@hypit/hypit 0.1.3 → 0.1.5

package/packages/{speech-track → timeline-author}/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@hypit/speech-track",
+  "name": "@hypit/timeline-author",
   "version": "0.0.0-dev",
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
@@ -12,12 +12,14 @@
   },
   "dependencies": {
     "@hypit/component-kit": "workspace:*",
-    "@hypit/composition": "workspace:*",
     "@hypit/elaborator": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/speech": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
-    "@hypit/markup": "workspace:*"
+    "@hypit/timeline": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*"
   },
   "devDependencies": {
     "@hypit/core": "workspace:*",

package/packages/timeline-author/src/activation.ts

@@ -0,0 +1,22 @@
+import { decodeClockSurface } from "@hypit/program-space";
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  decodeTimelineAuthorSurface, timelineAuthorComponent, timelineAuthorManifest,
+  timelineAuthorModuleRef,
+  timelineAuthorMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: timelineAuthorManifest,
+  }],
+  components: [timelineAuthorComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: timelineAuthorModuleRef,
+    declaration: timelineAuthorMarkupSurfaces.find((item) => item.name === "timeline")!, handler: decodeTimelineAuthorSurface,
+  }), createMarkupSurfaceHostFacet({ module: timelineAuthorModuleRef,
+    declaration: timelineAuthorMarkupSurfaces.find(item => item.name === "clock")!, handler: decodeClockSurface,
+  })],
+};
+export default hypitPackage;

package/packages/{speech-track → timeline-author}/src/component.ts

@@ -1,42 +1,44 @@
+import type { ProgramClock } from "@hypit/program-space";
 import type { ComponentPackage } from "@hypit/component-kit";
 import type { StoredValue } from "@hypit/protocol";
 import { canonicalize } from "@hypit/protocol";
 import type { SemanticTake } from "@hypit/speech";
 
-import { speechTrackProducers } from "./manifest.js";
-import { appendSpeechTrackTake, assembleSpeechTrack, createSpeechTrackSet } from "./program.js";
-import type { SpeechTrackHeader, SpeechTrackSet } from "./types.js";
+import { timelineAuthorProducers } from "./manifest.js";
+import { appendTimelineAuthorTake, assembleTimelineAuthor, createTimelineAuthorSet } from "./program.js";
+import type { TimelineAuthorHeader, TimelineAuthorSet } 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 unknown as T;
 }
 
