@hypit/hypit 0.1.4 → 0.1.6

package/packages/caption/src/style.ts

@@ -1,20 +1,10 @@
-import type { CaptionDocument, Narrative } from "@hypit/narrative";
+import type { CaptionDocument } from "@hypit/narrative";
 import { canonicalStringify, canonicalize } from "@hypit/protocol";
 
-import {
-  assertCaptionDocument,
-  captionUnitsForRole,
-  type CaptionUnitSubset,
-} from "./display.js";
-import type {
-  CaptionMuteApplication,
-  CaptionProgram,
-  CaptionStyleApplication,
-  CaptionStyleIntent,
-  CaptionWordStyleApplication,
-} from "./types.js";
-
-export type { CaptionMuteApplication, CaptionStyleApplication, CaptionWordStyleApplication } from "./types.js";
+import { assertCaptionDocument } from "./display.js";
+import { assertTemporalWindowFor } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
+import type { CaptionProgram, CaptionStyleIntent } from "./types.js";
 
 const ID = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/u;
 function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
@@ -22,7 +12,8 @@ function assert(condition: unknown, message: string): asserts condition { if (!c
 export function sealCaptionStyle(value: CaptionStyleIntent): CaptionStyleIntent {
   const result = canonicalize({
     id: value.id,
-    rendering: { family: value.rendering.family.trim(), parameters: canonicalize(value.rendering.parameters) },
+    rendering: value.rendering === null ? null
+      : { family: value.rendering.family.trim(), parameters: canonicalize(value.rendering.parameters) },
   }) as unknown as CaptionStyleIntent;
   assertCaptionStyle(result);
   return result;
@@ -30,6 +21,7 @@ export function sealCaptionStyle(value: CaptionStyleIntent): CaptionStyleIntent
 
 export function assertCaptionStyle(value: CaptionStyleIntent): void {
   assert(ID.test(value.id), "Caption Style identity is invalid");
+  if (value.rendering === null) return;
   assert(value.rendering.family.trim().length > 0, `Caption Style ${value.id} rendering family is empty`);
   canonicalize(value.rendering.parameters);
 }
@@ -41,130 +33,27 @@ export function sealCaptionProgram(value: CaptionProgram): CaptionProgram {
 }
 
 export function assertCaptionProgram(value: CaptionProgram): void {
-  assert(ID.test(value.id), "Caption Program identity is invalid");
-  assert(value.documentId.length > 0 && value.styles.length > 0 && value.runs.length > 0,
-    "Caption Program is empty");
-  const styles = new Map(value.styles.map((style) => [style.id, style]));
-  assert(styles.size === value.styles.length, "Caption Program styles are repeated");
+  assert(ID.test(value.id) && value.documentId.length > 0, "Caption Track identity is invalid");
+  const styles = new Map(value.styles.map(style => [style.id, style]));
+  assert(styles.size === value.styles.length, "Caption Styles are repeated");
   value.styles.forEach(assertCaptionStyle);
-  assert(new Set(value.runs.map((run) => run.id)).size === value.runs.length,
-    "Caption Program run ids are repeated");
-  const units = value.runs.flatMap((run) => run.unitIds);
-  assert(new Set(units).size === units.length, "Caption Program runs repeat a unit");
-  assert(value.runs.every((run) => styles.has(run.styleId) && run.unitIds.length > 0),
-    "Caption Program run is invalid");
-  assert(new Set(value.wordRuns.map((run) => run.id)).size === value.wordRuns.length,
-    "Caption Program word run ids are repeated");
-  const words = value.wordRuns.flatMap((run) => run.wordIds);
-  assert(new Set(words).size === words.length, "Caption Program word runs repeat a word");
-  assert(value.wordRuns.every((run) => styles.has(run.styleId) && run.wordIds.length > 0),
-    "Caption Program word run is invalid");
-  assert(new Set(value.mutedUnitIds).size === value.mutedUnitIds.length,
-    "Caption Program muted units are repeated");
+  assert(new Set(value.uses.map(use => use.window.subjectId)).size === value.uses.length, "Caption Use ids are repeated");
+  for (const use of value.uses) {
+    assertTemporalWindowFor(use.window, { subjectId: use.window.subjectId });
+    assert(styles.has(use.styleId), "Caption Use references an unknown Style");
+    assert(use.role === undefined || use.role.trim().length > 0, "Caption Role is empty");
+  }
 }
-
 export function assertCaptionProgramForDocument(value: CaptionProgram, document: CaptionDocument): void {
   assertCaptionProgram(value);
   assertCaptionDocument(document);
-  assert(value.documentId === document.id, "Caption Program belongs to another CaptionDocument");
-  const expected = document.units.map((unit) => unit.id);
-  assert(value.runs.flatMap((run) => run.unitIds).join("\0") === expected.join("\0"),
-    "Caption Program must partition every Caption unit exactly once and in order");
-  const known = new Set(expected);
-  assert(value.mutedUnitIds.every((id) => known.has(id)), "Caption Program mutes an unknown unit");
-  const knownWords = new Set(document.words.map((word) => word.id));
-  assert(value.wordRuns.every((run) => run.wordIds.every((id) => knownWords.has(id))),
-    "Caption Program styles an unknown display word");
+  assert(value.documentId === document.id, "Caption Uses belong to another CaptionDocument");
 }
-
-function orderedSubset(value: CaptionUnitSubset, document: CaptionDocument): string[] {
-  assertCaptionDocument(document);
-  assert(value.documentId === document.id, "Caption unit subset belongs to another document");
-  const order = new Map(document.units.map((unit, index) => [unit.id, index]));
-  const indices = value.unitIds.map((id) => order.get(id));
-  assert(indices.length > 0 && indices.every((index) => index !== undefined),
-    "Caption unit subset contains an unknown unit");
-  assert(indices.every((index, position) => position === 0 || index! > indices[position - 1]!),
-    "Caption unit subset must be ordered and contain no repeated unit");
-  return [...value.unitIds];
-}
-
-export function resolveCaptionProgram(
-  document: CaptionDocument,
-  narrative: Narrative,
-  id: string,
-  defaultStyle: CaptionStyleIntent,
-  applications: readonly CaptionStyleApplication[],
-  mutes: readonly CaptionMuteApplication[] = [],
-  wordApplications: readonly CaptionWordStyleApplication[] = [],
-): CaptionProgram {
-  assertCaptionDocument(document);
-  assertCaptionStyle(defaultStyle);
-  const styles = new Map<string, CaptionStyleIntent>([[defaultStyle.id, defaultStyle]]);
-  const selected = applications.map((application) => {
-    assert(ID.test(application.id), "Caption Style Application identity is invalid");
-    assertCaptionStyle(application.style);
-    const unitIds = orderedSubset({ documentId: document.id, unitIds: application.unitIds }, document);
-    const previous = styles.get(application.style.id);
-    assert(previous === undefined || canonicalStringify(previous) === canonicalStringify(application.style),
-      `Caption Style ${application.style.id} has conflicting definitions`);
-    styles.set(application.style.id, application.style);
-    return { ...application, unitIds };
-  });
-  const muted = mutes.flatMap((application) => {
-    assert(ID.test(application.id), "Caption Mute identity is invalid");
-    return orderedSubset({ documentId: document.id, unitIds: application.unitIds }, document);
+export function appendCaptionUse(program: CaptionProgram, window: TemporalWindow, style: CaptionStyleIntent, role?: string): CaptionProgram {
+  const previous = program.styles.find(item => item.id === style.id);
+  assert(previous === undefined || canonicalStringify(previous) === canonicalStringify(style), `Caption Style ${style.id} has conflicting definitions`);
+  return sealCaptionProgram({ ...program,
+    styles: previous === undefined ? [...program.styles, style] : program.styles,
+    uses: [...program.uses, { window, styleId: style.id, ...(role === undefined ? {} : { role }) }],
   });
-  const wordChosen = new Map<string, string>();
-  for (const application of wordApplications) {
-    assert(ID.test(application.id), "Caption Word Style Application identity is invalid");
-    assert(application.attribute.trim().length > 0, "Caption Word Style Application attribute is empty");
-    assertCaptionStyle(application.style);
-    const knownWordIds = new Set(document.words.map((word) => word.id));
-    for (const wordId of application.wordIds) {
-      assert(knownWordIds.has(wordId), `Caption Word Style Application references unknown word ${wordId}`);
-      const previous = wordChosen.get(wordId);
-      assert(previous === undefined || previous === application.style.id,
-        `Caption word ${wordId} receives conflicting styles`);
-      wordChosen.set(wordId, application.style.id);
-    }
-    const previous = styles.get(application.style.id);
-    assert(previous === undefined || canonicalStringify(previous) === canonicalStringify(application.style),
-      `Caption Style ${application.style.id} has conflicting definitions`);
-    styles.set(application.style.id, application.style);
-  }
-  const chosen = new Map(document.units.map((unit) => [unit.id, defaultStyle.id]));
-  for (const application of selected) for (const unitId of application.unitIds) chosen.set(unitId, application.style.id);
-  const runs: CaptionProgram["runs"][number][] = [];
-  for (const unit of document.units) {
-    const styleId = chosen.get(unit.id)!;
-    const previous = runs.at(-1);
-    if (previous === undefined || previous.styleId !== styleId) {
-      runs.push({ id: `${id}:run:${runs.length + 1}`, styleId, unitIds: [unit.id] });
-    } else {
-      runs[runs.length - 1] = { ...previous, unitIds: [...previous.unitIds, unit.id] };
-    }
-  }
-  const wordRuns: CaptionProgram["wordRuns"][number][] = [];
-  for (const [wordId, styleId] of wordChosen) {
-    const previous = wordRuns.at(-1);
-    if (previous === undefined || previous.styleId !== styleId) {
-      wordRuns.push({ id: `${id}:word-run:${wordRuns.length + 1}`, styleId, wordIds: [wordId] });
-    } else {
-      wordRuns[wordRuns.length - 1] = { ...previous, wordIds: [...previous.wordIds, wordId] };
-    }
-  }
-  const program = sealCaptionProgram({
-    id,
-    documentId: document.id,
-    styles: [...styles.values()].filter((style) => [...chosen.values(), ...wordChosen.values()].includes(style.id)),
-    runs,
-    wordRuns,
-    mutedUnitIds: [...new Set(muted)],
-  });
-  assertCaptionProgramForDocument(program, document);
-  void narrative;
-  return program;
 }
-
-export { captionUnitsForRole };

package/packages/caption/src/surface.ts

@@ -1,96 +1,16 @@
-import { narrativeTypes } from "@hypit/narrative";
-import type { CaptionDocument, Narrative, NarrativeSelection } from "@hypit/narrative";
-import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
-
+import type { StructuredSurfaceHandler } from "@hypit/markup";
+import { assertAttributes, assertEmptyElement, textAttribute } from "@hypit/markup";
 import { captionTypes } from "./manifest.js";
-import { captionUnitsForRole, captionUnitsForSelection, captionWordsForAttribute } from "./display.js";
-import { resolveCaptionProgram } from "./style.js";
-import type { CaptionMuteApplication, CaptionStyleApplication, CaptionStyleIntent, CaptionWordStyleApplication } from "./types.js";
-
-function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
-  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
-}
-function attributes(element: StructuredElement, required: readonly string[], optional: readonly string[] = []): void {
-  const allowed = new Set([...required, ...optional]);
-  const actual = Object.keys(element.attributes);
-  if (required.some((name) => element.attributes[name] === undefined) || actual.some((name) => !allowed.has(name))) {
-    throw new Error(`${element.name} requires ${required.join(", ")}${optional.length ? `; optional: ${optional.join(", ")}` : ""}`);
-  }
-}
-function stringAttribute(element: StructuredElement, name: string): string {
-  const value = element.attributes[name];
-  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be a non-empty string`);
-  return value.trim();
-}
-function optionalString(element: StructuredElement, name: string): string | undefined {
-  const value = element.attributes[name];
-  if (value === undefined) return undefined;
-  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be a non-empty string`);
-  return value.trim();
-}
-function reference(
-  element: StructuredElement,
-  name: string,
-  expected: SurfaceResolvedReference["type"],
-  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
-): SurfaceResolvedReference {
-  const raw: MarkupAttributeValue | undefined = element.attributes[name];
-  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a whole-value reference`);
-  const value = resolveReference(raw.path);
-  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}`);
-  if (!sameType(value.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);
-  return value;
-}
-function inline<T>(referenceValue: SurfaceResolvedReference, subject: string): T {
-  if (referenceValue.record?.value.kind !== "inline") throw new Error(`${subject} must reference an authored inline Record`);
-  return referenceValue.record.value.value as unknown as T;
-}
-function localName(name: string): string { const index = name.lastIndexOf(":"); return index < 0 ? name : name.slice(index + 1); }
+import { sealCaptionStyle } from "./style.js";
 
-export const decodeCaptionProgramSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  attributes(element, ["id", "document", "narrative", "default"]);
-  const id = stringAttribute(element, "id");
-  const document = inline<CaptionDocument>(reference(element, "document", narrativeTypes.captionDocument, resolveReference), `${element.name}.document`);
-  const narrative = inline<Narrative>(reference(element, "narrative", narrativeTypes.narrative, resolveReference), `${element.name}.narrative`);
-  const defaultStyle = inline<CaptionStyleIntent>(reference(element, "default", captionTypes.style, resolveReference), `${element.name}.default`);
-  const applications: CaptionStyleApplication[] = [];
-  const wordApplications: CaptionWordStyleApplication[] = [];
-  const mutes: CaptionMuteApplication[] = [];
-  for (const child of element.children) {
-    if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts only Use or Mute children`); continue; }
-    const childName = localName(child.name);
-    if (childName !== "Use" && childName !== "Mute") throw new Error(`${element.name} accepts only Use or Mute children`);
-    attributes(child, childName === "Use" ? ["style"] : [], ["role", "selection", "attribute"]);
-    const role = optionalString(child, "role");
-    const attribute = optionalString(child, "attribute");
-    const selectionRaw = child.attributes.selection;
-    const selectors = [role !== undefined, selectionRaw !== undefined, attribute !== undefined].filter(Boolean).length;
-    if (selectors !== 1) throw new Error(`${child.name} requires exactly one of role, selection or attribute`);
-    if (childName === "Mute" && attribute !== undefined) throw new Error(`${child.name} cannot mute a token attribute`);
-    if (attribute !== undefined) {
-      const wordIds = captionWordsForAttribute(document, attribute);
-      wordApplications.push({
-        id: `${id}.word-use.${wordApplications.length + 1}`,
-        attribute,
-        wordIds,
-        style: inline<CaptionStyleIntent>(reference(child, "style", captionTypes.style, resolveReference), `${child.name}.style`),
-      });
-      continue;
-    }
-    const unitIds = role !== undefined
-      ? captionUnitsForRole(document, role).unitIds
-      : captionUnitsForSelection(
-          document,
-          narrative,
-          inline<NarrativeSelection>(reference(child, "selection", narrativeTypes.selection, resolveReference), `${child.name}.selection`),
-        ).unitIds;
-    if (childName === "Mute") mutes.push({ id: `${id}.mute.${mutes.length + 1}`, unitIds });
-    else applications.push({
-      id: `${id}.use.${applications.length + 1}`,
-      unitIds,
-      style: inline<CaptionStyleIntent>(reference(child, "style", captionTypes.style, resolveReference), `${child.name}.style`),
-    });
+export const decodeHiddenCaptionStyleSurface: StructuredSurfaceHandler = ({ element }) => {
+  assertAttributes(element, ["id"]);
+  assertEmptyElement(element);
+  const id = textAttribute(element, "id");
+  if (element.children.some(child => child.kind !== "text" || child.value.trim())) {
+    throw new Error(`${element.name} accepts no children`);
   }
-  const program = resolveCaptionProgram(document, narrative, id, defaultStyle, applications, mutes, wordApplications);
-  return { records: [{ id, type: captionTypes.program, value: { kind: "inline", value: program }, range: element.range }], components: [], fragments: [] };
+  return { records: [{ id, type: captionTypes.style,
+    value: { kind: "inline", value: sealCaptionStyle({ id, rendering: null }) }, range: element.range }],
+    components: [], fragments: [] };
 };

package/packages/caption/src/temporalize.ts

@@ -1,64 +1,55 @@
 import type { CaptionDocument } from "@hypit/narrative";
-import { projectSemanticProgramSpace, tokenFrameSpan } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import { projectTimelineSpace, tokenFrameSpan } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 
 import { CaptionTimingError } from "./error.js";
 import { assertCaptionDocument } from "./display.js";
-import { assertCaptionProgramForDocument } from "./style.js";
-import type { CaptionProgram, TimedCaptionProjection, TimedCaptionCue, TimedCaptionUnit } from "./types.js";
+import type { TimedCaptionProjection, TimedCaptionCue, TimedCaptionUnit } from "./types.js";
 
 export function temporalizeCaptionDocument(
   document: CaptionDocument,
-  semantic: SemanticTrack,
-  program: CaptionProgram,
+  semantic: Timeline,
 ): TimedCaptionProjection {
   assertCaptionDocument(document);
-  assertCaptionProgramForDocument(program, document);
-  const space = projectSemanticProgramSpace(semantic);
-  if (document.narrativeId !== semantic.narrativeId) {
-    throw new CaptionTimingError("CAPTION_NARRATIVE", "CaptionDocument and SemanticTrack belong to different Narratives.");
+  const space = projectTimelineSpace(semantic);
+  if (semantic.narrativeId !== undefined && document.narrativeId !== semantic.narrativeId) {
+    throw new CaptionTimingError("CAPTION_NARRATIVE", "CaptionDocument and Timeline belong to different Narratives.");
   }
-  const styleByUnit = new Map(program.runs.flatMap((run) => run.unitIds.map((unitId) => [unitId, run.styleId] as const)));
-  const muted = new Set(program.mutedUnitIds);
   const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));
-  const timed: Array<{ unit: CaptionDocument["units"][number]; styleId: string; timing: TimedCaptionUnit }> = [];
+  const timed: Array<{ unit: CaptionDocument["units"][number]; timing: TimedCaptionUnit }> = [];
   for (const unit of document.units) {
-    if (muted.has(unit.id)) continue;
-    const styleId = styleByUnit.get(unit.id);
-    if (styleId === undefined) throw new CaptionTimingError("CAPTION_UNIT", `Caption unit ${unit.id} has no Style.`);
     const window = tokenFrameSpan(semantic, unit.sourceTokenIds);
-    if (window === undefined) throw new CaptionTimingError("CAPTION_SPEECH_COVERAGE", `Caption unit ${unit.id} is absent from the SemanticTrack.`);
+    if (window === undefined) continue;
     if (window.endFrameExclusive < window.startFrame) {
       throw new CaptionTimingError("CAPTION_SPEECH_ORDER", `Caption unit ${unit.id} references speech Tokens in reverse order.`);
     }
     const startFrame = window.startFrame;
     const endFrameExclusive = Math.max(startFrame + 1, window.endFrameExclusive);
-    timed.push({ unit, styleId, timing: { unitId: unit.id, startFrame, endFrameExclusive } });
+    timed.push({ unit, timing: { unitId: unit.id, startFrame, endFrameExclusive } });
   }
   const cues: TimedCaptionCue[] = [];
-  let current: { styleId: string; units: TimedCaptionUnit[]; segmentId: string; turnId: string } | undefined;
+  let current: { units: TimedCaptionUnit[]; segmentId: string; turnId: string } | undefined;
   const flush = (): void => {
     if (current === undefined || current.units.length === 0) return;
     cues.push({
-      id: `${program.id}:cue:${cues.length + 1}`,
-      styleId: current.styleId,
+      id: `${document.id}:cue:${cues.length + 1}`,
       startFrame: current.units[0]!.startFrame,
       endFrameExclusive: current.units.at(-1)!.endFrameExclusive,
       units: current.units,
     });
     current = undefined;
   };
+  const documentOrder = new Map(document.units.map((unit, index) => [unit.id, index]));
   for (const [index, entry] of timed.entries()) {
     const previousDocumentUnit = index === 0 ? undefined : timed[index - 1]!.unit;
     const mustBreak = current !== undefined && (
-      current.styleId !== entry.styleId
-      || current.segmentId !== entry.unit.segmentId
+      current.segmentId !== entry.unit.segmentId
       || current.turnId !== entry.unit.turnId
-      || (previousDocumentUnit !== undefined && breaks.has(previousDocumentUnit.id))
+      || (previousDocumentUnit !== undefined && (breaks.has(previousDocumentUnit.id)
+        || documentOrder.get(entry.unit.id)! !== documentOrder.get(previousDocumentUnit.id)! + 1))
     );
     if (mustBreak) flush();
     if (current === undefined) current = {
-      styleId: entry.styleId,
       units: [],
       segmentId: entry.unit.segmentId,
       turnId: entry.unit.turnId,
@@ -68,7 +59,7 @@ export function temporalizeCaptionDocument(
   flush();
   const result: TimedCaptionProjection = {
     spaceId: space.id,
-    narrativeId: semantic.narrativeId,
+    narrativeId: document.narrativeId,
     documentId: document.id,
     cues,
   };
@@ -76,32 +67,6 @@ export function temporalizeCaptionDocument(
   return result;
 }
 
-export function applyCaptionMute(
-  projection: TimedCaptionProjection,
-  program: CaptionProgram,
-  document: CaptionDocument,
-): TimedCaptionProjection {
-  assertCaptionDocument(document);
-  assertCaptionProgramForDocument(program, document);
-  if (projection.documentId !== document.id || projection.narrativeId !== document.narrativeId) {
-    throw new Error("Caption Mute received another CaptionDocument or Narrative");
-  }
-  const muted = new Set(program.mutedUnitIds);
-  const cues = projection.cues.flatMap((cue) => {
-    const units = cue.units.filter((unit) => !muted.has(unit.unitId));
-    if (units.length === 0) return [];
-    return [{ ...cue, units, startFrame: units[0]!.startFrame, endFrameExclusive: units.at(-1)!.endFrameExclusive }];
-  });
-  const result = {
-    spaceId: projection.spaceId,
-    narrativeId: projection.narrativeId,
-    documentId: projection.documentId,
-    cues,
-  };
-  assertTimedCaptionProjection(result);
-  return result;
-}
-
 export function assertTimedCaptionProjection(projection: TimedCaptionProjection): void {
   if (projection.spaceId.length === 0 || projection.narrativeId.length === 0 || projection.documentId.length === 0) {
     throw new Error("TimedCaptionProjection provenance is invalid");
@@ -109,7 +74,7 @@ export function assertTimedCaptionProjection(projection: TimedCaptionProjection)
   const cueIds = new Set<string>();
   const unitIds = new Set<string>();
   for (const cue of projection.cues) {
-    if (cue.id.length === 0 || cueIds.has(cue.id) || cue.styleId.length === 0 || cue.units.length === 0
+    if (cue.id.length === 0 || cueIds.has(cue.id) || cue.units.length === 0
       || !Number.isSafeInteger(cue.startFrame) || !Number.isSafeInteger(cue.endFrameExclusive)
       || cue.startFrame < 0 || cue.endFrameExclusive <= cue.startFrame) throw new Error("TimedCaptionProjection contains an invalid Cue");
     cueIds.add(cue.id);

package/packages/caption/src/types.ts

@@ -2,50 +2,24 @@ import type { CanonicalValue } from "@hypit/protocol";
 
 export type CaptionStyleIntent = {
   readonly id: string;
+  /** null selects no rendering; later Uses can select a visible Style again. */
   readonly rendering: {
     readonly family: string;
     readonly parameters: CanonicalValue;
-  };
+  } | null;
 };
 
-export type CaptionStyleApplication = {
-  readonly id: string;
-  readonly unitIds: readonly string[];
-  readonly style: CaptionStyleIntent;
-};
-
-export type CaptionWordStyleApplication = {
-  readonly id: string;
-  readonly attribute: string;
-  readonly wordIds: readonly string[];
-  readonly style: CaptionStyleIntent;
-};
-
-export type CaptionMuteApplication = {
-  readonly id: string;
-  readonly unitIds: readonly string[];
-};
-
-export type CaptionProgramRun = {
-  readonly id: string;
-  readonly styleId: string;
-  readonly unitIds: readonly string[];
-};
-
-export type CaptionProgramWordRun = {
-  readonly id: string;
+/** Ordered, resolved Uses owned by a Caption Track, not a separate author element. */
+export type CaptionUse = {
+  readonly window: import("@hypit/temporal").TemporalWindow;
   readonly styleId: string;
-  readonly wordIds: readonly string[];
+  readonly role?: string;
 };
-
 export type CaptionProgram = {
   readonly id: string;
   readonly documentId: string;
   readonly styles: readonly CaptionStyleIntent[];
-  readonly runs: readonly CaptionProgramRun[];
-  /** Optional local word styles resolved from Script-native word attributes. */
-  readonly wordRuns: readonly CaptionProgramWordRun[];
-  readonly mutedUnitIds: readonly string[];
+  readonly uses: readonly CaptionUse[];
 };
 
 export type TimedCaptionUnit = {
@@ -56,14 +30,13 @@ export type TimedCaptionUnit = {
 
 export type TimedCaptionCue = {
   readonly id: string;
-  readonly styleId: string;
   readonly startFrame: number;
   readonly endFrameExclusive: number;
   readonly units: readonly TimedCaptionUnit[];
 };
 
 export type TimedCaptionProjection = {
-  /** Semantic ProgramSpace from which every unit frame was measured. */
+  /** Semantic Timeline from which every unit frame was measured. */
   readonly spaceId: string;
   readonly narrativeId: string;
   readonly documentId: string;

package/packages/caption/src/visibility.ts

@@ -0,0 +1,23 @@
+type FrameSpan = { readonly startFrame: number; readonly endFrameExclusive: number };
+import type { CaptionProgram } from "./types.js";
+
+/** Later Uses replace this Cue's presentation inside their windows, including Hidden. */
+export function captionUseVisibility(program: CaptionProgram, index: number, role: string | undefined, envelope: FrameSpan): FrameSpan[] {
+  const use = program.uses[index]!;
+  if (use.role !== undefined && use.role !== role) return [];
+  const startFrame = Math.max(envelope.startFrame, use.window.span.startFrame);
+  const endFrameExclusive = Math.min(envelope.endFrameExclusive, use.window.span.endFrameExclusive);
+  let visible = endFrameExclusive > startFrame ? [{ startFrame, endFrameExclusive }] : [];
+  for (const later of program.uses.slice(index + 1)) {
+    if (later.role !== undefined && later.role !== role) continue;
+    const cut = later.window.span;
+    visible = visible.flatMap(span => {
+      if (cut.startFrame >= span.endFrameExclusive || cut.endFrameExclusive <= span.startFrame) return [span];
+      return [
+        ...(cut.startFrame > span.startFrame ? [{ startFrame: span.startFrame, endFrameExclusive: cut.startFrame }] : []),
+        ...(cut.endFrameExclusive < span.endFrameExclusive ? [{ startFrame: cut.endFrameExclusive, endFrameExclusive: span.endFrameExclusive }] : []),
+      ];
+    });
+  }
+  return visible;
+}

package/packages/caption-fine/README.md

@@ -7,9 +7,11 @@ does not carry a private visual role.
 
 ```xml
 <caption-fine:Style id="primary" recipe={recipes.caption.primary} font={caption-font}/>
-<caption:Program id="captions" document={story.caption} narrative={story} default={primary}/>
+
 <caption-fine:Track id="captions-track" document={story.caption}
-  semantic={speech.semantic} program={captions}/>
+  timeline={speech.timeline}>
+    <caption-fine:Use style={primary}/>
+  </caption-fine:Track>
 ```
 
 An optional Spatial Region Timeline replaces only the moving placement point. The timeline is authored
@@ -20,7 +22,9 @@ and a later Run can reuse the same media and alignment while changing placement:
 ```xml
 <space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
 <caption-fine:Track id="captions-track" document={story.caption}
-  semantic={speech.semantic} program={captions} regions={heads}/>
+  timeline={speech.timeline} regions={heads}>
+    <caption-fine:Use style={primary}/>
+  </caption-fine:Track>
 ```
 
 With `regions`, every Cue must carry one Script Role. When the Region Timeline contains a measured region for that
@@ -45,16 +49,17 @@ One SVS Recipe freezes three public dimensions:
 
 Caption first projects authored Script units onto semantic Word timing. Fine then produces an
 explicit visible Schedule and renders that Schedule. Lead and tail never change the semantic Word
-times used by Karaoke.
+times used by Karaoke. Later Uses mask earlier presentation, including Hidden. The final visibility
+is clipped to the winning Use Window while the original Cue envelope and animations are preserved.
 
 The Fine Schedule preserves the Caption projection's ProgramSpace, Narrative and document identities.
 The renderer rejects any mismatched Space or document. Studio may expose lead, tail and handoff as
 ordinary parameter edits, but Cue rectangles remain read-only semantic evidence.
 
-Script segments, turns, Style changes and `||` author Cue grouping. Fine rejects word-specific Style
-runs. A caption whose Cue contains structural roles or
+Script segments, turns and `||` organize complete Cues. Timed Uses select presentation without
+changing that grouping. Fine applies uniform rules to the words of a Cue. A caption whose Cue contains structural roles or
 relationships—such as an independently arranged oversized keyword and supporting phrase—can use
-a new project Caption family. Reuse the common [Caption document, Program and timing](../caption/README.md),
+a new project Caption family. Reuse the common [Caption content, timed Uses and timing](../caption/README.md),
 and implement the new schedule and rendering behavior in that package. This is ordinary component
 authorship; different colors or fonts alone can remain Fine Style choices.
 
@@ -82,6 +87,13 @@ individual Han characters as Display Words; punctuation stays with its display w
 those units for timing and active Paint, while authored Cues remain complete reading phrases.
 Dual Text retains its complete alignment unit even when it displays or speaks several words.
 
+`<组件化|>` authors the same unit as `<组件化|组件化>` without repeating the speech. Fine's `step`
+karaoke, active underline and active box treat that unit together using its first-to-last speech
+interval. Ordinary Chinese characters around it retain their own activation times. This is an
+explicit authored group, not a renderer-selected segmentation, and does not introduce a new Cue.
+The underlying character anchors remain available to other Timeline consumers. `wipe` and
+`typewriter` still animate inside the complete unit over its interval when deliberately selected.
+
 `word-gap` applies between Latin words and at Chinese/Latin boundaries. Adjacent Han characters and
 full-width punctuation carry no extra word gap. `letter-spacing` controls glyph tracking. Exact
 font fallbacks supply the required glyphs; the layout does not select a font by language.
@@ -119,5 +131,5 @@ The Hypit Skill's Caption craft page owns grouping and visual direction.
 primary face or a `<caption-fine:Fallback font={...}/>` child, just like a bundled face. See
 [Media font assets](../media/README.md#font-files) and [the open catalog](../fonts-open/README.md).
 
-The [Fine Studio Companion](../caption-fine-studio/src/index.ts) reads the same schedule and per-Cue
-Style references. It presents the actual Cue timing and exposes supported Style edits in the Inspector.
+The [Fine Studio Companion](../caption-fine-studio/src/index.ts) reads the same schedule and authored Use
+Style references. It presents the actual Cue timing and exposes Use timing and supported Style edits in the Inspector.

package/packages/caption-fine/package.json

@@ -19,10 +19,12 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
-    "@hypit/markup": "workspace:*"
+    "@hypit/markup": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*"
   },
   "devDependencies": {
     "@hypit/script": "workspace:*"

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: {},