@hypit/hypit 0.1.4 → 0.1.5

package/examples/semantic-composition/packages/responsive-explainer/README.md

@@ -8,16 +8,23 @@ With prepared Takes, a Canvas and an exact FontStack already available:
 ```svml
 <import as="explainer" from="@example/responsive-explainer@1"/>
 
-<speech:Track id="speech">
-  <speech:Take source={opening.take}/>
-  <speech:Take source={explanation.take}/>
-</speech:Track>
-<explainer:Scene id="scene" semantic={speech.semantic} canvas={canvas} font={font}
+<time:Clock id="clock" frame-rate="30"/>
+<time:Timeline id="speech" clock={clock}>
+  <time:Take source={opening.take}/>
+  <time:Take source={explanation.take}/>
+</time:Timeline>
+<explainer:Scene id="scene" timeline={speech.timeline} canvas={canvas} font={font}
   during="program" reveal={story.moment.demonstrate} title="Make room for meaning"
   transition-frames="24" stack-order="0"/>
-<film:Film id="main" canvas={canvas} semantic={speech.semantic} appearance={look.film}>
+<import as="sound" from="@hypit/sound@1"/>
+<sound:Style id="voice-style"/>
+<sound:Track id="voice" timeline={speech.timeline}>
+  <sound:Use style={voice-style}/>
+</sound:Track>
+
+<film:Film id="main" canvas={canvas} timeline={speech.timeline} appearance={look.film}>
   <film:Track source={scene.visual}/>
-  <film:Track source={speech.audio}/>
+  <film:Track source={voice.audio}/>
   <film:Track source={captions.track}/>
 </film:Film>
 ```
@@ -28,11 +35,11 @@ the Script or using another delivery changes the projected frame while retaining
 `transition-frames` is the duration of that change, separate from the scene's lifetime. `stack-order`
 places this scene among other contributions. The caller supplies its title and exact fonts.
 
-`projectSemanticMedia` selects all intersecting prepared Takes. Each video's target interval is
+`projectTimelineMedia` selects all intersecting prepared Takes. Each video's target interval is
 Present-local and its source offset is preserved. The parent viewport changes size and position;
 playback is never restarted by the layout change. The component owns the diagram and the viewport,
 so its internal overlap, rounded clipping and backdrop blur are ordinary HTML/CSS relationships.
-The original audio stays independently selectable as `speech.audio`.
+Sound independently presents the existing audio as `voice.audio`.
 
 `src/activation.ts` declares the Module, Surface, semantic projections and Producer Fragment.
 `src/render.ts` emits a browser program with HTML slots for typed video and text children. Its render

package/examples/semantic-composition/packages/responsive-explainer/src/activation.ts

@@ -5,8 +5,8 @@ import { compositionTypes } from "@hypit/hypit/composition";
 import { mediaTypes } from "@hypit/hypit/media";
 import type { FontStackRef } from "@hypit/hypit/media";
 import { narrativeTypes } from "@hypit/hypit/narrative";
-import { semanticTrackTypes } from "@hypit/hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/hypit/semantic-track";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import type { Timeline } from "@hypit/hypit/timeline";
 import { spatialTypes } from "@hypit/hypit/spatial";
 import type { CanvasSpace } from "@hypit/hypit/spatial";
 import { temporalTypes } from "@hypit/hypit/temporal";
@@ -20,12 +20,12 @@ const module = { name: "@example/responsive-explainer", version: "1" } as const;
 const optionsType = { module, name: "ExplainerOptions" };
 const producer = { module, name: "compose" };
 const inputs = [
-  { name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+  { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
   { name: "window", type: temporalTypes.window }, { name: "reveal", type: temporalTypes.instant },
   { name: "font", type: mediaTypes.fontStack }, { name: "options", type: optionsType },
 ];
 export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
-  dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, semanticTrackTypes.track,
+  dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, timelineTypes.track,
     spatialTypes.canvas, temporalTypes.window].map(type => ({ module: type.module })),
   types: [{ name: optionsType.name }], capabilities: [],
   producers: [{ name: producer.name, inputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] }],
