feat: Transfer protocol for TypeGPU resources (on souls)

[reczkok]

Replaces #2732, rebuilt on top of #2796. With souls in place the protocol got much simpler: a snapshot is just a structured copy of the resource's soul

• transferred pipelines arrive precompiled and are never resolved again, so definitions (tgpu.fn, entry functions, tgpu.comptime) stay runtime-local
• pipelines carrying attachments or a bound pass/encoder throw on transfer (those hold views and encoders local to their runtime)
• data schemas travel as descriptions of themselves - every schema is callable and host serializers claim functions before asking whether a value is transferable, so there's no way to hand them the schema directly
• transfer cache keeps identity: sending the same resource twice yields the same object back

[github-actions]

pkg.pr.new

packages
Ready to be installed by your favorite package manager ⬇️

https://pkg.pr.new/software-mansion/TypeGPU/eslint-plugin-typegpu@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/tgpu-gen@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/tinyest-for-wgsl@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/cli@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/color@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/gl@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/noise@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/radiance-cascades@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/react@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/sdf@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/three@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@4ab25cb25e7d23f9e9931ee4bbf1468db23be343

benchmark
view benchmark

commit
view commit

[github-actions]

Resolution Time Benchmark

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Random Branching (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.90, 1.86, 3.97, 6.06, 7.12, 11.95, 21.98, 23.34]
  line [0.87, 1.93, 3.86, 5.60, 6.61, 11.70, 21.59, 25.48]
  line [0.90, 1.82, 4.44, 6.12, 6.90, 11.63, 22.04, 22.72]

Loading

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Linear Recursion (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.32, 0.49, 0.67, 0.78, 1.11, 1.13, 1.42, 1.61]
  line [0.32, 0.52, 0.70, 0.85, 1.12, 1.16, 1.44, 1.53]
  line [0.28, 0.54, 0.67, 0.89, 1.23, 1.27, 1.43, 1.60]

Loading

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#E63946, #3B82F6, #059669"
---
xychart
  title "Full Tree (🔴 PR | 🔵 main | 🟢 release)"
  x-axis "max depth" [1, 2, 3, 4, 5, 6, 7, 8]
  y-axis "time (ms)"
  line [0.80, 2.13, 3.38, 7.24, 12.52, 24.78, 53.22, 110.00]
  line [0.69, 2.19, 4.32, 6.64, 12.64, 24.38, 53.16, 107.51]
  line [0.81, 1.99, 4.22, 6.28, 12.50, 25.61, 54.53, 113.18]

Loading

[github-actions]

Bundle size comparison (import * as ... in PR vs import * as ... in target):

🟢 Decreased	➖ Unchanged	🔴 Increased (max 6.16%)	❔ Unknown
0	2	320	1

import * as ... in PR vs import * as ... in target (did bundle size increase?):

Click to reveal the results table (119 entries).

