pngine 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,32 +1,36 @@
1
- ; PNGine WebGPU schema — Phase 1 vertical slice.
1
+ ; PNGine WebGPU schema.
2
2
  ;
3
3
  ; Single source of truth for what a PNGine `.sjon` document may contain. The
4
- ; compiler (`src/dsl_sjon/Compiler.zig`) prepends this manifest to the user
5
- ; source and runs `Host.validateDocument`, so the data forms below are validated
4
+ ; compiler (`src/dsl_sjon/Compiler.zig`) preloads this manifest once
5
+ ; (`sjon.preloadSchema`) and hands it to every `Host.validateDocument`, so
6
+ ; the user document parses at offset 0 and the data forms below are validated
6
7
  ; against this plugin with no filesystem (works on wasm32-freestanding). It is
7
8
  ; `@embedFile`'d via the `pngine_schema` build import and feeds the web editor's
8
9
  ; TS / JSON-Schema export.
9
10
  ;
10
- ; Phase 1 covered the minimal core (define, shader-module, data-float32, buffer,
11
- ; queue, bind-group, render/compute pipeline + pass, frame, `init` sugar via the
12
- ; `pngine/init-v1` hook). Phase 2a adds shape generators (cube…dragon), textures
13
- ; (depth subset), depth/stencil pipeline state, and indexed draws. Samplers,
14
- ; imageBitmap, MRT/blend/MSAA and `#pass` land in later Phase 2 sub-waves.
11
+ ; It grew in phases (the core forms first, then shapes, textures, depth/stencil
12
+ ; and indexed draws, then samplers, imageBitmap, MRT/blend/MSAA, queries, copies
13
+ ; and `(pass …)`); every one of those is here now, and 3.0.0 re-shaped the
14
+ ; whole file against the WebGPU IDL.
15
15
  ;
16
- ; ---- Defaults policy (F6) — three DISTINCT notions, never conflated ----
16
+ ; ---- Defaults policy — three DISTINCT notions, never conflated ----
17
17
  ; 1. Schema `:default V` is a PNGine OPINION. On key absence SJON materializes V
18
18
  ; into the effective view (→ HostResult.materialized_defaults), so the emitter
19
19
  ; always bakes a concrete value into the bytecode. Use it where PNGine commits
20
- ; to a value even when WebGPU has none — e.g. `load-op :default clear` (WebGPU
21
- ; REQUIRES loadOp; there is no spec default, so the opinion must ship).
20
+ ; to a value even when WebGPU has none. Note this is NOT a licence to default
21
+ ; a REQUIRED member: `load-op` used to be the example here, and it was the
22
+ ; wrong one — WebGPU requires loadOp precisely so the author states it, and
23
+ ; 3.0.0 made it required here too.
22
24
  ; 2. A key with NO `:default`, left absent, defers to WebGPU's OWN spec default at
23
25
  ; runtime — the emitter writes nothing and PNGine invents nothing.
24
26
  ; 3. js_codegen's omit-when-default (`--html`) is a SIZE ENCODING, not a semantic
25
27
  ; source: it may drop a descriptor field ONLY when the emitted value equals
26
28
  ; WebGPU's spec default (e.g. a buffer-binding offset 0 / size = rest-of-buffer),
27
29
  ; leaning on WebGPU to refill it identically. A materialized OPINION that differs
