shaders 3.2.474 → 4.0.0

package/dist/core/std/sim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../src/std/sim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAC,aAAa,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAI/D,oFAAoF;AACpF,MAAM,WAAW,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC/B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AACzC,MAAM,MAAM,YAAY,GAAG,UAAU,CAAA;AAErC,eAAO,MAAM,EAAE;4BACE;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,KAAG,MAAM;6BAG1B;QAAC,EAAE,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,KAAG,OAAO;6BAG5E,UAAU;CAGhB,CAAA;AAIV,MAAM,WAAW,aAAa;IAC1B,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,IAAI,EAAE,UAAU,EAAE,CAAA;IAClB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACpC,4DAA4D;IAC5D,IAAI,CAAC,EAAE;QAAC,WAAW,EAAE,sBAAsB,CAAA;KAAC,CAAA;CAC/C;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAC1B;AAED,2FAA2F;AAC3F,qBAAa,OAAO;IACJ,QAAQ,CAAC,MAAM,EAAE,aAAa;gBAArB,MAAM,EAAE,aAAa;IAE1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;CAMrC;AAED,eAAO,MAAM,QAAQ;4BACJ,aAAa,KAAG,OAAO;CAG9B,CAAA"}
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../src/std/sim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAC,aAAa,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAI/D;;;;;GAKG;AAGH,MAAM,WAAW,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;GAKG;AAIH,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAC3B;AAED;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC/B;AAED,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AACzC,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,UAAU,CAAA;AAErC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,EAAE;IACX;;;;;;;;;;OAUG;4BACU;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,KAAG,MAAM;IAGxC;;;;;;;;;;OAUG;6BACW;QAAC,EAAE,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,KAAG,OAAO;IAGxF;;;;;;;;OAQG;6BACS,UAAU;CAGhB,CAAA;AAIV;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,IAAI,EAAE,UAAU,EAAE,CAAA;IAClB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACpC,sFAAsF;IAGtF,IAAI,CAAC,EAAE;QAAC,WAAW,EAAE,sBAAsB,CAAA;KAAC,CAAA;CAC/C;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;IACJ,QAAQ,CAAC,MAAM,EAAE,aAAa;gBAArB,MAAM,EAAE,aAAa;IAE1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;CAMrC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;IACjB;;;;;;;;OAQG;4BACU,aAAa,KAAG,OAAO;CAG9B,CAAA"}

package/dist/core/std/slots.d.ts

@@ -1,15 +1,81 @@
 import { IdentityRule, RecompileRule } from './types';
 
-/** Recompose only when the prop value crosses `value` (identity ↔ effect boundary). */
+/**
+ * Rebuild the shader only when the prop crosses `value`, not on every change.
+ *
+ * Put it on a prop's `recompile:`. Pair it with an identity rule at the same value: the rule
+ * decides whether the filter is skipped, and this is what lets that decision change.
+ *
+ * @example
+ * ```ts
+ * props: {shift: {default: 0, recompile: crosses(0)}},
+ * effect: hueRotate(p('shift')),
+ * identityWhen: isZero('shift'),
+ * ```
+ * @tip Without it a runtime prop never rebuilds, so a filter that started skipped stays skipped.
+ * @see isZero, isValue, recompileWhen
+ */
 export declare function crosses(value: number): RecompileRule;
-/** Recompose when a bespoke predicate flips — the recompile escape hatch. */
+/**
+ * Rebuild when your own test of the old and new value says so, for a threshold `crosses` cannot express.
+ *
+ * @example
+ * ```ts
+ * blur: {default: 0, recompile: recompileWhen((prev, next) => (prev > 0) !== (next > 0))}
+ * ```
+ * @see crosses
+ */
 export declare function recompileWhen(predicate: (prev: any, next: any) => boolean): RecompileRule;
-/** The effect is a provable no-op when `prop` (or its default when unset) is exactly 0. */
+/**
+ * Skip the filter entirely while `prop` is exactly 0.
+ *
+ * Put it on `identityWhen:`. An unset prop counts as its default. A prop that is mapped per
+ * pixel by a driver disables the skip automatically, since the value then varies across the
+ * canvas. Give the prop `recompile: crosses(0)` so the skip switches on and off.
+ *
+ * @example
+ * ```ts
+ * identityWhen: isZero('intensity')
+ * ```
+ * @see isValue, allOf, crosses
+ */
 export declare function isZero(prop: string): IdentityRule;
