@hypit/hypit 0.0.1 → 0.1.0

package/packages/caption-fine/src/schedule.ts

@@ -0,0 +1,126 @@
+import { applyCaptionMute, assertCaptionProgramForDocument, assertTimedCaptionProjection } from "@hypit/caption";
+import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import type { CaptionDocument } from "@hypit/narrative";
+
+import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
+import type { FineCaptionParameters, FineCaptionSchedule, FineCaptionScheduledCue } from "./types.js";
+
+function assertIntegerFrame(value: number, label: string): void {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative integer Frame`);
+}
+
+/**
+ * Resolve visible Cue envelopes before the renderer runs.
+ *
+ * Semantic unit timing stays untouched. `leadFrames` and `tailFrames` only
+ * widen the visible envelope, and `cut` prevents adjacent Cues from competing
+ * for the same handoff interval without shortening either Cue's spoken time.
+ */
+export function scheduleFineCaption(
+  projection: TimedCaptionProjection,
+  program: CaptionProgram,
+  document: CaptionDocument,
+): FineCaptionSchedule {
+  assertTimedCaptionProjection(projection);
+  assertCaptionProgramForDocument(program, document);
+  if (projection.documentId !== document.id) throw new Error("Fine Caption Schedule received another CaptionDocument");
+  if (projection.narrativeId !== document.narrativeId) {
+    throw new Error("Fine Caption Schedule received a CaptionDocument from another Narrative");
+  }
+  if (program.wordRuns.length !== 0) {
+    throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");
+  }
+  const visibleProjection = applyCaptionMute(projection, program, document);
+
+  const parameters = new Map<string, FineCaptionParameters>();
+  for (const style of program.styles) {
+    if (style.rendering.family !== FINE_CAPTION_FAMILY) {
+      throw new Error(`Fine Caption cannot schedule Style family ${style.rendering.family}`);
+    }
+    const value = style.rendering.parameters as unknown as FineCaptionParameters;
+    assertFineCaptionParameters(value);
+    parameters.set(style.id, value);
+  }
+
+  const desired = visibleProjection.cues.map((cue): FineCaptionScheduledCue => {
+    const style = parameters.get(cue.styleId);
+    if (style === undefined) throw new Error(`Fine Caption Cue ${cue.id} references unknown Style ${cue.styleId}`);
+    const visibleStartFrame = Math.max(0, cue.startFrame - style.timing.leadFrames);
+    const visibleEndFrameExclusive = cue.endFrameExclusive + style.timing.tailFrames;
+    return {
+      id: cue.id,
+      styleId: cue.styleId,
+      semanticStartFrame: cue.startFrame,
+      semanticEndFrameExclusive: cue.endFrameExclusive,
+      visibleStartFrame,
+      visibleEndFrameExclusive,
+      units: cue.units,
+    };
+  });
+
+  const cues: FineCaptionScheduledCue[] = [];
+  for (const wanted of desired) {
+    let cue = wanted;
+    const previous = cues.at(-1);
+    if (previous !== undefined) {
+      const previousStyle = parameters.get(previous.styleId)!;
+      const currentStyle = parameters.get(cue.styleId)!;
+      if (previousStyle.timing.handoff === "cut" || currentStyle.timing.handoff === "cut") {
+        const previousEnd = Math.max(
+          previous.semanticEndFrameExclusive,
+          Math.min(previous.visibleEndFrameExclusive, cue.semanticStartFrame),
+        );
+        cues[cues.length - 1] = { ...previous, visibleEndFrameExclusive: previousEnd };
+        cue = { ...cue, visibleStartFrame: Math.min(cue.semanticStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
+      }
+    }
+    cues.push(cue);
+  }
+
+  const ids = new Set<string>();
+  for (const cue of cues) {
+    if (ids.has(cue.id)) throw new Error(`Fine Caption Schedule repeats Cue ${cue.id}`);
+    ids.add(cue.id);
+    assertIntegerFrame(cue.semanticStartFrame, `Fine Caption Cue ${cue.id} semantic start`);
+    assertIntegerFrame(cue.semanticEndFrameExclusive, `Fine Caption Cue ${cue.id} semantic end`);
+    assertIntegerFrame(cue.visibleStartFrame, `Fine Caption Cue ${cue.id} visible start`);
+    assertIntegerFrame(cue.visibleEndFrameExclusive, `Fine Caption Cue ${cue.id} visible end`);
+    if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
+      || cue.visibleStartFrame > cue.semanticStartFrame
+      || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+      || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+      throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+    }
+  }
+  return {
+    spaceId: projection.spaceId,
+    narrativeId: projection.narrativeId,
+    documentId: document.id,
+    cues,
+  };
+}
+
+export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {
+  if (!value.spaceId || !value.narrativeId || !value.documentId) {
+    throw new Error("Fine Caption Schedule provenance is empty");
+  }
+  const ids = new Set<string>();
+  for (const cue of value.cues) {
+    if (!cue.id || !cue.styleId || ids.has(cue.id) || cue.units.length === 0) {
+      throw new Error("Fine Caption Schedule contains an invalid Cue");
+    }
+    ids.add(cue.id);
+    for (const [label, frame] of [
+      ["semantic start", cue.semanticStartFrame],
+      ["semantic end", cue.semanticEndFrameExclusive],
+      ["visible start", cue.visibleStartFrame],
+      ["visible end", cue.visibleEndFrameExclusive],
+    ] as const) assertIntegerFrame(frame, `Fine Caption Cue ${cue.id} ${label}`);
+    if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
+      || cue.visibleStartFrame > cue.semanticStartFrame
+      || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+      || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+      throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+    }
+  }
+}

package/packages/caption-fine/src/spacing.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a word gap belongs between two adjacent display surfaces.
+ *
+ * A Display Word is one lexical unit, and in Han, Hiragana and Katakana that unit is a single
+ * character. A gap applied to every boundary therefore sets Chinese and Japanese as though every
+ * character were a word, so each boundary decides its own gap from the two characters that meet
+ * across it.
+ *
+ * The classes follow pangu.js: a CJK character beside a half-width letter, digit, bracket or
+ * operator takes one space. The gap pangu inserts is an ordinary space, so a boundary either
+ * carries the Style's `word-gap` or carries nothing.
+ */
+
+/** The three scripts the Script tokenizer treats as one character per lexical unit. */
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u;
+
+/**
+ * Full-width punctuation, including the bracket, quotation and dash pairs.
+ *
+ * These glyphs are drawn inside a full-width em box with their own side bearing, so a gap beside
+ * one paints a second space over the one the font already carries. The ranges cover CJK
+ * punctuation, the full-width ASCII forms, the curly quotes and the ellipsis, and stop short of
+ * the full-width digits and letters at `０-９`, `Ａ-Ｚ` and `ａ-ｚ`, which
+ * are ordinary word characters.
+ */
+const FULL_WIDTH_PUNCTUATION =
+  /[、-〃〈-】〔-〟！-／：-＠［-｀｛-･‘’“”—…]/u;
+
+/**
+ * Half-width brackets and quotation marks take their space on the outside of the pair, which falls
+ * out of reading the boundary characters: `displayWordSurfaces` attaches an opener to the surface
+ * that follows it and a closer to the surface before it, so `中文(注)中文` meets `(` on the right
+ * of one boundary and `)` on the left of the next, and both take a gap.
+ *
+ * A boundary with no CJK character on either side keeps the gap it has today. Latin spacing is not
+ * what this decides.
+ */
+export function wordGapBetween(previous: string, next: string): boolean {
+  const left = [...previous].at(-1);
+  const right = [...next].at(0);
+  if (left === undefined || right === undefined) return false;
+  if (FULL_WIDTH_PUNCTUATION.test(left) || FULL_WIDTH_PUNCTUATION.test(right)) return false;
+  return !(CJK.test(left) && CJK.test(right));
+}
+
+/** Every boundary in order. The first surface opens the run, so its entry is always `false`. */
+export function wordGaps(surfaces: readonly string[]): readonly boolean[] {
+  return surfaces.map((surface, index) => {
+    const previous = surfaces[index - 1];
+    return previous === undefined ? false : wordGapBetween(previous, surface);
+  });
+}
+
+/**
+ * A run whose boundaries all agree carries one `column-gap` on its container. A mixed run cannot,
+ * because `column-gap` is uniform, and takes a margin per element instead.
+ */
+export function uniformGap(gaps: readonly boolean[]): boolean | undefined {
+  const boundaries = gaps.slice(1);
+  if (boundaries.length === 0) return false;
+  if (boundaries.every((gap) => gap)) return true;
+  return boundaries.some((gap) => gap) ? undefined : false;
+}
+
+/** Join surfaces back into prose, spacing only the boundaries that carry a gap. */
+export function joinSurfaces(surfaces: readonly string[], separator: string): string {
+  const gaps = wordGaps(surfaces);
+  return surfaces.map((surface, index) => (gaps[index] ? `${separator}${surface}` : surface)).join("");
+}

package/packages/caption-fine/src/style.ts

@@ -0,0 +1,370 @@
+import type { CaptionStyleIntent } from "@hypit/caption";
+import { sealCaptionStyle } from "@hypit/caption";
+import { assertFontArtifactRef } from "@hypit/media";
+import type { FontArtifactRef } from "@hypit/media";
+import { canonicalStringify } from "@hypit/protocol";
+import type { SvsRecipe } from "@hypit/svs";
+
+import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";
+import {
+  fineCaptionOneShotMotions,
+  fineCaptionOptionalRecipeProperties,
+  fineCaptionRequiredRecipeProperties,
+} from "./recipe.js";
+
+export const FINE_CAPTION_FAMILY = "@hypit/caption-fine@1";
+
+const ALLOWED_PROPERTIES = new Set<string>([
+  ...fineCaptionRequiredRecipeProperties,
+  ...fineCaptionOptionalRecipeProperties,
+]);
+
+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, 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, 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 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`);
+  }
+  return property;
+}
+
+function padding(value: string): { readonly x: number; readonly y: number } {
+  const parts = value.trim().split(/\s+/u).map(Number);
+  if ((parts.length !== 1 && parts.length !== 2) || parts.some((item) => !Number.isFinite(item) || item < 0)) {
+    throw new Error("Fine Caption Recipe padding must contain one or two non-negative pixel numbers");
+  }
+  return { y: parts[0]!, x: parts[1] ?? parts[0]! };
+}
+
+function optionalGradient(
+  recipe: SvsRecipe,
+  prefix: "" | "active-",
+  base?: FineCaptionGlyphPaint["gradient"],
+): FineCaptionGlyphPaint["gradient"] | undefined {
+  const fromName = `${prefix}gradient-from`;
+  const toName = `${prefix}gradient-to`;
+  const hasFrom = Object.hasOwn(recipe.properties, fromName);
+  const hasTo = Object.hasOwn(recipe.properties, toName);
+  const hasAngle = Object.hasOwn(recipe.properties, `${prefix}gradient-angle`);
+  if (!hasFrom && !hasTo && !hasAngle) return prefix === "active-" ? undefined : base;
+  if (!hasFrom || !hasTo) {
+    throw new Error(`Fine Caption Recipe ${prefix}gradient requires both from and to colors`);
+  }
+  return {
+    from: color(recipe, fromName),
+    to: color(recipe, toName),
+    angleDeg: number(recipe, `${prefix}gradient-angle`, base?.angleDeg ?? 90),
+  };
+}
+
+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;
+  const baseLongShadow = fallback("longShadow") as FineCaptionGlyphPaint["longShadow"] | undefined;
+  const gradient = optionalGradient(recipe, prefix, base?.gradient);
+  return {
+    fill: color(recipe, `${prefix}fill`, prefix === "active-" ? "#FFD54A" : base?.fill),
+    ...(gradient === undefined ? {} : { gradient }),
+    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),
+      spreadPx: number(recipe, `${prefix}shadow-spread`, baseShadow?.spreadPx ?? 0),
+    },
+    longShadow: {
+      color: color(recipe, `${prefix}long-shadow-color`, baseLongShadow?.color ?? "#000000"),
+      opacity: number(recipe, `${prefix}long-shadow-opacity`, baseLongShadow?.opacity ?? 0),
+      distancePx: number(recipe, `${prefix}long-shadow-distance`, baseLongShadow?.distancePx ?? 0),
+      angleDeg: number(recipe, `${prefix}long-shadow-angle`, baseLongShadow?.angleDeg ?? 45),
+    },
+    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),
+      spreadPx: number(recipe, `${prefix}glow-spread`, baseGlow?.spreadPx ?? 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.longShadow.color, `${label} long shadow color`);
+  assertColor(value.glow.color, `${label} glow color`);
+  assertOpacity(value.shadow.opacity, `${label} shadow opacity`);
+  assertOpacity(value.longShadow.opacity, `${label} long shadow opacity`);
+  assertOpacity(value.glow.opacity, `${label} glow opacity`);
+  for (const [name, metric] of [
+    ["stroke width", value.stroke.widthPx], ["shadow blur", value.shadow.blurPx],
+    ["long shadow distance", value.longShadow.distancePx], ["glow blur", value.glow.blurPx],
+    ["glow spread", value.glow.spreadPx],
+  ] as const) {
+    if (!Number.isFinite(metric) || metric < 0) throw new Error(`${label} ${name} is invalid`);
+  }
+  if (!Number.isFinite(value.shadow.offsetXPx) || !Number.isFinite(value.shadow.offsetYPx)
+    || !Number.isFinite(value.shadow.spreadPx)) {
+    throw new Error(`${label} shadow offset is invalid`);
+  }
+  if (!Number.isFinite(value.longShadow.angleDeg)) throw new Error(`${label} long shadow angle is invalid`);
+  if (value.gradient !== undefined) {
+    assertColor(value.gradient.from, `${label} gradient from`);
+    assertColor(value.gradient.to, `${label} gradient to`);
+    if (!Number.isFinite(value.gradient.angleDeg)) throw new Error(`${label} gradient angle is invalid`);
+  }
+}
+
+export function fineCaptionParameters(
+  recipe: SvsRecipe,
+  exactFonts: readonly FontArtifactRef[],
+): FineCaptionParameters {
+  for (const name of fineCaptionRequiredRecipeProperties) 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 activeBoxPadding = padding(string(recipe, "active-box-padding", "0"));
+  const fontSizePx = number(recipe, "size");
+  const basePaint = glyphPaint(recipe, "");
+  const cueEnter = choice(recipe, "cue-enter", fineCaptionOneShotMotions, "none");
+  const parameters: FineCaptionParameters = {
+
+    stackingOrder: integer(recipe, "stack-order"),
+    placement: {
+      x: number(recipe, "x"),
+      y: number(recipe, "y"),
+      width: number(recipe, "width"),
+      ...(Object.hasOwn(recipe.properties, "height") ? { height: number(recipe, "height") } : {}),
+      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),
+      blockAlign: choice(recipe, "block-align", ["start", "center", "end"] as const, "center"),
+      direction: choice(recipe, "direction", ["ltr", "rtl"] as const, "ltr"),
+      inlineSize: choice(recipe, "inline-size", ["hug", "fixed"] as const, "hug"),
+      wrap: choice(recipe, "wrap", ["word", "grapheme"] as const, "word"),
+      ...(Object.hasOwn(recipe.properties, "max-lines") ? { maxLines: integer(recipe, "max-lines") } : {}),
+      ...(Object.hasOwn(recipe.properties, "max-words-per-line")
+        ? { maxWordsPerLine: integer(recipe, "max-words-per-line") } : {}),
+      lineHeight: number(recipe, "line-height"),
+      letterSpacingPx: number(recipe, "letter-spacing", 0),
+      wordGapPx: number(recipe, "word-gap", fontSizePx * 0.25),
+    },
+    typography: {
+      fontSizePx,
+      kerning: choice(recipe, "kerning", ["auto", "normal", "none"] as const, "auto"),
+      variantCaps: choice(recipe, "caps", ["normal", "small-caps", "all-small-caps"] as const, "normal"),
+      textTransform: choice(recipe, "text-transform", ["none", "uppercase", "lowercase", "capitalize"] as const, "none"),
+      exactFonts: [...exactFonts],
+    },
+    basePaint,
+    activePaint: glyphPaint(recipe, "active-", basePaint),
+    underline: {
+      mode: choice(recipe, "underline", ["off", "always"] as const, "off"),
+      color: color(recipe, "underline-color", basePaint.fill),
+      thicknessPx: number(recipe, "underline-thickness", 2),
+      offsetPx: number(recipe, "underline-offset", 4),
+    },
+    activeUnderline: {
+      mode: choice(recipe, "active-underline", ["off", "current", "trail"] as const, "off"),
+      color: color(recipe, "active-underline-color", "#FFD54A"),
+      thicknessPx: number(recipe, "active-underline-thickness", 3),
+      offsetPx: number(recipe, "active-underline-offset", 4),
+    },
+    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"),
+      shadow: {
+        color: color(recipe, "cue-shadow-color", "#000000"),
+        opacity: number(recipe, "cue-shadow-opacity", 0),
+        offsetXPx: number(recipe, "cue-shadow-x", 0),
+        offsetYPx: number(recipe, "cue-shadow-y", 0),
+        blurPx: number(recipe, "cue-shadow-blur", 0),
+        spreadPx: number(recipe, "cue-shadow-spread", 0),
+      },
+    },
+    karaoke: {
+      mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, "off"),
+      transition: choice(recipe, "karaoke-transition", ["step", "wipe"] as const, "step"),
+    },
+    activeBox: {
+      mode: choice(recipe, "active-box", ["off", "current", "trail"] as const, "off"),
+      continuity: choice(recipe, "active-box-continuity", ["isolated", "joined"] as const, "isolated"),
+      background: color(recipe, "active-box-background", "#FFD54A"),
+      borderColor: color(recipe, "active-box-border-color", "#00000000"),
+      borderWidthPx: number(recipe, "active-box-border-width", 0),
+      paddingXPx: activeBoxPadding.x,
+      paddingYPx: activeBoxPadding.y,
+      radiusPx: number(recipe, "active-box-radius", 8),
+      enter: choice(recipe, "active-box-enter", fineCaptionOneShotMotions, "none"),
+      exit: choice(recipe, "active-box-exit", fineCaptionOneShotMotions, "none"),
+      transitionFrames: integer(recipe, "active-box-transition-frames", 0),
+    },
+    motion: {
+      cueEnter,
+      cueExit: choice(recipe, "cue-exit", fineCaptionOneShotMotions, "none"),
+      cueEnterFrames: integer(recipe, "cue-enter-frames", 0),
+      cueExitFrames: integer(recipe, "cue-exit-frames", 0),
+      ...(Object.hasOwn(recipe.properties, "cue-enter-start-scale")
+        ? { cueEnterStartScale: number(recipe, "cue-enter-start-scale") } : {}),
+      atomEnter: choice(recipe, "atom-enter", fineCaptionOneShotMotions, "none"),
+      atomEnterFrames: integer(recipe, "atom-enter-frames", 0),
+      atomExit: choice(recipe, "atom-exit", fineCaptionOneShotMotions, "none"),
+      atomExitFrames: integer(recipe, "atom-exit-frames", 0),
+      atomReveal: choice(recipe, "atom-reveal", ["all", "on-start", "typewriter"] as const, "all"),
+      activeResponse: choice(recipe, "active-response", fineCaptionOneShotMotions, "none"),
+      activeResponseFrames: integer(recipe, "active-response-frames", 6),
+      activeScale: number(recipe, "active-scale", 1.08),
+      slideDistancePx: number(recipe, "slide-distance", 24),
+      loop: choice(recipe, "loop", ["none", "shake", "wobble", "glow-pulse", "breathe", "float", "pulse", "flicker"] as const, "none"),
+      loopTarget: choice(recipe, "loop-target", ["cue", "active-atom"] as const, "cue"),
+      loopPeriodFrames: integer(recipe, "loop-period-frames", 12),
+      loopIntensity: number(recipe, "loop-intensity", 1),
+    },
+    timing: {
+      leadFrames: integer(recipe, "lead-frames", 0),
+      tailFrames: integer(recipe, "tail-frames", 0),
+      handoff: choice(recipe, "handoff", ["cut", "overlap"] as const, "cut"),
+    },
+  };
+  assertFineCaptionParameters(parameters);
+  return parameters;
+}
+
+export function assertFineCaptionParameters(value: FineCaptionParameters): void {
+  if (!Number.isSafeInteger(value.stackingOrder) || value.stackingOrder < 0) {
+    throw new Error("Fine Caption stacking order is invalid");
+  }
+  const nonNegative = [
+    value.placement.x, value.placement.y, value.placement.width, value.typography.fontSizePx,
+    value.layout.lineHeight, value.layout.wordGapPx, value.cueBox.paddingXPx,
+    value.cueBox.paddingYPx, value.cueBox.radiusPx, value.cueBox.borderWidthPx,
+    value.underline.thicknessPx, value.underline.offsetPx, value.activeUnderline.thicknessPx,
+    value.activeUnderline.offsetPx, value.activeBox.borderWidthPx, value.activeBox.paddingXPx,
+    value.activeBox.paddingYPx, value.activeBox.radiusPx, value.activeBox.transitionFrames,
+    value.motion.cueEnterFrames, value.motion.cueExitFrames, value.motion.atomEnterFrames, value.motion.atomExitFrames,
+    value.motion.activeResponseFrames,
+    value.motion.slideDistancePx, value.motion.loopPeriodFrames, value.motion.loopIntensity,
+    value.timing.leadFrames, value.timing.tailFrames,
+    value.cueBox.shadow.blurPx,
+  ];
+  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.placement.height !== undefined && (!Number.isFinite(value.placement.height) || value.placement.height <= 0 || value.placement.height > 1))
+    || value.typography.fontSizePx <= 0 || value.layout.lineHeight <= 0
+    || !Number.isSafeInteger(value.motion.cueEnterFrames) || !Number.isSafeInteger(value.motion.cueExitFrames)
+    || !Number.isSafeInteger(value.motion.atomEnterFrames) || !Number.isSafeInteger(value.motion.atomExitFrames)
+    || !Number.isSafeInteger(value.motion.loopPeriodFrames)
+    || !Number.isSafeInteger(value.motion.activeResponseFrames)
+    || !Number.isSafeInteger(value.activeBox.transitionFrames) || value.motion.loopPeriodFrames <= 0
+    || !Number.isSafeInteger(value.timing.leadFrames) || !Number.isSafeInteger(value.timing.tailFrames)
+    || (value.layout.maxLines !== undefined && (!Number.isSafeInteger(value.layout.maxLines) || value.layout.maxLines <= 0))
+    || (value.layout.maxWordsPerLine !== undefined && (!Number.isSafeInteger(value.layout.maxWordsPerLine) || value.layout.maxWordsPerLine <= 0))
+    || (value.motion.cueEnterStartScale !== undefined
+      && (!Number.isFinite(value.motion.cueEnterStartScale) || value.motion.cueEnterStartScale < 0))
+    || 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.motion.cueEnter === "none"
+    && value.motion.cueEnterStartScale !== undefined) {
+    throw new Error("Fine Caption Cue entrance modifiers require a Cue entrance motion");
+  }
+  if (value.typography.exactFonts.length === 0) throw new Error("Fine Caption exact Font stack is empty");
+  const faces = new Set<string>();
+  for (const [index, font] of value.typography.exactFonts.entries()) {
+    assertFontArtifactRef(font, `Fine Caption exact Font ${index + 1}`);
+    const identity = canonicalStringify(font);
+    if (faces.has(identity)) throw new Error("Fine Caption exact Font stack contains a duplicate face");
+    faces.add(identity);
+  }
+  if (value.layout.maxLines !== undefined && value.layout.maxWordsPerLine === undefined) {
+    throw new Error("Fine Caption max-lines requires max-words-per-line so its rows are structural");
+  }
+  assertColor(value.cueBox.background, "Fine Caption background");
+  assertColor(value.cueBox.borderColor, "Fine Caption border color");
+  assertColor(value.cueBox.shadow.color, "Fine Caption Cue shadow color");
+  assertOpacity(value.cueBox.shadow.opacity, "Fine Caption Cue shadow opacity");
+  if (![value.cueBox.shadow.offsetXPx, value.cueBox.shadow.offsetYPx, value.cueBox.shadow.spreadPx]
+    .every(Number.isFinite)) throw new Error("Fine Caption Cue shadow contains an invalid metric");
+  assertColor(value.underline.color, "Fine Caption underline color");
+  assertColor(value.activeUnderline.color, "Fine Caption active underline color");
+  assertColor(value.activeBox.background, "Fine Caption active box background");
+  assertColor(value.activeBox.borderColor, "Fine Caption active box border color");
+  assertPaint(value.basePaint, "Fine Caption base Paint");
+  assertPaint(value.activePaint, "Fine Caption active Paint");
+}
+
+export function fineCaptionStyle(
+  id: string,
+  recipe: SvsRecipe,
+  exactFonts: readonly FontArtifactRef[],
+): CaptionStyleIntent {
+  return sealCaptionStyle({
+    id,
+    rendering: {
+      family: FINE_CAPTION_FAMILY,
+      parameters: fineCaptionParameters(recipe, exactFonts),
+    },
+  });
+}