@mkbabb/glass-ui 8.0.0 → 9.0.0

package/dist/components/fourier-field/renderer/mint.d.ts

@@ -0,0 +1,50 @@
+import { type BasisComponent } from "../math.js";
+/**
+ * The reference stage diagonal in device px — the derivation is on the line above. Every
+ * axis maximum in the tree is this number's consequence, so it is declared once.
+ */
+export declare const FOURIER_REFERENCE_DIAGONAL_PX = 856;
+/** A term survives the mint iff it moves the curve at least this far at the reference stage. */
+export declare const FOURIER_PAINT_FLOOR_PX = 0.5;
+/**
+ * A minted spectrum: the DC anchor, the amplitude-ordered surviving terms, and the model
+ * geometry the fit and the ring law both read. Immutable and reference-stable — the
+ * renderer's re-upload guard is an identity check against this object.
+ */
+export interface MintedSpectrum {
+    /** The amplitude-ordered, paint-floored terms. `length` IS the N axis maximum. */
+    readonly terms: readonly BasisComponent[];
+    /** The hoisted DC term (the curve's centroid) — the anchor the scene is centred on. */
+    readonly dc: readonly [number, number];
+    /** The full reconstruction's bbox half-extents in model units (DC removed). */
+    readonly halfSpanX: number;
+    readonly halfSpanY: number;
+    /** The bbox centre in model units (DC removed) — the fit's centre. */
+    readonly centerX: number;
+    readonly centerY: number;
+    /** The bbox diagonal in model units — the reference-stage mapping's denominator. */
+    readonly diagonal: number;
+    /** `Σ|c_k|` over the terms — the chain's maximum reach from the centre. */
+    readonly chainReach: number;
+}
+/**
+ * Mint a raw spectrum into the shipped one. The input is anything `dftFromPoints`,
+ * `makeHarmonicFigure` or `makeEllipticSpectrum` produced; the output is what the GPU
+ * ever sees.
+ *
+ * Deterministic: the same input array yields the same output, term for term. An empty or
+ * all-sub-floor input still emits its single largest term — a spectrum that draws nothing
+ * is not a fallback, it is a blank stage, and the machine must always have one ring.
+ */
+export declare function mintSpectrum(raw: readonly BasisComponent[]): MintedSpectrum;
+/**
+ * THE RING LAW. A ring is DRAWN iff its own diameter reaches the mark's stroke at the
+ * LIVE stage: `2·|c_k| ≥ markStroke`, both sides in device pixels. Below that rung the
+ * term is still SUMMED and still CHAINED — the scaffold arm and the joint dot stay — only
+ * the circle outline elides, because a circle narrower than the line drawing it is a blob,
+ * not a circle.
+ *
+ * This is why the machine reads at every size with ZERO media queries: the question is
+ * asked of the stage the component is actually in.
+ */
+export declare function ringsAt(minted: MintedSpectrum, stageDiagonalDevicePx: number, markStrokeDevicePx: number): number;

package/dist/components/fourier-field/renderer/uniforms.d.ts

@@ -0,0 +1,84 @@
+import { type OklchStop } from "../../../composables/color/index.js";
+import type { BasisComponent } from "../math.js";
+import type { MintedSpectrum } from "./mint.js";
+/** One phasor lane in the storage buffer: (re, im, index, _pad). */
+export declare const FOURIER_PHASOR_BYTES = 16;
+export interface FourierUniformScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+    i32: Int32Array;
+}
+export declare function createFourierComputeScratch(): FourierUniformScratch;
+export declare function packFourierComputeUniforms(scratch: FourierUniformScratch, headT: number, trailArc: number, harmonicN: number, sampleCount: number, termCount: number): FourierUniformScratch;
+export declare function createFourierRenderScratch(): FourierUniformScratch;
+/** The model→clip fit transform — computed once per spectrum, never per N edit. */
+export interface FourierFit {
+    centerX: number;
+    centerY: number;
+    /** The uniform scale s mapping (model − center)·s into clip [-1,1] with margin. */
+    scale: number;
+}
+/**
+ * The view fit, read straight off the mint. It unions the curve's own bbox with the
+ * chain's reach when the machine shows, because a chain that leaves the stage is a
+ * machine you cannot check. It is FIXED under N: the mint is the only input, so an N edit
+ * never rescales the figure and the "N=1 is genuinely this big" claim stays true.
+ */
+export declare function computeFourierFit(minted: MintedSpectrum, showMachine: boolean): FourierFit;
+/**
+ * Convert a CSS-px stroke to MODEL units. The fit maps model → clip; clip spans [-1,1]
+ * over the min CSS dimension, so cssPx-per-clip is `canvasCssMin/2`.
+ */
+export declare function strokeToModel(strokePx: number, scale: number, canvasCssMin: number): number;
+/**
+ * The resolved ramp: a linear-sRGB LUT plus the two derived pigments the paint law names.
+ * Rebuilt only when the palette itself changes.
+ */
+export interface FourierRamp {
+    /** `FOURIER_LUT_SIZE` linear-sRGB entries, index 0 the ramp head. */
+    readonly lut: Float32Array;
+    /** The ink: the ramp head one step DOWN in L, gamut-mapped at fixed L and hue. */
+    readonly ink: [number, number, number];
+    /** The head core: the ramp head lifted by half a step, chroma preserved. */
+    readonly head: [number, number, number];
+}
+/**
+ * Resolve a palette into the shipped ramp. Chroma is floored at every entry — a ramp that
+ * falls to grey paints a smear where the tail should still be pigment — and every entry
+ * is gamut-mapped, so an out-of-gamut author stop becomes a real colour rather than a
+ * clipped one.
+ */
+export declare function resolveFourierRamp(palette: readonly OklchStop[]): FourierRamp;
+export interface FourierRenderPack {
+    fit: FourierFit;
+    aspect: number;
+    markHalfModel: number;
+    inkOffsetStrokes: number;
+    scaffoldFrac: number;
+    edgeMargin: number;
+    peakAlpha: number;
+    glow: number;
+    squash: number;
+    trailFadeExp: number;
+    trailFloor: number;
+    hueSweep: number;
+    ringStrokeModel: number;
+    showMachine: boolean;
+    rainbowChain: boolean;
+    sampleCount: number;
+    /** The number of chain arms this frame draws — the hue sweep's denominator. */
+    chainCount: number;
+    ramp: FourierRamp;
+}
+/**
+ * Pack the render uniforms in place. `peakAlpha` arrives already multiplied by the
+ * intensity envelope and CLAMPED here — the one place loudness can leave the legal range,
+ * closed at pack time so no fragment can composite past 1.
+ */
+export declare function packFourierRenderUniforms(scratch: FourierUniformScratch, p: FourierRenderPack): FourierUniformScratch;
+/**
+ * Pack the phasor storage table (re, im, index, _pad) from the minted spectrum. The
+ * buffer is sized per-spectrum by the caller — there is no table ceiling, so a 61-term ℱ
+ * and a 2-term foil each pay for exactly what they carry.
+ */
+export declare function packPhasorTable(terms: readonly BasisComponent[]): Float32Array;

