@hypit/hypit 0.0.1 → 0.1.1

package/packages/build-result-s3/src/repository.ts

@@ -0,0 +1,361 @@
+import type {
+  BuildResultFileRef,
+  BuildResultFileRange,
+  BuildResultFinish,
+  BuildResultManifest,
+  BuildResultPresentationUpdate,
+  BuildResultRepository,
+  BuildResultSeed,
+  BuildResultSync,
+  BuildResultWriter,
+  BuildResultWriterState,
+  RepositoryBuildResultOutput,
+  RepositoryBuildResultOutputDescription,
+} from "@hypit/build-result";
+import {
+  applyBuildResultPresentation,
+  assertBuildResultSeed,
+  decodeBuildResultJson,
+  decodeBuildResultManifest,
+  decodeBuildResultValueDocument,
+  decodeBuildResultWriterState,
+  encodeBuildResultManifest,
+  normalizeBuildResultForwards,
+  syncBuildResultOutputs,
+} from "@hypit/build-result";
+import { assertOrderedBuildId, buildIdCreatedAt } from "@hypit/protocol";
+
+import { AwsBuildResultS3Client } from "./client.js";
+import type { AwsBuildResultS3ClientOptions, BuildResultS3Client } from "./client.js";
+
+export type S3BuildResultRepositoryOptions = AwsBuildResultS3ClientOptions & {
+  readonly prefix?: string;
+  readonly client?: BuildResultS3Client;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function normalizePrefix(value: string | undefined): string {
+  if (value === undefined || value.length === 0) return "";
+  const normalized = value.replace(/^\/+|\/+$/gu, "");
+  assert(normalized.length > 0 && !normalized.split("/").some((part) => part === "." || part === ".."), "S3 Build Result prefix is invalid");
+  return normalized;
+}
+
+function physicalBuild(build: string): string {
+  assertOrderedBuildId(build);
+  const createdAt = buildIdCreatedAt(build)!;
+  const descendingTime = (Number.MAX_SAFE_INTEGER - createdAt).toString().padStart(16, "0");
+  return `${descendingTime}-${build}`;
+}
+
+function publicBuild(physical: string): string | undefined {
+  if (!/^\d{16}-bld_/u.test(physical)) return undefined;
+  const build = physical.slice(17);
+  return buildIdCreatedAt(build) === undefined || physicalBuild(build) !== physical ? undefined : build;
+}
+
+function safePath(path: string): string {
+  assert(path.length > 0 && !path.startsWith("/") && !path.includes("\\"), "Build Result path must be relative");
+  assert(!path.split("/").some((part) => part.length === 0 || part === "." || part === ".."), `Build Result path ${path} is invalid`);
+  return path;
+}
+
+function encodeJson(value: unknown): Uint8Array {
+  return new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+class S3BuildResultWriter implements BuildResultWriter {
+  readonly #repository: S3BuildResultRepository;
+  readonly #build: string;
+
+  constructor(repository: S3BuildResultRepository, build: string) {
+    this.#repository = repository;
+    this.#build = build;
+  }
+
+  async read(): Promise<BuildResultManifest> {
+    const manifest = await this.#repository.read(this.#build);
+    assert(manifest !== undefined, `Build Result ${this.#build} does not exist`);
+    return manifest;
+  }
+
+  async sync(input: BuildResultSync): Promise<BuildResultManifest> {
+    const manifest = await this.read();
+    if (manifest.outcome !== undefined) return manifest;
+    const writer = await this.#repository.readWriter(this.#build);
+    assert(writer !== undefined, `Build Result ${this.#build} has no writer state`);
+    const updated = await syncBuildResultOutputs({
+      manifest,
+      writer,
+      sync: input,
+      target: {
+        writeResource: async (path, artifact, source) => {
+          const chunks = await source.open(artifact);
+          if (chunks === undefined) throw new Error(`Build resource ${artifact.resource} is unavailable`);
+          await this.#repository.writeFile(this.#build, path, chunks, artifact.mediaType);
+        },
+        writeValue: async (path, document) => {
+          await this.#repository.writeJson(this.#build, path, document);
+        },
+      },
+    });
+    await this.#repository.writeWriter(this.#build, updated.writer);
+    await this.#repository.writeManifest(this.#build, updated.manifest);
+    return updated.manifest;
+  }
+
+  async finish(input: BuildResultFinish): Promise<BuildResultManifest> {
+    const manifest = await this.read();
+    if (manifest.outcome !== undefined) {
+      assert(manifest.outcome === input.outcome && manifest.failure === input.failure,
+        `Build Result ${manifest.id} is already finished with a different outcome`);
+      await this.#repository.deleteWriter(this.#build);
+      return manifest;
+    }
+    const now = Date.now();
+    const updated: BuildResultManifest = {
+      ...manifest,
+      outcome: input.outcome,
+      ...(input.operations === undefined ? {} : { operations: input.operations }),
+      finishedAt: manifest.finishedAt ?? now,
+      ...(input.failure === undefined ? {} : { failure: input.failure }),
+    };
+    await this.#repository.writeManifest(this.#build, updated);
+    await this.#repository.deleteWriter(this.#build);
+    return updated;
+  }
+}
+
+export class S3BuildResultRepository implements BuildResultRepository {
+  readonly #client: BuildResultS3Client;
+  readonly #prefix: string;
+
+  constructor(options: S3BuildResultRepositoryOptions) {
+    assert(options.bucket.trim().length > 0, "S3 Build Result bucket must not be empty");
+    this.#prefix = normalizePrefix(options.prefix);
+    this.#client = options.client ?? new AwsBuildResultS3Client(options);
+  }
+
+  #key(build: string, path: string): string {
+    const relative = `${physicalBuild(build)}/${safePath(path)}`;
+    return this.#prefix.length === 0 ? relative : `${this.#prefix}/${relative}`;
+  }
+
+  async #readJson(build: string, path: string): Promise<unknown | undefined> {
+    const bytes = await this.#client.get(this.#key(build, path));
+    return bytes === undefined ? undefined : decodeBuildResultJson(bytes, `${build}/${path}`);
+  }
+
+  async writeJson(build: string, path: string, value: unknown): Promise<void> {
+    await this.#client.put(this.#key(build, path), encodeJson(value), "application/json");
+  }
+
+  async writeFile(build: string, path: string, chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<void> {
+    await this.#client.putStream(this.#key(build, path), chunks, mediaType);
+  }
+
+  async writeManifest(build: string, manifest: BuildResultManifest): Promise<void> {
+    await this.writeJson(build, "result.json", encodeBuildResultManifest(manifest));
+  }
+
+  async readWriter(build: string): Promise<BuildResultWriterState | undefined> {
+    const subject = `${build}/.writer.json`;
+    const value = await this.#readJson(build, ".writer.json");
+    return value === undefined ? undefined : decodeBuildResultWriterState(value, subject);
+  }
+
+  async writeWriter(build: string, state: BuildResultWriterState): Promise<void> {
+    await this.writeJson(build, ".writer.json", state);
+  }
+
+  async deleteWriter(build: string): Promise<void> {
+    await this.#client.delete(this.#key(build, ".writer.json"));
+  }
+
+  async create(seed: BuildResultSeed): Promise<BuildResultWriter> {
+    assertOrderedBuildId(seed.id);
+    assertBuildResultSeed(seed);
+    assert((await this.read(seed.id)) === undefined, `Build Result ${seed.id} already exists`);
+    const forwards = await normalizeBuildResultForwards(this, seed.forwards ?? []);
+    const manifest: BuildResultManifest = {
+      format: "hypit.build-result@1",
+      id: seed.id,
+      ...(seed.title === undefined ? {} : { title: seed.title }),
+      source: seed.source,
+      ...(seed.run === undefined ? {} : { run: seed.run }),
+      targets: [...seed.targets],
+      outputs: {},
+    };
+    try {
+      await this.writeWriter(seed.id, {
+        resources: {},
+        values: {},
+        publishedOutputs: seed.publishedOutputs,
+        forwards,
+      });
+      await this.writeManifest(seed.id, manifest);
+    } catch (error) {
+      await this.#client.delete(this.#key(seed.id, ".writer.json")).catch(() => undefined);
+      await this.#client.delete(this.#key(seed.id, "result.json")).catch(() => undefined);
+      throw error;
+    }
+    return new S3BuildResultWriter(this, seed.id);
+  }
+
+  async openWriter(build: string): Promise<BuildResultWriter | undefined> {
+    return (await this.read(build)) === undefined ? undefined : new S3BuildResultWriter(this, build);
+  }
+
+  async removeIncomplete(build: string): Promise<void> {
+    const manifest = await this.read(build);
+    if (manifest === undefined) return;
+    assert(manifest.outcome === undefined, `Finished Build Result ${build} cannot be removed`);
+    const prefix = this.#key(build, "result.json").slice(0, -"result.json".length);
+    const keys = await this.#client.list(prefix);
+    await Promise.all(keys.filter((key) => key.startsWith(prefix)).map(async (key) => await this.#client.delete(key)));
+  }
+
+  async read(build: string): Promise<BuildResultManifest | undefined> {
+    const subject = `${build}/result.json`;
+    const value = await this.#readJson(build, "result.json");
+    return value === undefined ? undefined : decodeBuildResultManifest(value, build, subject);
+  }
+
+  async updatePresentation(
+    build: string,
+    update: BuildResultPresentationUpdate,
+  ): Promise<BuildResultManifest> {
+    const manifest = await this.read(build);
+    assert(manifest !== undefined, `Build Result ${build} does not exist`);
+    const updated = applyBuildResultPresentation(manifest, update);
+    await this.writeManifest(build, updated);
+    return updated;
+  }
+
+  async browse(request: { readonly before?: string; readonly limit: number }) {
+    assert(Number.isSafeInteger(request.limit) && request.limit > 0, "Build Result browse limit must be positive");
+    if (request.before !== undefined) assertOrderedBuildId(request.before);
+    const prefix = this.#prefix.length === 0 ? "" : `${this.#prefix}/`;
+    const found: Array<BuildResultManifest & { readonly outcome: NonNullable<BuildResultManifest["outcome"]>; readonly finishedAt: number }> = [];
+    let after = request.before === undefined ? undefined : `${prefix}${physicalBuild(request.before)}/`;
+    while (found.length <= request.limit) {
+      const page = await this.#client.list(prefix, {
+        limit: Math.min(1_000, Math.max(32, request.limit + 1)),
+        delimiter: "/",
+        ...(after === undefined ? {} : { after }),
+      });
+      if (page.length === 0) break;
+      for (const item of page) {
+        after = item;
+        if (!item.startsWith(prefix) || !item.endsWith("/")) continue;
+        const physical = item.slice(prefix.length, -1);
+        if (physical.includes("/")) continue;
+        const build = publicBuild(physical);
+        if (build === undefined) continue;
+        const manifest = await this.read(build);
+        if (manifest?.outcome === undefined || manifest.finishedAt === undefined) continue;
+        found.push(manifest as typeof found[number]);
+        if (found.length > request.limit) break;
+      }
+      if (found.length > request.limit || page.length < Math.min(1_000, Math.max(32, request.limit + 1))) break;
+    }
+    const results = found.slice(0, request.limit);
+    return {
+      results,
+      ...(found.length > request.limit && results.length > 0 ? { next: results[results.length - 1]!.id } : {}),
+    };
+  }
+
+  async describeOutput(build: string, output: string): Promise<RepositoryBuildResultOutputDescription | undefined> {
+    const seen = new Set<string>();
+    let currentBuild = build;
+    let currentOutput = output;
+    while (true) {
+      const address = `${currentBuild}\u0000${currentOutput}`;
+      assert(!seen.has(address), `Build Output forwarding repeats ${currentBuild} / ${currentOutput}`);
+      seen.add(address);
+      const manifest = await this.read(currentBuild);
+      const entry = manifest?.outputs[currentOutput];
+      if (entry === undefined) return undefined;
+      if (entry.value.kind === "build-output") {
+        currentBuild = entry.value.build;
+        currentOutput = entry.value.output;
+        continue;
+      }
+      return entry.value.kind === "build-file"
+        ? { type: entry.type, kind: "resource", size: entry.value.size, mediaType: entry.value.mediaType }
+        : entry.value.kind === "value"
+          ? { type: entry.type, kind: "composite" }
+          : { type: entry.type, kind: "scalar" };
+    }
+  }
+
+  async resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined> {
+    const seen = new Set<string>();
+    let currentBuild = build;
+    let currentOutput = output;
+    while (true) {
+      const address = `${currentBuild}\u0000${currentOutput}`;
+      assert(!seen.has(address), `Build Output forwarding repeats ${currentBuild} / ${currentOutput}`);
+      seen.add(address);
+      const manifest = await this.read(currentBuild);
+      const entry = manifest?.outputs[currentOutput];
+      if (entry === undefined) return undefined;
+      if (entry.value.kind === "build-output") {
+        currentBuild = entry.value.build;
+        currentOutput = entry.value.output;
+        continue;
+      }
+      if (entry.value.kind === "value") {
+        const rawDocument = await this.#readJson(currentBuild, entry.value.path);
+        assert(rawDocument !== undefined, `Build ${currentBuild} value ${entry.value.path} is unavailable`);
+        const document = decodeBuildResultValueDocument(
+          rawDocument,
+          `Build ${currentBuild} Output ${currentOutput}`,
+        );
+        return {
+          build: currentBuild,
+          output: currentOutput,
+          type: entry.type,
+          value: { ...entry.value, document },
+        };
+      }
+      const terminalKind = (entry.value as { readonly kind?: unknown }).kind;
+      assert(terminalKind === "build-file" || terminalKind === "inline",
+        `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);
+      return {
+        build: currentBuild,
+        output: currentOutput,
+        type: entry.type,
+        value: entry.value,
+      };
+    }
+  }
+
+  async openFile(
+    build: string,
+    file: BuildResultFileRef,
+    range?: BuildResultFileRange,
+  ): Promise<AsyncIterable<Uint8Array> | undefined> {
+    if (range !== undefined) {
+      assert(Number.isSafeInteger(range.start) && range.start >= 0, "Build Result file range start is invalid");
+      assert(Number.isSafeInteger(range.endExclusive) && range.endExclusive > range.start,
+        "Build Result file range end is invalid");
+      assert(range.endExclusive <= file.size, "Build Result file range exceeds the declared file size");
+    }
+    return await this.#client.open(this.#key(build, file.path), range);
+  }
+
+  /** Verify that the configured bucket/prefix can be listed without loading Result history. */
+  async diagnose(): Promise<void> {
+    const prefix = this.#prefix.length === 0 ? "" : `${this.#prefix}/`;
+    await this.#client.list(prefix, { limit: 1 });
+  }
+
+  async close(): Promise<void> {
+    await this.#client.close?.();
+  }
+}

package/packages/caption/README.md

@@ -0,0 +1,77 @@
+# `@hypit/caption`
+
+External components use `@hypit/hypit/caption` from their `@hypit/hypit` development dependency. The package
+owns the types and helpers below; Source imports retain the `@hypit/caption@1` Module identity.
+
+
+The deterministic Caption contract. Script emits one `CaptionDocument` containing display words,
+N:M alignment units and authored `||` cue breaks. Caption applies Styles to complete units selected
+by a Role or a semantic Selection, then joins those units to a `SemanticTrack` for frame timing.
+
+```xml
+<caption:Program id="captions" document={story.caption} narrative={story} default={plain}>
+  <caption:Use role="HOST" style={impact}/>
+  <caption:Use selection={story.selection.emphasis} style={plain}/>
+  <caption:Use attribute="emphasis" style={keyword}/>
+</caption:Program>
+```
+
+There is no planner, model call or frame range in this authoring contract. A Selection is projected
+to complete alignment units before timing; a Selection that cuts through an N:M unit is rejected.
+Script-native word attributes are resolved separately as local word Style runs and do not create
+another timing source. They are part of the common Caption contract for structural Caption families;
+`@hypit/caption-fine` deliberately rejects them because Fine requires one uniform token rule per Cue.
+
+`TimedCaptionProjection` is intentionally not a `TemporalWindow` collection. Cue timing is a
+read-only projection of token evidence, not an author-controlled placement window. It nevertheless
+carries the exact `spaceId`, `narrativeId` and `documentId`, so another SemanticTrack or Script cannot
+be substituted silently.
+
+## Extending with another rendering family
+
+The common public values are defined in [types.ts](src/types.ts), with exports in
+[index.ts](src/index.ts). A family supplies:
+
+- a Style decoder producing `CaptionStyleIntent` with its own `rendering.family` and validated
+  `rendering.parameters`;
+- an optional family schedule Type and deterministic scheduling Producer;
+- a rendering Producer returning the ordinary `VisualTrack` Type;
+- a Surface/Fragment connecting the common document, program and timing to those Producers.
+
+`caption:Program` remains the common author Surface. `Use` selects exactly one of `role`, `selection`
+or `attribute`; `Mute` selects a Role or Selection. For Role/Selection applications, the last matching
+`Use` in Source order selects the complete Style for each unit. It replaces the previous choice
+without merging Style parameters. A Selection can cover a phrase, a whole Segment, several Segments
+or the program through its structural anchors; there is no separate Segment selector.
+
+Word attributes produce separate `wordRuns`. Conflicting Styles on the same attributed word are
+rejected; these runs do not use the Role/Selection override rule. A family chooses whether and how
+it supports word-specific runs.
+
+Mute applications combine their selected unit ids independently of Style order. They suppress those
+display words, preserving the speech and semantic timeline. Visible lead and tail still belong to
+the family schedule, so muting a word is not a time-based mask of every neighboring Cue.
+
+Reuse `captionProducers.temporalizeDocument` with inputs `document`, `semantic` and `program`, or the
+corresponding exported timing Fragment. It emits a `TimedCaptionProjection` whose Cues contain
+`styleId`, `startFrame`, `endFrameExclusive` and measured `units`. Each unit carries `unitId` and its
+own boundaries. Recover display Words and their associations from the same `CaptionDocument`; do
+not infer N:M timing by evenly dividing a Cue or splitting its rendered string.
+
+Scheduling may derive visible intervals while preserving those measured boundaries. Use
+`assertCaptionProgramForDocument`, `assertTimedCaptionProjection` and, for visible scheduling,
+`applyCaptionMute` as appropriate. Retain `spaceId`, `narrativeId` and `documentId` in a schedule so
+the renderer can check its inputs. The renderer should consume that schedule without silently
+changing Cue grouping, lead or tail again.
+
+`@hypit/caption-fine` provides a working example in its `src/fragment.ts`, `src/schedule.ts` and
+`src/render.ts`: one shared timing join, then family schedule and render operations. A new structural
+family replaces Fine's uniform-word layout and parameters, not the common speech truth. Its own
+Manifest, activation and vocabulary belong to the project package; no change to this common package
+is required merely to add a new visual family.
+
+That family can render a standalone Caption Track or coordinate caption text with graphics in a
+shared scene. Its output uses ordinary VisualTrack elements or a renderer program with explicit
+resources. Caption retains the authored words and their semantic relationship while the component
+owns the visual boundary. The Program does not automatically route different families to different
+renderers; choose the implementing component and its coverage explicitly.

package/packages/caption/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hypit/caption",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/program-space": "workspace:*",
+    "@hypit/script": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/speech-alignment": "workspace:*",
+    "@hypit/speech-evidence": "workspace:*"
+  }
+}

package/packages/caption/src/activation.ts

@@ -0,0 +1,17 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  captionComponent, captionManifest, captionModuleRef,
+  decodeCaptionProgramSurface,
+  captionMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: captionManifest }],
+  components: [captionComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({ module: captionModuleRef,
+    declaration: captionMarkupSurfaces.find((item) => item.name === "program")!, handler: decodeCaptionProgramSurface }),
+  ],
+};
+export default hypitPackage;

