@hypit/hypit 0.1.3 → 0.1.5

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

@@ -1,5 +1,7 @@
+import { preserveExecutionLog } from "@hypit/build-result";
 import type {
   BuildResultFileRef,
+  ExternalFileAccess,
   BuildResultFileRange,
   BuildResultFinish,
   BuildResultManifest,
@@ -22,6 +24,8 @@ import {
   encodeBuildResultManifest,
   normalizeBuildResultForwards,
   syncBuildResultOutputs,
+  currentFileReference,
+  localExternalFiles,
 } from "@hypit/build-result";
 import { assertOrderedBuildId, buildIdCreatedAt } from "@hypit/protocol";
 
@@ -31,6 +35,7 @@ import type { AwsBuildResultS3ClientOptions, BuildResultS3Client } from "./clien
 export type S3BuildResultRepositoryOptions = AwsBuildResultS3ClientOptions & {
   readonly prefix?: string;
   readonly client?: BuildResultS3Client;
+  readonly externalFiles?: ExternalFileAccess;
 };
 
 function assert(condition: unknown, message: string): asserts condition {
@@ -102,6 +107,7 @@ class S3BuildResultWriter implements BuildResultWriter {
         },
       },
     });
+    if (!updated.changed) return manifest;
     await this.#repository.writeWriter(this.#build, updated.writer);
     await this.#repository.writeManifest(this.#build, updated.manifest);
     return updated.manifest;
@@ -115,10 +121,13 @@ class S3BuildResultWriter implements BuildResultWriter {
       await this.#repository.deleteWriter(this.#build);
       return manifest;
     }
