pngine 2.2.0 → 3.0.1

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,31 +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.
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.)
29
34
  (plugin :name pngine :version "0.1.0"
30
35
 
31
36
  ; ---- numeric refinements ----
@@ -38,13 +43,65 @@
38
43
  ; silently wraps it, and SJON's exporter emits the branded `U32` TS alias so the
39
44
  ; editor gets real per-field GPU types. Repr checks literals only — expressions
40
45
  ; (`:size (* NUM 4 4)`) and define-refs are evaluated later, untouched here.
41
- (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
42
72
  :description "Non-negative integer byte size / offset / stride."
43
73
  :underlying number
44
74
  :numeric (numeric-bounds :min 0 :integer true)
45
75
  :unit (unit-shape :reject true)
46
76
  :repr (repr-shape :type u32))
47
- (value-kind :name pool-size
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."
86
+ :underlying number
87
+ :numeric (numeric-bounds :min 0 :integer true :multiple-of 4)
88
+ :unit (unit-shape :reject true)
89
+ :repr (repr-shape :type u32))
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
48
105
  :description "Ping-pong pool size (1..255). The ceiling is the wire's: the
49
106
  pool index is a byte everywhere it is encoded, so a larger pool
50
107
  cannot be addressed. Bounds a LITERAL; the emitter re-checks the
@@ -53,24 +110,99 @@
53
110
  :numeric (numeric-bounds :min 1 :max 255 :integer true)
54
111
  :unit (unit-shape :reject true)
55
112
  :repr (repr-shape :type u32))
56
- (value-kind :name binding-index
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
57
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)."
58
119
  :underlying number
59
120
  :numeric (numeric-bounds :min 0 :max 255 :integer true)
60
121
  :unit (unit-shape :reject true)
61
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))
62
127
  (value-kind :name count-value
63
128
  :description "Non-negative integer draw / dispatch count (literals + expressions)."
64
129
  :underlying number
65
130
  :numeric (numeric-bounds :min 0 :integer true)
66
131
  :unit (unit-shape :reject true)
67
132
  :repr (repr-shape :type u32))
68
- ; A count may also be a bare `#define` reference (a symbol the emitter
69
- ; 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))
70
164
  (value-kind :name count
71
165
  :description "Draw / dispatch count: a literal, a bounded expression, or a bare (define …) reference."
72
- :underlying union
73
- :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))
74
206
  ; A WebGPU device-limit value. Non-negative integer, u32-range in the schema
75
207
  ; (the PNGB wire carries u64 for forward-compat). Passed VERBATIM to
76
208
  ; requiredLimits at device creation — an unsatisfiable request fails loud there
@@ -81,53 +213,108 @@
81
213
  :numeric (numeric-bounds :min 0 :integer true)
82
214
  :unit (unit-shape :reject true)
83
215
  :repr (repr-shape :type u32))
84
- (value-kind :name unorm
85
- :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)."
86
222
  :underlying number
87
223
  :numeric (numeric-bounds :min 0 :max 1)
88
224
  :unit (unit-shape :reject true)
89
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))
90
246
  (value-kind :name depth-bias-value
91
- :description "Depth bias term: constant (int) or slope-scale / clamp (real)."
247
+ :description "Depth bias slope-scale / clamp: a real."
92
248
  :underlying number
93
249
  :unit (unit-shape :reject true)
94
250
  :repr (repr-shape :type f32))
95
- (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
96
256
  :description "Sampler mip level-of-detail clamp (non-negative real; WebGPU defaults lodMinClamp 0, lodMaxClamp 32)."
97
257
  :underlying number
98
258
  :numeric (numeric-bounds :min 0)
99
259
  :unit (unit-shape :reject true)
100
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))
101
265
  (value-kind :name anisotropy-value
102
266
  :description "Sampler max anisotropy (integer in [1,16]; values > 1 require linear mag/min/mipmap filters)."
103
267
  :underlying number
104
268
  :numeric (numeric-bounds :min 1 :max 16 :integer true)
105
269
  :unit (unit-shape :reject true)
106
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).
107
281
  (value-kind :name texture-dimension
108
- :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.)"
109
- :underlying number
110
- :numeric (numeric-bounds :min 1 :max 3 :integer true)
111
- :unit (unit-shape :reject true)
112
- :repr (repr-shape :type u32))
113
- (value-kind :name subresource-count
114
- :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."
115
290
  :underlying number
116
291
  :numeric (numeric-bounds :min 1 :integer true)
117
292
  :unit (unit-shape :reject true)
118
293
  :repr (repr-shape :type u32))
119
- (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
120
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.)"
121
300
  :underlying number
122
301
  :numeric (numeric-bounds :min 0 :integer true)
123
302
  :unit (unit-shape :reject true)