package/packages/caption/src/component.ts

@@ -0,0 +1,38 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { CaptionDocument } from "@hypit/narrative";
+import type { SemanticTrack } from "@hypit/semantic-track";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { captionProducers, captionTypes } from "./manifest.js";
+import { assertCaptionProgram } from "./style.js";
+import { assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
+import type { CaptionProgram, CaptionStyleIntent, TimedCaptionProjection } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+  if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value as T;
+}
+
+export const captionComponent = {
+  producers: [{
+    producer: captionProducers.temporalizeDocument,
+    handler: ({ inputs }) => ({
+      outputs: { caption: { kind: "inline", value: canonicalize(temporalizeCaptionDocument(
+        inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
+        inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+        inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
+      )) } },
+      needs: {},
+    }),
+  }],
+  validators: [
+    { type: captionTypes.style, handler: ({ value }) => {
+      if (value.kind !== "inline") throw new Error("CaptionStyle must be inline");
+      const style = value.value as CaptionStyleIntent;
+      if (!style.id || !style.rendering?.family) throw new Error("CaptionStyle is invalid");
+    } },
+    { type: captionTypes.program, handler: ({ value }) => assertCaptionProgram(inline<CaptionProgram>(value, "CaptionProgram")) },
+    { type: captionTypes.timedProjection, handler: ({ value }) => assertTimedCaptionProjection(inline<TimedCaptionProjection>(value, "TimedCaptionProjection")) },
+  ],
+} satisfies ComponentPackage;

