shaders 3.2.474 → 4.0.0

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

@@ -2,43 +2,103 @@ import { Paint } from './paint/fields';
 import { GatherEffect, PointwiseEffect } from './types';
 import { PropRef, ScalarInput } from './values';
 
-/** Mix the child's rgb toward a color by a scalar amount, preserving alpha (linear-RGB). */
+/** What `tintToward` returns: the color prop and the amount, ready for `effect:`. */
 export interface TintTowardEffect {
     readonly kind: 'tintToward';
     readonly color: PropRef;
     readonly amount: ScalarInput;
 }
+/**
+ * Mix the child's color toward one color by an amount, leaving its alpha alone.
+ *
+ * `color` is a color prop. `amount` runs 0 (no change) to 1 (fully that color) and can be a
+ * number, a prop, or a value that varies per pixel such as a mask. Pointwise.
+ *
+ * @example
+ * ```ts
+ * effect: tintToward(p('color'), {amount: radialMask({center: p('center'), radius: p('radius'), falloff: p('falloff')}).times(p('intensity'))})
+ * ```
+ * @tip Pair it with `identityWhen: isZero('intensity')` so the filter costs nothing at zero.
+ * @see paintThrough, pointwise
+ */
 export declare function tintToward(color: PropRef, opts: {
     amount: ScalarInput;
 }): TintTowardEffect;
 /**
- * Displace the child's sample coordinates by a vector field (a simulation output), with a
- * chromatic R/B split around the displaced tap and edge handling per tap. A gather effect:
- * the child renders to a texture, taps are premultiplied, and the result is straight
- * alpha — the alpha discipline is the species', never the author's.
+ * What `displaceBy` returns: the simulation field and the props it reads, ready for `effect:`.
  */
 export interface DisplaceByEffect {
     readonly kind: 'displaceBy';
     readonly field: import('./sim').SimOutputRef;
     readonly strength: PropRef;
     readonly chromatic: PropRef;
-    /** Binds a structural edge-mode prop ('stretch' | 'transparent' | 'mirror' | 'wrap'). */
+    /** A prop marked `compileTime: true` holding `'stretch'`, `'transparent'`, `'mirror'` or `'wrap'`. */
     readonly edges: PropRef;
 }
+/**
+ * Push the child's pixels around by a vector field from one of your simulations.
+ *
+ * `field` is a simulation output, such as `waves.output('displacement')` from
+ * `simulate.grid`. `strength` scales the push (the library uses 0–20), capped at about 15%
+ * of the canvas. `chromatic` (0–3) splits red and blue slightly apart from green along the
+ * push, like a lens. `edges` is a prop marked `compileTime: true` holding `'stretch'`,
+ * `'transparent'`, `'mirror'` or `'wrap'`. Gather.
+ *
+ * @example
+ * ```ts
+ * effect: displaceBy(waves.output('displacement'), {strength: p('intensity'), chromatic: p('chromaticSplit'), edges: p('edges')})
+ * ```
+ * @tip The simulation must derive the field with `op.gradient()`; the definition fails loudly otherwise.
+ * @see gather
+ */
 export declare function displaceBy(field: import('./sim').SimOutputRef, opts: {
     strength: PropRef;
     chromatic: PropRef;
     edges: PropRef;
 }): DisplaceByEffect;
-/** L1 tier: a pointwise filter around a blessed bespoke `'use gpu'` body. */
+/**
+ * Write your own pointwise effect: a function of the child's color at this pixel.
+ *
+ * Give it `build`, which receives `params.childNode` (the child's color here) and
+ * `params.uniforms` (your props), and returns the new color. Keep the child's alpha unless
+ * you mean to change it. No texture is involved, so it is the cheapest kind of filter.
+ *
+ * @example
+ * ```ts
+ * effect: pointwise({build: ({childNode, uniforms}) => math.vec4(math.mul(childNode.member('rgb'), uniforms.gain), childNode.member('a'))})
+ * ```
+ * @see gather, tintToward, paintThrough
+ */
 export declare function pointwise(config: Omit<PointwiseEffect, 'kind'>): PointwiseEffect;
