@hypit/hypit 0.1.4 → 0.1.6

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: [
@@ -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";
 
@@ -639,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(
@@ -1069,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]));
   })();
@@ -1105,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);
@@ -1130,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"),

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

@@ -1,8 +1,8 @@
-import { captionTypes } from "@hypit/caption";
+import { captionTypes, captionProducers } from "@hypit/caption";
 import { assertFontArtifactRef, assertFontStackRef, mediaTypes } from "@hypit/media";
 import type { FontArtifactRef, FontStackRef } from "@hypit/media";
 import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 import { spatialTypes } from "@hypit/spatial";
 import { svsRecipeType } from "@hypit/svs";
 import type { SvsRecipe } from "@hypit/svs";
@@ -13,7 +13,16 @@ import type {
   MarkupAttributeValue,
 } from "@hypit/markup";
 
-import { fineCaptionRegionTrackFragment, fineCaptionTrackFragment } from "./fragment.js";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import type { SurfaceRecordDraft, SurfaceComponentDraft } from "@hypit/markup";
+import { assertEmptyElement, optionalTextAttribute } from "@hypit/markup";
+import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { temporalTypes } from "@hypit/temporal";
+import { compositionTypes } from "@hypit/composition";
+import { captionFineProducers, captionFineTypes } from "./manifest.js";
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
 import { fineCaptionStyle } from "./style.js";
 
 function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
@@ -114,39 +123,57 @@ export const decodeFineCaptionStyleSurface: StructuredSurfaceHandler = ({ elemen
 };
 
 export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  attributes(element, ["id", "document", "semantic", "program"], ["regions"]);
-  if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
-    throw new Error(`${element.name} does not accept children`);
-  }
+  attributes(element, ["id", "document", "timeline"], ["regions"]);
   const id = stringAttribute(element, "id");
   const document = reference(element, "document", narrativeTypes.captionDocument, resolveReference);
