@hypit/hypit 0.1.4 → 0.1.6

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

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { artifactTypes } from "@hypit/artifact";
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
@@ -14,7 +15,7 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
 export const stillMediaTrackFragment = sealGraphFragment({
   inputs: [
     { name: "header", type: mediaTrackTypes.header },
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "canvas", type: spatialTypes.canvas },
     { name: "source", type: artifactTypes.blob },
     { name: "extent", type: spatialTypes.extent },
@@ -32,14 +33,14 @@ export const stillMediaTrackFragment = sealGraphFragment({
     { id: "set", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
     { id: "sounds", producer: mediaTrackProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" } },
     { id: "append", producer: mediaTrackProducers.appendItem, inputs: {
-      set: operation("set"), header: input("header"), space: input("space"), canvas: input("canvas"), layers: operation("sample"),
+      set: operation("set"), header: input("header"), timeline: input("timeline"), canvas: input("canvas"), layers: operation("sample"),
       frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: input("window"),
     }, result: { kind: "output", name: "set" } },
     { id: "finalize", producer: mediaTrackProducers.finalize, inputs: {
-      set: operation("append"), header: input("header"), space: input("space"),
+      set: operation("append"), header: input("header"), timeline: input("timeline"),
     }, result: { kind: "output", name: "program" } },
     { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: {
-      space: input("space"), program: operation("finalize"),
+      timeline: input("timeline"), program: operation("finalize"),
     }, result: { kind: "output", name: "track" } },
   ],
   exports: [
@@ -49,9 +50,9 @@ export const stillMediaTrackFragment = sealGraphFragment({
 });
 
 export const renderMediaTrackFragment = sealGraphFragment({
-  inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }],
+  inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }],
   operations: [
-    { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { space: input("space"), program: input("program") }, result: { kind: "output", name: "track" } },
+    { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: input("program") }, result: { kind: "output", name: "track" } },
   ],
   exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("visual") }],
 });

package/packages/media-track/src/index.ts