-/** L1 tier: a gather filter around a blessed bespoke tap chain over the child texture. */
+/**
+ * Write your own gather effect: a function that can read the child anywhere.
+ *
+ * Give it `build`, which receives the child as a texture (`params.texture`, or
+ * `params.sampleStraight(uv)` for plain colors), `params.ctx.uv` for this pixel and
+ * `params.uniforms` for your props. Return the new color. Set `resultAlpha: 'straight'` when
+ * you built the color from `sampleStraight`. Costs one extra render of the child.
+ *
+ * @example
+ * ```ts
+ * effect: gather({resultAlpha: 'straight', build: ({sampleStraight, ctx, uniforms}) => sampleStraight(math.add(ctx.uv, uniforms.shift))})
+ * ```
+ * @tip Reach for `pointwise` first. Only gather when the effect needs pixels other than this one.
+ * @see pointwise, displaceBy
+ */
 export declare function gather(config: Omit<GatherEffect, 'kind'>): GatherEffect;
 /**
- * A paint shown through the child — the CSS `mask-image` of the language, inverted:
- * the child is the mask, the paint is the content. `by: 'alpha'` (default) reveals the
- * paint wherever the child has coverage (gradient-through-text); `by: 'luminance'`
- * reveals it by the child's brightness. The paint's own alpha still applies.
+ * Show a paint through the child, so the child becomes the mask.
+ *
+ * Like CSS `mask-image` the other way round: the paint is the content and the child decides
+ * where it shows. `by: 'alpha'` (the default) reveals the paint wherever the child is opaque,
+ * which gives a gradient through text. `by: 'luminance'` reveals it where the child is
+ * bright. The paint's own alpha still applies. Pointwise.
+ *
+ * @example
+ * ```ts
+ * effect: paintThrough(paint.rampOver(paint.dist.radial({center: p('center'), radius: p('radius'), aspect: 1, skew: 0}), paint.pair(p('colorA'), p('colorB'), p('colorSpace'))))
+ * ```
+ * @see tintToward, pointwise
  */
 export declare function paintThrough(paint: Paint, opts?: {
     by?: 'alpha' | 'luminance';

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

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/std/filter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,SAAS,CAAA;AAC1D,OAAO,KAAK,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,UAAU,CAAA;AAElD,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC/B;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;IAAC,MAAM,EAAE,WAAW,CAAA;CAAC,GAAG,gBAAgB,CAExF;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,OAAO,EAAE,YAAY,CAAA;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAC1B;AAED,wBAAgB,UAAU,CACtB,KAAK,EAAE,OAAO,OAAO,EAAE,YAAY,EACnC,IAAI,EAAE;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,GAC9D,gBAAgB,CAElB;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,eAAe,CAEhF;AAED,0FAA0F;AAC1F,wBAAgB,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,YAAY,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE;IAAC,EAAE,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;CAAM,GAAG,eAAe,CAWnG"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/std/filter.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,SAAS,CAAA;AAC1D,OAAO,KAAK,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,UAAU,CAAA;AAElD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;IAAC,MAAM,EAAE,WAAW,CAAA;CAAC,GAAG,gBAAgB,CAGxF;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,OAAO,EAAE,YAAY,CAAA;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,OAAO,OAAO,EAAE,YAAY,EACnC,IAAI,EAAE;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,GAC9D,gBAAgB,CAOlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,eAAe,CAKhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,YAAY,CAKvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE;IAAC,EAAE,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;CAAM,GAAG,eAAe,CAWnG"}

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

@@ -1,32 +1,60 @@
 import { Expr, GpuFragmentParams } from '../gpu/contract';
 import { PropRef } from './values';
 
-/** The generator surface: composed UV, effective viewport, and aspect — locals-bound. */
+/**
+ * The canvas a generator paints on: its `uv`, its `viewport` size in pixels and its `aspect`.
+ *
+ * `uv` runs 0–1 across the layer, y down. `aspect` is width over height. When a parent fits
+ * the layer into a box, `viewport` and `aspect` describe that box. Every frame takes this as
+ * its second argument.
+ *
+ * @example
+ * ```ts
+ * paint: (params) => { const {uv, viewport, aspect} = surfaceOf(params); … }
+ * ```
+ * @see rawSurfaceOf, centredFrame, segmentFrame
+ */
 export declare function surfaceOf(params: GpuFragmentParams): {
     uv: Expr;
     viewport: Expr;
     aspect: Expr;
 };
 /**
- * The generator surface against the RAW canvas viewport (no resize-fit box) — for paints whose
- * pattern is anchored to the canvas rather than a fitted box (Blob's organic disc). Same
- * `uvContext ?? ctx.uv` idiom as {@link surfaceOf}.
+ * The canvas like `surfaceOf`, but always measured against the whole canvas, never a fitted box.
+ *
+ * Use it when a pattern should stay anchored to the canvas as the layer is resized.
+ *
+ * @example
+ * ```ts
+ * const {delta, dist} = centredFrame({center: p('center')})(params, rawSurfaceOf(params))
+ * ```
+ * @see surfaceOf
  */
 export declare function rawSurfaceOf(params: GpuFragmentParams): {
     uv: Expr;
     viewport: Expr;
     aspect: Expr;
 };
+/** What `centredFrame` gives you for each pixel. */
 export interface CentredFrame {
-    /** Vector from the centre to the pixel, aspect-corrected (centre-scaled, D-1). */
+    /** The vector from the centre to the pixel, aspect-corrected (in canvas-height units). */
     delta: Expr;
-    /** Radial distance from the centre. */
+    /** The distance from the centre, in canvas-height units. */
     dist: Expr;
 }
 /**
- * An aspect-corrected frame centred on a position prop: the pixel's `delta` from the centre and
- * its radial `dist` — the opening of every centred field. The centre is a transformPosition
- * value (stored `(x, 1−y)`); the centre is scaled, not the UV alone (D-1 centre-scaled rule).
+ * A frame centred on a position prop: each pixel's offset from the centre and its distance.
+ *
+ * Pass `{center: p('center')}` where `center` is a position prop. Call the result with
+ * `params` and a surface. Distances are aspect-corrected, so 1 is the canvas height and a
+ * circle stays round on a wide canvas.
+ *
+ * @example
+ * ```ts
+ * const {dist} = centredFrame({center: p('center')})(params, surfaceOf(params))
+ * ```
+ * @tip `dist` is in canvas-height units: a radius of 0.5 reaches the top and bottom edges from the middle.
+ * @see segmentFrame, surfaceOf, rawSurfaceOf
  */
 export declare function centredFrame(slots: {
     center: PropRef;
@@ -34,18 +62,28 @@ export declare function centredFrame(slots: {
     uv: Expr;
     aspect: Expr;
 }) => CentredFrame;
+/** What `segmentFrame` gives you for each pixel. */
 export interface SegmentFrame {
-    /** Distance travelled along the from→to axis (0 at `from`). */
+    /** How far the pixel is along the line from `from` toward `to` (0 at `from`), in canvas-height units. */
     along: Expr;
-    /** Signed perpendicular distance from the axis. */
+    /** The signed distance from the line: positive below a left-to-right line, negative above. */
     across: Expr;
-    /** Length of the from→to segment (≥ 1e-4). */
+    /** The length of the line from `from` to `to`, in canvas-height units (never less than 0.0001). */
     length: Expr;
 }
 /**
- * An aspect-corrected frame along the segment between two position props: the pixel's
- * `along`/`across` coordinates plus the segment `length`. Positions are transformPosition
- * values (stored `(x, 1−y)`).
+ * A frame along the line between two position props: how far each pixel is along it and across it.
+ *
+ * Pass `{from: p('from'), to: p('to')}` and call the result with `params` and a surface.
+ * `along` is 0 at `from` and equals `length` at `to`. `across` is the signed distance from the
+ * line. All three are aspect-corrected, in canvas-height units.
+ *
+ * @example
+ * ```ts
+ * const {along, across, length} = segmentFrame({from: p('from'), to: p('to')})(params, surfaceOf(params))
+ * ```
+ * @tip Divide `along` by `length` for a 0–1 position along the line, the natural gradient parameter.
+ * @see centredFrame, directionFrame, surfaceOf
  */
 export declare function segmentFrame(slots: {
     from: PropRef;
@@ -54,28 +92,57 @@ export declare function segmentFrame(slots: {
     uv: Expr;
     aspect: Expr;
 }) => SegmentFrame;
-/** A degrees prop as a unit vector — `(cos θ, sin θ)`, bound to one local. */
+/**
+ * A direction in degrees as a unit vector.
+ *
+ * 0° points right and angles turn clockwise on screen, so 90° points down. Use it wherever a
+ * word wants a light or flow direction as a vector.
+ *
+ * @example
+ * ```ts
+ * const light = direction(params.uniforms.lightAngle, 'light')
+ * ```
+ * @see directionFrame
+ */
 export declare function direction(angleDeg: Expr | number, hint?: string): Expr;
+/** What `directionFrame` gives you. */
 export interface DirectionFrame {
-    /** Unit vector along the frame's direction. */
+    /** The unit vector pointing along the direction. */
     tangent: Expr;
-    /** Unit vector perpendicular to it (90° counter-clockwise). */
+    /** The unit vector at right angles to it. */
     perp: Expr;
-    /** Project a 2D point into the frame: distance along / across the direction. */
+    /** Project a 2D point into the frame: its distance `along` the direction and `across` it. */
     coordsOf(p: Expr): {
         along: Expr;
         across: Expr;
     };
 }
 /**
- * A rotated 2D basis from a degrees prop — the frame a directional surface (brush grain, weave,
- * streaks, flow) lives in. `coordsOf` gives grain-space coordinates; `tangent`/`perp` are the
- * axes for smearing or tilting along it.
+ * The two axes of a direction given in degrees, for patterns that run along it.
+ *
+ * `tangent` points along the direction, `perp` at right angles to it. `coordsOf(point)`
+ * returns that point's `along` and `across` distances in the frame. Brush grain, weave,
+ * streaks and flow all live in one of these.
+ *
+ * @example
+ * ```ts
+ * const grain = directionFrame(params.uniforms.brushAngle, 'brush'); const {along, across} = grain.coordsOf(delta)
+ * ```
+ * @see direction, segmentFrame
  */
 export declare function directionFrame(angleDeg: Expr | number, hint?: string): DirectionFrame;
 /**
- * Fold a point around a centre into one angular sector (mirrored at the sector's half) —
- * the kaleidoscope domain fold. Returns the folded point in polar-recovered coordinates.
+ * Fold a point into one mirrored wedge around a centre: the kaleidoscope fold.
+ *
+ * `sectorAngle` is the wedge's angle in radians (2π divided by the number of facets). `center`
+ * is where the wedges meet, 0.5 by default. Returns the folded point as an offset from the
+ * centre. Sample anything at that point and it repeats and mirrors around the centre.
+ *
+ * @example
+ * ```ts
+ * const folded = sectorFold(uv.member('x'), uv.member('y'), math.div(2 * Math.PI, params.uniforms.facets))
+ * ```
+ * @see directionFrame, centredFrame
  */
 export declare function sectorFold(x: Expr, y: Expr, sectorAngle: Expr, center?: number): Expr;
 //# sourceMappingURL=frames.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/std/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAA;AAOrC,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,CAK7F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,CAKhG;AAED,MAAM,WAAW,YAAY;IACzB,kFAAkF;IAClF,KAAK,EAAE,IAAI,CAAA;IACX,uCAAuC;IACvC,IAAI,EAAE,IAAI,CAAA;CACb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,YACjC,iBAAiB,WAAW;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,KAAG,YAAY,CAUtF;AAED,MAAM,WAAW,YAAY;IACzB,+DAA+D;IAC/D,KAAK,EAAE,IAAI,CAAA;IACX,mDAAmD;IACnD,MAAM,EAAE,IAAI,CAAA;IACZ,8CAA8C;IAC9C,MAAM,EAAE,IAAI,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAC,YAC5C,iBAAiB,WAAW;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,KAAG,YAAY,CAsBtF;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,SAAQ,GAAG,IAAI,CAGrE;AAED,MAAM,WAAW,cAAc;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,IAAI,CAAA;IACb,+DAA+D;IAC/D,IAAI,EAAE,IAAI,CAAA;IACV,gFAAgF;IAChF,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,IAAI,CAAA;KAAC,CAAA;CACjD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,SAAU,GAAG,cAAc,CAatF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,SAAM,GAAG,IAAI,CASlF"}
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/std/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAA;AAOrC;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,CAO7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,CAOhG;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IACzB,0FAA0F;IAC1F,KAAK,EAAE,IAAI,CAAA;IACX,4DAA4D;IAC5D,IAAI,EAAE,IAAI,CAAA;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,YAGjC,iBAAiB,WAAW;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,KAAG,YAAY,CAUtF;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IACzB,yGAAyG;IACzG,KAAK,EAAE,IAAI,CAAA;IACX,8FAA8F;IAC9F,MAAM,EAAE,IAAI,CAAA;IACZ,mGAAmG;IACnG,MAAM,EAAE,IAAI,CAAA;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAC,YAI5C,iBAAiB,WAAW;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,KAAG,YAAY,CAsBtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,SAAQ,GAAG,IAAI,CAIrE;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC3B,oDAAoD;IACpD,OAAO,EAAE,IAAI,CAAA;IACb,6CAA6C;IAC7C,IAAI,EAAE,IAAI,CAAA;IACV,6FAA6F;IAC7F,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,IAAI,CAAA;KAAC,CAAA;CACjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,SAAU,GAAG,cAAc,CActF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,SAAM,GAAG,IAAI,CAWlF"}

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

@@ -1,14 +1,15 @@
 /**
- * `@coreroot/std` — the standard authoring layer for shader definitions.
+ * `shaders/std` — the authoring layer for shader definitions.
  *
- * A shader definition authored on std is declarative data built from these constructors;
- * `defineStd` lowers it onto the engine scaffolds and kit primitives and returns an
- * ordinary `GpuShaderDefinition` — registry generation, framework components, editor
- * metadata and presets are all untouched. GPU math lives in the kit behind the nouns; the
- * per-species L1 tiers (`pointwise`, `gather`, a warp's map fn, a generator's paint
- * builder) carry blessed bespoke bodies where the vocabulary does not reach yet.
+ * A definition is a plain object handed to `defineShader`: a name, its props, and one field
+ * that says what it draws (`paint:`, `effect:`, `map:` or `shape:`), written either from the
+ * words exported here or as a raw `wgsl` body. `defineShader` compiles it to an ordinary
+ * engine definition, so registry generation, framework components, editor metadata and
+ * presets all work unchanged. The GPU math behind each word lives in `src/gpu/kit`.
  */
-export { defineStd } from './lower';
+export { defineStd, defineShader } from './lower';
+export { wgsl, WgslBody, isWgslBody, scanIdentifiers, wgslTypeForProp } from './wgsl';
+export type { WgslSpec, WgslInput, WgslType, WgslHost } from './wgsl';
 export { tintToward, pointwise, gather, displaceBy, paintThrough } from './filter';
 export { radialMask } from './mask';
 export { simulate, op, GridSim } from './sim';
@@ -28,4 +29,41 @@ export type { TintTowardEffect, DisplaceByEffect } from './filter';
 export type { PropRef, ScalarInput, ScalarSource } from './values';
 export type { GridSimConfig, SimOutputRef, GridStepOp, GridDeriveOp } from './sim';
 export type { PointerSignal, PointerSpeedSignal } from './signal';
+export * as math from './math';
+export * as shape from './shape';
+export * as paint from './paint/fields';
+export * as gradients from './paint/gradients';
+export * as patterns from './paint/patterns';
+export * as light from './paint/light';
+export * as noise from './paint/noise';
+export * as materials from './paint/materials';
+export * as volume from './paint/volume';
+export * as compose from './paint/compose';
+export * as figures from './paint/figures';
+export * as media from './paint/media';
+export * as radiance from './paint/radiance';
+export * as voxels from './paint/voxels';
+export * as frames from './frames';
+export * as warps from './warps';
+export * as motion from './motion';
+export * as mask from './mask';
+export * as signal from './signal';
+export * as effects from './effects/index';
+export * as sim from './sim/index';
+export { layered, layers } from './paint/compose';
+export { paintFrame, resolveArgIn } from './invoke';
+export { call, expr, asLocal, ZERO, WHITE0 } from '../gpu/composer';
+export type { KitTexture, EmitContext } from '../gpu/contract';
+export { reliefStylizeProps } from '../utilities/noiseStylize';
+export { listOf, accumulate } from './lists';
+export { listPropConfig } from '../utilities/listProps';
+export type { ListPropSpec } from '../utilities/listProps';
+export { animatedTime } from '../gpu/porters';
+export { colorStopsPropConfig } from '../utilities/colorStops';
+export type { ColorStop } from '../utilities/colorStops';
+export { transformColor, transformPosition, transformColorSpace, colorSpaceOptions, transformBoolean, transformAngle, transformEdges, } from '../utilities/transformations';
+export { registerShader, unregisterShader, getRegisteredShader, getRegisteredShaders, onShaderRegistered } from '../customShaders';
+export type { GpuShaderDefinition as ShaderDefinition, GpuShaderDefinition, GpuFragmentParams, Expr } from '../gpu/contract';
+export type { PropConfig, PropUIConfig, ComponentProps } from '../types';
+export type { StdWgslFilterDefinition } from './types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/std/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,SAAS,EAAC,MAAM,SAAS,CAAA;AACjC,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAC,MAAM,UAAU,CAAA;AAChF,OAAO,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAA;AACjC,OAAO,EAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAC,MAAM,OAAO,CAAA;AAC3C,OAAO,EAAC,OAAO,EAAE,YAAY,EAAC,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAC,CAAC,EAAE,MAAM,EAAC,MAAM,UAAU,CAAA;AAClC,OAAO,EAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAC,MAAM,SAAS,CAAA;AACxF,OAAO,EAAC,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAC,MAAM,UAAU,CAAA;AAI/E,OAAO,EAAC,CAAC,IAAI,MAAM,EAAC,MAAM,kBAAkB,CAAA;AAC5C,YAAY,EAAC,OAAO,EAAE,QAAQ,EAAC,MAAM,UAAU,CAAA;AAG/C,OAAO,EAAC,cAAc,EAAE,SAAS,EAAC,MAAM,gCAAgC,CAAA;AACxE,YAAY,EAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAC,MAAM,gCAAgC,CAAA;AACtG,YAAY,EAAC,YAAY,EAAC,MAAM,kCAAkC,CAAA;AAClE,YAAY,EAAC,eAAe,EAAC,MAAM,4BAA4B,CAAA;AAC/D,YAAY,EAAC,kBAAkB,EAAE,cAAc,EAAC,MAAM,2BAA2B,CAAA;AAEjF,YAAY,EACR,aAAa,EACb,iBAAiB,EACjB,4BAA4B,EAC5B,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,GACf,MAAM,SAAS,CAAA;AAChB,YAAY,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,UAAU,CAAA;AAChE,YAAY,EAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,UAAU,CAAA;AAChE,YAAY,EAAC,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAC,MAAM,OAAO,CAAA;AAChF,YAAY,EAAC,aAAa,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/std/index.ts"],"names":[],"mappings":"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"}

package/dist/core/std/index.js

@@ -0,0 +1,4 @@
+import { Ac as defineStd, Al as uniformOf, Ao as fields_exports, As as op, Bd as ZERO, Bs as paintThrough, Cs as recompileWhen, Dl as resolveArg, Dr as layered, Ds as pointerSpeed, El as pointwiseOp, Es as pointer, Fc as wgslTypeForProp, Fs as radialMask, Gd as expr, Hd as call, Hs as tintToward, I as effects_exports, Ic as animatedTime, Ll as lerpToIdentity, Ln as motion_exports, Mc as isWgslBody, Ml as p, Nc as scanIdentifiers, Nr as volume_exports, Ol as resolveArgIn, Or as layers, Os as signal_exports, Pc as wgsl, Ps as mask_exports, Rl as selectMap, Rs as displaceBy, Ss as isZero, Tl as paintFrame, To as gradients_exports, Vd as asLocal, Vf as data_exports, Vs as pointwise, a as unregisterShader, bs as identityWhenever, c as reliefStylizeProps, eu as listPropConfig, hr as radiance_exports, i as registerShader, ii as materials_exports, ja as light_exports, jc as WgslBody, jl as Scalar, js as simulate, kc as defineShader, kl as resolveScalar, ks as GridSim, l as sim_exports, n as getRegisteredShaders, nr as warps_exports, o as accumulate, oo as patterns_exports, ou as colorStopsPropConfig, pr as voxels_exports, ps as shape_exports, qi as noise_exports, r as onShaderRegistered, s as listOf, sc as math_exports, sr as frames_exports, t as getRegisteredShader, vr as media_exports, vs as allOf, wl as ctx, wr as compose_exports, xr as figures_exports, xs as isValue, ys as crosses, zd as WHITE0, zs as gather } from "../std-ClftfWpF.js";
+import "../support-D3W86vgR.js";
+import { a as transformColor, c as transformPosition, i as transformBoolean, o as transformColorSpace, r as transformAngle, s as transformEdges, t as colorSpaceOptions } from "../transformations-P50Uo_Ju.js";
+export { GridSim, Scalar, WHITE0, WgslBody, ZERO, accumulate, allOf, animatedTime, asLocal, call, colorSpaceOptions, colorStopsPropConfig, compose_exports as compose, crosses, ctx, defineShader, defineStd, displaceBy, effects_exports as effects, expr, figures_exports as figures, frames_exports as frames, gather, getRegisteredShader, getRegisteredShaders, gradients_exports as gradients, identityWhenever, isValue, isWgslBody, isZero, layered, layers, lerpToIdentity, light_exports as light, listOf, listPropConfig, mask_exports as mask, materials_exports as materials, math_exports as math, media_exports as media, motion_exports as motion, noise_exports as noise, onShaderRegistered, op, p, fields_exports as paint, paintFrame, paintThrough, patterns_exports as patterns, pointer, pointerSpeed, pointwise, pointwiseOp, radialMask, radiance_exports as radiance, recompileWhen, registerShader, reliefStylizeProps, resolveArg, resolveArgIn, resolveScalar, scanIdentifiers, data_exports as schema, selectMap, shape_exports as shape, signal_exports as signal, sim_exports as sim, simulate, tintToward, transformAngle, transformBoolean, transformColor, transformColorSpace, transformEdges, transformPosition, uniformOf, unregisterShader, volume_exports as volume, voxels_exports as voxels, warps_exports as warps, wgsl, wgslTypeForProp };

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

@@ -4,47 +4,142 @@ import { FilterParams } from '../gpu/scaffolds/pointwiseFilter';
 import { PointwiseEffect } from './types';
 import { Scalar, PropRef, ScalarSource, SignalSlotParams } from './values';
 
-/** A read of one of the system context values. Build via {@link ctx}. */
+/** One of the context values as a token you can pass where a word takes a value: `ctx.uv`, `ctx.time`, … */
 export interface CtxToken {
     readonly kind: 'ctx';
     readonly name: 'uv' | 'aspect' | 'time' | 'viewportSize' | 'logicalViewportSize' | 'pointer';
 }
-/** Context tokens for arg specs: `ctx.uv`, `ctx.aspect`, … */
+/**
+ * The context values as tokens: `ctx.uv`, `ctx.time`, `ctx.aspect`, `ctx.pointer`, `ctx.viewportSize`, `ctx.logicalViewportSize`.
+ *
+ * Pass one where a word takes a value, or bind it under another name in a `wgsl` body's
+ * `inputs`. `uv` is 0–1 across the canvas with y down. `time` is the global clock in seconds
+ * and never pauses; for the layer's own speed-scaled clock declare `animatedTime` and read
+ * `time` in a body or `animatedTime(params)` in a builder. `aspect` is width / height.
+ * `pointer` is the mouse in uv. `viewportSize` is the frame in device pixels,
+ * `logicalViewportSize` in CSS pixels.
+ *
+ * @example
+ * ```ts
+ * paint: wgsl({inputs: {t: ctx.time, px: ctx.viewportSize}, body: 'return vec4f(fract(uv * px / 40.0), sin(t) * 0.5 + 0.5, 1.0);'})
+ * ```
+ * @tip A warp's `map:` has no context; a `ctx` token there throws when the shader is built.
+ * @see p, paintFrame, wgsl
+ */
 export declare const ctx: {
+    /** The pixel's coordinate: 0–1 across the canvas, y down. */
     readonly uv: CtxToken;
+    /** The canvas's width divided by its height. */
     readonly aspect: CtxToken;
+    /** The global clock in seconds. Never pauses; for the layer's own speed-scaled clock declare `animatedTime`. */
     readonly time: CtxToken;
+    /** The frame size in device pixels, as a `vec2f`. */
     readonly viewportSize: CtxToken;
+    /** The frame size in CSS pixels, as a `vec2f`, for feature counts that should not change with screen density. */
     readonly logicalViewportSize: CtxToken;
+    /** The mouse position in uv (0–1, y down). */
     readonly pointer: CtxToken;
 };
-/** One declarative GPU-body argument. */
+/** Anything a word accepts as an input value: a prop ref `p('x')`, a `Scalar`, a context token, or a plain number. */
 export type ArgSpec = PropRef | Scalar | CtxToken | number;
-/** The minimal host surface slots resolve against (warp hooks carry no `ctx`). */
+/** The least a value needs to resolve against: the props, plus `ctx` where the host has one (a warp's `map:` does not). */
 export type SlotParams = SignalSlotParams;
-/** Resolve a prop binding to its uniform accessor (throws on a dangling name). */
 /**
- * The uvContext idiom every generator paint shares: evaluate against the composed UV/viewport
- * when a UV-propagating parent supplies one, else the raw canvas frame.
+ * The coordinate and frame size a hand-written `paint:` builder should draw in.
+ *
+ * Returns `uv` and `viewport` as GPU values. Inside a distortion the uv is the distorted one,
+ * and inside a sized box the viewport is the box, so a generator built on these behaves like
+ * the library's own.
+ *
+ * @example
+ * ```ts
+ * paint: (params) => {
+ *   const {uv} = paintFrame(params)
+ *   const center = uniformOf(p('center'), params)
+ *   const d = length(sub(uv, vec2(center.member('x'), sub(1, center.member('y')))))
+ *   return vec4(splat3(smoothstep(0, 0.5, d)), 1)
+ * }
+ * ```
+ * @see ctx, uniformOf
  */
 export declare function paintFrame(params: GpuFragmentParams): {
     uv: Expr;
     viewport: Expr;
 };
+/**
+ * The live GPU value of a prop, for a hand-written builder: `uniformOf(p('radius'), params)`.
+ *
+ * Colors come back as `vec4f` in linear RGB with alpha, positions as `vec2f`, numbers as
+ * `f32`. Read a part with `.member('rgb')` or `.member('x')`. Throws when the name is not one
+ * of the definition's props.
+ *
+ * @example
+ * ```ts
+ * paint: (params) => {
+ *   const color = uniformOf(p('color'), params)
+ *   const gain = mul(uniformOf(p('intensity'), params), 0.5)
+ *   return vec4(mul(color.member('rgb'), gain), color.member('a'))
+ * }
+ * ```
+ * @tip A position prop's y is stored flipped: use `sub(1, center.member('y'))` to compare it with `uv`.
+ * @see p, resolveScalar, resolveArg, paintFrame
+ */
 export declare function uniformOf(ref: PropRef, params: {
     uniforms: Record<string, Expr>;
 }): Expr;
-/** Resolve a scalar value-graph node to an Expr against the composition params. */
+/**
+ * A `Scalar` or prop ref as a GPU value, for a hand-written builder.
+ *
+ * Products (`.times()`), radial masks and signals are built out here. A radial mask needs a
+ * `paint:` or `effect:` host; it throws in a warp's `map:`.
+ *
+ * @example
+ * ```ts
+ * const amount = resolveScalar(radialMask({center: p('center'), radius: p('radius'), falloff: p('falloff')}).times(p('intensity')), params)
+ * ```
+ * @see uniformOf, resolveArg, Scalar
+ */
 export declare function resolveScalar(input: Scalar | ScalarSource, params: SlotParams): Expr;
-/** Resolve any ArgSpec to an Expr against the composition params. */
+/**
+ * Any input value a word accepts (a prop ref, a `Scalar`, a context token, a number) as a GPU value inside a filter's builder.
+ *
+ * @example
+ * ```ts
+ * effect: pointwise({build: (params) => mix(params.childNode, vec4(0, 0, 0, 1), resolveArg(p('amount'), params))})
+ * ```
+ * @see resolveArgIn, uniformOf, resolveScalar
+ */
 export declare function resolveArg(spec: ArgSpec, params: FilterParams): Expr;
-/** {@link resolveArg} against any slot host (warp hooks included). */
+/**
+ * `resolveArg` for any host, including a warp's `map:` factory.
+ *
+ * A warp has no context, so a `ctx` token or a radial mask throws there; props, scalars and
+ * numbers resolve everywhere.
+ *
+ * @example
+ * ```ts
+ * map: (params) => ({map: (uv) => add(uv, mul(resolveArgIn(p('offset'), params), 0.1))})
+ * ```
+ * @see resolveArg
+ */
 export declare function resolveArgIn(spec: ArgSpec, params: SlotParams): Expr;
 /** Never-used guard so `expr` stays available to vocabulary modules re-exporting it. */
 export { expr as rawExpr };
 /**
- * Build a pointwise filter effect from a kit body + declarative arg specs. The child
- * colour is always the body's first argument; `args` follow in order.
+ * Wrap a compiled GPU function as a pointwise filter effect: the child's color goes in first, then `args`.
+ *
+ * This is how the library's color words are made. `fn` takes `(color: vec4f, ...args)` and
+ * returns the new color; `hint` names it in the generated code; `args` are the values that
+ * follow the color, given as prop refs, scalars, context tokens or numbers. `extra.compose`
+ * post-processes the result and `extra.setup` runs once per build.
+ *
+ * @example
+ * ```ts
+ * export function saturate(intensity: ArgSpec): PointwiseEffect {
+ *   return pointwiseOp(colorOps.saturate, 'saturate', [intensity])
+ * }
+ * ```
+ * @see resolveArg, p
  */
 export declare function pointwiseOp(fn: unknown, hint: string, args: ArgSpec[], extra?: {
     compose?: PointwiseEffect['compose'];

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

@@ -1 +1 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/std/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EAAO,IAAI,EAAS,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kCAAkC,CAAA;AAClE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAC,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAC,MAAM,UAAU,CAAA;AAEvF,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,qBAAqB,GAAG,SAAS,CAAA;CAC/F;AAED,8DAA8D;AAC9D,eAAO,MAAM,GAAG;iBACqB,QAAQ;qBACA,QAAQ;mBACZ,QAAQ;2BACQ,QAAQ;kCACM,QAAQ;sBAChC,QAAQ;CAC7C,CAAA;AAEV,yCAAyC;AACzC,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE1D,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAA;AAEzC,kFAAkF;AAClF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAC,CAKhF;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CAAC,GAAG,IAAI,CAItF;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAgBpF;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAEpE;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAYpE;AAED,wFAAwF;AACxF,OAAO,EAAC,IAAI,IAAI,OAAO,EAAC,CAAA;AAExB;;;GAGG;AACH,wBAAgB,WAAW,CACvB,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EAAE,EACf,KAAK,CAAC,EAAE;IAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;CAAC,GACjF,eAAe,CAQjB"}
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/std/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EAAO,IAAI,EAAS,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kCAAkC,CAAA;AAClE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAC,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAC,MAAM,UAAU,CAAA;AAEvF,4GAA4G;AAC5G,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,qBAAqB,GAAG,SAAS,CAAA;CAC/F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG;IACZ,6DAA6D;iBAC5B,QAAQ;IACzC,gDAAgD;qBACP,QAAQ;IACjD,gHAAgH;mBAC3E,QAAQ;IAC7C,qDAAqD;2BACA,QAAQ;IAC7D,iHAAiH;kCAC9C,QAAQ;IAC3E,8CAA8C;sBACH,QAAQ;CAC7C,CAAA;AAEV,sHAAsH;AACtH,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE1D,2HAA2H;AAC3H,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAA;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AAGH,wBAAgB,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAC,CAKhF;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;CAAC,GAAG,IAAI,CAItF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAgBpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAEpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAYpE;AAED,wFAAwF;AACxF,OAAO,EAAC,IAAI,IAAI,OAAO,EAAC,CAAA;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACvB,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EAAE,EACf,KAAK,CAAC,EAAE;IAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;CAAC,GACjF,eAAe,CAQjB"}