-/** The effect is a provable no-op when `prop` (or its default when unset) equals `value`. */
+/**
+ * Skip the filter entirely while `prop` equals `value`, for a filter whose no-op is not 0.
+ *
+ * An unset prop counts as its default; a per-pixel mapped prop disables the skip. Give the
+ * prop `recompile: crosses(value)` so the skip switches on and off.
+ *
+ * @example
+ * ```ts
+ * props: {intensity: {default: 1, recompile: crosses(1)}},
+ * effect: saturate(p('intensity')),
+ * identityWhen: isValue('intensity', 1),
+ * ```
+ * @see isZero, allOf, crosses
+ */
 export declare function isValue(prop: string, value: unknown): IdentityRule;
-/** The effect is a no-op only when EVERY rule holds (multi-prop identities). */
+/**
+ * Skip the filter only while every rule holds, for a no-op that needs several props at rest.
+ *
+ * @example
+ * ```ts
+ * identityWhen: allOf(isZero('brightness'), isZero('contrast'))
+ * ```
+ * @see isZero, isValue
+ */
 export declare function allOf(...rules: IdentityRule[]): IdentityRule;
-/** Identity escape hatch: a bespoke predicate over the listed props' CPU values. */
+/**
+ * Skip the filter when your own test of the props' values says so.
+ *
+ * List in `props` every prop the test reads: a per-pixel mapped prop among them disables the
+ * skip, and the engine needs the list to know which.
+ *
+ * @example
+ * ```ts
+ * identityWhen: identityWhenever(['amount', 'mode'], (v) => v.amount === 0 || v.mode === 'off')
+ * ```
+ * @see isZero, isValue, allOf
+ */
 export declare function identityWhenever(props: string[], when: (values: Record<string, unknown>) => boolean): IdentityRule;
 //# sourceMappingURL=slots.d.ts.map

package/dist/core/std/slots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/std/slots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAA;AAExD,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED,6EAA6E;AAE7E,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,GAAG,aAAa,CAEzF;AAED,2FAA2F;AAC3F,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAEjD;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAElE;AAED,gFAAgF;AAChF,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAE5D;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,YAAY,CAElH"}
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/std/slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAA;AAExD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED;;;;;;;;GAQG;AAEH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,GAAG,aAAa,CAEzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAEjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAE5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,YAAY,CAElH"}

package/dist/core/std/types.d.ts

@@ -4,12 +4,10 @@ import { FilterParams } from '../gpu/scaffolds/pointwiseFilter';
 import { RttFilterParams } from '../gpu/scaffolds/rttFilter';
 import { UvMapSource, UvRemapEdgeSource, UvRemapHookParams } from '../gpu/scaffolds/uvRemapShader';
 import { SdfShapeShaderSpec } from '../gpu/scaffolds/sdfShape';