package/packages/caption/src/display.ts

@@ -0,0 +1,111 @@
+import type { CaptionDocument, Narrative, NarrativeSelection } from "@hypit/narrative";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function assertCaptionDocument(value: CaptionDocument): void {
+  assert(value.id.length > 0, "CaptionDocument identity is invalid");
+  assert(value.units.length > 0 && value.words.length > 0, "CaptionDocument is empty");
+  const words = new Map(value.words.map((word) => [word.id, word]));
+  assert(words.size === value.words.length, "CaptionDocument word ids are repeated");
+  const units = new Set<string>();
+  const orderedWordIds: string[] = [];
+  for (const unit of value.units) {
+    assert(unit.id.length > 0 && !units.has(unit.id), "CaptionDocument unit ids are repeated");
+    units.add(unit.id);
+    assert(unit.wordIds.length > 0 && unit.sourceTokenIds.length > 0, `Caption unit ${unit.id} is empty`);
+    for (const wordId of unit.wordIds) {
+      const word = words.get(wordId);
+      assert(word !== undefined && word.unitId === unit.id, `Caption unit ${unit.id} references a foreign word`);
+      assert(word.segmentId === unit.segmentId && word.turnId === unit.turnId && word.role === unit.role,
+        `Caption unit ${unit.id} disagrees with its word context`);
+      orderedWordIds.push(wordId);
+    }
+  }
+  assert(orderedWordIds.join("\0") === value.words.map((word) => word.id).join("\0"),
+    "CaptionDocument words must be partitioned by units in order");
+  const breakIds = new Set<string>();
+  for (const cueBreak of value.cueBreaks) {
+    assert(units.has(cueBreak.afterUnitId) && !breakIds.has(cueBreak.afterUnitId),
+      "CaptionDocument cue break names an unknown or repeated unit");
+    breakIds.add(cueBreak.afterUnitId);
+  }
+}
+
+export type CaptionUnitSubset = {
+  readonly documentId: string;
+  readonly unitIds: readonly string[];
+};
+
+function tokenBoundary(narrative: Narrative, anchorId: string, owner: string): number {
+  const anchor = narrative.semanticIndex.anchors.find((candidate) => candidate.id === anchorId);
+  if (anchor === undefined) throw new Error(`${owner} names unknown semantic anchor ${anchorId}`);
+  if (anchor.kind === "program-start") return 0;
+  if (anchor.kind === "program-end") return narrative.tokens.length;
+  const segment = narrative.segments.find((candidate) => candidate.id === anchor.segmentId);
+  if (segment === undefined) throw new Error(`${owner} names an anchor outside its Segment`);
+  if (anchor.kind === "segment-start") return segment.tokenStart;
+  if (anchor.kind === "segment-end") return segment.tokenEndExclusive;
+  const tokenIndex = narrative.tokens.findIndex((token) => token.id === anchor.tokenId);
+  if (tokenIndex < 0) throw new Error(`${owner} names an anchor without a Narrative token`);
+  return anchor.kind === "token-start" ? tokenIndex : tokenIndex + 1;
+}
+
+/** Project a semantic Selection to complete authored N:M Caption units. */
+export function captionUnitsForSelection(
+  document: CaptionDocument,
+  narrative: Narrative,
+  selection: NarrativeSelection,
+): CaptionUnitSubset {
+  assertCaptionDocument(document);
+  const start = tokenBoundary(narrative, selection.startAnchorId, `Selection ${selection.id}`);
+  const end = tokenBoundary(narrative, selection.endAnchorId, `Selection ${selection.id}`);
+  assert(end >= start, `Selection ${selection.id} is backwards`);
+  const tokenPositions = new Map(narrative.tokens.map((token, index) => [token.id, index]));
+  const unitIds: string[] = [];
+  for (const unit of document.units) {
+    const positions = unit.sourceTokenIds.map((tokenId) => tokenPositions.get(tokenId));
+    assert(positions.every((position): position is number => position !== undefined),
+      `Caption unit ${unit.id} references a token outside Narrative`);
+    const unitStart = Math.min(...positions as number[]);
+    const unitEnd = Math.max(...positions as number[]) + 1;
+    if (unitStart >= end || unitEnd <= start) continue;
+    if (unitStart < start || unitEnd > end) {
+      throw new Error(`Caption Selection ${selection.id} partially selects Alignment Unit ${unit.id}`);
+    }
+    unitIds.push(unit.id);
+  }
+  if (unitIds.length === 0) throw new Error(`Caption Selection ${selection.id} selects no complete display unit`);
+  return { documentId: document.id, unitIds };
+}
+
+export function captionUnitsForRole(document: CaptionDocument, role: string): CaptionUnitSubset {
+  assertCaptionDocument(document);
+  const unitIds = document.units.filter((unit) => unit.role === role).map((unit) => unit.id);
+  if (unitIds.length === 0) throw new Error(`Caption Role ${role} selects no display unit`);
+  return { documentId: document.id, unitIds };
+}
+
+export function captionWordsForAttribute(document: CaptionDocument, attribute: string): readonly string[] {
+  assertCaptionDocument(document);
+  const name = attribute.trim();
+  if (!name) throw new Error("Caption attribute name is empty");
+  const wordIds = document.words
+    .filter((word) => word.attributes.some((item) => item.name === name))
+    .map((word) => word.id);
+  if (wordIds.length === 0) throw new Error(`Caption attribute ${name} selects no display word`);
+  return wordIds;
+}
+
+export function assertCaptionUnitSubset(value: CaptionUnitSubset, document: CaptionDocument): void {
+  assertCaptionDocument(document);
+  assert(value.documentId === document.id, "Caption unit subset belongs to another document");
+  const known = new Set(document.units.map((unit) => unit.id));
+  assert(value.unitIds.length > 0 && value.unitIds.every((id) => known.has(id)),
+    "Caption unit subset contains an unknown unit");
+  const order = new Map(document.units.map((unit, index) => [unit.id, index]));
+  const indices = value.unitIds.map((id) => order.get(id)!);
+  assert(indices.every((index, position) => position === 0 || index === indices[position - 1]! + 1),
+    "Caption unit subset must be an ordered contiguous range");
+}

package/packages/caption/src/error.ts

@@ -0,0 +1,9 @@
+export class CaptionTimingError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "CaptionTimingError";
+    this.code = code;
+  }
+}

package/packages/caption/src/fragment.ts

@@ -0,0 +1,26 @@
+import { narrativeTypes } from "@hypit/narrative";
+import { semanticTrackTypes } from "@hypit/semantic-track";
+import { sealGraphFragment } from "@hypit/elaborator";
+
+import { captionProducers, captionTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export const captionTimingFragment = sealGraphFragment({
+  inputs: [
+    { name: "document", type: narrativeTypes.captionDocument },
+    { name: "semantic", type: semanticTrackTypes.track },
+    { name: "program", type: captionTypes.program },
+  ],
+  operations: [{
+    id: "temporalize-caption-document",
+    producer: captionProducers.temporalizeDocument,
+    inputs: { document: input("document"), semantic: input("semantic"), program: input("program") },
+    result: { kind: "output", name: "caption" },
+  }],
+  exports: [{ name: "caption", type: captionTypes.timedProjection, root: operation("temporalize-caption-document") }],
+});
+
+/** Kept as the fragment's public name for callers that only know the old export. */
+export const plannedCaptionTimingFragment = captionTimingFragment;