@hypit/hypit 0.1.4 → 0.1.5

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: [] },
   ],
 };

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

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import {
   assertSpatialFrame,
   assertSpatialPath,
@@ -304,7 +304,7 @@ function append(
 export function appendProjectedTextItem(
   set: TypographyTrackSet,
   header: TypographyTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   placement: TextPlacement,
   spec: TextItemSpec,
   style: TextStyle,
@@ -312,7 +312,7 @@ export function appendProjectedTextItem(
   window: ProjectedWindow,
 ): TypographyTrackSet {
   assertTextPlacement(placement);
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
   return append(set, header, spec, style, motion, placement.geometry, window);
 }
 
@@ -332,18 +332,18 @@ export function sealTypographyTrackProgram(value: TypographyTrackProgram): Typog
   return programContent(value);
 }
 
-export function assertTypographyTrackProgramIdentity(program: TypographyTrackProgram, space: ProgramSpace): void {
-  assertProgramSpaceIdentity(space);
+export function assertTypographyTrackProgramIdentity(program: TypographyTrackProgram, timeline: Timeline): void {
+  assertProgramSpaceIdentity(timeline);
   nonEmpty(program.id, "TypographyTrackProgram id");
   if (program.items.length === 0) throw new Error("TypographyTrackProgram has no Items.");
-  const total = programSpaceFrameCount(space);
+  const total = programSpaceFrameCount(timeline);
   const ids = new Set<string>();
   for (const item of program.items) {
     nonEmpty(item.id, "Text Item id");
     if (ids.has(item.id)) throw new Error(`TypographyTrackProgram repeats ${item.id}.`);
     ids.add(item.id);
     if (item.span.startFrame < 0 || item.span.endFrameExclusive <= item.span.startFrame || item.span.endFrameExclusive > total) {
-      throw new Error(`${item.id} is outside ProgramSpace.`);
+      throw new Error(`${item.id} is outside Timeline.`);
     }
     assertGeometry(item.geometry);
     assertDocument(item.document, `${item.id} document`);
@@ -556,10 +556,10 @@ function elements(item: TextItem): VisualElement[] {
   return [root, motion, terminalTextElement(item, "motion", 2)];
 }
 
-export function renderTypographyTrack(space: ProgramSpace, program: TypographyTrackProgram): VisualTrack {
-  assertTypographyTrackProgramIdentity(program, space);
+export function renderTypographyTrack(timeline: Timeline, program: TypographyTrackProgram): VisualTrack {
+  assertTypographyTrackProgramIdentity(program, timeline);
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: program.id,
     presents: program.items.map((item) => ({
@@ -569,24 +569,24 @@ export function renderTypographyTrack(space: ProgramSpace, program: TypographyTr
       elements: elements(item),
     })),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }
 
 export function renderTextMaskTrack(
-  space: ProgramSpace,
+  timeline: Timeline,
   program: TypographyTrackProgram,
   material: CompositableSurfaceRef,
   spec: TextMaskSpec,
 ): VisualTrack {
-  assertTypographyTrackProgramIdentity(program, space);
+  assertTypographyTrackProgramIdentity(program, timeline);
   assertCompositableSurfaceRef(material);
   assertTextMaskSpec(spec);
   if (material.timing.kind !== "still") {
     throw new Error("Official Text Mask requires one explicit still material Surface; timed materials use an independent package.");
   }
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: spec.id,
     presents: program.items.map((item) => {
@@ -617,6 +617,6 @@ export function renderTextMaskTrack(
       };
     }),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }

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

@@ -1,5 +1,6 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
+
 import { compositionTypes } from "@hypit/composition";
 import type {
   VisualColorPaint,
@@ -649,7 +650,7 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
     }
     const append = `text:set:append:${String(index + 1).padStart(4, "0")}`;
     const common = {
-      set: operation(current), header: input("header"), space: input("space"), placement: operation(bind),
+      set: operation(current), header: input("header"), timeline: input("timeline"), placement: operation(bind),
       spec: item.contentName === undefined ? input(item.specName) : operation(materialized),
       style: input(item.styleName), motion: input(item.motionName), window: input(item.windowName),
     };
@@ -658,10 +659,10 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
   }
   operations.push(
     { id: "text:finalize", producer: typographyTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },
-    { id: "text:render", producer: typographyTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
+    { id: "text:render", producer: typographyTrackProducers.render, inputs: { timeline: input("timeline"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
   );
   const inputEntries = [
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "header", type: typographyTrackTypes.header },
     ...items.flatMap((item) => [
       { name: item.geometryName, type: item.placementKind === "point" ? spatialTypes.point : item.placementKind === "area" ? spatialTypes.frame : spatialTypes.path },
@@ -688,10 +689,9 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
 }
 
 export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space"], ["id"]);
+  allowed(element, ["id", "timeline"], ["id"]);
   const id = text(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const headerId = `${id}.__header`;
   const records: SurfaceRecordDraft[] = [{
     id: headerId, type: typographyTrackTypes.header,
@@ -699,8 +699,8 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
   }];
   const defaultMotionId = `${id}.__still-motion`;
   records.push({ id: defaultMotionId, type: typographyTrackTypes.motion, value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range });
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
-  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
   const items: Array<FragmentItem & {
     readonly geometry: SurfaceResolvedReference;
     readonly style: SurfaceResolvedReference;
@@ -731,7 +731,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
       "id", "content", "placement", "style", "motion", ...temporalWindowAttributeNames,
     ], ["id", "placement", "style"]);
     const itemId = text(child, "id");
-    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, space: time.space, resolveReference });
+    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, resolveReference });
     records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
     const placementKind = form.toLowerCase() as "point" | "area" | "path";
     const geometry = reference(child.attributes.placement, `${child.name}.placement`, placementKind === "point" ? spatialTypes.point : placementKind === "area" ? spatialTypes.frame : spatialTypes.path, resolveReference);
@@ -777,7 +777,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
     components: [...temporalComponents, {
       id, fragment: fragment.id,
       inputs: {
-        space: time.space.ref, header: { kind: "record", id: headerId },
+        timeline: context.timeline.ref, header: { kind: "record", id: headerId },
         ...Object.fromEntries(items.flatMap((item) => [
           [item.geometryName, item.geometry.ref], [item.specName, { kind: "record" as const, id: item.specId }],
           [item.windowName, item.window],
@@ -794,7 +794,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
 
 function createMaskFragment(id: string): GraphFragment {
   const inputs = [
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "program", type: typographyTrackTypes.program },
     { name: "material", type: mediaTypes.compositableSurface },
     { name: "spec", type: typographyTrackTypes.maskSpec },
@@ -804,7 +804,7 @@ function createMaskFragment(id: string): GraphFragment {
     operations: [
       {
         id: "text-mask:render", producer: typographyTrackProducers.renderMask,
-        inputs: { space: input("space"), program: input("program"), material: input("material"), spec: input("spec") },
+        inputs: { timeline: input("timeline"), program: input("program"), material: input("material"), spec: input("spec") },
         result: { kind: "output", name: "track" },
       },
     ],
@@ -815,11 +815,10 @@ function createMaskFragment(id: string): GraphFragment {
 }
 
 export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space", "text", "material", "mode", "fit"], ["id", "text", "material"]);
+  allowed(element, ["id", "timeline", "text", "material", "mode", "fit"], ["id", "text", "material"]);
   empty(element);
   const id = text(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const program = reference(element.attributes.text, `${element.name}.text`, typographyTrackTypes.program, resolveReference);
   const material = reference(element.attributes.material, `${element.name}.material`, mediaTypes.compositableSurface, resolveReference);
   const specId = `${id}.__spec`;
@@ -831,12 +830,12 @@ export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element,
   const fragment = createMaskFragment(id);
   return {
     records: [{ id: specId, type: typographyTrackTypes.maskSpec, value: { kind: "inline", value: spec }, range: element.range }],
-    components: [...time.components, {
+    components: [{
       id, fragment: fragment.id,
-      inputs: { space: time.space.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
+      inputs: { timeline: context.timeline.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
       outputs: { track: `${id}.track` }, range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
     exports: [`${id}.track`],
   };
 };

package/packages/video-cli/README.md

@@ -46,7 +46,10 @@ Chinese speech containing English names; the requested language selects the reco
 model, independently of the eventual caption font or script's simplified/traditional characters.
 
 `transcribe` uses the Profile's `whisperx-alignment` Endpoint (after
-extracting 16 kHz mono speech audio with ffmpeg). `measure` counts a Segment's pronunciation units at a
+extracting 16 kHz mono speech audio with ffmpeg). Direct invocation forwards the Provider's progress
+and diagnostic callbacks; the CLI reports phase changes while waiting, with JSON progress on the
+separate progress stream when supplied. Immediate invocation has no durable remote task receipt and
+does not become resumable merely because it reports progress. `measure` counts a Segment's pronunciation units at a
 delivery policy and prints estimated seconds, the resolved rate, padding and rounding. Choose the
 literal `duration` from that estimate and the intended performance. `measure` opens no Profile and
 spends nothing. It accepts `--pace slow|normal|fast` or `--rate <units/s>`; JSON includes the resolved

package/packages/video-cli/package.json

@@ -20,6 +20,7 @@
     "@hypit/markup": "workspace:*",
     "@hypit/model-kit": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/provider-hypihub": "workspace:*",
     "@hypit/runtime": "workspace:*",
@@ -32,6 +33,6 @@
     "@hypit/whisperx": "workspace:*",
     "@hypit/workspace-fs-node": "workspace:*",
     "@hypit/yt-dlp": "workspace:*",
-    "sharp": "0.35.3"
+    "sharp": "0.35.4"
   }
 }

package/packages/video-cli/src/creation.ts

@@ -2,7 +2,8 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-import { findRuntimeProfile, loadDiscoveredSourcePackages, resolveProjectRoot } from "@hypit/cli";
+import { loadDiscoveredSourcePackages } from "@hypit/cli";
+import { findRuntimeProfile, resolveProjectRoot } from "@hypit/project-context-node";
 import type { CliIo } from "@hypit/cli";
 import { MemoryResourceStore } from "@hypit/driver-node";
 import {
@@ -14,7 +15,7 @@ import {
 } from "@hypit/estimate";
 import type { CanonicalValue, CapabilityRef, Need, StoredValue } from "@hypit/protocol";
 import type { ResourceStore } from "@hypit/runtime";
-import type { RuntimeHostCapabilityProvider, RuntimeHostProviderQuery } from "@hypit/runtime-host-node";
+import type { RuntimeHostCapabilityProvider, RuntimeHostProviderQuery, RuntimeInvocationObservation } from "@hypit/runtime-host-node";
 import { sealSpeechEvidenceAudio } from "@hypit/speech";
 import { speechEvidenceTypes } from "@hypit/speech-evidence";
 import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
@@ -32,7 +33,7 @@ export type CreationCommand = typeof creationCommands[number];
 /** The slice of the Runtime host these commands use; tests hand in a fake. */
 export type CreationHost = {
   providers(requests: readonly RuntimeHostProviderQuery[]): Promise<readonly RuntimeHostCapabilityProvider[]>;
-  invoke(need: Need, resources: ResourceStore): Promise<{ readonly value: StoredValue }>;
+  invoke(need: Need, resources: ResourceStore, observation?: RuntimeInvocationObservation): Promise<{ readonly value: StoredValue }>;
 };
 
 export type CreationEnvironment = {
@@ -297,7 +298,16 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
   };
   const provider = await selectedProvider(host, need, profile);
   if (!parsed.json) io.write(`Transcribing through ${providerLine(provider)}\n`);
-  const fulfillment = await host.invoke(need, resources);
+  const report = parsed.json ? io.writeProgress : io.writeProgress ?? io.write;
+  let previousPhase: string | undefined;
+  const fulfillment = await host.invoke(need, resources, {
+    reportProgress: async (progress) => {
+      if (progress.phase === previousPhase) return;
+      previousPhase = progress.phase;
+      report?.(`  · ${progress.phase}\n`);
+    },
+    reportDiagnostic: async (diagnostic) => { report?.(`  · ${diagnostic.message}\n`); },
+  });
   assert(fulfillment.value.kind === "inline", "the transcript came back by reference");
   const passages = passagesInSeconds(fulfillment.value.value as unknown as AlignedTranscriptEvidence);
   const words = passages.reduce((total, passage) => total + passage.words.length, 0);

package/packages/video-cli/src/index.ts

@@ -28,7 +28,7 @@ export { runCaptureCli, writeCaptureHelp } from "./capture.js";
 export { listPackages, listSurfaces, runVocabularyCli, visualSchema, writeVocabularyHelp } from "./vocabulary.js";
 export type { PackageListing, SurfaceListing } from "./vocabulary.js";
 /** The project's selected Runtime Profile, read the way `hypit` reads it, for tools that run beside the CLI. */
-export { findRuntimeProfile } from "@hypit/cli";
+export { findRuntimeProfile } from "@hypit/project-context-node";
 
 export function runVideoCli(
   argv: readonly string[],