@@ -1,6 +1,7 @@
 export { mediaTrackComponent } from "./component.js";
 export {
   decodeMediaFit,
+  decodeMediaItemSpec,
   decodeMediaFramePaint,
   decodeMediaMotion,
   decodeMediaPresentation,
@@ -46,7 +47,6 @@ export {
 } from "./sounds.js";
 export { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaItemSpec, assertMediaTrackHeader, assertMediaTrackProgram, assertMediaTrackProgramIdentity, assertMediaTrackSet, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaTrackHeader, sealMediaTrackProgram } from "./program.js";
 export { resolveVisualSampling } from "./sampling.js";
-export { appendMediaPerformance } from "./performance.js";
 export { decodeMediaSamplingKeyframe, decodeMediaTrackSurface } from "./surface.js";
 export {
   appendMediaSequenceMember,
@@ -63,3 +63,5 @@ export {
   sequenceMemberHandoffAnimation,
 } from "./sequence.js";
 export type * from "./types.js";
+
+export { mediaAppearanceDefaults } from "./author.js";

package/packages/media-track/src/lower.ts

@@ -1,10 +1,10 @@
+import type { Timeline } from "@hypit/timeline";
 import type {
   VisualAnimation,
   VisualElement,
   VisualStyleDeclaration,
   VisualTimedSampling,
 } from "@hypit/composition";
-import type { ProgramSpace } from "@hypit/program-space";
 import { fitContent } from "@hypit/spatial";
 import type { SpatialFrame, SpatialPath } from "@hypit/spatial";
 
@@ -133,7 +133,7 @@ function sampleElements(
   item: MediaItemProgram,
   parent: string,
   order: { value: number },
-  space: ProgramSpace,
+  timeline: Timeline,
   samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
   samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
 ): VisualElement[] {
@@ -209,7 +209,7 @@ function sampleElements(
     }];
   }
   const sampling = samplingOverrides[layer.id] ?? layer.sampling ?? resolveVisualSampling({
-      space,
+      timeline,
       sourceFrameRate: sourceTiming.frameRate,
       sourceFrameCount: sourceTiming.frameCount,
       targetFrameCount: durationFrames,
@@ -244,12 +244,12 @@ function layerElements(
   item: MediaItemProgram,
   parent: string,
   order: { value: number },
-  space: ProgramSpace,
+  timeline: Timeline,
   samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
   samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
 ): VisualElement[] {
   if (layer.kind === "sample") {
-    return sampleElements(layer, item, parent, order, space, samplingOverrides, samplingAnimationOverrides);
+    return sampleElements(layer, item, parent, order, timeline, samplingOverrides, samplingAnimationOverrides);
   }
   return [{
     id: layer.id,
@@ -271,7 +271,7 @@ function layerElements(
 /** Lower one independent Item through the fixed wrapper stack from the Media spec. */
 export function lowerMediaItemElements(
   item: MediaItemProgram,
-  space: ProgramSpace,
+  timeline: Timeline,
   options: {
     readonly includeHandoffWrapper?: boolean;
     readonly handoffAnimation?: VisualAnimation;
@@ -326,7 +326,7 @@ export function lowerMediaItemElements(
       item,
       frame,
       order,
-      space,
+      timeline,
       options.samplingOverrides ?? {},
       options.samplingAnimationOverrides ?? {},
     ));

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

@@ -1,3 +1,4 @@
+import type { Timeline } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { visualTimedSamplingSchema } from "@hypit/composition";
 import { readFile } from "node:fs/promises";
@@ -10,9 +11,9 @@ import {
   mediaTypes,
 } from "@hypit/media";
 import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
 import {
   contentFitSchema,
   intrinsicExtentSchema,
@@ -48,7 +49,6 @@ export const mediaTrackTypes = {
 } satisfies Record<string, TypeRef>;
 
 export const mediaTrackProducers = {
-  appendPerformance: { module: mediaTrackModuleRef, name: "append-media-performance" },
   createLayers: { module: mediaTrackModuleRef, name: "create-media-layer-set" },
   appendPaintLayer: { module: mediaTrackModuleRef, name: "append-media-paint-layer" },
   appendStillLayer: { module: mediaTrackModuleRef, name: "append-still-media-layer" },
@@ -256,18 +256,18 @@ export const mediaTrackHeaderSchema: ValueSchema = object({
 
 const itemInputs = [
   { name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
-  { name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
+  { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
   { name: "layers", type: mediaTrackTypes.layerSet },
   { name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.itemSpec },
   { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "window", type: temporalTypes.window },
 ] as const;
 const memberInputs = [
-  { name: "members", type: mediaTrackTypes.memberSet }, { name: "space", type: programSpaceTypes.programSpace }, { name: "layers", type: mediaTrackTypes.layerSet },
+  { name: "members", type: mediaTrackTypes.memberSet }, { name: "timeline", type: timelineTypes.track }, { name: "layers", type: mediaTrackTypes.layerSet },
   { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "activation", type: temporalTypes.instant },
 ] as const;
 const sequenceInputs = [
   { name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
-  { name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
+  { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
   { name: "members", type: mediaTrackTypes.memberSet },
   { name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.sequenceSpec },
   { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "terminal", type: temporalTypes.instant },
@@ -368,7 +368,7 @@ export const mediaTrackMarkupSurfaces = [{
       temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, mediaTrackTypes.program,
       compositionTypes.visualTrack, compositionTypes.audioTrack],
     vocabulary: {
-      summary: "Show the semantic performance, place independent media Items, and compose replacement Sequences on a shared film time axis and Canvas. Publishes a VisualTrack and, when audio is authored, an AudioTrack.",
+      summary: "Show the timeline performance, place independent media Items, and compose replacement Sequences on a shared film time axis and Canvas. Publishes a VisualTrack and, when audio is authored, an AudioTrack.",
       appearance: "Pictures and layered compositions occupy authored Frames on the Canvas. Each source is scaled and aligned inside its Frame's border and padding; a contain fit can leave space, while cover can crop. Paint and sampled Layers draw in Source order under a shared rectangular, rounded or Path clip, with optional border and shadows. Lifecycle motion moves the framed unit; Sampling pans, zooms or rotates the picture inside it. Each Item has an independent window. A Sequence shares one outer Frame while Members replace its contents through cut, crossfade, push, wipe, cover or page-turn Handoffs. Source playback determines whether moving content covers the whole assigned span. Absolute stack order decides which overlapping unit draws in front.",
       preview: previewImage("Track.png"),
       attributes: [
@@ -379,23 +379,6 @@ export const mediaTrackMarkupSurfaces = [{
           summary: "Chooses the Canvas every Frame on this Track is measured inside." },
       ],
       children: [
-        { tag: "Performance", cardinality: "many",
-          summary: "Shows the enclosing Track's semantic performance during a chosen interval, preserving each Take's original source position under one frame and continuous motion. Accepts Sampling and Sound children.",
-          attributes: [
-            { name: "id", kind: "identifier", required: false,
-              summary: "Names this presentation; otherwise its identity follows the shared Item/Performance order." },
-            { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
-              summary: "Places the performance picture on the Canvas." },
-            { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType],
-              summary: "Uses the Media fitting, picture styling, frame paint, clipping, border and shadow properties. Source time follows the semantic performance.",
-              recipe: appearanceRecipeProperties.filter(property => !["playback", "trim-start", "trim-end"].includes(property.name)) },
-            { name: "motion", kind: "reference", required: false, accepts: [svsRecipeType],
-              summary: "Moves the whole framed presentation over its Window, across Take boundaries.",
-              recipe: motionRecipeProperties },
-            { name: "clip", kind: "reference", required: false, accepts: [spatialTypes.path],
-              summary: "Clips the presentation to an authored Path." },
-            ...temporalWindowAttributeVocabulary,
-          ] },
         { tag: "Item", cardinality: "many",
           summary: "One independently timed picture on its own Frame, from a direct source or ordered Paint and Layer children, carrying its own Sampling and Sound children.",
           attributes: [
@@ -458,19 +441,18 @@ export const mediaTrackMarkupSurfaces = [{
       example: `<pipeline:Normalize id="cutaway-bags" source={bags-take.video}
   video="primary-moving" audio="none" span-authority="video" clock={clock}/>
 
-<media-track:Track id="cutaways" semantic={speech.semantic} canvas={vertical}>
-  <media-track:Performance during="program" frame={full} appearance={recipes.media.presenter}/>
+<media-track:Track id="cutaways" timeline={speech.timeline} canvas={vertical}>
+  <media-track:Item media={prepared.media} during="program" frame={full} appearance={recipes.media.clip}/>
   <media-track:Item id="bags" media={cutaway-bags.media} during={story.selection.bags}
     frame={full} appearance={recipes.media.cutaway} motion={recipes.motion.cut}/>
 </media-track:Track>`,
       notes: [
-        "A Track requires at least one Performance, Item or Sequence and accepts no text content.",
-        "Performance and Item use one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`. Bind `selection`, `segment` and/or `moment` only when the start/end expressions use them; different endpoints can use different bindings.",
-        "Performance uses the Track's existing semantic input. `during=\"program\"` shows all its prepared Takes in order; a Segment or Selection shows that interval at the corresponding source positions. Speech Track.audio independently supplies the original sound. Sampling pans, zooms or rotates the fitted picture across the whole selected Window.",
+        "A Track requires at least one Item or Sequence and accepts no text content.",
+        "Item use one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`. Bind `selection`, `segment` and/or `moment` only when the start/end expressions use them; different endpoints can use different bindings.",
         "A point expression is `program.start`, `program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.",
         "A unit that names a direct source names exactly one of `image`, `media` or `surface`; `extent` is required with `image` and refused otherwise.",
         "`audio-gain` is refused without selected source audio.",
-        "`clip` is refused on a Performance, Item or Sequence whose Recipe already states a clip.",
+        "`clip` is refused on a Item or Sequence whose Recipe already states a clip.",
         "An `appearance` or `motion` Recipe is refused when it carries a property outside its own set.",
         "`playback`, `trim-start` and `trim-end` are refused on durationless still material, and `trim-start` and `trim-end` are written together or not at all.",
         "An `enter` or an `exit` operator requires its own `enter-frames` or `exit-frames`.",
@@ -575,8 +557,7 @@ export const mediaTrackManifest: ModuleManifest = {
     artifactDependency,
     mediaDependency,
     narrativeDependency,
-    programSpaceDependency,
-    semanticTrackDependency,
+    timelineDependency,
     temporalDependency,
     spatialDependency,
     compositionDependency,
@@ -606,18 +587,15 @@ export const mediaTrackManifest: ModuleManifest = {
     { name: mediaTrackProducers.createSounds.name, inputs: [], outputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }], needs: [] },
     { name: mediaTrackProducers.appendSound.name, inputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }, { name: "source", type: mediaTypes.synchronized }, { name: "spec", type: mediaTrackTypes.soundSpec }], outputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }], needs: [] },
     { name: mediaTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
-    { name: mediaTrackProducers.appendPerformance.name, inputs: [...itemInputs,
-      { name: "semantic", type: semanticTrackTypes.track }, { name: "fit", type: spatialTypes.fit },
-      { name: "sampleSpec", type: mediaTrackTypes.sampleLayerSpec }], outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
     { name: mediaTrackProducers.appendItem.name, inputs: itemInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
     { name: mediaTrackProducers.bindItemClipPath.name, inputs: [{ name: "spec", type: mediaTrackTypes.itemSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: mediaTrackTypes.itemSpec }], needs: [] },
     { name: mediaTrackProducers.bindSequenceClipPath.name, inputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }], needs: [] },
     { name: mediaTrackProducers.createMembers.name, inputs: [], outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
     { name: mediaTrackProducers.appendMember.name, inputs: memberInputs, outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
     { name: mediaTrackProducers.appendSequence.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
-    { name: mediaTrackProducers.finalize.name, inputs: [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header }, { name: "space", type: programSpaceTypes.programSpace }], outputs: [{ name: "program", type: mediaTrackTypes.program }], needs: [] },
-    { name: mediaTrackProducers.projectVisual.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
-    { name: mediaTrackProducers.projectAudio.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
+    { name: mediaTrackProducers.finalize.name, inputs: [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header }, { name: "timeline", type: timelineTypes.track }], outputs: [{ name: "program", type: mediaTrackTypes.program }], needs: [] },
+    { name: mediaTrackProducers.projectVisual.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+    { name: mediaTrackProducers.projectAudio.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
   ],
 };
 

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

@@ -1,3 +1,4 @@
+import type { Timeline } from "@hypit/timeline";
 import {
   assertAudioTrackIdentity,
   assertVisualTrackIdentity,
@@ -5,13 +6,7 @@ import {
   sealVisualTrack,
 } from "@hypit/composition";
 import type { AudioClip, AudioTrack, VisualTrack } from "@hypit/composition";
-import {
-  assertProgramSpaceIdentity,
-  programFrameSampleBoundary,
-  programSpaceFrameCount,
-  programSpaceSampleFrames,
-} from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
+import { assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceFrameCount, programSpaceSampleFrames } from "@hypit/program-space";
 import { canonicalize, isResourceId } from "@hypit/protocol";
 import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
 import type { CanvasSpace } from "@hypit/spatial";
@@ -125,7 +120,7 @@ export function assertMediaTrackSet(value: MediaTrackSet): void {
 function realizedItems(
   set: MediaTrackSet,
   header: MediaTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   canvas: CanvasSpace,
   layers: MediaLayerSet,
   frame: MediaItemProgram["frame"],
@@ -135,13 +130,13 @@ function realizedItems(
 ): MediaTrackSet {
   assertMediaTrackSet(set);
   assertMediaTrackHeader(header);
-  assertProgramSpaceIdentity(space);
+  assertProgramSpaceIdentity(timeline);
   assertCanvasSpace(canvas);
   assertMediaLayerSet(layers);
   assert(layers.layers.length > 0, `Media Item ${spec.id} requires at least one layer.`);
   assertSpatialFrame(frame);
   assertMediaItemSpec(spec);
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
   assertMediaSoundSet(sounds);
   assert(!sounds.sounds.some((sound) => sound.trigger.kind === "handoff"),
     `Media Item ${spec.id} cannot own a Handoff sound.`);
@@ -177,7 +172,7 @@ function realizedItems(
 export function appendMediaItem(
   set: MediaTrackSet,
   header: MediaTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   canvas: CanvasSpace,
   layers: MediaLayerSet,
   frame: MediaItemProgram["frame"],
@@ -185,29 +180,29 @@ export function appendMediaItem(
   sounds: MediaSoundSet,
   window: ProjectedWindow,
 ): MediaTrackSet {
-  return realizedItems(set, header, space, canvas, layers, frame, spec, sounds, window);
+  return realizedItems(set, header, timeline, canvas, layers, frame, spec, sounds, window);
 }
 
-function assertSampleLayerForSpace(layer: MediaSampleLayerProgram, space: ProgramSpace, label: string): void {
+function assertSampleLayerForSpace(layer: MediaSampleLayerProgram, timeline: Timeline, label: string): void {
   assertMediaVisualSource(layer.source, `${label}.source`);
   const timing = layer.source.kind === "timed" ? { frameRate: layer.source.frameRate, frameCount: layer.source.frameCount }
     : layer.source.kind === "surface" && layer.source.surface.timing.kind === "frames"
       ? layer.source.surface.timing : undefined;
   if (timing === undefined) return;
-  assert(timing.frameRate.numerator === space.frameRate.numerator
-    && timing.frameRate.denominator === space.frameRate.denominator,
-  `${label} is not normalized to ProgramSpace frame rate.`);
+  assert(timing.frameRate.numerator === timeline.frameRate.numerator
+    && timing.frameRate.denominator === timeline.frameRate.denominator,
+  `${label} is not normalized to Timeline frame rate.`);
   if (layer.trim !== undefined) assertMediaVisualTrim(layer.trim, timing.frameCount, `${label}.trim`);
   assert(layer.occupancy !== undefined, `${label} requires occupancy.`);
   assertMediaVisualOccupancy(layer.occupancy, `${label}.occupancy`);
 }
 
-function assertItem(item: MediaItemProgram, space: ProgramSpace, label: string): void {
+function assertItem(item: MediaItemProgram, timeline: Timeline, label: string): void {
   assertMediaIdentity(item.id, `${label}.id`);
   assertMediaIdentity(item.subjectId, `${label}.subjectId`);
   assert(Number.isSafeInteger(item.span.startFrame) && Number.isSafeInteger(item.span.endFrameExclusive)
     && item.span.startFrame >= 0 && item.span.endFrameExclusive > item.span.startFrame
-    && item.span.endFrameExclusive <= programSpaceFrameCount(space), `${label}.span is invalid.`);
+    && item.span.endFrameExclusive <= programSpaceFrameCount(timeline), `${label}.span is invalid.`);
   assertSpatialFrame(item.frame);
   assertMediaFramePresentation(item.presentation, `${label}.presentation`);
   assertMediaLifecycleMotion(item.motion, item.span.endFrameExclusive - item.span.startFrame, `${label}.motion`);
@@ -217,7 +212,7 @@ function assertItem(item: MediaItemProgram, space: ProgramSpace, label: string):
   assert(item.layers.length > 0, `${label} requires layers.`);
   const layerSet: MediaLayerSet = { layers: item.layers };
   assertMediaLayerSet(layerSet);
-  for (const layer of item.layers) if (layer.kind === "sample") assertSampleLayerForSpace(layer, space, `${label}.${layer.id}`);
+  for (const layer of item.layers) if (layer.kind === "sample") assertSampleLayerForSpace(layer, timeline, `${label}.${layer.id}`);
   if (item.sourceAudio !== undefined) {
     const selected = item.layers.find((layer) => layer.id === item.sourceAudio!.fromLayer);
     assert(selected?.kind === "sample" && selected.source.kind === "timed" && selected.source.audio !== undefined,
@@ -230,7 +225,7 @@ function assertItem(item: MediaItemProgram, space: ProgramSpace, label: string):
 function appendMediaSequenceAtFrame(
   set: MediaTrackSet,
   header: MediaTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   canvas: CanvasSpace,
   members: MediaSequenceMemberSet,
   frame: MediaSequenceProgram["frame"],
@@ -241,7 +236,7 @@ function appendMediaSequenceAtFrame(
   assertMediaTrackSet(set);
   assertMediaSequenceMemberSet(members);
   assertMediaSequenceSpec(spec);
-  const sequence = resolveMediaSequence(header, space, canvas, members, frame, spec, sounds, terminalFrame);
+  const sequence = resolveMediaSequence(header, timeline, canvas, members, frame, spec, sounds, terminalFrame);
   assert(!set.items.some((item) => item.id === sequence.id)
     && !set.sequences.some((item) => item.id === sequence.id),
   `Media Track ${header.id} already contains ${sequence.id}.`);
@@ -251,7 +246,7 @@ function appendMediaSequenceAtFrame(
 export function appendMediaSequence(
   set: MediaTrackSet,
   header: MediaTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   canvas: CanvasSpace,
   members: MediaSequenceMemberSet,
   frame: MediaSequenceProgram["frame"],
@@ -259,13 +254,13 @@ export function appendMediaSequence(
   sounds: MediaSoundSet,
   terminal: TemporalInstant,
 ): MediaTrackSet {
-  assertTemporalInstantFor(terminal, { subjectId: spec.id, space });
-  return appendMediaSequenceAtFrame(set, header, space, canvas, members, frame, spec, sounds, terminal.frame);
+  assertTemporalInstantFor(terminal, { subjectId: spec.id, space: timeline });
+  return appendMediaSequenceAtFrame(set, header, timeline, canvas, members, frame, spec, sounds, terminal.frame);
 }
 
-function assertSequence(sequence: MediaSequenceProgram, space: ProgramSpace, label: string): void {
+function assertSequence(sequence: MediaSequenceProgram, timeline: Timeline, label: string): void {
   assertMediaIdentity(sequence.id, `${label}.id`);
-  assert(sequence.span.startFrame >= 0 && sequence.span.endFrameExclusive <= programSpaceFrameCount(space)
+  assert(sequence.span.startFrame >= 0 && sequence.span.endFrameExclusive <= programSpaceFrameCount(timeline)
     && sequence.span.endFrameExclusive > sequence.span.startFrame
     && sequence.terminalFrame === sequence.span.endFrameExclusive, `${label}.span is invalid.`);
   assertSpatialFrame(sequence.frame);
@@ -288,7 +283,7 @@ function assertSequence(sequence: MediaSequenceProgram, space: ProgramSpace, lab
     const layerSet: MediaLayerSet = { layers: member.layers };
     assertMediaLayerSet(layerSet);
     for (const layer of member.layers) if (layer.kind === "sample") {
-      assertSampleLayerForSpace(layer, space, `${label}.members.${index}.${layer.id}`);
+      assertSampleLayerForSpace(layer, timeline, `${label}.members.${index}.${layer.id}`);
     }
     if (member.sourceAudio !== undefined) {
       const selected = member.layers.find((layer) => layer.id === member.sourceAudio!.fromLayer);
@@ -323,13 +318,13 @@ function normalizeProgram(value: MediaTrackProgram): MediaTrackProgram {
   };
 }
 
-export function sealMediaTrackProgram(value: MediaTrackProgram, space: ProgramSpace): MediaTrackProgram {
+export function sealMediaTrackProgram(value: MediaTrackProgram, timeline: Timeline): MediaTrackProgram {
   const normalized = normalizeProgram(value);
-  assertMediaTrackProgramIdentity(normalized, space);
+  assertMediaTrackProgramIdentity(normalized, timeline);
   return canonicalize(normalized) as unknown as MediaTrackProgram;
 }
 
-export function finalizeMediaTrack(set: MediaTrackSet, header: MediaTrackHeader, space: ProgramSpace): MediaTrackProgram {
+export function finalizeMediaTrack(set: MediaTrackSet, header: MediaTrackHeader, timeline: Timeline): MediaTrackProgram {
   assertMediaTrackSet(set);
   assertMediaTrackHeader(header);
   assert(set.items.length + set.sequences.length > 0, "Media Track requires at least one Item or Sequence.");
@@ -338,7 +333,7 @@ export function finalizeMediaTrack(set: MediaTrackSet, header: MediaTrackHeader,
     id: header.id,
     items: set.items,
     sequences: set.sequences,
-  }, space);
+  }, timeline);
 }
 
 export function assertMediaTrackProgram(value: MediaTrackProgram): void {
@@ -347,26 +342,26 @@ export function assertMediaTrackProgram(value: MediaTrackProgram): void {
     && value.items.length + value.sequences.length > 0, "MediaTrackProgram is empty.");
 }
 
-export function assertMediaTrackProgramIdentity(value: MediaTrackProgram, space: ProgramSpace): void {
+export function assertMediaTrackProgramIdentity(value: MediaTrackProgram, timeline: Timeline): void {
   assertMediaTrackProgram(value);
-  assertProgramSpaceIdentity(space);
+  assertProgramSpaceIdentity(timeline);
   const ids = new Set<string>();
   for (const item of value.items) {
     assert(!ids.has(item.id), `MediaTrackProgram repeats ${item.id}.`);
     ids.add(item.id);
-    assertItem(item, space, `Media Item ${item.id}`);
+    assertItem(item, timeline, `Media Item ${item.id}`);
   }
   for (const sequence of value.sequences) {
     assert(!ids.has(sequence.id), `MediaTrackProgram repeats ${sequence.id}.`);
     ids.add(sequence.id);
-    assertSequence(sequence, space, `Media Sequence ${sequence.id}`);
+    assertSequence(sequence, timeline, `Media Sequence ${sequence.id}`);
   }
 }
 
-export function projectMediaVisualTrack(space: ProgramSpace, program: MediaTrackProgram): VisualTrack {
-  assertMediaTrackProgramIdentity(program, space);
+export function projectMediaVisualTrack(timeline: Timeline, program: MediaTrackProgram): VisualTrack {
+  assertMediaTrackProgramIdentity(program, timeline);
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: program.id,
     presents: [
@@ -375,12 +370,12 @@ export function projectMediaVisualTrack(space: ProgramSpace, program: MediaTrack
       subjectId: item.subjectId,
       span: { ...item.span },
       stacking: { ...item.stacking },
-      elements: lowerMediaItemElements(item, space),
+      elements: lowerMediaItemElements(item, timeline),
       })),
-      ...program.sequences.flatMap((sequence) => lowerMediaSequencePresents(sequence, space)),
+      ...program.sequences.flatMap((sequence) => lowerMediaSequencePresents(sequence, timeline)),
     ],
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }
 
@@ -394,7 +389,7 @@ function sourceSampleBoundary(frame: number, frameCount: number, sampleFrames: n
 
 function sourceAudioClip(
   value: Pick<MediaItemProgram, "id" | "subjectId" | "span" | "layers" | "sourceAudio">,
-  space: ProgramSpace,
+  timeline: Timeline,
   fades: { readonly inSamples: number; readonly outSamples: number } = { inSamples: 0, outSamples: 0 },
 ): AudioClip | undefined {
   if (value.sourceAudio === undefined) return undefined;
@@ -409,8 +404,8 @@ function sourceAudioClip(
   const trim = layer.trim ?? { startFrame: 0, endFrameExclusive: source.frameCount };
   const sourceStart = sourceSampleBoundary(trim.startFrame, source.frameCount, audio.sampleFrames);
   const sourceEnd = sourceSampleBoundary(trim.endFrameExclusive, source.frameCount, audio.sampleFrames);
-  const targetWindowStart = programFrameSampleBoundary(space, value.span.startFrame, 48_000);
-  const targetWindowEnd = programFrameSampleBoundary(space, value.span.endFrameExclusive, 48_000);
+  const targetWindowStart = programFrameSampleBoundary(timeline, value.span.startFrame, 48_000);
+  const targetWindowEnd = programFrameSampleBoundary(timeline, value.span.endFrameExclusive, 48_000);
   const targetFrames = value.span.endFrameExclusive - value.span.startFrame;
   const sourceFrames = trim.endFrameExclusive - trim.startFrame;
   let targetStart = targetWindowStart;
@@ -423,10 +418,10 @@ function sourceAudioClip(
   if (layer.occupancy.mode === "once" || layer.occupancy.mode === "hold") {
     const playedFrames = Math.min(targetFrames, sourceFrames);
     if (layer.occupancy.align === "start") {
-      targetEnd = programFrameSampleBoundary(space, value.span.startFrame + playedFrames, 48_000);
+      targetEnd = programFrameSampleBoundary(timeline, value.span.startFrame + playedFrames, 48_000);
       clipSourceEnd = sourceSampleBoundary(trim.startFrame + playedFrames, source.frameCount, audio.sampleFrames);
     } else {
-      targetStart = programFrameSampleBoundary(space, value.span.endFrameExclusive - playedFrames, 48_000);
+      targetStart = programFrameSampleBoundary(timeline, value.span.endFrameExclusive - playedFrames, 48_000);
       clipSourceStart = sourceSampleBoundary(trim.endFrameExclusive - playedFrames, source.frameCount, audio.sampleFrames);
     }
   } else if (layer.occupancy.mode === "loop") {
@@ -466,12 +461,12 @@ function soundClip(
   source: MediaSoundSource,
   gain: number,
   point: number,
-  space: ProgramSpace,
+  timeline: Timeline,
 ): AudioClip {
-  const total = programSpaceSampleFrames(space, 48_000);
-  const targetStart = programFrameSampleBoundary(space, point, 48_000);
+  const total = programSpaceSampleFrames(timeline, 48_000);
+  const targetStart = programFrameSampleBoundary(timeline, point, 48_000);
   const audible = Math.min(source.sampleFrames, Math.max(0, total - targetStart));
-  assert(audible > 0, `Media sound ${id} begins outside ProgramSpace.`);
+  assert(audible > 0, `Media sound ${id} begins outside Timeline.`);
   return {
     id,
     artifact: structuredClone(source.artifact),
@@ -493,18 +488,18 @@ function soundClip(
 
 function edgeSoundClips(
   value: Pick<MediaItemProgram, "id" | "span" | "motion" | "sounds">,
-  space: ProgramSpace,
+  timeline: Timeline,
 ): AudioClip[] {
   return value.sounds.flatMap((sound) => {
     if (sound.trigger.kind === "handoff") return [];
     const point = sound.trigger.kind === "enter"
       ? value.span.startFrame
       : value.span.endFrameExclusive - (value.motion.exit?.durationFrames ?? 0);
-    return [soundClip(`${value.id}:${sound.id}`, sound.source, sound.gain, point, space)];
+    return [soundClip(`${value.id}:${sound.id}`, sound.source, sound.gain, point, timeline)];
   });
 }
 
-function sequenceAudioClips(sequence: MediaSequenceProgram, space: ProgramSpace): AudioClip[] {
+function sequenceAudioClips(sequence: MediaSequenceProgram, timeline: Timeline): AudioClip[] {
   const sourceClips = sequence.members.flatMap((member, index) => {
     if (member.sourceAudio === undefined) return [];
     const incoming = sequence.handoffs[index - 1];
@@ -515,12 +510,12 @@ function sequenceAudioClips(sequence: MediaSequenceProgram, space: ProgramSpace)
         ? outgoing.span.endFrameExclusive : member.logicalSpan.endFrameExclusive,
     };
     const fadeInSamples = incoming?.audio === "crossfade"
-      ? programFrameSampleBoundary(space, incoming.span.endFrameExclusive, 48_000)
-        - programFrameSampleBoundary(space, incoming.span.startFrame, 48_000)
+      ? programFrameSampleBoundary(timeline, incoming.span.endFrameExclusive, 48_000)
+        - programFrameSampleBoundary(timeline, incoming.span.startFrame, 48_000)
       : 0;
     const fadeOutSamples = outgoing?.audio === "crossfade"
-      ? programFrameSampleBoundary(space, outgoing.span.endFrameExclusive, 48_000)
-        - programFrameSampleBoundary(space, outgoing.span.startFrame, 48_000)
+      ? programFrameSampleBoundary(timeline, outgoing.span.endFrameExclusive, 48_000)
+        - programFrameSampleBoundary(timeline, outgoing.span.startFrame, 48_000)
       : 0;
     const clip = sourceAudioClip({
       id: `${sequence.id}:${member.id}`,
@@ -528,7 +523,7 @@ function sequenceAudioClips(sequence: MediaSequenceProgram, space: ProgramSpace)
       span,
       layers: member.layers,
       sourceAudio: member.sourceAudio,
-    }, space, { inSamples: fadeInSamples, outSamples: fadeOutSamples });
+    }, timeline, { inSamples: fadeInSamples, outSamples: fadeOutSamples });
     return clip === undefined ? [] : [clip];
   });
   const handoffSounds = sequence.sounds.flatMap((sound) => {
@@ -537,7 +532,7 @@ function sequenceAudioClips(sequence: MediaSequenceProgram, space: ProgramSpace)
     const handoff = sequence.handoffs.find((candidate) => candidate.id === handoffId)!;
     return [soundClip(
       `${sequence.id}:${sound.id}`, sound.source, sound.gain,
-      sequence.members.find((member) => member.id === handoff.toMemberId)!.activationFrame, space,
+      sequence.members.find((member) => member.id === handoff.toMemberId)!.activationFrame, timeline,
     )];
   });
   return [
@@ -547,19 +542,19 @@ function sequenceAudioClips(sequence: MediaSequenceProgram, space: ProgramSpace)
       span: sequence.span,
       motion: sequence.motion,
       sounds: sequence.sounds,
-    }, space),
+    }, timeline),
     ...handoffSounds,
   ];
 }
 
-export function projectMediaAudioTrack(space: ProgramSpace, program: MediaTrackProgram): AudioTrack {
-  assertMediaTrackProgramIdentity(program, space);
+export function projectMediaAudioTrack(timeline: Timeline, program: MediaTrackProgram): AudioTrack {
+  assertMediaTrackProgramIdentity(program, timeline);
   const clips = program.items.flatMap((item) => {
-    const source = sourceAudioClip(item, space);
-    return [...(source === undefined ? [] : [source]), ...edgeSoundClips(item, space)];
-  }).concat(program.sequences.flatMap((sequence) => sequenceAudioClips(sequence, space)));
+    const source = sourceAudioClip(item, timeline);
+    return [...(source === undefined ? [] : [source]), ...edgeSoundClips(item, timeline)];
+  }).concat(program.sequences.flatMap((sequence) => sequenceAudioClips(sequence, timeline)));
   assert(clips.length > 0, `Media Program ${program.id} has no explicitly authored audio projection.`);
-  const track = sealAudioTrack({ programSpaceId: space.id, id: `${program.id}:audio`, clips });
-  assertAudioTrackIdentity(track, space);
+  const track = sealAudioTrack({ programSpaceId: timeline.id, id: `${program.id}:audio`, clips });
+  assertAudioTrackIdentity(track, timeline);
   return track;
 }