Test	tsdown
d_unstruct.ts	1.65 kB ($${\color{red}+6.2\%}$$)
d_Void.ts	759 B ($${\color{red}+4.0\%}$$)
d_sampler.ts	767 B ($${\color{red}+3.9\%}$$)
d_isPtr.ts	777 B ($${\color{red}+3.9\%}$$)
d_comparisonSampler.ts	778 B ($${\color{red}+3.9\%}$$)
d_isSizeAttrib.ts	779 B ($${\color{red}+3.9\%}$$)
d_isWgslArray.ts	779 B ($${\color{red}+3.9\%}$$)
d_isAlignAttrib.ts	780 B ($${\color{red}+3.9\%}$$)
d_isAtomic.ts	780 B ($${\color{red}+3.9\%}$$)
d_isWgslStruct.ts	780 B ($${\color{red}+3.9\%}$$)
d_isBuiltinAttrib.ts	782 B ($${\color{red}+3.9\%}$$)
d_isDecorated.ts	783 B ($${\color{red}+3.8\%}$$)
d_isLocationAttrib.ts	783 B ($${\color{red}+3.8\%}$$)
d_isInterpolateAttrib.ts	786 B ($${\color{red}+3.8\%}$$)
d_atomic.ts	804 B ($${\color{red}+3.7\%}$$)
d_ptrHandle.ts	876 B ($${\color{red}+3.4\%}$$)
d_ptrUniform.ts	877 B ($${\color{red}+3.4\%}$$)
d_ptrStorage.ts	881 B ($${\color{red}+3.4\%}$$)
d_ptrPrivate.ts	883 B ($${\color{red}+3.4\%}$$)
d_ptrFn.ts	884 B ($${\color{red}+3.4\%}$$)
d_ptrWorkgroup.ts	885 B ($${\color{red}+3.4\%}$$)
d_textureExternal.ts	898 B ($${\color{red}+3.3\%}$$)
d_textureStorage1d.ts	1.04 kB ($${\color{red}+2.8\%}$$)
d_textureStorage2d.ts	1.04 kB ($${\color{red}+2.8\%}$$)
d_textureStorage3d.ts	1.04 kB ($${\color{red}+2.8\%}$$)
d_textureStorage2dArray.ts	1.05 kB ($${\color{red}+2.8\%}$$)
d_struct.ts	3.71 kB ($${\color{red}+2.7\%}$$)
d_isDisarray.ts	1.14 kB ($${\color{red}+2.6\%}$$)
d_isUnstruct.ts	1.14 kB ($${\color{red}+2.6\%}$$)
d_isLooseDecorated.ts	1.14 kB ($${\color{red}+2.5\%}$$)
d_isLooseData.ts	1.18 kB ($${\color{red}+2.5\%}$$)
d_isWgslData.ts	1.33 kB ($${\color{red}+2.2\%}$$)
d_ref.ts	4.99 kB ($${\color{red}+2.0\%}$$)
d_isData.ts	1.83 kB ($${\color{red}+1.6\%}$$)
STATIC_tgpu.ts	276.85 kB ($${\color{red}+1.3\%}$$)
tgpu_fn.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_init.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_lazy.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_slot.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_const.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_unroll.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_resolve.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_accessor.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_comptime.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_vertexFn.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_computeFn.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_fragmentFn.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_privateVar.ts	276.86 kB ($${\color{red}+1.3\%}$$)
tgpu_vertexLayout.ts	276.87 kB ($${\color{red}+1.3\%}$$)
tgpu_workgroupVar.ts	276.87 kB ($${\color{red}+1.3\%}$$)
tgpu_initFromDevice.ts	276.87 kB ($${\color{red}+1.3\%}$$)
tgpu_bindGroupLayout.ts	276.87 kB ($${\color{red}+1.3\%}$$)
tgpu_mutableAccessor.ts	276.87 kB ($${\color{red}+1.3\%}$$)
tgpu_resolveWithContext.ts	276.87 kB ($${\color{red}+1.3\%}$$)
d_deepEqual.ts	2.22 kB ($${\color{red}+1.3\%}$$)
STATIC_allImports.ts	302.69 kB ($${\color{red}+1.2\%}$$)
d_bool.ts	13.89 kB ($${\color{red}+0.7\%}$$)
d_f16.ts	13.89 kB ($${\color{red}+0.7\%}$$)
d_f32.ts	13.89 kB ($${\color{red}+0.7\%}$$)
d_i32.ts	13.89 kB ($${\color{red}+0.7\%}$$)
d_u32.ts	13.89 kB ($${\color{red}+0.7\%}$$)
d_u16.ts	13.91 kB ($${\color{red}+0.7\%}$$)
d_textureDepth2d.ts	14.33 kB ($${\color{red}+0.7\%}$$)
d_textureDepthCube.ts	14.34 kB ($${\color{red}+0.7\%}$$)
d_texture1d.ts	14.34 kB ($${\color{red}+0.7\%}$$)
d_texture2d.ts	14.34 kB ($${\color{red}+0.7\%}$$)
d_texture3d.ts	14.34 kB ($${\color{red}+0.7\%}$$)
d_textureCube.ts	14.35 kB ($${\color{red}+0.7\%}$$)
d_textureDepth2dArray.ts	14.35 kB ($${\color{red}+0.7\%}$$)
d_textureDepthCubeArray.ts	14.36 kB ($${\color{red}+0.7\%}$$)
d_textureDepthMultisampled2d.ts	14.36 kB ($${\color{red}+0.7\%}$$)
d_texture2dArray.ts	14.36 kB ($${\color{red}+0.7\%}$$)
d_textureCubeArray.ts	14.37 kB ($${\color{red}+0.7\%}$$)
d_textureMultisampled2d.ts	14.37 kB ($${\color{red}+0.7\%}$$)
std_discard.ts	15.18 kB ($${\color{red}+0.7\%}$$)
std_isBeingTranspiled.ts	15.28 kB ($${\color{red}+0.7\%}$$)
std_getTargetShaderLanguage.ts	15.34 kB ($${\color{red}+0.7\%}$$)
std_extensionEnabled.ts	15.40 kB ($${\color{red}+0.7\%}$$)
std_copy.ts	15.42 kB ($${\color{red}+0.7\%}$$)
std_arrayLength.ts	15.43 kB ($${\color{red}+0.6\%}$$)
std_range.ts	15.66 kB ($${\color{red}+0.6\%}$$)
d_disarrayOf.ts	15.83 kB ($${\color{red}+0.6\%}$$)
std_dpdx.ts	16.14 kB ($${\color{red}+0.6\%}$$)
std_dpdxCoarse.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_dpdxFine.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_dpdy.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_dpdyCoarse.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_dpdyFine.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_fwidth.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_fwidthCoarse.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_fwidthFine.ts	16.15 kB ($${\color{red}+0.6\%}$$)
std_atomicLoad.ts	16.94 kB ($${\color{red}+0.6\%}$$)
std_atomicStore.ts	16.95 kB ($${\color{red}+0.6\%}$$)
std_textureBarrier.ts	16.95 kB ($${\color{red}+0.6\%}$$)
std_atomicAdd.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicAnd.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicMax.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicMin.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicOr.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicSub.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_atomicXor.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_storageBarrier.ts	16.96 kB ($${\color{red}+0.6\%}$$)
std_workgroupBarrier.ts	16.96 kB ($${\color{red}+0.6\%}$$)
d_vec2b.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec2f.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec2h.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec2i.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec2u.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec3b.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec3f.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec3h.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec3i.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec3u.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec4b.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec4f.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec4h.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec4i.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_vec4u.ts	20.34 kB ($${\color{red}+0.5\%}$$)
d_isInvariantAttrib.ts	784 B

