@clipkit/runtime 1.0.0

package/dist/text/font-atlas.js

@@ -0,0 +1,225 @@
+// Canvas-2D-based font atlas generator (v2, clean rewrite).
+//
+// Renders the ASCII printable charset into a single texture once per
+// {family, size, weight} key. Characters are laid out in a grid with
+// padding to avoid bleeding between cells at linear filtering.
+//
+// Fixes over the v0 implementation:
+//   - Uses `actualBoundingBox{Ascent,Descent}` correctly (clamping to a
+//     positive minimum so the negative-ascent edge case can't break layout).
+//   - Pre-loads the requested font via the FontFace API BEFORE measuring,
+//     so we measure the actual font, not the browser fallback.
+//   - Documents that the caller MUST await loadFont() before requesting
+//     an atlas. The atlas itself is sync once fonts are ready.
+import { getLogger } from '../logger.js';
+// The atlas charset. ASCII printable plus the Unicode punctuation +
+// symbols that actually appear in modern Western text — smart quotes,
+// dashes, bullets, currency, etc. Without these, paintviz-style content
+// (curly quotes around dialogue, em-dashes in citations, · separators)
+// drops glyphs at render time.
+//
+// Longer-term: scan the Source for actually-used characters and build a
+// per-source atlas, so non-Latin content "just works" without growing
+// this string further.
+const ASCII_PRINTABLE = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~' +
+    // Latin-1 punctuation + symbols
+    ' ¢£¥¦§©«®°±·»¿×÷' +
+    // General Punctuation: en/em dash, smart quotes, ellipsis, bullets
+    '–—‘’“”„†‡•…‰′″›‹' +
+    // Common symbols: euro, trademark, registered, arrows
+    '€™←↑→↓';
+export function atlasKey(k) {
+    return `${k.family}|${k.size}|${k.weight}`;
+}
+/**
+ * Generate a font atlas synchronously. Caller must have already awaited
+ * font loading (loadFont + document.fonts.ready) — this function does
+ * NOT load fonts.
+ */
+export function generateFontAtlas(key, backend) {
+    const { family, size, weight } = key;
+    const canvas = typeof OffscreenCanvas !== 'undefined'
+        ? new OffscreenCanvas(1, 1)
+        : document.createElement('canvas');
+    const ctx = canvas.getContext('2d', { willReadFrequently: false });
+    if (!ctx)
+        throw new Error('Failed to acquire 2D context for font atlas');
+    const fontSpec = `${weight} ${size}px ${family}`;
+    ctx.font = fontSpec;
+    ctx.textBaseline = 'alphabetic';
+    ctx.textAlign = 'left';
+    // Measure baseline metrics from a reference string with ascenders + descenders.
+    // Clamp to positive minimums: browsers occasionally return negative ascents
+    // for fallback fonts, which used to break v0 layout.
+    //
+    // Two metric sets with different jobs:
+    //   - INK bounds (actualBoundingBox*, maxed over the charset below)
+    //     size the atlas cells — a cell must contain every drawn pixel.
+    //   - DESIGN metrics (fontBoundingBox*) drive line LAYOUT. CSS
+    //     half-leading centers the font's design block in the line box;
+    //     centering the ink block instead shifts baselines by a few px
+    //     in a per-font direction (Inter reads high, DejaVu low).
+    const refMetrics = ctx.measureText('Mg');
+    let ascent = Math.max(size * 0.6, refMetrics.actualBoundingBoxAscent || size * 0.8);
+    let descent = Math.max(size * 0.15, refMetrics.actualBoundingBoxDescent || size * 0.2);
+    let fontAscent = Math.max(size * 0.6, refMetrics.fontBoundingBoxAscent || refMetrics.actualBoundingBoxAscent || size * 0.8);
+    let fontDescent = Math.max(size * 0.1, refMetrics.fontBoundingBoxDescent || refMetrics.actualBoundingBoxDescent || size * 0.2);
+    // fontBoundingBox APPROXIMATES the metrics Chrome's line layout
+    // uses, but disagrees per font (sohne-var lays out 3px high, Inter
+    // 2px low through it). When a document is available, measure the
+    // REAL baseline with a zero-size inline-block strut — its baseline
+    // sits on the text baseline, so offsetTop+offsetHeight inside a
+    // line-height:1 block IS Chrome's within-line-box baseline. Only
+    // the half-leading combo (ascent − descent)/2 affects our layout,
+    // so anchoring ascent = baseline, descent = size − baseline
+    // reproduces DOM positions exactly at any line_height.
+    if (typeof document !== 'undefined' && document.body) {
+        const probe = document.createElement('div');
+        probe.style.cssText =
+            `position:absolute;visibility:hidden;left:-9999px;top:0;` +
+                `white-space:nowrap;font:${fontSpec};line-height:${size}px;`;
+        probe.textContent = 'Hg';
+        const strut = document.createElement('span');
+        strut.style.cssText = 'display:inline-block;width:0;height:0;';
+        probe.appendChild(strut);
+        document.body.appendChild(probe);
+        const baseline = strut.offsetTop + strut.offsetHeight;
+        probe.remove();
+        if (baseline > 0 && baseline < size * 2) {
+            fontAscent = baseline;
+            fontDescent = size - baseline;
+        }
+    }
+    const metrics = new Map();
+    let maxCellWidth = 0;
+    for (const ch of ASCII_PRINTABLE) {
+        const m = ctx.measureText(ch);
+        const advance = m.width;
+        const aLeft = m.actualBoundingBoxLeft || 0;
+        const aRight = m.actualBoundingBoxRight || advance;
+        const aAscent = m.actualBoundingBoxAscent || ascent;
+        const aDescent = m.actualBoundingBoxDescent || descent;
+        const width = Math.ceil(Math.max(advance, aLeft + aRight));
+        metrics.set(ch, { width, advance, aLeft, aRight, aAscent, aDescent });
+        if (width > maxCellWidth)
+            maxCellWidth = width;
+        if (aAscent > ascent)
+            ascent = aAscent;
+        if (aDescent > descent)
+            descent = aDescent;
+    }
+    // Generous padding inside each cell. With ≥ 4 pixels of empty space around
+    // every glyph, bilinear filtering at the cell edge samples only padding
+    // pixels (transparent) — never neighboring glyphs. Combined with the
+    // half-texel UV inset on the read side, this eliminates glyph bleed.
+    const PADDING = 4;
+    const cellWidth = Math.ceil(maxCellWidth + 2 * PADDING);
+    const cellHeight = Math.ceil(ascent + descent + 2 * PADDING);
+    // Layout in a square-ish grid.
+    const cols = Math.ceil(Math.sqrt(ASCII_PRINTABLE.length));
+    const rows = Math.ceil(ASCII_PRINTABLE.length / cols);
+    const atlasWidth = cols * cellWidth;
+    const atlasHeight = rows * cellHeight;
+    // Cap at backend's max texture size — bail loudly if we exceed.
+    const maxDim = backend.capabilities.maxTextureSize;
+    if (atlasWidth > maxDim || atlasHeight > maxDim) {
+        throw new Error(`Font atlas for ${family} ${size}px ${weight} (${atlasWidth}×${atlasHeight}) ` +
+            `exceeds backend max texture dimension ${maxDim}.`);
+    }
+    canvas.width = atlasWidth;
+    canvas.height = atlasHeight;
+    // Re-set font on the resized canvas (browsers clear context state on resize).
+    ctx.font = fontSpec;
+    ctx.textBaseline = 'alphabetic';
+    ctx.textAlign = 'left';
+    ctx.fillStyle = '#ffffff';
+    ctx.clearRect(0, 0, atlasWidth, atlasHeight);
+    // Render each glyph and record its metrics.
+    // Antialiasing margin (in pixels) baked into each glyph's atlas bounds.
+    // This is what the renderer samples at the quad edge — guaranteed to be
+    // either transparent or a low-alpha AA fringe, never another glyph's ink.
+    const AA_MARGIN = 2;
+    const glyphs = new Map();
+    for (let i = 0; i < ASCII_PRINTABLE.length; i++) {
+        const ch = ASCII_PRINTABLE[i];
+        const col = i % cols;
+        const row = Math.floor(i / cols);
+        const cellX = col * cellWidth;
+        const cellY = row * cellHeight;
+        const baselineY = cellY + PADDING + ascent;
+        const penX = cellX + PADDING;
+        // Render glyph at the baseline. textBaseline: 'alphabetic' means y is baseline.
+        ctx.fillText(ch, penX, baselineY);
+        const m = metrics.get(ch);
+        // Compute the glyph's tight bounding box from its actual measured bounds,
+        // plus AA margin, then clamp to the cell so a runaway measurement can't
+        // pick up neighboring cells.
+        let glyphLeft = Math.floor(penX - m.aLeft) - AA_MARGIN;
+        let glyphRight = Math.ceil(penX + m.aRight) + AA_MARGIN;
+        let glyphTop = Math.floor(baselineY - m.aAscent) - AA_MARGIN;
+        let glyphBottom = Math.ceil(baselineY + m.aDescent) + AA_MARGIN;
+        glyphLeft = Math.max(cellX, glyphLeft);
+        glyphRight = Math.min(cellX + cellWidth, glyphRight);
+        glyphTop = Math.max(cellY, glyphTop);
+        glyphBottom = Math.min(cellY + cellHeight, glyphBottom);
+        const glyphW = Math.max(0, glyphRight - glyphLeft);
+        const glyphH = Math.max(0, glyphBottom - glyphTop);
+        glyphs.set(ch, {
+            x: glyphLeft,
+            y: glyphTop,
+            width: glyphW,
+            height: glyphH,
+            advance: m.advance,
+            offsetX: glyphLeft - penX,
+            offsetY: glyphTop - baselineY,
+        });
+    }
+    getLogger().debug(`Generated font atlas: ${family} ${size}px ${weight} (${atlasWidth}×${atlasHeight}, ${ASCII_PRINTABLE.length} glyphs)`);
+    const texture = backend.createTexture(canvas);
+    // Dedicated 1×1 measuring context for lazy pair-kerning — the atlas
+    // canvas itself would otherwise be retained at full size by the
+    // closure after its texture upload.
+    const kernCanvas = typeof OffscreenCanvas !== 'undefined'
+        ? new OffscreenCanvas(1, 1)
+        : document.createElement('canvas');
+    const kernCtx = kernCanvas.getContext('2d');
+    kernCtx.font = fontSpec;
+    const kernCache = new Map();
+    const kern = (a, b) => {
+        if (a === '' || b === '')
+            return 0;
+        const key = a + b;
+        let v = kernCache.get(key);
+        if (v === undefined) {
+            const ma = metrics.get(a);
+            const mb = metrics.get(b);
+            if (!ma || !mb) {
+                v = 0;
+            }
+            else {
+                if (kernCtx.font !== fontSpec)
+                    kernCtx.font = fontSpec;
+                v = kernCtx.measureText(key).width - ma.advance - mb.advance;
+            }
+            kernCache.set(key, v);
+        }
+        return v;
+    };
+    return {
+        family,
+        size,
+        weight,
+        texture,
+        width: atlasWidth,
+        height: atlasHeight,
+        glyphs,
+        // Exported ascent/descent are the DESIGN metrics used for line
+        // layout. Cell geometry above keeps using the ink-bound values;
+        // glyph offsets are baseline-relative, so the two never mix.
+        ascent: fontAscent,
+        descent: fontDescent,
+        lineHeight: cellHeight,
+        kern,
+    };
+}
+//# sourceMappingURL=font-atlas.js.map