124
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))
125
308
  (value-kind :name view-dimension
126
- :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`.)"
127
- :underlying number
128
- :numeric (numeric-bounds :min 0 :max 5 :integer true)
129
- :unit (unit-shape :reject true)
130
- :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).")))
131
318
  (value-kind :name texture-aspect
132
319
  :description "GPUTextureAspect — which aspect(s) of a depth/stencil texture a view exposes."
133
320
  :underlying symbol
@@ -157,10 +344,6 @@
157
344
  :description "Reference to a declared (compute-pipeline :name …)."
158
345
  :underlying symbol
159
346
  :cross-ref (cross-ref :target compute-pipeline))
160
- (value-kind :name wasm-call-ref
161
- :description "Reference to a declared (wasm-call :name …)."
162
- :underlying symbol
163
- :cross-ref (cross-ref :target wasm-call))
164
347
  (value-kind :name bind-group-ref
165
348
  :description "Reference to a declared (bind-group :name …)."
166
349
  :underlying symbol
@@ -173,20 +356,35 @@
173
356
  :description "Reference to a declared (queue :name …)."
174
357
  :underlying symbol
175
358
  :cross-ref (cross-ref :target queue))
176
- (value-kind :name render-pass-ref
177
- :description "Reference to a declared (render-pass :name …)."
178
- :underlying symbol
179
- :cross-ref (cross-ref :target render-pass))
180
359
  (value-kind :name compute-pass-ref
181
360
  :description "Reference to a declared (compute-pass :name …), including one lowered from (init …) sugar."
182
361
  :underlying symbol
183
362
  :cross-ref (cross-ref :target compute-pass))
184
- ; A bind-group's :layout-pipeline may target either pipeline kind; the union
185
- ; tries render first, then falls through to compute on cross-ref miss.
186
- (value-kind :name pipeline-ref
187
- :description "Reference to a declared render- or compute-pipeline."
188
- :underlying union
189
- :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]))
190
388
 
191
389
  ; ---- runtime builtin data sources (write-buffer :data) ----
192
390
  (value-kind :name builtin-data-source
@@ -194,18 +392,27 @@
194
392
  :underlying symbol
195
393
  :members (member-set
196
394
  (member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32).")
197
- (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.")
198
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]))
199
406
  (value-kind :name write-buffer-source
200
- :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."
201
408
  :underlying union
202
- :union (union-shape :alternatives [builtin-data-source data-ref]))
409
+ :union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
203
410
 
204
- ; ---- size: a byte count / expression OR a data-ref the buffer is sized from ----
205
- (value-kind :name byte-size
206
- :description "Buffer size: an integer / expression, or a (data …) reference."
207
- :underlying union
208
- :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.
209
416
 
210
417
  ; ---- enums ----
211
418
  (value-kind :name buffer-usage
@@ -220,8 +427,8 @@
220
427
  (member :name copy-src :description "Source of copy operations.")
221
428
  (member :name indirect :description "Holds indirect draw/dispatch arguments.")
222
429
  (member :name query-resolve :description "Receives resolve-query-set results.")
223
- (member :name map-read :description "Mappable for CPU readback.")
224
- (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.")))
225
432
  (value-kind :name primitive-topology
226
433
  :description "GPUPrimitiveTopology — how vertices are assembled into primitives."
227
434
  :underlying symbol
@@ -304,8 +511,7 @@
304
511
  ; Follows `entry-point`: a free symbol naming something inside opaque WGSL,
305
512
  ; which the EMITTER cross-checks against reflection. SJON cannot check it —
306
513
  ; the override declarations live inside a `:code` string the validator does
307
- ; not parse (see docs/plans/constants/05-lowered-reflection.md for the route
308
- ; that would change that, and why it is blocked upstream).
514
+ ; not parse.
309
515
  (value-kind :name override-name
310
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."
311
517
  :underlying symbol)
@@ -317,6 +523,10 @@
317
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."
318
524
  :underlying number
319
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))
320
530
  (value-kind :name layout-mode
321
531
  :description "Pipeline layout mode: auto derives bind-group layouts from the WGSL."
322
532
  :underlying symbol
@@ -389,9 +599,16 @@
389
599
  :description "Reference to a declared (query-set :name …)."
390
600
  :underlying symbol
391
601
  :cross-ref (cross-ref :target query-set))
392
- (value-kind :name timestamp-writes-item :underlying form :heads (head-set :names [timestamp-writes]))
393
602
  ; Heads admitted positionally inside an (occlusion-query …) bracket.
394
- (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)))
395
612
 
396
613
  ; ---- Phase 2a: textures, shape generators, depth/stencil, indexed draws ----
397
614
  (value-kind :name texture-ref
@@ -472,6 +689,38 @@
472
689
  :underlying symbol
473
690
  :members (member-set
474
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]))
475
724
  (value-kind :name index-format
476
725
  :description "GPUIndexFormat — byte width of index-buffer entries."
477
726
  :underlying symbol
@@ -549,7 +798,9 @@
549
798
  (member :name decrement-clamp :description "Decrement, clamping at 0.")
550
799
  (member :name increment-wrap :description "Increment, wrapping to 0 past the maximum.")
551
800
  (member :name decrement-wrap :description "Decrement, wrapping to the maximum below 0.")))
552
- (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)))
553
804
 
554
805
  ; ---- Phase 2d: MRT / MSAA / advanced render state ----
555
806
  ; A render-pass attachment view: the canvas (context-current-texture) or a
@@ -594,16 +845,34 @@
594
845
  :numeric (numeric-bounds :min 0 :max 15 :integer true)
595
846
  :unit (unit-shape :reject true)
596
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.
597
865
  (value-kind :name write-mask
598
866
  :description "Color write mask: an integer bitmask (R=1 G=2 B=4 A=8) or the symbol all (15). Emitter-resolved."
599
- :underlying union
600
- :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))
601
869
 
602
870
  ; ---- explicit bind-group-layout (uniform_access feature) ----
603
- ; A `#bindGroupLayout` declares the binding layout explicitly (per-entry
604
- ; visibility + buffer-binding-type) instead of inferring it from a pipeline's
605
- ; auto-layout. visibility is a shader-stage set the emitter ORs into the WebGPU
606
- ; 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).
607
876
  (value-kind :name visibility
608
877
  :description "GPUShaderStage — a shader stage that may access the binding."
609
878
  :underlying symbol
@@ -629,14 +898,38 @@
629
898
  :description "Reference to a declared (pipeline-layout :name …)."
630
899
  :underlying symbol
631
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]))
632
913
  ; Positional sub-form heads for the explicit bind-group-layout: an (entry …)
633
- ; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms (F8):
914
+ ; layout entry and its (buffer …) resource. Both are SLOT-LOCAL forms:
634
915
  ; declared inline under their parent form and resolved LOCAL-FIRST, so the
635
916
  ; natural names `entry`/`buffer` shadow within scope — no collision with the
636
917
  ; global `entry` (render-pipeline stage) or `buffer` (top-level resource) forms.
637
918
  ; Extends to local (sampler …)/(texture …) resources later.
638
919
  (value-kind :name bgl-entry-item :underlying form :heads (head-set :names [entry]))
639
- (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)))
640
933
  ; The three non-buffer resource kinds. Each symbol member IS its WebGPU spelling,
641
934
  ; so the emitter passes it into the descriptor JSON verbatim (like buffer-binding-type).
642
935
  (value-kind :name canvas-alpha-mode
@@ -644,7 +937,7 @@
644
937
  :underlying symbol
645
938
  :members (member-set
646
939
  (member :name opaque :description "Alpha is ignored; the canvas composites as opaque (the WebGPU spec default; cheaper, no fringe on colored pages).")
647
- (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.")))
648
941
  (value-kind :name sampler-binding-type
649
942
  :description "GPUSamplerBindingType — how a sampler binding is exposed to WGSL."
650
943
  :underlying symbol
@@ -676,24 +969,27 @@
676
969
  :string-bounds (string-bounds :format path))
677
970
 
678
971
  ; ---- vectors ----
679
- (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))
680
973
  ; Viewport: the two shapes the emitter accepts — a 5-element rect is invalid.
681
974
  (value-kind :name viewport-rect4
682
975
  :description "Viewport [x y w h]; minDepth/maxDepth default to 0 and 1."
683
- :underlying vector :vector (vector-shape :element number :len 4))
976
+ :underlying vector :vector (vector-shape :element real :len 4))
684
977
  (value-kind :name viewport-rect6
685
978
  :description "Viewport [x y w h minDepth maxDepth]; depths in [0,1]."
686
- :underlying vector :vector (vector-shape :element number :len 6))
979
+ :underlying vector :vector (vector-shape :element real :len 6))
687
980
  (value-kind :name viewport-rect
688
981
  :description "Viewport rectangle: [x y w h] or [x y w h minDepth maxDepth]."
689
982
  :underlying union
690
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.
691
987
  (value-kind :name pixel-rect
692
988
  :description "Rectangle [x y w h] in integer pixels."
693
- :underlying vector :vector (vector-shape :element number :len 4))
989
+ :underlying vector :vector (vector-shape :element u32 :len 4))
694
990
  (value-kind :name origin3
695
- :description "Copy origin [x y z] in texels; z is the destination array layer / depth slice (default 0)."
696
- :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))
697
993
  ; A buffer/texture with zero usage flags is invalid GPU — require >= 1 (else the
698
994
  ; reader emits a buffer with no usage and no diagnostic). `:min-len 1`.
699
995
  (value-kind :name usage-list
@@ -702,13 +998,13 @@
702
998
  ; RGBA clear: exactly 4 components (else a 3-element color silently gets alpha 0).
703
999
  (value-kind :name clear-color
704
1000
  :description "RGBA clear color: exactly 4 components."
705
- :underlying vector :vector (vector-shape :element number :len 4))
1001
+ :underlying vector :vector (vector-shape :element real :len 4))
706
1002
  ; RGBA blend-constant: exactly 4 float components, used by the `constant` /
707
1003
  ; `one-minus-constant` blend factors (setBlendConstant). Same shape as
708
1004
  ; clear-color; named separately so the description reads for its own role.
709
1005
  (value-kind :name blend-constant-color
710
1006
  :description "RGBA blend constant: exactly 4 float components (the `constant` blend factor's value)."
711
- :underlying vector :vector (vector-shape :element number :len 4))
1007
+ :underlying vector :vector (vector-shape :element real :len 4))
712
1008
  (value-kind :name buffer-ref-list
713
1009
  :description "Declared (buffer …) names, bound to vertex slots 0..N in order."
714
1010
  :underlying vector :vector (vector-shape :element buffer-ref))
@@ -716,7 +1012,7 @@
716
1012
  :description "Declared (bind-group …) names, set at @group 0..N in order."
717
1013
  :underlying vector :vector (vector-shape :element bind-group-ref))
718
1014
  (value-kind :name bind-group-layout-ref-list
719
- :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."
720
1016
  :underlying vector :vector (vector-shape :element bind-group-layout-ref :min-len 1))