+import { WgslBody } from './wgsl';
 
 /**
- * A declarative recompile rule — the std replacement for a `compileTimeWhen` function.
- * `crosses(v)` recompiles only when the prop value crosses `v` (identity ↔ effect
- * boundaries that add or remove whole code paths); `recompileWhen(fn)` is the escape for
- * a genuinely bespoke predicate.
+ * When a prop change rebuilds the shader: `crosses(value)` at a threshold, or `recompileWhen(fn)` by your own test.
  */
 export type RecompileRule = {
     readonly kind: 'crosses';
@@ -19,20 +17,17 @@ export type RecompileRule = {
     readonly predicate: (prev: any, next: any) => boolean;
 };
 /**
- * A std prop config: the existing `PropConfig` surface (defaults, transforms, ui — the
- * public surface, unchanged) with the function-valued `compileTimeWhen` escape hatch
- * replaced by the declarative `recompile` rule.
+ * One prop of a definition: `default`, optional `transform`, `ui`, `description`, `compileTime`, and a `recompile:` rule.
  */
 export type StdPropConfig<V> = Omit<PropConfig<V>, 'compileTimeWhen'> & {
     recompile?: RecompileRule;
 };
+/** The `props` object of a definition: one `StdPropConfig` per prop name. */
 export type StdProps<T extends ComponentProps> = {
     [K in keyof T]: StdPropConfig<T[K]>;
 };
 /**
- * A declarative no-op condition. Lowered to the filter scaffolds' `FilterIdentity`, which
- * owns the map-driver bypass refusal — a prop the rule reads that carries a map driver
- * disables the bypass automatically.
+ * When a filter does nothing and can be skipped: built with `isZero`, `isValue`, `allOf` or `identityWhenever`.
  */
 export type IdentityRule = {
     readonly kind: 'isZero';
@@ -50,9 +45,11 @@ export type IdentityRule = {
     readonly when: (values: Record<string, unknown>) => boolean;
 };
 /**
- * A pointwise filter effect: a pure fn(color, …) over the composed child — straight
- * alpha, no render-to-texture. The body is a blessed `'use gpu'` fn; `hint` lands in the
- * emitted WGSL and is part of the shader's snapshot contract.
+ * A filter that edits the layer inside one pixel at a time: what the color words (`saturate`, `hueRotate`, …) and `pointwise({build})` return.
+ *
+ * Give either `body` (a compiled GPU function taking the child's color first, then `args`)
+ * or `build` (a function of the params that returns the new color from `params.childNode`).
+ * The child arrives in straight alpha and there is no extra render pass.
  */
 export interface PointwiseEffect {
     readonly kind: 'pointwise';
@@ -63,37 +60,40 @@ export interface PointwiseEffect {
         fn: unknown;
         hint: string;
     });
-    /** Pure-Expr alternative to `body`: build the filtered colour directly (`params.childNode`
-     *  is the composed child). Exactly one of `body`/`build` must be given. */
+    /** Build the new color yourself from `params.childNode`. Give exactly one of `body` or `build`. */
     readonly build?: (params: FilterParams) => Expr;
-    /** Body args AFTER the child colour (always first). */
+    /** The values that follow the child's color as `body`'s arguments. */
     readonly args?: (params: FilterParams) => Expr[];
-    /** Builder-level tail on the body's result (compile-time colour-space mixes etc.). */
+    /** Post-process the result (a color-space mix, a palette lookup). */
     readonly compose?: (result: Expr, params: FilterParams) => Expr;
-    /** Per-composition side effects (extraFields drivers). Non-identity path only. */
+    /** Runs once per build, only when the filter is not skipped (for per-frame driven values). */
     readonly setup?: (params: FilterParams) => void;
 }
 /**
- * A gather filter effect: samples the child's render-to-texture (neighbour taps, screens,
- * dithers). Taps are premultiplied; the species appends the unpremultiply tail unless the
- * build already returns straight alpha. Identity bypasses to a centre sample — never to
- * the raw child (the species' alpha discipline, owned here, invisible to authors).
+ * A filter that reads the layer inside anywhere, not just at this pixel: blurs, halftones, displacements.
+ *
+ * The child is rendered to a texture first (`params.texture`, premultiplied) and
+ * `params.sampleStraight(uv)` reads it back in straight alpha. Return premultiplied color
+ * and it is unpremultiplied for you; say `resultAlpha: 'straight'` when you already did.
  */
 export interface GatherEffect {
     readonly kind: 'gather';
-    /** Build the filtered colour from the child texture (`params.texture` / `sampleStraight`). */
+    /** Build the new color from the child texture. */
     readonly build: (params: RttFilterParams) => Expr;
     readonly resultAlpha?: 'premultiplied' | 'straight';
     readonly setup?: (params: RttFilterParams) => void;
 }
-/** See `filter.ts` — displace the child's sample coordinates by a simulation field. */
+/** A filter that moves the layer inside by a simulation's vector field. See `displaceBy`. */
 export interface DisplaceByEffectRef {
     readonly kind: 'displaceBy';
 }
 /**
- * Fields shared by every std definition. The optional flags are the declarative half of
- * the engine contract; species may derive some of them (a filter never declares
- * `requiresChild`), while the custom tier states them explicitly.
+ * The fields every definition shares: `name`, `props`, optional `description` and `category`, the `animatedTime` clock, and engine flags.
+ *
+ * `animatedTime: {speed: 'speed'}` gives the layer its own clock scaled by that prop.
+ * `usesPointer` asks for mouse tracking, `acceptsOptionalChild` lets a generator take a
+ * nested layer, `extraFields` declares per-frame values you compute on the CPU. Most
+ * definitions need only the first three fields.
  */
 export interface StdDefinitionBase<T extends ComponentProps> {
     name: string;
@@ -123,69 +123,99 @@ export interface StdDefinitionBase<T extends ComponentProps> {
         schema: import('typegpu/data').AnyWgslData;
         initial: number | number[];
     }>;
-    /** A compute pass (simulation state, prepasses). Part of the L1 tier. */
+    /** A compute pass that runs before the pixel work (simulation state, a prepass). */
     compute?: GpuComputeNode;
-    /** Custom per-prop map-driver sample UVs (cell-centre sampling). */
+    /** Where a per-prop map driver samples its map (cell-centre sampling, for grids). */
     mapSampleUVs?: GpuMapSampleUVs;
 }
-/** role 'filter' + species 'pointwise' — inline colour filter over the composed child. */
+/**
+ * A filter that edits the layer inside one pixel at a time: `effect:` holds a color word, `tintToward`, `pointwise({…})` or a `wgsl` body that reads `child`.
+ *
+ * `role` and `species` are optional; the `effect:` field already says filter, and its kind
+ * says pointwise. `identityWhen` skips the filter while a rule holds. `missingChildMessage`
+ * is shown when nothing is nested inside; omit it to fail silently with a transparent output.
+ */
 export interface StdPointwiseFilterDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
-    role: 'filter';
-    species: 'pointwise';
-    effect: PointwiseEffect | import('./filter').TintTowardEffect;
-    /** Declared no-op condition; the lowering owns bypass + driver guards. */
+    role?: 'filter';
+    species?: 'pointwise';
+    effect: PointwiseEffect | import('./filter').TintTowardEffect | WgslBody;
+    /** Skip the filter while this rule holds (`isZero`, `isValue`, `allOf`, `identityWhenever`). */
     identityWhen?: IdentityRule;
-    /** User-facing missing-child message; omit for silent (returns transparent). */
+    /** Logged when nothing is nested inside. Omit to stay silent (the output is transparent). */
     missingChildMessage?: string;
 }
