shaders 3.2.474 → 4.0.0

package/dist/core/std/effects/reveal.d.ts

@@ -5,102 +5,180 @@ import { ArgSpec } from '../invoke';
 import { PropRef } from '../values';
 
 /**
- * A coverage coordinate: a per-pixel scalar in [0,1] ordering when each pixel is wiped
- * (0 = goes first, 1 = goes last). Produced by the {@link coverage} namespace; refined by the
- * modifier methods, each of which returns a new coverage.
+ * The order pixels disappear in: a number per pixel from 0 (goes first) to 1 (goes last).
+ *
+ * Get one from a `coverage` word, then reshape it with the methods below. Each method returns
+ * a new coverage, so they chain. Pass the result to `reveal`.
+ *
+ * @example
+ * ```ts
+ * coverage: coverage.directional(p('angle')).folded()
+ * ```
+ * @see coverage, reveal
  */
 export declare class Coverage {
     readonly build: (params: FilterParams) => Expr;
     constructor(build: (params: FilterParams) => Expr);
     /**
-     * Fold the coordinate about its midpoint: 0 on the center line, 1 at both ends — one sweeping
-     * front becomes two fronts opening outward (barn doors).
+     * Mirror the order about its middle so one moving edge becomes two opening outward, like
+     * barn doors. The center goes first, both ends last.
      */
     folded(): Coverage;
     /**
-     * Tile the coordinate into `count` repeats, each tile crossing the same front in lockstep
-     * (venetian blinds).
+     * Repeat the order `count` times so every strip wipes at once, like venetian blinds.
      */
     tiled(count: ArgSpec): Coverage;
     /**
-     * Quantize the coordinate into `count` bands that vanish whole, one after another in
-     * coordinate order (ring pops over a radial coverage). Chain `.shuffled()` to randomize the
-     * band order instead.
+     * Cut the order into `count` bands that vanish whole, one after another (rings popping
+     * over a radial coverage). Chain `.shuffled()` to randomize the band order.
      */
     bands(count: ArgSpec): BandedCoverage;
 }
-/** A banded coverage — bands vanish in coordinate order, or in stable random order via {@link BandedCoverage.shuffled}. */
+/**
+ * A coverage cut into bands. Bands vanish in order, or in a fixed random order after `.shuffled()`.
+ *
+ * @example
+ * ```ts
+ * coverage: coverage.radial(p('center')).bands(p('rings'))
+ * ```
+ * @see Coverage
+ */
 export declare class BandedCoverage extends Coverage {
     constructor(base: Coverage, count: ArgSpec);
     private readonly base;
     private readonly count;
     /**
-     * Give each band a stable random coverage (a hash of its index, no time dependence) so the
-     * bands vanish in a frozen shuffled order (random bars).
+     * Vanish the bands in a random order that never changes between frames (random bars).
      */
     shuffled(): Coverage;
 }
 /**
- * The cell-grid coverage family: the frame diced into square-ish cells `size` wide (as a fraction
- * of frame width, height aspect-corrected). Not a coverage by itself — pick how the cells order
- * their pixels: {@link diamond}, {@link checker}, or {@link shuffled}.
+ * The canvas cut into a grid of square cells, waiting for you to pick the order the cells go in.
+ *
+ * Not a coverage on its own. Call `.diamond()`, `.checker()` or `.shuffled()` to get one.
+ *
+ * @example
+ * ```ts
+ * coverage: coverage.cells(p('blockSize')).shuffled()
+ * ```
+ * @see coverage
  */
 export declare class CellCoverage {
     private readonly size;
     constructor(size: ArgSpec);
-    /** Each pixel's coverage is its diamond distance from the cell center — a lattice of growing diamonds. */
+    /** Every cell opens as a growing diamond from its center, all at once. */
     diamond(): Coverage;
-    /** Cells vanish in the staggered checkerboard order: even-parity cells sweep corner-to-corner first, odd-parity second. */
+    /** Cells vanish in checkerboard order: one color of squares sweeps corner to corner, then the other. */
     checker(): Coverage;
-    /** Each cell gets a stable random coverage (a hash of its index, no time dependence) — blocks dissolve in a frozen random order. */
+    /** Cells vanish in a random order that never changes between frames (a block dissolve). */
     shuffled(): Coverage;
 }