-  const semantic = reference(element, "semantic", semanticTrackTypes.track, resolveReference);
-  const program = reference(element, "program", captionTypes.program, resolveReference);
-  if (element.attributes.regions !== undefined) {
-    const regions = reference(element, "regions", spatialTypes.regionTimeline, resolveReference);
-    return {
-      records: [],
-      components: [{
-        id,
-        fragment: fineCaptionRegionTrackFragment.id,
-        inputs: { document: document.ref, semantic: semantic.ref, program: program.ref, regions: regions.ref },
-        outputs: { schedule: `${id}.schedule`, track: `${id}.track` },
-        range: element.range,
-      }],
-      fragments: [fineCaptionRegionTrackFragment],
-    };
+  const context = resolveTemporalContext({ element, resolveReference });
+  const regions = element.attributes.regions === undefined ? undefined : reference(element, "regions", spatialTypes.regionTimeline, resolveReference);
+  const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: captionTypes.header,
+    value: { kind: "inline", value: { id } }, range: element.range }];
+  const components: SurfaceComponentDraft[] = [];
+  const fragments: ReturnType<typeof sealGraphFragment>[] = [];
+  const inputs: { name: string; type: SurfaceResolvedReference["type"] }[] = [{ name: "document", type: narrativeTypes.captionDocument }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: captionTypes.header }];
+  const bindings: Record<string, SurfaceResolvedReference["ref"]> = { document: document.ref, timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
+  const operations: FragmentOperation[] = [{ id: "create", producer: captionProducers.create,
+    inputs: { document: input("document"), header: input("header") }, result: { kind: "output", name: "program" } }];
+  let previous = "create", index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim()) throw new Error("Caption Track accepts Use children."); continue; }
+    if (localName(child.name) !== "Use") throw new Error("Caption Track accepts Use children.");
+    attributes(child, ["style"], ["id", "role", ...temporalWindowAttributeNames]);
+    assertEmptyElement(child);
+    index += 1;
+    const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index}`;
+    const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
+    const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
+      element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
+    records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
+    const style = reference(child, "style", captionTypes.style, resolveReference);
+    const role = optionalTextAttribute(child, "role");
+    const filterId = `${useId}.filter`;
+    records.push({ id: filterId, type: captionTypes.filter, value: { kind: "inline", value: role === undefined ? {} : { role } }, range: child.range });
+    const key = `use-${index}`;
+    inputs.push({ name: `${key}-window`, type: temporalTypes.window }, { name: `${key}-style`, type: captionTypes.style }, { name: `${key}-filter`, type: captionTypes.filter });
+    bindings[`${key}-window`] = temporal.ref; bindings[`${key}-style`] = style.ref; bindings[`${key}-filter`] = { kind: "record", id: filterId };
+    operations.push({ id: key, producer: captionProducers.append,
+      inputs: { program: operation(previous), window: input(`${key}-window`), style: input(`${key}-style`), filter: input(`${key}-filter`) }, result: { kind: "output", name: "program" } });
+    previous = key;
   }
-  return {
-    records: [],
-    components: [{
-      id,
-      fragment: fineCaptionTrackFragment.id,
-      inputs: {
-        document: document.ref, semantic: semantic.ref, program: program.ref,
-      },
-      outputs: { schedule: `${id}.schedule`, track: `${id}.track` },
-      range: element.range,
-    }],
-    fragments: [fineCaptionTrackFragment],
-  };
+  operations.push({ id: "content", producer: captionProducers.temporalizeDocument,
+    inputs: { document: input("document"), timeline: input("timeline") }, result: { kind: "output", name: "caption" } });
+  operations.push({ id: "schedule", producer: captionFineProducers.schedule,
+    inputs: { caption: operation("content"), document: input("document"), program: operation(previous) }, result: { kind: "output", name: "schedule" } });
+  if (regions !== undefined) { inputs.push({ name: "regions", type: spatialTypes.regionTimeline }); bindings.regions = regions.ref; }
+  operations.push({ id: "render", producer: regions === undefined ? captionFineProducers.render : captionFineProducers.renderWithRegions,
+    inputs: { schedule: operation("schedule"), document: input("document"), timeline: input("timeline"), program: operation(previous), ...(regions === undefined ? {} : { regions: input("regions") }) }, result: { kind: "output", name: "track" } });
+  const collector = sealGraphFragment({ inputs, operations, exports: [
+    { name: "content", type: captionTypes.timedProjection, root: operation("content") },
+    { name: "program", type: captionTypes.program, root: operation(previous) },
+    { name: "schedule", type: captionFineTypes.schedule, root: operation("schedule") },
+    { name: "track", type: compositionTypes.visualTrack, root: operation("render") },
+  ] });
+  fragments.push(collector);
+  components.push({ id, fragment: collector.id, inputs: bindings,
+    outputs: { content: `${id}.content`, program: `${id}.program`, schedule: `${id}.schedule`, track: `${id}.track` }, range: element.range });
+  return { records, components, fragments, exports: [`${id}.content`, `${id}.program`, `${id}.schedule`, `${id}.track`] };
 };

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

@@ -173,6 +173,8 @@ export type FineCaptionParameters = {
 };
 
 export type FineCaptionScheduledCue = {
+  readonly cueId: string;
+  readonly visibility: readonly { readonly startFrame: number; readonly endFrameExclusive: number }[];
   readonly id: string;
   readonly styleId: string;
   readonly semanticStartFrame: number;

package/packages/caption-fine-studio/README.md

@@ -1,3 +1,25 @@
-# `@hypit/caption-fine-studio`
+# Caption Fine Studio Companion
 
-Hypit Studio Companion for `@hypit/caption-fine`. It projects the public Caption Schedule and owns the Inspector layout.
+One Caption Track contains Cue blocks and a bottom Uses band declared through the public ABI.
+Each Cue has a numbered title such as `#15` and complete subtitle text in its body.
+Cue ids remain the underlying identities; the number is a display label. Cues retain their measured
+times, including content currently hidden by a Use. Their read-only Range describes the content, independently of its visual treatment.
+
+The Uses band shows each authored Window once, with its Style name. A whole-Timeline Use remains one
+block across Segment changes and gaps. Hidden and overridden Uses stay selectable. The Companion
+reads the Track's `content`, `schedule` and `program` exports; it never reconstructs author windows
+from the rendered words.
+
+Use entities retain the actual child Source range and standard Temporal lineage. Timeline gestures
+therefore use the same writeback rules as Performance and Sound. Selecting a Use exposes its
+referenced Style's font and Recipe fields. Shared Styles remain shared; changing a time window
+changes presentation without editing Script Cue breaks.
+
+Studio owns Track bands, block chrome, overlap selection and generic Inspector controls. This Companion owns
+Caption facts, field grouping and Source bindings. Content, Uses and their renderer stay independent
+of central Studio domain logic.
+
+Fine Style parameters are a separate `parameters` Companion matched to the Fine Style Surface.
+The Use band opts its `style` reference into the selected object's Companion. Custom Styles can
+provide their own field table through their project package. Supported omitted defaults appear
+in the Inspector and are inserted into the owning Recipe only when edited.