feat: Souls

[reczkok]

Groundwork for the transfer protocol (PR on top of this one). To move a resource between runtimes we need its complete definitional state as a plain serializable record, and previously that state was scattered across private fields, closures and getters per resource. This PR gathers it into one place without changing any behavior.

• every resource now carries a [$soul] - a plain record of everything that survives a device boundary (own data properties only, no methods, no prototype, no symbol keys)
• [$internal] changed from true to an object exposing materialize(), which fills the soul's raw with the device object for resources that own one (buffer, texture, query set, pipelines, ...)
• resource impls read their state through the soul instead of private fields, so the soul is the single source of truth rather than a copy that could drift

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[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@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/tgpu-gen@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/tinyest-for-wgsl@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/cli@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/color@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/gl@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/noise@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/radiance-cascades@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/react@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/sdf@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/three@5da406816c068003015cdb150856769d97d5f30f

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@5da406816c068003015cdb150856769d97d5f30f

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.95, 1.90, 4.09, 6.14, 6.77, 11.48, 21.18, 22.33]
  line [0.88, 1.79, 3.81, 6.07, 7.14, 11.48, 21.45, 22.61]
  line [0.95, 1.92, 4.15, 6.31, 7.11, 10.61, 20.70, 22.32]

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.25, 0.47, 0.63, 0.76, 1.07, 1.10, 1.37, 1.53]
  line [0.34, 0.47, 0.65, 0.86, 1.08, 1.16, 1.29, 1.44]
  line [0.32, 0.54, 0.74, 0.87, 1.15, 1.21, 1.42, 1.59]

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.77, 1.99, 4.09, 7.49, 12.78, 24.45, 51.62, 104.21]
  line [0.76, 2.07, 3.70, 6.60, 12.69, 24.49, 51.42, 105.14]
  line [0.83, 2.15, 4.43, 7.18, 12.65, 26.09, 54.47, 111.06]

Loading

[github-actions]

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

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

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

Click to reveal the results table (56 entries).

Test	tsdown
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_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_unstruct.ts	1.58 kB ($${\color{red}+1.8\%}$$)
d_isData.ts	1.83 kB ($${\color{red}+1.6\%}$$)
d_deepEqual.ts	2.22 kB ($${\color{red}+1.3\%}$$)
STATIC_tgpu.ts	275.78 kB ($${\color{red}+1.1\%}$$)
tgpu_fn.ts	275.78 kB ($${\color{red}+1.1\%}$$)
tgpu_init.ts	275.78 kB ($${\color{red}+1.1\%}$$)
tgpu_lazy.ts	275.78 kB ($${\color{red}+1.1\%}$$)
tgpu_slot.ts	275.78 kB ($${\color{red}+1.1\%}$$)
tgpu_const.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_unroll.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_resolve.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_accessor.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_comptime.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_vertexFn.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_computeFn.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_fragmentFn.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_privateVar.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_vertexLayout.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_workgroupVar.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_initFromDevice.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_bindGroupLayout.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_mutableAccessor.ts	275.79 kB ($${\color{red}+1.1\%}$$)
tgpu_resolveWithContext.ts	275.80 kB ($${\color{red}+1.1\%}$$)
STATIC_allImports.ts	301.55 kB ($${\color{red}+1.0\%}$$)
d_struct.ts	3.64 kB ($${\color{red}+0.8\%}$$)
d_ref.ts	4.92 kB ($${\color{red}+0.6\%}$$)

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

Test	tsdown
tgpu_init.ts	266.69 kB ($${\color{green}-3.3\%}$$)
tgpu_initFromDevice.ts	266.16 kB ($${\color{green}-3.5\%}$$)
tgpu_resolve.ts	167.70 kB ($${\color{green}-39.2\%}$$)
tgpu_resolveWithContext.ts	167.63 kB ($${\color{green}-39.2\%}$$)
tgpu_bindGroupLayout.ts	73.57 kB ($${\color{green}-73.3\%}$$)
tgpu_mutableAccessor.ts	68.30 kB ($${\color{green}-75.2\%}$$)
tgpu_accessor.ts	68.29 kB ($${\color{green}-75.2\%}$$)
tgpu_privateVar.ts	66.85 kB ($${\color{green}-75.8\%}$$)
tgpu_workgroupVar.ts	66.85 kB ($${\color{green}-75.8\%}$$)
tgpu_const.ts	66.40 kB ($${\color{green}-75.9\%}$$)
tgpu_lazy.ts	66.21 kB ($${\color{green}-76.0\%}$$)
tgpu_fragmentFn.ts	38.72 kB ($${\color{green}-86.0\%}$$)
tgpu_fn.ts	38.65 kB ($${\color{green}-86.0\%}$$)
tgpu_vertexFn.ts	38.53 kB ($${\color{green}-86.0\%}$$)
tgpu_computeFn.ts	38.24 kB ($${\color{green}-86.1\%}$$)
tgpu_vertexLayout.ts	27.36 kB ($${\color{green}-90.1\%}$$)
tgpu_comptime.ts	14.97 kB ($${\color{green}-94.6\%}$$)
tgpu_unroll.ts	1.68 kB ($${\color{green}-99.4\%}$$)
tgpu_slot.ts	1.63 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.