28
- ; from the WebGPU default (loadOp/storeOp/clearValue) is NEVER omitted.
29
- ; Full rationale + the invariant a new `:default` must satisfy: CONTRIBUTING §19.
30
+ ; from the WebGPU default (a pass-lowered sampler's `linear` filters, or an
31
+ ; authored `:default` on a key whose IDL default is something else) is
32
+ ; NEVER omitted. (loadOp/storeOp/clearValue used to be the example: they
33
+ ; are required / default-less since 3.0.0.)
30
34
  (plugin :name pngine :version "0.1.0"
31
35
 
32
36
  ; ---- numeric refinements ----
@@ -39,36 +43,166 @@
39
43
  ; silently wraps it, and SJON's exporter emits the branded `U32` TS alias so the
40
44
  ; editor gets real per-field GPU types. Repr checks literals only — expressions
41
45
  ; (`:size (* NUM 4 4)`) and define-refs are evaluated later, untouched here.
42
- (value-kind :name byte-count
46
+ ;
47
+ ; ---- the `x` / `x-value` pair ----
48
+ ; Every numeric kind here comes in two: `x-value` carries the bounds and the
49
+ ; repr, and `x` is `(scalar-or-ref-shape :base x-value :ref define-ref)` — a
50
+ ; literal, a bounded expression, or a bare `(define …)` name. KEYS NAME `x`.
51
+ ; The pair is `count` / `count-value`'s, applied to the rest: a number slot
52
+ ; is "literal | expression | checked reference" everywhere, because an author
53
+ ; who can write `:vertex-count NUM_PARTICLES` and not `:size NUM_PARTICLES`
54
+ ; is looking at an accident, not a rule.
55
+ ;
56
+ ; This could not be written until SJON's union reporting changed. A `scalar-or-ref`
57
+ ; desugars to a union, and a union that matched nothing used to report only
58
+ ; its ALTERNATIVE NAMES — so adding the reference arm would have retired every
59
+ ; bound below it: `:max-anisotropy 32` would have said "no alternative
60
+ ; matched: anisotropy-value | define-ref" where it used to name 1..16. SJON
61
+ ; reports the arm the value's SHAPE selected, so the bounds still speak. The
62
+ ; three inline tests in Compiler.zig are the ratchet.
63
+ ;
64
+ ; Two numeric slots have no `define-ref` arm, and neither is an oversight:
65
+ ; `write-mask` (its symbol arm is the closed member set `all`) and a
66
+ ; `(wasm-call :args […])` element (`wasm-arg`, whose symbol arm is the
67
+ ; builtin set `canvas-width` …). A third alternative would put a bare name
68
+ ; within reach of TWO arms, and SJON's rule declines to guess between them —
69
+ ; the slot would lose the report it just gained. A constant is written
70
+ ; `(* MASK 1)` / `(* SCALE 1)` there.
71
+ (value-kind :name byte-count-value
43
72
  :description "Non-negative integer byte size / offset / stride."
44
73
  :underlying number
45
74
  :numeric (numeric-bounds :min 0 :integer true)
46
75
  :unit (unit-shape :reject true)
47
76
  :repr (repr-shape :type u32))
48
- (value-kind :name pool-size
49
- :description "Ping-pong pool size (>= 1)."
77
+ (value-kind :name byte-count
78
+ :description "Byte size / offset / stride: a literal, a bounded expression, or a bare (define …) reference."
79
+ :underlying scalar-or-ref
80
+ :scalar-or-ref (scalar-or-ref-shape :base byte-count-value :ref define-ref))
81
+ ; WebGPU's alignment rules on byte offsets and sizes, as `:multiple-of`
82
+ ; bounds (SJON 1.2.0). Like every numeric-bounds, these judge a LITERAL; an
83
+ ; expression (`:offset (* N 4)`) is evaluated by the emitter, untouched here.
84
+ (value-kind :name byte-count-4-aligned-value
85
+ :description "Byte offset / size that WebGPU requires to be a multiple of 4."
50
86
  :underlying number
51
- :numeric (numeric-bounds :min 1 :integer true)
87
+ :numeric (numeric-bounds :min 0 :integer true :multiple-of 4)
52
88
  :unit (unit-shape :reject true)
53
89
  :repr (repr-shape :type u32))
54
- (value-kind :name binding-index
90
+ (value-kind :name byte-count-4-aligned
91
+ :description "A 4-aligned byte offset / size: a literal, a bounded expression, or a bare (define …) reference."
92
+ :underlying scalar-or-ref
93
+ :scalar-or-ref (scalar-or-ref-shape :base byte-count-4-aligned-value :ref define-ref))
94
+ (value-kind :name byte-count-256-aligned-value
95
+ :description "Byte offset that WebGPU requires to be a multiple of 256."
96
+ :underlying number
97
+ :numeric (numeric-bounds :min 0 :integer true :multiple-of 256)
98
+ :unit (unit-shape :reject true)
99
+ :repr (repr-shape :type u32))
100
+ (value-kind :name byte-count-256-aligned
101
+ :description "A 256-aligned byte offset: a literal, a bounded expression, or a bare (define …) reference."
102
+ :underlying scalar-or-ref
103
+ :scalar-or-ref (scalar-or-ref-shape :base byte-count-256-aligned-value :ref define-ref))
104
+ (value-kind :name pool-size-value
105
+ :description "Ping-pong pool size (1..255). The ceiling is the wire's: the
106
+ pool index is a byte everywhere it is encoded, so a larger pool
107
+ cannot be addressed. Bounds a LITERAL; the emitter re-checks the
108
+ expression spelling (`:pool (* 100 3)`), which repr cannot see."
109
+ :underlying number
110
+ :numeric (numeric-bounds :min 1 :max 255 :integer true)
111
+ :unit (unit-shape :reject true)
112
+ :repr (repr-shape :type u32))
113
+ (value-kind :name pool-size
114
+ :description "Ping-pong pool size: a literal, a bounded expression, or a bare (define …) reference."
115
+ :underlying scalar-or-ref
116
+ :scalar-or-ref (scalar-or-ref-shape :base pool-size-value :ref define-ref))
117
+ (value-kind :name binding-index-value
55
118
  :description "Non-negative binding / group / pool index. The PNGB wire stores these as u8, so 255 is the ceiling (WebGPU's own maxBindingsPerBindGroup default is 1000, but PNGine's uniform table and descriptor encoding are byte-indexed)."
56
119
  :underlying number
57
120
  :numeric (numeric-bounds :min 0 :max 255 :integer true)
58
121
  :unit (unit-shape :reject true)
59
122
  :repr (repr-shape :type u32))
123
+ (value-kind :name binding-index
124
+ :description "Binding / group / pool index: a literal, a bounded expression, or a bare (define …) reference."
125
+ :underlying scalar-or-ref
126
+ :scalar-or-ref (scalar-or-ref-shape :base binding-index-value :ref define-ref))
60
127
  (value-kind :name count-value
61
128
  :description "Non-negative integer draw / dispatch count (literals + expressions)."
62
129
  :underlying number
63
130
  :numeric (numeric-bounds :min 0 :integer true)
64
131
  :unit (unit-shape :reject true)
65
132
  :repr (repr-shape :type u32))
66
- ; A count may also be a bare `#define` reference (a symbol the emitter
67
- ; resolves through the expr env), e.g. `:instance-count NUM_PARTICLES`.
133
+ ; A count may also be a bare `(define …)` reference, e.g.
134
+ ; `:instance-count NUM_PARTICLES`. The reference half is a cross-ref to the
135
+ ; define form (SJON 1.2.0 `scalar-or-ref-shape :ref`), so a misspelt constant is
136
+ ; a located `union_no_branch_matched` at validation — it used to be an
137
+ ; unlocated "emit failed" from the emitter's env lookup. The emitter still
138
+ ; resolves the symbol through its expr env; the schema only guarantees the
139
+ ; name exists.
140
+ (value-kind :name define-ref
141
+ :description "Reference to a declared (define :name …) constant."
142
+ :underlying symbol
143
+ :cross-ref (cross-ref :target define))
144
+ ; The unbounded real: the element kind of every numeric vector (clear
145
+ ; colors, blend constants, float lists) and, since 3.0.0, the
146
+ ; `(define …)` value. No bounds to keep, but the unit reject stays — `:base
147
+ ; number` (the primitive shortcut) took `1f` and the reader used its
148
+ ; magnitude, one reading of the `1.0f` defect the scalar slots close.
149
+ ;
150
+ ; On `(define :value …)` the rule holds in full: a constant is a real, negative
151
+ ; and fractional allowed, and the SLOT that reads it decides integrality and
152
+ ; range at use — `0.5` is `:vertex-count`'s located reject and legal in
153
+ ; `:clear-value`. The reference arm lets a constant name another constant,
154
+ ; declared before or after it; the emitter resolves the set document-wide
155
+ ; and refuses a cycle with a span.
156
+ (value-kind :name real-value
157
+ :description "An unbounded real literal: negative and fractional allowed; a unit suffix is rejected."
158
+ :underlying number
159
+ :unit (unit-shape :reject true))
160
+ (value-kind :name real
161
+ :description "An unbounded real: a literal, a bounded expression, or a bare (define …) reference."
162
+ :underlying scalar-or-ref
163
+ :scalar-or-ref (scalar-or-ref-shape :base real-value :ref define-ref))
68
164
  (value-kind :name count
69
165
  :description "Draw / dispatch count: a literal, a bounded expression, or a bare (define …) reference."
70
- :underlying union
71
- :union (union-shape :alternatives [count-value symbol]))
166
+ :underlying scalar-or-ref
167
+ :scalar-or-ref (scalar-or-ref-shape :base count-value :ref define-ref))
168
+ ; ---- the domain names ----
169
+ ; `count` names a draw / dispatch count and `byte-count` names bytes; a slot
170
+ ; that is neither — a sample count, a query index or count, a stencil
171
+ ; reference or clear value, a pixel rect, a texel origin, a pool offset — is
172
+ ; the general `u32`, and a bitmask is `mask32` (hex literals read as the
173
+ ; number they spell: `0xFF` is 255, `pngine inspect` shows the decimal). Same
174
+ ; bounds and repr as `count`; the name says the domain, and the exported
175
+ ; `.d.ts` alias follows it.
176
+ (value-kind :name u32-value
177
+ :description "Non-negative integer that rides the wire as u32."
178
+ :underlying number
179
+ :numeric (numeric-bounds :min 0 :integer true)
180
+ :unit (unit-shape :reject true)
181
+ :repr (repr-shape :type u32))
182
+ (value-kind :name u32
183
+ :description "A non-negative integer: a literal, a bounded expression, or a bare (define …) reference."
184
+ :underlying scalar-or-ref
185
+ :scalar-or-ref (scalar-or-ref-shape :base u32-value :ref define-ref))
186
+ (value-kind :name query-count-value
187
+ :description "Number of queries in a (query-set …): an integer in [1, 4096] (GPUQuerySetDescriptor.count's createQuerySet bound)."
188
+ :underlying number
189
+ :numeric (numeric-bounds :min 1 :max 4096 :integer true)
190
+ :unit (unit-shape :reject true)
191
+ :repr (repr-shape :type u32))
192
+ (value-kind :name query-count
193
+ :description "Query-set size: a literal, a bounded expression, or a bare (define …) reference, at most 4096."
194
+ :underlying scalar-or-ref
195
+ :scalar-or-ref (scalar-or-ref-shape :base query-count-value :ref define-ref))
196
+ (value-kind :name mask32-value
197
+ :description "32-bit bitmask (0..0xFFFFFFFF); a hex literal reads as the number it spells."
198
+ :underlying number
199
+ :numeric (numeric-bounds :min 0 :integer true)
200
+ :unit (unit-shape :reject true)
201
+ :repr (repr-shape :type u32))
202
+ (value-kind :name mask32
203
+ :description "A 32-bit bitmask: a literal (hex welcome), a bounded expression, or a bare (define …) reference."
204
+ :underlying scalar-or-ref
205
+ :scalar-or-ref (scalar-or-ref-shape :base mask32-value :ref define-ref))
72
206
  ; A WebGPU device-limit value. Non-negative integer, u32-range in the schema
73
207
  ; (the PNGB wire carries u64 for forward-compat). Passed VERBATIM to
74
208
  ; requiredLimits at device creation — an unsatisfiable request fails loud there
@@ -79,53 +213,108 @@
79
213
  :numeric (numeric-bounds :min 0 :integer true)
80
214
  :unit (unit-shape :reject true)
81
215
  :repr (repr-shape :type u32))
82
- (value-kind :name unorm
83
- :description "Clear-color component in [0,1]."
216
+ (value-kind :name device-limit
217
+ :description "A WebGPU device limit: a literal, a bounded expression, or a bare (define …) reference."
218
+ :underlying scalar-or-ref
219
+ :scalar-or-ref (scalar-or-ref-shape :base device-limit-value :ref define-ref))
220
+ (value-kind :name unorm-value
221
+ :description "A float in [0,1] (the depth clear value)."
84
222
  :underlying number
85
223
  :numeric (numeric-bounds :min 0 :max 1)
86
224
  :unit (unit-shape :reject true)
87
225
  :repr (repr-shape :type f32))
226
+ (value-kind :name unorm
227
+ :description "A float in [0,1] (the depth clear value): a literal, a bounded expression, or a bare (define …) reference."
228
+ :underlying scalar-or-ref
229
+ :scalar-or-ref (scalar-or-ref-shape :base unorm-value :ref define-ref))
230
+ ; WebGPU's three bias terms are two different types, and conflating them cost
231
+ ; this schema a value: `GPUDepthBiasValue` is a `long` (signed 32-bit) while
232
+ ; `depthBiasSlopeScale` / `depthBiasClamp` are floats. One `f32`-repr kind for
233
+ ; all three let `:depth-bias -1` through the schema and into a u32 read, which
234
+ ; dropped it silently (webgpu_wireframe's wireframe pass layered over the solid
235
+ ; one by exactly that -1, and shipped without it).
236
+ (value-kind :name depth-bias-int-value
237
+ :description "Constant depth bias: a signed integer (GPUDepthBiasValue is a long)."
238
+ :underlying number
239
+ :numeric (numeric-bounds :integer true)
240
+ :unit (unit-shape :reject true)
241
+ :repr (repr-shape :type i32))
242
+ (value-kind :name depth-bias-int
243
+ :description "Constant depth bias: a literal, a bounded expression, or a bare (define …) reference."
244
+ :underlying scalar-or-ref
245
+ :scalar-or-ref (scalar-or-ref-shape :base depth-bias-int-value :ref define-ref))
88
246
  (value-kind :name depth-bias-value
89
- :description "Depth bias term: constant (int) or slope-scale / clamp (real)."
247
+ :description "Depth bias slope-scale / clamp: a real."
90
248
  :underlying number
91
249
  :unit (unit-shape :reject true)
92
250
  :repr (repr-shape :type f32))
93
- (value-kind :name lod-clamp
251
+ (value-kind :name depth-bias
252
+ :description "Depth bias slope-scale / clamp: a literal, a bounded expression, or a bare (define …) reference."
253
+ :underlying scalar-or-ref
254
+ :scalar-or-ref (scalar-or-ref-shape :base depth-bias-value :ref define-ref))
255
+ (value-kind :name lod-clamp-value
94
256
  :description "Sampler mip level-of-detail clamp (non-negative real; WebGPU defaults lodMinClamp 0, lodMaxClamp 32)."
95
257
  :underlying number
96
258
  :numeric (numeric-bounds :min 0)
97
259
  :unit (unit-shape :reject true)
98
260
  :repr (repr-shape :type f32))
261
+ (value-kind :name lod-clamp
262
+ :description "Sampler LOD clamp: a literal, a bounded expression, or a bare (define …) reference."
263
+ :underlying scalar-or-ref
264
+ :scalar-or-ref (scalar-or-ref-shape :base lod-clamp-value :ref define-ref))
99
265
  (value-kind :name anisotropy-value
100
266
  :description "Sampler max anisotropy (integer in [1,16]; values > 1 require linear mag/min/mipmap filters)."
101
267
  :underlying number
102
268
  :numeric (numeric-bounds :min 1 :max 16 :integer true)
103
269
  :unit (unit-shape :reject true)
104
270
  :repr (repr-shape :type u32))
271
+ (value-kind :name anisotropy
272
+ :description "Sampler max anisotropy: a literal, a bounded expression, or a bare (define …) reference."
273
+ :underlying scalar-or-ref
274
+ :scalar-or-ref (scalar-or-ref-shape :base anisotropy-value :ref define-ref))
275
+ ; Digit-leading spellings (`1d`, `2d-array`) lex as unit-bearing numbers; SJON
276
+ ; 1.2.0 lets a symbol member-set declare them and matches on the parsed
277
+ ; (magnitude, unit) pair, so the value reaches the emitter as a
278
+ ; `number_with_unit` node, not a symbol — read it with `Reader.memberSpelling`
279
+ ; and map through `values.textureDimensionCode` / `viewDimensionCode`
280
+ ; (`Emitter.dimensionCode`), never `Reader.symbol` (which returns null on it).
105
281
  (value-kind :name texture-dimension
106
- :description "GPUTextureDimension as an integer: 1 = 1d, 2 = 2d (default), 3 = 3d. (`1d`/`2d`/`3d` are not bare symbols in SJON — they lex as number+unit — so the count is authored numerically.)"
107
- :underlying number
108
- :numeric (numeric-bounds :min 1 :max 3 :integer true)
109
- :unit (unit-shape :reject true)
110
- :repr (repr-shape :type u32))
111
- (value-kind :name subresource-count
112
- :description "Positive integer texture subresource count (≥ 1) — mip levels or array/3d layers. Defaults to 1."
282
+ :description "GPUTextureDimension, spelled as the WebGPU spec spells it: 1d, 2d (default), 3d."
283
+ :underlying symbol
284
+ :members (member-set
285
+ (member :name 1d :description "One-dimensional texture.")
286
+ (member :name 2d :description "Two-dimensional texture (the default); with a third :size element > 1 it is a 2d array.")
287
+ (member :name 3d :description "Three-dimensional (volume) texture; the third :size element is its slice count.")))
288
+ (value-kind :name subresource-count-value
289
+ :description "Positive integer texture subresource count (≥ 1) — mip levels or array/3d layers. Absent: a texture allocates 1; a texture view exposes every level/layer from its base."
113
290
  :underlying number
114
291
  :numeric (numeric-bounds :min 1 :integer true)
115
292
  :unit (unit-shape :reject true)
116
293
  :repr (repr-shape :type u32))
117
- (value-kind :name subresource-index
294
+ (value-kind :name subresource-count
295
+ :description "Texture subresource count: a literal, a bounded expression, or a bare (define …) reference."
296
+ :underlying scalar-or-ref
297
+ :scalar-or-ref (scalar-or-ref-shape :base subresource-count-value :ref define-ref))
298
+ (value-kind :name subresource-index-value
118
299
  :description "Zero-based texture subresource index (≥ 0) — a texture view's base mip level or base array layer. Defaults to 0. (subresource-count is ≥ 1; a base index is ≥ 0.)"
119
300
  :underlying number
120
301
  :numeric (numeric-bounds :min 0 :integer true)
121
302
  :unit (unit-shape :reject true)
122
303
  :repr (repr-shape :type u32))
304
+ (value-kind :name subresource-index
305
+ :description "Texture subresource index: a literal, a bounded expression, or a bare (define …) reference."
306
+ :underlying scalar-or-ref
307
+ :scalar-or-ref (scalar-or-ref-shape :base subresource-index-value :ref define-ref))
123
308
  (value-kind :name view-dimension
124
- :description "GPUTextureViewDimension as an integer: 0 = 1d, 1 = 2d, 2 = 2d-array, 3 = cube, 4 = cube-array, 5 = 3d. (Authored numerically because `1d`/`2d`/`2d-array`/`3d` lex as number+unit in SJON, not symbols — keeping the whole enum numeric beats mixing symbolic `cube` with numeric `2d`.)"
125
- :underlying number
126
- :numeric (numeric-bounds :min 0 :max 5 :integer true)
127
- :unit (unit-shape :reject true)
128
- :repr (repr-shape :type u32))
309
+ :description "GPUTextureViewDimension, spelled as the WebGPU spec spells it: 1d, 2d, 2d-array, cube, cube-array, 3d."
310
+ :underlying symbol
311
+ :members (member-set
312
+ (member :name 1d :description "One-dimensional view (texture_1d).")
313
+ (member :name 2d :description "Two-dimensional view (texture_2d) — the default.")
314
+ (member :name 2d-array :description "Array of 2d layers (texture_2d_array).")
315
+ (member :name cube :description "Cube map — six 2d layers (texture_cube).")
316
+ (member :name cube-array :description "Array of cube maps — 6·N layers (texture_cube_array).")
317
+ (member :name 3d :description "Volume view (texture_3d).")))
129
318
  (value-kind :name texture-aspect
130
319
  :description "GPUTextureAspect — which aspect(s) of a depth/stencil texture a view exposes."
131
320
  :underlying symbol
@@ -155,10 +344,6 @@
155
344
  :description "Reference to a declared (compute-pipeline :name …)."
156
345
  :underlying symbol
157
346
  :cross-ref (cross-ref :target compute-pipeline))
158
- (value-kind :name wasm-call-ref
159
- :description "Reference to a declared (wasm-call :name …)."
160
- :underlying symbol
161
- :cross-ref (cross-ref :target wasm-call))
162
347
  (value-kind :name bind-group-ref
163
348
  :description "Reference to a declared (bind-group :name …)."
164
349
  :underlying symbol
@@ -171,20 +356,35 @@
171
356
  :description "Reference to a declared (queue :name …)."
172
357
  :underlying symbol
173
358
  :cross-ref (cross-ref :target queue))
174
- (value-kind :name render-pass-ref
175
- :description "Reference to a declared (render-pass :name …)."
176
- :underlying symbol
177
- :cross-ref (cross-ref :target render-pass))
178
359
  (value-kind :name compute-pass-ref
179
360
  :description "Reference to a declared (compute-pass :name …), including one lowered from (init …) sugar."
180
361
  :underlying symbol
181
362
  :cross-ref (cross-ref :target compute-pass))
182
- ; A bind-group's :layout-pipeline may target either pipeline kind; the union
183
- ; tries render first, then falls through to compute on cross-ref miss.
184
- (value-kind :name pipeline-ref
185
- :description "Reference to a declared render- or compute-pipeline."
186
- :underlying union
187
- :union (union-shape :alternatives [render-pipeline-ref compute-pipeline-ref]))
363
+ ; `pipeline-ref` = `(cross-ref :target [render-pipeline compute-pipeline])`
364
+ ; lived here until the descriptor cut. Its ONE consumer was the bind-group's
365
+ ; `:layout-pipeline`, and `bind-group-layout-spec` below is the same group
366
+ ; plus `bind-group-layout` — so the render/compute one-namespace property
367
+ ; that closed the shared-namespace hole is unchanged, and keeping both meant two buckets over
368
+ ; overlapping target sets reporting ONE collision twice.
369
+ ;
370
+ ; A bind group's `:layout` names the layout it is built against: a pipeline's
371
+ ; auto-derived layout, or an explicit (bind-group-layout …). One key, because
372
+ ; GPUBindGroupDescriptor.layout is one member — it was two mutually
373
+ ; exclusive keys and an exactly-one group.
374
+ ;
375
+ ; A TARGET GROUP (`:target [a b c]`), never a union of ref kinds. A union
376
+ ; resolves first-match while the emitter's tables are separate id spaces, so a
377
+ ; render-pipeline and a bind-group-layout sharing a name would resolve one way
378
+ ; here and bind the other downstream — the same hole, closed for `pipeline-ref`
379
+ ; and `frame-step` the same way on 2026-08-17. As a group the three forms are
380
+ ; ONE namespace: the collision is a `duplicate_cross_ref_target` at the second
381
+ ; declaration, so a reference here resolves to exactly one form by
382
+ ; construction, and the emitter's "did it resolve to a pipeline?" test is a
383
+ ; lookup in its own tables rather than a guess.
384
+ (value-kind :name bind-group-layout-spec
385
+ :description "The layout a bind group is built against: a render-/compute-pipeline whose auto-layout it targets, or an explicit (bind-group-layout …). One namespace across the three."
386
+ :underlying symbol
387
+ :cross-ref (cross-ref :target [render-pipeline compute-pipeline bind-group-layout]))
188
388
 
189
389
  ; ---- runtime builtin data sources (write-buffer :data) ----
190
390
  (value-kind :name builtin-data-source
@@ -192,18 +392,27 @@
192
392
  :underlying symbol
193
393
  :members (member-set
194
394
  (member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32).")
195
- (member :name scene-time-inputs :description "12 B: time, canvasWidth, canvasHeight (all f32) — the first 12 bytes of pngine-inputs. True scene timing is a planned extension (docs/plans/spec/01).")
395
+ (member :name scene-time-inputs :description "12 B: time, canvasWidth, canvasHeight (all f32) — the first 12 bytes of pngine-inputs. True scene timing is not modelled yet.")
196
396
  (member :name pointer-inputs :description "48 B: x, y, clickX, clickY, dx, dy, buttons, pressure, modifiers, scrollX, scrollY, _pad (all f32).")))
397
+ ; The two ref arms are ONE cross-ref target group, never a union of two ref
398
+ ; kinds: a union resolves first-match while the emitter looks the name up in
399
+ ; separate id tables. A group gives one namespace — a
400
+ ; `(data …)` and a `(wasm-call …)` that share a name collide at the second
401
+ ; declaration, so "which table" is decided by the document, not by arm order.
402
+ (value-kind :name data-or-wasm-ref
403
+ :description "Reference to a declared (data :name …) or (wasm-call :name …). One namespace across the two."
404
+ :underlying symbol
405
+ :cross-ref (cross-ref :target [data wasm-call]))
197
406
  (value-kind :name write-buffer-source
198
- :description "write-buffer :data source: a runtime builtin or a (data …) reference."
407
+ :description "write-buffer :data source: a runtime builtin, a (data …) reference, or a (wasm-call …) whose result is written each frame."
199
408
  :underlying union
200
- :union (union-shape :alternatives [builtin-data-source data-ref]))
409
+ :union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
201
410
 
202
- ; ---- size: a byte count / expression OR a data-ref the buffer is sized from ----
203
- (value-kind :name byte-size
204
- :description "Buffer size: an integer / expression, or a (data …) reference."
205
- :underlying union
206
- :union (union-shape :alternatives [byte-count data-ref]))
411
+ ; `byte-size` was `[byte-count data-ref]` — a union whose ref arm meant "size
412
+ ; this buffer from that data without filling it". Every corpus use of it also
413
+ ; carried `:mapped-at-creation <the same data>`, naming one thing twice, and
414
+ ; `:data` sizes the buffer now. The arm is gone; a buffer's `:size` is a byte
415
+ ; count.
207
416
 
208
417
  ; ---- enums ----
209
418
  (value-kind :name buffer-usage
@@ -218,8 +427,8 @@
218
427
  (member :name copy-src :description "Source of copy operations.")
219
428
  (member :name indirect :description "Holds indirect draw/dispatch arguments.")
220
429
  (member :name query-resolve :description "Receives resolve-query-set results.")
221
- (member :name map-read :description "Mappable for CPU readback.")
222
- (member :name map-write :description "Mappable for CPU upload (write).")))
430
+ (member :name map-read :description "Mappable for CPU readback; combines with copy-dst and nothing else.")
431
+ (member :name map-write :description "Mappable for CPU upload (write); combines with copy-src and nothing else.")))
223
432
  (value-kind :name primitive-topology
224
433
  :description "GPUPrimitiveTopology — how vertices are assembled into primitives."
225
434
  :underlying symbol
@@ -299,6 +508,25 @@
299
508
  (value-kind :name entry-point
300
509
  :description "Shader entry-point function name (a WGSL @vertex/@fragment/@compute fn)."
301
510
  :underlying symbol)
511
+ ; Follows `entry-point`: a free symbol naming something inside opaque WGSL,
512
+ ; which the EMITTER cross-checks against reflection. SJON cannot check it —
513
+ ; the override declarations live inside a `:code` string the validator does
514
+ ; not parse.
515
+ (value-kind :name override-name
516
+ :description "A WGSL `override` identifier, as written in the shader. An @id(N)-annotated override is still named by its identifier here — pngine resolves the value at compile time, so the numeric id never reaches a runtime."
517
+ :underlying symbol)
518
+ ; Deliberately NOT :repr-tagged. A constant's width is whatever its WGSL
519
+ ; `override` declares (f32/u32/i32/bool), which the schema cannot see; the
520
+ ; emitter type-checks the value against the reflected type instead. A repr
521
+ ; tag here would be a guess that rejects valid documents.
522
+ (value-kind :name override-value
523
+ :description "The value to specialise a WGSL `override` with: an integer or real literal, or a bounded expression over (define …) constants. A bool override takes 0 or 1."
524
+ :underlying number
525
+ :unit (unit-shape :reject true))
526
+ (value-kind :name override-number
527
+ :description "An override's value: a literal, a bounded expression, or a bare (define …) reference."
528
+ :underlying scalar-or-ref
529
+ :scalar-or-ref (scalar-or-ref-shape :base override-value :ref define-ref))
302
530
  (value-kind :name layout-mode
303
531
  :description "Pipeline layout mode: auto derives bind-group layouts from the WGSL."
304
532
  :underlying symbol
@@ -371,9 +599,16 @@
371
599
  :description "Reference to a declared (query-set :name …)."
372
600
  :underlying symbol
373
601
  :cross-ref (cross-ref :target query-set))
374
- (value-kind :name timestamp-writes-item :underlying form :heads (head-set :names [timestamp-writes]))
375
602
  ; Heads admitted positionally inside an (occlusion-query …) bracket.
376
- (value-kind :name occlusion-draw-item :underlying form :heads (head-set :names [draw draw-indexed]))
603
+ ; Every draw WebGPU brackets, at least one — the bracket is a plain
604
+ ; begin/draws/end sequence, and it admits the indirect pair the wire has
605
+ ; always allowed.
606
+ (value-kind :name occlusion-draw-item :underlying form :heads (head-set
607
+ :min-children 1
608
+ (head :name draw)
609
+ (head :name draw-indexed)
610
+ (head :name draw-indirect)
611
+ (head :name draw-indexed-indirect)))
377
612
 
378
613
  ; ---- Phase 2a: textures, shape generators, depth/stencil, indexed draws ----
379
614
  (value-kind :name texture-ref
@@ -454,6 +689,38 @@
454
689
  :underlying symbol
455
690
  :members (member-set
456
691
  (member :name canvas :description "Track the canvas size at runtime (resizes with it).")))
692
+ ; One dimension of a GPUExtent3D. `:min 1`, not `:min 0`: a zero-texel
693
+ ; dimension is invalid GPU in every direction, and the keys this replaces
694
+ ; (`:width`/`:height`, typed `byte-count`) accepted 0 and encoded it.
695
+ (value-kind :name extent-value
696
+ :description "One dimension of a GPUExtent3D, in texels (at least 1)."
697
+ :underlying number
698
+ :numeric (numeric-bounds :min 1 :integer true)
699
+ :unit (unit-shape :reject true)
700
+ :repr (repr-shape :type u32))
701
+ (value-kind :name extent
702
+ :description "One GPUExtent3D dimension: a literal, a bounded expression, or a bare (define …) reference."
703
+ :underlying scalar-or-ref
704
+ :scalar-or-ref (scalar-or-ref-shape :base extent-value :ref define-ref))
705
+ ; GPUExtent3D's sequence form: [w], [w h], [w h d]. The missing dimensions are
706
+ ; WebGPU's own defaults (height 1, depthOrArrayLayers 1), not pngine's — which
707
+ ; is why they are absent rather than materialized (see the defaults policy at
708
+ ; the top of this file). A vector, because a sequence of scalars is a vector;
709
+ ; three keys, because it was three keys.
710
+ (value-kind :name extent3
711
+ :description "Texture size as [width], [width height], or [width height depth-or-array-layers]; the missing dimensions default to 1."
712
+ :underlying vector
713
+ :vector (vector-shape :element extent :min-len 1 :max-len 3))
714
+ ; GPUTextureDescriptor.size is ONE required member, so it is one required key
715
+ ; over the three things a pngine texture may be sized by. Three
716
+ ; different underlyings — vector, symbol member, cross-ref — so the union
717
+ ; cannot be ambiguous. `texture-size-mode` precedes `image-bitmap-ref` because
718
+ ; both are symbols and `canvas` must be read as the mode; the emitter's
719
+ ; reserved-name check keeps a form from claiming the name.
720
+ (value-kind :name texture-size
721
+ :description "Texture size: an [w h d] extent, `canvas` to track the canvas, or an (image-bitmap …) to take the decoded image's size."
722
+ :underlying union
723
+ :union (union-shape :alternatives [extent3 texture-size-mode image-bitmap-ref]))
457
724
  (value-kind :name index-format
458
725
  :description "GPUIndexFormat — byte width of index-buffer entries."
459
726
  :underlying symbol
@@ -531,7 +798,9 @@
531
798
  (member :name decrement-clamp :description "Decrement, clamping at 0.")
532
799
  (member :name increment-wrap :description "Increment, wrapping to 0 past the maximum.")
533
800
  (member :name decrement-wrap :description "Decrement, wrapping to the maximum below 0.")))
534
- (value-kind :name depth-stencil-section :underlying form :heads (head-set :names [stencil-front stencil-back]))
801
+ (value-kind :name depth-stencil-section :underlying form :heads (head-set
802
+ (head :name stencil-front :max 1)
803
+ (head :name stencil-back :max 1)))
535
804
 
536
805
  ; ---- Phase 2d: MRT / MSAA / advanced render state ----
537
806
  ; A render-pass attachment view: the canvas (context-current-texture) or a
@@ -576,16 +845,34 @@
576
845
  :numeric (numeric-bounds :min 0 :max 15 :integer true)
577
846
  :unit (unit-shape :reject true)
578
847
  :repr (repr-shape :type u32))