package/dist/text/font-atlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-atlas.js","sourceRoot":"","sources":["../../src/text/font-atlas.ts"],"names":[],"mappings":"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"}

package/dist/text/measure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Ensure a font-family has a generic fallback so an unregistered or
+ * unavailable family falls back to SANS-SERIF (matching the browser/CSS
+ * convention) instead of the Canvas 2D default, which is serif. No-op if
+ * the value already carries a fallback chain or is itself a generic
+ * family. Applied at every text render so `font_family: "Inter"` doesn't
+ * silently render as Times when Inter isn't registered.
+ */
+export declare function withFontFallback(family: string): string;
+/**
+ * Measure the rendered width (in pixels) of a string at the given font.
+ * Returns 0 if measurement isn't possible (non-browser environment).
+ */
+export declare function measureTextWidth(text: string, fontFamily: string, fontWeight: string | number, fontSize: number): number;
+/**
+ * Compute the font size (in pixels) that makes `text` fit exactly within
+ * `maxWidth` at the given family and weight. Clamps to a sane range.
+ *
+ * Strategy: measure at a fixed reference size, then scale linearly. Text
+ * width is approximately linear in font size for a single line, so a
+ * single measurement is enough.
+ */
+export declare function autoFitFontSize(text: string, fontFamily: string, fontWeight: string | number, maxWidth: number, fallback?: number, minSize?: number, maxSize?: number): number;
+/**
+ * Two-dimensional auto-fit: the largest font size at which `text`,
+ * greedy-word-wrapped to `boxWidth`, fits within `boxHeight`
+ * (`lineCount × size × lineHeightRatio`). Used by
+ * `font_size: "auto"` when the element has BOTH width and height —
+ * the text wraps and grows to fill the box.
+ *
+ * Binary search over [minSize, maxSize]; the wrap simulation uses the
+ * same kerning-free per-char metric the renderer draws with, so the
+ * renderer's own wrap at the returned size agrees with the search.
+ * Returns minSize when even that overflows (text then overflows the
+ * box, CSS-style).
+ */
+export declare function autoFitFontSizeBox(text: string, fontFamily: string, fontWeight: string | number, boxWidth: number, boxHeight: number, lineHeightRatio: number, minSize?: number, maxSize?: number): number;
+//# sourceMappingURL=measure.d.ts.map

