Code-first video & image, rendered natively on WebGPU.
/**
* TextReveal: headlines and body copy that animate in (and out) by
* character, word or line. One timing model, many looks. Glyph styles run on
* the GPU through baked per-unit schedules, so a paragraph stays one text
* node and its final frame is exactly the static text.
*/
import {
type KeyframeTuple,
LayerAnimation,
type LayoutNode,
type TextNode,
} from "@framefields/compositions/program";
import { z } from "zod";
import { bakeSamples } from "../core/bake.js";
import { defineComponent } from "../core/contract.js";
import type { Rect } from "../core/draw.js";
import { evaluateEase } from "../core/ease.js";
import {
constantExpression,
type GlyphAnimator,
type GlyphProps,
type GlyphUnit,
glyphAnimator,
rendererChars,
scheduleExpression,
stepExpression,
type UnitSchedule,
} from "../core/glyphs.js";
import type { Animatable } from "../core/host.js";
import { round as roundTo } from "../core/keys.js";
import {
findRange,
lineShift,
type MeasureOptions,
type Metrics,
rangeRects,
} from "../core/text.js";
import { type Theme, themeFrames } from "../core/theme.js";
import { scaleFrames } from "../core/timing.js";
import { typingFrames } from "../core/typing.js";
import {
burstStarts,
indexedStarts,
scrambleSet,
unitStarts,
unitsOf,
} from "./plan.js";
export const REVEAL_STYLES = [
"rise",
"blur",
"mask",
"slam",
"scatter",
"scramble",
"type",
"stream",
"wipe",
"flip",
] as const;
export type RevealStyle = (typeof REVEAL_STYLES)[number];
/** Styles that can also play out (`exitStyle`). */
export const EXIT_STYLES = [
"rise",
"blur",
"mask",
"scatter",
"type",
"stream",
"wipe",
"flip",
] as const;
export type ExitStyle = (typeof EXIT_STYLES)[number];
const ORDERS = ["forward", "reverse", "center", "edges", "random"] as const;
interface StyleDefaults {
by: GlyphUnit;
/** Frames between units at 30 fps. */
stagger: number;
speed: keyof Theme["motion"]["speed"];
/** Multiplier on the speed token. */
length: number;
ease: string;
}
const STYLE: Record<RevealStyle, StyleDefaults> = {
rise: {
by: "word",
stagger: 3,
speed: "base",
length: 1.4,
ease: "expo.out",
},
blur: {
by: "char",
stagger: 1.2,
speed: "slow",
length: 1,
ease: "power3.out",
},
mask: {
by: "line",
stagger: 5,
speed: "base",
length: 1.5,
ease: "expo.out",
},
slam: { by: "word", stagger: 7, speed: "fast", length: 1, ease: "power3.in" },
scatter: {
by: "char",
stagger: 0.8,
speed: "slow",
length: 1.2,
ease: "expo.out",
},
scramble: {
by: "char",
stagger: 1.5,
speed: "base",
length: 1,
ease: "none",
},
type: { by: "char", stagger: 0, speed: "fast", length: 1, ease: "none" },
stream: {
by: "word",
stagger: 6,
speed: "slow",
length: 1,
ease: "power2.out",
},
wipe: {
by: "line",
stagger: 0,
speed: "slow",
length: 1.4,
ease: "power2.inOut",
},
flip: {
by: "char",
stagger: 1.5,
speed: "base",
length: 1.2,
ease: "back.out(1.4)",
},
};
/** What each glyph style pushes at full weight (font-size units, degrees). */
function glyphFrom(style: RevealStyle, fs: number, exit: boolean): GlyphProps {
switch (style) {
case "rise":
return { y: (exit ? -0.32 : 0.42) * fs, opacity: 0 };
case "blur":
return { blur: 0.16 * fs, scale: 1.18, opacity: 0 };
case "flip":
return { rotationX: exit ? -90 : 90, opacity: 0 };
default:
return { opacity: 0 };
}
}
export interface TextRevealCues {
[name: string]: ReadonlyArray<{ frame: number }>;
/** Per unit: starts moving (`frame`) and comes to rest (`settled`). */
units: ReadonlyArray<{
frame: number;
settled: number;
index: number;
text: string;
}>;
/** The whole text is at rest. */
revealed: ReadonlyArray<{ frame: number }>;
/** The exit starts (empty without `exitStyle`). */
exitStart: ReadonlyArray<{ frame: number }>;
/** Each typed character (`type`) or arriving word (`stream`): for key sounds. */
keystrokes: ReadonlyArray<{ frame: number; index: number }>;
}
export interface TextRevealApi {
/**
* Rects (parent coordinates) that a match covers, one per line: hand
* them to `Annotate` or a camera. Without `match`, the whole text.
*/
rects(match?: string | RegExp, nth?: number): Rect[];
}
type TextProps = Partial<
Pick<
TextNode,
| "fontFamily"
| "fontSize"
| "fontWeight"
| "fill"
| "align"
| "lineHeight"
| "letterSpacing"
| "direction"
| "width"
>
>;
const ALIGN = { start: "left", center: "center", end: "right" } as const;
export const textReveal = /* @__PURE__ */ defineComponent({
name: "TextReveal",
props: () => ({
text: z.string().min(1),
style: z.enum(REVEAL_STYLES).default("rise"),
/** Unit of animation. Default per style. */
by: z.enum(["char", "word", "line"]).optional(),
/** Frames between units. Default per style. */
stagger: z.number().min(0).optional(),
order: z.enum(ORDERS).default("forward"),
/** Frames one unit's move takes. Default per style, from the theme. */
unitDuration: z.number().int().positive().optional(),
ease: z.string().optional(),
/** Play out after `hold`, unit by unit. */
exitStyle: z.union([z.enum(EXIT_STYLES), z.literal(false)]).default(false),
/** Typing speed for `type`, characters a second. */
cps: z.number().positive().default(24),
/** Caret for `type` and `stream`. */
caret: z.boolean().default(true),
/** Words or patterns drawn in the theme's accent. */
emphasis: z.array(z.union([z.string(), z.instanceof(RegExp)])).default([]),
accent: z.string().optional(),
fontFamily: z.string().optional(),
fontSize: z.number().positive().optional(),
fontWeight: z.union([z.number(), z.string()]).optional(),
fill: z.string().optional(),
align: z.enum(["start", "center", "end"]).default("start"),
lineHeight: z.number().positive().optional(),
letterSpacing: z.number().optional(),
direction: z.enum(["ltr", "rtl", "auto"]).optional(),
}),
defaults: { enter: false, exit: false, hold: 30 },
build(ctx, props) {
const { host, theme, fps } = ctx;
const text = props.text;
const fs = props.fontSize ?? 96 * theme.scale;
const fontFamily = props.fontFamily ?? theme.font.display;
const registered = host.fonts();
if (registered.length > 0 && !registered.includes(fontFamily)) {
throw new Error(
`TextReveal: font "${fontFamily}" is not registered. Registered: ${registered.join(", ")}.`,
);
}
const wrap = ctx.requested.width;
const textProps: TextProps = {
fontFamily,
fontSize: fs,
fill: props.fill ?? theme.color.ink,
align: props.align,
...(props.fontWeight !== undefined && { fontWeight: props.fontWeight }),
...(props.lineHeight !== undefined && { lineHeight: props.lineHeight }),
...(props.letterSpacing !== undefined && {
letterSpacing: props.letterSpacing,
}),
...(props.direction !== undefined && { direction: props.direction }),
...(wrap !== undefined && { width: wrap }),
};
const measureOptions: MeasureOptions = {
fontFamily,
fontSize: fs,
fontWeight: props.fontWeight,
letterSpacing: props.letterSpacing,
lineHeight: props.lineHeight,
width: wrap,
align: ALIGN[props.align],
direction: props.direction,
};
const m = host.measure(text, measureOptions);
const W = wrap ?? m.width;
const H = m.height;
const style = STYLE[props.style];
const by: GlyphUnit = props.by ?? style.by;
// Stagger stays fractional: units may start between frames.
const perFps = (v: number) => (v * fps) / 30;
const stagger = perFps(props.stagger ?? style.stagger);
const duration =
props.unitDuration ??
Math.max(
1,
Math.round(themeFrames(theme, style.speed, fps) * style.length),
);
const ease = props.ease ?? style.ease;
const parts: Record<string, Animatable<LayoutNode>> = {};
const children: LayoutNode[] = [];
const animators: GlyphAnimator[] = [];
const keystrokes: Array<{ frame: number; index: number }> = [];
let unitCues: TextRevealCues["units"] = [];
let revealed = 0;
// Emphasis is static colour, first in the stack so streaming ink mixes over it.
const emphasised = emphasisWeights(text, props.emphasis);
if (emphasised) {
animators.push(
glyphAnimator(
"emphasis",
constantExpression("char", rendererChars(text, emphasised)),
{
fillColor: props.accent ?? theme.color.accent,
},
),
);
}
const units = unitsOf(text, by, m);
const schedule = (starts: number[], dur = duration, e = ease) => ({
starts: indexedStarts(text, by, units, starts),
duration: dur,
ease: e,
});
const cuesFor = (starts: number[], dur: number) =>
units.map((u, i) => ({
frame: Math.round(starts[i] ?? 0),
settled: Math.round((starts[i] ?? 0) + dur),
index: u.index,
text: u.text,
}));
const textNode = host.text(text, {
...textProps,
id: ctx.partId("text"),
position: "absolute",
x: 0,
y: 0,
});
parts.text = textNode;
// What carries the glyphs: the text node, or a wrapper around it (null when lines are split).
let main: LayoutNode | null = textNode;
let lines: MaskLine[] = [];
let sweep: ReturnType<typeof wipeMatte> | null = null;
// ── Enter ────────────────────────────────────────────────────────
switch (props.style) {
case "rise":
case "blur":
case "flip": {
const starts = unitStarts(units.length, stagger, props.order, ctx.seed);
animators.push(
glyphAnimator(
"enter",
scheduleExpression(by, schedule(starts), "enter"),
glyphFrom(props.style, fs, false),
),
);
unitCues = cuesFor(starts, duration);
break;
}
case "slam": {
// Each unit is its own node so it scales around its own centre;
// the paragraph takes over the frame the last one lands.
const starts = unitStarts(units.length, stagger, props.order, ctx.seed);
unitCues = cuesFor(starts, duration);
const { width: _w, align: _a, ...unitProps } = textProps;
const pieces = units.map((u, i) => {
const rect = rangeRects(m, u.start, u.end, measureOptions)[0];
const s = starts[i] ?? 0;
const accented =
emphasised?.slice(u.start, u.end).every((v) => v === 1) ?? false;
const piece = host.text(u.text, {
...unitProps,
...(accented && { fill: props.accent ?? theme.color.accent }),
id: ctx.partId(`unit-${i}`),
position: "absolute",
x: rect?.x ?? 0,
y: rect?.y ?? 0,
});
piece.animate(
LayerAnimation.create()
.keys("scale", [
[s, 2.4],
[s + duration, 1, ease],
])
.keys("opacity", [
[s, 0],
[s + Math.max(1, Math.round(duration * 0.45)), 1],
]),
);
return piece;
});
const landed = Math.max(0, ...unitCues.map((u) => u.settled));
// Words land from 2.4×: neither box may clip them on the way in.
const group = host.box({
id: ctx.partId("units"),
position: "absolute",
x: 0,
y: 0,
width: W,
height: H,
overflow: "visible",
children: pieces,
});
group.animate(
LayerAnimation.keys("opacity", [
[0, 1],
[landed, 0, "hold"],
]),
);
textNode.animate(
LayerAnimation.keys("opacity", [
[0, 0],
[landed, 1, "hold"],
]),
);
// A short landing shake as each unit hits.
const shake = host.box({
id: ctx.partId("shake"),
position: "absolute",
x: 0,
y: 0,
width: W,
height: H,
overflow: "visible",
children: [group, textNode],
});
shake.animate(...slamShake(unitCues, fs, ctx.rng("slam")));
parts.units = group;
parts.shake = shake;
main = shake;
break;
}
case "scatter": {
const starts = unitStarts(units.length, stagger, props.order, ctx.seed);
const sched = schedule(starts);
const per = (key: string) => {
const q = ctx.rng(key);
return rendererChars(
text,
Array.from({ length: text.length }, () => q.spread(1)),
);
};
const rx = per("scatter-x");
const ry = per("scatter-y");
const rr = per("scatter-r");
animators.push(
glyphAnimator("enter-x", scheduleExpression(by, sched, "enter", rx), {
x: 1.1 * fs,
}),
glyphAnimator("enter-y", scheduleExpression(by, sched, "enter", ry), {
y: 0.9 * fs,
}),
glyphAnimator("enter-r", scheduleExpression(by, sched, "enter", rr), {
rotation: 120,
}),
glyphAnimator("enter", scheduleExpression(by, sched, "enter"), {
opacity: 0,
blur: 0.06 * fs,
}),
);
unitCues = cuesFor(starts, duration);
break;
}
case "stream": {
const words = unitsOf(text, "word", m);
const step = scaleFrames(1, fps);
const starts = burstStarts(
words.length,
perFps(props.stagger ?? style.stagger),
step,
ctx.rng("stream"),
);
const fade = Math.max(2, themeFrames(theme, "fast", fps));
const ink = props.unitDuration ?? themeFrames(theme, "slow", fps);
animators.push(
glyphAnimator(
"enter",
scheduleExpression(
"word",
{ starts, duration: fade, ease: "power2.out" },
"enter",
),
{ opacity: 0, y: 0.08 * fs },
),
glyphAnimator(
"ink",
scheduleExpression(
"word",
{ starts, duration: ink, ease: "sine.inOut" },
"enter",
),
{ fillColor: theme.color.muted },
),
);
unitCues = words.map((w, i) => ({
frame: starts[i] ?? 0,
settled: (starts[i] ?? 0) + ink,
index: w.index,
text: w.text,
}));
words.forEach((w, i) => {
keystrokes.push({ frame: starts[i] ?? 0, index: w.index });
});
if (props.caret) {
const ends = words.map((w) => w.end);
const caret = buildCaret(ctx, m, measureOptions, fs, {
at: starts,
counts: ends,
until: (starts[starts.length - 1] ?? 0) + ink,
shape: "block",
});
children.push(caret);
parts.caret = caret;
}
break;
}
case "type": {
// Each glyph switches on at its keystroke inside the full layout,
// so centred or wrapped lines never reflow while typing.
const frames = typingFrames(text, props.cps, fps, ctx.rng("type"));
animators.push(
glyphAnimator(
"enter",
stepExpression("char", rendererChars(text, frames)),
{ opacity: 0 },
),
);
frames.forEach((f, i) => {
if (!/\s/.test(text[i] ?? ""))
keystrokes.push({ frame: f, index: i });
});
unitCues = keystrokes.map((k) => ({
frame: k.frame,
settled: k.frame,
index: k.index,
text: text[k.index] ?? "",
}));
revealed = (frames[frames.length - 1] ?? 0) + 1;
if (props.caret) {
const caret = buildCaret(ctx, m, measureOptions, fs, {
at: frames,
counts: frames.map((_, i) => i + 1),
until: revealed + ctx.hold,
shape: "bar",
});
children.push(caret);
parts.caret = caret;
}
break;
}
case "mask": {
lines = maskLines(ctx, text, m, measureOptions, textProps, fs);
const starts = unitStarts(lines.length, stagger, props.order, ctx.seed);
lines.forEach((line, i) => {
const s = starts[i] ?? 0;
line.text.animate(
LayerAnimation.keys("y", [
[s, line.restY + line.travel],
[s + duration, line.restY, ease],
]),
);
children.push(line.clip);
parts[`line-${i}`] = line.clip;
});
unitCues = lines.map((l, i) => ({
frame: Math.round(starts[i] ?? 0),
settled: Math.round((starts[i] ?? 0) + duration),
index: i,
text: l.content,
}));
main = null;
break;
}
case "wipe": {
const w = wipeMatte(ctx, W, H, fs, "hidden");
sweep = w;
w.matte.animate(
LayerAnimation.keys("x", [
[0, w.hidden],
[duration, w.shown, ease],
]),
);
host.matte(textNode, w.matte);
parts.matte = w.matte;
// The front trails a little blur over the glyphs it is uncovering.
const xs = rendererChars(text, glyphCenters(text, m, measureOptions));
const front = Array.from({ length: duration + 1 }, (_, f) =>
w.front(
w.hidden + (w.shown - w.hidden) * evaluateEase(ease, f / duration),
),
);
animators.push(
glyphAnimator(
"wipe-blur",
`((X,T)=>{const f=clamp(frame,0,${duration});const k=floor(f);const front=T[k]+((T[k+1]??T[k])-T[k])*(f-k);return clamp(1-(front-(X[textIndex]??0))/${round(w.feather)},0,1);})(${list(xs)},${list(front)})`,
{ blur: 0.12 * fs },
),
);
unitCues = [{ frame: 0, settled: duration, index: 0, text }];
break;
}
case "scramble": {
const result = scramble(ctx, text, m, measureOptions, textProps, {
stagger,
cycle: duration,
order: props.order,
});
children.push(result.reels);
parts.reels = result.reels;
// The real text takes over the moment the last glyph locks.
textNode.animate(
LayerAnimation.keys("opacity", [
[0, 0],
[result.done, 1, "hold"],
]),
);
unitCues = result.cues;
break;
}
}
if (unitCues.length > 0 && props.style !== "type")
revealed = Math.max(...unitCues.map((u) => u.settled));
// The text is at rest only once the last landing shake dies out.
if (props.style === "slam") revealed += SHAKE.length - 1;
// ── Exit ─────────────────────────────────────────────────────────
let afterHold = 0;
const exitStart = revealed + ctx.hold;
if (props.exitStyle !== false) {
const out = props.exitStyle;
const outStyle = STYLE[out];
const outBy: GlyphUnit = props.by ?? outStyle.by;
const outUnits = unitsOf(text, outBy, m);
const outStagger = perFps((props.stagger ?? outStyle.stagger) * 0.5);
const outDur = Math.max(
1,
Math.round(
themeFrames(theme, outStyle.speed, fps) * outStyle.length * 0.75,
),
);
const outEase = theme.motion.ease.exit;
const starts = unitStarts(
outUnits.length,
outStagger,
props.order,
ctx.seed,
exitStart,
);
const sched: UnitSchedule = {
starts: indexedStarts(text, outBy, outUnits, starts),
duration: outDur,
ease: outEase,
};
afterHold = Math.round(Math.max(...starts) - exitStart + outDur);
switch (out) {
case "rise":
case "blur":
case "flip":
case "scatter":
case "stream":
animators.push(
glyphAnimator(
"exit",
scheduleExpression(outBy, sched, "exit"),
out === "scatter"
? { y: -0.6 * fs, opacity: 0, blur: 0.06 * fs }
: glyphFrom(out, fs, true),
),
);
break;
case "type": {
// Backspace, twice as fast as typing: the last glyph goes first.
const per = Math.max(1, Math.round(fps / (props.cps * 2)));
const gone = Array.from(
{ length: text.length },
(_, c) => exitStart + per * (text.length - c),
);
animators.push(
glyphAnimator(
"exit",
`(1-${stepExpression("char", rendererChars(text, gone))})`,
{ opacity: 0 },
),
);
afterHold = per * text.length + 1;
break;
}
case "wipe": {
if (!sweep) {
sweep = wipeMatte(ctx, W, H, fs, "shown");
host.matte(textNode, sweep.matte);
parts.matte = sweep.matte;
}
sweep.matte.animate(
LayerAnimation.keys("x", [
[exitStart, sweep.shown],
[exitStart + outDur, sweep.gone, outEase],
]),
);
afterHold = outDur;
break;
}
case "mask": {
if (lines.length === 0)
throw new Error(
'TextReveal: exitStyle "mask" needs style "mask" (it splits the lines).',
);
const outStarts = unitStarts(
lines.length,
outStagger,
props.order,
ctx.seed,
exitStart,
);
lines.forEach((line, i) => {
const s = outStarts[i] ?? exitStart;
line.text.animate(
LayerAnimation.keys("y", [
[s, line.restY],
[s + outDur, line.restY - line.travel, outEase],
]),
);
});
afterHold = Math.round(Math.max(...outStarts) - exitStart + outDur);
break;
}
}
}
if (animators.length > 0)
(textNode as unknown as { animators: GlyphAnimator[] }).animators =
animators;
if (main) children.unshift(main);
return {
children,
width: W,
height: H,
duration: Math.max(1, revealed),
openEnded: true,
afterHold,
cues: {
units: unitCues,
revealed: [{ frame: revealed }],
exitStart: props.exitStyle === false ? [] : [{ frame: exitStart }],
keystrokes,
} as TextRevealCues,
parts,
api: (placement): TextRevealApi => ({
rects(match, nth = 0) {
const range: [number, number] | null =
match === undefined
? [0, text.length]
: findRange(text, match, nth);
if (!range)
throw new Error(
`TextReveal.rects: "${String(match)}" not found in "${text}".`,
);
return rangeRects(m, range[0], range[1], measureOptions).map((q) => ({
...q,
x: q.x + placement.x,
y: q.y + placement.y,
}));
},
}),
};
},
});
// ── Helpers ──────────────────────────────────────────────────────────
const round = (v: number) => roundTo(v, 4);
const list = (values: readonly number[]) => `[${values.map(round).join(",")}]`;
/** 1 for characters inside an emphasis match, else 0 (null when nothing matches). */
function emphasisWeights(
text: string,
patterns: ReadonlyArray<string | RegExp>,
): number[] | null {
if (patterns.length === 0) return null;
const w = new Array<number>(text.length).fill(0);
for (const p of patterns) {
for (let nth = 0; ; nth++) {
const range = findRange(text, p, nth);
if (!range || range[1] <= range[0]) break;
for (let i = range[0]; i < range[1]; i++) w[i] = 1;
}
}
return w.some((v) => v > 0) ? w : null;
}
/** Landing shake, per frame after a unit lands (× 0.045 em). */
const SHAKE = [0, 1, -0.55, 0.3, -0.12, 0];
function slamShake(
units: ReadonlyArray<{ settled: number }>,
fs: number,
r: { spread(n: number): number },
): LayerAnimation[] {
const end = Math.max(0, ...units.map((u) => u.settled)) + 8;
const xs = new Array<number>(end + 1).fill(0);
const ys = new Array<number>(end + 1).fill(0);
const a = 0.045 * fs;
const profile = SHAKE;
for (const u of units) {
const dx = r.spread(1);
profile.forEach((p, k) => {
const f = u.settled + k;
if (f <= end) {
xs[f] = (xs[f] ?? 0) + a * p * dx;
ys[f] = (ys[f] ?? 0) + a * p * 0.6;
}
});
}
return [
// Tight tolerance: the text must come to rest exactly where it belongs.
LayerAnimation.keys("x", bakeSamples(xs, 0, { tolerance: 0.005 })),
LayerAnimation.keys("y", bakeSamples(ys, 0, { tolerance: 0.005 })),
];
}
interface Ctx {
host: import("../core/host.js").Host;
theme: Theme;
fps: number;
seed: number;
partId(part: string): string;
rng(key: string | number): import("../core/rng.js").Rng;
}
/** Where the caret sits after `count` characters: x, and the line's top. */
function caretAt(
count: number,
m: Metrics,
options: MeasureOptions,
): [number, number] {
let last: Metrics["glyphs"][number] | undefined;
for (const g of m.glyphs)
if (g.index < count && (!last || g.index > last.index)) last = g;
if (!last) return [lineShift(m, 0, options), 0];
const shift = lineShift(m, last.line, options);
return [
shift + last.x + last.width - (options.letterSpacing ?? 0),
last.line * m.lineHeight,
];
}
function buildCaret(
ctx: Ctx,
m: Metrics,
options: MeasureOptions,
fs: number,
o: {
at: readonly number[];
counts: readonly number[];
until: number;
shape: "bar" | "block";
},
): Animatable<LayoutNode> {
const w = o.shape === "bar" ? Math.max(2, 0.06 * fs) : 0.42 * fs;
const h = o.shape === "bar" ? 1.05 * fs : 0.42 * fs;
const dy =
o.shape === "bar" ? (m.lineHeight - h) / 2 : m.lineHeight * 0.52 - h / 2;
const gap = o.shape === "bar" ? 0.04 * fs : 0.18 * fs;
const [x0, y0] = caretAt(0, m, options);
const xs: KeyframeTuple[] = [[0, x0 + (o.shape === "bar" ? 0 : -w)]];
const ys: KeyframeTuple[] = [[0, y0 + dy]];
o.at.forEach((f, i) => {
const [x, y] = caretAt(o.counts[i] ?? 0, m, options);
xs.push([f, x + gap, "hold"]);
ys.push([f, y + dy, "hold"]);
});
const caret = ctx.host.box({
id: ctx.partId("caret"),
position: "absolute",
x: x0,
y: y0 + dy,
width: w,
height: h,
background: ctx.theme.color.accent,
borderRadius: o.shape === "bar" ? w / 2 : w * 0.18,
});
// Solid while text arrives, then a few blinks, then gone.
const last = o.at[o.at.length - 1] ?? 0;
const half = Math.max(1, Math.round(ctx.fps * 0.5));
const blink: KeyframeTuple[] = [[0, 1]];
let on = false;
for (let f = last + half; f < o.until; f += half, on = !on)
blink.push([f, on ? 1 : 0, "hold"]);
blink.push([Math.max(last + 1, o.until), 0, "hold"]);
caret.animate(
LayerAnimation.create().keys("x", xs).keys("y", ys).keys("opacity", blink),
);
return caret;
}
/** Centre x of every character (spaces included), wrapped and aligned. */
function glyphCenters(
text: string,
m: Metrics,
options: MeasureOptions,
): number[] {
const xs = new Array<number>(text.length).fill(0);
for (const g of m.glyphs)
xs[g.index] = lineShift(m, g.line, options) + g.x + g.width / 2;
return xs;
}
/**
* A soft-edged matte for `wipe`: transparent → opaque → opaque → transparent,
* `feather` px ramps. `hidden` / `shown` / `gone` are its x for each phase.
*/
function wipeMatte(
ctx: Ctx,
W: number,
H: number,
fs: number,
initial: "hidden" | "shown",
) {
const feather = Math.max(24, 0.9 * fs);
const pad = fs * 0.5;
const total = W + feather * 2;
const a = ((feather / total) * 100).toFixed(3);
const b = (((feather + W) / total) * 100).toFixed(3);
const hidden = -total;
const shown = -feather;
const matte = ctx.host.box({
id: ctx.partId("matte"),
position: "absolute",
x: initial === "hidden" ? hidden : shown,
y: -pad,
width: total,
height: H + pad * 2,
background: `linear-gradient(90deg, rgba(255,255,255,0) 0%, #ffffff ${a}%, #ffffff ${b}%, rgba(255,255,255,0) 100%)`,
});
return {
matte,
feather,
total,
hidden,
shown,
gone: W + feather,
/** Where visibility reaches zero, for a matte at `x`. */
front: (x: number) => x + total,
};
}
interface MaskLine {
clip: Animatable<LayoutNode>;
text: Animatable<TextNode>;
content: string;
restY: number;
travel: number;
}
/** One clipped text node per measured line, each at its wrapped position. */
function maskLines(
ctx: Ctx,
text: string,
m: Metrics,
options: MeasureOptions,
textProps: TextProps,
fs: number,
): MaskLine[] {
const pad = Math.round(fs * 0.18);
const { width: _w, align: _a, ...lineProps } = textProps;
return unitsOf(text, "line", m).map((u, i) => {
const first = m.glyphs.find(
(g) => g.index >= u.start && !/\s/.test(g.char),
);
const x = lineShift(m, i, options) + (first?.x ?? 0);
const content = text.slice(u.start, u.end).trim();
const lineText = ctx.host.text(content, {
...lineProps,
id: ctx.partId(`line-${i}-text`),
position: "absolute",
x,
y: pad,
});
const clip = ctx.host.box({
id: ctx.partId(`line-${i}`),
position: "absolute",
x: 0,
y: i * m.lineHeight - pad,
width: Math.max(m.width, options.width ?? 0) + fs,
height: m.lineHeight + pad * 2,
overflow: "hidden",
children: [lineText],
});
return {
clip,
text: lineText,
content,
restY: pad,
travel: m.lineHeight + pad,
};
});
}
/**
* Scramble: each character is a clipped vertical reel of seeded glyphs that
* steps every couple of frames and lands on the real glyph. Reels are as
* wide as the real glyph's advance, so the line never jitters.
*/
function scramble(
ctx: Ctx,
text: string,
m: Metrics,
options: MeasureOptions,
textProps: TextProps,
o: { stagger: number; cycle: number; order: (typeof ORDERS)[number] },
) {
const units = unitsOf(text, "char", m);
const starts = unitStarts(units.length, o.stagger, o.order, ctx.seed);
const step = Math.max(1, scaleFrames(2, ctx.fps));
const { width: _w, align: _a, letterSpacing: _l, ...glyphProps } = textProps;
const reels: LayoutNode[] = [];
const cues: Array<{
frame: number;
settled: number;
index: number;
text: string;
}> = [];
let done = 0;
units.forEach((u, i) => {
const g = m.glyphs.find((q) => q.index === u.start);
if (!g) return;
const appear = Math.round((starts[i] ?? 0) * 0.5);
const lock = Math.round((starts[i] ?? 0) + o.cycle);
const r = ctx.rng(`scramble:${u.start}`);
const set = scrambleSet(u.text);
const count = Math.max(1, Math.floor((lock - appear) / step));
const glyphs = Array.from({ length: count }, () => r.pick([...set]));
glyphs.push(u.text);
const advance = g.width - (options.letterSpacing ?? 0);
const reel = ctx.host.text(glyphs.join("\n"), {
...glyphProps,
id: ctx.partId(`reel-${u.start}`),
position: "absolute",
x: 0,
y: 0,
width: advance,
align: "center",
});
const ys: KeyframeTuple[] = [[0, 0]];
for (let k = 1; k < count; k++)
ys.push([appear + k * step, -k * m.lineHeight, "hold"]);
ys.push([lock, -count * m.lineHeight, "hold"]);
reel.animate(
LayerAnimation.create()
.keys("y", ys)
.keys("opacity", [
[appear, 0],
[appear + 3, 1],
]),
);
reels.push(
ctx.host.box({
id: ctx.partId(`cell-${u.start}`),
position: "absolute",
x: lineShift(m, g.line, options) + g.x,
y: g.line * m.lineHeight,
width: advance,
height: m.lineHeight,
overflow: "hidden",
children: [reel],
}),
);
cues.push({ frame: appear, settled: lock, index: u.index, text: u.text });
done = Math.max(done, lock);
});
const group = ctx.host.box({
id: ctx.partId("reels"),
position: "absolute",
x: 0,
y: 0,
width: m.width,
height: m.height,
children: reels,
});
group.animate(
LayerAnimation.keys("opacity", [
[0, 1],
[done, 0, "hold"],
]),
);
return { reels: group, cues, done };
}