package/dist/components/fourier-field/renderer/wgpu.d.ts

@@ -0,0 +1,28 @@
+import type { WebGPUCanvasFrame } from "../../../composables/glass/webgpu/useWebGPUCanvas.js";
+import type { WebGLCanvasFrame } from "../../../composables/glass/webgl/useWebGLCanvas.js";
+import type { OklchStop } from "../../../composables/color/index.js";
+import { type FourierFieldConfig } from "../constants.js";
+import type { MintedSpectrum } from "./mint.js";
+export interface FourierRendererDeps {
+    canvas: HTMLCanvasElement;
+    config: FourierFieldConfig;
+    /** The minted spectrum — re-read each frame; identity change triggers the re-upload. */
+    getSpectrum: () => MintedSpectrum;
+    /** The resolved palette stops, re-read each frame so a live edit reaches the ramp. */
+    getPalette: () => OklchStop[];
+    /** The single loop parameter `head_t ∈ [0,1)`. */
+    getHeadT: () => number;
+    /** Demand-gate (the renderer's quiescence layer). */
+    shouldContinue: () => boolean;
+    /** The per-frame hook — the clock advances here, inside the substrate's own frame. */
+    onFrame?: (timeSec: number) => void;
+}
+/** Build the fourier-field `setupWGPU(device, context, format)` callback. */
+export declare function createFourierWGPUSetup(deps: FourierRendererDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
+/**
+ * The WebGL2 seam, declared closed. The substrate picker requires a `setupGL`; this one
+ * acquires nothing and draws nothing — it throws the sentence above, which the picker
+ * surfaces as a renderer error. The result is exactly what the law asks for: no second
+ * renderer, zero canvas pixels, and a status a consumer can read and show.
+ */
+export declare function createFourierUnsupportedSetup(): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

package/dist/components/fourier-field/shaders/compute.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const FOURIER_FIELD_COMPUTE_WGSL = "\nconst TAU: f32 = 6.283185307179586;\n\nstruct Phasor {\n  // (re, im, index, _pad)\n  data: vec4<f32>,\n};\n\nstruct ComputeUniforms {\n  // c0: (headT, trailArc, _pad, _pad)\n  c0: vec4<f32>,\n  // ints: (harmonicN, sampleCount, termCount, _pad)\n  ints: vec4<i32>,\n};\n\n@group(0) @binding(0) var<uniform> u: ComputeUniforms;\n@group(0) @binding(1) var<storage, read> phasors: array<Phasor>;\n// curveSamples[i] = (x, y, age, _pad) in MODEL space\n@group(0) @binding(2) var<storage, read_write> curveSamples: array<vec4<f32>>;\n// chainTips[k] = (x, y, _pad, _pad) in MODEL space\n@group(0) @binding(3) var<storage, read_write> chainTips: array<vec4<f32>>;\n\n// The truncated inverse DFT at parameter t over the first n terms \u2014 the transcription of\n// math.ts partialSumAt:  c += vec2(re*cos - im*sin, re*sin + im*cos), angle = TAU*index*t.\nfn partialSumAt(t: f32, n: i32) -> vec2<f32> {\n  var c = vec2<f32>(0.0, 0.0);\n  let lim = min(n, i32(arrayLength(&phasors)));\n  for (var i = 0; i < lim; i = i + 1) {\n    let p = phasors[i].data;\n    let angle = TAU * p.z * t;\n    let cs = cos(angle);\n    let sn = sin(angle);\n    c = c + vec2<f32>(p.x * cs - p.y * sn, p.x * sn + p.y * cs);\n  }\n  return c;\n}\n\n@compute @workgroup_size(64)\nfn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let i = i32(gid.x);\n  let headT = u.c0.x;\n  let trailArc = u.c0.y;\n  let harmonicN = u.ints.x;\n  let sampleCount = u.ints.y;\n\n  // \u2500\u2500 The comet body \u2500\u2500\n  if (i < sampleCount) {\n    let denom = max(f32(sampleCount - 1), 1.0);\n    let frac = f32(i) / denom;                  // 0 = head, 1 = tail\n    let age = 1.0 - frac;                       // 1 = head, 0 = tail\n    var t = headT - trailArc * frac;\n    t = t - floor(t);                           // fract -> [0,1)\n    let pt = partialSumAt(t, harmonicN);\n    curveSamples[i] = vec4<f32>(pt.x, pt.y, age, 0.0);\n  }\n\n  // \u2500\u2500 The chain tips (k = 0..N). chainTips[0] is the origin. \u2500\u2500\n  if (i <= harmonicN && i < i32(arrayLength(&chainTips))) {\n    let tip = partialSumAt(headT, i);\n    chainTips[i] = vec4<f32>(tip.x, tip.y, 0.0, 0.0);\n  }\n}\n";

package/dist/components/fourier-field/shaders/render.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const FOURIER_FIELD_RENDER_WGSL = "\n// 0 chain \u00B7 1 trail \u00B7 2 head \u2014 a pipeline-overridable constant, three pipelines, one module.\noverride LAYER: i32 = 0;\n\n// THE SPLICE CONTRACT, honoured. OKLCH_MATRICES_WGSL states it at color.wgsl.ts:52-53 \u2014\n// \"PI must be in scope (the consumer defines it first, as the GLSL chunk requires)\" \u2014 and\n// spends it at :105 folding the OKLCh hue to [0, 2pi). This module splices that chunk\n// below and defined PI nowhere, so every CreateShaderModule on this source failed\n// validation with \"unresolved value 'PI'\" and the stage painted NOTHING. The two other\n// WGSL primaries carry the same line for the same reason (aurora.wgsl.ts:49,\n// metaball.wgsl.ts:53); this is that house idiom, not a local patch. The CLASS is gated\n// by tests/components/fourier-field/wgsl-splice-contract.test.ts, which resolves every\n// assembled module against the chunks it splices.\nconst PI: f32 = 3.141592653589793;\n\nconst TANGENT_EPS: f32 = 1e-4;\nconst SPEED_REF_HALFWIDTHS: f32 = 6.0;\n// The trail's taper: the mark keeps this fraction of its width at the oldest tail.\nconst TAIL_TAPER: f32 = 0.55;\n\nstruct RenderUniforms {\n  // r0: (centerX, centerY, scale, aspect)\n  r0: vec4<f32>,\n  // r1: (markHalf, inkOffsetStrokes, scaffoldFrac, edgeMargin)\n  r1: vec4<f32>,\n  // r2: (peakAlpha, glow, squash, trailFadeExp)\n  r2: vec4<f32>,\n  // r3: (trailFloor, hueSweep, ringStrokeModel, showMachine)\n  r3: vec4<f32>,\n  // ink: (linear rgb, rainbowChain)\n  ink: vec4<f32>,\n  // head: (linear rgb, _pad)\n  head: vec4<f32>,\n  // ints: (sampleCount, lutSize, chainCount, _pad)\n  ints: vec4<i32>,\n  // the CPU-resolved linear-sRGB ramp \u2014 the length is the TS constant, not a second copy\n  lut: array<vec4<f32>, 16>,\n};\n\n@group(0) @binding(0) var<uniform> u: RenderUniforms;\n@group(0) @binding(1) var<storage, read> curveSamples: array<vec4<f32>>;\n@group(0) @binding(2) var<storage, read> chainTips: array<vec4<f32>>;\n\n\nfn srgbToLinearCh(c: f32) -> f32 {\n  if (c <= 0.04045) { return c / 12.92; }\n  return pow((c + 0.055) / 1.055, 2.4);\n}\nfn srgbToLinear(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfn linearToSrgbCh(c: f32) -> f32 {\n  if (c <= 0.0031308) { return c * 12.92; }\n  return 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nfn linearToSrgb(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// value.js LINEAR_SRGB_TO_LMS, row-major \u2192 WGSL columns (= the transpose).\nconst LINEAR_SRGB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  0.4122214708, 0.2119034982, 0.0883024619,\n  0.5363325363, 0.6806995451, 0.2817188376,\n  0.0514459929, 0.1073969566, 0.6299787005\n);\n\n// value.js srgbToOKLab's INLINE LMS\u2192OKLab coefficients, row-major \u2192 WGSL columns.\nconst LMS_TO_OKLAB: mat3x3<f32> = mat3x3<f32>(\n  0.2104542553, 1.9779984951, 0.0259040371,\n  0.7936177850, -2.4285922050, 0.7827717662,\n  -0.0040720468, 0.4505937099, -0.8086757660\n);\n\n// value.js OKLAB_TO_LMS_COEFF, row-major \u2192 WGSL columns.\nconst OKLAB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  1.0, 1.0, 1.0,\n  0.3963377774, -0.1055613458, -0.0894841775,\n  0.2158037573, -0.0638541728, -1.2914855480\n);\n\n// value.js LMS_TO_LINEAR_SRGB, row-major \u2192 WGSL columns.\nconst LMS_TO_LINEAR_SRGB: mat3x3<f32> = mat3x3<f32>(\n  4.0767416621, -1.2684380046, -0.0041960863,\n  -3.3077115913, 2.6097574011, -0.7034186147,\n  0.2309699292, -0.3413193965, 1.7076147010\n);\n\nfn cbrt3(v: vec3<f32>) -> vec3<f32> {\n  return sign(v) * pow(abs(v), vec3<f32>(1.0 / 3.0));\n}\n\n// Gamma sRGB \u2192 raw OKLab (L, a, b). Mirrors value.js srgbToOKLab.\nfn srgbToOklab(c: vec3<f32>) -> vec3<f32> {\n  let lin = srgbToLinear(c);\n  let lms = LINEAR_SRGB_TO_LMS * lin;\n  return LMS_TO_OKLAB * cbrt3(lms);\n}\n\n// Raw OKLab (L, a, b) \u2192 linear sRGB. Mirrors value.js oklabToLinearSRGB.\nfn oklabToLinearSrgb(lab: vec3<f32>) -> vec3<f32> {\n  let lms_ = OKLAB_TO_LMS * lab;\n  let lms = lms_ * lms_ * lms_;\n  return LMS_TO_LINEAR_SRGB * lms;\n}\n\n// OKLab \u2192 OKLCh: H in RADIANS, folded to [0, 2pi). Mirrors value.js rawOklabToOklch.\nfn oklabToOklch(lab: vec3<f32>) -> vec3<f32> {\n  let C = length(lab.yz);\n  var H = atan2(lab.z, lab.y);\n  if (H < 0.0) { H = H + 2.0 * PI; }\n  return vec3<f32>(lab.x, C, H);\n}\n\n// OKLCh (H radians) \u2192 OKLab. Mirrors value.js rawOklchToOklab.\nfn oklchToOklab(lch: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(lch.x, lch.y * cos(lch.z), lch.y * sin(lch.z));\n}\n\n// Read the CPU-resolved ramp. No colour-space conversion happens here \u2014 the LUT already\n// carries the chroma floor and the gamut map.\nfn sampleRamp(t: f32) -> vec3<f32> {\n  let n = u.ints.y;\n  let ft = clamp(t, 0.0, 1.0) * f32(n - 1);\n  let i0 = i32(floor(ft));\n  let i1 = min(i0 + 1, n - 1);\n  return mix(u.lut[i0].rgb, u.lut[i1].rgb, ft - f32(i0));\n}\n\n// The chain's hue sweep, taken ONCE PER INSTANCE in the vertex stage: the ramp entry for\n// this arm, rotated about the palette anchor by \u00B1hueSweep. Anchored warm, the sweep is\n// bounded by its own arithmetic \u2014 it cannot arrive anywhere the palette is not.\nfn chainTint(seg: f32) -> vec3<f32> {\n  let base = sampleRamp(seg * 0.6);\n  if (u.ink.w < 0.5) { return base; }\n  let lab = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * base);\n  let lch = oklabToOklch(lab);\n  let swept = vec3<f32>(lch.x, lch.y, lch.z + mix(-u.r3.y, u.r3.y, clamp(seg, 0.0, 1.0)));\n  return oklabToLinearSrgb(oklchToOklab(swept));\n}\n\nfn segDist(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>) -> f32 {\n  let pa = p - a;\n  let ba = b - a;\n  let h = clamp(dot(pa, ba) / max(dot(ba, ba), 1e-8), 0.0, 1.0);\n  return length(pa - ba * h);\n}\n\n// The head's travel frame + its volume-preserving anisotropic metric.\nstruct HeadFrame { T: vec2<f32>, sHat: f32, };\nfn headFrame(head: vec2<f32>, back: vec2<f32>, halfW: f32) -> HeadFrame {\n  let d = head - back;\n  let s = length(d);\n  var out: HeadFrame;\n  if (s <= TANGENT_EPS) {\n    out.T = vec2<f32>(1.0, 0.0);\n    out.sHat = 0.0;\n    return out;\n  }\n  out.T = d / s;\n  out.sHat = clamp(s / max(halfW * SPEED_REF_HALFWIDTHS, 1e-6), 0.0, 1.0);\n  return out;\n}\n\nfn headAniso(p: vec2<f32>, head: vec2<f32>, fr: HeadFrame, k: f32) -> f32 {\n  let g = 1.0 + k * fr.sHat;\n  let n = vec2<f32>(-fr.T.y, fr.T.x);\n  let rel = p - head;\n  return length(vec2<f32>(dot(rel, fr.T) / g, dot(rel, n) * g));\n}\n\nfn quadCorner(vi: u32) -> vec2<f32> {\n  var c = array<vec2<f32>, 6>(\n    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 0.0), vec2<f32>(0.0, 1.0),\n    vec2<f32>(0.0, 1.0), vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 1.0),\n  );\n  return c[vi];\n}\n\nstruct VSOut {\n  @builtin(position) pos: vec4<f32>,\n  @location(0) p: vec2<f32>,\n  @location(1) a: vec2<f32>,\n  @location(2) b: vec2<f32>,\n  // (age, strokeHalf, drawRing)\n  @location(3) seg: vec3<f32>,\n  @location(4) @interpolate(flat) tint: vec3<f32>,\n};\n\n@vertex\nfn vs_main(@builtin(vertex_index) vi: u32, @builtin(instance_index) inst: u32) -> VSOut {\n  let corner = quadCorner(vi);\n  let center = u.r0.xy;\n  let scale = max(u.r0.z, 1e-6);\n  let aspect = max(u.r0.w, 1e-4);\n  let markHalf = u.r1.x;\n  let margin = u.r1.w;\n\n  var a = vec2<f32>(0.0);\n  var b = vec2<f32>(0.0);\n  var strokeHalf = markHalf;\n  var age = 0.0;\n  var drawRing = 0.0;\n  var tint = vec3<f32>(0.0);\n  var isCapsule = true;\n  var ext = markHalf;\n\n  if (LAYER == 0) {\n    // CHAIN \u2014 the AABB around this arm's own orbit (radius = |b \u2212 a| = |c_k|).\n    a = chainTips[inst].xy;\n    b = chainTips[inst + 1u].xy;\n    let radius = length(b - a);\n    // THE RING LAW, asked of the live stage: a circle narrower than its own line is a blob.\n    if (2.0 * radius >= u.r3.z) { drawRing = 1.0; }\n    strokeHalf = markHalf * u.r1.z;\n    tint = chainTint(f32(inst) / max(f32(u.ints.z) - 1.0, 1.0));\n    ext = radius + strokeHalf * 2.0;\n    isCapsule = false;\n  } else if (LAYER == 1) {\n    // TRAIL \u2014 the curve capsule, padded for the ink's own offset.\n    a = curveSamples[inst].xy;\n    b = curveSamples[inst + 1u].xy;\n    age = max(curveSamples[inst].z, curveSamples[inst + 1u].z);\n    tint = sampleRamp(1.0 - age);\n    ext = markHalf * (1.0 + 2.0 * max(u.r1.y, 0.0));\n    isCapsule = true;\n  } else {\n    // HEAD \u2014 centred on the newest curve sample; the AABB is the halo.\n    a = curveSamples[0].xy;\n    b = curveSamples[1].xy;\n    tint = u.head.rgb;\n    ext = markHalf * 5.0;\n    isCapsule = false;\n  }\n  ext = ext + margin;\n\n  var pos: vec2<f32>;\n  if (isCapsule) {\n    let d = b - a;\n    let len = length(d);\n    var dir = vec2<f32>(1.0, 0.0);\n    if (len > 1e-6) { dir = d / len; }\n    let perp = vec2<f32>(-dir.y, dir.x);\n    pos = mix(a - dir * ext, b + dir * ext, corner.x) + perp * (corner.y * 2.0 - 1.0) * ext;\n  } else {\n    pos = a + (corner * 2.0 - vec2<f32>(1.0)) * ext;\n  }\n\n  var out: VSOut;\n  out.pos = vec4<f32>((pos.x - center.x) * scale / aspect, (pos.y - center.y) * scale, 0.0, 1.0);\n  out.p = pos;\n  out.a = a;\n  out.b = b;\n  out.seg = vec3<f32>(age, strokeHalf, drawRing);\n  out.tint = tint;\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4<f32> {\n  let p = in.p;\n  let aa = max(fwidth(p.x) + fwidth(p.y), 1e-5) * 0.75;\n  let peak = u.r2.x;\n  let glow = u.r2.y;\n  let squash = u.r2.z;\n  let fadeExp = u.r2.w;\n  let trailFloor = u.r3.x;\n  let markHalf = u.r1.x;\n  let strokeHalf = in.seg.y;\n  let age = in.seg.x;\n  let a = in.a;\n  let b = in.b;\n\n  if (LAYER == 0) {\n    // \u2500\u2500 THE MACHINE \u2014 ring (conditionally), arm, joint dot; one scaffold rung \u2500\u2500\n    let radius = length(b - a);\n    var m = 0.0;\n    if (in.seg.z > 0.5) {\n      let dRing = abs(length(p - a) - radius);\n      m = max(m, 1.0 - smoothstep(strokeHalf, strokeHalf + aa, dRing));\n    }\n    m = max(m, 1.0 - smoothstep(strokeHalf, strokeHalf + aa, segDist(p, a, b)));\n    // The joint dot is the mark's own diameter \u2014 the machine's one solid rung.\n    m = max(m, 1.0 - smoothstep(markHalf, markHalf + aa, length(p - a)));\n    let alpha = clamp(m, 0.0, 1.0) * peak;\n    let rgb = clamp(linearToSrgb(in.tint), vec3<f32>(0.0), vec3<f32>(1.0));\n    return vec4<f32>(rgb * alpha, alpha);\n  } else if (LAYER == 1) {\n    // \u2500\u2500 THE CURVE \u2014 ink under mark, composited at \u03B11, then ONE envelope \u2500\u2500\n    let taper = TAIL_TAPER + (1.0 - TAIL_TAPER) * age;\n    let half = markHalf * taper;\n    // The ink rides THIS segment's own tangent, opposite the travel: the head runs from\n    // b toward a, so the ink lands behind at (b \u2212 a).\n    var dir = vec2<f32>(1.0, 0.0);\n    let d = b - a;\n    let len = length(d);\n    if (len > 1e-6) { dir = d / len; }\n    let off = dir * (markHalf * 2.0 * u.r1.y);\n\n    let aMark = 1.0 - smoothstep(half, half + aa, segDist(p, a, b));\n    let aInk = 1.0 - smoothstep(half, half + aa, segDist(p, a + off, b + off));\n\n    let markRgb = clamp(linearToSrgb(in.tint), vec3<f32>(0.0), vec3<f32>(1.0));\n    let inkRgb = clamp(linearToSrgb(u.ink.rgb), vec3<f32>(0.0), vec3<f32>(1.0));\n\n    // Mark OVER ink, both fully opaque where they cover \u2014 the pair, then the envelope.\n    let aPair = aMark + aInk * (1.0 - aMark);\n    let rgbPair = markRgb * aMark + inkRgb * aInk * (1.0 - aMark);\n    let env = peak * max(pow(max(age, 0.0), fadeExp), trailFloor);\n    return vec4<f32>(rgbPair * env, aPair * env);\n  } else {\n    // \u2500\u2500 THE HEAD \u2014 palette-lifted core over its own halo. Light-led, never white. \u2500\u2500\n    let fr = headFrame(a, b, markHalf);\n    let dHead = headAniso(p, a, fr, squash);\n    let coreR = markHalf * 1.5;\n    let haloR = coreR * 3.0;\n    let rgb = clamp(linearToSrgb(in.tint), vec3<f32>(0.0), vec3<f32>(1.0));\n    let halo = (1.0 - smoothstep(0.0, haloR, dHead)) * glow;\n    let core = (1.0 - smoothstep(coreR, coreR + aa, dHead)) * peak;\n    let alpha = clamp(max(core, halo), 0.0, 1.0);\n    return vec4<f32>(rgb * alpha, alpha);\n  }\n}\n";

package/dist/components/fourier-field/useFourierField.d.ts

@@ -0,0 +1,49 @@
+import { type Ref } from "vue";
+import { type GpuBackend, type RendererStatus } from "../../composables/glass/webgpu/useGpuSubstrate.js";
+import type { OklchStop } from "../../composables/color/index.js";
+import { type FourierFieldConfig } from "./constants.js";
+import type { MintedSpectrum } from "./renderer/mint.js";
+export interface UseFourierFieldOptions {
+    config: FourierFieldConfig;
+    /** The minted spectrum (identity-stable until the source or seed changes). */
+    getSpectrum: () => MintedSpectrum;
+    /** The resolved palette stops as OKLCh. */
+    getPalette: () => OklchStop[];
+    /**
+     * Whether the pointer drives the clock. ONE authority — the component's own
+     * `interactive` prop — read live rather than copied into the config.
+     */
+    interactive: () => boolean;
+    /** Hold the clock at its current parameter and never advance. */
+    freeze?: () => boolean;
+    /** `"capture"` → renderAt-only (the deterministic capture path). Default `"live"`. */
+    mode?: "live" | "capture";
+}
+/** The handle a consumer wires its lifecycle and its transport against. */
+export interface FourierFieldHandle {
+    /** The resolved backend. Always `"webgpu"` where the field paints at all. */
+    readonly backend: GpuBackend;
+    /** Park the loop (the pause seam). */
+    pause: () => void;
+    /** Re-arm the loop. */
+    resume: () => void;
+    /** Re-arm a parked loop on demand. */
+    wake: () => void;
+    /** The live `prefers-reduced-motion: reduce` state. */
+    readonly reducedMotion: boolean;
+    /** The current loop parameter `head_t ∈ [0,1)`. */
+    readonly headT: number;
+    /**
+     * The same parameter as a REACTIVE read, refreshed off the one clock at a rate a
+     * reader (or a screen reader) can follow. It is a sample of the frame loop, never a
+     * second one.
+     */
+    readonly headTLive: Readonly<Ref<number>>;
+    readonly rendererStatus: Readonly<Ref<RendererStatus>>;
+    /** Scrub the clock directly. Takes no spring — a hand's position is not a physics event. */
+    setHeadT: (t: number) => void;
+    /** Inject one flick impulse, in turns per second. Capped and floored like any other. */
+    flick: (turnsPerSec: number) => void;
+    dispose: () => void;
+}
+export declare function useFourierField(canvasRef: Ref<HTMLCanvasElement | null>, options: UseFourierFieldOptions): FourierFieldHandle;

package/dist/components/handmark/HandMark.vue.d.ts

@@ -1,23 +1,27 @@
-import type { HandMarkProps } from "./types.js";
+import { type HandShape } from "./stroke.js";
+type __VLS_Props = {
+    shape?: HandShape;
+    color?: string;
+    weight?: number;
+    seed?: number;
+    draw?: boolean;
+};
 declare function play(): void;
-declare var __VLS_1: {};
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+} & {
+    default?: (props: typeof __VLS_5) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<HandMarkProps, {
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     play: typeof play;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<HandMarkProps> & Readonly<{}>, {
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     color: string;
-    seed: number;
-    shape: import("./types.js").HandShape;
-    animation: import("./types.js").HandAnimation;
-    brush: import("./brush.js").BrushName | Partial<import("./brush.js").Brush>;
-    drawMs: number;
-    drawDelayMs: number;
-    appear: "mount" | "visible" | "manual";
-    boilFps: number;
-    boilFrames: number;
-    jagged: boolean;
+    shape: HandShape;
+    weight: number;
+    draw: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/handmark/index.d.ts

@@ -1,26 +1,7 @@
 /**
- * HandMark public barrel.
- * ─────────────────────────────────────────────────────────────────────────────
- * `HandMark` is the sole public component name. The pure L1–L3 functions ship
- * too — they are framework-free, directly usable in slides decks, D3 charts
- * (call `shapeGeom`/`ellipsePoints` to ink a path), even canvas.
- *
- * The DEFAULT is `pen` (clean ink, grain:0 ⇒ no filter, zero extra dep). The
- * `@mkbabb/pencil-boil` geometry is an OPTIONAL PEER. The perfect-freehand body
- * is vendored; only `ribbon:'hull'` (the highlighter) touches that core
- * (treeshaken otherwise).
- *
- * The editorial draw-on underline is
- * `<HandMark shape="underline" animation="draw-on">`; the natural pencil-boil
- * morphology is the `boil` brush.
+ * HandMark public barrel. The component is the surface; the pure functions ship with
+ * it so a caller who owns its own path can ink it with the same pen — `strokeRibbon`
+ * takes any polyline.
  */
 export { default as HandMark } from "./HandMark.vue.js";
-export { BRUSHES, resolveBrush, lerpBrush, type Brush, type BrushName, type BlendMode, type TaperSpec, type StampFn, type InkPath, } from "./brush.js";
-export { shapeGeom, serialize, boilLines, type ShapeGeom } from "./geometry.js";
-export { naturalUnderlinePoints } from "./noise.js";
-export { VB_W, VB_H, UNDERLINE_GAP } from "./constants.js";
-export { ink, type SVGFragment } from "./ink.js";
-export { grainFilter, hasGrain } from "./texture.js";
-export { getStroke, getStrokePoints, getSvgPathFromStroke, type StrokeOptions, type InputPoint, } from "./freehand.js";
-export { useHandMark, normalizeProps, type UseHandMarkInput, type HandMarkCore, type BoilClock, } from "./composables/useHandMark.js";
-export type { HandMarkProps, HandShape, HandAnimation, MarkBox, } from "./types.js";
+export { SHAPES, handBand, handLine, handRing, markDuration, minJerk, serialize, strokeRibbon, type Frame, type HandShape, type Point, } from "./stroke.js";

package/dist/components/handmark/stroke.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The hand voice — one pen, five laws, no framework.
+ *
+ * Every function here is pure and framework-free: a caller with a rect and a font
+ * size gets the same geometry the component draws, in 1:1 CSS pixels. `strokeRibbon`
+ * takes ANY polyline, so a consumer that owns its own path (a chart leader, a route)
+ * inks it with this pen rather than re-deriving one.
+ */
+/** The four gestures, enumerated at runtime so a member change breaks compile-visibly. */
+export declare const SHAPES: readonly ["underline", "strike", "circle", "highlight"];
+export type HandShape = (typeof SHAPES)[number];
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A measured text rect, in CSS px, already expressed in the frame that draws it. */
+export interface Frame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const CAP_HEIGHT = 0.7515;
+/** L4 — x-height plus a 0.04em bleed at each end. */
+export declare const BAND_HEIGHT: number;
+/**
+ * The hand's outer envelope for the ring, in em: the declared vertical run 2b carried
+ * out by the largest radial creep and the largest wobble crest it admits.
+ */
+export declare const RING_ENVELOPE: number;
+/** L1 — the clampless allometric nib. `weight` is a dimensionless multiple. */
+export declare function nib(weight: number, fs: number): number;
+/** L3 — floorless, ceilingless pace over the path length of ONE line rect. */
+export declare function markDuration(length: number): number;
+/**
+ * The minimum-jerk draw profile as a CSS `linear()` easing.
+ *
+ * Every stop is emitted the same way — the PROFILE'S OWN VALUE at its own input — so
+ * `easing(0) = 0` and `easing(1) = 1` hold by construction: `10t³ − 15t⁴ + 6t⁵` is
+ * exactly 0 and exactly 1 at those ends. There is no endpoint special case, because an
+ * endpoint special case is a second expression for a quantity the loop already has,
+ * and the two can disagree. (They did: the branch it replaces emitted the loop INDEX,
+ * so `easing(1)` was `samples` and a draw animating `stroke-dashoffset` to 0 with
+ * `fill: both` came to rest at −23 dash periods — a mark inside its own gap.)
+ */
+export declare function minJerk(samples?: number): string;
+export interface LineOpts {
+    fs: number;
+    seed: number;
+    kind: "underline" | "strike";
+}
+/**
+ * L2 — the centreline. `d(u) = S·[4u(1−u) + B·4u(1−u)(1−2u)]` with |B| ≤ 0.4: both
+ * modes vanish at the endpoints and `d′` is a quadratic, so the commit carries at most
+ * two extrema in closed form for every seed. The lift-off hook is monotone in t over
+ * the last 6% and belongs to the release, never to the calm reading. Tilt is a shear,
+ * not a rotation, so the per-end reach stays exactly what the run-out declares.
+ */
+export declare function handLine(rect: Frame, o: LineOpts): Point[];
+/** The ring's semi-axes: the exact curve through the padded box corner on BOTH axes. */
+export declare function ringAxes(rect: Frame, fs: number): {
+    a: number;
+    b: number;
+};
+/** The horizontal overshoot a ring reserves with `padding-inline` on its wrapper. */
+export declare function ringReserve(rect: Frame, fs: number): number;
+/** L2-RING — an n=3 superellipse, overswept so the tail closes outside the head. */
+export declare function handRing(rect: Frame, o: {
+    fs: number;
+    seed: number;
+}): Point[];
+/**
+ * L4 — the band: one chisel per line rect, raked at both ends, sagging like a swipe,
+ * overrunning its word by 1–2% a side. Opaque, and it carries no ink colour: the page's
+ * own foreground reads on it in both themes.
+ */
+export declare function handBand(rect: Frame, o: {
+    fs: number;
+    seed: number;
+}): Point[];
+/** `M x y L x y …` over an open polyline. */
+export declare function serialize(points: Point[]): string;
+/**
+ * The pen, over an arbitrary polyline: the ribbon is the outline of a stroke of
+ * maximum width `w`, emitted left side forward then right side back, so the minor axis
+ * at any sample is the nib the eye reads there.
+ */
+export declare function strokeRibbon(points: Point[], w: number): string;
+/** A closed polygon — the band's own emission, which is a fill and not a stroke. */
+export declare function fillPolygon(points: Point[]): string;
+/** The default seed: the marked text, salted by the mark's position among its siblings. */
+export declare function markSeed(text: string, instanceIndex: number): number;

package/dist/composables/dark/darkModeSyncScript.d.ts

@@ -8,6 +8,25 @@ export interface DarkModeSyncScriptOptions {
      * uses. Override ONLY if a consumer reconfigured the vueuse storage key.
      */
     storageKey?: string;
+    /**
+     * What an ABSENT or `"auto"` stored mode resolves to. `"os"` (the default)
+     * follows `prefers-color-scheme`, which is right for an app. `false`/`true`
+     * resolve DETERMINISTICALLY, which is right for a document that must not flip
+     * with the projector's OS theme — a briefing, a print target, a capture.
+     */
+    defaultDark?: boolean | "os";
+    /**
+     * Honour `?light` / `?dark` in the query string, above storage and above the
+     * default. This is the capture-forcing seam: a screenshot pipeline asks for a
+     * mode in the URL rather than driving a toggle and hoping.
+     */
+    queryOverride?: boolean;
+    /**
+     * Write the RESOLVED mode back to storage, so an absent or `"auto"` value
+     * becomes a concrete `"dark"`/`"light"` at first paint and the runtime
+     * composable and the stamp cannot disagree about what `auto` meant.
+     */
+    normalize?: boolean;
 }
 /**
  * Return the inline `<head>` script STRING that resolves dark/light at parse

package/dist/composables/motion/pointer/pointerFieldMappings.d.ts

@@ -20,47 +20,6 @@ export interface PointerFieldSnapshot {
     /** The smoothed active-engagement envelope (0..1). */
     engagement: number;
 }
-/** The default bias gain — the curve advances at most ±BIAS_GAIN faster/slower (≤0.15). */
-export declare const FOURIER_BIAS_GAIN = 0.15;
-/** The default centroid-lean fraction (the subtle lean). */
-export declare const FOURIER_FOLLOW_LEAN = 0.15;
-export interface FourierLeanGeometry {
-    /** The canvas backing aspect (w/h) — the model→clip fit inverse. */
-    aspect: number;
-    /** The fit scale (`model = center + clip·aspect / scale`). */
-    scale: number;
-    /**
-     * The head→cursor direction in CLIP space (the renderer computes it from the head
-     * model position + the cursor clip position). Its dot with the head's travel tangent
-     * is the draw-bias alignment. Omit (or zero) → no draw-bias (phaseRateMul = 1).
-     */
-    headToCursor?: PointerVec2;
-    /** The head's travel TANGENT (clip space), for the draw-bias alignment. Omit → no bias. */
-    headTangent?: PointerVec2;
-}
-export interface FourierLeanOptions {
-    /** The centroid-lean fraction (default {@link FOURIER_FOLLOW_LEAN}). */
-    lean?: number;
-    /** The draw-bias gain (default {@link FOURIER_BIAS_GAIN}; clamped ≤0.15). */
-    biasGain?: number;
-}
-export interface FourierLeanResult {
-    /** The MODEL-space centroid lean the setups subtract from `fit.center`. */
-    leanX: number;
-    leanY: number;
-    /**
-     * The clock phase-rate multiplier (1 = neutral). >1 draws toward the cursor a hair
-     * faster; <1 a hair slower. Bounded [1-biasGain, 1+biasGain].
-     */
-    phaseRateMul: number;
-}
-/**
- * The fourier draw-bias + subtle-lean mapping (PURE). The lean uses the SAME [0,1]→clip
- * (y-inverted) → model math the renderer inverts, at the subtle FOLLOW_LEAN (NOT the retired
- * FOLLOW_REACH teleport), scaled by engagement. The draw-bias modulates the clock phase-rate
- * by the head-tangent · head→cursor alignment, bounded by biasGain.
- */
-export declare function fourierLeanMapping(snap: PointerFieldSnapshot, geom: FourierLeanGeometry, options?: FourierLeanOptions): FourierLeanResult;
 /** The steady velocity-lead gain (the body anticipates the heading). */
 export declare const BLOB_LEAD_K = 0.09;
 /** The pseudopod stretch gain off |acceleration| (capped LOW so it swells, never taffies). */

package/dist/{components/search/composables → composables/search}/index.d.ts

@@ -1,5 +1,5 @@
 export { useFuzzySearch } from "./useFuzzySearch.js";
 export type { UseFuzzySearchOptions } from "./useFuzzySearch.js";
-export { buildIndex, searchIndex, fuzzyMatch, clearSearchCache } from "./fuzzySearchIndex.js";
-export type { SearchIndex } from "./fuzzySearchIndex.js";
+export { buildIndex, searchIndex, fuzzyMatch, clearSearchCache } from "./match.js";
+export type { SearchIndex } from "./match.js";
 export type { SearchableItem, SearchResult, FuzzySearchState } from "./types.js";

package/dist/{components/search/composables/fuzzySearchIndex.d.ts → composables/search/match.d.ts}

@@ -1,7 +1,12 @@
 /**
- * Generic fuzzy search index — builds a flat searchable index from items
- * and scores queries with VSCode-style fuzzy matching.
- * Pure functions, no Vue reactivity.
+ * The engine's matcher — builds a flat searchable index from items and scores queries
+ * with VSCode-style fuzzy matching. Pure functions, no Vue reactivity.
+ *
+ * [2026-08-25 · BK #42 W-SEARCH] Landed here from
+ * `src/components/search/composables/fuzzySearchIndex.ts`. The name lost its
+ * `fuzzySearchIndex` prefix with the directory: under `composables/search/` the words
+ * "search" and "fuzzy" are the path, and a file called `search/fuzzySearchIndex.ts`
+ * says them twice.
  */
 import type { SearchableItem, SearchResult } from "./types.js";
 interface IndexEntry<T extends SearchableItem> {