@hypit/hypit 0.0.1 → 0.1.1

package/packages/caption/src/index.ts

@@ -0,0 +1,33 @@
+export { CaptionTimingError } from "./error.js";
+export {
+  assertCaptionDocument,
+  assertCaptionUnitSubset,
+  captionUnitsForRole,
+  captionUnitsForSelection,
+} from "./display.js";
+export type { CaptionUnitSubset } from "./display.js";
+export { captionWordsForAttribute } from "./display.js";
+export { captionComponent } from "./component.js";
+export { captionTimingFragment, plannedCaptionTimingFragment } from "./fragment.js";
+export {
+  captionProgramSchema,
+  captionStyleSchema,
+  timedCaptionProjectionSchema,
+  captionManifest,
+  captionMarkupSurfaces,
+  captionModuleRef,
+  captionProducers,
+  captionTypes,
+} from "./manifest.js";
+export { decodeCaptionProgramSurface } from "./surface.js";
+export {
+  assertCaptionProgram,
+  assertCaptionProgramForDocument,
+  assertCaptionStyle,
+  resolveCaptionProgram,
+  sealCaptionProgram,
+  sealCaptionStyle,
+} from "./style.js";
+export type { CaptionMuteApplication, CaptionStyleApplication, CaptionWordStyleApplication } from "./style.js";
+export { applyCaptionMute, assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
+export type * from "./types.js";

package/packages/caption/src/manifest.ts

@@ -0,0 +1,97 @@
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+
+export const captionModuleRef = { name: "@hypit/caption", version: "1" } as const;
+export const captionProducers = {
+  temporalizeDocument: { module: captionModuleRef, name: "temporalize-caption-document" },
+} satisfies Record<string, ProducerRef>;
+export const captionTypes = {
+  style: { module: captionModuleRef, name: "CaptionStyle" },
+  program: { module: captionModuleRef, name: "CaptionProgram" },
+  timedProjection: { module: captionModuleRef, name: "TimedCaptionProjection" },
+} satisfies Record<string, TypeRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+export const captionStyleSchema: ValueSchema = object({
+  id: { schema: string },
+  rendering: { schema: object({
+    family: { schema: string },
+    parameters: { schema: { kind: "object", fields: {}, allowUnknown: true } },
+  }) },
+});
+export const captionProgramSchema: ValueSchema = object({
+  id: { schema: string }, documentId: { schema: string },
+  styles: { schema: { kind: "array", minItems: 1, items: captionStyleSchema } },
+  runs: { schema: { kind: "array", minItems: 1, items: object({
+    id: { schema: string }, styleId: { schema: string }, unitIds: { schema: { kind: "array", minItems: 1, items: string } },
+  }) } },
+  wordRuns: { schema: { kind: "array", items: object({
+    id: { schema: string }, styleId: { schema: string }, wordIds: { schema: { kind: "array", minItems: 1, items: string } },
+  }) } },
+  mutedUnitIds: { schema: { kind: "array", items: string } },
+});
+const timedUnit = object({ unitId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
+export const timedCaptionProjectionSchema: ValueSchema = object({
+  spaceId: { schema: string },
+  narrativeId: { schema: string },
+  documentId: { schema: string },
+  cues: { schema: { kind: "array", items: object({
+    id: { schema: string }, styleId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer },
+    units: { schema: { kind: "array", minItems: 1, items: timedUnit } },
+  }) } },
+});
+
+export const captionMarkupSurfaces = [{
+  name: "program", tag: "Program", mode: "structured", outputs: [captionTypes.program],
+  vocabulary: {
+    summary: "Assigns rendering Styles to the Script-owned CaptionDocument using authored semantic selections.",
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Names the CaptionProgram." },
+      { name: "document", kind: "reference", required: true, accepts: [narrativeTypes.captionDocument], summary: "The complete Script-owned CaptionDocument." },
+      { name: "narrative", kind: "reference", required: true, accepts: [narrativeTypes.narrative], summary: "The semantic anchor universe used to project selections." },
+      { name: "default", kind: "reference", required: true, accepts: [captionTypes.style], summary: "The default Style." },
+    ],
+    children: [
+      { tag: "Use", cardinality: "many", summary: "Applies a complete Style by Role or semantic Selection, or supplies a word-attribute Style for a supporting family.", attributes: [
+        { name: "style", kind: "reference", required: true, accepts: [captionTypes.style], summary: "The Style to apply." },
+        { name: "role", kind: "literal", required: false, summary: "Selects all Caption units authored for this Role." },
+        { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Selects complete Caption units contained by a semantic Selection." },
+        { name: "attribute", kind: "literal", required: false, summary: "Selects display words carrying this Script-native attribute." },
+      ] },
+      { tag: "Mute", cardinality: "many", summary: "Hides selected complete Caption units.", attributes: [
+        { name: "role", kind: "literal", required: false, summary: "Selects all Caption units authored for this Role." },
+        { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Selects complete Caption units contained by a semantic Selection." },
+      ] },
+    ],
+    example: `<caption:Program id="captions" document={story.caption} narrative={story} default={plain}>
+  <caption:Use role="GUEST" style={guest}/>
+  <caption:Use selection={story.selection.answer} style={answer}/>
+  <caption:Mute selection={story.selection.demonstration}/>
+</caption:Program>`,
+    notes: [
+      "Use selects exactly one of role, selection or attribute; Mute selects exactly one of role or selection.",
+      "For Role and Selection applications, the last matching Use in Source order selects the complete Style; properties are not merged.",
+      "Selections may cover a phrase, a whole Segment, several Segments or the program, preserving complete display/pronunciation units.",
+      "All Mute selections hide their words independently of Style order. They do not mute audio; the family still controls neighboring Cue lead and tail.",
+      "Word-attribute runs are separate from Role/Selection overrides and require a family that implements them; Fine does not. Conflicting Styles on one attributed word are rejected.",
+    ],
+  },
+}] as const;
+
+export const captionManifest: ModuleManifest = {
+  format: "hypit.module@1", name: captionModuleRef.name, version: captionModuleRef.version,
+  dependencies: [narrativeDependency, semanticTrackDependency], types: [
+    { name: captionTypes.style.name }, { name: captionTypes.program.name }, { name: captionTypes.timedProjection.name },
+  ], capabilities: [], producers: [{
+    name: captionProducers.temporalizeDocument.name,
+    inputs: [
+      { name: "document", type: narrativeTypes.captionDocument },
+      { name: "semantic", type: semanticTrackTypes.track },
+      { name: "program", type: captionTypes.program },
+    ],
+    outputs: [{ name: "caption", type: captionTypes.timedProjection }], needs: [],
+  }],
+};

package/packages/caption/src/style.ts

@@ -0,0 +1,170 @@
+import type { CaptionDocument, Narrative } 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";
+
+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); }
+
+export function sealCaptionStyle(value: CaptionStyleIntent): CaptionStyleIntent {
+  const result = canonicalize({
+    id: value.id,
+    rendering: { family: value.rendering.family.trim(), parameters: canonicalize(value.rendering.parameters) },
+  }) as unknown as CaptionStyleIntent;
+  assertCaptionStyle(result);
+  return result;
+}
+
+export function assertCaptionStyle(value: CaptionStyleIntent): void {
+  assert(ID.test(value.id), "Caption Style identity is invalid");
+  assert(value.rendering.family.trim().length > 0, `Caption Style ${value.id} rendering family is empty`);
+  canonicalize(value.rendering.parameters);
+}
+
+export function sealCaptionProgram(value: CaptionProgram): CaptionProgram {
+  const result = canonicalize(value) as unknown as CaptionProgram;
+  assertCaptionProgram(result);
+  return result;
+}
+
+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");
+  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");
+}
+
+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");
+}
+
+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);
+  });
+  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