848
+ ; The symbol half used to be the PRIMITIVE `symbol`, which accepts any
849
+ ; spelling: `:write-mask everything` validated, and the emitter's "any
850
+ ; non-numeric means all channels" fallback wrote 0xF — a target the author
851
+ ; believed was masked rendered every channel, with no diagnostic anywhere.
852
+ ; One member, closed.
853
+ (value-kind :name write-mask-symbol
854
+ :description "The one symbolic write mask: all (every channel, WebGPU's GPUColorWrite.ALL = 15)."
855
+ :underlying symbol
856
+ :members (member-set :values [all]))
857
+ ; A `(scalar-or-ref-shape …)` rather than a hand-written `(union-shape …)` of
858
+ ; the same two kinds, and the difference is the diagnostic: SJON's arm report
859
+ ; is gated on the scalar-or-ref flag (a hand-written union keeps the collapsed
860
+ ; report, deliberately — its alternatives may legitimately overlap). Spelled
861
+ ; this way, `:write-mask MASK` says `all` is the only symbol it takes; spelled
862
+ ; as a union it said "no alternative matched: write-mask-value |
863
+ ; write-mask-symbol". `:ref` need not be a cross-ref kind — the meta-schema
864
+ ; defines it as "a symbolic reference", and a closed member set is one.
579
865
  (value-kind :name write-mask
580
866
  :description "Color write mask: an integer bitmask (R=1 G=2 B=4 A=8) or the symbol all (15). Emitter-resolved."
581
- :underlying union
582
- :union (union-shape :alternatives [write-mask-value symbol]))
867
+ :underlying scalar-or-ref
868
+ :scalar-or-ref (scalar-or-ref-shape :base write-mask-value :ref write-mask-symbol))
583
869
 
584
870
  ; ---- explicit bind-group-layout (uniform_access feature) ----
585
- ; A `#bindGroupLayout` declares the binding layout explicitly (per-entry
586
- ; visibility + buffer-binding-type) instead of inferring it from a pipeline's
587
- ; auto-layout. visibility is a shader-stage set the emitter ORs into the WebGPU
588
- ; descriptor mask (vertex 0x01 / fragment 0x02 / compute 0x04).
871
+ ; A `(bind-group-layout …)` declares the binding layout explicitly (per-entry
872
+ ; visibility + one resource sub-form: buffer / sampler / texture /
873
+ ; storage-texture) instead of inferring it from a pipeline's auto-layout.
874
+ ; visibility is a shader-stage set the emitter ORs into the WebGPU descriptor
875
+ ; mask (vertex 0x01 / fragment 0x02 / compute 0x04).
589
876
  (value-kind :name visibility
590
877
  :description "GPUShaderStage — a shader stage that may access the binding."
591
878
  :underlying symbol
@@ -611,14 +898,38 @@
611
898
  :description "Reference to a declared (pipeline-layout :name …)."
612
899
  :underlying symbol
613
900
  :cross-ref (cross-ref :target pipeline-layout))
901
+ ; GPUPipelineDescriptorBase.layout is ONE required member of type
902
+ ; `GPUPipelineLayout | "auto"`, so it is ONE key. It was two keys and
903
+ ; an exclusive-group, which said the same thing in three places and let the
904
+ ; exported types describe a shape WebGPU does not have.
905
+ ; `layout-mode` comes FIRST in the union: SJON tries alternatives in order, so
906
+ ; `auto` is matched as the mode before it could ever be read as a name — which
907
+ ; is what reserves it (`(pipeline-layout :name auto)` is rejected by the
908
+ ; emitter's reserved-name check).
909
+ (value-kind :name pipeline-layout-spec
910
+ :description "GPUPipelineDescriptorBase.layout: auto (derive from the WGSL), or an explicit (pipeline-layout …)."
911
+ :underlying union
912
+ :union (union-shape :alternatives [layout-mode pipeline-layout-ref]))
614
913
  ; Positional sub-form heads for the explicit bind-group-layout: an (entry …)
615
- ; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms (F8):
914
+ ; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms:
616
915
  ; declared inline under their parent form and resolved LOCAL-FIRST, so the
617
916
  ; natural names `entry`/`buffer` shadow within scope — no collision with the
618
917
  ; global `entry` (render-pipeline stage) or `buffer` (top-level resource) forms.
619
918
  ; Extends to local (sampler …)/(texture …) resources later.
620
919
  (value-kind :name bgl-entry-item :underlying form :heads (head-set :names [entry]))
621
- (value-kind :name bgl-resource :underlying form :heads (head-set :names [buffer sampler texture storage-texture]))
920
+ ; Exactly ONE resource per entry (GPUBindGroupLayoutEntry). Both levels are
921
+ ; stated on purpose. `:min-children 1 :max-children 1` (SJON after 1.2.0)
922
+ ; counts the WHOLE set — the half per-head bounds cannot express, and what the
923
+ ; emitter's `requireOneOf` used to carry. The per-head `:max 1`s are then
924
+ ; arithmetically redundant, and kept for their diagnostic: the set yields to
925
+ ; the head, so two `(buffer …)` report "at most one `buffer`" (the line to
926
+ ; delete) rather than the set's weaker "too many resources".
927
+ (value-kind :name bgl-resource :underlying form :heads (head-set
928
+ :min-children 1 :max-children 1
929
+ (head :name buffer :max 1)
930
+ (head :name sampler :max 1)
931
+ (head :name texture :max 1)
932
+ (head :name storage-texture :max 1)))
622
933
  ; The three non-buffer resource kinds. Each symbol member IS its WebGPU spelling,
623
934
  ; so the emitter passes it into the descriptor JSON verbatim (like buffer-binding-type).
624
935
  (value-kind :name canvas-alpha-mode
@@ -626,7 +937,7 @@
626
937
  :underlying symbol
627
938
  :members (member-set
628
939
  (member :name opaque :description "Alpha is ignored; the canvas composites as opaque (the WebGPU spec default; cheaper, no fringe on colored pages).")
629
- (member :name premultiplied :description "Color values are premultiplied by alpha and blend with the page (PNGine's default when the form is absent).")))
940
+ (member :name premultiplied :description "Color values are premultiplied by alpha and blend with the page, so a transparent clear lets the page show through. Never a default: an absent (canvas …) form is opaque, as the IDL says.")))
630
941
  (value-kind :name sampler-binding-type
631
942
  :description "GPUSamplerBindingType — how a sampler binding is exposed to WGSL."
632
943
  :underlying symbol
@@ -658,24 +969,27 @@
658
969
  :string-bounds (string-bounds :format path))
659
970
 
660
971
  ; ---- vectors ----
661
- (value-kind :name float-list :underlying vector :vector (vector-shape :element number))
972
+ (value-kind :name float-list :underlying vector :vector (vector-shape :element real))
662
973
  ; Viewport: the two shapes the emitter accepts — a 5-element rect is invalid.
663
974
  (value-kind :name viewport-rect4
664
975
  :description "Viewport [x y w h]; minDepth/maxDepth default to 0 and 1."
665
- :underlying vector :vector (vector-shape :element number :len 4))
976
+ :underlying vector :vector (vector-shape :element real :len 4))
666
977
  (value-kind :name viewport-rect6
667
978
  :description "Viewport [x y w h minDepth maxDepth]; depths in [0,1]."
668
- :underlying vector :vector (vector-shape :element number :len 6))
979
+ :underlying vector :vector (vector-shape :element real :len 6))
669
980
  (value-kind :name viewport-rect
670
981
  :description "Viewport rectangle: [x y w h] or [x y w h minDepth maxDepth]."
671
982
  :underlying union
672
983
  :union (union-shape :alternatives [viewport-rect4 viewport-rect6]))
984
+ ; Integer pixels / texels / indices: `u32` elements (a literal, a bounded
985
+ ; expression, or a bare (define …) reference — non-negative integer), where
986
+ ; `real` used to let `[0.5 0 1 1.25]` through to be truncated.
673
987
  (value-kind :name pixel-rect
674
988
  :description "Rectangle [x y w h] in integer pixels."
675
- :underlying vector :vector (vector-shape :element number :len 4))
989
+ :underlying vector :vector (vector-shape :element u32 :len 4))
676
990
  (value-kind :name origin3
677
- :description "Copy origin [x y z] in texels; z is the destination array layer / depth slice (default 0)."
678
- :underlying vector :vector (vector-shape :element number :max-len 3))
991
+ :description "Copy origin [x y z] in integer texels; z is the destination array layer / depth slice (default 0)."
992
+ :underlying vector :vector (vector-shape :element u32 :max-len 3))
679
993
  ; A buffer/texture with zero usage flags is invalid GPU — require >= 1 (else the
680
994
  ; reader emits a buffer with no usage and no diagnostic). `:min-len 1`.
681
995
  (value-kind :name usage-list
@@ -684,13 +998,13 @@
684
998
  ; RGBA clear: exactly 4 components (else a 3-element color silently gets alpha 0).
685
999
  (value-kind :name clear-color
686
1000
  :description "RGBA clear color: exactly 4 components."
687
- :underlying vector :vector (vector-shape :element number :len 4))
1001
+ :underlying vector :vector (vector-shape :element real :len 4))
688
1002
  ; RGBA blend-constant: exactly 4 float components, used by the `constant` /
689
1003
  ; `one-minus-constant` blend factors (setBlendConstant). Same shape as
690
1004
  ; clear-color; named separately so the description reads for its own role.
691
1005
  (value-kind :name blend-constant-color
692
1006
  :description "RGBA blend constant: exactly 4 float components (the `constant` blend factor's value)."
693
- :underlying vector :vector (vector-shape :element number :len 4))
1007
+ :underlying vector :vector (vector-shape :element real :len 4))
694
1008
  (value-kind :name buffer-ref-list
695
1009
  :description "Declared (buffer …) names, bound to vertex slots 0..N in order."
696
1010
  :underlying vector :vector (vector-shape :element buffer-ref))
@@ -698,79 +1012,207 @@
698
1012
  :description "Declared (bind-group …) names, set at @group 0..N in order."
699
1013
  :underlying vector :vector (vector-shape :element bind-group-ref))
700
1014
  (value-kind :name bind-group-layout-ref-list
701
- :description "Declared (bind-group-layout …) names composing a pipeline layout at @group 0..N in order."
1015
+ :description "Declared (bind-group-layout …) names composing a pipeline layout at @group 0..N in order. At least one — a pngine opinion (WebGPU allows an empty list); an empty pipeline layout is `:layout auto` over a shader with no bindings."
702
1016
  :underlying vector :vector (vector-shape :element bind-group-layout-ref :min-len 1))
703
1017
  (value-kind :name render-bundle-ref-list
704
1018
  :description "Declared (render-bundle …) names replayed by a pass."
705
1019
  :underlying vector :vector (vector-shape :element render-bundle-ref))
1020
+ ; Every list below runs ONCE PER FRAME, so its length multiplies per-frame GPU
1021
+ ; work directly. `:max-len 2048` on all three is the command-buffer budget: the
1022
+ ; cheapest step that emits anything is a compute pass (begin 1B + set_pipeline
1023
+ ; 3B + dispatch 13B + end 1B = 18B), so ~3,640 steps alone exhaust the 64 KB
1024
+ ; buffer — and past that the stream TEARS rather than truncates (cmd_count
1025
+ ; counts commands whose operand bytes were dropped). 2048 sits below that with
1026
+ ; headroom and is 25x the longest list in the corpus (82, webgpu_bitonic_sort).
1027
+ ; Mirrored by Emitter.MAX_FRAME_STEPS for the queue-action count, which is
1028
+ ; positional and so has no schema length to bound.
706
1029
  (value-kind :name queue-ref-list
707
1030
  :description "Declared (queue …) names, run in order."
708
- :underlying vector :vector (vector-shape :element queue-ref))
1031
+ :underlying vector :vector (vector-shape :element queue-ref :max-len 2048))
709
1032
  (value-kind :name compute-pass-ref-list
710
1033
  :description "Declared (compute-pass …) / (init …) names, run in order."
711
- :underlying vector :vector (vector-shape :element compute-pass-ref))
712
- ; One frame step: render-pass tried first, then compute-pass, then queue.
1034
+ :underlying vector :vector (vector-shape :element compute-pass-ref :max-len 2048))
1035
+ ; One frame step. The three forms share ONE namespace (SJON 1.2.0 multi-target
1036
+ ; cross-ref): a pass and a queue with the same :name is a
1037
+ ; `duplicate_cross_ref_target` at the declaration, so a step can never be
1038
+ ; ambiguous. (It used to be a union tried in order, while the emitter kept
1039
+ ; one table for both pass kinds — a collision silently dropped the render pass.)
713
1040
  (value-kind :name frame-step
714
- :description "One frame step: a render-pass, compute-pass, or queue name."
715
- :underlying union
716
- :union (union-shape :alternatives [render-pass-ref compute-pass-ref queue-ref]))
1041
+ :description "One frame step: a render-pass, compute-pass, or queue name (one namespace across the three)."
1042
+ :underlying symbol
1043
+ :cross-ref (cross-ref :target [render-pass compute-pass queue]))
717
1044
  (value-kind :name frame-step-list
718
1045
  :description "Passes and queues run every frame, in order."
719
- :underlying vector :vector (vector-shape :element frame-step))
1046
+ :underlying vector :vector (vector-shape :element frame-step :max-len 2048))
1047
+ ; `:min-len 1` because count 0 is not "no color targets" on the wire — it is
1048
+ ; the frozen legacy sentinel meaning "substitute the preferred canvas format"
1049
+ ; (docs/abi.md §6.5), which is exactly the fabrication 3.0.0 removes.
1050
+ ; A depth-only bundle is legal WebGPU and this descriptor cannot express it;
1051
+ ; saying so is better than accepting `[]` and encoding the canvas guess.
720
1052
  (value-kind :name texture-format-list
721
- :description "Color target formats a (render-bundle …) is recorded against."
722
- :underlying vector :vector (vector-shape :element texture-format))
1053
+ :description "Color target formats a (render-bundle …) is recorded against (at least one)."
1054
+ :underlying vector :vector (vector-shape :element texture-format :min-len 1))
723
1055
  (value-kind :name data-file-list
724
- :description "WASM file paths whose data segments become D0, D1, … storage buffers."
1056
+ :description "WASM file paths (a pass's :file) whose data segments become D0, D1, … storage buffers."
725
1057
  :underlying vector :vector (vector-shape :element file-path))
726
1058
  (value-kind :name offset-list
727
1059
  :description "Integer offset list (e.g. per-entry ping-pong pool offsets)."
728
- :underlying vector :vector (vector-shape :element number))
1060
+ :underlying vector :vector (vector-shape :element u32))
729
1061
  (value-kind :name shape-format-list
730
1062
  :description "Vertex layout of generated shape data, as ordered attribute specifiers."
731
1063
  :underlying vector :vector (vector-shape :element shape-format))
732
1064
  (value-kind :name texture-usage-list
733
1065
  :description "Texture usage flags (at least one)."
734
1066
  :underlying vector :vector (vector-shape :element texture-usage :min-len 1))
1067
+ ; GPUExtent3D's sequence rule again, one form over: [x], [x y], [x y z], the
1068
+ ; missing dimensions WebGPU's own default of 1. Vector-only — the
1069
+ ; alternative was a union with a bare `:workgroups 64` beside `[16 16 1]`,
1070
+ ; which would leave the grammar with exactly one member that has two shapes
1071
+ ; while texture `:size 512` stays illegal.
1072
+ ;
1073
+ ; The element is `count` — a literal, a bounded expression, or a bare
1074
+ ; `(define …)` name — since 3.0.0 (`[WG 1 1]` works; it used to
1075
+ ; be `count-value`, literals and expressions only, because the element
1076
+ ; reader resolved no symbols, §307).
735
1077
  (value-kind :name dispatch-size
736
- :description "3-element compute dispatch [x y z] in workgroups."
737
- :underlying vector :vector (vector-shape :element count-value :len 3))
738
- ; #wasmCall args: the emitter encodes a type tag per arg (+ 4 value bytes for
1078
+ :description "Compute dispatch in workgroups as [x], [x y] or [x y z]; the missing dimensions default to 1. Elements are literals, expressions, or (define …) names."
1079
+ :underlying vector :vector (vector-shape :element count :min-len 1 :max-len 3))
1080
+ ; `(wasm-call …)` args: the emitter encodes a type tag per arg (+ 4 value bytes for
739
1081
  ; literals); the legacy spells the builtins `canvas.width`/etc.
1082
+ ; Same closure as `write-mask`, one form over: the symbol half was the
1083
+ ; primitive, so `:args [canvas-widht]` validated and reached an emitter check
1084
+ ; that had to exist because the schema could not say the four names. The
1085
+ ; emitter's map is still the authority on the ENCODING; the schema is
1086
+ ; the authority on the spelling, and the two are pinned together by
1087
+ ; `values.mapWasmArgType` (a member the map does not know is `internal:`).
1088
+ (value-kind :name wasm-arg-builtin
1089
+ :description "A runtime value the player fills in before each (wasm-call …)."
1090
+ :underlying symbol
1091
+ :members (member-set
1092
+ (member :name canvas-width :description "Canvas width in physical pixels.")
1093
+ (member :name canvas-height :description "Canvas height in physical pixels.")
1094
+ (member :name time-total :description "Seconds since playback started.")
1095
+ (member :name time-delta :description "Seconds since the previous frame.")))
740
1096
  (value-kind :name wasm-arg
741
1097
  :description "WASM call argument: a numeric literal, or a runtime builtin the player fills each frame (canvas-width, canvas-height, time-total, time-delta)."
742
- :underlying union :union (union-shape :alternatives [symbol number]))
1098
+ :underlying union :union (union-shape :alternatives [wasm-arg-builtin number]))
743
1099
  (value-kind :name wasm-arg-list
744
1100
  :description "Arguments passed to a (wasm-call …) function each frame."
745
1101
  :underlying vector :vector (vector-shape :element wasm-arg))
746
1102
 
747
1103
  ; ---- positional head-sets ----