-/** The sweep direction of an angular coverage — a structural choice, baked into the compiled shader. */
+/** Which way an angular sweep turns. Baked into the shader, so a change rebuilds it. */
 export type AngularDirection = 'cw' | 'ccw' | 'both';
-/** The coverage coordinate producers — one per family. All read the frame's own UV and aspect. */
+/**
+ * The orders a wipe can follow. Each word returns a `Coverage` for `reveal`.
+ *
+ * All of them read the canvas in uv (0–1 across, y down) and correct for its aspect ratio, so
+ * a circle stays round and a diagonal stays at its true angle.
+ *
+ * @example
+ * ```ts
+ * coverage: coverage.radial(p('center'))
+ * ```
+ * @see reveal, Coverage
+ */
 export declare const coverage: {
     /**
-     * 0→1 along `angleDeg` (degrees, 0 = left to right), aspect corrected so a diagonal reads as
-     * a true angle and both extremes of the frame are reached exactly.
+     * A straight edge sweeping across the canvas.
+     *
+     * `angleDeg` is in degrees; 0 wipes left to right, 90 top to bottom. The edge reaches both
+     * ends of the canvas exactly at whatever angle you give.
+     *
+     * @example
+     * ```ts
+     * coverage: coverage.directional(p('angle'))
+     * ```
+     * @see radial, angular
      */
     directional(angleDeg: ArgSpec): Coverage;
     /**
-     * Distance from `center` (a position prop), normalized by the distance to the FARTHEST corner
-     * so coverage 1 is reached at every pixel however off-center the origin is.
+     * A circle growing out from `center`, an iris wipe.
+     *
+     * `center` is a position prop (`transform: transformPosition`). The circle is sized to the
+     * farthest corner, so it clears the whole canvas even from an off-center start.
+     *
+     * @example
+     * ```ts
+     * coverage: coverage.radial(p('center'))
+     * ```
+     * @see directional, angular
      */
     radial(center: ArgSpec): Coverage;
     /**
-     * Clock-sweep fraction around `center`, measured from `startDeg`. `direction` is STRUCTURAL —
-     * a compile-time string prop (bind with `p()`) or a literal `'cw' | 'ccw' | 'both'`, baked
-     * into the compiled shader as a mode literal ('both' opens two wedges meeting on the far side).
+     * A clock hand sweeping around `center`.
+     *
+     * `startDeg` is where the sweep begins, in degrees. `direction` is `'cw'`, `'ccw'` or
+     * `'both'` (two hands opening from the start and meeting opposite it), either as a literal
+     * or as a select prop declared `compileTime: true`.
+     *
+     * @example
+     * ```ts
+     * coverage: coverage.angular(p('center'), p('startAngle'), p('direction'))
+     * ```
+     * @see radial, directional
      */
     angular(center: ArgSpec, startDeg: ArgSpec, direction: PropRef | AngularDirection): Coverage;
     /**
-     * The frame diced into square-ish cells `size` wide (as a fraction of frame width). Pick the
-     * per-cell ordering: `.diamond()`, `.checker()`, or `.shuffled()`.
+     * A grid of square cells `size` wide.
+     *
+     * `size` is a fraction of the canvas width (0.01–0.5). Finish with `.diamond()`,
+     * `.checker()` or `.shuffled()` to say how the cells go.
+     *
+     * @example
+     * ```ts
+     * coverage: coverage.cells(p('blockSize')).checker()
+     * ```
+     * @see noise
      */
     cells(size: ArgSpec): CellCoverage;
     /**
-     * An organic noise field (a stable 3-octave fbm, no time dependence) — the classic film
-     * dissolve. `scale` sets the blob frequency; `seed` shifts the pattern.
+     * Soft blobs eating the image away, the classic film dissolve.
+     *
+     * `scale` sets the blob size (0.5–20; higher is smaller blobs). `seed` picks a different
+     * pattern. The pattern itself never moves; only `progress` does.
+     *
+     * @example
+     * ```ts
+     * coverage: coverage.noise(p('scale'), p('seed'))
+     * ```
+     * @see cells
      */
     noise(scale: ArgSpec, seed: ArgSpec): Coverage;
 };