-/** role 'filter' + species 'gather' — samples the child's render-to-texture. */
+/**
+ * A filter that reads the layer inside anywhere: `effect:` holds `gather({…})`, `displaceBy(…)` or a `wgsl` body that samples `childTexture`.
+ *
+ * Same optional fields as the pointwise form. The child gets its own render pass so the
+ * filter can read neighbouring pixels.
+ */
 export interface StdGatherFilterDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
-    role: 'filter';
-    species: 'gather';
-    effect: GatherEffect | import('./filter').DisplaceByEffect;
+    role?: 'filter';
+    species?: 'gather';
+    effect: GatherEffect | import('./filter').DisplaceByEffect | WgslBody;
+    identityWhen?: IdentityRule;
+    missingChildMessage?: string;
+}
+/**
+ * A filter whose `effect:` is a `wgsl` body with no `species` declared: gather when the body samples `childTexture`, pointwise otherwise.
+ *
+ * Declare `species` to override what the body implies.
+ */
+export interface StdWgslFilterDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
+    role?: 'filter';
+    species?: undefined;
+    effect: WgslBody;
     identityWhen?: IdentityRule;
     missingChildMessage?: string;
 }
 /**
- * role 'warp' — a distortion expressed as ONE coordinate map (screen UV → source UV +
- * coverage). The lowering emits both engine paths from it — the render-to-texture
- * fragment and the analytic fold — so they cannot drift.
+ * A distortion: `map:` is one function from the pixel's coordinate to where in the layer inside to read.
+ *
+ * The map returns the source uv, or `{uv, coverage}` when parts of the output should be
+ * transparent. `edges` says what happens past the layer's edge (`'prop'` reads an `edges`
+ * prop, a number fixes a mode, `'none'` skips it). `resample` picks the filter used to read
+ * the layer (`'catmullRom'` by default, `'bilinear'` for blocky or many-tap maps).
  */
 export interface StdWarpDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
-    role: 'warp';
+    role?: 'warp';
     map: UvMapSource;
-    /** Edge handling: `'prop'` (an `edges` prop, default) · a fixed mode · `'none'`. */
+    /** Past the edge: `'prop'` (an `edges` prop, default), a fixed mode number, or `'none'`. */
     edges?: UvRemapEdgeSource;
-    /** Reconstruction filter on the texture path. Default `'catmullRom'`. */
+    /** How the layer is read back: `'catmullRom'` (default, sharp when magnified) or `'bilinear'`. */
     resample?: 'catmullRom' | 'bilinear';
-    /** Analytic-path identity bail-out (a compute texture that may not exist yet). */
+    /** Treat the map as identity while this returns true (a texture it needs may not exist yet). */
     uvRemapIdentityWhen?: (params: UvRemapHookParams) => boolean;
     missingChildMessage?: string;
 }