@@ -0,0 +1,96 @@
+import { narrativeTypes } from "@hypit/narrative";
+import type { CaptionDocument, Narrative, NarrativeSelection } from "@hypit/narrative";
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference, MarkupAttributeValue } 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); }
+
+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`),
+    });
+  }
+  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: [] };
+};

package/packages/caption/src/temporalize.ts

@@ -0,0 +1,124 @@
+import type { CaptionDocument } from "@hypit/narrative";
+import { projectSemanticProgramSpace, tokenFrameSpan } from "@hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/semantic-track";
+
+import { CaptionTimingError } from "./error.js";
+import { assertCaptionDocument } from "./display.js";
+import { assertCaptionProgramForDocument } from "./style.js";
+import type { CaptionProgram, TimedCaptionProjection, TimedCaptionCue, TimedCaptionUnit } from "./types.js";
+
+export function temporalizeCaptionDocument(
+  document: CaptionDocument,
+  semantic: SemanticTrack,
+  program: CaptionProgram,
+): 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 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 }> = [];
+  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.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 } });
+  }
+  const cues: TimedCaptionCue[] = [];
+  let current: { styleId: string; 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,
+      startFrame: current.units[0]!.startFrame,
+      endFrameExclusive: current.units.at(-1)!.endFrameExclusive,
+      units: current.units,
+    });
+    current = undefined;
+  };
+  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.turnId !== entry.unit.turnId
+      || (previousDocumentUnit !== undefined && breaks.has(previousDocumentUnit.id))
+    );
+    if (mustBreak) flush();
+    if (current === undefined) current = {
+      styleId: entry.styleId,
+      units: [],
+      segmentId: entry.unit.segmentId,
+      turnId: entry.unit.turnId,
+    };
+    current.units.push(entry.timing);
+  }
+  flush();
+  const result: TimedCaptionProjection = {
+    spaceId: space.id,
+    narrativeId: semantic.narrativeId,
+    documentId: document.id,
+    cues,
+  };
+  assertTimedCaptionProjection(result);
+  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");
+  }
+  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
+      || !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);
+    for (const unit of cue.units) {
+      if (unit.unitId.length === 0 || unitIds.has(unit.unitId) || !Number.isSafeInteger(unit.startFrame)
+        || !Number.isSafeInteger(unit.endFrameExclusive) || unit.startFrame < 0 || unit.endFrameExclusive <= unit.startFrame) {
+        throw new Error("TimedCaptionProjection contains an invalid or repeated unit timing");
+      }
+      unitIds.add(unit.unitId);
+    }
+  }
+}

package/packages/caption/src/types.ts

@@ -0,0 +1,71 @@
+import type { CanonicalValue } from "@hypit/protocol";
+
+export type CaptionStyleIntent = {
+  readonly id: string;
+  readonly rendering: {
+    readonly family: string;
+    readonly parameters: CanonicalValue;
+  };
+};
+
+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;
+  readonly styleId: string;
+  readonly wordIds: readonly 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[];
+};
+
+export type TimedCaptionUnit = {
+  readonly unitId: string;
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+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. */
+  readonly spaceId: string;
+  readonly narrativeId: string;
+  readonly documentId: string;
+  readonly cues: readonly TimedCaptionCue[];
+};