@hypit/hypit 0.1.3 → 0.1.5

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";

package/packages/{semantic-track → timeline}/src/location.ts

@@ -1,7 +1,7 @@
 import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
 
-import { assertSemanticTrackIdentity, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";
-import type { LocatedFrameSpan, SemanticTrack } from "./types.js";
+import { assertTimelineIdentity, timelineFrameCount, timelineSpans } from "./identity.js";
+import type { LocatedFrameSpan, Timeline } from "./types.js";
 
 export function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void {
   if (!selection.narrativeId || !selection.id || !selection.startAnchorId || !selection.endAnchorId) throw new Error("NarrativeSelection is invalid");
@@ -11,33 +11,33 @@ export function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void
   if (!moment.narrativeId || !moment.id || !moment.anchorId) throw new Error("NarrativeMoment is invalid");
 }
 
-function assertNarrativeOwner(track: SemanticTrack, narrativeId: string, label: string): void {
+function assertNarrativeOwner(track: Timeline, narrativeId: string, label: string): void {
   if (narrativeId !== track.narrativeId) {
-    throw new Error(`${label} belongs to Narrative ${narrativeId}, not SemanticTrack ${track.id}.`);
+    throw new Error(`${label} belongs to Narrative ${narrativeId}, not Timeline ${track.id}.`);
   }
 }
 
-export function semanticAnchorFrames(track: SemanticTrack): ReadonlyMap<string, number> {
-  assertSemanticTrackIdentity(track);
+export function semanticAnchorFrames(track: Timeline): ReadonlyMap<string, number> {
+  assertTimelineIdentity(track);
   return new Map([
     ["program:start", 0] as const,
-    ...semanticTrackSpans(track).flatMap(({ item, startFrame }) =>
+    ...timelineSpans(track).flatMap(({ item, startFrame }) =>
       item.take.anchors.map((anchor) => [anchor.identity, startFrame + anchor.frame] as const)),
-    ["program:end", semanticTrackFrameCount(track)] as const,
+    ["program:end", timelineFrameCount(track)] as const,
   ]);
 }
 
 function frameFor(frames: ReadonlyMap<string, number>, anchorId: string, owner: string): number {
   const frame = frames.get(anchorId);
-  if (frame === undefined) throw new Error(`${owner} names Anchor ${anchorId}, which this SemanticTrack does not contain.`);
+  if (frame === undefined) throw new Error(`${owner} names Anchor ${anchorId}, which this Timeline does not contain.`);
   return frame;
 }
 
 export function selectionFrameSpan(
-  track: SemanticTrack,
+  track: Timeline,
   selection: NarrativeSelectionRef,
 ): LocatedFrameSpan {
-  assertSemanticTrackIdentity(track);
+  assertTimelineIdentity(track);
   assertNarrativeSelectionIdentity(selection);
   assertNarrativeOwner(track, selection.narrativeId, `NarrativeSelection ${selection.id}`);
   const frames = semanticAnchorFrames(track);
@@ -47,19 +47,19 @@ export function selectionFrameSpan(
   };
 }
 
-export function segmentFrameSpan(track: SemanticTrack, segment: NarrativeExcerpt): LocatedFrameSpan {
-  assertSemanticTrackIdentity(track);
+export function segmentFrameSpan(track: Timeline, segment: NarrativeExcerpt): LocatedFrameSpan {
+  assertTimelineIdentity(track);
   if (segment.kind !== "segment" || !segment.id) throw new Error("Narrative Segment excerpt is invalid");
   assertNarrativeOwner(track, segment.narrativeId, `Narrative Segment ${segment.id}`);
-  const found = semanticTrackSpans(track).find(({ item }) => item.take.segment.segmentId === segment.id);
-  if (found === undefined) throw new Error(`SemanticTrack does not contain Segment ${segment.id}.`);
+  const found = timelineSpans(track).find(({ item }) => item.take.segment.segmentId === segment.id);
+  if (found === undefined) throw new Error(`Timeline does not contain Segment ${segment.id}.`);
   return { startFrame: found.startFrame, endFrameExclusive: found.endFrameExclusive };
 }
 
-export function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]): LocatedFrameSpan | undefined {
-  assertSemanticTrackIdentity(track);
+export function tokenFrameSpan(track: Timeline, tokenIds: readonly string[]): LocatedFrameSpan | undefined {
+  assertTimelineIdentity(track);
   if (tokenIds.length === 0) return undefined;
-  const timing = new Map(semanticTrackSpans(track).flatMap(({ item, startFrame }) =>
+  const timing = new Map(timelineSpans(track).flatMap(({ item, startFrame }) =>
     item.take.tokens.map((token) => [token.tokenId, {
       startFrame: startFrame + token.startFrame,
       endFrameExclusive: startFrame + token.endFrameExclusive,
@@ -72,8 +72,8 @@ export function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]
   };
 }
 
-export function momentFrame(track: SemanticTrack, moment: NarrativeMomentRef): number {
-  assertSemanticTrackIdentity(track);
+export function momentFrame(track: Timeline, moment: NarrativeMomentRef): number {
+  assertTimelineIdentity(track);
   assertNarrativeMomentIdentity(moment);
   assertNarrativeOwner(track, moment.narrativeId, `NarrativeMoment ${moment.id}`);
   const frames = semanticAnchorFrames(track);

package/packages/timeline/src/manifest.ts

@@ -0,0 +1,39 @@
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { narrativeDependency } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceSchema, programSpaceTypes } from "@hypit/program-space";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { semanticTakeSchema, speechDependency } from "@hypit/speech";
+
+export const timelineModuleRef = { name: "@hypit/timeline", version: "1" } as const;
+export const timelineTypes = {
+  track: { module: timelineModuleRef, name: "Timeline" },
+} satisfies Record<string, TypeRef>;
+export const timelineProducers = {
+  projectProgramSpace: { module: timelineModuleRef, name: "project-program-space" },
+  projectAudio: { module: timelineModuleRef, name: "project-audio-track" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+export const timelineSchema: ValueSchema = object({
+  ...(programSpaceSchema.kind === "object" ? programSpaceSchema.fields : {}),
+  narrativeId: { schema: string, optional: true },
+  items: { schema: { kind: "array", items: object({
+    startFrame: { schema: { kind: "number", integer: true, minimum: 0 } },
+    take: { schema: semanticTakeSchema },
+  }) } },
+});
+
+export const timelineManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: timelineModuleRef.name,
+  version: timelineModuleRef.version,
+  dependencies: [speechDependency, narrativeDependency, programSpaceDependency, compositionDependency],
+  types: [{ name: timelineTypes.track.name }],
+  capabilities: [],
+  producers: [
+    { name: timelineProducers.projectProgramSpace.name, inputs: [{ name: "track", type: timelineTypes.track }], outputs: [{ name: "space", type: programSpaceTypes.programSpace }], needs: [] },
+    { name: timelineProducers.projectAudio.name, inputs: [{ name: "track", type: timelineTypes.track }], outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
+  ],
+};
+export const timelineDependency = { module: timelineModuleRef } as const;

package/packages/{semantic-track → timeline}/src/projection.ts

@@ -7,18 +7,18 @@ import {
 } from "@hypit/program-space";
 import type { ProgramSpace } from "@hypit/program-space";
 
-import { assertSemanticTrackIdentity, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";
-import type { SemanticTrack } from "./types.js";
+import { assertTimelineIdentity, timelineFrameCount, timelineSpans } from "./identity.js";
+import type { Timeline } from "./types.js";
 
 /** Prepared material in an authored program interval, with its original source position retained. */
-export function projectSemanticMedia(track: SemanticTrack, window = {
-  startFrame: 0, endFrameExclusive: semanticTrackFrameCount(track),
+export function projectTimelineMedia(track: Timeline, window = {
+  startFrame: 0, endFrameExclusive: timelineFrameCount(track),
 }) {
-  assertSemanticTrackIdentity(track);
+  assertTimelineIdentity(track);
   if (!Number.isSafeInteger(window.startFrame) || !Number.isSafeInteger(window.endFrameExclusive)
     || window.startFrame < 0 || window.endFrameExclusive <= window.startFrame
-    || window.endFrameExclusive > semanticTrackFrameCount(track)) throw new Error("Semantic media window is outside the performance.");
-  return semanticTrackSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
+    || window.endFrameExclusive > timelineFrameCount(track)) throw new Error("Semantic media window is outside the performance.");
+  return timelineSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
     const start = Math.max(window.startFrame, startFrame);
     const end = Math.min(window.endFrameExclusive, endFrameExclusive);
     return end <= start ? [] : [{
@@ -30,19 +30,19 @@ export function projectSemanticMedia(track: SemanticTrack, window = {
   });
 }
 
-export function projectSemanticProgramSpace(track: SemanticTrack): ProgramSpace {
-  assertSemanticTrackIdentity(track);
-  const frameRate = track.items[0]!.take.media.timeline.frameRate;
+export function projectTimelineSpace(track: Timeline): ProgramSpace {
+  assertTimelineIdentity(track);
+  const frameRate = track.frameRate;
   return sealProgramSpace({
     id: track.id,
-    durationSec: semanticTrackFrameCount(track) * frameRate.denominator / frameRate.numerator,
+    durationSec: track.durationSec,
     frameRate,
   });
 }
 
-export function projectSemanticAudioTrack(track: SemanticTrack): AudioTrack {
-  const space = projectSemanticProgramSpace(track);
-  const clips = semanticTrackSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
+export function projectTimelineAudio(track: Timeline): AudioTrack {
+  const space = projectTimelineSpace(track);
+  const clips = timelineSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
     const audio = item.take.media.audio;
     if (audio === undefined) return [];
     const sourceSampleFrames = synchronizedMediaSampleFrames(item.take.media);

package/packages/timeline/src/types.ts

@@ -0,0 +1,24 @@
+import type { ProgramSpace } from "@hypit/program-space";
+import type { SemanticTake } from "@hypit/speech";
+
+export type TimelineItem = {
+  readonly take: SemanticTake;
+  readonly startFrame: number;
+};
+
+/** One complete film time range, with prepared material placed where it belongs. */
+export type Timeline = ProgramSpace & {
+  readonly narrativeId?: string;
+  readonly items: readonly TimelineItem[];
+};
+
+export type TimelineSpan = {
+  readonly item: TimelineItem;
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+export type LocatedFrameSpan = {
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};

package/packages/timeline-author/README.md

@@ -0,0 +1,68 @@
+# `@hypit/timeline-author`
+
+Declare one complete Timeline and place prepared Takes within it. Spoken work, mixed spoken/MG
+work and pure authored animation use the same declaration. The separate
+[Timeline value package](../timeline/README.md) owns the data and projections; this author package
+owns the markup and deterministic assembly.
+
+```svml
+<import as="time" from="@hypit/timeline-author@1"/>
+<time:Clock id="clock" frame-rate="30"/>
+<time:Timeline id="program" clock={clock} end="content.end+2s">
+  <time:Take source={opening.take} at="2s"/>
+  <time:Take source={explanation.take} at="previous.end+3s"/>
+  <time:Take source={closing.take} at="previous.end-12f"/>
+</time:Timeline>
+```
+
+The first Take begins at two seconds. The second starts three seconds after the preceding Take ends.
+The third overlaps its predecessor by twelve frames. The complete Timeline ends two seconds after
+all Takes have ended. Durations come from prepared material, so authoring these relations does not
+require knowing generated lengths beforehand or serializing generation.
+
+| Declaration | Meaning |
+| --- | --- |
+| `clock={clock}` | Required frame-rate input, also usable by upstream normalization. |
+| Take `source={clip.take}` | Complete normalized, semantically prepared local Take. A wordless Take is valid real media. |
+| First omitted `at` | `0f`. |
+| Later omitted `at` | `previous.end`. |
+| `at="20s"` | Absolute start. |
+| `at="previous.end+2s"` | Start relative to the preceding Take declaration's end. Negative offsets permit overlap. |
+| Omitted `end` | `content.end`, the maximum end across all placed Takes. |
+| `end="content.end+2s"` | Reserve a trailing interval after all Takes finish. |
+| `end="30s"` | Fixed complete extent, including every placed Take. |
+
+Positions and offsets accept seconds, milliseconds and frames, and must resolve to exact frame
+boundaries on the Clock. Negative placements, a missing predecessor, or a fixed end shorter than
+placed content produce an error. A positive predecessor offset does not promise globally empty
+time if another long Take remains active. Placement is translation at native speed; trimming or
+retiming material belongs before its semantic preparation.
+
+For ordinary sequential assembly, omit all Take `at` attributes and Timeline `end`. For wholly
+authored animation, supply the extent and no Takes:
+
+```svml
+<time:Timeline id="animation" clock={clock} end="30s"/>
+```
+
+This produces no blank video or fabricated Script. Empty content cannot supply an implicit positive
+extent. Program boundaries remain available for MG, media, titles and sound.
+
+| Output | Use |
+| --- | --- |
+| `.timeline` | Complete time range and placed material/evidence, consumed through `timeline={program.timeline}`. |
+
+[Performance](../performance/README.md) presents footage already
+held by the Timeline. It can show it full-frame, in an inset or as a cutout; project components can
+own coordinated video and graphics. Sampling a new presentation Window preserves each Take's source
+position. Overlap supplies multiple sources, not an automatic dissolve. Independent Media Items
+still receive their own assets and may coexist. Caption reads the authored words and placed timing.
+
+[Sound](../sound/README.md) presents existing Timeline audio through ordered Uses.
+[Audio Track](../audio-track/README.md) handles independent music and effects. Include the wanted
+presentation outputs explicitly in Film. Timeline itself exports only `.timeline`; holding material
+does not add a picture or sound contribution.
+
+Timeline placement is authored with `at` and `end`. Studio shows placed Takes and the complete range
+as reference information. Use-window and Script-marker controls edit presentation timing and semantic
+anchors respectively; they do not move Takes or change the Timeline extent.