package/dist/text/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../../src/text/measure.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKvD;AAoBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,QAAQ,EAAE,MAAM,GACf,MAAM,CASR;AA2CD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAW,EACrB,OAAO,GAAE,MAAsB,EAC/B,OAAO,GAAE,MAAsB,GAC9B,MAAM,CAMR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE,MAAsB,EAC/B,OAAO,GAAE,MAAsB,GAC9B,MAAM,CAyCR"}

package/dist/text/measure.js

@@ -0,0 +1,164 @@
+// Text measurement utilities. Used for `font_size: "auto"` to compute the
+// pixel size that makes a given string fit within a width constraint.
+//
+// Measurement uses a single shared Canvas 2D context. measureText is fast
+// and doesn't depend on any GPU resources, so we can call it freely during
+// preflight without affecting the render loop.
+// Generic CSS families that already imply a fallback target.
+const GENERIC_FAMILIES = new Set([
+    'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
+    'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded',
+]);
+/**
+ * Ensure a font-family has a generic fallback so an unregistered or
+ * unavailable family falls back to SANS-SERIF (matching the browser/CSS
+ * convention) instead of the Canvas 2D default, which is serif. No-op if
+ * the value already carries a fallback chain or is itself a generic
+ * family. Applied at every text render so `font_family: "Inter"` doesn't
+ * silently render as Times when Inter isn't registered.
+ */
+export function withFontFallback(family) {
+    const f = family.trim();
+    if (f.includes(','))
+        return f;
+    if (GENERIC_FAMILIES.has(f.toLowerCase()))
+        return f;
+    return `${f}, sans-serif`;
+}
+let sharedCtx = null;
+function getCtx() {
+    if (sharedCtx)
+        return sharedCtx;
+    // Workers have no document but DO have OffscreenCanvas — real
+    // measurement beats the character-count estimate everywhere.
+    if (typeof OffscreenCanvas !== 'undefined') {
+        sharedCtx = new OffscreenCanvas(1, 1).getContext('2d');
+        return sharedCtx;
+    }
+    if (typeof document === 'undefined')
+        return null;
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    sharedCtx = canvas.getContext('2d');
+    return sharedCtx;
+}
+/**
+ * Measure the rendered width (in pixels) of a string at the given font.
+ * Returns 0 if measurement isn't possible (non-browser environment).
+ */
+export function measureTextWidth(text, fontFamily, fontWeight, fontSize) {
+    const ctx = getCtx();
+    if (!ctx) {
+        // Rough estimate — every character ≈ 0.5 of font size in width. Better
+        // than nothing for non-browser callers.
+        return text.length * fontSize * 0.5;
+    }
+    ctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
+    return ctx.measureText(text).width;
+}
+const REFERENCE_FONT_SIZE = 100;
+const MIN_FONT_SIZE = 8;
+const MAX_FONT_SIZE = 1000;
+/**
+ * Per-character width at the reference size — the SUM of these matches
+ * the renderer's kerning-free atlas advances, unlike a whole-string
+ * measureText (which applies kerning and reads a few px narrower).
+ * Auto-fit MUST size against the same metric the renderer draws with,
+ * or "exactly fits" overflows the box by the kerning delta.
+ */
+function measureCharWidth(ch, fontFamily, fontWeight) {
+    const ctx = getCtx();
+    if (!ctx)
+        return REFERENCE_FONT_SIZE * 0.5;
+    ctx.font = `${fontWeight} ${REFERENCE_FONT_SIZE}px ${fontFamily}`;
+    return ctx.measureText(ch).width;
+}
+/** Kerning-free reference width of a string (sum of per-char widths). */
+function refWidthOf(text, fontFamily, fontWeight, cache) {
+    let w = 0;
+    for (const ch of text) {
+        let cw = cache.get(ch);
+        if (cw === undefined) {
+            cw = measureCharWidth(ch, fontFamily, fontWeight);
+            cache.set(ch, cw);
+        }
+        w += cw;
+    }
+    return w;
+}
+/**
+ * Compute the font size (in pixels) that makes `text` fit exactly within
+ * `maxWidth` at the given family and weight. Clamps to a sane range.
+ *
+ * Strategy: measure at a fixed reference size, then scale linearly. Text
+ * width is approximately linear in font size for a single line, so a
+ * single measurement is enough.
+ */
+export function autoFitFontSize(text, fontFamily, fontWeight, maxWidth, fallback = 48, minSize = MIN_FONT_SIZE, maxSize = MAX_FONT_SIZE) {
+    if (!text || maxWidth <= 0)
+        return fallback;
+    const refWidth = refWidthOf(text, fontFamily, fontWeight, new Map());
+    if (refWidth <= 0)
+        return fallback;
+    const scaled = REFERENCE_FONT_SIZE * (maxWidth / refWidth);
+    return Math.max(minSize, Math.min(scaled, maxSize));
+}
+/**
+ * Two-dimensional auto-fit: the largest font size at which `text`,
+ * greedy-word-wrapped to `boxWidth`, fits within `boxHeight`
+ * (`lineCount × size × lineHeightRatio`). Used by
+ * `font_size: "auto"` when the element has BOTH width and height —
+ * the text wraps and grows to fill the box.
+ *
+ * Binary search over [minSize, maxSize]; the wrap simulation uses the
+ * same kerning-free per-char metric the renderer draws with, so the
+ * renderer's own wrap at the returned size agrees with the search.
+ * Returns minSize when even that overflows (text then overflows the
+ * box, CSS-style).
+ */
+export function autoFitFontSizeBox(text, fontFamily, fontWeight, boxWidth, boxHeight, lineHeightRatio, minSize = MIN_FONT_SIZE, maxSize = MAX_FONT_SIZE) {
+    if (!text || boxWidth <= 0 || boxHeight <= 0)
+        return minSize;
+    const cache = new Map();
+    const spaceRef = refWidthOf(' ', fontFamily, fontWeight, cache);
+    const lineWords = text.split('\n').map((line) => line.split(' ').map((word) => refWidthOf(word, fontFamily, fontWeight, cache)));
+    const fits = (size) => {
+        const scale = size / REFERENCE_FONT_SIZE;
+        let lineCount = 0;
+        for (const words of lineWords) {
+            let current = 0;
+            let started = false;
+            for (const refW of words) {
+                const w = refW * scale;
+                if (w > boxWidth)
+                    return false; // a single word can't fit
+                const candidate = started ? current + spaceRef * scale + w : w;
+                if (started && candidate > boxWidth) {
+                    lineCount += 1;
+                    current = w;
+                }
+                else {
+                    current = candidate;
+                    started = true;
+                }
+            }
+            lineCount += 1;
+        }
+        return lineCount * size * lineHeightRatio <= boxHeight;
+    };
+    if (!fits(minSize))
+        return minSize;
+    let lo = minSize;
+    let hi = maxSize;
+    for (let i = 0; i < 24; i++) {
+        const mid = (lo + hi) / 2;
+        if (fits(mid))
+            lo = mid;
+        else
+            hi = mid;
+    }
+    // Round down a notch so float dust never pushes the wrap over.
+    return Math.floor(lo * 10) / 10;
+}
+//# sourceMappingURL=measure.js.map