721
1017
  (value-kind :name render-bundle-ref-list
722
1018
  :description "Declared (render-bundle …) names replayed by a pass."
@@ -736,72 +1032,187 @@
736
1032
  (value-kind :name compute-pass-ref-list
737
1033
  :description "Declared (compute-pass …) / (init …) names, run in order."
738
1034
  :underlying vector :vector (vector-shape :element compute-pass-ref :max-len 2048))
739
- ; One frame step: render-pass tried first, then compute-pass, then queue.
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.)
740
1040
  (value-kind :name frame-step
741
- :description "One frame step: a render-pass, compute-pass, or queue name."
742
- :underlying union
743
- :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]))
744
1044
  (value-kind :name frame-step-list
745
1045
  :description "Passes and queues run every frame, in order."
746
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.
747
1052
  (value-kind :name texture-format-list
748
- :description "Color target formats a (render-bundle …) is recorded against."
749
- :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))
750
1055
  (value-kind :name data-file-list
751
- :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."
752
1057
  :underlying vector :vector (vector-shape :element file-path))
753
1058
  (value-kind :name offset-list
754
1059
  :description "Integer offset list (e.g. per-entry ping-pong pool offsets)."
755
- :underlying vector :vector (vector-shape :element number))
1060
+ :underlying vector :vector (vector-shape :element u32))
756
1061
  (value-kind :name shape-format-list
757
1062
  :description "Vertex layout of generated shape data, as ordered attribute specifiers."
758
1063
  :underlying vector :vector (vector-shape :element shape-format))
759
1064
  (value-kind :name texture-usage-list
760
1065
  :description "Texture usage flags (at least one)."
761
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).
762
1077
  (value-kind :name dispatch-size
763
- :description "3-element compute dispatch [x y z] in workgroups."
764
- :underlying vector :vector (vector-shape :element count-value :len 3))
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))
765
1080
  ; `(wasm-call …)` args: the emitter encodes a type tag per arg (+ 4 value bytes for
766
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.")))
767
1096
  (value-kind :name wasm-arg
768
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)."
769
- :underlying union :union (union-shape :alternatives [symbol number]))
1098
+ :underlying union :union (union-shape :alternatives [wasm-arg-builtin number]))
770
1099
  (value-kind :name wasm-arg-list
771
1100
  :description "Arguments passed to a (wasm-call …) function each frame."
772
1101
  :underlying vector :vector (vector-shape :element wasm-arg))
773
1102
 
774
1103
  ; ---- positional head-sets ----
775
- (value-kind :name pipeline-section :underlying form :heads (head-set :names [layout vertex fragment primitive depth-stencil multisample]))
776
- (value-kind :name vertex-section :underlying form :heads (head-set :names [module entry buffers constant]))
777
- (value-kind :name fragment-section :underlying form :heads (head-set :names [module entry targets constant]))
778
- ; A compute pipeline has exactly one stage, so `(constant …)` attaches
779
- ; directly rather than through an invented `(compute …)` stage form — the
780
- ; asymmetry is already in WebGPU's own descriptor shapes.
781
- (value-kind :name compute-pipeline-section :underlying form :heads (head-set :names [constant]))
782
- (value-kind :name primitive-section :underlying form :heads (head-set :names [topology]))
783
- (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]))
784
1143
  (value-kind :name attribute-item :underlying form :heads (head-set :names [attribute]))
785
- (value-kind :name targets-item :underlying form :heads (head-set :names [target]))
786
- (value-kind :name target-section :underlying form :heads (head-set :names [blend]))
787
- (value-kind :name blend-section :underlying form :heads (head-set :names [color alpha]))
788
- (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)))
789
1160
  (value-kind :name bind-entry-item :underlying form :heads (head-set :names [entry]))
790
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]))
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)))
791
1187
  ; `(data …)` generators: a positional sub-form whose head selects a procedural shape
792
1188
  ; (cube/sphere/…) or `wasm-data` (a WASM function that returns the vertex bytes).
793
- (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)))
794
1205
 
795
1206
  ; =====================================================================
796
- ; Top-level forms (one per legacy `#macro`)
1207
+ ; Top-level forms
797
1208
  ; =====================================================================
798
1209
 