import { ... } in PR vs import * as ... in PR (is the library tree-Shakeable?):

Test	tsdown
tgpu_init.ts	267.77 kB ($${\color{green}-3.3\%}$$)
tgpu_initFromDevice.ts	267.22 kB ($${\color{green}-3.5\%}$$)
tgpu_resolve.ts	168.34 kB ($${\color{green}-39.2\%}$$)
tgpu_resolveWithContext.ts	168.27 kB ($${\color{green}-39.2\%}$$)
tgpu_bindGroupLayout.ts	73.79 kB ($${\color{green}-73.4\%}$$)
tgpu_mutableAccessor.ts	68.51 kB ($${\color{green}-75.3\%}$$)
tgpu_accessor.ts	68.51 kB ($${\color{green}-75.3\%}$$)
tgpu_privateVar.ts	67.07 kB ($${\color{green}-75.8\%}$$)
tgpu_workgroupVar.ts	67.07 kB ($${\color{green}-75.8\%}$$)
tgpu_const.ts	66.62 kB ($${\color{green}-75.9\%}$$)
tgpu_lazy.ts	66.42 kB ($${\color{green}-76.0\%}$$)
tgpu_fragmentFn.ts	38.92 kB ($${\color{green}-85.9\%}$$)
tgpu_fn.ts	38.86 kB ($${\color{green}-86.0\%}$$)
tgpu_vertexFn.ts	38.73 kB ($${\color{green}-86.0\%}$$)
tgpu_computeFn.ts	38.44 kB ($${\color{green}-86.1\%}$$)
tgpu_vertexLayout.ts	27.57 kB ($${\color{green}-90.0\%}$$)
tgpu_comptime.ts	15.17 kB ($${\color{green}-94.5\%}$$)
tgpu_unroll.ts	1.75 kB ($${\color{green}-99.4\%}$$)
tgpu_slot.ts	1.70 kB ($${\color{green}-99.4\%}$$)

If you wish to run a comparison for other, slower bundlers, run the 'Tree-shake test' from the GitHub Actions menu.

[pullfrog]

This is a solid, well-tested addition of the cross-runtime transfer protocol. The snapshot/restore split is clean, the tests cover all the major resource kinds, and the JSI-specific type guards are a nice touch for React Native.

I have a few small suggestions around TgpuBindGroupImpl / bind-group restoration that are worth double-checking before merge, but nothing that blocks the overall approach. The relevant unit tests (serial, serializeDataSchema, computePipeline, renderPipeline, internal/typeGuards, root) all pass locally.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

This as GPUDevice hides the fact that device can be undefined when the bind group is created rootlessly via tgpu.resolve(). TgpuDeviceOwningSoul requires device: GPUDevice, so the type system will treat this as a real device even when it isn't. Consider making device optional in the soul type for rootless resources, or using a separate soul shape, so the runtime value matches the type.

[pullfrog]

Skipping the missing-entry check when raw is provided makes sense for restored/materialized bind groups, but it means the constructor now allows bind groups with incomplete entries as long as a raw GPUBindGroup is passed. Since TgpuBindGroupImpl is exported, this is a bit of a footgun. Could you add a clarifying comment that this path is only for restoration, or consider validating anyway when raw comes from an untrusted source?

[Copilot]

Pull request overview

Implements a snapshot/restore (“transfer”) protocol for TypeGPU resources built on top of souls, enabling React Native worklet runtimes to receive precompiled pipelines and resource wrappers while keeping runtime-local definitions (functions/comptime) non-transferable.

Changes:

• Add core serialization infrastructure: resource snapshotting/restoration, data-schema serialization, and vec/mat value snapshots.
• Enable restoration of precompiled compute/render pipelines (no re-resolution) and broaden public type guards/exports to support transfer use-cases.
• Integrate React Native worklets support in @typegpu/react (UI-thread useFrame, automatic custom-serializable registration, identity cache) plus docs/tests.

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Dependency graph updates (RN worklets/metro/babel).
packages/typegpu/tests/serializeDataSchema.test.ts	Tests for schema serialization + round-trip.
packages/typegpu/tests/serial.test.ts	End-to-end resource snapshot/restore tests.
packages/typegpu/tests/root.test.ts	Verifies optionalFeatures handling during init.
packages/typegpu/tests/renderPipeline.test.ts	Tests restoring raw render pipelines + bind groups.
packages/typegpu/tests/internal/typeGuards.test.ts	Tests JSI-hostobject-safe pipeline type guards.
packages/typegpu/tests/computePipeline.test.ts	Tests restoring raw compute pipelines + bind groups.
packages/typegpu/src/tgpuBindGroupLayout.ts	Bind-group souls/restoration + materialization changes.
packages/typegpu/src/std/bitcast.ts	Import correction for getName.
packages/typegpu/src/serial/types.ts	Introduces RestoreContext interface.
packages/typegpu/src/serial/schema.ts	Serialize/deserialize data schemas.
packages/typegpu/src/serial/restore.ts	Central soul→resource restoration registry.
packages/typegpu/src/serial/registry.ts	Snapshot/restore entrypoints + schema tagging.
packages/typegpu/src/serial/dataValue.ts	Snapshot/restore vec/mat instances via bytes.
packages/typegpu/src/resolutionCtx.ts	Catchall bind-group creation updated for new ctor.
packages/typegpu/src/internal.ts	Re-export serialization APIs for ~internal.
packages/typegpu/src/indexNamedExports.ts	Export new guards/types (bind groups, pipelines, etc.).
packages/typegpu/src/data/index.ts	Export invariant helpers/types.
packages/typegpu/src/core/texture/texture.ts	Allow wrapping existing GPUTexture; avoid double-destroy.
packages/typegpu/src/core/root/init.ts	Init optionalFeatures handling + bind-group creation update.
packages/typegpu/src/core/pipeline/renderPipeline.ts	Precompiled render pipeline restoration support.
packages/typegpu/src/core/pipeline/pipelineUtils.ts	Helpers to collect priors + restore timestamps.
packages/typegpu/src/core/pipeline/computePipeline.ts	Precompiled compute pipeline restoration support.
packages/typegpu/src/core/buffer/buffer.ts	Helper to reapply buffer usages on restore.
packages/typegpu-react/tsdown.config.ts	Bundler plugin to preserve optional require() for Metro.
packages/typegpu-react/tests/root-context.test.tsx	Ensures Root options flow into init.
packages/typegpu-react/tests/react-native/use-frame.test.tsx	Tests UI-vs-RN thread useFrame behavior.
packages/typegpu-react/tests/react-native/register-serializables.test.ts	Tests RN custom-serializable registration + transfer.
packages/typegpu-react/src/react-native/worklets-integration.ts	Optional runtime detection of react-native-worklets.
packages/typegpu-react/src/react-native/use-frame.ts	UI-runtime frame loop for worklet callbacks.
packages/typegpu-react/src/react-native/use-configure-worklet-context.ts	Shareable canvas context ref for UI runtime.
packages/typegpu-react/src/react-native/serialization/transfer-cache.ts	Identity cache for transferred resources/roots.
packages/typegpu-react/src/react-native/serialization/register-serializables.ts	Custom serializer pack/unpack using snapshot protocol.
packages/typegpu-react/src/react-native/index.ts	RN entry: install WebGPU + register serializables + export hooks.
packages/typegpu-react/src/core/use-frame.ts	Extract shared startFrameLoop helper + export FrameCtx.
packages/typegpu-react/src/core/root-context.tsx	Add init options passthrough + disableWorklets flag/context.
packages/typegpu-react/README.md	Document RN worklets support.
packages/typegpu-react/package.json	Add RN export conditions + optional worklets peer.
apps/typegpu-docs/src/content/docs/integration/react-native/worklets.mdx	New RN Worklets guide.
apps/typegpu-docs/astro.config.mjs	Add docs sidebar entry for worklets guide.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pullfrog]

ℹ️ No new issues found in the latest push.

Reviewed changes

The latest force-push is a small cleanup delta:

• Moved the root-class JSDoc comment in packages/typegpu/src/core/root/init.ts onto TgpuRootImpl.
• Updated packages/typegpu/src/shared/soul.ts and packages/typegpu/src/shared/symbols.ts docstrings to describe souls as surviving transfer between runtimes.
• Wired resource names into souls in packages/typegpu/src/shared/meta.ts: getName now falls back to soul.label, and setName writes the name into the soul so labels survive cross-runtime transfer.

The relevant unit tests still pass.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}