@hypit/hypit 0.1.4 → 0.1.5

package/packages/temporal/src/projection.ts

@@ -1,8 +1,8 @@
 import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
 import type { ProgramSpace } from "@hypit/program-space";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import { projectTimelineSpace } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 
 import { locateMoment, locateProgram, locateSegment, locateSelection } from "./location.js";
 import { add, compare, durationInFrames, quantizeBoundary, rational } from "./rational.js";
@@ -169,17 +169,17 @@ function projectedInstant(
 export function projectSelectionInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly selection: NarrativeSelectionRef;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const selection = locateSelection(input.semantic, input.selection);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const selection = locateSelection(input.timeline, input.selection);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "selection", id: selection.id },
+    { spaceId: space.id, narrativeId: input.selection.narrativeId, kind: "selection", id: selection.id },
     projectTemporalInstant(input.projection, { program, selection }, space),
   );
 }
@@ -187,17 +187,17 @@ export function projectSelectionInstant(input: {
 export function projectMomentInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly moment: NarrativeMomentRef;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const moment = locateMoment(input.semantic, input.moment);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const moment = locateMoment(input.timeline, input.moment);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "moment", id: moment.id },
+    { spaceId: space.id, narrativeId: input.moment.narrativeId, kind: "moment", id: moment.id },
     projectTemporalInstant(input.projection, { program, moment }, space),
   );
 }