-export const speechTrackComponent = {
+export const timelineAuthorComponent = {
   producers: [
     {
-      producer: speechTrackProducers.createSet,
+      producer: timelineAuthorProducers.createSet,
       handler: () => ({
-        outputs: { set: { kind: "inline", value: canonicalize(createSpeechTrackSet()) } },
+        outputs: { set: { kind: "inline", value: canonicalize(createTimelineAuthorSet()) } },
         needs: {},
       }),
     },
     {
-      producer: speechTrackProducers.appendTake,
+      producer: timelineAuthorProducers.appendTake,
       handler: ({ inputs }) => ({
-        outputs: { set: { kind: "inline", value: canonicalize(appendSpeechTrackTake(
-          inline<SpeechTrackSet>(inputs.set?.value, "SpeechTrackSet"),
+        outputs: { set: { kind: "inline", value: canonicalize(appendTimelineAuthorTake(
+          inline<TimelineAuthorSet>(inputs.set?.value, "TimelineAuthorSet"),
           inline<SemanticTake>(inputs.take?.value, "SemanticTake"),
         )) } },
         needs: {},
       }),
     },
     {
-      producer: speechTrackProducers.assembleTrack,
+      producer: timelineAuthorProducers.assembleTrack,
       handler: ({ inputs }) => ({
-        outputs: { track: { kind: "inline", value: canonicalize(assembleSpeechTrack(
-          inline<SpeechTrackHeader>(inputs.header?.value, "SpeechTrackHeader"),
-          inline<SpeechTrackSet>(inputs.set?.value, "SpeechTrackSet"),
+        outputs: { track: { kind: "inline", value: canonicalize(assembleTimelineAuthor(
+          inline<TimelineAuthorHeader>(inputs.header?.value, "TimelineAuthorHeader"),
+          inline<TimelineAuthorSet>(inputs.set?.value, "TimelineAuthorSet"),
+          inline<ProgramClock>(inputs.clock?.value, "ProgramClock"),
         )) } },
         needs: {},
       }),

package/packages/{speech-track → timeline-author}/src/fragment.ts

@@ -1,35 +1,35 @@
+import { programSpaceTypes } from "@hypit/program-space";
 import { speechTypes } from "@hypit/speech";
-import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
 import type { FragmentOperation } from "@hypit/elaborator";
-import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 import type { TypeRef } from "@hypit/protocol";
 
-import { speechTrackProducers, speechTrackTypes } from "./manifest.js";
-import type { SpeechTrackFragmentOptions } from "./types.js";
+import { timelineAuthorProducers, timelineAuthorTypes } from "./manifest.js";
+import type { TimelineAuthorFragmentOptions } from "./types.js";
 
 const input = (name: string) => ({ kind: "fragment-input" as const, name });
 const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
 
-export function createSpeechTrackFragment(options: SpeechTrackFragmentOptions) {
-  if (options.takes.length === 0) throw new Error("Speech Track requires at least one Take");
+export function createTimelineAuthorFragment(options: TimelineAuthorFragmentOptions) {
   const declaredInputs = new Map<string, TypeRef>();
   const addInput = (name: string, type: TypeRef): void => {
-    if (!name) throw new Error("Speech Track Fragment input names must not be empty");
+    if (!name) throw new Error("Timeline Fragment input names must not be empty");
     const previous = declaredInputs.get(name);
     if (previous !== undefined && (previous.module.name !== type.module.name
       || previous.module.version !== type.module.version || previous.name !== type.name)) {
-      throw new Error(`Speech Track Fragment input ${name} is reused with another Type`);
+      throw new Error(`Timeline Fragment input ${name} is reused with another Type`);
     }
     declaredInputs.set(name, type);
   };
-  addInput("header", speechTrackTypes.header);
+  addInput("header", timelineAuthorTypes.header);
+  addInput("clock", programSpaceTypes.clock);
   for (const take of options.takes) {
     addInput(take.takeName, speechTypes.semanticTake);
   }
   const operations: FragmentOperation[] = [{
     id: "track:set:empty",
-    producer: speechTrackProducers.createSet,
+    producer: timelineAuthorProducers.createSet,
     inputs: {},
     result: { kind: "output", name: "set" },
   }];
@@ -38,7 +38,7 @@ export function createSpeechTrackFragment(options: SpeechTrackFragmentOptions) {
     const id = `track:set:append:${String(index + 1).padStart(4, "0")}`;
     operations.push({
       id,
-      producer: speechTrackProducers.appendTake,
+      producer: timelineAuthorProducers.appendTake,
       inputs: {
         set: operation(current),
         take: input(take.takeName),
@@ -50,25 +50,16 @@ export function createSpeechTrackFragment(options: SpeechTrackFragmentOptions) {
   operations.push(
     {
       id: "track:semantic",
-      producer: speechTrackProducers.assembleTrack,
-      inputs: { header: input("header"), set: operation(current) },
+      producer: timelineAuthorProducers.assembleTrack,
+      inputs: { header: input("header"), set: operation(current), clock: input("clock") },
       result: { kind: "output", name: "track" },
     },
-    {
-      id: "track:audio-track",
-      producer: semanticTrackProducers.projectAudio,
-      inputs: { track: operation("track:semantic") },
-      result: { kind: "output", name: "audio" },
-    },
   );
   return sealGraphFragment({
     inputs: [...declaredInputs.entries()].map(([name, type]) => ({ name, type })),
     operations,
     exports: [
-      { name: "semantic", type: semanticTrackTypes.track, root: operation("track:semantic") },
-      {
-        name: "audio", type: compositionTypes.audioTrack, root: operation("track:audio-track"),
-      },
+      { name: "timeline", type: timelineTypes.track, root: operation("track:semantic") },
     ],
   });
 }

package/packages/timeline-author/src/index.ts

@@ -0,0 +1,7 @@
+/** Official Timeline authoring and deterministic Timeline assembly. */
+export { timelineAuthorComponent } from "./component.js";
+export { createTimelineAuthorFragment } from "./fragment.js";
+export { timelineAuthorManifest, timelineAuthorMarkupSurfaces, timelineAuthorModuleRef, timelineAuthorProducers, timelineAuthorTypes, timelineAuthorHeaderSchema, timelineAuthorSetSchema } from "./manifest.js";
+export { appendTimelineAuthorTake, assembleTimelineAuthor, assertTimelineAuthorHeader, assertTimelineAuthorSet, createTimelineAuthorSet, sealTimelineAuthorHeader } from "./program.js";
+export { decodeTimelineAuthorSurface } from "./surface.js";
+export type * from "./types.js";

package/packages/timeline-author/src/manifest.ts

@@ -0,0 +1,78 @@
+import { programSpaceDependency, programSpaceTypes, programSpaceMarkupSurfaces } from "@hypit/program-space";
+import { semanticTakeSchema, speechDependency, speechTypes } from "@hypit/speech";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+import type { ModuleManifest, ValueSchema } from "@hypit/protocol";
+export const timelineAuthorModuleRef = { name: "@hypit/timeline-author", version: "1" } as const;
+export const timelineAuthorTypes = {
+  header: { module: timelineAuthorModuleRef, name: "TimelineAuthorHeader" },
+  trackSet: { module: timelineAuthorModuleRef, name: "TimelineAuthorSet" },
+} as const;
+export const timelineAuthorProducers = {
+  createSet: { module: timelineAuthorModuleRef, name: "create-track-set" },
+  appendTake: { module: timelineAuthorModuleRef, name: "append-track-take" },
+  assembleTrack: { module: timelineAuthorModuleRef, name: "assemble-timeline" },
+} as const;
+export const timelineAuthorHeaderSchema: ValueSchema = { kind: "object", fields: { id: { schema: { kind: "string", minLength: 1 } }, at: { optional: true, schema: { kind: "array", items: { kind: "string" } } }, end: { optional: true, schema: { kind: "string" } } } };
+export const timelineAuthorSetSchema: ValueSchema = { kind: "object", fields: { takes: { schema: { kind: "array", items: { kind: "object", fields: { semantic: { schema: semanticTakeSchema } } } } } } };
+export const timelineAuthorMarkupSurfaces = [{
+  name: "timeline", tag: "Timeline", mode: "structured",
+  outputs: [timelineAuthorTypes.header, timelineTypes.track],
+  vocabulary: {
+    summary: "Declares one complete Timeline, with zero or more prepared Takes placed within it.",
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Names the Timeline output." },
+      { name: "clock", kind: "reference", required: true, accepts: [programSpaceTypes.clock], summary: "Frame rate, available before material generation." },
+      { name: "end", kind: "literal", required: false, summary: "Program end: fixed time or content.end with an optional offset; defaults to content.end." },
+    ],
+    children: [{ tag: "Take", cardinality: "many", summary: "A prepared SemanticTake in performance order.",
+      attributes: [{ name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake], summary: "The normalized, aligned performance." },
+        { name: "at", kind: "literal", required: false, summary: "Absolute position or previous.end with an offset. Defaults to zero for the first Take and previous.end thereafter." }] }],
+    ports: [
+      { name: "timeline", type: timelineTypes.track, summary: "The complete time range, retaining placed material and any semantic evidence." },
+    ],
+    example: '<time:Clock id="clock" frame-rate="30"/><time:Timeline id="program" clock={clock} end="content.end+2s"><time:Take source={opening.take} at="2s"/><time:Take source={answer.take}/></time:Timeline>',
+    notes: ["Performance, Sound and Caption present existing pictures, audio and words independently. Include their contributions explicitly in Film."],
+  },
+}, programSpaceMarkupSurfaces[0]] as const;
+export const timelineAuthorManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: timelineAuthorModuleRef.name,
+  version: timelineAuthorModuleRef.version,
+  dependencies: [
+    programSpaceDependency,
+    speechDependency,
+    timelineDependency,
+  ],
+  types: [
+    { name: timelineAuthorTypes.header.name },
+    { name: timelineAuthorTypes.trackSet.name },
+  ],
+  capabilities: [],
+  producers: [
+    {
+      name: timelineAuthorProducers.createSet.name,
+      inputs: [],
+      outputs: [{ name: "set", type: timelineAuthorTypes.trackSet }],
+      needs: [],
+    },
+    {
+      name: timelineAuthorProducers.appendTake.name,
+      inputs: [
+        { name: "set", type: timelineAuthorTypes.trackSet },
+        { name: "take", type: speechTypes.semanticTake },
+      ],
+      outputs: [{ name: "set", type: timelineAuthorTypes.trackSet }],
+      needs: [],
+    },
+    {
+      name: timelineAuthorProducers.assembleTrack.name,
+      inputs: [
+        { name: "header", type: timelineAuthorTypes.header },
+        { name: "clock", type: programSpaceTypes.clock },
+        { name: "set", type: timelineAuthorTypes.trackSet },
+      ],
+      outputs: [{ name: "track", type: timelineTypes.track }],
+      needs: [],
+    },
+  ],
+};

package/packages/timeline-author/src/program.ts

@@ -0,0 +1,107 @@
+import { assertProgramClockIdentity, type ProgramClock } from "@hypit/program-space";
+import { durationInFrames } from "@hypit/temporal";
+import { parseTemporalDuration } from "@hypit/temporal-markup";
+import { assertSemanticTakeIdentity } from "@hypit/speech";
+import type { SemanticTake } from "@hypit/speech";
+import { sealTimeline } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import type { TimelineAuthorHeader, TimelineAuthorSet, TimelineAuthorTake } from "./types.js";
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+export function sealTimelineAuthorHeader(value: TimelineAuthorHeader): TimelineAuthorHeader { return structuredClone(value); }
+export function assertTimelineAuthorHeader(value: TimelineAuthorHeader): void {
+  assert(value.id.trim().length > 0, "TimelineAuthorHeader id must not be empty");
+}
+function sealTimelineAuthorSet(value: TimelineAuthorSet): TimelineAuthorSet { return structuredClone(value); }
+function assertTake(take: TimelineAuthorTake): void { assertSemanticTakeIdentity(take.semantic); }
+export function assertTimelineAuthorSet(value: TimelineAuthorSet): void {
+  const segments = new Set<string>();
+  for (const take of value.takes) {
+    assertSemanticTakeIdentity(take.semantic);
+    const segmentId = take.semantic.segment.segmentId;
+    assert(!segments.has(segmentId), `Timeline repeats Segment ${segmentId}`);
+    segments.add(segmentId);
+  }
+}
+
+export function createTimelineAuthorSet(): TimelineAuthorSet {
+  return sealTimelineAuthorSet({
+    takes: [],
+  });
+}
+
+function appendTake(
+  set: TimelineAuthorSet,
+  take: TimelineAuthorTake,
+): TimelineAuthorSet {
+  assertTimelineAuthorSet(set);
+  assertTake(take);
+  assert(!set.takes.some((item) => item.semantic.segment.segmentId === take.semantic.segment.segmentId),
+    `Timeline repeats Segment ${take.semantic.segment.segmentId}`);
+  return sealTimelineAuthorSet({
+    takes: [...set.takes, take],
+  });
+}
+
+export function appendTimelineAuthorTake(set: TimelineAuthorSet, semantic: SemanticTake): TimelineAuthorSet {
+  return appendTake(set, { semantic });
+}
+
+export function assembleTimelineAuthor(
+  header: TimelineAuthorHeader,
+  set: TimelineAuthorSet,
+  clock: ProgramClock,
+): Timeline {
+  assertTimelineAuthorHeader(header);
+  assertTimelineAuthorSet(set);
+  assertProgramClockIdentity(clock);
+  if (header.at !== undefined && header.at.length !== set.takes.length) {
+    throw new Error("Timeline placement declarations must correspond to its Takes.");
+  }
+  const narrativeId = set.takes[0]?.semantic.narrativeId;
+  let previousEnd = 0;
+  let contentEnd = 0;
+  const items = set.takes.map((item, index) => {
+    const at = header.at?.[index] ?? (index === 0 ? "0f" : "previous.end");
+    const startFrame = placementFrame(at, clock, index === 0 ? undefined : previousEnd, "previous.end");
+    previousEnd = startFrame + item.semantic.media.timeline.frameCount;
+    contentEnd = Math.max(contentEnd, previousEnd);
+    return { take: item.semantic, startFrame };
+  });
+  const endFrame = placementFrame(header.end ?? "content.end", clock, contentEnd, "content.end");
+  assert(endFrame > 0, "Timeline needs a positive end; an empty Timeline requires an authored extent.");
+  assert(endFrame >= contentEnd, "Timeline end precedes placed content; choose an end that includes its Takes.");
+  return sealTimeline({
+    id: header.id, frameRate: clock.frameRate,
+    durationSec: endFrame * clock.frameRate.denominator / clock.frameRate.numerator,
+    ...(narrativeId === undefined ? {} : { narrativeId }), items,
+  });
+}
+
+/** Parse local placement syntax before any upstream material needs to run. */
+export function placementExpression(expression: string, reference: string) {
+  const value = expression.trim();
+  if (!value.startsWith(reference)) return { relative: false, sign: 1,
+    duration: parseTemporalDuration(value, "Timeline position") };
+  const offset = value.slice(reference.length).trim();
+  if (offset === "") return { relative: true, sign: 1,
+    duration: parseTemporalDuration("0f", "Timeline offset") };
+  const match = /^([+-])\s*(.+)$/u.exec(offset);
+  if (match === null) throw new Error(`Invalid Timeline position ${expression}.`);
+  return { relative: true, sign: match[1] === "-" ? -1 : 1,
+    duration: parseTemporalDuration(match[2]!, "Timeline offset") };
+}
+
+/** Resolve local assembly expressions before a complete Timeline exists. */
+export function placementFrame(expression: string, clock: ProgramClock, base: number | undefined, reference: string): number {
+  const parsed = placementExpression(expression, reference);
+  if (parsed.relative && base === undefined) throw new Error(`${reference} has no preceding Take.`);
+  const frames = durationInFrames(parsed.duration, clock);
+  if (frames.denominator !== 1n || frames.numerator > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`Timeline duration ${expression} must land on an exact frame boundary.`);
+  }
+  const frame = (parsed.relative ? base! : 0) + parsed.sign * Number(frames.numerator);
+  if (!Number.isSafeInteger(frame) || frame < 0) throw new Error(`Timeline position ${expression} must resolve to a non-negative frame.`);
+  return frame;
+}

package/packages/timeline-author/src/surface.ts

@@ -0,0 +1,46 @@
+import { placementExpression } from "./program.js";
+import { programSpaceTypes } from "@hypit/program-space";
+import { assertAttributes, assertEmptyElement, localName, textAttribute, type StructuredSurfaceHandler } from "@hypit/markup";
+import { sameType } from "@hypit/protocol";
+import { speechTypes } from "@hypit/speech";
+import { createTimelineAuthorFragment } from "./fragment.js";
+import { timelineAuthorTypes } from "./manifest.js";
+
+export const decodeTimelineAuthorSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "clock", "end"]);
+  const id = textAttribute(element, "id");
+  const rawClock = element.attributes.clock;
+  const clock = typeof rawClock === "object" && rawClock.kind === "reference" ? resolveReference(rawClock.path) : undefined;
+  if (clock === undefined || !sameType(clock.type, programSpaceTypes.clock)) throw new Error(`${element.name}.clock must reference a Clock.`);
+  if (element.attributes.end !== undefined) placementExpression(textAttribute(element, "end"), "content.end");
+  const at: string[] = [];
+  const takes = element.children.flatMap(child => {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error("Timeline accepts only Take children.");
+      return [];
+    }
+    if (localName(child.name) !== "Take") throw new Error("Timeline accepts only Take children.");
+    assertAttributes(child, ["source", "at"]);
+    at.push(child.attributes.at === undefined ? (at.length === 0 ? "0f" : "previous.end") : textAttribute(child, "at"));
+    const position = placementExpression(at.at(-1)!, "previous.end");
+    if (at.length === 1 && position.relative) throw new Error("The first Timeline Take has no previous.end.");
+    assertEmptyElement(child);
+    const source = child.attributes.source;
+    if (typeof source !== "object" || source.kind !== "reference") throw new Error("Timeline Take source must be a reference.");
+    const resolved = resolveReference(source.path);
+    if (resolved === undefined || !sameType(resolved.type, speechTypes.semanticTake)) throw new Error("Timeline Take source must be a SemanticTake.");
+    return [resolved];
+  });
+  const inputs = takes.map((_, index) => ({ takeName: `take-${index + 1}` }));
+  const fragment = createTimelineAuthorFragment({ takes: inputs });
+  return {
+    records: [{ id: `${id}.header`, type: timelineAuthorTypes.header, value: { kind: "inline", value: { id, at, ...(element.attributes.end === undefined ? {} : { end: textAttribute(element, "end") }) } }, range: element.range }],
+    fragments: [fragment],
+    components: [{ id, fragment: fragment.id, inputs: {
+      clock: clock.ref,
+      header: { kind: "record", id: `${id}.header` },
+      ...Object.fromEntries(takes.map((take, index) => [inputs[index]!.takeName, take.ref])),
+    }, outputs: { timeline: `${id}.timeline` }, range: element.range }],
+    exports: [`${id}.timeline`],
+  };
+};

package/packages/timeline-author/src/types.ts

@@ -0,0 +1,6 @@
+import type { SemanticTake } from "@hypit/speech";
+export type TimelineAuthorHeader = { readonly id: string; readonly at?: readonly string[]; readonly end?: string };
+export type TimelineAuthorTake = { readonly semantic: SemanticTake };
+export type TimelineAuthorSet = { readonly takes: readonly TimelineAuthorTake[] };
+export type TimelineAuthorInput = { readonly takeName: string };
+export type TimelineAuthorFragmentOptions = { readonly takes: readonly TimelineAuthorInput[] };

package/packages/typography-track/README.md

@@ -1,14 +1,14 @@
 # `@hypit/typography-track`
 
-The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
-resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+The Track Surface accepts `timeline={program.timeline}`. The same Timeline supports authored
+positions and, where prepared Takes supply evidence, Script Selections and Moments. Shared `at`
 inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
 
 Place independently authored titles, labels, verdicts and other text in the video. Their lifetime
 can follow a Script Selection or Moment even when their wording differs from the speech. For words
 displayed as they are spoken, use a [Caption family](../caption-fine/README.md).
 
-The Track takes `semantic` or `space` to supply ProgramSpace. Items use explicit Point, Frame or Path
+The Track takes the shared `timeline`. Items use explicit Point, Frame or Path
 placement, exact fonts and Styles. Timing can follow a Segment, Selection, Moment with duration, the
 whole program or explicit clock expressions. `.program` describes the text presentation; `.track`
 is the VisualTrack to include in Film. Each item has its own lifetime and stacking order.
@@ -26,7 +26,7 @@ Content has two explicit author forms:
 
 <copy:Value id="headline-copy">A useful idea, clearly shown.</copy:Value>
 
-<typo:Track id="titles" semantic={speech.semantic}>
+<typo:Track id="titles" timeline={speech.timeline}>
   <typo:Area id="headline" content={headline-copy}
     placement={layout.headline} style={title-style} during="program"/>
 

package/packages/typography-track/package.json

@@ -18,7 +18,7 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/program-space": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/temporal": "workspace:*",

package/packages/typography-track/src/component.ts

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CompositableSurfaceRef } from "@hypit/media";
 import type { SpatialFrame, SpatialPath, SpatialPoint } from "@hypit/spatial";
 import type { StoredValue } from "@hypit/protocol";
@@ -58,7 +58,7 @@ export const typographyTrackComponent = {
       handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedTextItem(
         inline<TypographyTrackSet>(inputs.set?.value, "TypographyTrackSet"),
         inline<TypographyTrackHeader>(inputs.header?.value, "TypographyTrackHeader"),
-        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<Timeline>(inputs.timeline?.value, "Timeline"),
         inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),
         inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
         inline<TextStyle>(inputs.style?.value, "TextStyle"),
@@ -76,14 +76,14 @@ export const typographyTrackComponent = {
     {
       producer: typographyTrackProducers.render,
       handler: ({ inputs }) => ({ outputs: { track: output(renderTypographyTrack(
-        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<Timeline>(inputs.timeline?.value, "Timeline"),
         inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),
       )) }, needs: {} }),
     },
     {
       producer: typographyTrackProducers.renderMask,
       handler: ({ inputs }) => ({ outputs: { track: output(renderTextMaskTrack(
-        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<Timeline>(inputs.timeline?.value, "Timeline"),
         inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),
         inline<CompositableSurfaceRef>(inputs.material?.value, "CompositableSurfaceRef"),
         inline<TextMaskSpec>(inputs.spec?.value, "TextMaskSpec"),

package/packages/typography-track/src/fragment.ts

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { compositionTypes } from "@hypit/composition";
 import type { VisualTrack } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
@@ -11,14 +12,14 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
 /** Provider-free official lowering from TypographyTrackProgram to one peer VisualTrack. */
 export const typographyTrackFragment = sealGraphFragment({
   inputs: [
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "program", type: typographyTrackTypes.program },
   ],
   operations: [
     {
       id: "render",
       producer: typographyTrackProducers.render,
-      inputs: { space: input("space"), program: input("program") },
+      inputs: { timeline: input("timeline"), program: input("program") },
       result: { kind: "output", name: "track" },
     },
   ],

package/packages/typography-track/src/manifest.ts

@@ -1,9 +1,11 @@
+import { timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { readFile } from "node:fs/promises";
 
 import { narrativeDependency } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+
+import { timelineDependency } from "@hypit/timeline";
 import {
   compositionDependency,
   compositionTypes,
@@ -423,7 +425,7 @@ export const typographyTrackMarkupSurfaces = [
     },
     { name: "track", tag: "Track", mode: "structured", outputs: [typographyTrackTypes.header, typographyTrackTypes.itemSpec, typographyTrackTypes.plainItemSpec, typographyTrackTypes.motion, typographyTrackTypes.set, typographyTrackTypes.placement, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, typographyTrackTypes.program, compositionTypes.visualTrack],
       vocabulary: {
-        summary: "One Typography Track: independently placed and timed text items on a shared ProgramSpace, lowered to one addressable TypographyTrackProgram and one peer VisualTrack.",
+        summary: "One Typography Track: independently placed and timed text items on a shared Timeline, lowered to one addressable TypographyTrackProgram and one peer VisualTrack.",
         appearance: "Text alone on an otherwise empty Canvas: the glyphs, plus whatever Paint the Style puts around them — fills, outlines, glows, shadows and rounded, bordered, optionally tailed boxes drawn behind the frame, paragraph, line, run, word or grapheme. Each item holds its own region of the Canvas: a Point item is one unwrapped block that hugs its text and hangs off a single coordinate by its inline and block anchors, an Area item flows and wraps inside a rectangle under its own alignment, columns, clipping and overflow, and a Path item strings the glyphs along a curve, on one side of it, turning with it or standing upright. Items switch on and off at their own frame windows and overlap in the stacking order their Styles declare, so titles, labels and captions can occupy different corners at once and outlast or outlive one another. While an item is on screen it plays its Motion: the whole block translating, scaling, rotating, skewing, fading, blurring, recoloring or wiping open from an edge, and its paragraphs, lines, runs, words or graphemes arriving one behind another in a staggered run.",
         preview: previewImage("Track.png"),
         attributes: [
@@ -475,7 +477,7 @@ export const typographyTrackMarkupSurfaces = [
           { name: "track", type: compositionTypes.visualTrack,
             summary: "The rendered text, an ordinary peer VisualTrack." },
         ],
-        example: `<text:Track id="titles" semantic={speech.semantic}>
+        example: `<text:Track id="titles" timeline={speech.timeline}>
   <text:Area id="title" placement={title-frame} style={title-style} during="program">
     EDIT MEANING, NOT TIMELINES
   </text:Area>
@@ -514,7 +516,7 @@ export const typographyTrackMarkupSurfaces = [
           { name: "track", type: compositionTypes.visualTrack,
             summary: "The masked picture, an ordinary peer VisualTrack." },
         ],
-        example: `<text:Mask id="masked-titles" semantic={speech.semantic} text={mask-shape.program} material={material}/>`,
+        example: `<text:Mask id="masked-titles" timeline={speech.timeline} text={mask-shape.program} material={material}/>`,
         notes: [
           "A Mask is written empty and accepts no children.",
           "The material must be a still Surface; a timed material is refused and materializes through an independent package.",
@@ -529,7 +531,7 @@ export const typographyTrackManifest: ModuleManifest = {
   format: "hypit.module@1",
   name: typographyTrackModuleRef.name,
   version: typographyTrackModuleRef.version,
-  dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],
+  dependencies: [narrativeDependency, timelineDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],
   types: [
     { name: typographyTrackTypes.style.name },
     { name: typographyTrackTypes.motion.name },
@@ -548,9 +550,9 @@ export const typographyTrackManifest: ModuleManifest = {
     { name: typographyTrackProducers.bindArea.name, inputs: [{ name: "frame", type: spatialTypes.frame }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },
     { name: typographyTrackProducers.bindPath.name, inputs: [{ name: "path", type: spatialTypes.path }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },
     { name: typographyTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },
-    { name: typographyTrackProducers.appendItem.name, inputs: [{ name: "set", type: typographyTrackTypes.set }, { name: "header", type: typographyTrackTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "placement", type: typographyTrackTypes.placement }, { name: "spec", type: typographyTrackTypes.itemSpec }, { name: "style", type: typographyTrackTypes.style }, { name: "motion", type: typographyTrackTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },
+    { name: typographyTrackProducers.appendItem.name, inputs: [{ name: "set", type: typographyTrackTypes.set }, { name: "header", type: typographyTrackTypes.header }, { name: "timeline", type: timelineTypes.track }, { name: "placement", type: typographyTrackTypes.placement }, { name: "spec", type: typographyTrackTypes.itemSpec }, { name: "style", type: typographyTrackTypes.style }, { name: "motion", type: typographyTrackTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },
     { name: typographyTrackProducers.finalize.name, inputs: [{ name: "header", type: typographyTrackTypes.header }, { name: "set", type: typographyTrackTypes.set }], outputs: [{ name: "program", type: typographyTrackTypes.program }], needs: [] },
-    { name: typographyTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: typographyTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
-    { name: typographyTrackProducers.renderMask.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: typographyTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: typographyTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+    { name: typographyTrackProducers.render.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: typographyTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+    { name: typographyTrackProducers.renderMask.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: typographyTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: typographyTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
   ],
 };