748
- (value-kind :name pipeline-section :underlying form :heads (head-set :names [layout vertex fragment primitive depth-stencil multisample]))
749
- (value-kind :name vertex-section :underlying form :heads (head-set :names [module entry buffers]))
750
- (value-kind :name fragment-section :underlying form :heads (head-set :names [module entry targets]))
751
- (value-kind :name primitive-section :underlying form :heads (head-set :names [topology]))
752
- (value-kind :name buffers-item :underlying form :heads (head-set :names [vertex-buffer]))
1104
+ ; Per-head `:min`/`:max` (SJON 1.2.0) carry the IDL's cardinality: a
1105
+ ; GPURenderPipelineDescriptor has exactly one vertex stage and at most one of
1106
+ ; each other state; a compute pipeline has exactly one compute stage. Below
1107
+ ; the floor is `positional_missing` (on the parent), above the ceiling
1108
+ ; `positional_too_many` (on the extra child) — both located, at validation.
1109
+ ; Until 1.3 these were unenforced or hand-checked in the emitter.
1110
+ (value-kind :name pipeline-section :underlying form :heads (head-set
1111
+ (head :name vertex :min 1 :max 1)
1112
+ (head :name fragment :max 1)
1113
+ (head :name primitive :max 1)
1114
+ (head :name depth-stencil :max 1)
1115
+ (head :name multisample :max 1)))
1116
+ ; A stage's module and entry point are SCALARS, so they are keys; what
1117
+ ; is left positional is the stage's sequences — `GPUVertexState.buffers`
1118
+ ; and `GPUFragmentState.targets`, spliced in directly with no wrapper form.
1119
+ (value-kind :name vertex-section :underlying form :heads (head-set
1120
+ (head :name vertex-buffer)
1121
+ (head :name constant)))
1122
+ ; `:min 1` on `target` is a deliberate PNGine narrowing of
1123
+ ; GPUFragmentState.targets, which WebGPU lets be empty (a depth-only fragment
1124
+ ; stage). Removing the wrapper costed as "zero targets becomes legal" — but
1125
+ ; pngine has no runtime that honours it: wgpu_native_gpu's
1126
+ ; pipeline decoder substitutes ONE BGRA8Unorm target when the list is empty,
1127
+ ; and gpu.js passes the empty list through, so the two backends would build
1128
+ ; DIFFERENT pipelines from the same document. That is exactly the fabrication
1129
+ ; 3.0.0 set out to remove, so the floor stays until a backend can
1130
+ ; express a depth-only stage. It also closes a hole the wrapper left open:
1131
+ ; `(targets)` with no children validated and reached the same fabrication.
1132
+ (value-kind :name fragment-section :underlying form :heads (head-set
1133
+ (head :name target :min 1)
1134
+ (head :name constant)))
1135
+ ; One stage per compute pipeline, spelled as a form like the other two. The
1136
+ ; schema used to argue the flat `:module`/`:entry` shape was natural
1137
+ ; here; it is the same GPUProgrammableStage the vertex and fragment stages
1138
+ ; carry, and one rule that holds everywhere beats three shapes that each read
1139
+ ; well alone.
1140
+ (value-kind :name compute-pipeline-section :underlying form :heads (head-set
1141
+ (head :name compute :min 1 :max 1)))
1142
+ (value-kind :name compute-section :underlying form :heads (head-set :names [constant]))
753
1143
  (value-kind :name attribute-item :underlying form :heads (head-set :names [attribute]))
754
- (value-kind :name targets-item :underlying form :heads (head-set :names [target]))
755
- (value-kind :name target-section :underlying form :heads (head-set :names [blend]))
756
- (value-kind :name blend-section :underlying form :heads (head-set :names [color alpha]))
757
- (value-kind :name render-pass-section :underlying form :heads (head-set :names [color-attachment depth-attachment draw draw-indexed draw-indirect draw-indexed-indirect timestamp-writes occlusion-query]))
1144
+ (value-kind :name target-section :underlying form :heads (head-set
1145
+ (head :name blend :max 1)))
1146
+ ; GPUBlendState requires BOTH components — `(blend (color …))` alone used to
1147
+ ; validate and die on the GPU.
1148
+ (value-kind :name blend-section :underlying form :heads (head-set
1149
+ (head :name color :min 1 :max 1)
1150
+ (head :name alpha :min 1 :max 1)))
1151
+ (value-kind :name render-pass-section :underlying form :heads (head-set
1152
+ (head :name color-attachment)
1153
+ (head :name depth-stencil-attachment :max 1)
1154
+ (head :name draw)
1155
+ (head :name draw-indexed)
1156
+ (head :name draw-indirect)
1157
+ (head :name draw-indexed-indirect)
1158
+ (head :name timestamp-writes :max 1)
1159
+ (head :name occlusion-query)))
758
1160
  (value-kind :name bind-entry-item :underlying form :heads (head-set :names [entry]))
759
1161
  (value-kind :name queue-action :underlying form :heads (head-set :names [write-buffer copy-texture-to-texture copy-external-image-to-texture resolve-query-set copy-buffer-to-buffer]))
760
- ; #data generators: a positional sub-form whose head selects a procedural shape
1162
+ ; Both texture copies take exactly one endpoint of each kind. The heads
1163
+ ; are shared but the FORMS are not — each copy declares its own slot-local
1164
+ ; `source`/`destination`, resolved local-first, so `(source :image …)` under
1165
+ ; one is not `(source :texture …)` under the other.
1166
+ (value-kind :name copy-endpoints-section :underlying form :heads (head-set
1167
+ (head :name source :min 1 :max 1)
1168
+ (head :name destination :min 1 :max 1)))
1169
+ ; A compute pass issues at least one command: a pass that dispatches
1170
+ ; nothing is always an authoring slip. WebGPU has no such rule — this is
1171
+ ; pngine's opinion, and it is one line of schema rather than an emitter check.
1172
+ ; Unbounded per head: several dispatches in one pass is legal WebGPU.
1173
+ (value-kind :name compute-pass-command :underlying form :heads (head-set
1174
+ :min-children 1
1175
+ (head :name dispatch)
1176
+ (head :name dispatch-indirect)))
1177
+ ; A bundle records EXACTLY ONE draw, and only a direct one. Not an opinion:
1178
+ ; the create_render_bundle descriptor carries a single `drawType` byte with
1179
+ ; two values, decoded that way by gpu.js, the native backend and the reference
1180
+ ; dispatcher alike. `draw-indirect` in a bundle, and a second draw, arrive
1181
+ ; when that descriptor does.
1182
+ (value-kind :name render-bundle-command :underlying form :heads (head-set
1183
+ :min-children 1
1184
+ :max-children 1
1185
+ (head :name draw :max 1)
1186
+ (head :name draw-indexed :max 1)))
1187
+ ; `(data …)` generators: a positional sub-form whose head selects a procedural shape
761
1188
  ; (cube/sphere/…) or `wasm-data` (a WASM function that returns the vertex bytes).
762
- (value-kind :name data-shape-section :underlying form :heads (head-set :names [cube plane sphere torus truncated-cone cylinder teapot dragon wasm-data]))
1189
+ ; At most ONE per (data …) — one byte source, nine spellings. Per-head bounds
1190
+ ; say "at most one of each"; "at most one across the nine" is the ceiling over
1191
+ ; the SET (SJON after 1.2.0 — it replaced the emitter's `requireOneOf`).
1192
+ ; `:max-children` with no floor, since a (data … :float32 […]) / (data …
1193
+ ; :file …) carries no generator at all.
1194
+ (value-kind :name data-shape-section :underlying form :heads (head-set
1195
+ :max-children 1
1196
+ (head :name cube :max 1)
1197
+ (head :name plane :max 1)
1198
+ (head :name sphere :max 1)
1199
+ (head :name torus :max 1)
1200
+ (head :name truncated-cone :max 1)
1201
+ (head :name cylinder :max 1)
1202
+ (head :name teapot :max 1)
1203
+ (head :name dragon :max 1)
1204
+ (head :name wasm-data :max 1)))
763
1205
 
764
1206
  ; =====================================================================
765
- ; Top-level forms (one per legacy `#macro`)
1207
+ ; Top-level forms
766
1208
  ; =====================================================================
767
1209
 
768
1210
  (form :name define
769
- :description "Named numeric constant collected into the emitter's expr env."
1211
+ :description "Named numeric constant, usable in every numeric slot and vector element as a bare name or inside a bounded expression."
770
1212
  (key :name name :type symbol
771
- :description "Constant name, referenced from numeric expression slots and count slots.")
772
- (key :name value :type byte-count
773
- :description "Non-negative integer value."))
1213
+ :description "Constant name, referenced from numeric slots, vector elements and expressions.")
1214
+ (key :name value :type real
1215
+ :description "The constant's value: a real (negative and fractional allowed), a bounded expression, or another constant's name — the slot that reads the constant decides integrality and range."))
774
1216
 
775
1217
  ; Authored WebGPU device requiredLimits. Optional singleton (declare at most
776
1218
  ; once, no :name). Each present key raises the corresponding GPUSupportedLimits
@@ -778,121 +1220,131 @@
778
1220
  ; device().requestDevice({requiredLimits}); an unsatisfiable value fails loud at
779
1221
  ; device creation. Also feeds compile-time validation — e.g. raising
780
1222
  ; :max-compute-workgroup-size-x unlocks @workgroup_size(512). Names are the exact