@@ -205,11 +205,11 @@ export function projectMomentInstant(input: {
 export function projectProgramInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly space: ProgramSpace;
+  readonly timeline: Timeline;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = input.space;
+  const space = projectTimelineSpace(input.timeline);
   const program = { id: "program" as const, start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
@@ -221,17 +221,17 @@ export function projectProgramInstant(input: {
 export function projectSegmentInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly segment: NarrativeExcerpt;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const segment = locateSegment(input.semantic, input.segment);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const segment = locateSegment(input.timeline, input.segment);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "segment", id: segment.id },
+    { spaceId: space.id, narrativeId: input.segment.narrativeId, kind: "segment", id: segment.id },
     projectTemporalInstant(input.projection, { program, segment }, space),
   );
 }

package/packages/temporal/src/rational.ts

@@ -1,4 +1,4 @@
-import type { ProgramSpace } from "@hypit/program-space";
+import type { ProgramClock } from "@hypit/program-space";
 
 import type { TemporalDuration } from "./types.js";
 
@@ -51,9 +51,9 @@ function safeInteger(value: number, label: string): bigint {
   return BigInt(value);
 }
 
-export function durationInFrames(duration: TemporalDuration, space: ProgramSpace): Rational {
-  const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramSpace frame-rate numerator");
-  const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramSpace frame-rate denominator");
+export function durationInFrames(duration: TemporalDuration, space: ProgramClock): Rational {
+  const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramClock frame-rate numerator");
+  const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramClock frame-rate denominator");
   switch (duration.unit) {
     case "frames":
       return rational(safeInteger(duration.value, "Frame duration"));

package/packages/temporal-markup/EDITING.md

@@ -132,8 +132,8 @@ handles allow it, a choice lists the other anchors at the same frame; horizontal
 cannot distinguish them. That explicit choice uses the same Script adjustment operation as dragging.
 
 Segment overlap or gaps can change temporal order without changing Script order. Stop construction
-must not assume contiguous Segments. The current SemanticTrack implementation still concatenates
-Take durations; introducing explicit Take placement is separate work.
+must not assume contiguous Segments. Timeline places each prepared Take independently; semantic
+stops use those placed anchor frames, including coincident anchors from overlapping Takes.
 
 ## Selection, projection, and consumption
 

package/packages/temporal-markup/README.md

@@ -2,11 +2,11 @@
 
 Shared SVML author-time projection helpers for `@hypit/temporal`. The Surface lowers authored
 Selection, Segment, Moment or explicit clock expressions to ordinary Instant projections and Window
-composition. A domain consumer receives the projected values and explicit ProgramSpace; it does not
+composition. A domain consumer receives the projected values and the shared Timeline; it does not
 locate Script words or infer a semantic source inside its renderer.
 
 The package exports `createTemporalWindowProjection`, `createTemporalInstantProjection`,
-`resolveTemporalContext`, `createTemporalSpace`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
+`resolveTemporalContext`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
 Surfaces, not standalone author tags or a new Track.
 
 The editing behavior is specified in [Author-directed time editing](EDITING.md).
@@ -15,15 +15,15 @@ write target for each supported gesture.
 
 ## Time context
 
-A Track Surface can accept `semantic={speech.semantic}` or `space={animation}`. Resolve that choice
-with `resolveTemporalContext({ element, resolveReference })`, and pass the result to
-`createTemporalSpace({ id, element, ...context })`. Preserve its component and fragment drafts.
-Supply `...context, space: time.space` to each temporal projection helper, and pass `time.space.ref`
-to the domain Fragment. Its input Type is `programSpaceTypes.programSpace`.
+A Track Surface accepts `timeline={program.timeline}`. Resolve it with
+`resolveTemporalContext({ element, resolveReference })` and pass that context to each temporal
+projection helper. Wire `context.timeline.ref` directly into the component Fragment's Timeline port.
+Preserve the projections' returned records, components and fragments.
 
-A semantic context locates Script references and supplies the performance's time axis. A declared
-space supplies a clock for authored animation. Literal times and program boundaries work in either
-context. A Script reference needs `semantic` to locate it; the renderer never invents that mapping.
+The context contains one required `timeline` reference. Program time and Script references both
+project against it. Pure animation uses a zero-Take Timeline with an authored extent. Script events
+use the anchors provided by its placed Takes. Drawing Producers receive that same Timeline and the
+projected Instants/Windows; they need no Script parser or separate time-range input.
 
 ## Window forms
 
@@ -70,10 +70,26 @@ can deliberately admit only that form; consumers need not expose unrelated tempo
 
 The Surface supplies an author-facing `subjectId` for the actual item whose time is being projected,
 separately from graph-qualified operation ids. The graph wires the resulting Instant or Window and
-ProgramSpace into the consumer. Keep projection outside the domain Producer: it consumes resolved
+Timeline into the consumer. Keep projection outside the domain Producer: it consumes resolved
 time and implements its own schedule or state, while the shared temporal protocol retains where that
 time came from. An outer lifetime and child activations are separate inputs when a component persists
 between events.
 
 Script's `@`, `~@`, close markers and Moment syntax belong to `@hypit/script`; media playback belongs
 to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.
+
+## Independently bound endpoints
+
+For a Window whose endpoints refer to different semantic sources, use `start-source` and
+`end-source`. The expression still states the kind and boundary; each binding supplies that source:
+
+```svml
+<example:Item start-source={story.segment.next} start="segment.start"
+  end-source={story.segment.previous} end="segment.end"/>
+```
+
+This describes an overlapping physical interval without authoring a backwards Script Selection.
+The same endpoint bindings accept Selections or Moments with their corresponding expressions.
+`segment`, `selection` and `moment` remain convenient shared bindings when both expressions use the
+same source. Explicit expressions retain local parameter writeback; these bindings do not move the
+referenced Script anchors when the expression's offset is edited.

package/packages/temporal-markup/package.json

@@ -11,7 +11,7 @@
     "@hypit/elaborator": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/narrative": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/temporal": "workspace:*",
     "@hypit/program-space": "workspace:*"
   }

package/packages/temporal-markup/src/index.ts

@@ -9,10 +9,8 @@ import type {
   SurfaceResolvedReference,
 } from "@hypit/markup";
 import { narrativeTypes } from "@hypit/narrative";
-import { programSpaceTypes } from "@hypit/program-space";
-import { createTemporalSpace } from "./space.js";
 export * from "./space.js";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 import {
   temporalProducers,
   temporalTypes,
@@ -41,6 +39,9 @@ export const temporalWindowAttributeVocabulary: readonly SurfaceAttributeVocabul
     summary: "Sets a projected start expression; write it together with end." },
   { name: "end", kind: "literal", required: false,
     summary: "Sets a projected end expression; write it together with start." },
+  ...["start-source", "end-source"].map(name => ({ name, kind: "reference" as const, required: false,
+    accepts: [narrativeTypes.selection, narrativeTypes.excerpt, narrativeTypes.moment],
+    summary: "Binds this endpoint's semantic source independently; its expression determines the boundary." })),
   { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],
     summary: "Resolves selection.start or selection.end used by a projected start/end expression." },
   { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],
@@ -205,12 +206,13 @@ function sourceReference(
   element: StructuredElement,
   kind: SourceKind,
   resolveReference: ResolveReference,
+  attribute = kind as string,
 ): SurfaceResolvedReference | undefined {
   if (kind === "program") return undefined;
   const expected = kind === "selection"
     ? narrativeTypes.selection
     : kind === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment;
-  return resolve(element.attributes[kind], `${element.name}.${kind}`, expected, resolveReference);
+  return resolve(element.attributes[attribute], `${element.name}.${attribute}`, expected, resolveReference);
 }
 
 function projectionFragment(input: {
@@ -224,8 +226,7 @@ function projectionFragment(input: {
     ? [["instant", input.start] as const]
     : [["start", input.start] as const, ["end", input.end] as const];
   const inputs = [
-    { name: "space", type: programSpaceTypes.programSpace },
-    ...(endpoints.some(([, endpoint]) => endpoint.source !== "program") ? [{ name: "semantic", type: semanticTrackTypes.track }] : []),
+    { name: "timeline", type: timelineTypes.track },
     ...endpoints.map(([name]) => ({ name: `${name}-spec`, type: temporalTypes.instantSpec })),
     ...endpoints.flatMap(([name, endpoint]) => endpoint.source === "program" ? [] : [{
       name: `${name}-${endpoint.source}`,
@@ -241,7 +242,7 @@ function projectionFragment(input: {
         : endpoint.source === "segment" ? temporalProducers.projectSegmentInstant
           : temporalProducers.projectMomentInstant,
     inputs: {
-      ...(endpoint.source === "program" ? { space: fragmentInput("space") } : { semantic: fragmentInput("semantic") }),
+      timeline: fragmentInput("timeline"),
       spec: fragmentInput(`${name}-spec`),
       ...(endpoint.source === "program" ? {} : {
         [endpoint.source]: fragmentInput(`${name}-${endpoint.source}`),
@@ -274,15 +275,10 @@ function projectionDraft(input: {
   readonly id: string;
   readonly subjectId?: string;
   readonly element: StructuredElement;
-  readonly semantic?: SurfaceResolvedReference;
-  readonly space?: SurfaceResolvedReference;
+  readonly timeline: SurfaceResolvedReference;
   readonly start: InstantDraft;
   readonly end?: InstantDraft;
 }): TemporalMarkupProjection {
-  if ([input.start, input.end].some((endpoint) => endpoint !== undefined && endpoint.source !== "program") && input.semantic === undefined) {
-    throw new Error(`${input.element.name} needs semantic to resolve this Script reference.`);
-  }
-  const time = createTemporalSpace(input);
   const output = input.end === undefined ? "instant" : "window";
   const subjectId = input.subjectId ?? input.id;
   if (subjectId.length === 0) throw new Error("Temporal projection subjectId must not be empty.");
@@ -291,8 +287,7 @@ function projectionDraft(input: {
   const records: SurfaceRecordDraft[] = [];
   const componentInputs: SurfaceComponentDraft["inputs"] extends infer _T
     ? Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }>
-    : never = { space: time.space.ref, ...(input.semantic === undefined ? {} : { semantic: input.semantic.ref }) };
-  if ([input.start, input.end].every((endpoint) => endpoint === undefined || endpoint.source === "program")) delete componentInputs.semantic;
+    : never = { timeline: input.timeline.ref };
   const endpoints = input.end === undefined
     ? [["instant", input.start] as const]
     : [["start", input.start] as const, ["end", input.end] as const];
@@ -327,14 +322,14 @@ function projectionDraft(input: {
   }
   return {
     records,
-    components: [...time.components, {
+    components: [{
       id: componentId,
       fragment: fragment.id,
       inputs: componentInputs,
       outputs: { [output]: `${input.id}.__temporal.${output}` },
       range: input.element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
     ref: { kind: "component-output", component: componentId, output },
   };
 }
@@ -344,8 +339,7 @@ export function createTemporalWindowProjection(input: {
   readonly id: string;
   readonly subjectId?: string;
   readonly element: StructuredElement;
-  readonly semantic?: SurfaceResolvedReference;
-  readonly space?: SurfaceResolvedReference;
+  readonly timeline: SurfaceResolvedReference;
   readonly resolveReference: ResolveReference;
 }): TemporalMarkupProjection {
   const { element, resolveReference } = input;
@@ -422,13 +416,15 @@ export function createTemporalWindowProjection(input: {
   const endExpression = parseTemporalInstant(end, `${element.name}.end`);
   const startSource = expressionSource(startExpression);
   const endSource = expressionSource(endExpression);
+  const startBinding = element.attributes["start-source"] === undefined ? startSource : "start-source";
+  const endBinding = element.attributes["end-source"] === undefined ? endSource : "end-source";
   rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, [
     "start", "end",
-    ...(startSource === "program" ? [] : [startSource]),
-    ...(endSource === "program" ? [] : [endSource]),
+    ...(startSource === "program" ? [] : [startBinding]),
+    ...(endSource === "program" ? [] : [endBinding]),
   ]);
-  const startReference = startSource === "program" ? undefined : sourceReference(element, startSource, resolveReference);
-  const endReference = endSource === "program" ? undefined : sourceReference(element, endSource, resolveReference);
+  const startReference = sourceReference(element, startSource, resolveReference, startBinding);
+  const endReference = sourceReference(element, endSource, resolveReference, endBinding);
   return projectionDraft({
     ...input,
     start: {
@@ -451,8 +447,7 @@ export function createTemporalInstantProjection(input: {
   readonly id: string;
   readonly subjectId?: string;
   readonly element: StructuredElement;
-  readonly semantic?: SurfaceResolvedReference;
-  readonly space?: SurfaceResolvedReference;
+  readonly timeline: SurfaceResolvedReference;
   readonly resolveReference: ResolveReference;
   readonly semanticAttribute?: string;
   readonly boundaryAttribute?: string;

package/packages/temporal-markup/src/space.ts

@@ -1,59 +1,28 @@
-import { sealGraphFragment } from "@hypit/elaborator";
 import type { StructuredElement, SurfaceAttributeVocabulary, SurfaceResolvedReference } from "@hypit/markup";
-import { programSpaceTypes } from "@hypit/program-space";
-import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 export type TemporalContext = {
-  readonly semantic?: SurfaceResolvedReference;
-  readonly space?: SurfaceResolvedReference;
+  readonly timeline: SurfaceResolvedReference;
 };
 
 export const temporalContextAttributeVocabulary = [
-  { name: "semantic", kind: "reference", required: false, accepts: [semanticTrackTypes.track],
-    summary: "Uses the performance's time axis and resolves Script Selections and Moments." },
-  { name: "space", kind: "reference", required: false, accepts: [programSpaceTypes.programSpace],
-    summary: "Uses a declared film time axis for authored animation. Supply semantic or space." },
+  { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
+    summary: "The complete film Timeline, with any placed material and semantic anchors." },
 ] as const satisfies readonly SurfaceAttributeVocabulary[];
 
-/** Select the author's film time source. */
+/** One author-facing Timeline; projections share its range and evidence. */
 export function resolveTemporalContext(input: {
   readonly element: StructuredElement;
   readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
 }): TemporalContext {
   const { element, resolveReference } = input;
-  if (Number(element.attributes.semantic !== undefined) + Number(element.attributes.space !== undefined) !== 1) {
-    throw new Error(`${element.name} requires one time source: semantic or space.`);
-  }
-  const name = element.attributes.semantic === undefined ? "space" : "semantic";
-  const raw = element.attributes[name];
-  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const raw = element.attributes.timeline;
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.timeline must be a reference.`);
   const found = resolveReference(raw.path);
-  const expected = name === "semantic" ? semanticTrackTypes.track : programSpaceTypes.programSpace;
+  const expected = timelineTypes.track;
   if (found === undefined || found.type.module.name !== expected.module.name
     || found.type.module.version !== expected.module.version || found.type.name !== expected.name) {
-    throw new Error(`${element.name}.${name} must reference ${expected.name}.`);
+    throw new Error(`${element.name}.timeline must reference a Timeline.`);
   }
-  return { [name]: found };
-}
-
-/** Give consumers a ProgramSpace while preserving semantic context for word-bound projections. */
-export function createTemporalSpace(input: TemporalContext & { readonly id: string; readonly element: StructuredElement }) {
-  if (input.space !== undefined) return { records: [], components: [], fragments: [], space: input.space };
-  if (input.semantic === undefined) throw new Error(`${input.element.name} requires a film time source.`);
-  const fragment = sealGraphFragment({
-    inputs: [{ name: "semantic", type: semanticTrackTypes.track }],
-    operations: [{ id: "project-space", producer: semanticTrackProducers.projectProgramSpace,
-      inputs: { track: { kind: "fragment-input", name: "semantic" } }, result: { kind: "output", name: "space" } }],
-    exports: [{ name: "space", type: programSpaceTypes.programSpace,
-      root: { kind: "fragment-operation", operation: "project-space" } }],
-  });
-  const id = `${input.id}.__space`;
-  const space: SurfaceResolvedReference = { path: `${id}.space`, type: programSpaceTypes.programSpace,
-    ref: { kind: "component-output", component: id, output: "space" } };
-  return {
-    records: [],
-    components: [{ id, fragment: fragment.id, inputs: { semantic: input.semantic.ref }, outputs: { space: `${id}.space` }, range: input.element.range }],
-    fragments: [fragment],
-    space,
-  };
+  return { timeline: found };
 }

package/packages/timeline/README.md

@@ -0,0 +1,31 @@
+# `@hypit/timeline`
+
+One Timeline describes the complete film time range and the prepared Takes placed within it.
+Semantic anchors exist wherever those Takes supply them; no second kind of time axis is needed
+for authored animation. The value stores `id`, `durationSec`, `frameRate`, optional `narrativeId`,
+and `items` containing `take` and `startFrame`. A zero-Take Timeline has no Narrative identity.
+
+Each Take retains its normalized local media and semantic evidence. Global positions are its
+placement start plus local positions. Items can leave gaps or overlap; their declaration order is
+preserved. Frame rates and Narrative ownership agree, identities remain unique, and every complete
+Take fits inside the positive Program range. Assembly is owned by
+[Timeline authoring](../timeline-author/README.md).
+
+`projectTimelineSpace` supplies the lightweight `ProgramSpace` range used by rendering.
+`semanticAnchorFrames`, `selectionFrameSpan`, `segmentFrameSpan`, `tokenFrameSpan` and `momentFrame`
+locate evidence without copying another word table. Program boundaries are available even with zero
+Takes. Selection endpoints retain their authored identities; projection/consumption determines
+whether a requested physical Window is usable.
+
+## Project prepared material
+
+`projectTimelineMedia(timeline, window?)` returns every intersecting Take's `media`, `segmentId`,
+global `span` and local `source` frame span. The default Window is the complete Timeline. Gaps
+return no source; overlaps return all intersecting sources. Audio-only Takes remain represented.
+Starting presentation inside a Take retains the matching source frame. This projection chooses no
+layout, winning picture, held frame or transition.
+
+`projectTimelineAudio` places original audio at each Take's position at native speed and gain.
+Takes without audio contribute no clip; gaps are silent and overlapping Takes contribute simultaneous
+clips. Film explicitly includes that audio contribution. These functions perform no media I/O,
+transcription, rendering or generation.

package/packages/{semantic-track → timeline}/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@hypit/semantic-track",
+  "name": "@hypit/timeline",
   "version": "0.0.0-dev",
   "license": "SEE LICENSE IN LICENSE",
   "private": true,

package/packages/timeline/src/activation.ts

@@ -0,0 +1,8 @@
+import { timelineComponent, timelineManifest } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: timelineManifest }],
+  components: [timelineComponent],
+};
+export default hypitPackage;

package/packages/timeline/src/component.ts

@@ -0,0 +1,24 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { timelineProducers, timelineTypes } from "./manifest.js";
+import { assertTimelineIdentity } from "./identity.js";
+import { projectTimelineAudio, projectTimelineSpace } from "./projection.js";
+import type { Timeline } from "./types.js";
+
+function track(value: StoredValue | undefined): Timeline {
+  if (value?.kind !== "inline") throw new Error("Timeline must be inline.");
+  return value.value as unknown as Timeline;
+}
+
+export const timelineComponent = {
+  producers: [
+    { producer: timelineProducers.projectProgramSpace, handler: ({ inputs }) => ({ outputs: { space: { kind: "inline", value: canonicalize(projectTimelineSpace(track(inputs.track?.value))) } }, needs: {} }) },
+    { producer: timelineProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { audio: { kind: "inline", value: canonicalize(projectTimelineAudio(track(inputs.track?.value))) } }, needs: {} }) },
+  ],
+  validators: [{
+    type: timelineTypes.track,
+    handler: ({ value }) => assertTimelineIdentity(track(value)),
+  }],
+} satisfies ComponentPackage;

package/packages/timeline/src/identity.ts

@@ -0,0 +1,60 @@
+import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
+import { assertSemanticTakeIdentity } from "@hypit/speech";
+
+import type { Timeline, TimelineSpan } from "./types.js";
+
+export function sealTimeline(value: Timeline): Timeline {
+  const track = structuredClone(value);
+  assertTimelineIdentity(track);
+  return track;
+}
+
+export function assertTimelineIdentity(track: Timeline): void {
+  assertProgramSpaceIdentity(track);
+  const frameCount = programSpaceFrameCount(track);
+  if (track.items.length > 0 && !track.narrativeId?.trim()) throw new Error("A Timeline with Takes requires their Narrative identity.");
+  if (track.items.length === 0 && track.narrativeId !== undefined) throw new Error("An empty Timeline has no Narrative identity.");
+  const segmentIds = new Set<string>();
+  const tokenIds = new Set<string>();
+  const anchorIds = new Set<string>();
+  const frameRate = track.frameRate;
+  for (const item of track.items) {
+    assertSemanticTakeIdentity(item.take);
+    if (!Number.isSafeInteger(item.startFrame) || item.startFrame < 0
+      || item.startFrame + item.take.media.timeline.frameCount > frameCount) {
+      throw new Error(`Timeline placement for ${item.take.segment.segmentId} is outside its Program range.`);
+    }
+    if (item.take.narrativeId !== track.narrativeId) {
+      throw new Error(`Timeline ${track.id} mixes Narrative ${item.take.narrativeId} into ${track.narrativeId}.`);
+    }
+    const rate = item.take.media.timeline.frameRate;
+    if (frameRate.numerator !== rate.numerator || frameRate.denominator !== rate.denominator) {
+      throw new Error("Timeline items must use one frame rate.");
+    }
+    const segmentId = item.take.segment.segmentId;
+    if (segmentIds.has(segmentId)) throw new Error(`Timeline repeats Segment ${segmentId}.`);
+    segmentIds.add(segmentId);
+    for (const token of item.take.tokens) {
+      if (tokenIds.has(token.tokenId)) throw new Error(`Timeline repeats Token ${token.tokenId}.`);
+      tokenIds.add(token.tokenId);
+    }
+    for (const anchor of item.take.anchors) {
+      if (anchor.identity === "program:start" || anchor.identity === "program:end") {
+        throw new Error(`SemanticTake cannot declare reserved Program Anchor ${anchor.identity}.`);
+      }
+      if (anchorIds.has(anchor.identity)) throw new Error(`Timeline repeats Anchor ${anchor.identity}.`);
+      anchorIds.add(anchor.identity);
+    }
+  }
+}
+
+export function timelineSpans(track: Timeline): readonly TimelineSpan[] {
+  assertTimelineIdentity(track);
+  return track.items.map(item => ({ item, startFrame: item.startFrame,
+    endFrameExclusive: item.startFrame + item.take.media.timeline.frameCount }));
+}
+
+export function timelineFrameCount(track: Timeline): number {
+  assertTimelineIdentity(track);
+  return programSpaceFrameCount(track);
+}

package/packages/timeline/src/index.ts

@@ -0,0 +1,6 @@
+export { timelineComponent } from "./component.js";
+export { assertTimelineIdentity, sealTimeline, timelineFrameCount, timelineSpans } from "./identity.js";
+export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, momentFrame, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, tokenFrameSpan } from "./location.js";
+export { timelineDependency, timelineManifest, timelineModuleRef, timelineProducers, timelineSchema, timelineTypes } from "./manifest.js";
+export { projectTimelineAudio, projectTimelineSpace, projectTimelineMedia } from "./projection.js";
+export type * from "./types.js";