@hypit/hypit 0.1.3 → 0.1.5

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

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
 import type { ComponentPackage } from "@hypit/component-kit";
 import type { CaptionDocument } from "@hypit/narrative";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { StoredValue } from "@hypit/protocol";
 import { canonicalize } from "@hypit/protocol";
 import type { SpatialRegionTimeline } from "@hypit/spatial";
@@ -36,7 +36,7 @@ export const captionFineComponent = {
           inline<FineCaptionSchedule>(inputs.schedule?.value, "FineCaptionSchedule"),
           inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
           inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
         )) } },
         needs: {},
       }),
@@ -48,7 +48,7 @@ export const captionFineComponent = {
           inline<FineCaptionSchedule>(inputs.schedule?.value, "FineCaptionSchedule"),
           inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
           inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<SpatialRegionTimeline>(inputs.regions?.value, "SpatialRegionTimeline"),
         )) } },
         needs: {},

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

@@ -2,7 +2,7 @@ import { captionProducers, captionTypes } from "@hypit/caption";
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
 import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 import { spatialTypes } from "@hypit/spatial";
 
 import { captionFineProducers, captionFineTypes } from "./manifest.js";
@@ -14,21 +14,15 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
 export const fineCaptionTrackFragment = sealGraphFragment({
   inputs: [
     { name: "document", type: narrativeTypes.captionDocument },
-    { name: "semantic", type: semanticTrackTypes.track },
+    { name: "timeline", type: timelineTypes.track },
     { name: "program", type: captionTypes.program },
   ],
   operations: [
-    {
-      id: "caption:space",
-      producer: semanticTrackProducers.projectProgramSpace,
-      inputs: { track: input("semantic") },
-      result: { kind: "output", name: "space" },
-    },
     {
       id: "caption:temporalize-document",
       producer: captionProducers.temporalizeDocument,
       inputs: {
-        document: input("document"), semantic: input("semantic"), program: input("program"),
+        document: input("document"), timeline: input("timeline"),
       },
       result: { kind: "output", name: "caption" },
     },
@@ -45,7 +39,7 @@ export const fineCaptionTrackFragment = sealGraphFragment({
       producer: captionFineProducers.render,
       inputs: {
         schedule: operation("caption-fine:schedule"), program: input("program"),
-        document: input("document"), space: operation("caption:space"),
+        document: input("document"), timeline: input("timeline"),
       },
       result: { kind: "output", name: "track" },
     },
@@ -68,22 +62,16 @@ export const fineCaptionTrackFragment = sealGraphFragment({
 export const fineCaptionRegionTrackFragment = sealGraphFragment({
   inputs: [
     { name: "document", type: narrativeTypes.captionDocument },
-    { name: "semantic", type: semanticTrackTypes.track },
+    { name: "timeline", type: timelineTypes.track },
     { name: "program", type: captionTypes.program },
     { name: "regions", type: spatialTypes.regionTimeline },
   ],
   operations: [
-    {
-      id: "caption:space",
-      producer: semanticTrackProducers.projectProgramSpace,
-      inputs: { track: input("semantic") },
-      result: { kind: "output", name: "space" },
-    },
     {
       id: "caption:temporalize-document",
       producer: captionProducers.temporalizeDocument,
       inputs: {
-        document: input("document"), semantic: input("semantic"), program: input("program"),
+        document: input("document"), timeline: input("timeline"),
       },
       result: { kind: "output", name: "caption" },
     },
@@ -100,7 +88,7 @@ export const fineCaptionRegionTrackFragment = sealGraphFragment({
       producer: captionFineProducers.renderWithRegions,
       inputs: {
         schedule: operation("caption-fine:schedule"), program: input("program"),
-        document: input("document"), space: operation("caption:space"), regions: input("regions"),
+        document: input("document"), timeline: input("timeline"), regions: input("regions"),
       },
       result: { kind: "output", name: "track" },
     },

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

@@ -17,3 +17,5 @@ export {
 } from "./style.js";
 export { decodeFineCaptionStyleSurface, decodeFineCaptionTrackSurface } from "./surface.js";
 export type * from "./types.js";
+
+export { fineCaptionEditableDefaults } from "./recipe.js";

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

@@ -1,12 +1,15 @@
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import type { Timeline } from "@hypit/timeline";
 import { readFile } from "node:fs/promises";
 
 import { captionManifest, captionModuleRef, captionTypes } from "@hypit/caption";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
 import { mediaDependency, mediaTypes } from "@hypit/media";
 import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
 import { spatialDependency, spatialTypes } from "@hypit/spatial";
 import { svsRecipeType } from "@hypit/svs";
 
@@ -35,7 +38,7 @@ export const captionFineMarkupSurfaces = [
         summary: "Resolves one SVS Recipe and one exact font stack into a complete fine-grained Caption Style.",
         attributes: [
           { name: "id", kind: "identifier", required: true,
-            summary: "Names this Style so a Caption Program can assign it." },
+            summary: "Names this Style so a timed Use can select it." },
           { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
             summary: "Chooses the Recipe that carries Cue geometry, Paint and local motion.",
             recipe: [
@@ -206,7 +209,7 @@ export const captionFineMarkupSurfaces = [
               { name: "karaoke", required: false, values: ["off", "current", "trail"], fallback: "off",
                 summary: "Decides whether the active Paint marks only the Word being spoken or every Word up to it." },
               { name: "karaoke-transition", required: false, values: ["step", "wipe"], fallback: "step",
-                summary: "Decides whether the karaoke Paint snaps at the Word boundary or sweeps across the glyphs." },
+                summary: "step activates each whole timed unit at its start (normally one Han character in Chinese); wipe sweeps inside that unit's glyphs during its own interval." },
               { name: "active-box", required: false, values: ["off", "current", "trail"], fallback: "off",
                 summary: "Decides whether a highlight box sits behind the Word being spoken or behind every Word up to it." },
               { name: "active-box-continuity", required: false, values: ["isolated", "joined"], fallback: "isolated",
@@ -295,9 +298,9 @@ export const captionFineMarkupSurfaces = [
       },
     },
     {
-      name: "track", tag: "Track", mode: "structured", outputs: [captionFineTypes.schedule, compositionTypes.visualTrack],
+      name: "track", tag: "Track", mode: "structured", outputs: [captionFineTypes.schedule, compositionTypes.visualTrack, captionTypes.program, captionTypes.timedProjection, captionTypes.header, captionTypes.filter, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window],
       vocabulary: {
-        summary: "Joins the authored CaptionDocument against the SemanticTrack and renders it as one ordinary peer VisualTrack.",
+        summary: "Joins the authored CaptionDocument against the Timeline and renders it as one ordinary peer VisualTrack.",
         appearance: "One block of caption text wrapped into lines inside a rounded Cue box, placed at a Recipe-chosen point on the Canvas and spanning a fraction of its width. Cues follow the speech one after another, each arriving and leaving with its own motion, and the Words of a Cue either stand there together from its first Frame or uncover as they are spoken. As the speech advances, the Word being spoken, or every Word up to it, is repainted in the active Paint, snapping at the Word boundary or sweeping across the glyphs, and it may take a rule beneath it, a rounded highlight capsule behind it and a brief pop at the moment it becomes the spoken one. That capsule either stands alone on each Atom or grows as one continuous run over everything already read, following the Words across line breaks.\n\nEvery Cue uses the ordered exact font stack its Style names, with fallback faces supplying glyphs for other scripts. Emphasis varies by timed unit through the active Paint. Lines follow the common flow, so a line cannot be given a separate face, colour or weight of its own. A caption whose lines are set in different typefaces is outside what this Track can draw.",
         preview: previewImage("Track.png"),
         attributes: [
@@ -305,23 +308,30 @@ export const captionFineMarkupSurfaces = [
             summary: "Names this Track so its rendered output can be placed in a Film." },
           { name: "document", kind: "reference", required: true, accepts: [narrativeTypes.captionDocument],
             summary: "Chooses the Script-owned CaptionDocument." },
-          { name: "semantic", kind: "reference", required: true, accepts: [semanticTrackTypes.track],
-            summary: "Chooses the continuous SemanticTrack whose Word anchors give every Cue its time." },
-          { name: "program", kind: "reference", required: true, accepts: [captionTypes.program],
-            summary: "Chooses the Style assignment that decides which Style each run is rendered in." },
+          { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
+            summary: "Chooses the continuous Timeline whose Word anchors give every Cue its time." },
           { name: "regions", kind: "reference", required: false, accepts: [spatialTypes.regionTimeline],
             summary: "Optionally follows external, frame-exact regions whose ids equal Script Roles, placing a Cue at its measured speaker region's top center and hiding it on null Frames." },
         ],
+        children: [{ tag: "Use", cardinality: "many", summary: "Presents complete Cues inside a time window. Later matching Uses replace earlier ones.", attributes: [
+          { name: "id", kind: "identifier", required: false, summary: "Optional occurrence identity." },
+          { name: "style", kind: "reference", required: true, accepts: [captionTypes.style], summary: "Complete Caption Style, including Hidden." },
+          { name: "role", kind: "literal", required: false, summary: "Optional speaker filter, independent of the time window." },
+          ...temporalWindowAttributeVocabulary,
+        ] }],
         ports: [
           { name: "schedule", type: captionFineTypes.schedule,
             summary: "The visible Cue schedule consumed by the renderer and other declared tools." },
           { name: "track", type: compositionTypes.visualTrack,
             summary: "The rendered Caption as one self-contained VisualTrack." },
         ],
-        example: `<caption-fine:Track id="captions" document={story.caption} semantic={speech.semantic} program={caption-program}/>`,
+        example: `<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+  <caption-fine:Use style={primary-caption}/>
+  <caption-fine:Use during={story.selection.answer} style={answer-caption}/>
+</caption-fine:Track>`,
         notes: [
-          "The element is empty; it accepts no children and no text.",
-          "One Track renders the Program's default Style and every ordered replacement together.",
+          "Use without time attributes covers the whole Timeline. Role filters content without changing the window.",
+          "Script Cue breaks organize text; Use windows change presentation without cutting Cues or restarting word timing. A hidden Use still replaces earlier presentation.",
           "Without regions, Recipe x/y placement is unchanged. With regions, a measured region overrides x/y for that Frame; a null Frame on that Role track hides the Cue, while a missing Role track retains authored x/y.",
           "The tracked point replaces Recipe x/y while width and the Recipe anchor still decide the Caption box geometry; anchor-x=center and anchor-y=bottom place the box immediately above the measured region.",
         ],
@@ -339,9 +349,8 @@ export const captionFineManifest: ModuleManifest = {
     compositionDependency,
     mediaDependency,
     narrativeDependency,
-    programSpaceDependency,
-    semanticTrackDependency,
-    spatialDependency,
+    timelineDependency,
+    spatialDependency, temporalDependency,
   ],
   types: [{ name: captionFineTypes.schedule.name }],
   capabilities: [],
@@ -362,7 +371,7 @@ export const captionFineManifest: ModuleManifest = {
         { name: "schedule", type: captionFineTypes.schedule },
         { name: "program", type: captionTypes.program },
         { name: "document", type: narrativeTypes.captionDocument },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
       ],
       outputs: [{ name: "track", type: compositionTypes.visualTrack }],
       needs: [],
@@ -373,7 +382,7 @@ export const captionFineManifest: ModuleManifest = {
         { name: "schedule", type: captionFineTypes.schedule },
         { name: "program", type: captionTypes.program },
         { name: "document", type: narrativeTypes.captionDocument },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "regions", type: spatialTypes.regionTimeline },
       ],
       outputs: [{ name: "track", type: compositionTypes.visualTrack }],

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

@@ -118,3 +118,10 @@ export const fineCaptionRecipeSchema: ValueSchema = {
     required.has(name) ? { schema: schemaFor(name) } : { schema: schemaFor(name), optional: true },
   ])),
 };
+
+/** Static authored defaults; dependent paint values retain their decoder relationships. */
+export const fineCaptionEditableDefaults = {
+  opacity: 1, "stroke-width": 0, "shadow-opacity": 0, "glow-opacity": 0,
+  karaoke: "off", "karaoke-transition": "step", "active-box": "off",
+  "underline": "off", "active-underline": "off",
+} as const;

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

@@ -1,3 +1,4 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertCaptionProgramForDocument } from "@hypit/caption";
 import type { CaptionProgram } from "@hypit/caption";
 import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
@@ -14,7 +15,6 @@ import type {
 } from "@hypit/composition";
 import type { CaptionAlignmentUnit, CaptionDocument } from "@hypit/narrative";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { assertSpatialRegionTimeline } from "@hypit/spatial";
 import type { CanvasSpace, SpatialFrame, SpatialRegionTimeline } from "@hypit/spatial";
 
@@ -480,23 +480,6 @@ function karaokeWipeAnimation(
   ] };
 }
 
-function typewriterAnimation(
-  text: string,
-  parameters: FineCaptionParameters,
-  startFrame: number,
-  endFrame: number,
-  durationFrames: number,
-): VisualAnimation | undefined {
-  if (parameters.motion.atomReveal !== "typewriter") return undefined;
-  const graphemes = Math.max(1, [...new Intl.Segmenter("und", { granularity: "grapheme" }).segment(text)].length);
-  const span = Math.max(1, endFrame - startFrame);
-  const offsets = Array.from({ length: graphemes + 1 }, (_, index) => startFrame + Math.round(span * index / graphemes));
-  return animationFrom(durationFrames, [...stepOffsets(startFrame), ...offsets], (frame) => {
-    const progress = frame < startFrame ? 0 : Math.floor(clamp((frame - startFrame) / span, 0, 1) * graphemes) / graphemes;
-    return [{ name: "clip-path", value: wipeClip(progress, parameters.layout.direction) }];
-  });
-}
-
 function activeResponseAnimation(
   parameters: FineCaptionParameters,
   startFrame: number,
@@ -656,7 +639,7 @@ function structuralRowCount(
 
 /**
  * Acoustic Word windows may overlap. Preserve those measurements in the
- * SemanticTrack, but give every current-only visual state one unambiguous
+ * Timeline, but give every current-only visual state one unambiguous
  * owner: as soon as the next authored unit starts, the previous one stops.
  */
 function exclusiveActivationFrames(
@@ -867,9 +850,7 @@ function cueElements(
     // the karaoke wipe keeps sitting on the letterforms it reveals.
     const gaps = wordGaps(surfaces);
     const wordGap = uniformGap(gaps);
-    const atomText = joinSurfaces(surfaces, " ");
     const entryId = `${atomId}-entry`;
-    const typewriterId = `${atomId}-typewriter`;
     const loopId = `${atomId}-loop`;
     const responseId = `${atomId}-response`;
     if (parameters.layout.maxWordsPerLine !== undefined
@@ -884,7 +865,6 @@ function cueElements(
       wordsOnLine = 0;
     }
     const entryAnimation = atomLifecycleAnimation(parameters, timing.start, timing.end, durationFrames);
-    const writerAnimation = typewriterAnimation(atomText, parameters, timing.start, timing.end, durationFrames);
     const atomLoop = parameters.motion.loopTarget === "active-atom"
       ? loopAnimation(parameters, durationFrames, activationTiming) : undefined;
     const responseAnimation = activeResponseAnimation(
@@ -906,20 +886,9 @@ function cueElements(
       ],
       ...(entryAnimation === undefined ? {} : { animation: entryAnimation }),
     });
-    push({
-      id: typewriterId,
-      parent: entryId,
-      kind: "box",
-      style: [
-        { name: "display", value: "inline-flex" },
-        { name: "min-width", value: "0" },
-        { name: "transform-origin", value: parameters.layout.direction === "rtl" ? "right center" : "left center" },
-      ],
-      ...(writerAnimation === undefined ? {} : { animation: writerAnimation }),
-    });
     push({
       id: loopId,
-      parent: typewriterId,
+      parent: entryId,
       kind: "box",
       style: [
         { name: "display", value: "inline-flex" },
@@ -983,10 +952,53 @@ function cueElements(
         attributes: [{ name: "data-caption-active-box", value: "isolated" }],
       });
     }
+    const graphemes = parameters.motion.atomReveal === "typewriter"
+      ? surfaces.map((text) =>
+        [...new Intl.Segmenter("und", { granularity: "grapheme" }).segment(text)].map((part) => part.segment))
+      : [];
+    const graphemeCount = graphemes.reduce((sum, word) => sum + word.length, 0);
+    const pushText = (element: Omit<VisualTextElement, "order">, wordIndex: number): void => {
+      if (parameters.motion.atomReveal !== "typewriter") {
+        push(element);
+        return;
+      }
+      // Reveal complete glyphs, not fractions of a Word's width. Variable-width Latin letters,
+      // Han characters and combining sequences all retain their actual layout widths.
+      const isMargin = (name: string): boolean => name.startsWith("margin-");
+      push({
+        id: element.id,
+        ...(element.parent === undefined ? {} : { parent: element.parent }),
+        kind: "box",
+        style: [
+          { name: "display", value: "inline" },
+          { name: "min-width", value: "0" },
+          ...element.style.filter(({ name }) => isMargin(name) || name === "opacity"),
+        ],
+        ...(element.attributes === undefined ? {} : { attributes: element.attributes }),
+      });
+      const preceding = graphemes.slice(0, wordIndex).reduce((sum, word) => sum + word.length, 0);
+      const { attributes: _attributes, ...glyph } = element;
+      for (const [index, text] of (graphemes[wordIndex] ?? []).entries()) {
+        const revealFrame = timing.start + Math.floor(
+          (timing.end - timing.start) * (preceding + index) / Math.max(1, graphemeCount),
+        );
+        push({
+          ...glyph,
+          id: `${element.id}-grapheme-${index + 1}`,
+          parent: element.id,
+          text,
+          style: [
+            ...element.style.filter(({ name }) => !isMargin(name) && name !== "opacity"),
+            { name: "display", value: "inline" },
+          ],
+          animation: activationStepAnimation("trail", revealFrame, durationFrames, durationFrames),
+        });
+      }
+    };
     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({
+      pushText({
         id: `${atomId}-base-${wordIndex + 1}`,
         parent: atomId,
         kind: "text",
@@ -997,7 +1009,7 @@ function cueElements(
         ],
         ...glyphPaintFields(parameters.basePaint),
         fonts,
-      });
+      }, wordIndex);
     }
     const addActivatedTextLayer = (
       suffix: string,
@@ -1026,7 +1038,7 @@ function cueElements(
       });
       for (const [wordIndex, wordId] of atom.wordIds.entries()) {
         const text = wordText.get(wordId)!;
-        push({
+        pushText({
           id: `${activeId}-${wordIndex + 1}`,
           parent: activeId,
           kind: "text",
@@ -1041,7 +1053,7 @@ function cueElements(
           ...(kind === "glyph" ? glyphPaintFields(parameters.activePaint) : {}),
           fonts,
           attributes: [{ name: kind === "glyph" ? "data-caption-active-word" : "data-caption-underlined-word", value: wordId }],
-        });
+        }, wordIndex);
       }
     };
     if (parameters.karaoke.mode !== "off") addActivatedTextLayer("active", parameters.karaoke.mode, "glyph");
@@ -1057,33 +1069,32 @@ export function renderFineCaption(
   schedule: FineCaptionSchedule,
   program: CaptionProgram,
   document: CaptionDocument,
-  space: ProgramSpace,
+  timeline: Timeline,
   regions?: SpatialRegionTimeline,
 ): VisualTrack {
   assertFineCaptionSchedule(schedule);
   assertCaptionProgramForDocument(program, document);
   if (schedule.documentId !== document.id) throw new Error("Fine Caption received another CaptionDocument");
-  if (program.wordRuns.length !== 0) {
-    throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");
-  }
-  assertProgramSpaceIdentity(space);
-  if (schedule.spaceId !== space.id || schedule.narrativeId !== document.narrativeId) {
-    throw new Error("Fine Caption inputs belong to different ProgramSpaces or Narratives");
+
+  assertProgramSpaceIdentity(timeline);
+  if (schedule.spaceId !== timeline.id || schedule.narrativeId !== document.narrativeId) {
+    throw new Error("Fine Caption inputs belong to different Timelines or Narratives");
   }
   const styles = new Map(program.styles.map((style) => [style.id, style]));
   const wordText = new Map(document.words.map((word) => [word.id, word.text]));
   const atomById = new Map(document.units.map((atom) => [atom.id, atom]));
   for (const style of styles.values()) {
+    if (style.rendering === null) continue;
     if (style.rendering.family !== FINE_CAPTION_FAMILY) {
       throw new Error(`Fine Caption cannot render Style family ${style.rendering.family}`);
     }
     assertFineCaptionParameters(style.rendering.parameters as unknown as FineCaptionParameters);
   }
-  const totalFrames = programSpaceFrameCount(space);
+  const totalFrames = programSpaceFrameCount(timeline);
   const regionTracks = regions === undefined ? undefined : (() => {
     assertSpatialRegionTimeline(regions);
     if (regions.frameCount !== totalFrames) {
-      throw new Error(`Fine Caption regions cover ${regions.frameCount} Frames but ProgramSpace has ${totalFrames}`);
+      throw new Error(`Fine Caption regions cover ${regions.frameCount} Frames but Timeline has ${totalFrames}`);
     }
     return new Map(regions.tracks.map((track) => [track.id, track]));
   })();
@@ -1093,6 +1104,7 @@ export function renderFineCaption(
     const resolvedAtoms = atoms.map((atom) => atom!);
     const style = styles.get(cue.styleId);
     if (style === undefined) throw new Error(`Fine Caption Cue ${cue.id} references unknown Style ${cue.styleId}`);
+    if (style.rendering === null) return [];
     const parameters = style.rendering.parameters as unknown as FineCaptionParameters;
     const startFrame = Math.max(0, cue.visibleStartFrame);
     const measuredEnd = Math.min(totalFrames, cue.visibleEndFrameExclusive);
@@ -1118,16 +1130,17 @@ export function renderFineCaption(
     return [{
       id: cue.id,
       span: { startFrame, endFrameExclusive },
+      visibility: cue.visibility,
       stacking: { order: parameters.stackingOrder, tieBreak: `${program.id}:${cue.id}` },
       elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId, trackedPlacement),
     }];
   });
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: program.id,
     presents,
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }

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

@@ -1,4 +1,4 @@
-import { applyCaptionMute, assertCaptionProgramForDocument, assertTimedCaptionProjection } from "@hypit/caption";
+import { assertCaptionProgramForDocument, assertTimedCaptionProjection, captionUseVisibility } from "@hypit/caption";
 import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
 import type { CaptionDocument } from "@hypit/narrative";
 
@@ -27,13 +27,11 @@ export function scheduleFineCaption(
   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>();
+  const activeStyles = new Set(program.uses.map(use => use.styleId));
   for (const style of program.styles) {
+    if (!activeStyles.has(style.id)) continue;
+    if (style.rendering === null) continue;
     if (style.rendering.family !== FINE_CAPTION_FAMILY) {
       throw new Error(`Fine Caption cannot schedule Style family ${style.rendering.family}`);
     }
@@ -42,39 +40,41 @@ export function scheduleFineCaption(
     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 units = new Map(document.units.map(unit => [unit.id, unit]));
   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 };
+  for (const [index, use] of program.uses.entries()) {
+    if (use.window.start.source.spaceId !== projection.spaceId) throw new Error("Caption Use belongs to another Timeline");
+    const style = parameters.get(use.styleId);
+    if (style === undefined) continue; // Hidden still participates in coverage below.
+    const desired = projection.cues.filter(cue => use.role === undefined || units.get(cue.units[0]!.unitId)?.role === use.role).map((cue): FineCaptionScheduledCue => ({
+      id: `${use.window.subjectId}:${cue.id}`, cueId: cue.id, styleId: use.styleId,
+      semanticStartFrame: cue.startFrame, semanticEndFrameExclusive: cue.endFrameExclusive,
+      visibleStartFrame: Math.max(0, cue.startFrame - style.timing.leadFrames),
+      visibleEndFrameExclusive: cue.endFrameExclusive + style.timing.tailFrames,
+      units: cue.units, visibility: [],
+    }));
+    // Resolve each speaker's ordinary Cue handoff before masking by Use windows.
+    desired.sort((a, b) => a.semanticStartFrame - b.semanticStartFrame);
+    const previousByRole = new Map<string | undefined, number>();
+    const envelopes: FineCaptionScheduledCue[] = [];
+    for (const wanted of desired) {
+      let cue = wanted;
+      const role = units.get(cue.units[0]!.unitId)?.role;
+      const previousIndex = previousByRole.get(role);
+      const previous = previousIndex === undefined ? undefined : envelopes[previousIndex];
+      if (previous !== undefined && style.timing.handoff === "cut" && previous.semanticEndFrameExclusive <= cue.semanticStartFrame) {
+        const previousEnd = Math.max(previous.semanticEndFrameExclusive, Math.min(previous.visibleEndFrameExclusive, cue.semanticStartFrame));
+        envelopes[previousIndex!] = { ...previous, visibleEndFrameExclusive: previousEnd };
         cue = { ...cue, visibleStartFrame: Math.min(cue.semanticStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
       }
+      previousByRole.set(role, envelopes.length);
+      envelopes.push(cue);
+    }
+    for (const cue of envelopes) {
+      const role = units.get(cue.units[0]!.unitId)?.role;
+      const visibility = captionUseVisibility(program, index, role, { startFrame: cue.visibleStartFrame, endFrameExclusive: cue.visibleEndFrameExclusive });
+      if (visibility.length) cues.push({ ...cue, visibility });
     }
-    cues.push(cue);
   }
 
   const ids = new Set<string>();
@@ -110,6 +110,10 @@ export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {
       throw new Error("Fine Caption Schedule contains an invalid Cue");
     }
     ids.add(cue.id);
+    if (!cue.cueId || cue.visibility.length === 0 || cue.visibility.some(span =>
+      !Number.isSafeInteger(span.startFrame) || !Number.isSafeInteger(span.endFrameExclusive)
+      || span.startFrame < cue.visibleStartFrame || span.endFrameExclusive > cue.visibleEndFrameExclusive
+      || span.endFrameExclusive <= span.startFrame)) throw new Error("Fine Caption visibility is invalid");
     for (const [label, frame] of [
       ["semantic start", cue.semanticStartFrame],
       ["semantic end", cue.semanticEndFrameExclusive],

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

@@ -8,6 +8,7 @@ import type { SvsRecipe } from "@hypit/svs";
 import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";
 import {
   fineCaptionOneShotMotions,
+  fineCaptionEditableDefaults,
   fineCaptionOptionalRecipeProperties,
   fineCaptionRequiredRecipeProperties,
 } from "./recipe.js";
@@ -104,14 +105,14 @@ function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptio
   return {
     fill: color(recipe, `${prefix}fill`, prefix === "active-" ? "#FFD54A" : base?.fill),
     ...(gradient === undefined ? {} : { gradient }),
-    opacity: number(recipe, `${prefix}opacity`, base?.opacity ?? 1),
+    opacity: number(recipe, `${prefix}opacity`, base?.opacity ?? fineCaptionEditableDefaults.opacity),
     stroke: {
       color: color(recipe, `${prefix}stroke-color`, baseStroke?.color ?? "#000000"),
-      widthPx: number(recipe, `${prefix}stroke-width`, baseStroke?.widthPx ?? 0),
+      widthPx: number(recipe, `${prefix}stroke-width`, baseStroke?.widthPx ?? fineCaptionEditableDefaults["stroke-width"]),
     },
     shadow: {
       color: color(recipe, `${prefix}shadow-color`, baseShadow?.color ?? "#000000"),
-      opacity: number(recipe, `${prefix}shadow-opacity`, baseShadow?.opacity ?? 0),
+      opacity: number(recipe, `${prefix}shadow-opacity`, baseShadow?.opacity ?? fineCaptionEditableDefaults["shadow-opacity"]),
       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),
@@ -125,7 +126,7 @@ function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptio
     },
     glow: {
       color: color(recipe, `${prefix}glow-color`, baseGlow?.color ?? "#FFFFFF"),
-      opacity: number(recipe, `${prefix}glow-opacity`, baseGlow?.opacity ?? 0),
+      opacity: number(recipe, `${prefix}glow-opacity`, baseGlow?.opacity ?? fineCaptionEditableDefaults["glow-opacity"]),
       blurPx: number(recipe, `${prefix}glow-blur`, baseGlow?.blurPx ?? 0),
       spreadPx: number(recipe, `${prefix}glow-spread`, baseGlow?.spreadPx ?? 0),
     },
@@ -216,13 +217,13 @@ export function fineCaptionParameters(
     basePaint,
     activePaint: glyphPaint(recipe, "active-", basePaint),
     underline: {
-      mode: choice(recipe, "underline", ["off", "always"] as const, "off"),
+      mode: choice(recipe, "underline", ["off", "always"] as const, fineCaptionEditableDefaults["underline"]),
       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"),
+      mode: choice(recipe, "active-underline", ["off", "current", "trail"] as const, fineCaptionEditableDefaults["active-underline"]),
       color: color(recipe, "active-underline-color", "#FFD54A"),
       thicknessPx: number(recipe, "active-underline-thickness", 3),
       offsetPx: number(recipe, "active-underline-offset", 4),
@@ -244,11 +245,11 @@ export function fineCaptionParameters(
       },
     },
     karaoke: {
-      mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, "off"),
-      transition: choice(recipe, "karaoke-transition", ["step", "wipe"] as const, "step"),
+      mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, fineCaptionEditableDefaults["karaoke"]),
+      transition: choice(recipe, "karaoke-transition", ["step", "wipe"] as const, fineCaptionEditableDefaults["karaoke-transition"]),
     },
     activeBox: {
-      mode: choice(recipe, "active-box", ["off", "current", "trail"] as const, "off"),
+      mode: choice(recipe, "active-box", ["off", "current", "trail"] as const, fineCaptionEditableDefaults["active-box"]),
       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"),