@@ -40,12 +40,12 @@ const inline = <T>(record: { value: { kind: string; value?: unknown } } | undefi
   return record.value.value as T;
 };
 const component: ComponentPackage = { producers: [{ producer, handler: ({ inputs }) => ({ needs: {}, outputs: {
-  visual: { kind: "inline", value: canonicalize(renderExplainer(inline<SemanticTrack>(inputs.semantic),
+  visual: { kind: "inline", value: canonicalize(renderExplainer(inline<Timeline>(inputs.timeline),
     inline<CanvasSpace>(inputs.canvas), inline<TemporalWindow>(inputs.window), inline<TemporalInstant>(inputs.reveal),
     inline<FontStackRef>(inputs.font).faces, inline<ExplainerOptions>(inputs.options))) },
 } }) }] };
 export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  assertAttributes(element, ["id", "semantic", "canvas", "font", "reveal", "title", "transition-frames", "stack-order", ...temporalWindowAttributeNames]);
+  assertAttributes(element, ["id", "timeline", "canvas", "font", "reveal", "title", "transition-frames", "stack-order", ...temporalWindowAttributeNames]);
   assertEmptyElement(element);
   const id = textAttribute(element, "id");
   const reference = (name: string, type: TypeRef): SurfaceResolvedReference => {
@@ -55,19 +55,19 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
     if (value === undefined || !sameType(type, value.type)) throw new Error(`${name} has the wrong type.`);
     return value;
   };
-  const semantic = reference("semantic", semanticTrackTypes.track);
-  const window = createTemporalWindowProjection({ id: `${id}.window`, element, semantic, resolveReference });
+  const timeline = reference("timeline", timelineTypes.track);
+  const window = createTemporalWindowProjection({ id: `${id}.window`, element, timeline, resolveReference });
   // Reveal has its own Moment; the outer Window independently controls this scene's lifetime.
   reference("reveal", narrativeTypes.moment);
   const reveal = createTemporalInstantProjection({ id: `${id}.reveal`,
-    element: { ...element, attributes: { at: element.attributes.reveal! } }, semantic, resolveReference });
+    element: { ...element, attributes: { at: element.attributes.reveal! } }, timeline, resolveReference });
   const options: ExplainerOptions = { id, title: textAttribute(element, "title"),
     transitionFrames: Number(textAttribute(element, "transition-frames")), stackingOrder: Number(textAttribute(element, "stack-order")) };
   return { records: [...window.records, ...reveal.records, { id: `${id}.options`, type: optionsType,
       value: { kind: "inline", value: canonicalize(options) }, range: element.range }],
     fragments: [...window.fragments, ...reveal.fragments, fragment],
     components: [...window.components, ...reveal.components, { id, fragment: fragment.id,
-      inputs: { semantic: semantic.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
+      inputs: { timeline: timeline.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
         font: reference("font", mediaTypes.fontStack).ref, window: window.ref, reveal: reveal.ref,
         options: { kind: "record", id: `${id}.options` } }, outputs: { visual: `${id}.visual` }, range: element.range }],
     exports: [`${id}.visual`] };
@@ -77,12 +77,12 @@ const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
   vocabulary: { summary: "A continuously playing performance makes room for a diagram on a semantic Moment.",
     attributes: [
       ...["id", "title", "transition-frames", "stack-order"].map(name => ({ name, kind: "literal" as const, required: true, summary: name })),
-      ...[{ name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+      ...[{ name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
         { name: "font", type: mediaTypes.fontStack }, { name: "reveal", type: narrativeTypes.moment }]
         .map(({ name, type }) => ({ name, kind: "reference" as const, required: true, accepts: [type], summary: name })),
       ...temporalWindowAttributeVocabulary,
     ], ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "The coordinated scene." }],
-    example: '<explainer:Scene id="scene" semantic={speech.semantic} canvas={canvas} font={font} during="program" reveal={story.moment.reveal} title="How it works" transition-frames="18" stack-order="0"/>',
+    example: '<explainer:Scene id="scene" timeline={speech.timeline} canvas={canvas} font={font} during="program" reveal={story.moment.reveal} title="How it works" transition-frames="18" stack-order="0"/>',
   },
 };
 export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component],

package/examples/semantic-composition/packages/responsive-explainer/src/render.ts

@@ -2,22 +2,22 @@ import { sealVisualTrack } from "@hypit/hypit/composition";
 import type { VisualElement } from "@hypit/hypit/composition";
 import { browserProgram } from "@hypit/hypit/hyperframes";
 import type { FontArtifactRef } from "@hypit/hypit/media";
-import { projectSemanticMedia, projectSemanticProgramSpace } from "@hypit/hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/hypit/semantic-track";
+import { projectTimelineMedia, projectTimelineSpace } from "@hypit/hypit/timeline";
+import type { Timeline } from "@hypit/hypit/timeline";
 import type { CanvasSpace } from "@hypit/hypit/spatial";
 import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
 
 export type ExplainerOptions = { id: string; title: string; transitionFrames: number; stackingOrder: number };
 
 /** One scene owns the moving performance viewport and the diagram it makes room for. */
-export function renderExplainer(semantic: SemanticTrack, canvas: CanvasSpace, window: TemporalWindow,
+export function renderExplainer(semantic: Timeline, canvas: CanvasSpace, window: TemporalWindow,
   reveal: TemporalInstant, fonts: readonly FontArtifactRef[], options: ExplainerOptions) {
-  const space = projectSemanticProgramSpace(semantic);
+  const space = projectTimelineSpace(semantic);
   if (window.start.source.spaceId !== space.id || reveal.source.spaceId !== space.id)
     throw new Error("Explainer timing must belong to its semantic performance.");
   if (!Number.isSafeInteger(options.transitionFrames) || options.transitionFrames < 1)
     throw new Error("Explainer transitionFrames must be a positive integer.");
-  const clips = projectSemanticMedia(semantic, window.span).filter(clip => clip.media.visual !== undefined);
+  const clips = projectTimelineMedia(semantic, window.span).filter(clip => clip.media.visual !== undefined);
   const videos: VisualElement[] = clips.map((clip, i) => ({
     id: `take-${i}`, parent: "scene", kind: "video", order: i + 1,
     artifact: clip.media.visual!.artifact, muted: true,

package/examples/semantic-composition/packages/sound-styles/README.md

@@ -0,0 +1,36 @@
+# Project sound Style: explicit crossfade
+
+This ordinary project package demonstrates `soundStyle(fragment, bindings)`. It publishes one
+`Crossfade` Style with explicit outgoing and incoming Segment inputs. It uses public
+`@hypit/hypit/*` imports and returns ordinary AudioTrack data. Copy it into a video's `packages/`,
+select the installed Hypit version as its development dependency, build it and declare it in the
+project's ordinary package configuration.
+
+```svml
+<import as="sound" from="@hypit/sound@1"/>
+<import as="mix" from="@example/sound-styles@1"/>
+<sound:Style id="normal"/>
+<mix:Crossfade id="handoff"
+  outgoing={story.segment.first} incoming={story.segment.second}/>
+<sound:Track id="voice" timeline={program.timeline}>
+  <sound:Use style={normal}/>
+  <sound:Use style={handoff}
+    start-source={story.segment.second} start="segment.start"
+    end-source={story.segment.first} end="segment.end"/>
+</sound:Track>
+```
+
+The Window describes an actual overlap, even though its endpoints are reversed in Script order.
+The two Style inputs declare roles; temporal endpoints do not infer them. Outgoing gain decreases
+from 1 to 0 and incoming gain increases from 0 to 1 across that Window. Playback stays at each
+Take's existing source position. A known source with no audio contributes nothing; an unknown source
+is an error. Both roles must name distinct Segments.
+
+Linear crossfade is this family's chosen behavior, not a universal acoustic rule. A different
+project family can use another envelope or more sources without changing Timeline or the renderer.
+For intentional simultaneous speech, a family can return both explicit `sourceSound` results at
+unity gain. Independently included Sound Tracks can also coexist.
+
+The implementation is in [render.ts](src/render.ts); [activation.ts](src/activation.ts) declares the
+Surface, typed inputs, fragment and Producer. Build with `pnpm --filter @example/sound-styles build`
+inside this repository after public declarations are available.

package/examples/semantic-composition/packages/sound-styles/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@example/sound-styles",
+  "version": "0.0.0-dev",
+  "private": true,
+  "type": "module",
+  "hypit": {
+    "activation": "./dist/activation.js"
+  },
+  "exports": {
+    ".": "./dist/render.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@hypit/hypit": "workspace:*",
+    "typescript": "5.9.3",
+    "@types/node": "24.10.1"
+  }
+}

package/examples/semantic-composition/packages/sound-styles/src/activation.ts

@@ -0,0 +1,53 @@
+import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType, sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
+import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { soundStyle, soundTypes, soundModuleRef } from "@hypit/hypit/sound";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import type { Timeline } from "@hypit/hypit/timeline";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import type { TemporalWindow } from "@hypit/hypit/temporal";
+import { narrativeTypes } from "@hypit/hypit/narrative";
+import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
+import { crossfadeSound } from "./render.js";
+
+const module = { name: "@example/sound-styles", version: "1" } as const;
+const common = [{ name: "timeline", type: timelineTypes.track }, { name: "window", type: temporalTypes.window }];
+const mixInputs = [...common, { name: "outgoing", type: narrativeTypes.excerpt }, { name: "incoming", type: narrativeTypes.excerpt }];
+const families = [{ name: "crossfade", tag: "Crossfade", ports: mixInputs }];
+export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
+  dependencies: [soundModuleRef, compositionTypes.audioTrack.module, timelineTypes.track.module, temporalTypes.window.module, narrativeTypes.excerpt.module].map(module => ({ module })),
+  types: [], capabilities: [], producers: families.map(family => ({ name: family.name, inputs: family.ports, outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] })) };
+const fragments = families.map(family => sealGraphFragment({ inputs: family.ports,
+  operations: [{ id: "render", producer: { module, name: family.name }, inputs: Object.fromEntries(family.ports.map(port => [port.name, { kind: "fragment-input" as const, name: port.name }])), result: { kind: "output", name: "audio" } }],
+  exports: [{ name: "audio", type: compositionTypes.audioTrack, root: { kind: "fragment-operation", operation: "render" } }] }));
+const component: ComponentPackage = { producers: families.map(family => ({ producer: { module, name: family.name }, handler: ({ inputs }) => {
+  const values = Object.fromEntries(Object.entries(inputs).map(([key, record]) => {
+    if (record.value.kind !== "inline") throw new Error(`${key} must be inline`);
+    return [key, record.value.value];
+  }));
+  const audio = crossfadeSound(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow,
+    values.outgoing as unknown as NarrativeExcerpt, values.incoming as unknown as NarrativeExcerpt);
+  return { outputs: { audio: { kind: "inline", value: canonicalize(audio) } }, needs: {} };
+} })) };
+const hostFacets = families.map((family,index) => {
+  const params = family.ports.slice(common.length);
+  const handler: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+    assertAttributes(element, ["id", ...params.map(port => port.name)]); assertEmptyElement(element);
+    const bindings: Record<string, SurfaceResolvedReference> = {};
+    for (const param of params) {
+      const raw = element.attributes[param.name];
+      if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${param.name} must be a reference`);
+      const value = resolveReference(raw.path);
+      if (value === undefined || !sameType(value.type,param.type)) throw new Error(`${param.name} has the wrong Type`);
+      bindings[param.name] = value;
+    }
+    return { records: [{ id: textAttribute(element,"id"), type: soundTypes.style,
+      value: { kind: "inline", value: canonicalize(soundStyle(fragments[index]!,bindings)) }, range: element.range }], components: [], fragments: [] };
+  };
+  return createMarkupSurfaceHostFacet({ module, declaration: { name: family.name, tag: family.tag, mode: "structured", outputs: [soundTypes.style], vocabulary: {
+    summary: `Project-owned ${family.name} presentation Style.`, example: `<styles:${family.tag} id="look" ${params.map(port => `${port.name}={${port.name}}`).join(' ')}/>`,
+    attributes: [{ name: "id", kind: "identifier", required: true, summary: "Style identity." }, ...params.map(port => ({ name: port.name, kind: "reference" as const, required: true, accepts: [port.type], summary: `Explicit ${port.name} input.` }))],
+  } }, handler });
+});
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component], hostFacets };
+export default hypitPackage;

package/examples/semantic-composition/packages/sound-styles/src/render.ts

@@ -0,0 +1,14 @@
+import { sealAudioTrack } from "@hypit/hypit/composition";
+import { sourceSound } from "@hypit/hypit/sound";
+import type { Timeline } from "@hypit/hypit/timeline";
+import type { TemporalWindow } from "@hypit/hypit/temporal";
+import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
+
+/** The family explicitly chooses the two roles; the Window only controls the blend progress. */
+export function crossfadeSound(timeline: Timeline, window: TemporalWindow,
+  outgoing: NarrativeExcerpt, incoming: NarrativeExcerpt) {
+  if (outgoing.id === incoming.id && outgoing.narrativeId === incoming.narrativeId) throw new Error("Crossfade needs two distinct sources.");
+  const left = sourceSound(timeline, window, outgoing, { gain: 1, endGain: 0 });
+  const right = sourceSound(timeline, window, incoming, { gain: 0, endGain: 1 });
+  return sealAudioTrack({ id: window.subjectId, programSpaceId: timeline.id, clips: [...left.clips, ...right.clips] });
+}

package/examples/semantic-composition/packages/sound-styles/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -58,9 +58,9 @@
       "types": "./dist/public/runtime-kit.d.ts",
       "import": "./packages/runtime-kit/src/index.ts"
     },
-    "./semantic-track": {
-      "types": "./dist/public/semantic-track.d.ts",
-      "import": "./packages/semantic-track/src/index.ts"
+    "./timeline": {
+      "types": "./dist/public/timeline.d.ts",
+      "import": "./packages/timeline/src/index.ts"
     },
     "./spatial": {
       "types": "./dist/public/spatial.d.ts",
@@ -97,6 +97,14 @@
     "./hyperframes": {
       "types": "./dist/public/hyperframes.d.ts",
       "import": "./packages/hyperframes/src/index.ts"
+    },
+    "./performance": {
+      "types": "./dist/public/performance.d.ts",
+      "import": "./packages/performance/src/index.ts"
+    },
+    "./sound": {
+      "types": "./dist/public/sound.d.ts",
+      "import": "./packages/sound/src/index.ts"
     }
   },
   "bin": {
@@ -149,7 +157,12 @@
     "examples/semantic-composition/*.svml",
     "examples/semantic-composition/*.svrun",
     "examples/semantic-composition/*.svs",
-    "examples/semantic-composition/hypit.runtime.json"
+    "examples/semantic-composition/hypit.runtime.json",
+    "examples/provider-package/README.md",
+    "examples/provider-package/packages/*/package.json",
+    "examples/provider-package/packages/*/tsconfig.json",
+    "examples/provider-package/packages/*/src/**/*",
+    "examples/provider-package/hypit.runtime.json"
   ],
   "scripts": {
     "pack:distribution": "node scripts/pack-distribution.mjs",
@@ -166,15 +179,15 @@
     "prepack": "npm run build:public-types"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.15.0"
   },
   "devDependencies": {
-    "@hypit/browser-capture": "workspace:*",
     "@hypit/artifact": "workspace:*",
     "@hypit/audio-track": "workspace:*",
     "@hypit/audio-track-studio": "workspace:*",
     "@hypit/author-kit": "workspace:*",
     "@hypit/background-removal": "workspace:*",
+    "@hypit/browser-capture": "workspace:*",
     "@hypit/build-result": "workspace:*",
     "@hypit/build-result-fs": "workspace:*",
     "@hypit/build-result-kit": "workspace:*",
@@ -189,9 +202,11 @@
     "@hypit/credential-store-os": "workspace:*",
     "@hypit/deck-track": "workspace:*",
     "@hypit/deck-track-studio": "workspace:*",
+    "@hypit/elevenlabs-speech": "workspace:*",
     "@hypit/estimate": "workspace:*",
     "@hypit/film": "workspace:*",
     "@hypit/film-studio": "workspace:*",
+    "@hypit/fishaudio-speech": "workspace:*",
     "@hypit/fonts-open": "workspace:*",
     "@hypit/generation": "workspace:*",
     "@hypit/gpt-image": "workspace:*",
@@ -209,16 +224,16 @@
     "@hypit/minimax-h3": "workspace:*",
     "@hypit/nano-banana": "workspace:*",
     "@hypit/narrative": "workspace:*",
+    "@hypit/performance": "workspace:*",
+    "@hypit/performance-studio": "workspace:*",
     "@hypit/program-space": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/provider-hyperframes-aws-lambda": "workspace:*",
     "@hypit/provider-hyperframes-local": "workspace:*",
     "@hypit/provider-hypihub": "workspace:*",
     "@hypit/provider-image-opencv-local": "workspace:*",
-    "@hypit/provider-kie": "workspace:*",
     "@hypit/provider-media-local": "workspace:*",
     "@hypit/provider-whisperx-local": "workspace:*",
-    "@hypit/provider-xiaomi-mimo": "workspace:*",
     "@hypit/ranking": "workspace:*",
     "@hypit/ranking-studio": "workspace:*",
     "@hypit/raster": "workspace:*",
@@ -236,19 +251,20 @@
     "@hypit/seedance": "workspace:*",
     "@hypit/seedance-kits": "workspace:*",
     "@hypit/seedream": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/sound": "workspace:*",
+    "@hypit/sound-studio": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/speech": "workspace:*",
     "@hypit/speech-alignment": "workspace:*",
     "@hypit/speech-evidence": "workspace:*",
-    "@hypit/speech-track": "workspace:*",
-    "@hypit/speech-track-studio": "workspace:*",
     "@hypit/store-sqlite": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/temporal": "workspace:*",
     "@hypit/temporal-markup": "workspace:*",
     "@hypit/text": "workspace:*",
+    "@hypit/timeline": "workspace:*",
+    "@hypit/timeline-author": "workspace:*",
     "@hypit/typography-track": "workspace:*",
     "@hypit/typography-track-studio": "workspace:*",
     "@hypit/visual-ir": "workspace:*",
@@ -263,10 +279,11 @@
     "@puppeteer/browsers": "3.2.2",
     "koffi": "3.2.1",
     "puppeteer-core": "25.10.0",
-    "sharp": "0.35.3",
+    "sharp": "0.35.4",
     "cmu-pronouncing-dictionary": "3.0.0",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "vite": "8.2.2"
+    "vite": "8.2.2",
+    "cjs-module-lexer": "2.2.1"
   }
 }

package/packages/audio-track/README.md

@@ -1,37 +1,37 @@
 # `@hypit/audio-track`
 
-The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
-resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+The Track Surface accepts `timeline={program.timeline}`. The same Timeline supports authored
+positions and, where prepared Takes supply evidence, Script Selections and Moments. Shared `at`
 inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
 
 Place music, ambience and sound effects in the assembled video. A reveal sound can follow a Script
 Moment; music can occupy a Segment or the program; an explicitly timed sound can use clock placement.
-Performance audio normally comes from [Speech Track](../speech-track/README.md) and can continue
+Performance audio is presented by [Sound](../sound/README.md) from the assembled Timeline and can continue
 under these independent sounds and [Media Track](../media-track/README.md) coverage.
 
-Each Clip consumes normalized audio-bearing media and a projected Window. Gain, fades, trim and
+Each Item consumes normalized audio-bearing media and a projected Window. Gain, fades, trim and
 playback express the mix. Normalization preserves the source level; choose the balance and any
-music ducking for the actual performance. The resulting `.track` is a peer AudioTrack in Film.
+music ducking for the actual performance. The resulting `.audio` is a peer AudioTrack in Film.
 
-## Authoring clips
+## Authoring items
 
-The Markup Track selects `semantic` or `space`; its Fragment receives the resulting ProgramSpace.
-Each Clip accepts one shared temporal Window form: `during="program"`, a Selection or Segment,
+The Markup Track selects `timeline`; its Fragment receives the same Timeline.
+Each Item accepts one shared temporal Window form: `during="program"`, a Selection or Segment,
 a Moment paired with `for`, or explicit `start`/`end` expressions. The source must already contain
-normalized audio. This excerpt assumes imports, Script, SemanticTrack, Clock and source media exist:
+normalized audio. This excerpt assumes imports, Script, Timeline, Clock and source media exist:
 
 ```svml
 <pipeline:Normalize id="hit-media" source={hit-source}
   video="none" audio="default" span-authority="audio" clock={clock}/>
-<audio:Track id="effects" semantic={speech.semantic}>
-  <audio:Clip source={hit-media.media} at={story.moment.reveal} for="600ms"
+<audio:Track id="effects" timeline={speech.timeline}>
+  <audio:Item source={hit-media.media} at={story.moment.reveal} for="600ms"
     playback="once" gain="0.45" fade-in="0f" fade-out="3f"/>
 </audio:Track>
 ```
 
-The Track publishes `.program` and `.track`; include the latter as a peer Film Track. `gain` is a
+The Track publishes `.program` and `.audio`; include the latter as a peer Film Track. `gain` is a
 linear multiplier, defaulting to `1`; fade durations default to `0f`. Trim boundaries are source
-durations (`f`, integer `ms`, or fractional `s`), distinct from the Clip's destination Window.
+durations (`f`, integer `ms`, or fractional `s`), distinct from the Item's destination Window.
 `trim-end` is the exclusive source endpoint, not an amount to subtract from the tail. For example,
 `trim-start="1s" trim-end="3s"` selects the source interval from one to three seconds.
 
@@ -41,3 +41,10 @@ requires authored `min-rate` and `max-rate` bounds. Other playback modes reject
 Choose occupancy from the intended sound; the Track does not silently loop music or stretch a hit
 to fill a longer Window. Its source level is retained unless gain or another explicit audio operation
 changes it.
+
+Media Track and Audio Track both place independent Items on the same Timeline.
+Overlapping pictures compose by draw order; overlapping sounds mix together.
+Give an Item an `id` when it needs a recognizable author name. Studio otherwise
+displays its source reference; the generated internal identity still owns
+selection and writeback. Reusing a source in two Items keeps two independent
+placements, even when their displayed names match.

package/packages/audio-track/package.json

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

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

@@ -1,8 +1,8 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
 import type { SynchronizedMedia } from "@hypit/media";
 import { canonicalize } from "@hypit/protocol";
 import type { StoredValue } from "@hypit/protocol";
-import type { ProgramSpace } from "@hypit/program-space";
 
 import { audioTrackProducers, audioTrackTypes } from "./manifest.js";
 import { appendProjectedAudioItem, assertAudioTrackProgram, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack } from "./program.js";
@@ -15,14 +15,14 @@ function inline<T>(value: StoredValue | undefined, label: string): T {
 }
 const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
 
-const base = (inputs: [AudioTrackSet, AudioTrackHeader, ProgramSpace, SynchronizedMedia, AudioClipSpec, TemporalWindow]) => output(appendProjectedAudioItem(...inputs));
+const base = (inputs: [AudioTrackSet, AudioTrackHeader, Timeline, SynchronizedMedia, AudioClipSpec, TemporalWindow]) => output(appendProjectedAudioItem(...inputs));
 
 export const audioTrackComponent = {
   producers: [
     { producer: audioTrackProducers.createSet, handler: () => ({ outputs: { set: output(createAudioTrackSet()) }, needs: {} }) },
     { producer: audioTrackProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: base([
       inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
-      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
+      inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
       inline<AudioClipSpec>(inputs.spec?.value, "AudioClipSpec"),
       inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
     ]) }, needs: {} }) },
@@ -30,7 +30,7 @@ export const audioTrackComponent = {
       inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
     )) }, needs: {} }) },
     { producer: audioTrackProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderAudioTrack(
-      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),
+      inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),
     )) }, needs: {} }) },
   ],
   validators: [{

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

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
 import type { FragmentOperation } from "@hypit/elaborator";
@@ -32,7 +33,7 @@ export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[
       id,
       producer: audioTrackProducers.appendItem,
       inputs: {
-        set: operation(current), header: input("header"), space: input("space"),
+        set: operation(current), header: input("header"), timeline: input("timeline"),
         media: input(item.mediaName), spec: input(item.specName),
         window: input(item.windowName),
       },
@@ -42,18 +43,18 @@ export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[
   });
   operations.push(
     { id: "audio:program", producer: audioTrackProducers.finalize, inputs: { set: operation(current), header: input("header") }, result: { kind: "output", name: "program" } },
-    { id: "audio:track", producer: audioTrackProducers.render, inputs: { space: input("space"), program: operation("audio:program") }, result: { kind: "output", name: "track" } },
+    { id: "audio:track", producer: audioTrackProducers.render, inputs: { timeline: input("timeline"), program: operation("audio:program") }, result: { kind: "output", name: "track" } },
   );
   return sealGraphFragment({
     inputs: [
       { name: "header", type: audioTrackTypes.header },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...[...inputTypes].map(([inputName, type]) => ({ name: inputName, type })),
     ],
     operations,
     exports: [
       { name: "program", type: audioTrackTypes.program, root: operation("audio:program") },
-      { name: "track", type: compositionTypes.audioTrack, root: operation("audio:track") },
+      { name: "audio", type: compositionTypes.audioTrack, root: operation("audio:track") },
     ],
   });
 }

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

@@ -2,6 +2,6 @@ export { audioTrackComponent } from "./component.js";
 export { createAudioTrackFragment, programAudioTrackFragment } from "./fragment.js";
 export type { AudioTrackFragmentItem } from "./fragment.js";
 export { audioClipSpecSchema, audioTrackDependency, audioTrackHeaderSchema, audioTrackManifest, audioTrackMarkupSurfaces, audioTrackModuleRef, audioTrackProducers, audioTrackProgramSchema, audioTrackSetSchema, audioTrackTypes } from "./manifest.js";
-export { decodeAudioTrackSurface } from "./surface.js";
+export { decodeAudioTrackSurface, audioItemDefaults } from "./surface.js";
 export { appendProjectedAudioItem, assertAudioClipSpec, assertAudioTrackHeader, assertAudioTrackProgram, assertAudioTrackSet, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack, sealAudioClipSpec, sealAudioTrackHeader, sealAudioTrackProgram } from "./program.js";
 export type * from "./types.js";