-/** The reveal noun's slots: what orders the pixels, and the shared wipe timing. */
+/** What `reveal` needs: the order pixels go in, and the three timing props every wipe shares. */
 export interface RevealSlots {
-    /** The coverage coordinate — which pixels go first. */
+    /** The order pixels disappear in, from a `coverage` word. */
     coverage: Coverage;
-    /** How far the wipe has travelled (0 = fully visible, 1 = fully wiped away). */
+    /** How far the wipe has gone, 0–1 (0 fully visible, 1 fully gone). */
     progress: ArgSpec;
-    /** Softness of the wipe front (the progress window a pixel crosses). */
+    /** Width of the soft edge, 0–1 (0 is a hard edge). */
     feather: ArgSpec;
-    /** Reverse the coverage ordering (a boolean prop; flips the coordinate, not the progress). */
+    /** A boolean prop (`transform: transformBoolean`) that reverses the order. */
     invert: ArgSpec;
 }
 /**
- * Wipe the child away along a coverage coordinate: pixels vanish in coverage order as `progress`
- * grows, crossing a ±`feather` soft front remapped so both progress extremes clear completely.
- * Scales the straight-alpha child's alpha with RGB preserved — pointwise, no render-to-texture.
+ * Fade the child away in coverage order as `progress` goes from 0 to 1.
+ *
+ * At 0 the child is fully visible, at 1 it is gone, whatever `feather` is. Only the child's
+ * alpha changes; its colors stay put. Turning `invert` on reverses the order, so the last
+ * pixels go first.
+ *
+ * @example
+ * ```ts
+ * effect: reveal({coverage: coverage.directional(p('angle')), progress: p('progress'), feather: p('feather'), invert: p('invert')})
+ * ```
+ * @tip Animate `progress` from outside (a prop driven by scroll or a tween); the wipe itself has no clock.
+ * @see coverage, Coverage
  */
 export declare function reveal(slots: RevealSlots): PointwiseEffect;
 //# sourceMappingURL=reveal.d.ts.map

