Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: complete fine caption rendering
kashorin6ac042df6d12
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 0ccdb749..2e7c835d 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -25,7 +25,7 @@ Script Display → Caption Program → Planner + measured Atom timing → Style-`@narratage/caption` owns only common Cue bounds, generic optional per-Word fields, total Styleassignment, Plan validation and the timing join. `@narratage/caption-fine` is one field-free Style-family: it owns its font/box parameters and uniform Cue rendering.+family: it owns geometry, glyph/Cue-box Paint, restrained motion and optional whole-Atom karaoke.### caption-fine:Style@@ -36,11 +36,22 @@ both from one package-owned SVS Recipe:caption.primary {cue-min-words: 2;cue-max-words: 7;- stack-order: 70;- x: 0.08; y: 0.76; width: 0.84;- font: Inter; weight: 600; size: 58; line-height: 0.96;- align: center; fill: #FFFFFF; background: #09090BCC;+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84;+ anchor-x: center; anchor-y: bottom;+ font: Inter; weight: 700; size: 58; font-style: normal;+ line-height: 0.96; letter-spacing: -0.5; word-gap: 14;+ align: center; direction: ltr;+ fill: #FFFFFF; opacity: 1;+ stroke-color: #09090B; stroke-width: 2;+ shadow-color: #000000; shadow-opacity: 0.72;+ shadow-x: 0; shadow-y: 3; shadow-blur: 8;+ glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8;+ background: #09090BCC; border-color: #FFFFFF20; border-width: 1;padding: 16 24; radius: 18;+ karaoke: trail; karaoke-transition: wipe;+ active-fill: #FFD54A; active-scale: 1.04;+ cue-enter: fade; cue-exit: fade; cue-transition-frames: 4;+ atom-reveal: all;}```@@ -51,6 +62,16 @@ caption.primary {Another Caption package may define completely different planning fields and visual parameterswithout changing the common package.+Fine's properties are orthogonal: Cue planning; normalized placement and anchor; layout and+typography; base glyph Paint; Cue-box Paint; active glyph Paint; karaoke timing; and restrained+local motion. Active Paint supports the same `fill`/`opacity`/`stroke-*`/`shadow-*`/`glow-*`+dimensions using the `active-` prefix. Missing optional dimensions resolve deterministically to no+decoration or motion. Unknown properties are rejected.++`karaoke` is `off`, `current` or `trail`; `karaoke-transition` is `step` or `wipe`. Timing is always+whole-Atom timing already proven by Caption. A normal one-word Atom therefore highlights per word,+while a Dual Text Atom remains one indivisible visible unit. Fine never guesses internal time.+### caption:ProgramThe Program starts from the complete ordered display-word universe emitted by Script. One explicitdiff --git a/examples/talking-film-graph-check/studio.svs b/examples/talking-film-graph-check/studio.svsindex 4e0ea301..05663baf 100644--- a/examples/talking-film-graph-check/studio.svs+++ b/examples/talking-film-graph-check/studio.svs@@ -8,9 +8,14 @@}caption.base {cue-min-words: 1; cue-max-words: 5;- stack-order: 70; x: 0.08; y: 0.76; width: 0.84; font: Inter; weight: 600;- size: 58; line-height: 1; align: center; fill: #FFFFFF;- background: #09090BCC; padding: 16 24; radius: 18;+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84; anchor-x: center; anchor-y: bottom;+ font: Inter; weight: 700; size: 58; line-height: 1; align: center;+ fill: #FFFFFF; stroke-color: #09090B; stroke-width: 2;+ shadow-color: #000000; shadow-opacity: 0.72; shadow-x: 0; shadow-y: 3; shadow-blur: 8;+ glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8;+ background: #09090BCC; border-color: #FFFFFF20; border-width: 1; padding: 16 24; radius: 18;+ karaoke: trail; karaoke-transition: wipe; active-fill: #FFD54A;+ cue-enter: fade; cue-exit: fade; cue-transition-frames: 4;}text.title {stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1; font: Inter;diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lockindex afb4ba4a..cb9703a9 100644--- a/examples/talking-film-graph-check/svml.packages.lock+++ b/examples/talking-film-graph-check/svml.packages.lock@@ -14,7 +14,7 @@{"name": "@narratage/caption-fine","version": "0.0.0-dev",- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"},{"name": "@narratage/caption-gemini",@@ -64,7 +64,7 @@{"name": "@narratage/hyperframes","version": "0.0.0-dev",- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"},{"name": "@narratage/media-pipeline",@@ -221,8 +221,8 @@"name": "@narratage/caption-fine","version": "0.0.0-dev"},- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"},{"specifier": "@narratage/caption-gemini",@@ -267,7 +267,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"},{"specifier": "@narratage/media",@@ -312,7 +312,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"},{"specifier": "@narratage/run-text",@@ -432,5 +432,5 @@"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"}],- "digest": "sha256:b7da0d1b0c3e83d40b208922f6e4009c64343668b7fc02ec098897bc4f14cdf4"+ "digest": "sha256:8b85a7310c8dce55f460d1505e427f19f3ca644185b30c6c4372aa1c4f927273"}diff --git a/examples/talking-film-live/svml.packages.lock b/examples/talking-film-live/svml.packages.lockindex 6e09e25e..84841948 100644--- a/examples/talking-film-live/svml.packages.lock+++ b/examples/talking-film-live/svml.packages.lock@@ -9,7 +9,7 @@{"name": "@narratage/caption-fine","version": "0.0.0-dev",- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"},{"name": "@narratage/caption-gemini",@@ -64,7 +64,7 @@{"name": "@narratage/hyperframes","version": "0.0.0-dev",- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"},{"name": "@narratage/media-pipeline",@@ -212,8 +212,8 @@"name": "@narratage/caption-fine","version": "0.0.0-dev"},- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"},{"specifier": "@narratage/caption-gemini",@@ -267,7 +267,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"},{"specifier": "@narratage/media",@@ -312,7 +312,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"},{"specifier": "@narratage/run-text",@@ -432,5 +432,5 @@"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"}],- "digest": "sha256:ba1796603708eefed02adc16db787a018bd81379fbfee172cbe09f7dbb9e0510"+ "digest": "sha256:1a1c839057fe0c4a575f5dc660868d8008cdf33a1f9a6e690c046abb3a04ecc0"}diff --git a/examples/talking-head-aroll/svml.packages.lock b/examples/talking-head-aroll/svml.packages.lockindex 680d9f1f..c0313a61 100644--- a/examples/talking-head-aroll/svml.packages.lock+++ b/examples/talking-head-aroll/svml.packages.lock@@ -9,7 +9,7 @@{"name": "@narratage/caption-fine","version": "0.0.0-dev",- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"},{"name": "@narratage/caption-gemini",@@ -64,7 +64,7 @@{"name": "@narratage/hyperframes","version": "0.0.0-dev",- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"},{"name": "@narratage/media-pipeline",@@ -217,8 +217,8 @@"name": "@narratage/caption-fine","version": "0.0.0-dev"},- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"},{"specifier": "@narratage/caption-gemini",@@ -272,7 +272,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"},{"specifier": "@narratage/media",@@ -326,7 +326,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"},{"specifier": "@narratage/run-text",@@ -446,5 +446,5 @@"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"}],- "digest": "sha256:9459e7a8b5c06ff90185db72ec3e4fc24d832e2e02082543f80d2413a08f55f8"+ "digest": "sha256:b745b8193c9659e651cb612d17550702cb3deaedfd37c7cca01061d20a188af1"}diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.mdindex 55b2b66d..c4c63e40 100644--- a/packages/caption-fine/README.md+++ b/packages/caption-fine/README.md@@ -1,11 +1,12 @@# `@narratage/caption-fine`-The first official fine-grained Caption Style family. It turns an SVS Recipe into one complete-`CaptionStyle` and lowers timed Cues into one ordinary `VisualTrack`.+The official field-free fine-grained Caption Style family. It turns one SVS Recipe into a complete+`CaptionStyle` and lowers timed whole Atoms into one ordinary peer `VisualTrack`.-Fine means short semantic Cues with deterministic geometry, typography and paint. Every Word in a-Cue has one uniform static appearance. This family declares no planning fields and has no-`important`, karaoke, random sizing or per-Word motion semantics.+Fine owns Cue geometry, typography, base/active glyph Paint, Cue box Paint and restrained local+motion. Its optional karaoke is `current | trail` by `step | wipe`; ordinary single-Word Atoms get+per-word timing while a Dual Text Atom remains one honest indivisible activation unit. It declares+no planning fields and has no `important`, random sizing or inferred Word timestamps.```xml<fine:Style id="primary" recipe={studio.caption.primary}/>@@ -23,5 +24,6 @@ Cue has one uniform static appearance. This family declares no planning fields a/>```-One Track handles the default and ordered Style replacements and emits one peer `VisualTrack`.-Common Caption, Media, Composition and Core know none of Fine's Recipe fields or layout policy.+One Track handles the default and ordered Style replacements. Common Caption, Media, Composition+and Core know none of Fine's Recipe fields or layout policy. See `spec/caption-fine.md` for the full+parameter surface, defaults, non-goals and remaining visual evidence gates.diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.tsindex acbabbc2..36cd7ce5 100644--- a/packages/caption-fine/src/manifest.ts+++ b/packages/caption-fine/src/manifest.ts@@ -12,7 +12,7 @@ export const captionFineModuleRef = { name: "@narratage/caption-fine", version:export const captionFineProducers = {render: { module: captionFineModuleRef, name: "render-fine-caption" },} satisfies Record<string, ProducerRef>;-export const captionFineStyleSurfaceImplementationDigest = digestOf("@narratage/caption-fine/field-free-style-surface@1");+export const captionFineStyleSurfaceImplementationDigest = digestOf("@narratage/caption-fine/complete-style-surface@1");export const captionFineTrackSurfaceImplementationDigest = digestOf("@narratage/caption-fine/whole-atom-track-surface@1");export const captionFineManifest: ModuleManifest = {diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.tsindex c6dc0dc3..0defd29d 100644--- a/packages/caption-fine/src/render.ts+++ b/packages/caption-fine/src/render.ts@@ -1,90 +1,292 @@import { assertCaptionProgramForDisplay, assertTimedCaptionProjection } from "@narratage/caption";import type { CaptionProgram, TimedCaptionProjection } from "@narratage/caption";import { assertVisualTrackIdentity, sealVisualTrack } from "@narratage/composition";-import type { VisualElement, VisualStyleDeclaration, VisualTrack } from "@narratage/composition";-import type { CaptionDisplaySequence } from "@narratage/narrative";+import type {+ VisualAnimation,+ VisualBoxElement,+ VisualElement,+ VisualKeyframe,+ VisualStyleDeclaration,+ VisualTextElement,+ VisualTrack,+} from "@narratage/composition";+import type { CaptionDisplayAtom, CaptionDisplaySequence } from "@narratage/narrative";import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";import type { ProgramSpace } from "@narratage/program-space";import { digestOf } from "@narratage/protocol";import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";-import type { FineCaptionParameters } from "./types.js";+import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";-export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/render-field-free-atoms@1");+export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/render-atom-paint-karaoke@1");function frameAt(space: ProgramSpace, seconds: number): number {return Math.round(seconds * space.frameRate.numerator / space.frameRate.denominator);}-function captionPieces(wordIds: readonly string[], wordText: ReadonlyMap<string, string>): string[] {- return wordIds.map((wordId, index) => {- const text = wordText.get(wordId);- if (text === undefined) throw new Error(`Fine Caption Cue references unknown word ${wordId}`);- return index === wordIds.length - 1 ? text : `${text} `;- });+function clamp(value: number, minimum: number, maximum: number): number {+ return Math.max(minimum, Math.min(maximum, value));+}++function compactNumber(value: number): string {+ return String(Math.round(value * 1_000_000) / 1_000_000);}-function textStyle(parameters: FineCaptionParameters): VisualStyleDeclaration[] {+function alphaColor(hex: string, opacity: number): string {+ const red = Number.parseInt(hex.slice(1, 3), 16);+ const green = Number.parseInt(hex.slice(3, 5), 16);+ const blue = Number.parseInt(hex.slice(5, 7), 16);+ const authoredAlpha = hex.length === 9 ? Number.parseInt(hex.slice(7, 9), 16) / 255 : 1;+ return `rgba(${red},${green},${blue},${compactNumber(authoredAlpha * opacity)})`;+}++function glyphStyle(parameters: FineCaptionParameters, paint: FineCaptionGlyphPaint): VisualStyleDeclaration[] {+ const shadows: string[] = [];+ if (paint.shadow.opacity > 0) {+ shadows.push([+ `${compactNumber(paint.shadow.offsetXPx)}px`,+ `${compactNumber(paint.shadow.offsetYPx)}px`,+ `${compactNumber(paint.shadow.blurPx)}px`,+ alphaColor(paint.shadow.color, paint.shadow.opacity),+ ].join(" "));+ }+ if (paint.glow.opacity > 0) {+ shadows.push(`0 0 ${compactNumber(paint.glow.blurPx)}px ${alphaColor(paint.glow.color, paint.glow.opacity)}`);+ }return [- { name: "color", value: parameters.typography.fill },+ { name: "color", value: paint.fill },{ name: "font-family", value: parameters.typography.fontFamily },- { name: "font-size", value: `${parameters.typography.fontSizePx}px` },+ { name: "font-size", value: `${compactNumber(parameters.typography.fontSizePx)}px` },+ { name: "font-style", value: parameters.typography.fontStyle },{ name: "font-weight", value: parameters.typography.fontWeight },- { name: "line-height", value: parameters.typography.lineHeight },- { name: "white-space", value: "pre-wrap" },+ { name: "letter-spacing", value: `${compactNumber(parameters.layout.letterSpacingPx)}px` },+ { name: "line-height", value: parameters.layout.lineHeight },+ { name: "opacity", value: paint.opacity },+ { name: "white-space", value: "nowrap" },+ ...(paint.stroke.widthPx === 0 ? [] : [+ { name: "-webkit-text-stroke-color", value: paint.stroke.color },+ { name: "-webkit-text-stroke-width", value: `${compactNumber(paint.stroke.widthPx)}px` },+ ] as const),+ ...(shadows.length === 0 ? [] : [{ name: "text-shadow", value: shadows.join(",") }] as const),];}+function styleIdentity(style: readonly VisualStyleDeclaration[]): string {+ return JSON.stringify(style);+}++function animationFrom(+ durationFrames: number,+ offsets: Iterable<number>,+ styleAt: (frame: number) => readonly VisualStyleDeclaration[],+): VisualAnimation | undefined {+ const keyframes = [...new Set([0, durationFrames, ...offsets])]+ .filter((frame) => Number.isSafeInteger(frame) && frame >= 0 && frame <= durationFrames)+ .sort((left, right) => left - right)+ .map((atFrame): VisualKeyframe => ({ atFrame, style: styleAt(atFrame) }));+ if (new Set(keyframes.map((keyframe) => styleIdentity(keyframe.style))).size === 1) return undefined;+ return { keyframes };+}++function stepOffsets(...boundaries: number[]): number[] {+ return boundaries.flatMap((boundary) => [boundary - 1, boundary]);+}++function cueAnimation(parameters: FineCaptionParameters, durationFrames: number): VisualAnimation | undefined {+ const requested = parameters.motion.cueTransitionFrames;+ const enterFrames = parameters.motion.cueEnter === "fade" ? Math.min(requested, Math.floor(durationFrames / 2)) : 0;+ const exitFrames = parameters.motion.cueExit === "fade" ? Math.min(requested, Math.floor(durationFrames / 2)) : 0;+ return animationFrom(durationFrames, [enterFrames, durationFrames - exitFrames], (frame) => {+ const enter = enterFrames === 0 ? 1 : clamp(frame / enterFrames, 0, 1);+ const exit = exitFrames === 0 ? 1 : clamp((durationFrames - frame) / exitFrames, 0, 1);+ return [{ name: "opacity", value: Math.min(enter, exit) }];+ });+}++function atomAnimation(+ parameters: FineCaptionParameters,+ startFrame: number,+ endFrame: number,+ durationFrames: number,+): VisualAnimation | undefined {+ if (parameters.motion.atomReveal === "all" && parameters.motion.activeScale === 1) return undefined;+ return animationFrom(durationFrames, stepOffsets(startFrame, endFrame), (frame) => {+ const active = frame >= startFrame && (frame < endFrame || (endFrame === durationFrames && frame === durationFrames));+ const revealed = parameters.motion.atomReveal === "all" || frame >= startFrame;+ return [+ { name: "opacity", value: revealed ? 1 : 0 },+ { name: "transform", value: `scale(${compactNumber(active ? parameters.motion.activeScale : 1)})` },+ ];+ });+}++function karaokeStepAnimation(+ parameters: FineCaptionParameters,+ startFrame: number,+ endFrame: number,+ durationFrames: number,+): VisualAnimation {+ return animationFrom(durationFrames, stepOffsets(startFrame, endFrame), (frame) => {+ const active = parameters.karaoke.mode === "trail"+ ? frame >= startFrame+ : frame >= startFrame && (frame < endFrame || (endFrame === durationFrames && frame === durationFrames));+ return [{ name: "opacity", value: active ? 1 : 0 }];+ }) ?? { keyframes: [+ { atFrame: 0, style: [{ name: "opacity", value: 1 }] },+ { atFrame: durationFrames, style: [{ name: "opacity", value: 1 }] },+ ] };+}++function wipeClip(progress: number, direction: FineCaptionParameters["layout"]["direction"]): string {+ const hidden = compactNumber((1 - clamp(progress, 0, 1)) * 100);+ return direction === "rtl" ? `inset(0 0 0 ${hidden}%)` : `inset(0 ${hidden}% 0 0)`;+}++function karaokeWipeAnimation(+ parameters: FineCaptionParameters,+ startFrame: number,+ endFrame: number,+ durationFrames: number,+): VisualAnimation {+ if (parameters.karaoke.mode === "current" && endFrame - startFrame <= 1) {+ return karaokeStepAnimation(parameters, startFrame, endFrame, durationFrames);+ }+ const revealEnd = parameters.karaoke.mode === "current" ? endFrame - 1 : endFrame;+ return animationFrom(durationFrames, [startFrame, revealEnd, endFrame], (frame) => {+ let progress = 0;+ if (frame >= startFrame && frame <= revealEnd) {+ progress = revealEnd === startFrame ? 1 : (frame - startFrame) / (revealEnd - startFrame);+ } else if (parameters.karaoke.mode === "trail" && frame > revealEnd) {+ progress = 1;+ }+ return [{ name: "clip-path", value: wipeClip(progress, parameters.layout.direction) }];+ }) ?? { keyframes: [+ { atFrame: 0, style: [{ name: "clip-path", value: wipeClip(1, parameters.layout.direction) }] },+ { atFrame: durationFrames, style: [{ name: "clip-path", value: wipeClip(1, parameters.layout.direction) }] },+ ] };+}++function anchorTransform(parameters: FineCaptionParameters): string | undefined {+ const x = parameters.placement.anchorX === "left" ? 0 : parameters.placement.anchorX === "center" ? -50 : -100;+ const y = parameters.placement.anchorY === "top" ? 0 : parameters.placement.anchorY === "center" ? -50 : -100;+ return x === 0 && y === 0 ? undefined : `translate(${x}%,${y}%)`;+}+function cueElements(- wordIds: readonly string[],+ atoms: readonly CaptionDisplayAtom[],+ atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,parameters: FineCaptionParameters,wordText: ReadonlyMap<string, string>,+ durationFrames: number,): VisualElement[] {- const pieces = captionPieces(wordIds, wordText);- return [- {- id: "placement",- order: 0,+ type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order">;+ const elements: VisualElement[] = [];+ let order = 0;+ const push = (element: UnorderedVisualElement): void => {+ elements.push({ ...element, order } as VisualElement);+ order += 1;+ };+ const transform = anchorTransform(parameters);+ const cueMotion = cueAnimation(parameters, durationFrames);+ push({+ id: "placement",+ kind: "box",+ style: [+ { name: "align-items", value: "center" },+ { name: "display", value: "flex" },+ { name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"+ : parameters.layout.textAlign === "right" ? "flex-end" : "center" },+ { name: "left", value: `${compactNumber(parameters.placement.x * 100)}%` },+ { name: "position", value: "absolute" },+ { name: "top", value: `${compactNumber(parameters.placement.y * 100)}%` },+ ...(transform === undefined ? [] : [{ name: "transform", value: transform }] as const),+ { name: "width", value: `${compactNumber(parameters.placement.width * 100)}%` },+ ],+ });+ push({+ id: "cue",+ parent: "placement",+ kind: "box",+ style: [+ { name: "background", value: parameters.cueBox.background },+ { name: "border-color", value: parameters.cueBox.borderColor },+ { name: "border-radius", value: `${compactNumber(parameters.cueBox.radiusPx)}px` },+ { name: "border-style", value: "solid" },+ { name: "border-width", value: `${compactNumber(parameters.cueBox.borderWidthPx)}px` },+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },+ { name: "direction", value: parameters.layout.direction },+ { name: "display", value: "flex" },+ { name: "flex-wrap", value: "wrap" },+ { name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"+ : parameters.layout.textAlign === "right" ? "flex-end" : "center" },+ { name: "padding", value: `${compactNumber(parameters.cueBox.paddingYPx)}px ${compactNumber(parameters.cueBox.paddingXPx)}px` },+ { name: "text-align", value: parameters.layout.textAlign },+ ],+ ...(cueMotion === undefined ? {} : { animation: cueMotion }),+ });++ for (const [atomIndex, atom] of atoms.entries()) {+ const timing = atomFrames.get(atom.id);+ if (timing === undefined) throw new Error(`Fine Caption is missing timing for Atom ${atom.id}`);+ const atomId = `atom-${atomIndex + 1}`;+ const animation = atomAnimation(parameters, timing.start, timing.end, durationFrames);+ push({+ id: atomId,+ parent: "cue",kind: "box",style: [- { name: "align-items", value: "center" },- { name: "display", value: "flex" },- { name: "justify-content", value: parameters.typography.textAlign === "left" ? "flex-start"- : parameters.typography.textAlign === "right" ? "flex-end" : "center" },- { name: "left", value: `${parameters.placement.x * 100}%` },- { name: "position", value: "absolute" },- { name: "top", value: `${parameters.placement.y * 100}%` },- { name: "width", value: `${parameters.placement.width * 100}%` },+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },+ { name: "display", value: "inline-flex" },+ { name: "position", value: "relative" },+ { name: "transform-origin", value: "center center" },+ { name: "white-space", value: "nowrap" },],- },- {- id: "cue",- parent: "placement",- order: 1,+ ...(animation === undefined ? {} : { animation }),+ attributes: [{ name: "data-caption-atom", value: atom.id }],+ });+ for (const [wordIndex, wordId] of atom.wordIds.entries()) {+ const text = wordText.get(wordId);+ if (text === undefined) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);+ push({+ id: `${atomId}-base-${wordIndex + 1}`,+ parent: atomId,+ kind: "text",+ text,+ style: glyphStyle(parameters, parameters.basePaint),+ attributes: [{ name: "data-caption-word", value: wordId }],+ });+ }+ if (parameters.karaoke.mode === "off") continue;+ const activeId = `${atomId}-active`;+ push({+ id: activeId,+ parent: atomId,kind: "box",style: [- { name: "background", value: parameters.box.background },- { name: "border-radius", value: `${parameters.box.radiusPx}px` },- { name: "display", value: "flex" },- { name: "flex-wrap", value: "wrap" },- { name: "justify-content", value: parameters.typography.textAlign === "left" ? "flex-start"- : parameters.typography.textAlign === "right" ? "flex-end" : "center" },- { name: "padding", value: `${parameters.box.paddingYPx}px ${parameters.box.paddingXPx}px` },- { name: "text-align", value: parameters.typography.textAlign },+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },+ { name: "display", value: "inline-flex" },+ { name: "inset", value: "0" },+ { name: "overflow", value: "hidden" },+ { name: "position", value: "absolute" },],- },- ...wordIds.map((wordId, index): VisualElement => {- return {- id: `word-${index + 1}`,- parent: "cue",- order: index + 2,+ animation: parameters.karaoke.transition === "step"+ ? karaokeStepAnimation(parameters, timing.start, timing.end, durationFrames)+ : karaokeWipeAnimation(parameters, timing.start, timing.end, durationFrames),+ attributes: [{ name: "data-caption-karaoke", value: parameters.karaoke.mode }],+ });+ for (const [wordIndex, wordId] of atom.wordIds.entries()) {+ const text = wordText.get(wordId)!;+ push({+ id: `${atomId}-active-${wordIndex + 1}`,+ parent: activeId,kind: "text",- text: pieces[index]!,- style: textStyle(parameters),- attributes: [{ name: "data-caption-word", value: wordId }],- };- }),- ];+ text,+ style: glyphStyle(parameters, parameters.activePaint),+ attributes: [{ name: "data-caption-active-word", value: wordId }],+ });+ }+ }+ return elements;}export function renderFineCaption(@@ -111,7 +313,6 @@ export function renderFineCaption(const atoms = cue.atoms.map((timing) => atomById.get(timing.atomId));if (atoms.some((atom) => atom === undefined)) throw new Error(`Fine Caption Cue ${cue.id} references unknown Atom`);const resolvedAtoms = atoms.map((atom) => atom!);- const wordIds = resolvedAtoms.flatMap((atom) => atom.wordIds);const style = styles.get(cue.styleId);if (style === undefined) throw new Error(`Fine Caption Cue ${cue.id} references unknown Style ${cue.styleId}`);const parameters = style.rendering.parameters as unknown as FineCaptionParameters;@@ -120,11 +321,16 @@ export function renderFineCaption(const measuredEnd = Math.min(totalFrames, frameAt(space, cue.endSec));const endFrameExclusive = Math.min(totalFrames, Math.max(startFrame + 1, measuredEnd));if (startFrame >= totalFrames || endFrameExclusive <= startFrame) return [];+ const durationFrames = endFrameExclusive - startFrame;+ const atomFrames = new Map(cue.atoms.map((atom) => [atom.atomId, {+ start: clamp(frameAt(space, atom.startSec) - startFrame, 0, durationFrames),+ end: clamp(Math.max(frameAt(space, atom.endSec) - startFrame, frameAt(space, atom.startSec) - startFrame + 1), 0, durationFrames),+ }]));return [{id: cue.id,span: { startFrame, endFrameExclusive },stacking: { order: parameters.stackingOrder, tieBreak: `${program.id}:${cue.id}` },- elements: cueElements(wordIds, parameters, wordText),+ elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames),}];});const track = sealVisualTrack({diff --git a/packages/caption-fine/src/style.ts b/packages/caption-fine/src/style.tsindex 17f01f09..575ea829 100644--- a/packages/caption-fine/src/style.ts+++ b/packages/caption-fine/src/style.ts@@ -2,34 +2,67 @@ import type { CaptionStyleIntent } from "@narratage/caption";import { sealCaptionStyle } from "@narratage/caption";import type { SvsRecipe } from "@narratage/svs";-import type { FineCaptionParameters } from "./types.js";+import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";export const FINE_CAPTION_FAMILY = "@narratage/caption-fine@1";-function number(value: SvsRecipe, name: string): number {- const property = value.properties[name];+const REQUIRED_PROPERTIES = [+ "align", "background", "cue-max-words", "cue-min-words", "fill", "font",+ "line-height", "padding", "radius", "size", "stack-order", "weight", "width", "x", "y",+] as const;++const OPTIONAL_PROPERTIES = [+ "active-fill", "active-glow-blur", "active-glow-color", "active-glow-opacity", "active-opacity",+ "active-scale", "active-shadow-blur", "active-shadow-color", "active-shadow-opacity", "active-shadow-x",+ "active-shadow-y", "active-stroke-color", "active-stroke-width", "anchor-x", "anchor-y", "atom-reveal",+ "border-color", "border-width", "cue-enter", "cue-exit", "cue-transition-frames", "direction", "font-style",+ "glow-blur", "glow-color", "glow-opacity", "karaoke", "karaoke-transition", "letter-spacing", "opacity",+ "shadow-blur", "shadow-color", "shadow-opacity", "shadow-x", "shadow-y", "stroke-color", "stroke-width",+ "word-gap",+] as const;++const ALLOWED_PROPERTIES = new Set<string>([...REQUIRED_PROPERTIES, ...OPTIONAL_PROPERTIES]);++function required(value: SvsRecipe, name: string): unknown {+ if (!Object.hasOwn(value.properties, name)) throw new Error(`Fine Caption Recipe requires ${name}`);+ return value.properties[name];+}++function number(value: SvsRecipe, name: string, fallback?: number): number {+ const property = Object.hasOwn(value.properties, name) ? value.properties[name] : fallback;if (typeof property !== "number" || !Number.isFinite(property)) {throw new Error(`Fine Caption Recipe ${name} must be a number`);}return property;}-function integer(value: SvsRecipe, name: string): number {- const property = number(value, name);+function integer(value: SvsRecipe, name: string, fallback?: number): number {+ const property = number(value, name, fallback);if (!Number.isSafeInteger(property)) throw new Error(`Fine Caption Recipe ${name} must be an integer`);return property;}-function string(value: SvsRecipe, name: string): string {- const property = value.properties[name];+function string(value: SvsRecipe, name: string, fallback?: string): string {+ const property = Object.hasOwn(value.properties, name) ? value.properties[name] : fallback;if (typeof property !== "string" || !property.trim()) {throw new Error(`Fine Caption Recipe ${name} must be a string`);}return property.trim();}-function color(value: SvsRecipe, name: string): string {- const property = string(value, name);+function choice<const T extends readonly string[]>(+ value: SvsRecipe,+ name: string,+ choices: T,+ fallback?: T[number],+): T[number] {+ const property = string(value, name, fallback);+ if (!choices.includes(property)) throw new Error(`Fine Caption Recipe ${name} is invalid`);+ return property as T[number];+}++function color(value: SvsRecipe, name: string, fallback?: string): string {+ const property = string(value, name, fallback);if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(property)) {throw new Error(`Fine Caption Recipe ${name} must be an RGB or RGBA hex color`);}@@ -44,37 +77,111 @@ function padding(value: string): { readonly x: number; readonly y: number } {return { y: parts[0]!, x: parts[1] ?? parts[0]! };}-export function fineCaptionParameters(recipe: SvsRecipe): FineCaptionParameters {- const expected = [- "align", "background", "cue-max-words", "cue-min-words", "fill", "font",- "line-height", "padding", "radius", "size", "stack-order", "weight", "width", "x", "y",- ];- if (Object.keys(recipe.properties).sort().join("\0") !== expected.sort().join("\0")) {- throw new Error(`Fine Caption Recipe requires exactly ${expected.join(", ")}`);+function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptionGlyphPaint): FineCaptionGlyphPaint {+ const fallback = <K extends keyof FineCaptionGlyphPaint>(key: K): FineCaptionGlyphPaint[K] | undefined => base?.[key];+ const baseShadow = fallback("shadow") as FineCaptionGlyphPaint["shadow"] | undefined;+ const baseGlow = fallback("glow") as FineCaptionGlyphPaint["glow"] | undefined;+ const baseStroke = fallback("stroke") as FineCaptionGlyphPaint["stroke"] | undefined;+ return {+ fill: color(recipe, `${prefix}fill`, prefix === "active-" ? "#FFD54A" : base?.fill),+ opacity: number(recipe, `${prefix}opacity`, base?.opacity ?? 1),+ stroke: {+ color: color(recipe, `${prefix}stroke-color`, baseStroke?.color ?? "#000000"),+ widthPx: number(recipe, `${prefix}stroke-width`, baseStroke?.widthPx ?? 0),+ },+ shadow: {+ color: color(recipe, `${prefix}shadow-color`, baseShadow?.color ?? "#000000"),+ opacity: number(recipe, `${prefix}shadow-opacity`, baseShadow?.opacity ?? 0),+ offsetXPx: number(recipe, `${prefix}shadow-x`, baseShadow?.offsetXPx ?? 0),+ offsetYPx: number(recipe, `${prefix}shadow-y`, baseShadow?.offsetYPx ?? 0),+ blurPx: number(recipe, `${prefix}shadow-blur`, baseShadow?.blurPx ?? 0),+ },+ glow: {+ color: color(recipe, `${prefix}glow-color`, baseGlow?.color ?? "#FFFFFF"),+ opacity: number(recipe, `${prefix}glow-opacity`, baseGlow?.opacity ?? 0),+ blurPx: number(recipe, `${prefix}glow-blur`, baseGlow?.blurPx ?? 0),+ },+ };+}++function assertColor(value: string, label: string): void {+ if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value)) throw new Error(`${label} is invalid`);+}++function assertOpacity(value: number, label: string): void {+ if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${label} must be between 0 and 1`);+}++function assertPaint(value: FineCaptionGlyphPaint, label: string): void {+ assertColor(value.fill, `${label} fill`);+ assertOpacity(value.opacity, `${label} opacity`);+ assertColor(value.stroke.color, `${label} stroke color`);+ assertColor(value.shadow.color, `${label} shadow color`);+ assertColor(value.glow.color, `${label} glow color`);+ assertOpacity(value.shadow.opacity, `${label} shadow opacity`);+ assertOpacity(value.glow.opacity, `${label} glow opacity`);+ for (const [name, metric] of [+ ["stroke width", value.stroke.widthPx], ["shadow blur", value.shadow.blurPx], ["glow blur", value.glow.blurPx],+ ] as const) {+ if (!Number.isFinite(metric) || metric < 0) throw new Error(`${label} ${name} is invalid`);}- const align = string(recipe, "align");- if (align !== "left" && align !== "center" && align !== "right") {- throw new Error("Fine Caption Recipe align is invalid");+ if (!Number.isFinite(value.shadow.offsetXPx) || !Number.isFinite(value.shadow.offsetYPx)) {+ throw new Error(`${label} shadow offset is invalid`);}+}++export function fineCaptionParameters(recipe: SvsRecipe): FineCaptionParameters {+ for (const name of REQUIRED_PROPERTIES) required(recipe, name);+ const unknown = Object.keys(recipe.properties).filter((name) => !ALLOWED_PROPERTIES.has(name));+ if (unknown.length > 0) throw new Error(`Fine Caption Recipe contains unknown property ${unknown[0]}`);+const pad = padding(string(recipe, "padding"));+ const fontSizePx = number(recipe, "size");+ const basePaint = glyphPaint(recipe, "");const parameters: FineCaptionParameters = {contract: "svml.caption-fine-parameters@1",stackingOrder: integer(recipe, "stack-order"),- placement: { x: number(recipe, "x"), y: number(recipe, "y"), width: number(recipe, "width") },+ placement: {+ x: number(recipe, "x"),+ y: number(recipe, "y"),+ width: number(recipe, "width"),+ anchorX: choice(recipe, "anchor-x", ["left", "center", "right"] as const, "left"),+ anchorY: choice(recipe, "anchor-y", ["top", "center", "bottom"] as const, "top"),+ },+ layout: {+ textAlign: choice(recipe, "align", ["left", "center", "right"] as const),+ direction: choice(recipe, "direction", ["ltr", "rtl"] as const, "ltr"),+ lineHeight: number(recipe, "line-height"),+ letterSpacingPx: number(recipe, "letter-spacing", 0),+ wordGapPx: number(recipe, "word-gap", fontSizePx * 0.25),+ },typography: {fontFamily: string(recipe, "font"),- fontSizePx: number(recipe, "size"),+ fontSizePx,fontWeight: integer(recipe, "weight"),- lineHeight: number(recipe, "line-height"),- textAlign: align,- fill: color(recipe, "fill"),+ fontStyle: choice(recipe, "font-style", ["normal", "italic"] as const, "normal"),},- box: {+ basePaint,+ activePaint: glyphPaint(recipe, "active-", basePaint),+ cueBox: {background: color(recipe, "background"),+ borderColor: color(recipe, "border-color", "#00000000"),+ borderWidthPx: number(recipe, "border-width", 0),paddingXPx: pad.x,paddingYPx: pad.y,radiusPx: number(recipe, "radius"),},+ karaoke: {+ mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, "off"),+ transition: choice(recipe, "karaoke-transition", ["step", "wipe"] as const, "step"),+ },+ motion: {+ cueEnter: choice(recipe, "cue-enter", ["none", "fade"] as const, "none"),+ cueExit: choice(recipe, "cue-exit", ["none", "fade"] as const, "none"),+ cueTransitionFrames: integer(recipe, "cue-transition-frames", 0),+ atomReveal: choice(recipe, "atom-reveal", ["all", "on-start"] as const, "all"),+ activeScale: number(recipe, "active-scale", 1),+ },};assertFineCaptionParameters(parameters);return parameters;@@ -85,20 +192,25 @@ export function assertFineCaptionParameters(value: FineCaptionParameters): voidif (!Number.isSafeInteger(value.stackingOrder) || value.stackingOrder < 0) {throw new Error("Fine Caption stacking order is invalid");}- const numeric = [+ const nonNegative = [value.placement.x, value.placement.y, value.placement.width, value.typography.fontSizePx,- value.typography.fontWeight, value.typography.lineHeight, value.box.paddingXPx, value.box.paddingYPx,- value.box.radiusPx,+ value.typography.fontWeight, value.layout.lineHeight, value.layout.wordGapPx, value.cueBox.paddingXPx,+ value.cueBox.paddingYPx, value.cueBox.radiusPx, value.cueBox.borderWidthPx, value.motion.cueTransitionFrames,];- if (numeric.some((item) => !Number.isFinite(item) || item < 0)+ if (nonNegative.some((item) => !Number.isFinite(item) || item < 0)|| value.placement.x > 1 || value.placement.y > 1 || value.placement.width <= 0 || value.placement.width > 1- || value.typography.fontSizePx <= 0 || value.typography.lineHeight <= 0) {+ || value.typography.fontSizePx <= 0 || value.layout.lineHeight <= 0+ || !Number.isSafeInteger(value.motion.cueTransitionFrames) || value.motion.activeScale <= 0+ || !Number.isFinite(value.motion.activeScale) || !Number.isFinite(value.layout.letterSpacingPx)) {throw new Error("Fine Caption parameters contain invalid numeric bounds");}- if (!value.typography.fontFamily.trim()) throw new Error("Fine Caption font family is empty");- for (const colorValue of [value.typography.fill, value.box.background]) {- if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(colorValue)) throw new Error("Fine Caption color is invalid");+ if (!value.typography.fontFamily.trim() || value.typography.fontWeight < 1 || value.typography.fontWeight > 1000) {+ throw new Error("Fine Caption typography is invalid");}+ assertColor(value.cueBox.background, "Fine Caption background");+ assertColor(value.cueBox.borderColor, "Fine Caption border color");+ assertPaint(value.basePaint, "Fine Caption base Paint");+ assertPaint(value.activePaint, "Fine Caption active Paint");}export function fineCaptionStyle(id: string, recipe: SvsRecipe): CaptionStyleIntent {@@ -114,7 +226,7 @@ export function fineCaptionStyle(id: string, recipe: SvsRecipe): CaptionStyleIntcue: {minimumWords,maximumWords,- instruction: `Split into complete semantic phrases of ${minimumWords} to ${maximumWords} display words. Never cross punctuation when avoidable.`,+ instruction: `Split into complete semantic phrases of ${minimumWords} to ${maximumWords} display words. Never cut inside an Atom and avoid crossing punctuation. An indivisible Atom may exceed the requested maximum.`,},fields: [],},diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.tsindex 38c464e8..a1de7466 100644--- a/packages/caption-fine/src/types.ts+++ b/packages/caption-fine/src/types.ts@@ -1,3 +1,24 @@+export type FineCaptionGlyphPaint = {+ readonly fill: string;+ readonly opacity: number;+ readonly stroke: {+ readonly color: string;+ readonly widthPx: number;+ };+ readonly shadow: {+ readonly color: string;+ readonly opacity: number;+ readonly offsetXPx: number;+ readonly offsetYPx: number;+ readonly blurPx: number;+ };+ readonly glow: {+ readonly color: string;+ readonly opacity: number;+ readonly blurPx: number;+ };+};+export type FineCaptionParameters = {readonly contract: "svml.caption-fine-parameters@1";readonly stackingOrder: number;@@ -5,19 +26,41 @@ export type FineCaptionParameters = {readonly x: number;readonly y: number;readonly width: number;+ readonly anchorX: "left" | "center" | "right";+ readonly anchorY: "top" | "center" | "bottom";+ };+ readonly layout: {+ readonly textAlign: "left" | "center" | "right";+ readonly direction: "ltr" | "rtl";+ readonly lineHeight: number;+ readonly letterSpacingPx: number;+ readonly wordGapPx: number;};readonly typography: {readonly fontFamily: string;readonly fontSizePx: number;readonly fontWeight: number;- readonly lineHeight: number;- readonly textAlign: "left" | "center" | "right";- readonly fill: string;+ readonly fontStyle: "normal" | "italic";};- readonly box: {+ readonly basePaint: FineCaptionGlyphPaint;+ readonly activePaint: FineCaptionGlyphPaint;+ readonly cueBox: {readonly background: string;+ readonly borderColor: string;+ readonly borderWidthPx: number;readonly paddingXPx: number;readonly paddingYPx: number;readonly radiusPx: number;};+ readonly karaoke: {+ readonly mode: "off" | "current" | "trail";+ readonly transition: "step" | "wipe";+ };+ readonly motion: {+ readonly cueEnter: "none" | "fade";+ readonly cueExit: "none" | "fade";+ readonly cueTransitionFrames: number;+ readonly atomReveal: "all" | "on-start";+ readonly activeScale: number;+ };};diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.tsindex c011d180..92f0da95 100644--- a/packages/caption-fine/test/caption-fine.test.ts+++ b/packages/caption-fine/test/caption-fine.test.ts@@ -3,7 +3,7 @@ import test from "node:test";import { resolveCaptionProgram } from "@narratage/caption";import type { TimedCaptionProjection } from "@narratage/caption";-import { fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";+import { fineCaptionParameters, fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";import { sealProgramSpace } from "@narratage/program-space";import { captionDisplaySequence, parseScript } from "@narratage/script";import type { SvsRecipe } from "@narratage/svs";@@ -60,9 +60,183 @@ test("one Fine renderer handles uniform Cue appearance as one peer VisualTrack",const wordElements = track.presents[0]!.elements.filter((element) => element.kind === "text");assert.equal(wordElements.length, 3);assert.deepEqual(wordElements.map((element) => element.kind === "text" ? element.text : undefined),- ["Meaning ", "becomes ", "visible."]);+ ["Meaning", "becomes", "visible."]);assert.equal(wordElements.every((element) => element.style.some((declaration) =>declaration.name === "color" && declaration.value === "#FFFFFF")), true);assert.equal(wordElements.every((element) =>element.style.every((declaration) => declaration.name !== "transform")), true);+ assert.equal(fineCaptionParameters(recipe).activePaint.fill, "#FFD54A");+});++test("Fine resolves the complete orthogonal Paint, anchor, karaoke and motion surface", () => {+ const parameters = fineCaptionParameters({+ ...recipe,+ properties: {+ ...recipe.properties,+ "anchor-x": "center",+ "anchor-y": "bottom",+ direction: "rtl",+ "letter-spacing": -1.5,+ "word-gap": 11,+ "font-style": "italic",+ opacity: 0.9,+ "stroke-color": "#101010",+ "stroke-width": 3,+ "shadow-color": "#000000",+ "shadow-opacity": 0.75,+ "shadow-x": 2,+ "shadow-y": 4,+ "shadow-blur": 8,+ "glow-color": "#5CE1E6",+ "glow-opacity": 0.6,+ "glow-blur": 12,+ "border-color": "#FFFFFF80",+ "border-width": 2,+ karaoke: "trail",+ "karaoke-transition": "wipe",+ "active-fill": "#FFDD00",+ "active-opacity": 0.95,+ "active-stroke-color": "#401000",+ "active-stroke-width": 1,+ "active-shadow-color": "#FF8800",+ "active-shadow-opacity": 0.5,+ "active-shadow-x": 0,+ "active-shadow-y": 2,+ "active-shadow-blur": 5,+ "active-glow-color": "#FFFFFF",+ "active-glow-opacity": 0.7,+ "active-glow-blur": 10,+ "cue-enter": "fade",+ "cue-exit": "fade",+ "cue-transition-frames": 6,+ "atom-reveal": "on-start",+ "active-scale": 1.08,+ },+ });++ assert.deepEqual(parameters.placement, {+ x: 0.08, y: 0.76, width: 0.84, anchorX: "center", anchorY: "bottom",+ });+ assert.equal(parameters.layout.direction, "rtl");+ assert.equal(parameters.typography.fontStyle, "italic");+ assert.equal(parameters.basePaint.stroke.widthPx, 3);+ assert.equal(parameters.basePaint.glow.blurPx, 12);+ assert.equal(parameters.activePaint.fill, "#FFDD00");+ assert.equal(parameters.activePaint.shadow.offsetYPx, 2);+ assert.deepEqual(parameters.karaoke, { mode: "trail", transition: "wipe" });+ assert.deepEqual(parameters.motion, {+ cueEnter: "fade", cueExit: "fade", cueTransitionFrames: 6, atomReveal: "on-start", activeScale: 1.08,+ });+});++test("karaoke uses one active overlay per whole Atom and never invents Dual Text word timing", () => {+ const narrative = parseScript("karaoke.svml", "<line>Hello <New York City | new york city> today.</line>");+ const display = captionDisplaySequence(narrative, "story.caption");+ const style = fineCaptionStyle("karaoke", {+ ...recipe,+ properties: {+ ...recipe.properties,+ karaoke: "trail",+ "karaoke-transition": "wipe",+ "active-fill": "#FFD54A",+ "atom-reveal": "on-start",+ "active-scale": 1.04,+ "cue-enter": "fade",+ "cue-exit": "fade",+ "cue-transition-frames": 4,+ },+ });+ const program = resolveCaptionProgram(display, "karaoke-captions", style, []);+ const projection: TimedCaptionProjection = {+ contract: "svml.timed-caption-projection@1",+ displaySequenceId: display.id,+ cues: [{+ id: "cue:karaoke",+ runId: program.runs[0]!.id,+ styleId: style.id,+ segmentId: "line",+ startSec: 0,+ endSec: 3,+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),+ fields: [],+ }],+ };+ const space = sealProgramSpace({+ contract: "svml.program-space@1",+ durationSec: 3,+ frameRate: { numerator: 30, denominator: 1 },+ });++ const track = renderFineCaption(projection, program, display, space);+ const elements = track.presents[0]!.elements;+ const dualAtom = display.atoms.find((atom) => atom.wordIds.length === 3)!;+ const dualContainer = elements.find((element) =>+ element.attributes?.some((attribute) => attribute.name === "data-caption-atom" && attribute.value === dualAtom.id));+ assert.ok(dualContainer);+ const activeLayer = elements.find((element) => element.parent === dualContainer.id+ && element.attributes?.some((attribute) => attribute.name === "data-caption-karaoke"));+ assert.ok(activeLayer?.animation);+ assert.equal(activeLayer.animation.keyframes.some((keyframe) => keyframe.style.some((item) =>+ item.name === "clip-path" && String(item.value).includes("inset"))), true);+ assert.equal(elements.filter((element) => element.parent === activeLayer.id && element.kind === "text").length, 3);+ assert.equal(elements.filter((element) => element.attributes?.some((attribute) =>+ attribute.name === "data-caption-karaoke")).length, display.atoms.length);+});++test("Fine rejects unknown or obsolete Recipe dimensions instead of silently accepting them", () => {+ assert.throws(() => fineCaptionStyle("bad", {+ ...recipe,+ properties: { ...recipe.properties, important: true },+ }), /unknown property important/u);+});++test("current/trail by step/wipe have four distinct frame-exact Atom histories", () => {+ const narrative = parseScript("modes.svml", "<line>First second.</line>");+ const display = captionDisplaySequence(narrative, "story.caption");+ const space = sealProgramSpace({+ contract: "svml.program-space@1",+ durationSec: 2,+ frameRate: { numerator: 10, denominator: 1 },+ });+ const render = (mode: "current" | "trail", transition: "step" | "wipe") => {+ const style = fineCaptionStyle(`${mode}-${transition}`, {+ ...recipe,+ properties: { ...recipe.properties, karaoke: mode, "karaoke-transition": transition },+ });+ const program = resolveCaptionProgram(display, `program-${mode}-${transition}`, style, []);+ const projection: TimedCaptionProjection = {+ contract: "svml.timed-caption-projection@1",+ displaySequenceId: display.id,+ cues: [{+ id: "cue:modes",+ runId: program.runs[0]!.id,+ styleId: style.id,+ segmentId: "line",+ startSec: 0,+ endSec: 2,+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),+ fields: [],+ }],+ };+ const track = renderFineCaption(projection, program, display, space);+ return track.presents[0]!.elements.find((element) => element.id === "atom-1-active")!.animation!.keyframes;+ };+ const at = (keyframes: ReturnType<typeof render>, frame: number, property: string) =>+ keyframes.find((keyframe) => keyframe.atFrame === frame)!.style.find((item) => item.name === property)!.value;++ const currentStep = render("current", "step");+ assert.equal(at(currentStep, 0, "opacity"), 1);+ assert.equal(at(currentStep, 10, "opacity"), 0);+ const trailStep = render("trail", "step");+ assert.equal(at(trailStep, 0, "opacity"), 1);+ assert.equal(at(trailStep, 20, "opacity"), 1);++ const currentWipe = render("current", "wipe");+ assert.equal(at(currentWipe, 0, "clip-path"), "inset(0 100% 0 0)");+ assert.equal(at(currentWipe, 9, "clip-path"), "inset(0 0% 0 0)");+ assert.equal(at(currentWipe, 10, "clip-path"), "inset(0 100% 0 0)");+ const trailWipe = render("trail", "wipe");+ assert.equal(at(trailWipe, 0, "clip-path"), "inset(0 100% 0 0)");+ assert.equal(at(trailWipe, 10, "clip-path"), "inset(0 0% 0 0)");+ assert.equal(at(trailWipe, 20, "clip-path"), "inset(0 0% 0 0)");});diff --git a/packages/hyperframes/test/browser-visual.test.ts b/packages/hyperframes/test/browser-visual.test.tsindex 8934fe88..003f1c71 100644--- a/packages/hyperframes/test/browser-visual.test.ts+++ b/packages/hyperframes/test/browser-visual.test.ts@@ -1,10 +1,14 @@import { spawnSync } from "node:child_process";import { createHash } from "node:crypto";+import { createRequire } from "node:module";import { copyFile, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";import os from "node:os";import path from "node:path";import test from "node:test";import { deflateSync } from "node:zlib";+import { resolveCaptionProgram } from "@narratage/caption";+import type { TimedCaptionProjection } from "@narratage/caption";+import { fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";import type { FontArtifactRef } from "@narratage/media";import { sealProgramSpace } from "@narratage/program-space";import { sealComposition, sealVisualTrack } from "@narratage/composition";@@ -14,10 +18,14 @@ import {materializeHyperframesHtml,} from "@narratage/hyperframes";import type { Digest } from "@narratage/protocol";+import { captionDisplaySequence, parseScript } from "@narratage/script";+import type { SvsRecipe } from "@narratage/svs";const enabled = process.env.SVML_BROWSER_TESTS === "1";const localFont = process.env.SVML_TEST_FONT_PATH?? (process.platform === "darwin" ? "/System/Library/Fonts/SFNSMono.ttf" : undefined);+const hyperframesCli = createRequire(path.join(process.cwd(), "packages/provider-hyperframes-local/package.json"))+ .resolve("hyperframes/bin/hyperframes.mjs");function digest(bytes: Uint8Array): Digest {return `sha256:${createHash("sha256").update(bytes).digest("hex")}` as Digest;@@ -81,6 +89,31 @@ async function findPng(directory: string): Promise<string | undefined> {return undefined;}+async function collectPngs(directory: string): Promise<string[]> {+ const result: string[] = [];+ for (const entry of await readdir(directory, { withFileTypes: true })) {+ const absolute = path.join(directory, entry.name);+ if (entry.isDirectory()) result.push(...await collectPngs(absolute));+ else if (entry.name.endsWith(".png")) result.push(absolute);+ }+ return result.sort();+}++function yellowPixels(file: string, width: number, height: number): number {+ const decoded = spawnSync("ffmpeg", [+ "-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1",+ ], { encoding: "buffer", timeout: 30_000 });+ assert.equal(decoded.status, 0, decoded.stderr.toString());+ assert.equal(decoded.stdout.byteLength, width * height * 4);+ let count = 0;+ for (let index = 0; index < decoded.stdout.byteLength; index += 4) {+ if (decoded.stdout[index]! > 180 && decoded.stdout[index + 1]! > 130 && decoded.stdout[index + 2]! < 140) {+ count += 1;+ }+ }+ return count;+}+test("locked font and straight-alpha Surface survive one real Hyperframes browser frame", {skip: !enabled || localFont === undefined,timeout: 120_000,@@ -191,7 +224,7 @@ test("locked font and straight-alpha Surface survive one real Hyperframes browseconst output = path.join(temp, "frames");await mkdir(output);const render = spawnSync(process.execPath, [- path.join(process.cwd(), "node_modules/hyperframes/bin/hyperframes.mjs"),+ hyperframesCli,"render",temp,"--format", "png-sequence",@@ -232,3 +265,73 @@ test("locked font and straight-alpha Surface survive one real Hyperframes browseawait rm(temp, { recursive: true, force: true });}});++test("Fine Caption Paint and trail wipe survive real frame rendering", {+ skip: !enabled,+ timeout: 120_000,+}, async () => {+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-caption-fine-visual-"));+ try {+ const width = 360;+ const height = 180;+ const space = sealProgramSpace({+ contract: "svml.program-space@1",+ durationSec: 2,+ frameRate: { numerator: 10, denominator: 1 },+ });+ const narrative = parseScript("visual.svml", "<line>First second.</line>");+ const display = captionDisplaySequence(narrative, "visual.caption");+ const recipe: SvsRecipe = {+ contract: "svml.svs-recipe@1",+ path: "caption.visual",+ properties: {+ "cue-min-words": 1, "cue-max-words": 4,+ "stack-order": 10, x: 0.5, y: 0.82, width: 0.92,+ "anchor-x": "center", "anchor-y": "bottom",+ font: "Arial", weight: 800, size: 44, "line-height": 1,+ align: "center", fill: "#FFFFFF",+ "stroke-color": "#000000", "stroke-width": 2,+ "shadow-color": "#000000", "shadow-opacity": 0.8,+ "shadow-x": 0, "shadow-y": 2, "shadow-blur": 4,+ background: "#111111CC", padding: "10 14", radius: 10,+ karaoke: "trail", "karaoke-transition": "wipe", "active-fill": "#FFD54A",+ },+ };+ const style = fineCaptionStyle("visual", recipe);+ const program = resolveCaptionProgram(display, "visual-program", style, []);+ const projection: TimedCaptionProjection = {+ contract: "svml.timed-caption-projection@1",+ displaySequenceId: display.id,+ cues: [{+ id: "visual-cue", runId: program.runs[0]!.id, styleId: style.id, segmentId: "line",+ startSec: 0, endSec: 2,+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),+ fields: [],+ }],+ };+ const track = renderFineCaption(projection, program, display, space);+ const document = compileHyperframesDocument(sealComposition({+ contract: "svml.composition@1",+ id: "caption-fine-visual",+ canvas: { width, height, clearColor: "#000000" },+ tracks: [track],+ }), space);+ await writeFile(path.join(temp, "index.html"), document.html);+ const output = path.join(temp, "frames");+ await mkdir(output);+ const render = spawnSync(process.execPath, [+ hyperframesCli, "render", temp,+ "--format", "png-sequence", "--output", output, "--fps", "10", "--workers", "1",+ "--no-browser-gpu", "--no-best-effort", "--quiet",+ ], { encoding: "utf8", timeout: 110_000 });+ assert.equal(render.status, 0, `${render.stdout}\n${render.stderr}`);+ const frames = await collectPngs(output);+ assert.equal(frames.length, 20);+ const initialYellow = yellowPixels(frames[0]!, width, height);+ const finalYellow = yellowPixels(frames.at(-1)!, width, height);+ assert.ok(initialYellow < 10, `first wipe frame unexpectedly painted ${initialYellow} active pixels`);+ assert.ok(finalYellow > 100, `trail wipe painted only ${finalYellow} active pixels at the end`);+ } finally {+ await rm(temp, { recursive: true, force: true });+ }+});diff --git a/spec/caption-fine.md b/spec/caption-fine.mdindex 516bfd75..f61e27d4 100644--- a/spec/caption-fine.md+++ b/spec/caption-fine.md@@ -1,64 +1,155 @@# Fine Caption Style Family-Status: implemented baseline; parameter surface remains deliberately small and pre-release.+Status: complete public design recorded; implementation proceeds by the evidence gates below.-## Purpose+## Purpose and boundary-`@narratage/caption-fine` is one concrete Caption Style family. In this family, "fine-grained"-means that immutable Script display words are divided into short semantic Cues. It does not mean-that individual words receive ornamental semantic classes.+`@narratage/caption-fine` is the official field-free, fine-grained Caption Style family. "Fine"+means that immutable display Atoms are planned into short semantic Cues and then rendered through+one deterministic visual system. It does **not** mean `important`, semantic emphasis classes or+random per-word styling.-Every word in one Cue uses one uniform static appearance. This family declares:+The package consumes three facts which already exist:-```text-planning.fields = []-```+1. a `CaptionProgram`, which assigns one complete Style to every display Word;+2. a `TimedCaptionProjection`, which gives every Cue and whole Atom a proven time window;+3. a `CaptionDisplaySequence`, which preserves the author's exact visible text and punctuation.-It has no `important`, emphasis, active-word, karaoke or random-size semantics. Another package may-declare fields or motion without changing this family or the common Caption contract.--## Package boundary+It emits one ordinary peer `VisualTrack`. It never changes text, calls a model, infers time inside a+Dual Text Atom or adds Caption metadata to another contract.| Owner | Responsibility ||---|---|-| `@narratage/caption` | generic Style envelope, Cue/field Plan law, total Style assignment and SemanticMap timing join |-| `@narratage/caption-fine` | Fine Recipe schema, deterministic layout/paint interpretation and VisualTrack lowering |-| `@narratage/media` | renderable byte identities such as the existing `FontArtifactRef`, never Caption typography policy |-| `@narratage/visual-ir` | closed terminal element/style/keyframe vocabulary |+| `@narratage/caption` | generic Style envelope, Cue/field Plan law, total Style assignment and Atom timing join |+| `@narratage/caption-fine` | Fine Recipe schema, layout, Paint, local motion and VisualTrack lowering |+| `@narratage/media` | exact reusable bytes such as `FontArtifactRef`, never Fine typography policy |+| `@narratage/visual-ir` | closed code-free terminal element/style/keyframe vocabulary || Core | graph demand, validation, derivation and execution only; no Caption meaning |-Using a Type owned by Caption or Media does not transfer implementation ownership. Removing a Fine-field, changing a Fine anchor or revising its box layout must not modify Caption, Media, Visual IR,-Composition or Core when the existing public Types can already carry the result.+Changing a Fine shadow, anchor, karaoke mode or Cue box must not modify Caption, Media,+Composition, Visual IR or Core while their existing public contracts can express the result.++## Complete orthogonal surface++The complete restrained family has these independent dimensions. Properties not listed here are+not deferred accidents: they are deliberate non-goals for this family.++### 1. Cue planning++- `cue-min-words`+- `cue-max-words`++The planner may only cut between whole Atoms. An indivisible author Atom may exceed the preferred+maximum; it is never split to satisfy a number.++### 2. Placement and layout++- normalized `x`, `y`, `width`+- `anchor-x: left | center | right`+- `anchor-y: top | center | bottom`+- `align: left | center | right`+- `direction: ltr | rtl`+- `line-height`, `letter-spacing`, `word-gap`+- absolute `stack-order`++The Cue naturally wraps only between Atoms. Words inside one Atom never wrap apart. A hard+`max-lines` control is intentionally unavailable until exact font bytes and browser-measured layout+can fail the build rather than silently clip or truncate authored text.++### 3. Typography++- `font`, `weight`, `size`, `font-style: normal | italic`++The current Recipe names an environment font. Exact `FontArtifactRef` input is a shared typography+reproducibility gate and remains visible in the implementation table below.++### 4. Base glyph Paint++- solid `fill` and `opacity`+- one outline: `stroke-color`, `stroke-width`+- one shadow: color, opacity, x/y offset and blur+- one glow: color, opacity and blur++Shadow and glow are two independently authored contributions lowered into one deterministic+`text-shadow` declaration. Multiple arbitrary layers, textures, gradients, bevel, extrusion and+long-shadow generators are outside this restrained family.++### 5. Cue box Paint++- solid `background`+- `border-color`, `border-width`+- horizontal/vertical `padding`+- `radius`++Backdrop sampling is forbidden because it would make this Track inspect another Track's pixels.++### 6. Karaoke Paint and timing++- `karaoke: off | current | trail`+- `karaoke-transition: step | wipe`+- a complete active glyph Paint with the same fill/opacity/stroke/shadow/glow shape as base Paint++`current` activates only the Atom whose measured window contains the frame. `trail` retains every+activated Atom through the end of the Cue. `step` swaps the whole Atom; `wipe` reveals its active+layer across that Atom's measured window. RTL reverses the wipe direction.++Karaoke is deliberately Atom-grained. In ordinary text an Atom is normally one visible Word. In+`<45% | forty five percent>` the authored visible `45%` is one Atom and activates as one unit. In a+multi-word display Atom, the whole authored Atom activates together. No downstream package invents+internal Word timestamps that the author and audio evidence never supplied.++### 7. Restrained local motion++- Cue enter/exit: `none | fade`, with one frame duration+- Atom reveal: `all | on-start`+- active Atom scale++These motions affect only Fine's own elements. Typewriter, bounce, rotation, path motion and random+variation are intentionally excluded until a concrete reusable style needs them.++## One renderer, one layout tree++Static and karaoke output share this structure:++```text+placement+└── cue box+ ├── atom+ │ ├── base words+ │ └── active overlay (only when karaoke is enabled)+ │ └── active words+ └── atom ...+```-## Accepted dimensions+The active overlay reuses the same Atom geometry; karaoke does not fork a second DOM renderer.+Every animation lowers to frame-addressed `VisualTrack` keyframes before HyperFrames sees it.-The Style-family surface will be designed across four independent concerns:+## Defaults and compatibility-1. Cue planning: only minimum/maximum display-word bounds and a fixed no-rewrite planning law.-2. Geometry: placement anchor, bounded range, alignment, line packing and absolute stack order.-3. Typography: deterministic font choice and ordinary size/spacing metrics.-4. Paint: restrained readability controls such as solid fill, outline, shadow and an optional- content background.+The original fifteen baseline properties remain required, so a minimal Recipe is explicit about+planning, geometry, typography and its visible box. New dimensions are optional and resolve to a+complete immutable parameter object:-The exact property names, defaults and bounds are not frozen by this document. Motion, gradients,-glow, long shadow, backdrop sampling, case rewriting, random variation and field-dependent paint-must not enter merely to reproduce the old engine's option count.+- top-left anchor, LTR, normal font, zero letter spacing and a one-quarter-em word gap;+- no stroke, shadow, glow or border;+- karaoke off, Cue motion off, all Atoms visible, scale 1;+- when karaoke is enabled without another active Paint, active fill defaults to `#FFD54A` and the+ other active Paint dimensions inherit base Paint.-Cue timing is not a fifth Style dimension. It comes from the independent `TimedCaptionProjection`:-the first and last included whole-Atom windows determine the Cue window. Fine adds no hidden hold,-lead, fade or provider-dependent timing, and it receives no display-Word timestamps.+Unknown properties are rejected. Defaults are package implementation policy and therefore covered+by its implementation digest; they are not hidden Runtime behavior.-## Font boundary+## Evidence gates and implementation order-The current executable Fine baseline names an environment font in its Recipe. Exact font bytes are-a separate reproducibility problem shared by Text, Caption, Ranking and future typography-components. `@narratage/media` already defines `FontArtifactRef`; adding an author Surface for local-font files and connecting that value explicitly is separate work. It must not be smuggled into the-Fine redesign as a Caption-specific Media contract.+This is one complete design, delivered progressively rather than three incompatible versions:-## Remaining visual evidence+1. **Resolved model and static lowering** — complete parameters, anchors, layout, base/active Paint,+ Cue box and strict validation.+2. **Timed lowering** — current/trail, step/wipe, Cue fades, Atom reveal and active scale using only+ proven whole-Atom time.+3. **Reproducibility freeze** — exact Font Artifact input, real browser/pixel fixtures for wrapping,+ outline/glow and all karaoke modes, then decide whether measured `max-lines` can be exposed+ without clipping.-The field-free contract is executable. Before freezing the family's visual surface, add real-browser/pixel evidence for placement, wrapping and basic paint and review whether the current-bounded left/top geometry is the smallest useful public parameter set.+The first two gates require no common-contract change. The third may add an explicit Font input to+the Fine Surface/fragment, but still does not belong in Core or common Caption.diff --git a/spec/caption-program.md b/spec/caption-program.mdindex 80cfa43e..b7bd1764 100644--- a/spec/caption-program.md+++ b/spec/caption-program.md@@ -144,8 +144,8 @@ Each timed Cue selects the complete rendering payload of its resolved Style. Onerenderer returns one ordinary `VisualTrack`. In the first contract, all Styles in one Program usethe same rendering family.-`@narratage/caption-fine` is the first official family. It declares no fields and uses one uniform-static appearance for all Words in a Cue. Another package may define karaoke or field-dependent+`@narratage/caption-fine` is the first official family. It declares no fields and owns restrained+uniform Cue appearance plus optional whole-Atom karaoke. Another package may define field-dependentpaint without modifying Script, Caption, Composition or Core.Film does not recognize Caption specially. It folds the resulting peer Track beside Speech,