799
1210
  (form :name define
800
- :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."
801
1212
  (key :name name :type symbol
802
- :description "Constant name, referenced from numeric expression slots and count slots.")
803
- (key :name value :type byte-count
804
- :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."))
805
1216
 
806
1217
  ; Authored WebGPU device requiredLimits. Optional singleton (declare at most
807
1218
  ; once, no :name). Each present key raises the corresponding GPUSupportedLimits
@@ -812,116 +1223,126 @@
812
1223
  ; WebGPU GPUSupportedLimits members (kebab here → camelCase on the wire).
813
1224
  (form :name limits
814
1225
  :description "Authored WebGPU device requiredLimits (optional singleton)."
815
- (key :name max-texture-dimension-1d :type device-limit-value :optional true
1226
+ (key :name max-texture-dimension-1d :type device-limit :optional true
816
1227
  :description "Max width of a 1D texture (default 8192).")
817
- (key :name max-texture-dimension-2d :type device-limit-value :optional true
1228
+ (key :name max-texture-dimension-2d :type device-limit :optional true
818
1229
  :description "Max width/height of a 2D texture (default 8192).")
819
- (key :name max-texture-dimension-3d :type device-limit-value :optional true
1230
+ (key :name max-texture-dimension-3d :type device-limit :optional true
820
1231
  :description "Max width/height/depth of a 3D texture (default 2048).")
821
- (key :name max-texture-array-layers :type device-limit-value :optional true
1232
+ (key :name max-texture-array-layers :type device-limit :optional true
822
1233
  :description "Max array layers of a 2D texture (default 256).")
823
- (key :name max-bind-groups :type device-limit-value :optional true
1234
+ (key :name max-bind-groups :type device-limit :optional true
824
1235
  :description "Max simultaneous bind groups (default 4).")
825
- (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
826
1237
  :description "Max bind groups + vertex buffers combined (default 24).")
827
- (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
828
1239
  :description "Max bindings in a single bind group (default 1000).")
829
- (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
830
1241
  :description "Max dynamic-offset uniform buffers per pipeline layout (default 8).")
831
- (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
832
1243
  :description "Max dynamic-offset storage buffers per pipeline layout (default 4).")
833
- (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
834
1245
  :description "Max sampled textures per shader stage (default 16).")
835
- (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
836
1247
  :description "Max samplers per shader stage (default 16).")
837
- (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
838
1249
  :description "Max storage buffers per shader stage (default 8).")
839
- (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
840
1251
  :description "Max storage buffers in the vertex stage (compat split-stage limit; default 8).")
841
- (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
842
1253
  :description "Max storage buffers in the fragment stage (compat split-stage limit; default 8).")
843
- (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
844
1255
  :description "Max storage textures per shader stage (default 4).")
845
- (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
846
1257
  :description "Max storage textures in the vertex stage (compat split-stage limit; default 4).")
847
- (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
848
1259
  :description "Max storage textures in the fragment stage (compat split-stage limit; default 4).")
849
- (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
850
1263
  :description "Max uniform buffers per shader stage (default 12).")
851
- (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
852
1265
  :description "Max bound range of a uniform buffer in bytes (default 65536).")
853
- (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
854
1267
  :description "Max bound range of a storage buffer in bytes (default 134217728).")
855
- (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
856
1269
  :description "Required alignment of a dynamic uniform buffer offset (default 256).")
857
- (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
858
1271
  :description "Required alignment of a dynamic storage buffer offset (default 256).")
859
- (key :name max-vertex-buffers :type device-limit-value :optional true
1272
+ (key :name max-vertex-buffers :type device-limit :optional true
860
1273
  :description "Max vertex buffers in a render pipeline (default 8).")
861
- (key :name max-buffer-size :type device-limit-value :optional true
1274
+ (key :name max-buffer-size :type device-limit :optional true
862
1275
  :description "Max size of a buffer in bytes (default 268435456).")
863
- (key :name max-vertex-attributes :type device-limit-value :optional true
1276
+ (key :name max-vertex-attributes :type device-limit :optional true
864
1277
  :description "Max vertex attributes across all buffers (default 16).")
865
- (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
866
1279
  :description "Max stride of a vertex buffer in bytes (default 2048).")
867
- (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
868
1281
  :description "Max inter-stage shader variables (default 16).")
869
- (key :name max-color-attachments :type device-limit-value :optional true
1282
+ (key :name max-color-attachments :type device-limit :optional true
870
1283
  :description "Max color attachments in a render pass (default 8).")
871
- (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
872
1285
  :description "Max total bytes per sample across color attachments (default 32).")
873
- (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
874
1287
  :description "Max var<workgroup> storage in bytes (default 16384).")
875
- (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
876
1289
  :description "Max x*y*z of a compute @workgroup_size (default 256).")
877
- (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
878
1291
  :description "Max X of a compute @workgroup_size (default 256).")
879
- (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
880
1293
  :description "Max Y of a compute @workgroup_size (default 256).")
881
- (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
882
1295
  :description "Max Z of a compute @workgroup_size (default 64).")
883
- (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
884
1297
  :description "Max dispatchWorkgroups count per dimension (default 65535)."))
885
1298
 
886
1299
  (form :name canvas
887
1300
  :description "Canvas presentation configuration (optional singleton). Carried as a
888
1301
  header flag, consumed by the JS runtime at context.configure() before
889
- the executor runs. Form absent → premultiplied (the historical
890
- 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.
891
1305
  Native --frame renders offscreen and ignores it. viewFormats/
892
- colorSpace/toneMapping are deferred: anything list-shaped needs a
893
- chained header table, the 3 reserved header bytes being consumed
894
- by the device-limits offset (docs/plans/spec/04)."
895
- (key :name alpha-mode :type canvas-alpha-mode :default premultiplied
896
- :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."))
897
1311
 
898
1312
  (form :name shader-module
899
1313
  :description "A named WGSL module. The source is opaque text to SJON."
900
1314
  (key :name name :type symbol
901
- :description "Module name referenced by pipeline (module …) stages.")
1315
+ :description "Module name referenced by a pipeline stage's :module key.")
902
1316
  (key :name code :type string
903
- :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)."))
904
1318
 
905
1319
  (form :name data
906
1320
  :description "Binary data: an inline float32 array, a positional shape sub-form
907
- (cube/teapot/…) the emitter expands to vertex bytes, or a `:blob`
1321
+ (cube/teapot/…) the emitter expands to vertex bytes, or a `:file`
908
1322
  image file the emitter reads from disk and embeds as
909
1323
  [mime_len][mime][bytes] (consumed by an image-bitmap)."
910
1324
  :positional data-shape-section
911
1325
  (key :name name :type symbol
912
- :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.")
913
1327
  (key :name float32 :type float-list :optional true
914
1328
  :description "Inline float32 array embedded little-endian in the payload.")
915
- (key :name blob :type file-path :optional true
1329
+ (key :name file :type file-path :optional true
916
1330
  :description "Image file path (relative to the source file) embedded as [mime_len][mime][bytes]; decoded at runtime via createImageBitmap.")
917
1331
  (key :name mime :type string :optional true
918
- :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])))
919
1340
 
920
1341
  (form :name image-bitmap
921
- :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."
922
1343
  (key :name name :type symbol)
923
- (key :name image :type data-ref
924
- :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."))
925
1346
 
926
1347
  ; ---- shape sub-forms (positional children of `(data …)`) ----
927
1348
  ; `:open true` so generator-specific numeric config (segments, rings, radius,
@@ -954,36 +1375,28 @@
954
1375
 
955
1376
  (form :name wasm-data
956
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."
957
- (key :name url :type file-path
958
- :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.")
959
1380
  (key :name func :type symbol
960
1381
  :description "Exported function called once to produce the bytes.")
961
1382
  (key :name returns :type string
962
1383
  :description "Return type → byte count (e.g. array<f32,360> → 1440)."))
963
1384
 
964
1385
  (form :name texture
965
- :description "GPU texture. `:size canvas` tracks canvas size; `:size-from <image-bitmap>`
966
- sizes from a decoded image; else width/height. `pool` creates N
967
- 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."
968
1389
  (key :name name :type symbol)
969
- (key :name size :type texture-size-mode :optional true
970
- :description "canvas: track the canvas size at runtime (mutually exclusive with :width/:height).")
971
- (key :name size-from :type image-bitmap-ref :optional true
972
- :description "Take width/height from a decoded (image-bitmap …) at runtime (mutually exclusive with :size).")
973
- (key :name width :type byte-count :optional true
974
- :description "Texel width (when not sized by :size canvas or :size-from).")
975
- (key :name height :type byte-count :optional true
976
- :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.")
977
1392
  (key :name format :type texture-format
978
1393
  :description "Texel format of the texture.")
979
1394
  (key :name usage :type texture-usage-list
980
1395
  :description "Allowed texture usages (at least one).")
981
- (key :name sample-count :type count-value :optional true
1396
+ (key :name sample-count :type u32 :optional true
982
1397
  :description "Samples per texel: 1 (default) or 4 (MSAA). >1 requires render-attachment usage and a resolve-target on the pass.")
983
1398
  (key :name dimension :type texture-dimension :optional true
984
- :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.")
985
- (key :name depth-or-array-layers :type subresource-count :optional true
986
- :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.")
987
1400
  (key :name mip-level-count :type subresource-count :optional true
988
1401
  :description "GPUTextureDescriptor.mipLevelCount — number of mip levels to allocate (default 1). Levels beyond what's written stay uninitialized until generated.")
989
1402
  (key :name pool :type pool-size :optional true
@@ -1000,8 +1413,8 @@
1000
1413
  (key :name name :type symbol)
1001
1414
  (key :name texture :type texture-ref
1002
1415
  :description "Source texture this view aliases.")
1003
- (key :name view-dimension :type view-dimension :optional true
1004
- :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.")
1005
1418
  (key :name aspect :type texture-aspect :optional true
1006
1419
  :description "Which aspect(s) of a depth/stencil texture the view exposes (default all).")
1007
1420
  (key :name base-mip-level :type subresource-index :optional true
@@ -1021,20 +1434,20 @@
1021
1434
  indexed shape's (teapot/dragon) index data — avoids a synthetic
1022
1435
  `_indices` data symbol the SJON cross-ref validator can't resolve."
1023
1436
  (key :name name :type symbol)
1024
- (key :name size :type byte-size :optional true
1025
- :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.")
1026
1439
  (key :name usage :type usage-list
1027
- :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.")
1028
1441
  (key :name pool :type pool-size :optional true
1029
1442
  :description "Create N sequential buffer ids for ping-pong (actual id = base + (frame + offset) % N).")
1030
- (key :name mapped-at-creation :type data-ref :optional true
1031
- :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.")
1032
1445
  (key :name index-of :type data-ref :optional true
1033
- :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.")
1034
1447
  (key :name index-format :type index-format :optional true
1035
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).")
1036
- (key :name wasm :type file-path :optional true
1037
- :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."))
1038
1451
 
1039
1452
  ; Emitter packs a [type:u8][count:u16-LE] descriptor blob → create_query_set.
1040
1453
  (form :name query-set
@@ -1042,11 +1455,12 @@
1042
1455
  (key :name name :type symbol)
1043
1456
  (key :name type :type query-type
1044
1457
  :description "What each query measures: occlusion or timestamp.")
1045
- (key :name count :type count
1046
- :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)."))
1047
1460
 
1048
1461
  (form :name queue
1049
- :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
1050
1464
  frames that reference it."
1051
1465
  :positional queue-action
1052
1466
  (key :name name :type symbol))
@@ -1055,68 +1469,91 @@
1055
1469
  :description "Queue op: write bytes into a buffer before/within a frame (GPUQueue.writeBuffer)."
1056
1470
  (key :name buffer :type buffer-ref
1057
1471
  :description "Destination buffer (needs copy-dst usage).")
1058
- (key :name offset :type byte-count :default 0
1472
+ (key :name offset :type byte-count-4-aligned :default 0
1059
1473
  :description "Byte offset into the destination (WebGPU requires a multiple of 4).")
1060
- (key :name data :type write-buffer-source :optional true
1061
- :description "Source: a (data …) ref, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pointer-inputs (48B).")
1062
- (key :name data-from-wasm :type wasm-call-ref :optional true
1063
- :description "Write a (wasm-call …) result into the buffer at frame time. Mutually exclusive with :data.")
1064
- ; Exactly one data source. Declarative replacement for the emit-time check.
1065
- (exclusive-group :cardinality exactly-one
1066
- (alt :keys [data])
1067
- (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)."))
1068
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.
1069
1495
  (form :name copy-texture-to-texture
1070
1496
  :description "Queue op: GPU texture→texture copy. context-current-texture names the canvas; otherwise a (texture …) name."
1071
- (key :name source :type attachment-view
1072
- :description "Source texture: context-current-texture or a (texture …) name.")
1073
- (key :name destination :type attachment-view
1074
- :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.")))
1075
1506
 
1076
1507
  (form :name copy-external-image-to-texture
1077
1508
  :description "Queue op: upload a decoded image (image-bitmap) into a texture. mip-level / origin default to 0 per the WebGPU spec."
1078
- (key :name source :type image-bitmap-ref
1079
- :description "The decoded (image-bitmap …) to upload.")
1080
- (key :name texture :type texture-ref
1081
- :description "Destination texture (needs copy-dst usage).")
1082
- (key :name mip-level :type byte-count :optional true
1083
- :description "Destination mip level (default 0).")
1084
- (key :name origin :type origin3 :optional true
1085
- :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).")))
1086
1522
 
1087
1523
  (form :name resolve-query-set
1088
1524
  :description "Queue op: copy resolved query results from a query set into a buffer (GPUCommandEncoder.resolveQuerySet)."
1089
1525
  (key :name query-set :type query-set-ref
1090
1526
  :description "The query set to resolve.")
1091
- (key :name first-query :type count :default 0
1527
+ (key :name first-query :type u32 :default 0
1092
1528
  :description "Index of the first query to resolve.")
1093
- (key :name query-count :type count
1529
+ (key :name query-count :type u32
1094
1530
  :description "Number of queries to resolve; each resolves to 8 bytes.")
1095
1531
  (key :name destination :type buffer-ref
1096
1532
  :description "Destination buffer; must have query-resolve usage.")
1097
- (key :name destination-offset :type byte-count :default 0
1533
+ (key :name destination-offset :type byte-count-256-aligned :default 0
1098
1534
  :description "Byte offset into the destination (WebGPU requires a multiple of 256)."))
1099
1535
 
1100
1536
  (form :name copy-buffer-to-buffer
1101
1537
  :description "Queue op: GPU buffer→buffer copy (e.g. resolved queries → a map-read readback buffer)."
1102
1538
  (key :name source :type buffer-ref
1103
1539
  :description "Source buffer (needs copy-src usage).")
1104
- (key :name source-offset :type byte-count :default 0
1540
+ (key :name source-offset :type byte-count-4-aligned :default 0
1105
1541
  :description "Byte offset into the source (multiple of 4).")
1106
1542
  (key :name destination :type buffer-ref
1107
1543
  :description "Destination buffer (needs copy-dst usage).")
1108
- (key :name destination-offset :type byte-count :default 0
1544
+ (key :name destination-offset :type byte-count-4-aligned :default 0
1109
1545
  :description "Byte offset into the destination (multiple of 4).")
1110
- (key :name size :type byte-count
1546
+ (key :name size :type byte-count-4-aligned
1111
1547
  :description "Bytes to copy (multiple of 4)."))
1112
1548
 
1113
- ; The legacy nests `module={ url=… }`; SJON flattens to `:url` (the `module`
1114
- ; 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".
1115
1552
  (form :name wasm-call
1116
- :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."
1117
1554
  (key :name name :type symbol)
1118
- (key :name url :type file-path
1119
- :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).")
1120
1557
  (key :name func :type symbol
1121
1558
  :description "Exported function to call at frame time.")
1122
1559
  (key :name returns :type string
@@ -1126,30 +1563,32 @@
1126
1563
 
1127
1564
  (form :name bind-group
1128
1565
  :description "Bind group. `pool` + per-entry `ping-pong` drive ping-pong. The
1129
- layout is a pipeline's auto-layout (:layout-pipeline) OR an explicit
1130
- (bind-group-layout …) (:bind-group-layout); exactly one is required
1131
- (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."
1132
1568
  :positional bind-entry-item
1133
1569
  (key :name name :type symbol)
1134
- (key :name layout-pipeline :type pipeline-ref :optional true
1135
- :description "The render- or compute-pipeline whose auto-layout this group targets.")
1136
- (key :name bind-group-layout :type bind-group-layout-ref :optional true
1137
- :description "An explicit (bind-group-layout …) this group targets instead of a pipeline's auto-layout.")
1138
- (key :name layout-index :type binding-index :default 0
1139
- :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 …).")
1140
1582
  (key :name pool :type pool-size :optional true
1141
1583
  :description "Create N sequential bind-group ids for ping-pong selection.")
1142
- ; Exactly one layout source — a pipeline's auto-layout XOR an explicit
1143
- ; (bind-group-layout …). Declarative replacement for the emit-time check.
1144
- (exclusive-group :cardinality exactly-one
1145
- (alt :keys [layout-pipeline])
1146
- (alt :keys [bind-group-layout]))
1147
- ; 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)`.
1148
1585
  ; Resolved LOCAL-FIRST under bind-group, so this `entry` is distinct from the
1149
- ; 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.)
1150
1589
  (form :name entry
1151
- :description "One bind-group entry: binding → buffer | sampler | texture resource
1152
- (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)."
1153
1592
  (key :name binding :type binding-index
1154
1593
  :description "Binding slot matching @binding(N) in the WGSL.")
1155
1594
  (key :name buffer :type buffer-ref :optional true
@@ -1160,9 +1599,11 @@
1160
1599
  :description "Bind a (texture …) at this slot via its default 2d view.")
1161
1600
  (key :name texture-view :type texture-view-ref :optional true
1162
1601
  :description "Bind an explicit (texture-view …) at this slot — for 1d/3d/array/cube sampling.")
1163
- (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]
1164
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).")
1165
- (key :name size :type byte-count :optional true
1606
+ (key :name size :type byte-count :optional true :requires [buffer]
1166
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).")
1167
1608
  (key :name ping-pong :type binding-index :optional true
1168
1609
  :description "Pool offset for this entry: actual id = base + (frame + offset) % pool.")
@@ -1173,31 +1614,14 @@
1173
1614
  (alt :keys [texture])
1174
1615
  (alt :keys [texture-view]))))
1175
1616
 
1176
- ; Head-resolution target for the `(bind-group-layout entry (storage-texture …))`
1177
- ; slot-local form below. WebGPU has no standalone storage-texture resource (a
1178
- ; storage texture is a (texture … :usage [storage-binding])); this global form
1179
- ; exists only so the `bgl-resource` head-set resolves `storage-texture` to a form,
1180
- ; exactly as `buffer`/`sampler`/`texture` resolve to their global resource forms.
1181
- ; It has no emitter phase — never walked at top level — so the real fields live in
1182
- ; the slot-local form; this one just satisfies the head lookup.
1183
- (form :name storage-texture
1184
- :description "Storage-texture layout resource (authored inside (bind-group-layout entry …), not at top level)."
1185
- (key :name name :type symbol :optional true)
1186
- (key :name format :type texture-format :optional true
1187
- :description "Texel format of the storage texture.")
1188
- (key :name access :type storage-texture-access :optional true
1189
- :description "Access mode (default write-only).")
1190
- (key :name view-dimension :type view-dimension :optional true
1191
- :description "View dimension (default 2d)."))
1192
-
1193
1617
  ; ---- explicit bind-group-layout (uniform_access) ----
1194
1618
  ; → create_bind_group_layout (opcode 0x06), emitted between samplers and
1195
1619
  ; pipelines (the legacy phase position). Buffer, sampler, texture, and storage-
1196
- ; texture bindings are modeled. Entries and their resource are SLOT-LOCAL forms
1197
- ; (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 …)`,
1198
1622
  ; resolved local-first so the natural names don't collide with the global forms.
1199
1623
  (form :name bind-group-layout
1200
- :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."
1201
1625
  :positional bgl-entry-item
1202
1626
  (key :name name :type symbol)
1203
1627
  (form :name entry
@@ -1207,13 +1631,13 @@
1207
1631
  :description "Binding slot matching @binding(N) in the WGSL.")
1208
1632
  (key :name visibility :type visibility-list
1209
1633
  :description "Shader stages that may access this binding (ORed into the WebGPU mask: vertex 0x1, fragment 0x2, compute 0x4).")
1210
- ; Nested slot-local (F8) resource form: `(buffer :type T)`. Resolved
1634
+ ; Nested slot-local resource form: `(buffer :type T)`. Resolved
1211
1635
  ; local-first under the layout entry, distinct from the global `buffer`.
1212
1636
  (form :name buffer
1213
1637
  :description "Buffer resource of a layout entry."
1214
- (key :name type :type buffer-binding-type
1215
- :description "How the buffer is exposed to WGSL: uniform, storage, or read-only-storage."))
1216
- ; 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-
1217
1641
  ; objects flow verbatim through gpu.js/--html; native's create_bind_group_layout
1218
1642
  ; parser reads each field string-for-string.
1219
1643
  (form :name sampler
@@ -1225,7 +1649,7 @@
1225
1649
  (key :name sample-type :type texture-sample-type :optional true
1226
1650
  :description "Sample type of the bound texture (default float).")
1227
1651
  (key :name view-dimension :type view-dimension :optional true
1228
- :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).")
1229
1653
  (key :name multisampled :type boolean :optional true
1230
1654
  :description "Whether the binding is a multisampled texture (default false)."))
1231
1655
  (form :name storage-texture
@@ -1240,24 +1664,24 @@
1240
1664
  ; ---- explicit pipeline-layout ----
1241
1665
  ; → create_pipeline_layout (opcode 0x07), emitted between bind-group-layouts and
1242
1666
  ; pipelines. Composes N (bind-group-layout …) into a GPUPipelineLayout that a
1243
- ; (render-pipeline …)/(compute-pipeline …) references via :pipeline-layout instead
1244
- ; 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
1245
1669
  ; DIFFERENT explicit layouts (auto derives a single implicit layout per pipeline).
1246
1670
  (form :name pipeline-layout
1247
- :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."
1248
1672
  (key :name name :type symbol)
1249
1673
  (key :name bind-group-layouts :type bind-group-layout-ref-list
1250
1674
  :description "The (bind-group-layout …) forms at @group 0, 1, … in order."))
1251
1675
 
1252
1676
  (form :name sampler
1253
- :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."
1254
1678
  (key :name name :type symbol)
1255
- (key :name mag-filter :type filter-mode :default linear
1256
- :description "Magnification filter — sampling when one texel covers many pixels. PNGine default: linear (the WebGPU spec default is nearest).")
1257
- (key :name min-filter :type filter-mode :default linear
1258
- :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.")
1259
1683
  (key :name address-mode :type address-mode :optional true
1260
- :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.")
1261
1685
  (key :name address-mode-u :type address-mode :optional true
1262
1686
  :description "Addressing for the U (S) axis; overrides :address-mode for this axis.")
1263
1687
  (key :name address-mode-v :type address-mode :optional true
@@ -1265,12 +1689,12 @@
1265
1689
  (key :name address-mode-w :type address-mode :optional true
1266
1690
  :description "Addressing for the W (R) axis; overrides :address-mode for this axis (3D / cube sampling).")
1267
1691
  (key :name mipmap-filter :type filter-mode :optional true
1268
- :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.")
1269
1693
  (key :name lod-min-clamp :type lod-clamp :optional true
1270
1694
  :description "Minimum mip level of detail the sampler will use (default 0).")
1271
1695
  (key :name lod-max-clamp :type lod-clamp :optional true
1272
1696
  :description "Maximum mip level of detail the sampler will use (default 32).")
1273
- (key :name max-anisotropy :type anisotropy-value :optional true
1697
+ (key :name max-anisotropy :type anisotropy :optional true
1274
1698
  :description "Maximum anisotropy for filtering; values > 1 require linear mag/min/mipmap filters.")
1275
1699
  (key :name compare :type compare-function :optional true
1276
1700
  :description "Comparison function — makes this a comparison sampler (e.g. depth shadow sampling)."))
@@ -1279,38 +1703,48 @@
1279
1703
  ; (via EmittedForm positional children), so the render-pipeline descriptor has
1280
1704
  ; one path.
1281
1705
  (form :name render-pipeline
1282
- :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."
1283
1707
  :positional pipeline-section
1284
1708
  (key :name name :type symbol)
1285
- (key :name pipeline-layout :type pipeline-layout-ref :optional true
1286
- :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 …)."))
1287
1713
 
1288
- ; compute-pipeline is flat (no positional sections) — natural, not a workaround:
1289
- ; a compute pipeline is just module + entry, with no vertex/fragment stages to
1290
- ; nest. The `pngine/init-v1` hook emits one; the flat kvpair shape is correct
1291
- ; as-is (the positional-slot limitation it once worked around was lifted in SJON
1292
- ; 2026-06, but compute-pipeline never needed positional children anyway).
1293
1714
  (form :name compute-pipeline
1294
- :description "GPU compute pipeline: a WGSL module + @compute entry point. Optional positional (constant …) forms specialise the module's `override` declarations."
1715
+ :description "GPU compute pipeline: one positional (compute …) stage naming the WGSL module and its @compute entry point."
1295
1716
  :positional compute-pipeline-section
1296
1717
  (key :name name :type symbol)
1297
- (key :name module :type module-ref
1298
- :description "The (shader-module …) holding the @compute entry.")
1299
- (key :name entry :type entry-point :optional true
1300
- :description "Entry-point function name (defaults to the module's sole @compute fn).")
1301
- (key :name pipeline-layout :type pipeline-layout-ref :optional true
1302
- :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 …)."))
1303
1720
 
1304
- ; ---- render-pipeline sub-forms (source-authored only) ----
1305
- (form :name layout
1306
- :description "Pipeline layout: auto derives bind-group layouts from the WGSL."
1307
- :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.
1308
1727
  (form :name vertex
1309
- :description "Vertex stage: (module …)(entry …) and optional (buffers …) vertex-input layout."
1310
- :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)."))
1311
1734
  (form :name fragment
1312
- :description "Fragment stage: (module …)(entry …) and the (targets …) color targets."
1313
- :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)."))
1314
1748
  ; Authored per STAGE, mirroring WebGPU's GPUProgrammableStage.constants and
1315
1749
  ; the per-entry-point reflection — but RESOLVED per module, because pngine
1316
1750
  ; specialises the shader text at compile time instead of passing a constants
@@ -1320,39 +1754,68 @@
1320
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."
1321
1755
  (key :name name :type override-name
1322
1756
  :description "The WGSL `override` identifier this value is for.")
1323
- (key :name value :type override-value
1757
+ (key :name value :type override-number
1324
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."))
1325
1759
  (form :name primitive
1326
- :description "Primitive assembly state: (topology …) plus cull / winding. Mirror the source: omit the whole form when unauthored."
1327
- :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.")
1328
1784
  (key :name cull-mode :type cull-mode :optional true
1329
1785
  :description "Which faces are discarded (WebGPU default: none).")
1330
1786
  (key :name front-face :type front-face :optional true
1331
1787
  :description "Winding that counts as front-facing (WebGPU default: ccw).")
1332
- (key :name strip-index-format :type index-format :optional true
1333
- :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).")
1334
1788
  (key :name unclipped-depth :type boolean :optional true
1335
- :description "Disable depth clipping (clamp fragments to [0,1] instead of discarding them); needs the depth-clip-control device feature (WebGPU default: false)."))
1336
- ; Keys are optional + default-free: the emitter emits only authored keys
1337
- ; (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.
1338
1798
  (form :name depth-stencil
1339
1799
  :description "Depth/stencil pipeline state. Positional (stencil-front …)/(stencil-back …) carry per-face stencil state."
1340
1800
  :positional depth-stencil-section
1341
- (key :name format :type texture-format :optional true
1342
- :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.")
1343
1806
  (key :name depth-write-enabled :type boolean :optional true
1344
- :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.")
1345
1808
  (key :name depth-compare :type compare-function :optional true
1346
- :description "Comparison the depth test applies (fragment depth vs stored depth).")
1347
- (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
1348
1811
  :description "Constant bias added to fragment depth — shadow maps / depth pre-pass (triangles only).")
1349
- (key :name depth-bias-slope-scale :type depth-bias-value :optional true
1812
+ (key :name depth-bias-slope-scale :type depth-bias :optional true
1350
1813
  :description "Bias that scales with the triangle's depth slope (triangles only).")
1351
- (key :name depth-bias-clamp :type depth-bias-value :optional true
1814
+ (key :name depth-bias-clamp :type depth-bias :optional true
1352
1815
  :description "Maximum magnitude of the total depth bias (0 = unclamped).")
1353
- (key :name stencil-read-mask :type byte-count :optional true
1816
+ (key :name stencil-read-mask :type mask32 :optional true
1354
1817
  :description "Bitmask ANDed with stencil values for tests (spec default 0xFFFFFFFF).")
1355
- (key :name stencil-write-mask :type byte-count :optional true
1818
+ (key :name stencil-write-mask :type mask32 :optional true
1356
1819
  :description "Bitmask ANDed with stencil writes (spec default 0xFFFFFFFF)."))
1357
1820
  ; Same key set for front/back; the head selects which face the emitter writes.
1358
1821
  (form :name stencil-front
@@ -1377,28 +1840,16 @@
1377
1840
  :description "Applied when both stencil and depth tests pass."))
1378
1841
  (form :name multisample
1379
1842
  :description "Multisample pipeline state (MSAA)."
1380
- (key :name count :type count-value
1381
- :description "Samples per pixel: 1 or 4; must match the attachment textures' sample-count.")
1382
- (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
1383
1846
  :description "Sample coverage bitmask (spec default 0xFFFFFFFF).")
1384
1847
  (key :name alpha-to-coverage-enabled :type boolean :optional true
1385
- :description "Fragment alpha generates the coverage mask (requires count > 1)."))
1386
- (form :name module
1387
- :description "The (shader-module …) this stage executes."
1388
- :positional module-ref)
1389
- (form :name entry
1390
- :description "Entry-point function name within the stage's module."
1391
- :positional entry-point)
1392
- (form :name topology
1393
- :description "How vertices assemble into primitives (WebGPU default: triangle-list)."
1394
- :positional primitive-topology)
1395
- (form :name buffers
1396
- :description "Vertex input layout: one (vertex-buffer …) per bound vertex buffer slot."
1397
- :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."))
1398
1849
  (form :name vertex-buffer
1399
1850
  :description "Layout of one vertex buffer slot: stride + step mode + (attribute …) children."
1400
1851
  :positional attribute-item
1401
- (key :name array-stride :type byte-count
1852
+ (key :name array-stride :type byte-count-4-aligned
1402
1853
  :description "Bytes between consecutive elements; multiple of 4 (spec baseline limit 2048).")
1403
1854
  (key :name step-mode :type step-mode :optional true
1404
1855
  :description "Advance per vertex or per instance (WebGPU default: vertex)."))
@@ -1410,9 +1861,6 @@
1410
1861
  :description "Byte offset of the attribute within one element.")
1411
1862
  (key :name format :type vertex-format
1412
1863
  :description "Wire format of the attribute data."))
1413
- (form :name targets
1414
- :description "Color targets of the fragment stage: one (target …) per attachment."
1415
- :positional targets-item)
1416
1864
  (form :name target
1417
1865
  :description "One color target: format plus optional (blend …) state and write mask."
1418
1866
  :positional target-section
@@ -1421,32 +1869,32 @@
1421
1869
  (key :name write-mask :type write-mask :optional true
1422
1870
  :description "Channel write mask: bitmask R=1 G=2 B=4 A=8, or all (15; the WebGPU default)."))
1423
1871
  (form :name blend
1424
- :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."
1425
1873
  :positional blend-section)
1426
1874
  (form :name color
1427
1875
  :description "Blend component for RGB: out.rgb = operation(src.rgb * src-factor, dst.rgb * dst-factor)."
1428
- (key :name src-factor :type blend-factor
1429
- :description "Multiplier on the fragment's color (WebGPU default: one).")
1430
- (key :name dst-factor :type blend-factor
1431
- :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.")
1432
1880
  (key :name operation :type blend-operation :optional true
1433
1881
  :description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
1434
1882
  (form :name alpha
1435
1883
  :description "Blend component for alpha: out.a = operation(src.a * src-factor, dst.a * dst-factor)."
1436
- (key :name src-factor :type blend-factor
1437
- :description "Multiplier on the fragment's alpha (WebGPU default: one).")
1438
- (key :name dst-factor :type blend-factor
1439
- :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.")
1440
1888
  (key :name operation :type blend-operation :optional true
1441
1889
  :description "How the factored terms combine (WebGPU default: add). Emitted only when authored."))
1442
1890
 
1443
1891
  ; ---- render / compute pass ----
1444
1892
  (form :name render-pass
1445
- :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."
1446
1894
  :positional render-pass-section
1447
1895
  (key :name name :type symbol)
1448
1896
  (key :name occlusion-query-set :type query-set-ref :optional true
1449
- :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.")
1450
1898
  (key :name pipeline :type render-pipeline-ref :optional true
1451
1899
  :description "The render pipeline this pass draws with. Omit for a pass that only replays :execute-bundles (the bundle records it).")
1452
1900
  (key :name vertex-buffers :type buffer-ref-list :optional true
@@ -1459,7 +1907,7 @@
1459
1907
  :description "Bind groups set at @group 0..N in order.")
1460
1908
  (key :name bind-groups-pool-offsets :type offset-list :optional true
1461
1909
  :description "Per-group ping-pong offsets into each group's pool.")
1462
- (key :name stencil-reference :type count :optional true
1910
+ (key :name stencil-reference :type u32 :optional true
1463
1911
  :description "Reference value used by stencil compare and the replace operation.")
1464
1912
  (key :name blend-constant :type blend-constant-color :optional true
1465
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.")
@@ -1468,8 +1916,17 @@
1468
1916
  (key :name scissor-rect :type pixel-rect :optional true
1469
1917
  :description "[x y w h] in integer pixels; fragments outside are discarded.")
1470
1918
  (key :name execute-bundles :type render-bundle-ref-list :optional true
1471
- :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."))
1472
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.
1473
1930
  (form :name color-attachment
1474
1931
  :description "One color target of a render pass."
1475
1932
  (key :name view :type attachment-view
@@ -1477,30 +1934,53 @@
1477
1934
  (key :name resolve-target :type attachment-view :optional true
1478
1935
  :description "Receives the resolved single-sample output when :view is multisampled.")
1479
1936
  (key :name clear-value :type clear-color :optional true
1480
- :description "RGBA the attachment is cleared to when load-op is clear (ignored for load).")
1481
- (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
1482
1945
  :description "clear to :clear-value, or load the existing contents.")
1483
- (key :name store-op :type store-op :default store
1946
+ (key :name store-op :type store-op
1484
1947
  :description "store the pass result, or discard it."))
1485
1948
 
1486
1949
  ; Non-default load/store ops emit a preceding set_pass_depth_stencil_ops
1487
1950
  ; (matches the legacy path).
1488
- (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
1489
1969
  :description "Depth/stencil target of a render pass."
1490
1970
  (key :name view :type texture-ref
1491
1971
  :description "The depth/stencil (texture …) this pass tests/writes against.")
1492
1972
  (key :name depth-clear-value :type unorm :optional true
1493
- :description "Depth cleared to when depth-load-op is clear; must be in [0,1].")
1494
- (key :name depth-load-op :type load-op :default clear
1495
- :description "clear depth to :depth-clear-value, or load the existing depth.")
1496
- (key :name depth-store-op :type store-op :default store
1497
- :description "store the resulting depth, or discard it.")
1498
- (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
1499
1979
  :description "Stencil cleared to when stencil-load-op is clear.")
1500
1980
  (key :name stencil-load-op :type load-op :optional true
1501
- :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.")
1502
1982
  (key :name stencil-store-op :type store-op :optional true
1503
- :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."))
1504
1984
 
1505
1985
  (form :name draw
1506
1986
  :description "Non-indexed draw call."
@@ -1522,7 +2002,7 @@
1522
2002
  (key :name first-index :type count :default 0
1523
2003
  :description "Offset into the index buffer, in indices.")
1524
2004
  (key :name base-vertex :type count :default 0
1525
- :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.")
1526
2006
  (key :name first-instance :type count :default 0
1527
2007
  :description "First instance index."))
1528
2008
 
@@ -1530,73 +2010,95 @@
1530
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."
1531
2011
  (key :name buffer :type buffer-ref
1532
2012
  :description "Buffer holding the indirect args (needs indirect usage).")
1533
- (key :name offset :type byte-count :default 0
1534
- :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)."))
1535
2015
 
1536
2016
  (form :name draw-indexed-indirect
1537
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."
1538
2018
  (key :name buffer :type buffer-ref
1539
2019
  :description "Buffer holding the indirect args (needs indirect usage).")
1540
- (key :name offset :type byte-count :default 0
1541
- :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)."))
1542
2022
 
1543
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.
1544
2031
  (form :name timestamp-writes
1545
2032
  :description "Record GPU timestamps at pass start/end into a (query-set :type timestamp)."
1546
2033
  (key :name query-set :type query-set-ref
1547
2034
  :description "The timestamp query set written into.")
1548
- (key :name begin :type count :default 0
1549
- :description "Query index written at pass start.")
1550
- (key :name end :type count :default 1
1551
- :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)."))
1552
2039
 
1553
2040
  (form :name occlusion-query
1554
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."
1555
2042
  :positional occlusion-draw-item
1556
- (key :name query-index :type count :default 0
2043
+ (key :name query-index :type u32 :default 0
1557
2044
  :description "Index within the pass's occlusion query set."))
1558
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.
1559
2053
  (form :name compute-pass
1560
- :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
1561
2056
  (key :name name :type symbol)
1562
2057
  (key :name pipeline :type compute-pipeline-ref
1563
2058
  :description "The compute pipeline this pass dispatches.")
1564
2059
  (key :name bind-groups :type bind-group-ref-list :optional true
1565
2060
  :description "Bind groups set at @group 0..N in order.")
1566
2061
  (key :name bind-groups-pool-offsets :type offset-list :optional true
1567
- :description "Per-group ping-pong offsets into each group's pool.")
1568
- (key :name dispatch-workgroups :type count :optional true
1569
- :description "1D dispatch: N workgroups → dispatch(N,1,1). Accepts expressions like (ceil (/ NUM 64)).")
1570
- (key :name dispatch :type dispatch-size :optional true
1571
- :description "3D dispatch [x y z] in workgroups.")
1572
- (key :name dispatch-indirect :type buffer-ref :optional true
1573
- :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.")
1574
- (key :name dispatch-indirect-offset :type byte-count :default 0
1575
- :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."))
1576
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.
1577
2080
  (form :name render-bundle
1578
- :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
1579
2083
  (key :name name :type symbol)
1580
- (key :name pipeline :type render-pipeline-ref :optional true
1581
- :description "Pipeline recorded into the bundle (the executing pass omits its own).")
1582
- (key :name color-formats :type texture-format-list :optional true
1583
- :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.")
1584
2092
  (key :name depth-stencil-format :type texture-format :optional true
1585
- :description "Depth/stencil format the bundle is recorded against.")
1586
- (key :name sample-count :type count :optional true
1587
- :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.")
1588
2096
  (key :name vertex-buffers :type buffer-ref-list :optional true
1589
2097
  :description "Buffers bound to vertex slots 0..N in order.")
1590
2098
  (key :name bind-groups :type bind-group-ref-list :optional true
1591
2099
  :description "Bind groups set at @group 0..N in order.")
1592
2100
  (key :name index-buffer :type buffer-ref :optional true
1593
- :description "Index buffer when the bundle draws indexed.")
1594
- (key :name draw :type count :optional true
1595
- :description "Record a non-indexed draw of this many vertices.")
1596
- (key :name draw-indexed :type count :optional true
1597
- :description "Record an indexed draw of this many indices.")
1598
- (key :name instance-count :type count :optional true
1599
- :description "Instances for the recorded :draw."))
2101
+ :description "Index buffer when the bundle draws indexed."))
1600
2102
 
1601
2103
  (form :name frame
1602
2104
  :description "Frame program: what runs each frame, in order."
@@ -1611,15 +2113,21 @@
1611
2113
  ; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
1612
2114
  (form :name init
1613
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.
1614
2120
  :lowering (lowering :hook pngine/init-v1
1615
- :produces [compute-pipeline bind-group entry compute-pass])
2121
+ :produces [compute-pipeline compute bind-group entry compute-pass dispatch])
1616
2122
  (key :name name :type symbol)
1617
2123
  (key :name buffer :type buffer-ref
1618
2124
  :description "The storage buffer the init compute writes (bound at @binding 0).")
1619
- (key :name shader :type module-ref
2125
+ (key :name module :type module-ref
1620
2126
  :description "The (shader-module …) holding the @compute init entry.")
1621
- (key :name workgroups :type count
1622
- :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."))
1623
2131
 
1624
2132
  ; =====================================================================
1625
2133
  ; `(pass …)` sugar — container-lowered by pngine/pass-v1 (Phase 2f)
@@ -1637,14 +2145,14 @@
1637
2145
  :description "One `(pass …)`: a fullscreen fragment (or compute) shader-art stage.
1638
2146
  The hook detects features from the WGSL (pngine/pointer/feedback)."
1639
2147
  (key :name name :type symbol)
1640
- (key :name code :type string :optional true
1641
- :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.")
1642
2150
  (key :name feedback :type boolean :optional true
1643
2151
  :description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
1644
2152
  (key :name init :type string :optional true
1645
2153
  :description "One-shot WGSL compute source run on the first frame only.")
1646
- (key :name data :type data-file-list :optional true
1647
- :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."))
1648
2156
 
1649
2157
  (form :name pass-graph
1650
2158
  :description "Container of (pass …) children lowered as a unit so resource ids
@@ -1652,7 +2160,7 @@
1652
2160
  :open true
1653
2161
  :positional pass-item
1654
2162
  :lowering (lowering :hook pngine/pass-v1
1655
- :produces [shader-module buffer texture sampler bind-group
1656
- render-pipeline vertex fragment module entry targets target
2163
+ :produces [shader-module buffer texture sampler bind-group entry
2164
+ render-pipeline vertex fragment target
1657
2165
  render-pass color-attachment draw frame
1658
- compute-pipeline compute-pass queue write-buffer])))
2166
+ compute-pipeline compute compute-pass dispatch queue write-buffer])))