+    const executionLog = await preserveExecutionLog(input.executionLog,
+      async (path, chunks, mediaType) => await this.#repository.writeFile(this.#build, path, chunks, mediaType));
     const now = Date.now();
     const updated: BuildResultManifest = {
       ...manifest,
       outcome: input.outcome,
+      ...(executionLog === undefined ? {} : { executionLog }),
       ...(input.operations === undefined ? {} : { operations: input.operations }),
       finishedAt: manifest.finishedAt ?? now,
       ...(input.failure === undefined ? {} : { failure: input.failure }),
@@ -132,10 +141,12 @@ class S3BuildResultWriter implements BuildResultWriter {
 export class S3BuildResultRepository implements BuildResultRepository {
   readonly #client: BuildResultS3Client;
   readonly #prefix: string;
+  readonly #externalFiles: ExternalFileAccess;
 
   constructor(options: S3BuildResultRepositoryOptions) {
     assert(options.bucket.trim().length > 0, "S3 Build Result bucket must not be empty");
     this.#prefix = normalizePrefix(options.prefix);
+    this.#externalFiles = options.externalFiles ?? localExternalFiles;
     this.#client = options.client ?? new AwsBuildResultS3Client(options);
   }
 
@@ -194,6 +205,7 @@ export class S3BuildResultRepository implements BuildResultRepository {
         resources: {},
         values: {},
         publishedOutputs: seed.publishedOutputs,
+        ...(seed.resourceReferences === undefined ? {} : { resourceReferences: seed.resourceReferences }),
         forwards,
       });
       await this.writeManifest(seed.id, manifest);
@@ -285,8 +297,9 @@ export class S3BuildResultRepository implements BuildResultRepository {
         currentOutput = entry.value.output;
         continue;
       }
-      return entry.value.kind === "build-file"
-        ? { type: entry.type, kind: "resource", size: entry.value.size, mediaType: entry.value.mediaType }
+      const file = entry.value.kind === "external-file" ? await currentFileReference(entry.value, this.#externalFiles) : entry.value;
+      return file.kind === "build-file" || file.kind === "external-file"
+        ? { type: entry.type, kind: "resource", size: file.size, mediaType: file.mediaType }
         : entry.value.kind === "value"
           ? { type: entry.type, kind: "composite" }
           : { type: entry.type, kind: "scalar" };
@@ -324,29 +337,34 @@ export class S3BuildResultRepository implements BuildResultRepository {
         };
       }
       const terminalKind = (entry.value as { readonly kind?: unknown }).kind;
-      assert(terminalKind === "build-file" || terminalKind === "inline",
+      assert(terminalKind === "build-file" || terminalKind === "external-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,
+        value: entry.value.kind === "external-file" ? await currentFileReference(entry.value, this.#externalFiles) : entry.value,
       };
     }
   }
 
+  async describeFile(_build: string, file: BuildResultFileRef): Promise<BuildResultFileRef> {
+    return await currentFileReference(file, this.#externalFiles);
+  }
+
   async openFile(
     build: string,
     file: BuildResultFileRef,
     range?: BuildResultFileRange,
   ): Promise<AsyncIterable<Uint8Array> | undefined> {
+    if (file.kind === "external-file") return await this.#externalFiles.open(file.uri, range);
     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);
+    return await this.#client.open(this.#key(file.build ?? build, file.path), range);
   }
 
   /** Verify that the configured bucket/prefix can be listed without loading Result history. */

package/packages/caption/README.md

@@ -1,77 +1,65 @@
 # `@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>
+External components import `@hypit/hypit/caption`. Source uses the `@hypit/caption@1` Module
+identity for shared declarations such as `Hidden`.
+
+Caption has two independent structures: Script organizes displayed words into Cues, and timed Uses
+choose how those Cues appear. A Use may begin inside a Cue. It changes presentation without changing
+that Cue's text or restarting its word timing.
+
+`CaptionDocument` owns displayed words, display/pronunciation associations, word attributes and `||`
+breaks. `Timeline` owns placed Takes and measured word times. `temporalizeCaptionDocument(document,
+timeline)` joins their identities and returns `TimedCaptionProjection`: complete Cues with original
+unit times. Segment, speaking-turn and explicit Cue boundaries organize this content. No Style is
+needed for this operation. Unplaced material contributes no Cue.
+
+A rendering family's Track accepts `document`, `timeline` and ordered `Use` children. Fine provides:
+
+```svml
+<caption:Hidden id="hidden"/>
+<caption-fine:Track id="captions" document={story.caption} timeline={film.timeline}>
+  <caption-fine:Use style={plain}/>
+  <caption-fine:Use role="GUEST" style={guest}/>
+  <caption-fine:Use during={story.selection.demo} style={hidden}/>
+  <caption-fine:Use at={story.moment.key} for="2s" style={impact}/>
+</caption-fine:Track>
 ```
 
-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.
+Time attributes come from `@hypit/temporal-markup`: `during`, `at`/`for`, `until`/`for`, and
+`start`/`end`, including semantic references and explicit frame/second expressions. Omitted time
+attributes mean the whole Timeline. `role` filters content independently of time. Later matching
+Uses replace earlier presentation inside their windows, including a Hidden Style. Separate Tracks
+remain independent and can intentionally display simultaneous captions.
+
+## Rendering-family extension
+
+A family owns its Style, schedule, renderer and Track Surface. It can use ordinary VisualTrack
+objects or an explicit browser program; no central renderer dispatch is required.
+
+The public helpers and Types are in [index.ts](src/index.ts):
+
+- `CaptionStyleIntent` carries a family identifier and parameters, or `rendering: null` for Hidden.
+- `CaptionProgram` is the Track's internal collection of ordered, resolved Uses and referenced Styles.
+  It is not a separate author element. `create-caption-uses` and `append-caption-use` assemble it from
+  typed Windows. The Track may export it for its Companion, like Performance and Sound.
+- `captionUseVisibility(program, index, role, envelope)` intersects a Cue envelope with a Use and
+  subtracts later matching windows. Hidden participates even though it renders nothing.
+- `captionProducers.temporalizeDocument` takes only `document` and `timeline`. Its output retains
+  `spaceId`, `narrativeId`, `documentId`, Cue identities and measured alignment-unit boundaries.
+
+Derive layout and animation from complete Cue content and original timing. Apply Use coverage as a
+visibility mask. Fine keeps the original Present span and element animations, with separate
+`visibility` intervals; changing or briefly hiding a Style does not restart karaoke, typing or motion.
+A family may define lead/tail and handoff behavior, but its resulting visibility stays inside the
+winning Use window. Empty content produces no drawing.
+
+Word attributes remain on `CaptionDocument.words`. A structural family can interpret an explicit
+attribute as a keyword role while retaining complete display/alignment units. Time selection does
+not split `<display|speech>` text, and elapsed Cue progress is not a replacement for word timing.
+The content query helpers for Role, Selection and attributes remain available for components that
+actually need authored word subsets; those queries do not define the Use time language.
+
+See Fine's [Surface](../caption-fine/src/surface.ts), [schedule](../caption-fine/src/schedule.ts) and
+[renderer](../caption-fine/src/render.ts) for a concrete implementation. New family behavior belongs
+in its own project package. The selected family interprets its own Styles; mixed-family dispatch,
+when useful, is an explicit component responsibility.

package/packages/caption/package.json

@@ -15,8 +15,9 @@
     "@hypit/elaborator": "workspace:*",
     "@hypit/narrative": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
-    "@hypit/markup": "workspace:*"
+    "@hypit/timeline": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/temporal": "workspace:*"
   },
   "devDependencies": {
     "@hypit/program-space": "workspace:*",

package/packages/caption/src/activation.ts

@@ -1,7 +1,7 @@
 import { createMarkupSurfaceHostFacet } from "@hypit/markup";
 import {
   captionComponent, captionManifest, captionModuleRef,
-  decodeCaptionProgramSurface,
+  decodeHiddenCaptionStyleSurface,
   captionMarkupSurfaces,
 } from "./index.js";
 
@@ -11,7 +11,7 @@ export const hypitPackage = {
   components: [captionComponent],
   hostFacets: [
     createMarkupSurfaceHostFacet({ module: captionModuleRef,
-    declaration: captionMarkupSurfaces.find((item) => item.name === "program")!, handler: decodeCaptionProgramSurface }),
+    declaration: captionMarkupSurfaces.find((item) => item.name === "hidden")!, handler: decodeHiddenCaptionStyleSurface }),
   ],
 };
 export default hypitPackage;

package/packages/caption/src/component.ts

@@ -1,11 +1,12 @@
+import type { TemporalWindow } from "@hypit/temporal";
 import type { ComponentPackage } from "@hypit/component-kit";
 import type { CaptionDocument } from "@hypit/narrative";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import type { Timeline } from "@hypit/timeline";
 import type { StoredValue } from "@hypit/protocol";
 import { canonicalize } from "@hypit/protocol";
 
 import { captionProducers, captionTypes } from "./manifest.js";
-import { assertCaptionProgram } from "./style.js";
+import { appendCaptionUse, assertCaptionProgram, assertCaptionStyle } from "./style.js";
 import { assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
 import type { CaptionProgram, CaptionStyleIntent, TimedCaptionProjection } from "./types.js";
 
@@ -16,12 +17,26 @@ function inline<T>(value: StoredValue | undefined, subject: string): T {
 
 export const captionComponent = {
   producers: [{
+    producer: captionProducers.create,
+    handler: ({ inputs }) => ({ outputs: { program: { kind: "inline", value: canonicalize({
+      id: inline<{id:string}>(inputs.header?.value, "CaptionTrackSpec").id,
+      documentId: inline<CaptionDocument>(inputs.document?.value, "CaptionDocument").id,
+      styles: [], uses: [],
+    }) } }, needs: {} }),
+  }, {
+    producer: captionProducers.append,
+    handler: ({ inputs }) => ({ outputs: { program: { kind: "inline", value: canonicalize(appendCaptionUse(
+      inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
+      inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+      inline<CaptionStyleIntent>(inputs.style?.value, "CaptionStyle"),
+      inline<{role?:string}>(inputs.filter?.value, "CaptionContentFilter").role,
+    )) } }, needs: {} }),
+  }, {
     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"),
+        inline<Timeline>(inputs.timeline?.value, "Timeline"),
       )) } },
       needs: {},
     }),
