feat: Wire immediates into pipelines and passes

[reczkok]

Stacked on #3031.

pipeline.with(immediate, value) and pass.setImmediates(immediate, value), following the #2987 precedence (pass > pipeline > default). Values are snapshotted once and rewritten only when changed. Feature detection via root.enabledWgslLanguageFeatures.

~980 lines, ~570 of them tests.

[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@3a0415621bdb62259ebaf23e360125c358a0c5ca

https://pkg.pr.new/software-mansion/TypeGPU/tinyest@3a0415621bdb62259ebaf23e360125c358a0c5ca

https://pkg.pr.new/software-mansion/TypeGPU/tinyest-for-wgsl@3a0415621bdb62259ebaf23e360125c358a0c5ca

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@3a0415621bdb62259ebaf23e360125c358a0c5ca

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/gl@3a0415621bdb62259ebaf23e360125c358a0c5ca

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@3a0415621bdb62259ebaf23e360125c358a0c5ca

benchmark
view benchmark

commit
view commit

[github-actions]

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

🟢 Decreased	➖ Unchanged	🔴 Increased (max 1.47%)	❔ Unknown
0	39	286	0

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

Test	tsdown
STATIC_tgpu.ts	279.10 kB ($${\color{red}+1.5\%}$$)
STATIC_allImports.ts	305.16 kB ($${\color{red}+1.3\%}$$)
tgpu_initFromDevice.ts	268.47 kB ($${\color{red}+1.3\%}$$)
tgpu_init.ts	269.02 kB ($${\color{red}+1.3\%}$$)
d_ref.ts	5.03 kB ($${\color{red}+0.9\%}$$)

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

[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.74, 1.44, 3.21, 4.30, 4.96, 8.91, 16.12, 18.12]
  line [0.67, 1.36, 3.00, 4.33, 5.34, 8.07, 16.41, 14.74]
  line [0.70, 1.32, 3.00, 4.28, 5.35, 7.34, 16.44, 18.40]

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.20, 0.39, 0.53, 0.65, 0.86, 0.85, 1.11, 1.19]
  line [0.20, 0.38, 0.53, 0.64, 0.82, 0.88, 1.04, 1.07]
  line [0.26, 0.42, 0.55, 0.63, 0.86, 0.84, 1.01, 1.12]

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.83, 1.69, 2.73, 5.08, 9.01, 19.46, 38.98, 78.11]
  line [0.61, 1.81, 2.82, 5.12, 8.52, 19.05, 37.95, 79.55]
  line [0.62, 1.72, 3.86, 6.23, 9.46, 19.08, 38.93, 79.81]

Loading

[Copilot]

🟡 Changes recommended

Unresolved critical and moderate issues affect WGSL validity, SSR safety, serialization snapshots, and immediate-size validation.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds immediate-variable bindings to pipelines, passes, and render bundles with pass > pipeline > default precedence, snapshotting, serialization, feature detection, tests, and documentation.

Changes:

• Adds pipeline and pass immediate-value APIs.
• Implements snapshots, defaults, deduplication, restoration, and validation.
• Expands WebGPU mocks, tests, and pipeline documentation.

File summaries

File	Summary
packages/typegpu/tests/serial.test.ts	Serialization coverage.
packages/typegpu/tests/immediates.test.ts	Immediate behavior tests.
packages/typegpu/src/serial/restore.ts	Immediate resource restoration.
packages/typegpu/src/indexNamedExports.ts	Public error export.
packages/typegpu/src/errors.ts	Missing-immediate error.
packages/typegpu/src/core/root/rootTypes.ts	Feature-detection API.
packages/typegpu/src/core/root/init.ts	WGSL feature detection. Critical (3 votes): unguarded navigator access can throw in Node/SSR.
packages/typegpu/src/core/pipeline/renderPipeline.ts	Render pipeline bindings.
packages/typegpu/src/core/pipeline/priors.ts	Transferable immediate state.
packages/typegpu/src/core/pipeline/drawState.ts	Immediate state application and precedence.
packages/typegpu/src/core/pipeline/computePipeline.ts	Compute pipeline bindings.
packages/typegpu/src/core/immediate/immediateVar.ts	Immediate snapshots, defaults, and validation. Critical (1 vote): missing immediate_address_space WGSL enable directive. Moderate (3 votes): mutable default references are not snapshotted for serialization. Moderate (1 vote): non-4-byte immediate sizes are not rejected early.
packages/typegpu/src/core/commandEncoder/renderPass.ts	Render pass and bundle API.
packages/typegpu/src/core/commandEncoder/computePass.ts	Compute pass API.
packages/typegpu-testing-utility/src/extendedIt.ts	WebGPU mocks.
apps/typegpu-docs/src/content/docs/apis/pipelines.mdx	Immediate usage documentation.

Review details

Suppressed comments (1)

packages/typegpu/src/core/immediate/immediateVar.ts:112

• sizeOf can be 2 or 6 for otherwise accepted schemas such as d.f16 or d.vec3h, but the documented immediate range must be a multiple of 4 bytes. Passing those sizes directly to createPipelineLayout makes a valid immediateVar fail later with a WebGPU validation error; reject non-4-byte sizes here (and report the schema/name) before pipeline creation.

  return sizeOf(immediate.dataType);

• Files reviewed: 16/16 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[pullfrog]

ℹ️ No critical issues — two minor points inline.

Reviewed changes

• Pipeline-level immediates — pipeline.with(immediate, value) snapshots the value into per-pipeline priors, and the pipeline core now resolves immediateSize for device.createPipelineLayout.
• Pass-level immediates — setImmediates on render/compute passes and render bundle encoders, with pass > pipeline > default precedence and persistence across pipeline switches.
• Snapshot & dedup engine — ImmediatePassState captures values and skips redundant setImmediates calls; executeBundles invalidates the cache so state is re-applied.
• Feature detection & validation — root.enabledWgslLanguageFeatures plus validateImmediateUsage gate usage on the immediate_address_space extension.
• Defaults & serialization — immediateVar(schema, default) plus soul/pipeline round-trip support for immediate resources and held values.
• Tests & docs — ~570 lines of immediates coverage, a serial round-trip test, updated WebGPU mocks, and a new docs section.

One clarification, since an earlier review flagged it: immediate_address_space is a WGSL language extension (spec §4.1.2), which is automatically available when the implementation supports it — unlike f16/subgroups it does not require an enable immediate_address_space; directive. The wgslLanguageFeatures.has(...) gate is the correct contract here.

The dedup optimization checks out against the spec: setPipeline does not reset immediate data, and executeBundles is the only mid-pass reset — which invalidate() correctly handles.

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

[cieplypolar]

idk if this is relevant, but functions in dataIO.ts (calculateOffsets and writeToArrayBuffer) with similar signatures do not include ArrayBufferView in their union types. Maybe add it there as well for consistency.