package/dist/text/measure.js.map

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

package/dist/text/text-animation.d.ts

@@ -0,0 +1,52 @@
+import type { AnimationType, BaseElement, Easing } from '@clipkit/protocol';
+export declare function isTextAnimationType(t: AnimationType): boolean;
+/** [xRot, yRot, zRot] in degrees, applied about the unit's center. */
+export type UnitRotation = [number, number, number];
+export interface UnitEffect {
+    /** 0..1 multiplier folded into the glyph tint. */
+    opacity: number;
+    /** Element-local pixel offsets (pre-scale/skew/rotation). */
+    dx: number;
+    dy: number;
+    /**
+     * text-flip rotations (CKP/1.0, §6.5), accumulated per split
+     * granularity — each applies about the center of ITS unit (letter
+     * rotations about the glyph cell, word rotations about the word's
+     * bounding box). Word composes OUTSIDE letter.
+     */
+    flips?: {
+        letter?: UnitRotation;
+        word?: UnitRotation;
+    };
+}
+export interface CompiledTextAnim {
+    type: AnimationType;
+    split: 'letter' | 'word';
+    stagger: number;
+    /** Per-unit animation duration, seconds. */
+    duration: number;
+    /** Animation start, seconds relative to element start. */
+    startTime: number;
+    distance: number;
+    direction: 'left' | 'right' | 'up' | 'down';
+    frequency: number;
+    easing: Easing | undefined;
+    /** text-flip: rotation axis + starting angle in degrees. */
+    axis: 'x' | 'y' | 'z';
+    angle: number;
+}
+/** True when any compiled animation carries per-unit 3D rotation —
+ * the text renderer's signal to take the matrix path (§6.5). */
+export declare function hasUnitRotations(compiled: CompiledTextAnim[]): boolean;
+/**
+ * Compile the element's text-* animations. Returns null when there are
+ * none — the renderer's fast path.
+ */
+export declare function compileTextAnimations(element: BaseElement): CompiledTextAnim[] | null;
+/**
+ * Effect for one glyph at the element-local time. `letterIndex` counts
+ * drawn glyphs (whitespace excluded); `wordIndex` counts whitespace-
+ * separated runs.
+ */
+export declare function evaluateUnitEffect(compiled: CompiledTextAnim[], localTime: number, letterIndex: number, wordIndex: number): UnitEffect;
+//# sourceMappingURL=text-animation.d.ts.map