@@ -30,7 +45,7 @@ export const captionComponent = {
     { 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");
+      assertCaptionStyle(style);
     } },
     { type: captionTypes.program, handler: ({ value }) => assertCaptionProgram(inline<CaptionProgram>(value, "CaptionProgram")) },
     { type: captionTypes.timedProjection, handler: ({ value }) => assertTimedCaptionProjection(inline<TimedCaptionProjection>(value, "TimedCaptionProjection")) },

package/packages/caption/src/display.ts

@@ -1,3 +1,4 @@
+import { narrativeSelectionTokenRange } from "@hypit/narrative";
 import type { CaptionDocument, Narrative, NarrativeSelection } from "@hypit/narrative";
 
 function assert(condition: unknown, message: string): asserts condition {
@@ -38,30 +39,14 @@ export type CaptionUnitSubset = {
   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 {
+  const document = narrative.caption;
   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 { tokenStart: start, tokenEndExclusive: end } = narrativeSelectionTokenRange(narrative, selection);
   const tokenPositions = new Map(narrative.tokens.map((token, index) => [token.id, index]));
   const unitIds: string[] = [];
   for (const unit of document.units) {

package/packages/caption/src/fragment.ts

@@ -1,5 +1,5 @@
 import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 import { sealGraphFragment } from "@hypit/elaborator";
 
 import { captionProducers, captionTypes } from "./manifest.js";
@@ -10,17 +10,13 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
 export const captionTimingFragment = sealGraphFragment({
   inputs: [
     { name: "document", type: narrativeTypes.captionDocument },
-    { name: "semantic", type: semanticTrackTypes.track },
-    { name: "program", type: captionTypes.program },
+    { name: "timeline", type: timelineTypes.track },
   ],
   operations: [{
     id: "temporalize-caption-document",
     producer: captionProducers.temporalizeDocument,
-    inputs: { document: input("document"), semantic: input("semantic"), program: input("program") },
+    inputs: { document: input("document"), timeline: input("timeline") },
     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;

package/packages/caption/src/index.ts

@@ -8,7 +8,7 @@ export {
 export type { CaptionUnitSubset } from "./display.js";
 export { captionWordsForAttribute } from "./display.js";
 export { captionComponent } from "./component.js";
-export { captionTimingFragment, plannedCaptionTimingFragment } from "./fragment.js";
+export { captionTimingFragment } from "./fragment.js";
 export {
   captionProgramSchema,
   captionStyleSchema,
@@ -19,15 +19,16 @@ export {
   captionProducers,
   captionTypes,
 } from "./manifest.js";
-export { decodeCaptionProgramSurface } from "./surface.js";
+export { decodeHiddenCaptionStyleSurface } from "./surface.js";
 export {
   assertCaptionProgram,
   assertCaptionProgramForDocument,
   assertCaptionStyle,
-  resolveCaptionProgram,
+  appendCaptionUse,
   sealCaptionProgram,
   sealCaptionStyle,
 } from "./style.js";
-export type { CaptionMuteApplication, CaptionStyleApplication, CaptionWordStyleApplication } from "./style.js";
-export { applyCaptionMute, assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
+export { assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
 export type * from "./types.js";
+
+export { captionUseVisibility } from "./visibility.js";

package/packages/caption/src/manifest.ts

@@ -1,12 +1,17 @@
+import { temporalDependency, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
 import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
 
 export const captionModuleRef = { name: "@hypit/caption", version: "1" } as const;
 export const captionProducers = {
+  create: { module: captionModuleRef, name: "create-caption-uses" },
+  append: { module: captionModuleRef, name: "append-caption-use" },
   temporalizeDocument: { module: captionModuleRef, name: "temporalize-caption-document" },
 } satisfies Record<string, ProducerRef>;
 export const captionTypes = {
+  header: { module: captionModuleRef, name: "CaptionTrackSpec" },
+  filter: { module: captionModuleRef, name: "CaptionContentFilter" },
   style: { module: captionModuleRef, name: "CaptionStyle" },
   program: { module: captionModuleRef, name: "CaptionProgram" },
   timedProjection: { module: captionModuleRef, name: "TimedCaptionProjection" },
@@ -17,21 +22,17 @@ 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({
+  rendering: { schema: { kind: "oneOf", variants: [{ kind: "null" }, 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 } },
+  styles: { schema: { kind: "array", items: captionStyleSchema } },
+  uses: { schema: { kind: "array", items: object({
+    window: { schema: temporalWindowSchema }, styleId: { schema: string }, role: { schema: string, optional: true },
   }) } },
-  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({
@@ -39,58 +40,40 @@ export const timedCaptionProjectionSchema: ValueSchema = object({
   narrativeId: { schema: string },
   documentId: { schema: string },
   cues: { schema: { kind: "array", items: object({
-    id: { schema: string }, styleId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer },
+    id: { 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],
+  name: "hidden", tag: "Hidden", mode: "structured", outputs: [captionTypes.style],
   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.",
-    ],
+    summary: "Declares a Caption Style that contributes no rendering when selected by Use.",
+    attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names the hidden Style." }],
+    example: '<caption:Hidden id="hidden"/>',
+    notes: ["Hidden is a complete Style choice; it uses ordinary Use precedence and changes no speech or semantic anchors."],
   },
 }] as const;
 
 export const captionManifest: ModuleManifest = {
   format: "hypit.module@1", name: captionModuleRef.name, version: captionModuleRef.version,
-  dependencies: [narrativeDependency, semanticTrackDependency], types: [
+  dependencies: [narrativeDependency, timelineDependency, temporalDependency], types: [
+    { name: captionTypes.header.name }, { name: captionTypes.filter.name },
     { name: captionTypes.style.name }, { name: captionTypes.program.name }, { name: captionTypes.timedProjection.name },
   ], capabilities: [], producers: [{
+    name: captionProducers.create.name,
+    inputs: [{ name: "document", type: narrativeTypes.captionDocument }, { name: "header", type: captionTypes.header }],
+    outputs: [{ name: "program", type: captionTypes.program }], needs: [],
+  }, {
+    name: captionProducers.append.name,
+    inputs: [{ name: "program", type: captionTypes.program }, { name: "window", type: temporalTypes.window },
+      { name: "style", type: captionTypes.style }, { name: "filter", type: captionTypes.filter }],
+    outputs: [{ name: "program", type: captionTypes.program }], needs: [],
+  }, {
     name: captionProducers.temporalizeDocument.name,
     inputs: [
       { name: "document", type: narrativeTypes.captionDocument },
-      { name: "semantic", type: semanticTrackTypes.track },
-      { name: "program", type: captionTypes.program },
+      { name: "timeline", type: timelineTypes.track },
     ],
     outputs: [{ name: "caption", type: captionTypes.timedProjection }], needs: [],
   }],