-/** role 'shape' — an analytic 2D SDF shape (fill + stroke + soften + bounds). */
+/** A 2D shape: `shape:` gives the distance function and the shape's own props; fill, stroke, softness and bounds come for free. */
 export interface StdShapeDefinition {
-    role: 'shape';
+    role?: 'shape';
     name: string;
-    description: string;
+    description?: string;
     category?: string;
     shape: Omit<SdfShapeShaderSpec, 'name' | 'description' | 'category'>;
 }
 /**
- * role 'generator' — a source that paints from coordinates (no child required). `paint`
- * is the composition builder: the L1 tier for generators whose look is a blessed body fn.
+ * A generator: `paint:` produces a color from coordinates and needs nothing nested inside.
+ *
+ * `paint` is either a std composition (`rampOver(…)`, a builder function of the params) or
+ * a `wgsl` body.
  */
 export interface StdGeneratorDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
-    role: 'generator';
-    paint: (params: GpuFragmentParams) => Expr;
+    role?: 'generator';
+    /** A std composition or builder, or a `wgsl` body, returning the pixel's color. */
+    paint: ((params: GpuFragmentParams) => Expr) | WgslBody;
 }
 /**
- * The custom tier — the escape hatch for effects whose composition cannot yet be said in
- * vocabulary (simulations with bespoke render paths, materials, media, structural nodes).
- * The declarative half stays declared on the base; the GPU half is quarantined in `gpu:`.
+ * A raw builder: `gpu:` holds a fragment function (and optionally a `uvRemap`) for effects the words cannot say yet.
+ *
+ * `role` here is only a label. Set `requiresChild` and `requiresRTT` yourself.
  */
 export interface StdCustomDefinition<T extends ComponentProps> extends StdDefinitionBase<T> {
-    role: 'simulation' | 'shapeEffect' | 'media' | 'structural' | 'filter' | 'generator' | 'overlay';
-    species: 'custom';
+    /** A label for the kind of thing this is. Nothing reads it. */
+    role?: 'simulation' | 'shapeEffect' | 'media' | 'structural' | 'filter' | 'generator' | 'overlay';
+    species?: 'custom';
     requiresRTT?: boolean;
     requiresChild?: boolean;
     gpu: {
@@ -193,6 +223,13 @@ export interface StdCustomDefinition<T extends ComponentProps> extends StdDefini
         uvRemap?: GpuUvRemap;
     };
 }
-/** The std definition union — one member per role/species. */
-export type StdDefinition<T extends ComponentProps> = StdPointwiseFilterDefinition<T> | StdGatherFilterDefinition<T> | StdWarpDefinition<T> | StdShapeDefinition | StdGeneratorDefinition<T> | StdCustomDefinition<T>;
+/**
+ * What `defineShader` accepts: one of the definition shapes, told apart by which field carries the per-pixel work.
+ *
+ * `paint:` is a generator, `effect:` a filter (pointwise or gather from the effect), `map:` a
+ * distortion, `shape:` a 2D shape, `gpu:` a raw builder. `role` and `species` may be
+ * declared but must agree with the field; a contradiction throws when the definition is
+ * built.
+ */
+export type StdDefinition<T extends ComponentProps> = StdPointwiseFilterDefinition<T> | StdGatherFilterDefinition<T> | StdWgslFilterDefinition<T> | StdWarpDefinition<T> | StdShapeDefinition | StdGeneratorDefinition<T> | StdCustomDefinition<T>;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/std/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/std/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/std/types.ts"],"names":[],"mappings":"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"}

package/dist/core/std/values.d.ts

@@ -1,20 +1,31 @@
 /**
- * std — the value graph.
+ * Props and values: how a definition points at its own props (`p('radius')`) and combines them into a number, without writing GPU code.
  *
- * Nouns and slots reference values through these nodes, never through Exprs or uniforms
- * directly — the authored file stays strict-literal data, and the lowering (`lower.ts`)
- * turns nodes into Exprs against the composition params. Phase 0 slice: prop bindings and
- * scalar-producing nouns with `.times()` composition; the full ScalarInput union
- * (lengths, signals, field-valued params) lands with later phases.
+ * A prop ref is a live binding: the word you pass it to reads the prop on the GPU every
+ * frame, drivers and animation included. A `Scalar` is a number built from props and masks
+ * (`radialMask(…).times(p('intensity'))`) that any word taking a `ScalarInput` accepts.
  */
-/** A binding to one of the definition's own props. */
+/** A reference to one of the definition's props by name. Make one with `p`. */
 export interface PropRef {
     readonly kind: 'prop';
     readonly name: string;
 }