package/dist/text/text-animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-animation.d.ts","sourceRoot":"","sources":["../../src/text/text-animation.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAa,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAYvF,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAE7D;AAED,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,IAAI,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,4DAA4D;IAC5D,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAID;gEACgE;AAChE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAwBrF;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,UAAU,CA+DZ"}

package/dist/text/text-animation.js

@@ -0,0 +1,133 @@
+// Per-unit (letter / word) text animation evaluation.
+//
+// The text renderer draws one quad per glyph, so per-unit animation is
+// just per-glyph math at draw time: each glyph carries a letter index
+// and a word index; for each active text-* animation we compute the
+// unit's eased progress (offset by `stagger × unitIndex`) and fold the
+// result into an opacity multiplier + position offset applied in
+// element-local space (before scale/skew/rotation, so kinetic type
+// composes with every other transform).
+//
+// Pure functions — no caching, no state. Costs a few multiplies per
+// glyph per frame.
+import { applyEasing } from '../animation/easings.js';
+const TEXT_ANIMATION_TYPES = new Set([
+    'text-appear',
+    'text-slide',
+    'text-fly',
+    'text-typewriter',
+    'text-wave',
+    'text-flip',
+]);
+export function isTextAnimationType(t) {
+    return TEXT_ANIMATION_TYPES.has(t);
+}
+const NO_EFFECT = { opacity: 1, dx: 0, dy: 0 };
+/** True when any compiled animation carries per-unit 3D rotation —
+ * the text renderer's signal to take the matrix path (§6.5). */
+export function hasUnitRotations(compiled) {
+    return compiled.some((a) => a.type === 'text-flip');
+}
+/**
+ * Compile the element's text-* animations. Returns null when there are
+ * none — the renderer's fast path.
+ */
+export function compileTextAnimations(element) {
+    const anims = element.animations;
+    if (!anims || anims.length === 0)
+        return null;
+    let out = null;
+    for (const a of anims) {
+        if (!TEXT_ANIMATION_TYPES.has(a.type))
+            continue;
+        // v1: entrance-only — 'end' anchoring unsupported (documented).
+        if (a.time === 'end')
+            continue;
+        const split = a.split ?? defaultSplit(a.type);
+        (out ??= []).push({
+            type: a.type,
+            split,
+            stagger: a.stagger ?? (split === 'word' ? 0.09 : 0.035),
+            duration: a.duration ?? 0.5,
+            startTime: typeof a.time === 'number' ? a.time : 0,
+            distance: a.distance ?? (a.type === 'text-fly' ? 140 : a.type === 'text-wave' ? 12 : 40),
+            direction: a.direction ?? 'up',
+            frequency: a.frequency ?? 1.5,
+            easing: a.easing,
+            axis: a.axis ?? 'x',
+            angle: a.rotation ?? 90,
+        });
+    }
+    return out;
+}
+function defaultSplit(t) {
+    return t === 'text-typewriter' || t === 'text-wave' || t === 'text-flip' ? 'letter' : 'word';
+}
+/**
+ * Effect for one glyph at the element-local time. `letterIndex` counts
+ * drawn glyphs (whitespace excluded); `wordIndex` counts whitespace-
+ * separated runs.
+ */
+export function evaluateUnitEffect(compiled, localTime, letterIndex, wordIndex) {
+    let opacity = 1;
+    let dx = 0;
+    let dy = 0;
+    let flips;
+    for (const anim of compiled) {
+        const unit = anim.split === 'word' ? wordIndex : letterIndex;
+        if (anim.type === 'text-wave') {
+            // Ambient bob: phase marches across units; no stagger gating.
+            const t = localTime - anim.startTime;
+            if (t < 0)
+                continue;
+            dy += Math.sin(2 * Math.PI * anim.frequency * t - unit * 0.6) * anim.distance;
+            continue;
+        }
+        const unitStart = anim.startTime + unit * anim.stagger;
+        if (anim.type === 'text-typewriter') {
+            if (localTime < unitStart)
+                opacity = 0;
+            continue;
+        }
+        const p = anim.duration > 0
+            ? Math.max(0, Math.min(1, (localTime - unitStart) / anim.duration))
+            : localTime >= unitStart
+                ? 1
+                : 0;
+        const eased = applyEasing(anim.easing ?? (anim.type === 'text-fly' ? 'ease-out-back' : 'ease-out-cubic'), p);
+        // All entrance types fade in over the unit's window.
+        opacity *= Math.max(0, Math.min(1, eased));
+        if (anim.type === 'text-flip') {
+            // Rotate from `angle` to rest about the unit's own center.
+            const remaining = anim.angle * (1 - eased);
+            if (remaining !== 0) {
+                flips ??= {};
+                const slot = (flips[anim.split] ??= [0, 0, 0]);
+                slot[anim.axis === 'x' ? 0 : anim.axis === 'y' ? 1 : 2] += remaining;
+            }
+            continue;
+        }
+        if (anim.type === 'text-slide' || anim.type === 'text-fly') {
+            // Start displaced OPPOSITE the motion direction, settle at rest.
+            const remaining = (1 - eased) * anim.distance;
+            switch (anim.direction) {
+                case 'up':
+                    dy += remaining;
+                    break;
+                case 'down':
+                    dy -= remaining;
+                    break;
+                case 'left':
+                    dx += remaining;
+                    break;
+                case 'right':
+                    dx -= remaining;
+                    break;
+            }
+        }
+    }
+    if (opacity === 1 && dx === 0 && dy === 0 && !flips)
+        return NO_EFFECT;
+    return { opacity, dx, dy, flips };
+}
+//# sourceMappingURL=text-animation.js.map

package/dist/text/text-animation.js.map

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