781
- ; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire). (§5.3b)
1223
+ ; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire).
782
1224
  (form :name limits
783
1225
  :description "Authored WebGPU device requiredLimits (optional singleton)."
784
- (key :name max-texture-dimension-1d :type device-limit-value :optional true
1226
+ (key :name max-texture-dimension-1d :type device-limit :optional true
785
1227
  :description "Max width of a 1D texture (default 8192).")
786
- (key :name max-texture-dimension-2d :type device-limit-value :optional true
1228
+ (key :name max-texture-dimension-2d :type device-limit :optional true
787
1229
  :description "Max width/height of a 2D texture (default 8192).")
788
- (key :name max-texture-dimension-3d :type device-limit-value :optional true
1230
+ (key :name max-texture-dimension-3d :type device-limit :optional true
789
1231
  :description "Max width/height/depth of a 3D texture (default 2048).")
790
- (key :name max-texture-array-layers :type device-limit-value :optional true
1232
+ (key :name max-texture-array-layers :type device-limit :optional true
791
1233
  :description "Max array layers of a 2D texture (default 256).")
792
- (key :name max-bind-groups :type device-limit-value :optional true
1234
+ (key :name max-bind-groups :type device-limit :optional true
793
1235
  :description "Max simultaneous bind groups (default 4).")
794
- (key :name max-bind-groups-plus-vertex-buffers :type device-limit-value :optional true
1236
+ (key :name max-bind-groups-plus-vertex-buffers :type device-limit :optional true
795
1237
  :description "Max bind groups + vertex buffers combined (default 24).")
796
- (key :name max-bindings-per-bind-group :type device-limit-value :optional true
1238
+ (key :name max-bindings-per-bind-group :type device-limit :optional true
797
1239
  :description "Max bindings in a single bind group (default 1000).")
798
- (key :name max-dynamic-uniform-buffers-per-pipeline-layout :type device-limit-value :optional true
1240
+ (key :name max-dynamic-uniform-buffers-per-pipeline-layout :type device-limit :optional true
799
1241
  :description "Max dynamic-offset uniform buffers per pipeline layout (default 8).")
800
- (key :name max-dynamic-storage-buffers-per-pipeline-layout :type device-limit-value :optional true
1242
+ (key :name max-dynamic-storage-buffers-per-pipeline-layout :type device-limit :optional true
801
1243
  :description "Max dynamic-offset storage buffers per pipeline layout (default 4).")
802
- (key :name max-sampled-textures-per-shader-stage :type device-limit-value :optional true
1244
+ (key :name max-sampled-textures-per-shader-stage :type device-limit :optional true
803
1245
  :description "Max sampled textures per shader stage (default 16).")
804
- (key :name max-samplers-per-shader-stage :type device-limit-value :optional true
1246
+ (key :name max-samplers-per-shader-stage :type device-limit :optional true
805
1247
  :description "Max samplers per shader stage (default 16).")
806
- (key :name max-storage-buffers-per-shader-stage :type device-limit-value :optional true
1248
+ (key :name max-storage-buffers-per-shader-stage :type device-limit :optional true
807
1249
  :description "Max storage buffers per shader stage (default 8).")
808
- (key :name max-storage-buffers-in-vertex-stage :type device-limit-value :optional true
1250
+ (key :name max-storage-buffers-in-vertex-stage :type device-limit :optional true
809
1251
  :description "Max storage buffers in the vertex stage (compat split-stage limit; default 8).")
810
- (key :name max-storage-buffers-in-fragment-stage :type device-limit-value :optional true
1252
+ (key :name max-storage-buffers-in-fragment-stage :type device-limit :optional true
811
1253
  :description "Max storage buffers in the fragment stage (compat split-stage limit; default 8).")
812
- (key :name max-storage-textures-per-shader-stage :type device-limit-value :optional true
1254
+ (key :name max-storage-textures-per-shader-stage :type device-limit :optional true
813
1255
  :description "Max storage textures per shader stage (default 4).")
814
- (key :name max-storage-textures-in-vertex-stage :type device-limit-value :optional true
1256
+ (key :name max-storage-textures-in-vertex-stage :type device-limit :optional true
815
1257
  :description "Max storage textures in the vertex stage (compat split-stage limit; default 4).")
816
- (key :name max-storage-textures-in-fragment-stage :type device-limit-value :optional true
1258
+ (key :name max-storage-textures-in-fragment-stage :type device-limit :optional true
817
1259
  :description "Max storage textures in the fragment stage (compat split-stage limit; default 4).")
818
- (key :name max-uniform-buffers-per-shader-stage :type device-limit-value :optional true
1260
+ (key :name max-immediate-size :type device-limit :optional true
1261
+ :description "Max size in bytes of a pipeline's immediate-data range; must be a multiple of 4 (default 64).")
1262
+ (key :name max-uniform-buffers-per-shader-stage :type device-limit :optional true
819
1263
  :description "Max uniform buffers per shader stage (default 12).")
820
- (key :name max-uniform-buffer-binding-size :type device-limit-value :optional true
1264
+ (key :name max-uniform-buffer-binding-size :type device-limit :optional true
821
1265
  :description "Max bound range of a uniform buffer in bytes (default 65536).")
822
- (key :name max-storage-buffer-binding-size :type device-limit-value :optional true
1266
+ (key :name max-storage-buffer-binding-size :type device-limit :optional true
823
1267
  :description "Max bound range of a storage buffer in bytes (default 134217728).")
824
- (key :name min-uniform-buffer-offset-alignment :type device-limit-value :optional true
1268
+ (key :name min-uniform-buffer-offset-alignment :type device-limit :optional true
825
1269
  :description "Required alignment of a dynamic uniform buffer offset (default 256).")
826
- (key :name min-storage-buffer-offset-alignment :type device-limit-value :optional true
1270
+ (key :name min-storage-buffer-offset-alignment :type device-limit :optional true
827
1271
  :description "Required alignment of a dynamic storage buffer offset (default 256).")
828
- (key :name max-vertex-buffers :type device-limit-value :optional true
1272
+ (key :name max-vertex-buffers :type device-limit :optional true
829
1273
  :description "Max vertex buffers in a render pipeline (default 8).")
830
- (key :name max-buffer-size :type device-limit-value :optional true
1274
+ (key :name max-buffer-size :type device-limit :optional true
831
1275
  :description "Max size of a buffer in bytes (default 268435456).")
832
- (key :name max-vertex-attributes :type device-limit-value :optional true
1276
+ (key :name max-vertex-attributes :type device-limit :optional true
833
1277
  :description "Max vertex attributes across all buffers (default 16).")
834
- (key :name max-vertex-buffer-array-stride :type device-limit-value :optional true
1278
+ (key :name max-vertex-buffer-array-stride :type device-limit :optional true
835
1279
  :description "Max stride of a vertex buffer in bytes (default 2048).")
836
- (key :name max-inter-stage-shader-variables :type device-limit-value :optional true
1280
+ (key :name max-inter-stage-shader-variables :type device-limit :optional true
837
1281
  :description "Max inter-stage shader variables (default 16).")
838
- (key :name max-color-attachments :type device-limit-value :optional true
1282
+ (key :name max-color-attachments :type device-limit :optional true
839
1283
  :description "Max color attachments in a render pass (default 8).")
840
- (key :name max-color-attachment-bytes-per-sample :type device-limit-value :optional true
1284
+ (key :name max-color-attachment-bytes-per-sample :type device-limit :optional true
841
1285
  :description "Max total bytes per sample across color attachments (default 32).")
842
- (key :name max-compute-workgroup-storage-size :type device-limit-value :optional true
1286
+ (key :name max-compute-workgroup-storage-size :type device-limit :optional true
843
1287
  :description "Max var<workgroup> storage in bytes (default 16384).")
844
- (key :name max-compute-invocations-per-workgroup :type device-limit-value :optional true
1288
+ (key :name max-compute-invocations-per-workgroup :type device-limit :optional true
845
1289
  :description "Max x*y*z of a compute @workgroup_size (default 256).")
846
- (key :name max-compute-workgroup-size-x :type device-limit-value :optional true
1290
+ (key :name max-compute-workgroup-size-x :type device-limit :optional true
847
1291
  :description "Max X of a compute @workgroup_size (default 256).")
848
- (key :name max-compute-workgroup-size-y :type device-limit-value :optional true
1292
+ (key :name max-compute-workgroup-size-y :type device-limit :optional true
849
1293
  :description "Max Y of a compute @workgroup_size (default 256).")
850
- (key :name max-compute-workgroup-size-z :type device-limit-value :optional true
1294
+ (key :name max-compute-workgroup-size-z :type device-limit :optional true
851
1295
  :description "Max Z of a compute @workgroup_size (default 64).")
852
- (key :name max-compute-workgroups-per-dimension :type device-limit-value :optional true
1296
+ (key :name max-compute-workgroups-per-dimension :type device-limit :optional true
853
1297
  :description "Max dispatchWorkgroups count per dimension (default 65535)."))
854
1298
 
855
1299
  (form :name canvas
856
1300
  :description "Canvas presentation configuration (optional singleton). Carried as a
857
1301
  header flag, consumed by the JS runtime at context.configure() before
858
- the executor runs. Form absent → premultiplied (the historical
859
- behavior; the WebGPU spec default is opaque — a pinned deviation).
1302
+ the executor runs. Form absent → opaque, as
1303
+ GPUCanvasConfiguration.alphaMode. Write (canvas :alpha-mode
1304
+ premultiplied) for a canvas the page shows through.
860
1305
  Native --frame renders offscreen and ignores it. viewFormats/
861
- colorSpace/toneMapping are deferred: anything list-shaped needs a
862
- chained header table, the 3 reserved header bytes being consumed
863
- by the device-limits offset (docs/plans/spec/04)."
864
- (key :name alpha-mode :type canvas-alpha-mode :default premultiplied
865
- :description "GPUCanvasConfiguration.alphaMode — opaque or premultiplied (PNGine default: premultiplied; the spec default is opaque)."))
1306
+ colorSpace/toneMapping are not modelled: anything list-shaped
1307
+ needs a chained header table, and the 3 reserved header bytes
1308
+ are consumed by the device-limits offset."
1309
+ (key :name alpha-mode :type canvas-alpha-mode :default opaque
1310
+ :description "GPUCanvasConfiguration.alphaMode — opaque (the default) or premultiplied, which lets the page behind the canvas show through wherever the rendered alpha is below 1."))
866
1311
 
867
1312
  (form :name shader-module
868
1313
  :description "A named WGSL module. The source is opaque text to SJON."
869
1314
  (key :name name :type symbol
870
- :description "Module name referenced by pipeline (module …) stages.")
1315
+ :description "Module name referenced by a pipeline stage's :module key.")
871
1316
  (key :name code :type string
872
- :description "WGSL source text. Triple-quoted strings dedent by common minimum indentation."))
1317
+ :description "WGSL source text, kept verbatim (a triple-quoted string's indentation is part of the shader)."))
873
1318
 
874
1319
  (form :name data
875
1320
  :description "Binary data: an inline float32 array, a positional shape sub-form
876
- (cube/teapot/…) the emitter expands to vertex bytes, or a `:blob`
1321
+ (cube/teapot/…) the emitter expands to vertex bytes, or a `:file`
877
1322
  image file the emitter reads from disk and embeds as
878
1323
  [mime_len][mime][bytes] (consumed by an image-bitmap)."
879
1324
  :positional data-shape-section
880
1325
  (key :name name :type symbol
881
- :description "Data name referenced by buffer :size / :mapped-at-creation / :index-of and image-bitmap :image.")
1326
+ :description "Data name referenced by buffer :data / :index-of and image-bitmap :data.")
882
1327
  (key :name float32 :type float-list :optional true
883
1328
  :description "Inline float32 array embedded little-endian in the payload.")
884
- (key :name blob :type file-path :optional true
1329
+ (key :name file :type file-path :optional true
885
1330
  :description "Image file path (relative to the source file) embedded as [mime_len][mime][bytes]; decoded at runtime via createImageBitmap.")
886
1331
  (key :name mime :type string :optional true
887
- :description "MIME type stored with the :blob bytes (e.g. image/png)."))
1332
+ :description "MIME type stored with the :file bytes (e.g. image/png); default application/octet-stream. Ignored when there is no :file.")
1333
+ ; One source per (data …): the inline array OR the file (both used to
1334
+ ; validate and the file won in silence). The third source, a
1335
+ ; positional generator, is a head-set the group cannot count against; the
1336
+ ; emitter refuses a generator beside either key, and a (data …) with none.
1337
+ (exclusive-group :cardinality at-most-one
1338
+ (alt :keys [float32])
1339
+ (alt :keys [file])))
888
1340
 
889
1341
  (form :name image-bitmap
890
- :description "A decoded image created from a (data … :blob …) entry. Copied into a texture via a (copy-external-image-to-texture …) queue action."
1342
+ :description "A decoded image created from a (data … :file …) entry. Copied into a texture via a (copy-external-image-to-texture …) queue action."
891
1343
  (key :name name :type symbol)
892
- (key :name image :type data-ref
893
- :description "The (data … :blob …) entry holding the encoded image bytes."))
1344
+ (key :name data :type data-ref
1345
+ :description "The (data … :file …) entry holding the encoded image bytes."))
894
1346
 
895
- ; ---- shape sub-forms (positional children of #data) ----
1347
+ ; ---- shape sub-forms (positional children of `(data …)`) ----
896
1348
  ; `:open true` so generator-specific numeric config (segments, rings, radius,
897
1349
  ; thickness, …) is accepted without enumerating it per shape; the emitter reads
898
1350
  ; the keys it knows. Indexed shapes (teapot, dragon) also produce `_indices`.
@@ -923,42 +1375,34 @@
923
1375
 
924
1376
  (form :name wasm-data
925
1377
  :description "Static WASM data generator (positional child of (data …)): the module's :func is called once at buffer-create time and its returned bytes fill the buffer via mappedAtCreation."
926
- (key :name url :type file-path
927
- :description "WASM file path relative to the source file (the legacy module={url=…} is flattened).")
1378
+ (key :name file :type file-path
1379
+ :description "WASM file path relative to the source file.")
928
1380
  (key :name func :type symbol
929
1381
  :description "Exported function called once to produce the bytes.")
930
1382
  (key :name returns :type string
931
1383
  :description "Return type → byte count (e.g. array<f32,360> → 1440)."))
932
1384
 
933
1385
  (form :name texture
934
- :description "GPU texture. `:size canvas` tracks canvas size; `:size-from <image-bitmap>`
935
- sizes from a decoded image; else width/height. `pool` creates N
936
- sequential ping-pong ids."
1386
+ :description "GPU texture. `:size` is an [w h d] extent, `canvas` to track the
1387
+ canvas size at runtime, or an (image-bitmap …) to take the decoded
1388
+ image's size. `pool` creates N sequential ping-pong ids."
937
1389
  (key :name name :type symbol)
938
- (key :name size :type texture-size-mode :optional true
939
- :description "canvas: track the canvas size at runtime (mutually exclusive with :width/:height).")
940
- (key :name size-from :type image-bitmap-ref :optional true
941
- :description "Take width/height from a decoded (image-bitmap …) at runtime (mutually exclusive with :size).")
942
- (key :name width :type byte-count :optional true
943
- :description "Texel width (when not sized by :size canvas or :size-from).")
944
- (key :name height :type byte-count :optional true
945
- :description "Texel height (when not sized by :size canvas or :size-from).")
1390
+ (key :name size :type texture-size
1391
+ :description "Texel size: [w], [w h] or [w h d]; canvas to track the canvas; or an (image-bitmap …) to size from a decoded image.")
946
1392
  (key :name format :type texture-format
947
1393
  :description "Texel format of the texture.")
948
1394
  (key :name usage :type texture-usage-list
949
1395
  :description "Allowed texture usages (at least one).")
950
- (key :name sample-count :type count-value :optional true
1396
+ (key :name sample-count :type u32 :optional true
951
1397
  :description "Samples per texel: 1 (default) or 4 (MSAA). >1 requires render-attachment usage and a resolve-target on the pass.")
952
1398
  (key :name dimension :type texture-dimension :optional true
953
- :description "Texture dimensionality: 1 (1d), 2 (2d, default), or 3 (3d). 3d needs :depth-or-array-layers; sampling 1d/3d/array textures needs a matching texture view.")
954
- (key :name depth-or-array-layers :type subresource-count :optional true
955
- :description "GPUExtent3D depthOrArrayLayers: slice count of a 3d texture or layer count of a 2d array (default 1).")
1399
+ :description "Texture dimensionality: 1d, 2d (default), or 3d. A 3d texture needs a third :size element; sampling 1d/3d/array textures needs a matching texture view.")
956
1400
  (key :name mip-level-count :type subresource-count :optional true
957
1401
  :description "GPUTextureDescriptor.mipLevelCount — number of mip levels to allocate (default 1). Levels beyond what's written stay uninitialized until generated.")
958
1402
  (key :name pool :type pool-size :optional true
959
1403
  :description "Create N sequential texture ids for ping-pong (actual id = base + (frame + offset) % N)."))
960
1404
 
961
- ; ---- explicit texture view (create_texture_view, opcode 0x1D) ----
1405
+ ; ---- explicit texture view (create_texture_view, opcode 0x0C) ----
962
1406
  ; A (texture …) bound directly gets a default 2d view; sampling a 1d/3d/array/
963
1407
  ; cube texture needs an explicit view whose dimension matches the WGSL binding.
964
1408
  ; Emitted after textures, before bind groups; `(entry :texture-view v)` binds it.
@@ -969,8 +1413,8 @@
969
1413
  (key :name name :type symbol)
970
1414
  (key :name texture :type texture-ref
971
1415
  :description "Source texture this view aliases.")
972
- (key :name view-dimension :type view-dimension :optional true
973
- :description "How the view is addressed: 0=1d 1=2d 2=2d-array 3=cube 4=cube-array 5=3d. Must match the WGSL binding (texture_2d_array, texture_3d, …). Default: inferred from the texture.")
1416
+ (key :name dimension :type view-dimension :optional true
1417
+ :description "How the view is addressed (GPUTextureViewDescriptor.dimension): 1d, 2d, 2d-array, cube, cube-array or 3d. Must match the WGSL binding (texture_2d_array, texture_3d, …). Default: inferred from the texture.")
974
1418
  (key :name aspect :type texture-aspect :optional true
975
1419
  :description "Which aspect(s) of a depth/stencil texture the view exposes (default all).")
976
1420
  (key :name base-mip-level :type subresource-index :optional true
@@ -990,20 +1434,20 @@
990
1434
  indexed shape's (teapot/dragon) index data — avoids a synthetic
991
1435
  `_indices` data symbol the SJON cross-ref validator can't resolve."
992
1436
  (key :name name :type symbol)
993
- (key :name size :type byte-size :optional true
994
- :description "Size in bytes: an integer, a bounded expression like (* NUM 4 4), or a (data …) ref the buffer is sized from.")
1437
+ (key :name size :type byte-count :optional true
1438
+ :description "Size in bytes: an integer, a bounded expression like (* NUM 4 4), or a bare (define …) name. Optional only when :data, :index-of or :file supplies the size instead.")
995
1439
  (key :name usage :type usage-list
996
- :description "Allowed buffer usages (at least one).")
1440
+ :description "Allowed buffer usages (at least one). A mappable buffer is host memory the GPU may only copy in or out of: map-read pairs with copy-dst, map-write with copy-src, and neither combines with anything else.")
997
1441
  (key :name pool :type pool-size :optional true
998
1442
  :description "Create N sequential buffer ids for ping-pong (actual id = base + (frame + offset) % N).")
999
- (key :name mapped-at-creation :type data-ref :optional true
1000
- :description "(data …) whose bytes fill the buffer at creation via mappedAtCreation.")
1443
+ (key :name data :type data-ref :optional true
1444
+ :description "(data …) whose bytes fill the buffer at creation via mappedAtCreation, and size it when :size is absent.")
1001
1445
  (key :name index-of :type data-ref :optional true
1002
- :description "Source size, initial bytes, and index-format (uint16/uint32) from an indexed shape's (teapot/dragon) index companion.")
1446
+ :description "Source size, initial bytes, and index-format (uint16/uint32) from an indexed shape's (teapot/dragon) index companion. Beside :data it wins: the index data sizes and fills the buffer, and :data is only length-checked, never written.")
1003
1447
  (key :name index-format :type index-format :optional true
1004
1448
  :description "Index format (uint16/uint32) when the buffer is bound as a pass's :index-buffer without an :index-of source (e.g. GPU-generated indices).")
1005
- (key :name wasm :type file-path :optional true
1006
- :description "WASM file path (relative to the source file); its l/s/gen exports supply size + initial bytes — size comes from the WASM, not :size. Synthesized by pngine/pass-v1 for #pass data= buffers."))
1449
+ (key :name file :type file-path :optional true
1450
+ :description "WASM file path (relative to the source file); its l/s/gen exports supply size + initial bytes — size comes from the WASM, not :size. Synthesized by pngine/pass-v1 for `(pass … :file …)` buffers."))
1007
1451
 
1008
1452
  ; Emitter packs a [type:u8][count:u16-LE] descriptor blob → create_query_set.
1009
1453
  (form :name query-set
@@ -1011,11 +1455,12 @@
1011
1455
  (key :name name :type symbol)
1012
1456
  (key :name type :type query-type
1013
1457
  :description "What each query measures: occlusion or timestamp.")
1014
- (key :name count :type count
1015
- :description "Number of queries in the set (spec max 4096)."))
1458
+ (key :name count :type query-count
1459
+ :description "Number of queries in the set, 1 to 4096 (the createQuerySet bound)."))
1016
1460
 
1017
1461
  (form :name queue
1018
- :description "Queue action (write-buffer / copy-texture-to-texture) inlined into
1462
+ :description "Queue actions (write-buffer, copy-buffer-to-buffer, copy-texture-to-texture,
1463
+ copy-external-image-to-texture, resolve-query-set) run in order by the
1019
1464
  frames that reference it."
1020
1465
  :positional queue-action
1021
1466
  (key :name name :type symbol))
@@ -1024,68 +1469,91 @@
1024
1469
  :description "Queue op: write bytes into a buffer before/within a frame (GPUQueue.writeBuffer)."
1025
1470
  (key :name buffer :type buffer-ref
1026
1471
  :description "Destination buffer (needs copy-dst usage).")
1027
- (key :name offset :type byte-count :default 0
1472
+ (key :name offset :type byte-count-4-aligned :default 0
1028
1473
  :description "Byte offset into the destination (WebGPU requires a multiple of 4).")
1029
- (key :name data :type write-buffer-source :optional true
1030
- :description "Source: a (data …) ref, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pointer-inputs (48B).")
1031
- (key :name data-from-wasm :type wasm-call-ref :optional true
1032
- :description "Write a (wasm-call …) result into the buffer at frame time. Mutually exclusive with :data.")
1033
- ; Exactly one data source. Declarative replacement for the emit-time check.
1034
- (exclusive-group :cardinality exactly-one
1035
- (alt :keys [data])
1036
- (alt :keys [data-from-wasm])))
1474
+ ; One key for one member. `:data-from-wasm` was a second spelling of
1475
+ ; the same slot, distinguished only by which kind of name it took — so the
1476
+ ; document said twice what the widened union now says once, and the
1477
+ ; exclusive-group existed to stop an author saying both.
1478
+ (key :name data :type write-buffer-source
1479
+ :description "Source: a (data …) ref, a (wasm-call …) whose result is written each frame, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pointer-inputs (48B)."))
1037
1480
 
1481
+ ; Both ends of a copy are dictionaries in the IDL
1482
+ ; (GPUTexelCopyTextureInfo / GPUCopyExternalImageSourceInfo), so they are
1483
+ ; child forms, and their members are that form's keys: `:mip-level` and
1484
+ ; `:origin` describe the DESTINATION subresource, not the copy. The flat
1485
+ ; `:source X :texture Y` spelling is retired rather than kept as a second one.
1486
+ ; Their heads are SLOT-LOCAL: `source` carries a texture under one copy
1487
+ ; and an image under the other, and neither is a global form.
1488
+ ;
1489
+ ; There is no `:size`: pngine copies the whole source, which is what both
1490
+ ; runtimes do today. A key the bytecode cannot carry would validate and be
1491
+ ; dropped in silence — the texture→texture opcode encodes the two texture
1492
+ ; ids and nothing else (`wire_schema` L_2V); the external-image opcode encodes
1493
+ ; the bitmap id, the texture id and the destination mip level + origin
1494
+ ; (L_COPY_EXT_IMG). Neither carries a size. It arrives when the opcode does.
1038
1495
  (form :name copy-texture-to-texture
1039
1496
  :description "Queue op: GPU texture→texture copy. context-current-texture names the canvas; otherwise a (texture …) name."
1040
- (key :name source :type attachment-view
1041
- :description "Source texture: context-current-texture or a (texture …) name.")
1042
- (key :name destination :type attachment-view
1043
- :description "Destination texture: context-current-texture or a (texture …) name."))
1497
+ :positional copy-endpoints-section
1498
+ (form :name source
1499
+ :description "Copy source (GPUTexelCopyTextureInfo)."
1500
+ (key :name texture :type attachment-view
1501
+ :description "Source texture: context-current-texture or a (texture …) name."))
1502
+ (form :name destination
1503
+ :description "Copy destination (GPUTexelCopyTextureInfo)."
1504
+ (key :name texture :type attachment-view
1505
+ :description "Destination texture: context-current-texture or a (texture …) name.")))
1044
1506
 
1045
1507
  (form :name copy-external-image-to-texture
1046
1508
  :description "Queue op: upload a decoded image (image-bitmap) into a texture. mip-level / origin default to 0 per the WebGPU spec."
1047
- (key :name source :type image-bitmap-ref
1048
- :description "The decoded (image-bitmap …) to upload.")
1049
- (key :name texture :type texture-ref
1050
- :description "Destination texture (needs copy-dst usage).")
1051
- (key :name mip-level :type byte-count :optional true
1052
- :description "Destination mip level (default 0).")
1053
- (key :name origin :type origin3 :optional true
1054
- :description "Destination origin [x y z] in texels (default [0 0 0]; z selects the array layer / depth slice)."))
1509
+ :positional copy-endpoints-section
1510
+ (form :name source
1511
+ :description "Copy source (GPUCopyExternalImageSourceInfo)."
1512
+ (key :name image :type image-bitmap-ref
1513
+ :description "The decoded (image-bitmap …) to upload."))
1514
+ (form :name destination
1515
+ :description "Copy destination (GPUCopyExternalImageDestInfo)."
1516
+ (key :name texture :type texture-ref
1517
+ :description "Destination texture (needs copy-dst usage).")
1518
+ (key :name mip-level :type subresource-index :optional true
1519
+ :description "Destination mip level (default 0).")
1520
+ (key :name origin :type origin3 :optional true
1521
+ :description "Destination origin [x y z] in texels (default [0 0 0]; z selects the array layer / depth slice).")))
1055
1522
 
1056
1523
  (form :name resolve-query-set
1057
1524
  :description "Queue op: copy resolved query results from a query set into a buffer (GPUCommandEncoder.resolveQuerySet)."
1058
1525
  (key :name query-set :type query-set-ref
1059
1526
  :description "The query set to resolve.")
1060
- (key :name first-query :type count :default 0
1527
+ (key :name first-query :type u32 :default 0
1061
1528
  :description "Index of the first query to resolve.")
1062
- (key :name query-count :type count
1529
+ (key :name query-count :type u32
1063
1530
  :description "Number of queries to resolve; each resolves to 8 bytes.")
1064
1531
  (key :name destination :type buffer-ref
1065
1532
  :description "Destination buffer; must have query-resolve usage.")
1066
- (key :name destination-offset :type byte-count :default 0
1533
+ (key :name destination-offset :type byte-count-256-aligned :default 0
1067
1534
  :description "Byte offset into the destination (WebGPU requires a multiple of 256)."))
1068
1535
 
1069
1536
  (form :name copy-buffer-to-buffer
1070
1537
  :description "Queue op: GPU buffer→buffer copy (e.g. resolved queries → a map-read readback buffer)."
1071
1538
  (key :name source :type buffer-ref
1072
1539
  :description "Source buffer (needs copy-src usage).")
1073
- (key :name source-offset :type byte-count :default 0
1540
+ (key :name source-offset :type byte-count-4-aligned :default 0
1074
1541
  :description "Byte offset into the source (multiple of 4).")
1075
1542
  (key :name destination :type buffer-ref
1076
1543
  :description "Destination buffer (needs copy-dst usage).")
1077
- (key :name destination-offset :type byte-count :default 0
1544
+ (key :name destination-offset :type byte-count-4-aligned :default 0
1078
1545
  :description "Byte offset into the destination (multiple of 4).")
1079
- (key :name size :type byte-count
1546
+ (key :name size :type byte-count-4-aligned
1080
1547
  :description "Bytes to copy (multiple of 4)."))
1081
1548
 
1082
- ; The legacy nests `module={ url=… }`; SJON flattens to `:url` (the `module`
1083
- ; head is taken by the pipeline stage sub-form).
1549
+ ; The legacy nests `module={ url=… }`; SJON flattens to `:file` — `url`
1550
+ ; promised fetching the descriptor never did, and the kind is `file-path`,
1551
+ ; "relative to the document".
1084
1552
  (form :name wasm-call
1085
- :description "A runtime WASM call: load the module at :url, call :func with :args each frame; a (write-buffer :data-from-wasm <name>) writes the result into a buffer."
1553
+ :description "A runtime WASM call: load the module at :file, call :func with :args each frame; a (write-buffer :data <name>) writes the result into a buffer."
1086
1554
  (key :name name :type symbol)
1087
- (key :name url :type file-path
1088
- :description "WASM file path relative to the source file (modules deduped by url).")
1555
+ (key :name file :type file-path
1556
+ :description "WASM file path relative to the source file (modules deduped by path).")
1089
1557
  (key :name func :type symbol
1090
1558
  :description "Exported function to call at frame time.")
1091
1559
  (key :name returns :type string
@@ -1095,30 +1563,32 @@
1095
1563
 
1096
1564
  (form :name bind-group
1097
1565
  :description "Bind group. `pool` + per-entry `ping-pong` drive ping-pong. The
1098
- layout is a pipeline's auto-layout (:layout-pipeline) OR an explicit
1099
- (bind-group-layout …) (:bind-group-layout); exactly one is required
1100
- (schema-enforced via the exclusive-group below)."
1566
+ layout is a pipeline's auto-layout or an explicit
1567
+ (bind-group-layout …) — one required :layout key naming either."
1101
1568
  :positional bind-entry-item
1102
1569
  (key :name name :type symbol)
1103
- (key :name layout-pipeline :type pipeline-ref :optional true
1104
- :description "The render- or compute-pipeline whose auto-layout this group targets.")
1105
- (key :name bind-group-layout :type bind-group-layout-ref :optional true
1106
- :description "An explicit (bind-group-layout …) this group targets instead of a pipeline's auto-layout.")
1107
- (key :name layout-index :type binding-index :default 0
1108
- :description "Which @group index of the pipeline layout this group binds (spec baseline < 4).")
1570
+ (key :name layout :type bind-group-layout-spec
1571
+ :description "The layout this group is built against: a pipeline (its auto-derived layout) or an explicit (bind-group-layout …).")
1572
+ ; `:group` is `@group(N)` in the WGSL — the word WebGPU and WGSL both use,
1573
+ ; and it pairs with the entries' `:binding` the way the shader spells them.
1574
+ ; It was `:layout-index`, which named the mechanism rather than the
1575
+ ; thing. Meaningful for the PIPELINE arm only: that arm resolves the layout
1576
+ ; as `pipeline.getBindGroupLayout(:group)`, while an explicit
1577
+ ; (bind-group-layout …) IS the layout and the index selects nothing. The
1578
+ ; emitter warns rather than rejects — the value is still encoded, so a
1579
+ ; document that states it keeps compiling byte-identically.
1580
+ (key :name group :type binding-index :default 0
1581
+ :description "Which @group index of the pipeline's layout this group binds (spec baseline < 4). Ignored when :layout names an explicit (bind-group-layout …).")
1109
1582
  (key :name pool :type pool-size :optional true
1110
1583
  :description "Create N sequential bind-group ids for ping-pong selection.")
1111
- ; Exactly one layout source — a pipeline's auto-layout XOR an explicit
1112
- ; (bind-group-layout …). Declarative replacement for the emit-time check.
1113
- (exclusive-group :cardinality exactly-one
1114
- (alt :keys [layout-pipeline])
1115
- (alt :keys [bind-group-layout]))
1116
- ; Slot-local (F8) entry form: `(entry :binding N :buffer|:sampler|:texture R)`.
1584
+ ; Slot-local entry form: `(entry :binding N :buffer|:sampler|:texture|:texture-view R)`.
1117
1585
  ; Resolved LOCAL-FIRST under bind-group, so this `entry` is distinct from the
1118
- ; global render-pipeline stage (entry …) form of the same head.
1586
+ ; bind-group-layout's entry. (A global `entry` stand-in used to sit above
1587
+ ; this form so `:lowering :produces` could name the head; SJON since 1.5 makes
1588
+ ; `:produces` resolve slot-local heads and the stand-in is gone.)
1119
1589
  (form :name entry
1120
- :description "One bind-group entry: binding → buffer | sampler | texture resource
1121
- (exactly one of :buffer/:sampler/:texture, schema-enforced)."
1590
+ :description "One bind-group entry: binding → buffer | sampler | texture | texture-view resource
1591
+ (exactly one of :buffer/:sampler/:texture/:texture-view, schema-enforced)."
1122
1592
  (key :name binding :type binding-index
1123
1593
  :description "Binding slot matching @binding(N) in the WGSL.")
1124
1594
  (key :name buffer :type buffer-ref :optional true
@@ -1129,9 +1599,11 @@
1129
1599
  :description "Bind a (texture …) at this slot via its default 2d view.")
1130
1600
  (key :name texture-view :type texture-view-ref :optional true
1131
1601
  :description "Bind an explicit (texture-view …) at this slot — for 1d/3d/array/cube sampling.")
1132
- (key :name offset :type byte-count :optional true
1602
+ ; `:requires [buffer]` (SJON 1.2.0): a slice on a sampler/texture entry is a
1603
+ ; located `dependent_key_missing` at validation, not an emitter reject.
1604
+ (key :name offset :type byte-count :optional true :requires [buffer]
1133
1605
  :description "GPUBufferBinding.offset — byte offset of the bound slice into :buffer (default 0; requires :buffer; must lie inside the declared buffer size — checked at compile time). Dynamic-offset alignment rules apply (uniform 256, storage 256 by default).")
1134
- (key :name size :type byte-count :optional true
1606
+ (key :name size :type byte-count :optional true :requires [buffer]
1135
1607
  :description "GPUBufferBinding.size — byte size of the bound slice (default: the rest of :buffer from :offset; requires :buffer; :offset + :size must fit the declared buffer size — checked at compile time).")
1136
1608
  (key :name ping-pong :type binding-index :optional true
1137
1609
  :description "Pool offset for this entry: actual id = base + (frame + offset) % pool.")
@@ -1142,31 +1614,14 @@
1142
1614
  (alt :keys [texture])
1143
1615
  (alt :keys [texture-view]))))
1144
1616
 
1145
- ; Head-resolution target for the `(bind-group-layout entry (storage-texture …))`
1146
- ; slot-local form below. WebGPU has no standalone storage-texture resource (a
1147
- ; storage texture is a (texture … :usage [storage-binding])); this global form
1148
- ; exists only so the `bgl-resource` head-set resolves `storage-texture` to a form,
1149
- ; exactly as `buffer`/`sampler`/`texture` resolve to their global resource forms.
1150
- ; It has no emitter phase — never walked at top level — so the real fields live in
1151
- ; the slot-local form; this one just satisfies the head lookup.
1152
- (form :name storage-texture
1153
- :description "Storage-texture layout resource (authored inside (bind-group-layout entry …), not at top level)."
1154
- (key :name name :type symbol :optional true)
1155
- (key :name format :type texture-format :optional true
1156
- :description "Texel format of the storage texture.")
1157
- (key :name access :type storage-texture-access :optional true
1158
- :description "Access mode (default write-only).")
1159
- (key :name view-dimension :type view-dimension :optional true
1160
- :description "View dimension (default 2d)."))
1161
-
1162
1617
  ; ---- explicit bind-group-layout (uniform_access) ----
1163
1618
  ; → create_bind_group_layout (opcode 0x06), emitted between samplers and
1164
1619
  ; pipelines (the legacy phase position). Buffer, sampler, texture, and storage-
1165
- ; texture bindings are modeled. Entries and their resource are SLOT-LOCAL forms
1166
- ; (F8): `(entry …)` and its nested `(buffer|sampler|texture|storage-texture …)`,
1620
+ ; texture bindings are modeled. Entries and their resource are SLOT-LOCAL
1621
+ ; forms: `(entry …)` and its nested `(buffer|sampler|texture|storage-texture …)`,
1167
1622
  ; resolved local-first so the natural names don't collide with the global forms.
1168
1623
  (form :name bind-group-layout
1169
- :description "Explicit binding layout (per-entry visibility + resource type) targeted by a (bind-group … :bind-group-layout …) instead of a pipeline's auto-layout."
1624
+ :description "Explicit binding layout (per-entry visibility + resource type) named by a (bind-group … :layout …) instead of a pipeline's auto-layout."
1170
1625
  :positional bgl-entry-item
1171
1626
  (key :name name :type symbol)
1172
1627
  (form :name entry
@@ -1176,13 +1631,13 @@
1176
1631
  :description "Binding slot matching @binding(N) in the WGSL.")
1177
1632
  (key :name visibility :type visibility-list
1178
1633
  :description "Shader stages that may access this binding (ORed into the WebGPU mask: vertex 0x1, fragment 0x2, compute 0x4).")
1179
- ; Nested slot-local (F8) resource form: `(buffer :type T)`. Resolved
1634
+ ; Nested slot-local resource form: `(buffer :type T)`. Resolved
1180
1635
  ; local-first under the layout entry, distinct from the global `buffer`.
1181
1636
  (form :name buffer
1182
1637
  :description "Buffer resource of a layout entry."
1183
- (key :name type :type buffer-binding-type
1184
- :description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage."))
1185
- ; Non-buffer resources (F8 slot-local, like buffer). Their WebGPU-shape sub-
1638
+ (key :name type :type buffer-binding-type :optional true
1639
+ :description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage (WebGPU default: uniform)."))
1640
+ ; Non-buffer resources (slot-local, like buffer). Their WebGPU-shape sub-
1186
1641
  ; objects flow verbatim through gpu.js/--html; native's create_bind_group_layout
1187
1642
  ; parser reads each field string-for-string.
1188
1643
  (form :name sampler
@@ -1194,7 +1649,7 @@
1194
1649
  (key :name sample-type :type texture-sample-type :optional true
1195
1650
  :description "Sample type of the bound texture (default float).")
1196
1651
  (key :name view-dimension :type view-dimension :optional true
1197
- :description "View dimension: 0=1d 1=2d 2=2d-array 3=cube 4=cube-array 5=3d (default 2d).")
1652
+ :description "View dimension: 1d, 2d, 2d-array, cube, cube-array or 3d (default 2d).")
1198
1653
  (key :name multisampled :type boolean :optional true
1199
1654
  :description "Whether the binding is a multisampled texture (default false)."))
1200
1655
  (form :name storage-texture
@@ -1209,24 +1664,24 @@
1209
1664
  ; ---- explicit pipeline-layout ----
1210
1665
  ; → create_pipeline_layout (opcode 0x07), emitted between bind-group-layouts and
1211
1666
  ; pipelines. Composes N (bind-group-layout …) into a GPUPipelineLayout that a
1212
- ; (render-pipeline …)/(compute-pipeline …) references via :pipeline-layout instead
1213
- ; of auto-deriving from the WGSL. This is the only way to bind @group 0..N to
1667
+ ; (render-pipeline …)/(compute-pipeline …) names in `:layout` instead of
1668
+ ; `auto` (deriving from the WGSL). This is the only way to bind @group 0..N to
1214
1669
  ; DIFFERENT explicit layouts (auto derives a single implicit layout per pipeline).
1215
1670
  (form :name pipeline-layout
1216
- :description "Explicit pipeline layout: an ordered list of (bind-group-layout …) at @group 0..N. Referenced by (render-pipeline … :pipeline-layout …)."
1671
+ :description "Explicit pipeline layout: an ordered list of (bind-group-layout …) at @group 0..N. Named by a pipeline's :layout key in place of auto."
1217
1672
  (key :name name :type symbol)
1218
1673
  (key :name bind-group-layouts :type bind-group-layout-ref-list
1219
1674
  :description "The (bind-group-layout …) forms at @group 0, 1, … in order."))
1220
1675
 
1221
1676
  (form :name sampler
1222
- :description "GPU sampler. PNGine defaults: filters linear, address-mode clamp-to-edge (WebGPU's own defaults are nearest)."
1677
+ :description "GPU sampler. Defaults match GPUSamplerDescriptor: filters nearest, address-mode clamp-to-edge."
1223
1678
  (key :name name :type symbol)
1224
- (key :name mag-filter :type filter-mode :default linear
1225
- :description "Magnification filter — sampling when one texel covers many pixels. PNGine default: linear (the WebGPU spec default is nearest).")
1226
- (key :name min-filter :type filter-mode :default linear
1227
- :description "Minification filter — sampling when many texels cover one pixel. PNGine default: linear (the WebGPU spec default is nearest).")
1679
+ (key :name mag-filter :type filter-mode :default nearest
1680
+ :description "Magnification filter — sampling when one texel covers many pixels. Default nearest, as GPUSamplerDescriptor.magFilter; write :mag-filter linear for smoothing.")
1681
+ (key :name min-filter :type filter-mode :default nearest
1682
+ :description "Minification filter — sampling when many texels cover one pixel. Default nearest, as GPUSamplerDescriptor.minFilter; write :min-filter linear for smoothing.")
1228
1683
  (key :name address-mode :type address-mode :optional true
1229
- :description "Addressing for texture coordinates outside [0,1], applied to all three axes (PNGine default: clamp-to-edge). Per-axis :address-mode-u/v/w override it.")
1684
+ :description "Addressing for texture coordinates outside [0,1], applied to all three axes. A PNGine shorthand for the IDL's three separate keys, and like them it defaults to clamp-to-edge. Per-axis :address-mode-u/v/w override it.")
1230
1685
  (key :name address-mode-u :type address-mode :optional true
1231
1686
  :description "Addressing for the U (S) axis; overrides :address-mode for this axis.")
1232
1687
  (key :name address-mode-v :type address-mode :optional true
@@ -1234,85 +1689,133 @@
1234
1689
  (key :name address-mode-w :type address-mode :optional true
1235
1690
  :description "Addressing for the W (R) axis; overrides :address-mode for this axis (3D / cube sampling).")
1236
1691
  (key :name mipmap-filter :type filter-mode :optional true
1237
- :description "Filter applied between mip levels (only visible with a mipmapped texture).")
1692
+ :description "Filter applied between mip levels (only visible with a mipmapped texture). Default nearest, as GPUSamplerDescriptor.mipmapFilter; :max-anisotropy above 1 requires linear here as well as on :mag-filter and :min-filter.")
1238
1693
  (key :name lod-min-clamp :type lod-clamp :optional true
1239
1694
  :description "Minimum mip level of detail the sampler will use (default 0).")
1240
1695
  (key :name lod-max-clamp :type lod-clamp :optional true
1241
1696
  :description "Maximum mip level of detail the sampler will use (default 32).")
1242
- (key :name max-anisotropy :type anisotropy-value :optional true
1697
+ (key :name max-anisotropy :type anisotropy :optional true
1243
1698
  :description "Maximum anisotropy for filtering; values > 1 require linear mag/min/mipmap filters.")
1244
1699
  (key :name compare :type compare-function :optional true
1245
1700
  :description "Comparison function — makes this a comparison sampler (e.g. depth shadow sampling)."))
1246
1701
 
1247
- ; pngine/pass-v1 now authors the canonical positional (vertex …)(fragment …) shape
1248
- ; (via EmittedForm positional children), so the render-pipeline descriptor has ONE
1249
- ; path. The legacy flat `:flat-module`/… keys were retired in §86 (post-cutover):
1250
- ; they emitted `"targetFormat":FMT` where the authored shape emits
1251
- ; `"targets":[{format…}]` — a difference that was load-bearing only against the
1252
- ; now-deleted `.pngine` parity baseline; the runtime (gpu.js) normalizes both.
1702
+ ; pngine/pass-v1 authors the canonical positional (vertex …)(fragment …) shape
1703
+ ; (via EmittedForm positional children), so the render-pipeline descriptor has
1704
+ ; one path.
1253
1705
  (form :name render-pipeline
1254
- :description "GPU render pipeline. Positional (layout …)(vertex …)(fragment …)(primitive …)(depth-stencil …)(multisample …) sections mirror GPURenderPipelineDescriptor."
1706
+ :description "GPU render pipeline. Positional (vertex …)(fragment …)(primitive …)(depth-stencil …)(multisample …) sections mirror GPURenderPipelineDescriptor."
1255
1707
  :positional pipeline-section
1256
1708
  (key :name name :type symbol)
1257
- (key :name pipeline-layout :type pipeline-layout-ref :optional true
1258
- :description "An explicit (pipeline-layout …) instead of auto-deriving the layout from the WGSL. Supersedes the (layout auto) positional when present."))
1709
+ ; GPUPipelineDescriptorBase.layout: required, and ONE member — see
1710
+ ; `pipeline-layout-spec`.
1711
+ (key :name layout :type pipeline-layout-spec
1712
+ :description "auto to derive the bind-group layouts from the WGSL, or a declared (pipeline-layout …)."))
1259
1713
 
1260
- ; compute-pipeline is flat (no positional sections) — natural, not a workaround:
1261
- ; a compute pipeline is just module + entry, with no vertex/fragment stages to
1262
- ; nest. The `pngine/init-v1` hook emits one; the flat kvpair shape is correct
1263
- ; as-is (the positional-slot limitation it once worked around was lifted in SJON
1264
- ; 2026-06, but compute-pipeline never needed positional children anyway).
1265
1714
  (form :name compute-pipeline
1266
- :description "GPU compute pipeline: a WGSL module + @compute entry point."
1715
+ :description "GPU compute pipeline: one positional (compute …) stage naming the WGSL module and its @compute entry point."
1716
+ :positional compute-pipeline-section
1267
1717
  (key :name name :type symbol)
1268
- (key :name module :type module-ref
1269
- :description "The (shader-module …) holding the @compute entry.")
1270
- (key :name entry :type entry-point :optional true
1271
- :description "Entry-point function name (defaults to the module's sole @compute fn).")
1272
- (key :name pipeline-layout :type pipeline-layout-ref :optional true
1273
- :description "An explicit (pipeline-layout …) instead of auto-deriving the layout from the WGSL."))
1718
+ (key :name layout :type pipeline-layout-spec
1719
+ :description "auto to derive the bind-group layouts from the WGSL, or a declared (pipeline-layout …)."))
1274
1720
 
1275
- ; ---- render-pipeline sub-forms (source-authored only) ----
1276
- (form :name layout
1277
- :description "Pipeline layout: auto derives bind-group layouts from the WGSL."
1278
- :positional layout-mode)
1721
+ ; ---- pipeline stage sub-forms (source-authored + hook-emitted) ----
1722
+ ; All three are GPUProgrammableStage: a required module, an optional entry
1723
+ ; point, and per-stage `(constant …)` overrides. `(module …)`/`(entry …)` were
1724
+ ; positional atom forms until this cut — a scalar member of a dictionary is a
1725
+ ; key, and spelling it as a form meant two global heads existed for no
1726
+ ; reason but the grammar.
1279
1727
  (form :name vertex
1280
- :description "Vertex stage: (module …)(entry …) and optional (buffers …) vertex-input layout."
1281
- :positional vertex-section)
1728
+ :description "Vertex stage (GPUVertexState): the module + entry point, one (vertex-buffer …) per bound vertex slot, and (constant …) overrides."
1729
+ :positional vertex-section
1730
+ (key :name module :type module-ref
1731
+ :description "The (shader-module …) holding the @vertex entry.")
1732
+ (key :name entry :type entry-point :optional true
1733
+ :description "Entry-point function name (defaults to the module's sole @vertex fn)."))
1282
1734
  (form :name fragment
1283
- :description "Fragment stage: (module …)(entry …) and the (targets …) color targets."
1284
- :positional fragment-section)
1735
+ :description "Fragment stage (GPUFragmentState): the module + entry point, one (target …) per color attachment, and (constant …) overrides."
1736
+ :positional fragment-section
1737
+ (key :name module :type module-ref
1738
+ :description "The (shader-module …) holding the @fragment entry.")
1739
+ (key :name entry :type entry-point :optional true
1740
+ :description "Entry-point function name (defaults to the module's sole @fragment fn)."))
1741
+ (form :name compute
1742
+ :description "Compute stage (GPUProgrammableStage): the module + @compute entry point of a (compute-pipeline …), and (constant …) overrides."
1743
+ :positional compute-section
1744
+ (key :name module :type module-ref
1745
+ :description "The (shader-module …) holding the @compute entry.")
1746
+ (key :name entry :type entry-point :optional true
1747
+ :description "Entry-point function name (defaults to the module's sole @compute fn)."))
1748
+ ; Authored per STAGE, mirroring WebGPU's GPUProgrammableStage.constants and
1749
+ ; the per-entry-point reflection — but RESOLVED per module, because pngine
1750
+ ; specialises the shader text at compile time instead of passing a constants
1751
+ ; dict to a runtime. Two stages that specialise one module differently are
1752
+ ; refused rather than silently duplicating the module.
1753
+ (form :name constant
1754
+ :description "Specialise a WGSL `override` with a compile-time value. The declaration becomes a `const` in the shipped shader, so the value participates in const-folding and dead-code elimination — an unused branch leaves the payload entirely."
1755
+ (key :name name :type override-name
1756
+ :description "The WGSL `override` identifier this value is for.")
1757
+ (key :name value :type override-number
1758
+ :description "The value. Must fit the override's declared WGSL type: a fractional value for a u32/i32 override, or anything but 0/1 for a bool, is rejected."))
1285
1759
  (form :name primitive
1286
- :description "Primitive assembly state: (topology …) plus cull / winding. Mirror the source: omit the whole form when unauthored."
1287
- :positional primitive-section
1760
+ :description "Primitive assembly state (GPUPrimitiveState). Mirror the source: omit the whole form when unauthored."
1761
+ ; `:default triangle-list` is REQUIRED here, and it is the one default in
1762
+ ; this file the emitter deliberately does not bake. A `(variant …)` needs a
1763
+ ; discriminant it can resolve — SJON answers `missing_discriminant_key` when
1764
+ ; the key is neither authored nor defaulted — while a default is MATERIALIZED
1765
+ ; into the effective view, which the defaults policy at the top of this file
1766
+ ; says the emitter bakes. Both hold: the schema defaults the key so the
1767
+ ; variant below resolves, and `appendPrimitive` emits `topology` only when
1768
+ ; `authorNode` says the author wrote it, so a document that omits it still
1769
+ ; ships no topology (measured: +27 bytes on the one corpus document that
1770
+ ; omits it). The value is WebGPU's own default, so the two readings agree —
1771
+ ; a list topology, which reads no strip index format.
1772
+ ;
1773
+ ; `:strip-index-format` is the conditional key `(variant …)` exists for, and
1774
+ ; SJON's manifest spec uses this exact rule as its worked example. It could
1775
+ ; not be written until SJON 1.5: WebGPU reads stripIndexFormat for TWO
1776
+ ; topologies (triangle-strip and line-strip) and a key belonged to one
1777
+ ; variant (`variant_key_collision`). `(variant :when [a b])` is that fix,
1778
+ ; so the rule is the schema's now and the emitter's
1779
+ ; `checkStripIndexFormat` is gone. Under a list topology the key does not
1780
+ ; exist: `unknown_key`, located, at validation.
1781
+ :discriminant topology
1782
+ (key :name topology :type primitive-topology :optional true :default triangle-list
1783
+ :description "How vertices assemble into primitives (WebGPU default: triangle-list). Selects whether :strip-index-format exists: WebGPU reads a strip index format only for triangle-strip and line-strip.")
1288
1784
  (key :name cull-mode :type cull-mode :optional true
1289
1785
  :description "Which faces are discarded (WebGPU default: none).")
1290
1786
  (key :name front-face :type front-face :optional true
1291
1787
  :description "Winding that counts as front-facing (WebGPU default: ccw).")
1292
- (key :name strip-index-format :type index-format :optional true
1293
- :description "Index byte-width (uint16/uint32) for indexed strip draws; WebGPU requires it only when draw-indexed uses a strip topology (triangle-strip/line-strip).")
1294
1788
  (key :name unclipped-depth :type boolean :optional true
1295
- :description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false)."))
1296
- ; Keys are optional + default-free: the emitter emits only authored keys
1297
- ; (mirrors the legacy property-by-property JSON build).
1789
+ :description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false).")
1790
+ (variant :when [triangle-strip line-strip]
1791
+ (key :name strip-index-format :type index-format :optional true
1792
+ :description "Index byte-width (uint16/uint32) for indexed strip draws. WebGPU reads it only under a strip topology, which is why it is declared here and is an unknown key anywhere else; it becomes REQUIRED once a (draw-indexed …) runs this pipeline (that half crosses pipeline and pass, so it stays the emitter's).")))
1793
+ ; The emitter emits only authored keys (mirroring the legacy
1794
+ ; property-by-property JSON build), but "optional + default-free" is NOT the
1795
+ ; rule this form follows any more: `:format` is required, and
1796
+ ; `:depth-write-enabled` / `:depth-compare` become required from the format's
1797
+ ; aspects, which only the emitter can see.
1298
1798
  (form :name depth-stencil
1299
1799
  :description "Depth/stencil pipeline state. Positional (stencil-front …)/(stencil-back …) carry per-face stencil state."
1300
1800
  :positional depth-stencil-section
1301
- (key :name format :type texture-format :optional true
1302
- :description "Format of the depth/stencil attachment this pipeline renders to.")
1801
+ ; REQUIRED, matching GPUDepthStencilState.format. Every other key here is
1802
+ ; genuinely optional; this one only looked optional because the form was
1803
+ ; built "optional + default-free by construction" without checking the IDL.
1804
+ (key :name format :type texture-format
1805
+ :description "Format of the depth/stencil attachment this pipeline renders to; a depth or stencil format, never a colour one.")
1303
1806
  (key :name depth-write-enabled :type boolean :optional true
1304
- :description "Whether fragments write their depth value.")
1807
+ :description "Whether fragments write their depth value. Required once :format has a depth aspect (the IDL gives it no default); optional only because a stencil-only pipeline omits it.")
1305
1808
  (key :name depth-compare :type compare-function :optional true
1306
- :description "Comparison the depth test applies (fragment depth vs stored depth).")
1307
- (key :name depth-bias :type depth-bias-value :optional true
1809
+ :description "Comparison the depth test applies (fragment depth vs stored depth). Required once the pipeline writes depth, or a stencil face states a :depth-fail-op other than keep.")
1810
+ (key :name depth-bias :type depth-bias-int :optional true
1308
1811
  :description "Constant bias added to fragment depth — shadow maps / depth pre-pass (triangles only).")
1309
- (key :name depth-bias-slope-scale :type depth-bias-value :optional true
1812
+ (key :name depth-bias-slope-scale :type depth-bias :optional true
1310
1813
  :description "Bias that scales with the triangle's depth slope (triangles only).")
1311
- (key :name depth-bias-clamp :type depth-bias-value :optional true
1814
+ (key :name depth-bias-clamp :type depth-bias :optional true
1312
1815
  :description "Maximum magnitude of the total depth bias (0 = unclamped).")
1313
- (key :name stencil-read-mask :type byte-count :optional true
1816
+ (key :name stencil-read-mask :type mask32 :optional true
1314
1817
  :description "Bitmask ANDed with stencil values for tests (spec default 0xFFFFFFFF).")
1315
- (key :name stencil-write-mask :type byte-count :optional true
1818
+ (key :name stencil-write-mask :type mask32 :optional true
1316
1819
  :description "Bitmask ANDed with stencil writes (spec default 0xFFFFFFFF)."))
1317
1820
  ; Same key set for front/back; the head selects which face the emitter writes.
1318
1821
  (form :name stencil-front
@@ -1337,28 +1840,16 @@
1337
1840
  :description "Applied when both stencil and depth tests pass."))
1338
1841
  (form :name multisample
1339
1842
  :description "Multisample pipeline state (MSAA)."
1340
- (key :name count :type count-value
1341
- :description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count.")
1342
- (key :name mask :type count-value :optional true
1843
+ (key :name count :type u32 :optional true
1844
+ :description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count. Absent defers to WebGPU's 1 — a (multisample …) carrying only :mask or :alpha-to-coverage-enabled is legal.")
1845
+ (key :name mask :type mask32 :optional true
1343
1846
  :description "Sample coverage bitmask (spec default 0xFFFFFFFF).")
1344
1847
  (key :name alpha-to-coverage-enabled :type boolean :optional true
1345
- :description "Fragment alpha generates the coverage mask (requires count > 1)."))
1346
- (form :name module
1347
- :description "The (shader-module …) this stage executes."
1348
- :positional module-ref)
1349
- (form :name entry
1350
- :description "Entry-point function name within the stage's module."
1351
- :positional entry-point)
1352
- (form :name topology
1353
- :description "How vertices assemble into primitives (WebGPU default: triangle-list)."
1354
- :positional primitive-topology)
1355
- (form :name buffers
1356
- :description "Vertex input layout: one (vertex-buffer …) per bound vertex buffer slot."
1357
- :positional buffers-item)
1848
+ :description "Fragment alpha generates the coverage mask. Requires :count above 1, a (fragment …) stage, and a first (target …) whose format has an alpha channel to derive the mask from."))
1358
1849
  (form :name vertex-buffer
1359
1850
  :description "Layout of one vertex buffer slot: stride + step mode + (attribute …) children."
1360
1851
  :positional attribute-item
1361
- (key :name array-stride :type byte-count
1852
+ (key :name array-stride :type byte-count-4-aligned
1362
1853
  :description "Bytes between consecutive elements; multiple of 4 (spec baseline limit 2048).")
1363
1854
  (key :name step-mode :type step-mode :optional true
1364
1855
  :description "Advance per vertex or per instance (WebGPU default: vertex)."))
@@ -1370,9 +1861,6 @@
1370
1861
  :description "Byte offset of the attribute within one element.")
1371
1862
  (key :name format :type vertex-format
1372
1863
  :description "Wire format of the attribute data."))
1373
- (form :name targets
1374
- :description "Color targets of the fragment stage: one (target …) per attachment."
1375
- :positional targets-item)
1376
1864
  (form :name target
1377
1865
  :description "One color target: format plus optional (blend …) state and write mask."
1378
1866
  :positional target-section
@@ -1381,32 +1869,32 @@
1381
1869
  (key :name write-mask :type write-mask :optional true
1382
1870
  :description "Channel write mask: bitmask R=1 G=2 B=4 A=8, or all (15; the WebGPU default)."))
1383
1871
  (form :name blend
1384
- :description "Blend state of a color target: (color …) and (alpha …) components."
1872
+ :description "Blend state of a color target: (color …) and (alpha …) components. Only on a blendable target format — never a uint or sint one."
1385
1873
  :positional blend-section)
1386
1874
  (form :name color
1387
1875
  :description "Blend component for RGB: out.rgb = operation(src.rgb * src-factor, dst.rgb * dst-factor)."
1388
- (key :name src-factor :type blend-factor
1389
- :description "Multiplier on the fragment's color (WebGPU default: one).")
1390
- (key :name dst-factor :type blend-factor
1391
- :description "Multiplier on the attachment's color (WebGPU default: zero).")
1876
+ (key :name src-factor :type blend-factor :optional true
1877
+ :description "Multiplier on the fragment's color (WebGPU default: one). Emitted only when authored.")
1878
+ (key :name dst-factor :type blend-factor :optional true
1879
+ :description "Multiplier on the attachment's color (WebGPU default: zero). Emitted only when authored.")
1392
1880
  (key :name operation :type blend-operation :optional true
1393
1881
  :description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
1394
1882
  (form :name alpha
1395
1883
  :description "Blend component for alpha: out.a = operation(src.a * src-factor, dst.a * dst-factor)."
1396
- (key :name src-factor :type blend-factor
1397
- :description "Multiplier on the fragment's alpha (WebGPU default: one).")
1398
- (key :name dst-factor :type blend-factor
1399
- :description "Multiplier on the attachment's alpha (WebGPU default: zero).")
1884
+ (key :name src-factor :type blend-factor :optional true
1885
+ :description "Multiplier on the fragment's alpha (WebGPU default: one). Emitted only when authored.")
1886
+ (key :name dst-factor :type blend-factor :optional true
1887
+ :description "Multiplier on the attachment's alpha (WebGPU default: zero). Emitted only when authored.")
1400
1888
  (key :name operation :type blend-operation :optional true
1401
1889
  :description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
1402
1890
 
1403
1891
  ; ---- render / compute pass ----
1404
1892
  (form :name render-pass
1405
- :description "GPU render pass: (color-attachment …)/(depth-attachment …) targets, a pipeline, bound resources, and (draw …)/(draw-indexed …) calls."
1893
+ :description "GPU render pass: (color-attachment …)/(depth-stencil-attachment …) targets, a pipeline, bound resources, and its commands — the four draws (draw / draw-indexed / draw-indirect / draw-indexed-indirect), (occlusion-query …) brackets and one (timestamp-writes …). At least one attachment, of either kind — a pass writes somewhere."
1406
1894
  :positional render-pass-section
1407
1895
  (key :name name :type symbol)
1408
1896
  (key :name occlusion-query-set :type query-set-ref :optional true
1409
- :description "The (query-set :type occlusion) that (occlusion-query …) brackets in this pass write into.")
1897
+ :description "The (query-set :type occlusion) that (occlusion-query …) brackets in this pass write into. Required once the pass holds a bracket; optional only because a pass may hold none.")
1410
1898
  (key :name pipeline :type render-pipeline-ref :optional true
1411
1899
  :description "The render pipeline this pass draws with. Omit for a pass that only replays :execute-bundles (the bundle records it).")
1412
1900
  (key :name vertex-buffers :type buffer-ref-list :optional true
@@ -1419,7 +1907,7 @@
1419
1907
  :description "Bind groups set at @group 0..N in order.")
1420
1908
  (key :name bind-groups-pool-offsets :type offset-list :optional true
1421
1909
  :description "Per-group ping-pong offsets into each group's pool.")
1422
- (key :name stencil-reference :type count :optional true
1910
+ (key :name stencil-reference :type u32 :optional true
1423
1911
  :description "Reference value used by stencil compare and the replace operation.")
1424
1912
  (key :name blend-constant :type blend-constant-color :optional true
1425
1913
  :description "[r g b a] blend constant (setBlendConstant); the value the `constant`/`one-minus-constant` blend factors multiply by. Defaults to [0 0 0 0] when unset.")
@@ -1428,8 +1916,17 @@
1428
1916
  (key :name scissor-rect :type pixel-rect :optional true
1429
1917
  :description "[x y w h] in integer pixels; fragments outside are discarded.")
1430
1918
  (key :name execute-bundles :type render-bundle-ref-list :optional true
1431
- :description "Replay pre-recorded (render-bundle …) forms instead of an inline pipeline/draw."))
1919
+ :description "Replay pre-recorded (render-bundle …) forms instead of an inline pipeline/draw. Each bundle's declared color formats, depth/stencil format and sample count must equal this pass's, which WebGPU derives from its attachments' textures."))
1432
1920
 
1921
+ ; NOT `:discriminant load-op`, though `:clear-value` is exactly the
1922
+ ; conditional key `(variant …)` is for (WebGPU IGNORES a clearValue
1923
+ ; beside `load`, so a document that states one is stating something inert).
1924
+ ; SJON's variant rule is positional — the discriminant kvpair must be written
1925
+ ; BEFORE any variant-only key, in both walkers — and the corpus spells
1926
+ ; `:clear-value [0 0 0 1] :load-op clear` in all 234 of its colour
1927
+ ; attachments. Adopting the variant means a key-ORDER rule inside a form,
1928
+ ; which is not something WebGPU has and not something a 1:1 mapping should
1929
+ ; invent; the check is the emitter's instead, with the same span.
1433
1930
  (form :name color-attachment
1434
1931
  :description "One color target of a render pass."
1435
1932
  (key :name view :type attachment-view
@@ -1437,30 +1934,53 @@
1437
1934
  (key :name resolve-target :type attachment-view :optional true
1438
1935
  :description "Receives the resolved single-sample output when :view is multisampled.")
1439
1936
  (key :name clear-value :type clear-color :optional true
1440
- :description "RGBA the attachment is cleared to when load-op is clear (ignored for load).")
1441
- (key :name load-op :type load-op :default clear
1937
+ :description "RGBA the attachment is cleared to when load-op is clear (WebGPU default: transparent black). Stating one beside `:load-op load` is an error — WebGPU would ignore it.")
1938
+ ; REQUIRED, matching GPURenderPassColorAttachment.loadOp/storeOp. WebGPU has
1939
+ ; no default for either: a pass that does not say whether it clears or loads
1940
+ ; is a pass whose contents depend on what happened to be in the texture, and
1941
+ ; the spec makes the author decide. PNGine defaulted them to clear/store,
1942
+ ; which is right often enough that the one time it is wrong reads as a
1943
+ ; rendering bug.
1944
+ (key :name load-op :type load-op
1442
1945
  :description "clear to :clear-value, or load the existing contents.")
1443
- (key :name store-op :type store-op :default store
1946
+ (key :name store-op :type store-op
1444
1947
  :description "store the pass result, or discard it."))
1445
1948
 
1446
1949
  ; Non-default load/store ops emit a preceding set_pass_depth_stencil_ops
1447
1950
  ; (matches the legacy path).
1448
- (form :name depth-attachment
1951
+ ; `depthStencilAttachment` is the IDL's word, and the form has carried
1952
+ ; stencil keys since it was written — `depth-attachment` named half of it.
1953
+ ; `:depth-load-op` / `:depth-store-op` no longer carry PNGine defaults
1954
+ ; (clear/store) — that half stands. Making them
1955
+ ; unconditionally REQUIRED, as the first cut did, was wrong in the other
1956
+ ; direction: WebGPU requires the depth pair only when the VIEW's format has a
1957
+ ; depth aspect, and FORBIDS it otherwise, so a `stencil8` attachment became
1958
+ ; unwritable. The requirement is conditional on a format the schema cannot
1959
+ ; reach, so it is the emitter's, in both directions and for both aspects.
1960
+ ;
1961
+ ; `:depth-clear-value` is the emitter's, for the same positional reason the colour
1962
+ ; attachment records: GPURenderPassDepthStencilAttachment gives
1963
+ ; depthClearValue no default at all, so a `clear` without one baked a PNGine
1964
+ ; 1.0 — the single number in a depth pass that decides whether anything is
1965
+ ; visible. Required-when-clearing needs a `(variant :when clear …)`, which
1966
+ ; needs `:depth-load-op` written before `:depth-clear-value` in every
1967
+ ; document. The emitter says it instead, with a span on the attachment.
1968
+ (form :name depth-stencil-attachment
1449
1969
  :description "Depth/stencil target of a render pass."
1450
1970
  (key :name view :type texture-ref
1451
1971
  :description "The depth/stencil (texture …) this pass tests/writes against.")
1452
1972
  (key :name depth-clear-value :type unorm :optional true
1453
- :description "Depth cleared to when depth-load-op is clear; must be in [0,1].")
1454
- (key :name depth-load-op :type load-op :default clear
1455
- :description "clear depth to :depth-clear-value, or load the existing depth.")
1456
- (key :name depth-store-op :type store-op :default store
1457
- :description "store the resulting depth, or discard it.")
1458
- (key :name stencil-clear-value :type byte-count :optional true
1973
+ :description "Depth cleared to when depth-load-op is clear, in [0,1]. Required when it clears — WebGPU has no default for it — and rejected beside `:depth-load-op load`.")
1974
+ (key :name depth-load-op :type load-op :optional true
1975
+ :description "clear depth to :depth-clear-value, or load the existing depth. Required when the view's format has a depth aspect, and rejected when it has none.")
1976
+ (key :name depth-store-op :type store-op :optional true
1977
+ :description "store the resulting depth, or discard it. Required when the view's format has a depth aspect, and rejected when it has none.")
1978
+ (key :name stencil-clear-value :type u32 :optional true
1459
1979
  :description "Stencil cleared to when stencil-load-op is clear.")
1460
1980
  (key :name stencil-load-op :type load-op :optional true
1461
- :description "clear stencil to :stencil-clear-value, or load the existing stencil.")
1981
+ :description "clear stencil to :stencil-clear-value, or load the existing stencil. Required when the view's format has a stencil aspect, and rejected when it has none.")
1462
1982
  (key :name stencil-store-op :type store-op :optional true
1463
- :description "store the resulting stencil, or discard it."))
1983
+ :description "store the resulting stencil, or discard it. Required when the view's format has a stencil aspect, and rejected when it has none."))
1464
1984
 
1465
1985
  (form :name draw
1466
1986
  :description "Non-indexed draw call."
@@ -1482,7 +2002,7 @@
1482
2002
  (key :name first-index :type count :default 0
1483
2003
  :description "Offset into the index buffer, in indices.")
1484
2004
  (key :name base-vertex :type count :default 0
1485
- :description "Added to each index before vertex lookup (signed in WebGPU).")
2005
+ :description "Added to each index before vertex lookup. Signed in WebGPU; pngine carries a u32 and rejects a negative value.")
1486
2006
  (key :name first-instance :type count :default 0
1487
2007
  :description "First instance index."))
1488
2008
 
@@ -1490,73 +2010,95 @@
1490
2010
  :description "Non-indexed indirect draw: the GPUDrawIndirectArgs (4×u32: vertex-count, instance-count, first-vertex, first-instance) are read from :buffer at :offset, typically written by a compute pass. No index buffer needed."
1491
2011
  (key :name buffer :type buffer-ref
1492
2012
  :description "Buffer holding the indirect args (needs indirect usage).")
1493
- (key :name offset :type byte-count :default 0
1494
- :description "Byte offset of the args within :buffer."))
2013
+ (key :name offset :type byte-count-4-aligned :default 0
2014
+ :description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
1495
2015
 
1496
2016
  (form :name draw-indexed-indirect
1497
2017
  :description "Indexed indirect draw: the GPUDrawIndexedIndirectArgs (5×u32) are read from :buffer at :offset, typically written by a compute pass. Requires the pass's :index-buffer."
1498
2018
  (key :name buffer :type buffer-ref
1499
2019
  :description "Buffer holding the indirect args (needs indirect usage).")
1500
- (key :name offset :type byte-count :default 0
1501
- :description "Byte offset of the args within :buffer."))
2020
+ (key :name offset :type byte-count-4-aligned :default 0
2021
+ :description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
1502
2022
 
1503
2023
  ; Emitted as a pre-pass set_pass_timestamp_writes (before begin_render_pass).
2024
+ ; GPURenderPassTimestampWrites, keys spelled as the IDL spells them. The
2025
+ ; two indices are baked (`:default 0` / `:default 1`) where the IDL
2026
+ ; leaves them optional with NO default — "write only the end" is not
2027
+ ; expressible because the opcode carries two u32s and no absent marker. A
2028
+ ; PNGine opinion, ledgered in the conformance harness; the absent-index
2029
+ ; capability and the compute-pass timestamp-writes the IDL also has are not
2030
+ ; expressible here yet.
1504
2031
  (form :name timestamp-writes
1505
2032
  :description "Record GPU timestamps at pass start/end into a (query-set :type timestamp)."
1506
2033
  (key :name query-set :type query-set-ref
1507
2034
  :description "The timestamp query set written into.")
1508
- (key :name begin :type count :default 0
1509
- :description "Query index written at pass start.")
1510
- (key :name end :type count :default 1
1511
- :description "Query index written at pass end."))
2035
+ (key :name beginning-of-pass-write-index :type u32 :default 0
2036
+ :description "Query index written at pass start (PNGine bakes 0; the IDL leaves it absent = not written).")
2037
+ (key :name end-of-pass-write-index :type u32 :default 1
2038
+ :description "Query index written at pass end (PNGine bakes 1; the IDL leaves it absent = not written)."))
1512
2039
 
1513
2040
  (form :name occlusion-query
1514
2041
  :description "Bracket one or more draws in an occlusion query: the GPU counts samples passing depth/stencil into the pass's :occlusion-query-set at :query-index."
1515
2042
  :positional occlusion-draw-item
1516
- (key :name query-index :type count :default 0
2043
+ (key :name query-index :type u32 :default 0
1517
2044
  :description "Index within the pass's occlusion query set."))
1518
2045
 
2046
+ ; A dispatch is a COMMAND, and commands are forms — the same shape the
2047
+ ; render pass has used for `(draw …)` all along. It was three keys with a
2048
+ ; precedence rule between them (`:dispatch-indirect` beat `:dispatch` beat
2049
+ ; `:dispatch-workgroups`), which is what a writer had to know to read a pass
2050
+ ; that stated two. Several dispatches per pass are legal WebGPU and now
2051
+ ; expressible; a pass with none is not a pass, which is the head-set's
2052
+ ; `:min-children 1` — a pngine opinion, not an IDL rule.
1519
2053
  (form :name compute-pass
1520
- :description "GPU compute pass: a compute pipeline + bind groups + one dispatch."
2054
+ :description "GPU compute pass: a compute pipeline + bind groups + one or more (dispatch …) commands."
2055
+ :positional compute-pass-command
1521
2056
  (key :name name :type symbol)
1522
2057
  (key :name pipeline :type compute-pipeline-ref
1523
2058
  :description "The compute pipeline this pass dispatches.")
1524
2059
  (key :name bind-groups :type bind-group-ref-list :optional true
1525
2060
  :description "Bind groups set at @group 0..N in order.")
1526
2061
  (key :name bind-groups-pool-offsets :type offset-list :optional true
1527
- :description "Per-group ping-pong offsets into each group's pool.")
1528
- (key :name dispatch-workgroups :type count :optional true
1529
- :description "1D dispatch: N workgroups → dispatch(N,1,1). Accepts expressions like (ceil (/ NUM 64)).")
1530
- (key :name dispatch :type dispatch-size :optional true
1531
- :description "3D dispatch [x y z] in workgroups.")
1532
- (key :name dispatch-indirect :type buffer-ref :optional true
1533
- :description "Indirect dispatch: the workgroup counts (3×u32) are read from this buffer at :dispatch-indirect-offset, typically written by an earlier compute pass. Takes precedence over :dispatch / :dispatch-workgroups.")
1534
- (key :name dispatch-indirect-offset :type byte-count :default 0
1535
- :description "Byte offset of the dispatch args within :dispatch-indirect."))
2062
+ :description "Per-group ping-pong offsets into each group's pool."))
2063
+
2064
+ (form :name dispatch
2065
+ :description "Compute dispatch command (GPUComputePassEncoder.dispatchWorkgroups)."
2066
+ (key :name workgroups :type dispatch-size
2067
+ :description "Workgroup counts as [x], [x y] or [x y z]; the missing dimensions default to 1. Each element is a literal, an expression like (ceil (/ NUM 64)), or a bare (define …) name."))
1536
2068
 
2069
+ (form :name dispatch-indirect
2070
+ :description "Indirect compute dispatch: the workgroup counts (3×u32) are read from :buffer at :offset, typically written by an earlier compute pass."
2071
+ (key :name buffer :type buffer-ref
2072
+ :description "Buffer holding the dispatch args (needs indirect usage).")
2073
+ (key :name offset :type byte-count-4-aligned :default 0
2074
+ :description "Byte offset of the args within :buffer (a multiple of 4, as WebGPU requires of indirectOffset)."))
2075
+
2076
+ ; The recorded draw is a `(draw …)` / `(draw-indexed …)` CHILD — the same two
2077
+ ; forms a render pass issues, with the same keys. It was `:draw N`
2078
+ ; beside `:instance-count M`, a third spelling of a draw that could not say
2079
+ ; `:first-vertex`, and `:draw-indexed N` which could say nothing else at all.
1537
2080
  (form :name render-bundle
1538
- :description "Pre-recorded reusable draw sequence (pipeline + buffers + bind groups + one draw), replayed via a render-pass's :execute-bundles."
2081
+ :description "Pre-recorded reusable draw sequence (pipeline + buffers + bind groups + one (draw …)), replayed via a render-pass's :execute-bundles."
2082
+ :positional render-bundle-command
1539
2083
  (key :name name :type symbol)
1540
- (key :name pipeline :type render-pipeline-ref :optional true
1541
- :description "Pipeline recorded into the bundle (the executing pass omits its own).")
1542
- (key :name color-formats :type texture-format-list :optional true
1543
- :description "Color attachment formats the bundle is recorded against (must match the executing pass).")
2084
+ (key :name pipeline :type render-pipeline-ref
2085
+ :description "Pipeline recorded into the bundle (the executing pass omits its own). Required: a bundle's descriptor is its own layout, and a draw with no pipeline is invalid WebGPU.")
2086
+ ; REQUIRED, matching GPURenderPassLayout.colorFormats. A bundle is validated
2087
+ ; against the layout it declares, so an unstated list is not a shorthand —
2088
+ ; it is a claim the runtime has to invent, and every runtime invented the
2089
+ ; canvas format.
2090
+ (key :name color-formats :type texture-format-list
2091
+ :description "Color attachment formats the bundle is recorded against. Each must be a color format, and the list must equal both the :pipeline's color targets and the replaying pass's color attachments.")
1544
2092
  (key :name depth-stencil-format :type texture-format :optional true
1545
- :description "Depth/stencil format the bundle is recorded against.")
1546
- (key :name sample-count :type count :optional true
1547
- :description "Sample count the bundle is recorded against.")
2093
+ :description "Depth/stencil format the bundle is recorded against. Must be a depth or stencil format, and must be present exactly when the :pipeline declares a (depth-stencil …) and the replaying pass has a (depth-stencil-attachment …).")
2094
+ (key :name sample-count :type u32 :optional true
2095
+ :description "Sample count the bundle is recorded against (default 1). Must equal the :pipeline's (multisample :count …) and the sample count of the replaying pass's attachment textures.")
1548
2096
  (key :name vertex-buffers :type buffer-ref-list :optional true
1549
2097
  :description "Buffers bound to vertex slots 0..N in order.")
1550
2098
  (key :name bind-groups :type bind-group-ref-list :optional true
1551
2099
  :description "Bind groups set at @group 0..N in order.")
1552
2100
  (key :name index-buffer :type buffer-ref :optional true
1553
- :description "Index buffer when the bundle draws indexed.")
1554
- (key :name draw :type count :optional true
1555
- :description "Record a non-indexed draw of this many vertices.")
1556
- (key :name draw-indexed :type count :optional true
1557
- :description "Record an indexed draw of this many indices.")
1558
- (key :name instance-count :type count :optional true
1559
- :description "Instances for the recorded :draw."))
2101
+ :description "Index buffer when the bundle draws indexed."))
1560
2102
 
1561
2103
  (form :name frame
1562
2104
  :description "Frame program: what runs each frame, in order."
@@ -1571,18 +2113,24 @@
1571
2113
  ; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
1572
2114
  (form :name init
1573
2115
  :description "One-shot compute init of a storage buffer (first frame only)."
2116
+ ; `entry` here is the bind-group's SLOT-LOCAL entry, and it resolves through
2117
+ ; the dummy global `(entry …)` form declared beside bind-group — see the
2118
+ ; comment there. It used to resolve through the render-pipeline stage's
2119
+ ; `(entry …)`, by accident.
1574
2120
  :lowering (lowering :hook pngine/init-v1
1575
- :produces [compute-pipeline bind-group entry compute-pass])
2121
+ :produces [compute-pipeline compute bind-group entry compute-pass dispatch])
1576
2122
  (key :name name :type symbol)
1577
2123
  (key :name buffer :type buffer-ref
1578
2124
  :description "The storage buffer the init compute writes (bound at @binding 0).")
1579
- (key :name shader :type module-ref
2125
+ (key :name module :type module-ref
1580
2126
  :description "The (shader-module …) holding the @compute init entry.")
1581
- (key :name workgroups :type count
1582
- :description "Workgroup count. Read at lowering time through the lowering env: a literal or a bounded expression over (define …) constants, e.g. (ceil (/ NUM 64))."))
2127
+ ; Same shape as the `(dispatch :workgroups …)` this lowers to. Sugar is
2128
+ ; spelled like what it expands into, so a change binds both or neither.
2129
+ (key :name workgroups :type dispatch-size
2130
+ :description "Workgroup counts as [x], [x y] or [x y z]. Read at lowering time through the lowering env: literals, bounded expressions over (define …) constants, e.g. [(ceil (/ NUM 64))], or a bare (define …) name."))
1583
2131
 
1584
2132
  ; =====================================================================
1585
- ; #pass sugar — container-lowered by pngine/pass-v1 (Phase 2f)
2133
+ ; `(pass …)` sugar — container-lowered by pngine/pass-v1 (Phase 2f)
1586
2134
  ; =====================================================================
1587
2135
  ; The author writes (pass-graph (pass …) …). The hook sees every pass through
1588
2136
  ; the whole-document view, sequences cross-pass texture ids, and emits canonical
@@ -1594,17 +2142,17 @@
1594
2142
  (value-kind :name pass-item :underlying form :heads (head-set :names [pass]))
1595
2143
 
1596
2144
  (form :name pass
1597
- :description "One #pass: a fullscreen fragment (or compute) shader-art stage.
2145
+ :description "One `(pass …)`: a fullscreen fragment (or compute) shader-art stage.
1598
2146
  The hook detects features from the WGSL (pngine/pointer/feedback)."
1599
2147
  (key :name name :type symbol)
1600
- (key :name code :type string :optional true
1601
- :description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers).")
2148
+ (key :name code :type string
2149
+ :description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers). Required — the hook always refused its absence.")
1602
2150
  (key :name feedback :type boolean :optional true
1603
2151
  :description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
1604
2152
  (key :name init :type string :optional true
1605
2153
  :description "One-shot WGSL compute source run on the first frame only.")
1606
- (key :name data :type data-file-list :optional true
1607
- :description "WASM file paths → D0, D1, … storage buffers; the hook injects var<storage, read> D{i}: array<f32>."))
2154
+ (key :name file :type data-file-list :optional true
2155
+ :description "WASM file paths (relative to the document) → D0, D1, … storage buffers; the hook injects var<storage, read> D{i}: array<f32>. The same :file every other file-on-disk key spells."))
1608
2156
 
1609
2157
  (form :name pass-graph
1610
2158
  :description "Container of (pass …) children lowered as a unit so resource ids
@@ -1612,7 +2160,7 @@
1612
2160
  :open true
1613
2161
  :positional pass-item
1614
2162
  :lowering (lowering :hook pngine/pass-v1
1615
- :produces [shader-module buffer texture sampler bind-group
1616
- render-pipeline vertex fragment module entry targets target
2163
+ :produces [shader-module buffer texture sampler bind-group entry
2164
+ render-pipeline vertex fragment target
1617
2165
  render-pass color-attachment draw frame
1618
- compute-pipeline compute-pass queue write-buffer])))
2166
+ compute-pipeline compute compute-pass dispatch queue write-buffer])))