-/** Bind a prop by name. Identity-checked against the definition's props at lowering. */
+/**
+ * Reference one of the definition's props by name, wherever a word asks for a value.
+ *
+ * Pass it where a std word takes a color, a position or a number and the word reads that
+ * prop live on the GPU. The name must be one of the definition's `props`; a wrong name
+ * throws when the shader is built.
+ *
+ * @example
+ * ```ts
+ * effect: tintToward(p('color'), {amount: p('intensity')})
+ * ```
+ * @tip A prop ref is a binding, not a snapshot: changing the prop later needs no rebuild.
+ * @see Scalar, uniformOf, ctx
+ */
 export declare function p(name: string): PropRef;
-/** A scalar-valued node: a prop, a product, a scalar-producing noun, or a live signal. */
+/** The shapes a `Scalar` can hold: a prop, a product of two values, a radial mask, or a live signal. */
 export type ScalarSource = PropRef | {
     readonly kind: 'mul';
     readonly a: ScalarSource;
@@ -28,22 +39,30 @@ export type ScalarSource = PropRef | {
     readonly kind: 'signal';
     readonly build: (params: SignalSlotParams) => import('../gpu/contract').Expr;
 };
-/** What a signal build receives: any slot host has props+uniforms; `ctx` only in fragment hosts. */
+/** What a signal is given when it builds: the props, and the context values where the host has them (a warp's `map:` has no `ctx`). */
 export interface SignalSlotParams {
     props: import('../gpu/contract').Expr;
     uniforms: Record<string, import('../gpu/contract').Expr>;
     ctx?: import('../gpu/contract').GpuFragmentParams['ctx'];
 }
 /**
- * A scalar value in the authoring surface. Wraps the data node and carries the fluent
- * combinators (`.times()`); serialization reads `.node`.
+ * A number built from props: what `radialMask(…)`, `motion.oscillating(…)` and `.times()` return.
+ *
+ * Pass it anywhere a word accepts a `ScalarInput` (a prop ref or a Scalar): an effect's
+ * `amount`, a mask's strength. Chain `.times(p('intensity'))` to scale it by a prop.
+ *
+ * @example
+ * ```ts
+ * effect: tintToward(p('color'), {amount: radialMask({center: p('center'), radius: p('radius'), falloff: p('falloff')}).times(p('intensity'))})
+ * ```
+ * @see p, resolveScalar
  */
 export declare class Scalar {
     readonly node: ScalarSource;
     constructor(node: ScalarSource);
-    /** Multiply by another scalar (a prop or another Scalar). */
+    /** Multiply by a prop or another Scalar. */
     times(other: Scalar | PropRef): Scalar;
 }
-/** What scalar-typed slots accept. */
+/** What a number-valued input accepts: a prop ref `p('x')` or a `Scalar`. */
 export type ScalarInput = Scalar | PropRef;
 //# sourceMappingURL=values.d.ts.map

package/dist/core/std/values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/std/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACxB;AAED,wFAAwF;AACxF,wBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvC;AAED,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAClB,OAAO,GACP;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;CAAC,GAC1E;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAC,GAC5G;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,iBAAiB,EAAE,IAAI,CAAA;CAAC,CAAA;AAE7G,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,iBAAiB,EAAE,IAAI,CAAA;IACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,iBAAiB,EAAE,IAAI,CAAC,CAAA;IACxD,GAAG,CAAC,EAAE,OAAO,iBAAiB,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;CAC3D;AAED;;;GAGG;AACH,qBAAa,MAAM;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY;gBAAlB,IAAI,EAAE,YAAY;IAEvC,6DAA6D;IAC7D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;CAGzC;AAED,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAA"}
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/std/values.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,+EAA+E;AAC/E,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvC;AAED,wGAAwG;AACxG,MAAM,MAAM,YAAY,GAClB,OAAO,GACP;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAA;CAAC,GAC1E;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAC,GAC5G;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,iBAAiB,EAAE,IAAI,CAAA;CAAC,CAAA;AAE7G,uIAAuI;AACvI,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,iBAAiB,EAAE,IAAI,CAAA;IACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,iBAAiB,EAAE,IAAI,CAAC,CAAA;IACxD,GAAG,CAAC,EAAE,OAAO,iBAAiB,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;CAC3D;AAED;;;;;;;;;;;GAWG;AAEH,qBAAa,MAAM;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY;gBAAlB,IAAI,EAAE,YAAY;IAEvC,4CAA4C;IAC5C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;CAGzC;AAED,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAA"}