package/dist/core/std/effects/reveal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reveal.d.ts","sourceRoot":"","sources":["../../../src/std/effects/reveal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,oBAAoB,CAAA;AAG5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qCAAqC,CAAA;AACrE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,UAAU,CAAA;AAC7C,OAAO,EAAa,KAAK,OAAO,EAAC,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAEtC;;;;GAIG;AACH,qBAAa,QAAQ;IACL,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI;gBAArC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI;IAE1D;;;OAGG;IACH,MAAM,IAAI,QAAQ;IAIlB;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAK/B;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc;CAGxC;AAED,2HAA2H;AAC3H,qBAAa,cAAe,SAAQ,QAAQ;gBAC5B,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO;IAO1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;IACH,QAAQ,IAAI,QAAQ;CAIvB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,OAAO;IAE1C,0GAA0G;IAC1G,OAAO,IAAI,QAAQ;IAKnB,2HAA2H;IAC3H,OAAO,IAAI,QAAQ;IAKnB,oIAAoI;IACpI,QAAQ,IAAI,QAAQ;CAIvB;AAED,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA;AAIpD,kGAAkG;AAClG,eAAO,MAAM,QAAQ;IACjB;;;OAGG;0BACmB,OAAO,GAAG,QAAQ;IAKxC;;;OAGG;mBACY,OAAO,GAAG,QAAQ;IAKjC;;;;OAIG;oBACa,OAAO,YAAY,OAAO,aAAa,OAAO,GAAG,gBAAgB,GAAG,QAAQ;IAa5F;;;OAGG;gBACS,OAAO,GAAG,YAAY;IAIlC;;;OAGG;iBACU,OAAO,QAAQ,OAAO,GAAG,QAAQ;CAIjD,CAAA;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IACxB,uDAAuD;IACvD,QAAQ,EAAE,QAAQ,CAAA;IAClB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAA;IAChB,8FAA8F;IAC9F,MAAM,EAAE,OAAO,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAa1D"}
+{"version":3,"file":"reveal.d.ts","sourceRoot":"","sources":["../../../src/std/effects/reveal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,oBAAoB,CAAA;AAG5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qCAAqC,CAAA;AACrE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,UAAU,CAAA;AAC7C,OAAO,EAAa,KAAK,OAAO,EAAC,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAEtC;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;IACL,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI;gBAArC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI;IAE1D;;;OAGG;IACH,MAAM,IAAI,QAAQ;IAIlB;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAK/B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc;CAGxC;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC5B,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO;IAO1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;OAEG;IACH,QAAQ,IAAI,QAAQ;CAKvB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,OAAO;IAE1C,0EAA0E;IAC1E,OAAO,IAAI,QAAQ;IAKnB,wGAAwG;IACxG,OAAO,IAAI,QAAQ;IAKnB,2FAA2F;IAC3F,QAAQ,IAAI,QAAQ;CAKvB;AAED,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA;AAIpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ;IACjB;;;;;;;;;;;OAWG;0BACmB,OAAO,GAAG,QAAQ;IAKxC;;;;;;;;;;;OAWG;mBACY,OAAO,GAAG,QAAQ;IAKjC;;;;;;;;;;;;OAYG;oBACa,OAAO,YAAY,OAAO,aAAa,OAAO,GAAG,gBAAgB,GAAG,QAAQ;IAc5F;;;;;;;;;;;OAWG;gBACS,OAAO,GAAG,YAAY;IAIlC;;;;;;;;;;;OAWG;iBACU,OAAO,QAAQ,OAAO,GAAG,QAAQ;CAKjD,CAAA;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IACxB,6DAA6D;IAC7D,QAAQ,EAAE,QAAQ,CAAA;IAClB,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAA;IACjB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAA;IAChB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAgB1D"}

package/dist/core/std/effects/stylize.d.ts

@@ -4,17 +4,26 @@ import { RttFilterParams } from '../../gpu/scaffolds/rttFilter';
 import { GatherEffect } from '../types';
 import { PropRef } from '../values';
 
-/** One gather stage: a value derived from the child RTT. */
+/** A stage that reads the layer inside (rendered to a texture) and gives one value per pixel. */
 export type GatherStage = (params: RttFilterParams) => Expr;
 /**
- * The bleed frame: the tap position with a time-wobbled edge break, shared by the original
- * sample and every brush tap. `amount` at 0 compiles the wobble away (pair with
- * `recompile: crosses(0)` on the definition); the wobble is authored in LOGICAL pixels.
+ * A sample position that drifts slowly past hard edges, so paint bleeds instead of stopping.
+ *
+ * `amount` scales the drift in logical pixels (about four pixels per unit; 0 turns it off).
+ * Build it once and pass the same stage as `at` to both `kuwahara` and `wash`, so the brush and
+ * the original sample agree.
+ *
+ * @example
+ * ```ts
+ * const wet = bleedWarp({amount: p('bleed')})
+ * ```
+ * @tip Give the `amount` prop `recompile: crosses(0)` so turning the bleed off removes the work.
+ * @see kuwahara, wash
  */
 export declare function bleedWarp(slots: {
     amount: PropRef;
 }): GatherStage;
-/** The four overlapping Kuwahara quadrants: premultiplied sum + rgb sum² each, plus the tap weight. */
+/** The brush `kuwahara` builds: four overlapping patches of samples around each pixel. Pass it to `wash`. */
 export type KuwaharaBrush = (params: RttFilterParams) => {
     quadrants: {
         sum: Expr;
@@ -23,30 +32,53 @@ export type KuwaharaBrush = (params: RttFilterParams) => {
     invN: number;
 };
 /**
- * The Kuwahara brush: 4 overlapping quadrants of taps around the `at` frame, accumulating
- * premultiplied sum + rgb sum² per quadrant at the builder level. `radius` is a compile-time
- * brush size (the tap loop is unrolled in JS, stride-2 taps at texel-pair midpoints so one
- * bilinear fetch covers a 2×2 block); every tap is hoisted into a local so it samples exactly
- * once. The footprint is authored in LOGICAL pixels so it stays the same physical size at any
- * DPR.
+ * A painter's brush: the flattening that turns fine detail into soft patches of one color.
+ *
+ * `radius` is the brush size in logical pixels, 1 to 8, and must be a compile-time prop. `at`
+ * is the sample position, normally the same `bleedWarp` stage you hand to `wash`. Returns the
+ * brush for `wash`.
+ *
+ * @example
+ * ```ts
+ * brush: kuwahara({at: wet, radius: p('radius')})
+ * ```
+ * @tip Mark `radius` `compileTime: true`. A hidden prop with a fixed default is the usual choice.
+ * @see wash, bleedWarp
  */
 export declare function kuwahara(slots: {
     at: GatherStage;
     radius: PropRef;
 }): KuwaharaBrush;
 /**
- * The paper-grain stage: screen-space (device-pixel) value noise. `amount` at 0 compiles the
- * noise away (pair with `recompile: crosses(0)` on the definition).
+ * Fine paper grain for the pigment to settle into, one brightness value per screen pixel.
+ *
+ * `amount` runs 0 to 1; at 0 the grain is left out entirely. Returns the stage for the `grain`
+ * slot of `wash`. Pass the same prop as `paper` there too.
+ *
+ * @example
+ * ```ts
+ * grain: paperGrain({amount: p('paper')})
+ * ```
+ * @tip Give the `amount` prop `recompile: crosses(0)`.
+ * @see wash
  */
 export declare function paperGrain(slots: {
     amount: PropRef;
 }): GatherStage;
 /**
- * The wash compose gather recipe: the winning-quadrant Kuwahara mean (lowest variance, mixed
- * back toward the original by `strength`) over the `at` frame, broken by the paper grain toward
- * `paperColor`. The gather runs in PREMULTIPLIED space and unpremultiplies once in the compose,
- * so the result is straight alpha. `strength` at 0 compiles the whole gather away (pair with
- * `recompile: crosses(0)` on the definition).
+ * The watercolor look: the layer inside flattened into soft patches of color over paper grain.
+ *
+ * Closes the recipe and returns the effect for `effect:`. `strength` runs from 0 (the original)
+ * to 1 (the full wash). `paper` (0 to 1) sets how much grain shows and how far the result tints
+ * toward `paperColor`. `at`, `brush` and `grain` are the stages from `bleedWarp`, `kuwahara`
+ * and `paperGrain`.
+ *
+ * @example
+ * ```ts
+ * effect: wash({at: wet, brush: kuwahara({at: wet, radius: p('radius')}), grain: paperGrain({amount: p('paper')}), paper: p('paper'), paperColor: p('paperColor'), strength: p('strength')})
+ * ```
+ * @tip `strength` at 0 skips the whole effect. Give the prop `recompile: crosses(0)`.
+ * @see kuwahara, bleedWarp, paperGrain
  */
 export declare function wash(slots: {
     at: GatherStage;
@@ -56,7 +88,7 @@ export declare function wash(slots: {
     paperColor: PropRef;
     strength: PropRef;
 }): GatherEffect;
-/** The Sobel ring: the two 4-luma bundles around the centre tap, plus the centre sample itself. */
+/** The ring of edge samples `sobelTaps` builds around each pixel. Pass it to `chalkSketch`. */
 export type SobelRing = (params: RttFilterParams) => {
     sobelA: Expr;
     sobelB: Expr;
@@ -64,17 +96,33 @@ export type SobelRing = (params: RttFilterParams) => {
     centreLum: Expr;
 };
 /**
- * The Sobel tap ring: 8 straight-alpha tap luminances at `spacing` around the fragment (packed
- * `[tl, t, tr, l]` / `[r, bl, b, br]`), plus the centre sample and its luminance. Multi-tap → a
- * true gather, not a uvRemap candidate.
+ * Eight brightness samples in a ring around each pixel, for finding edges.
+ *
+ * `spacing` is the distance to the ring in device pixels (about 0.5 to 4; thicker strokes at
+ * larger values). Returns the ring for `chalkSketch`.
+ *
+ * @example
+ * ```ts
+ * edges: sobelTaps({spacing: p('edgeThickness')})
+ * ```
+ * @see chalkSketch
  */
 export declare function sobelTaps(slots: {
     spacing: PropRef;
 }): SobelRing;
 /**
- * The chalk-sketch compose gather recipe: the Sobel edge magnitude from the ring becomes the
- * stroke outline, cross-hatch line families fill darker regions, and value-noise dust breaks up
- * the strokes over the board colour. Straight alpha throughout (every tap is unpremultiplied).
+ * The chalk-drawing look: edges become chalk strokes and dark areas fill with cross-hatching.
+ *
+ * Closes the recipe and returns the effect for `effect:`. `sensitivity` (0 to 1) sets how faint
+ * an edge still draws. `hatchScale` is the hatch line spacing in device pixels. `shading` (0 to
+ * 1) is how much cross-hatch fills the dark regions and `grain` (0 to 1) how dusty the strokes
+ * are. `board` and `chalk` are colors. Alpha follows the layer inside.
+ *
+ * @example
+ * ```ts
+ * effect: chalkSketch({edges: sobelTaps({spacing: p('edgeThickness')}), sensitivity: p('edgeSensitivity'), hatchScale: p('hatchScale'), shading: p('shading'), grain: p('grain'), board: p('boardColor'), chalk: p('chalkColor')})
+ * ```
+ * @see sobelTaps, linework
  */
 export declare function chalkSketch(slots: {
     edges: SobelRing;
@@ -85,25 +133,53 @@ export declare function chalkSketch(slots: {
     board: PropRef;
     chalk: PropRef;
 }): GatherEffect;
-/** One custom-tier fragment stage. */
+/** A stage of the ASCII look: one value per pixel, computed in the fragment. */
 export type FragmentStage = (params: GpuFragmentParams) => Expr;
 /**
- * The character grid frame: the cell struct (`cellCenter`, `cellUV`, `isOutside`) shared by the
- * cell sample, the glyph lookup, and the tint.
+ * The character grid: which cell each pixel falls in, and where it sits inside that cell.
+ *
+ * `cellSize` is the cell size in pixels on a 1080-pixel-tall canvas; it scales with the canvas
+ * height. `spacing` is how much of the cell the character fills (1 fills it). Build it once and
+ * share it with `cellSample`, `glyphFor` and `glyphTint`.
+ *
+ * @example
+ * ```ts
+ * const grid = charGrid({cellSize: p('cellSize'), spacing: p('spacing')})
+ * ```
+ * @see cellSample, glyphFor, glyphTint
  */
 export declare function charGrid(slots: {
     cellSize: PropRef;
     spacing: PropRef;
 }): FragmentStage;
-/** The per-cell child colour: the child sampled once at the cell centre, unpremultiplied. */
+/**
+ * The color of the layer inside at the centre of each character cell.
+ *
+ * One sample per cell, straight alpha. Feeds `glyphFor` (to pick the character) and `glyphTint`
+ * (to color it).
+ *
+ * @example
+ * ```ts
+ * const cell = cellSample({grid})
+ * ```
+ * @see charGrid, glyphFor
+ */
 export declare function cellSample(slots: {
     grid: FragmentStage;
 }): FragmentStage;
 /**
- * The glyph lookup: the cell brightness (gamma-curved) picks a glyph from the CPU-rasterised
- * atlas, sampled nearest/clamped at the cell-local UV. Requires the
- * `_charCount`/`_atlasScale`/`_atlasSize` extraFields on the definition; the `atlas` slot runs
- * the host raster lifecycle at composition time and returns the glyph texture.
+ * The character drawn in each cell, picked by how bright the cell is.
+ *
+ * `gamma` bends the brightness curve: below 1 favours the light characters, above 1 the dark
+ * ones. `atlas` is your function that draws the character set into a texture and returns it
+ * (the Ascii shader shows one). The definition needs three extra fields the atlas fills in:
+ * `_charCount`, `_atlasScale` and `_atlasSize`.
+ *
+ * @example
+ * ```ts
+ * glyph: glyphFor({grid, cell, gamma: p('gamma'), atlas: setupGlyphAtlas})
+ * ```
+ * @see glyphTint, cellSample
  */
 export declare function glyphFor(slots: {
     grid: FragmentStage;
@@ -112,9 +188,17 @@ export declare function glyphFor(slots: {
     atlas: (params: GpuFragmentParams) => KitTexture;
 }): FragmentStage;
 /**
- * The glyph tint compose: the glyph shaped by the cell colour, with background / out-of-bounds /
- * below-threshold pixels turned transparent. Returns the fragment closure for the custom tier's
- * `gpu.fragment`.
+ * The finished ASCII look: each character tinted with its cell's color, everything else transparent.
+ *
+ * Returns the fragment for `gpu.fragment`. Cells whose alpha is below `alphaThreshold` (0 to 1)
+ * turn transparent. With `preserveAlpha` on, the output keeps the alpha of the layer inside;
+ * off, visible characters are fully opaque.
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: glyphTint({grid, cell, glyph, alphaThreshold: p('alphaThreshold'), preserveAlpha: p('preserveAlpha')})}
+ * ```
+ * @see glyphFor, charGrid
  */
 export declare function glyphTint(slots: {
     grid: FragmentStage;
@@ -123,45 +207,30 @@ export declare function glyphTint(slots: {
     alphaThreshold: PropRef;
     preserveAlpha: PropRef;
 }): FragmentStage;
-/**
- * Oriented-box placement field: aspect-corrected screen UV → rotated box-local UV + inside mask.
- * `center` is the TRANSFORMED position prop (transformPosition stores (x, 1-y)), so `1 - center.y`
- * recovers the authored y. Returns vec3(localU, localV, insideMask); the consumer samples its
- * content texture at `.xy` and gates by `.z`. No V-flip — media textures written via
- * `copyExternalImageToTexture` are top-left origin, matching the local V directly.
- */
+/** @internal The oriented-box placement kernel behind the Text shader. */
 export declare const orientedBoxField: import('typegpu').TgpuFn<(uv: d.Vec2f, aspect: d.F32, center: d.Vec2f, rotationDeg: d.F32, halfW: d.F32, halfH: d.F32) => d.Vec3f>;
-/**
- * One hatched line plate. Lines run along `angleDeg`; the coordinate perpendicular to them
- * carries a cosine wave whose crests are inked. `level` (0 = black, 1 = white) slides the ink
- * threshold across the wave, so darker tone → wider ink until the lines merge to solid;
- * `reliefPhase` shifts the wave with image brightness — the classic engraved "lines climb over
- * the form" look. `aa` is the analytic per-pixel wave footprint used for the smoothstep edge.
- */
+/** @internal One hatched line plate of the engraving; `linework` is the word. */
 export declare const hatchPlate: import('typegpu').TgpuFn<(p: d.Vec2f, angleDeg: d.F32, frequency: d.F32, reliefPhase: d.F32, level: d.F32, aa: d.F32) => d.F32>;
-/**
- * The spiral plate: an Archimedean spiral around `c` — rings spaced 1/frequency apart, each
- * advancing one full spacing per turn, so the line spirals continuously outward from the centre
- * (the classic guilloché portrait cut). Same tonal threshold + relief displacement as the
- * straight plate; the angular term's footprint grows toward the centre, so the spiral naturally
- * tightens into a dense knot there.
- */
+/** @internal The spiral plate of the engraving; `linework` is the word. */
 export declare const spiralPlate: import('typegpu').TgpuFn<(p: d.Vec2f, c: d.Vec2f, frequency: d.F32, reliefPhase: d.F32, level: d.F32, aa: d.F32) => d.F32>;
-/**
- * The linework composite (factory — `style` is a compile-time JS branch: 0 = single line plate,
- * 1 = cross-hatch (base + a +72° plate engaging in the shadows + a −38° plate in the deepest
- * blacks — the classic copper-plate build-up), 2 = one continuous spiral cut around `center`).
- *
- * Shared tonal front-end: pivot-0.5 contrast curve on luminance, wavy burin-stroke domain warp,
- * analytic AA, brightness→phase relief — then the style's plate stack inked between `paper`
- * and `ink`. p0 = (angleDeg, frequency, relief, waviness); p1 = (contrast, viewportY, 0, 0).
- */
+/** @internal The per-style engraving composite factory behind `linework`. */
 export declare function makeLineworkComposite(style: number): import('typegpu').TgpuFn<(childColor: d.Vec4f, uv: d.Vec2f, aspect: d.F32, paper: d.Vec4f, ink: d.Vec4f, center: d.Vec2f, p0: d.Vec4f, p1: d.Vec4f) => d.Vec4f>;
 /**
- * Line-engraving gather noun: sample the composed child once (unpremultiplied) and redraw it as
- * luminance-displaced line work between `paper` and `ink`. `style` binds a compile-time prop —
- * exactly one plate stack is emitted per composition. The composite works on and returns
- * STRAIGHT alpha, so no unpremultiply tail is appended.
+ * The engraving look: the layer inside redrawn as ink lines that swell where it is dark.
+ *
+ * Closes the recipe and returns the effect for `effect:`. `style` is a compile-time select:
+ * `'line'` (one set of parallel lines), `'crosshatch'` (more sets appear in the shadows) or
+ * `'spiral'` (one line coiling out from `center`, a position prop). `frequency` is how many
+ * lines span the canvas height. `angle` is in degrees. `relief` (0 to 2) is how far brightness
+ * pushes the lines sideways, `waviness` (0 to 1) how much they meander, and `contrast` (0.25 to
+ * 3) the tone curve before inking. `ink` and `paper` are colors.
+ *
+ * @example
+ * ```ts
+ * effect: linework({style: p('style'), frequency: p('frequency'), angle: p('angle'), center: p('center'), relief: p('relief'), waviness: p('waviness'), contrast: p('contrast'), ink: p('inkColor'), paper: p('paperColor')})
+ * ```
+ * @tip Set `blendWithChildren: false` on the definition. The lines replace the layer rather than sit on it.
+ * @see chalkSketch
  */
 export declare function linework(slots: {
     style: PropRef;

package/dist/core/std/effects/stylize.d.ts.map

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