@hypit/hypit 0.1.3 → 0.1.5

package/packages/elevenlabs-speech/src/index.ts

@@ -0,0 +1,111 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationRequestDraft, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const elevenLabsSpeechModuleRef = { name: "@hypit/elevenlabs-speech", version: "1" } as const;
+export const elevenLabsSpeechModels = ["eleven_ttv_v3"] as const;
+export type ElevenLabsSpeechModel = typeof elevenLabsSpeechModels[number];
+
+// ElevenLabs documents a 100 to 1000 character preview text. The port vocabulary
+// carries the ceiling; the floor is stated to authors and enforced by the service.
+const spokenText = { kind: "text", maxChars: 1000 } as const;
+// Voice descriptions have their own documented 20 to 1000 character bounds.
+const instruction = { kind: "text", maxChars: 1000 } as const;
+
+function table(model: ElevenLabsSpeechModel): GenerationPortTable {
+  return sealGenerationPortTable({
+    model,
+    result: "audio",
+    ports: [
+      { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+      { name: "voiceDescription", value: instruction, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const elevenLabsSpeechPorts: Readonly<Record<ElevenLabsSpeechModel, GenerationPortTable>> = {
+  "eleven_ttv_v3": table("eleven_ttv_v3"),
+};
+
+export function sealElevenLabsSpeechRequest(
+  model: ElevenLabsSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(elevenLabsSpeechPorts[model], ports);
+}
+
+export function sealElevenLabsSpeechRequestDraft(
+  model: ElevenLabsSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+) {
+  return sealGenerationRequestDraft(elevenLabsSpeechPorts[model], ports);
+}
+
+const base = defineExactModelModule({
+  module: elevenLabsSpeechModuleRef,
+  endpoints: ([
+    ["voiceDesign", "eleven_ttv_v3", "ElevenLabsVoiceDesignRequest"],
+  ] as const).map(([key, model, requestTypeName]) => ({
+    key,
+    requestTypeName,
+    producerName: `request-${model}`,
+    ports: elevenLabsSpeechPorts[model],
+  })),
+});
+
+export const elevenLabsSpeechEndpoints = base.endpoints;
+
+const spokenAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this speech request and prefixes the binding it publishes.",
+  },
+  {
+    name: "speech",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge whose exact words are spoken.",
+    accepts: [textTypes.text],
+  },
+];
+
+const referencePort: readonly SurfacePortVocabulary[] = [{
+  name: "reference",
+  type: artifactTypes.blob,
+  summary: "The designed voice reference, addressed as `<id>.reference`.",
+}];
+
+export const elevenLabsSpeechMarkupSurfaces = [
+  {
+    name: "voiceDesign", tag: "VoiceDesign", mode: "structured",
+    outputs: [elevenLabsSpeechEndpoints.voiceDesign.draftType],
+    vocabulary: {
+      summary: "Creates a reusable voice reference from a natural-language voice description.",
+      attributes: spokenAttributes,
+      ports: referencePort,
+      text: "The element's own text is the voice description and is required.",
+      example: `<eleven:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</eleven:VoiceDesign>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The spoken sample must be between 100 and 1000 characters.",
+        "The voice description must be between 20 and 1000 characters.",
+        "The result is an ordinary audio Resource that can be supplied anywhere an audio reference is accepted.",
+      ],
+    },
+  },
+] as const;
+
+export const elevenLabsSpeechManifest = { ...base.manifest } as const;
+export const elevenLabsSpeechComponent = base.component;
+export const elevenLabsSpeechDefinition = { ...base, manifest: elevenLabsSpeechManifest };
+
+export { createElevenLabsSpeechAudioFragment } from "./fragment.js";
+export { decodeElevenLabsVoiceDesignSurface } from "./surface.js";

package/packages/elevenlabs-speech/src/surface.ts

@@ -0,0 +1,167 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding } from "@hypit/generation";
+import type { GenerationMediaPort } from "@hypit/generation";
+import { exactModelMediaInputNames, exactModelTextInputName } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+import type { CanonicalValue } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+
+import { createElevenLabsSpeechAudioFragment } from "./fragment.js";
+import { elevenLabsSpeechEndpoints, sealElevenLabsSpeechRequestDraft } from "./index.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function attributes(element: StructuredElement, required: readonly string[]): void {
+  const allowed = new Set(required);
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.has(name));
+  if (unknown.length > 0 || required.some((name) => element.attributes[name] === undefined)) {
+    throw new Error(`${element.name} requires ${required.join(", ")}`);
+  }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function referencePath(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  return value.path;
+}
+
+function resolved(
+  element: StructuredElement,
+  name: string,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const path = referencePath(element, name);
+  const value = resolveReference(path);
+  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+  return value;
+}
+
+function speechText(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  if (!sameType(reference.type, textTypes.text)) throw new Error(`${subject} must reference Text`);
+  const value = reference.record?.value;
+  if (value !== undefined) {
+    if (value.kind !== "inline") throw new Error(`${subject} has an invalid authored Text value`);
+    verifyText(value.value);
+  }
+  return reference;
+}
+
+
+function body(element: StructuredElement, required: boolean): string | undefined {
+  if (element.children.some((child) => child.kind === "element")) {
+    throw new Error(`${element.name} accepts instruction text only`);
+  }
+  const lines = element.children.map((child) => child.kind === "text" ? child.value : "").join("")
+    .replaceAll("\r\n", "\n").split("\n");
+  while (lines[0]?.trim() === "") lines.shift();
+  while (lines.at(-1)?.trim() === "") lines.pop();
+  const indents = lines.filter((line) => line.trim()).map((line) => /^\s*/u.exec(line)?.[0].length ?? 0);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  const value = lines.map((line) => line.slice(indent).trimEnd()).join("\n").trim();
+  if (value.length === 0) {
+    if (required) throw new Error(`${element.name} requires a voice description in its body`);
+    return undefined;
+  }
+  return value;
+}
+
+function output(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  draft: ReturnType<typeof sealElevenLabsSpeechRequestDraft>,
+  outputName: "reference" | "audio",
+  text: readonly { readonly input: ExactModelTextInput; readonly source: SurfaceResolvedReference }[],
+  media: readonly { readonly input: ExactModelMediaInput; readonly source: SurfaceResolvedReference }[] = [],
+) {
+  const id = stringAttribute(element, "id");
+  const draftId = `${id}.draft`;
+  const records: Array<{
+    readonly id: string;
+    readonly type: SurfaceResolvedReference["type"];
+    readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+    readonly range: StructuredElement["range"];
+  }> = [{
+    id: draftId,
+    type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue },
+    range: element.range,
+  }];
+  const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {
+    draft: { kind: "record", id: draftId },
+  };
+  for (const item of text) inputs[exactModelTextInputName(item.input.name)] = item.source.ref;
+  for (const item of media) {
+    const binding = endpoint.mediaBindings[item.input.port];
+    if (binding === undefined) throw new Error(`${endpoint.ports.model} has no media port ${item.input.port}`);
+    const port = generationPort(endpoint.ports, item.input.port);
+    if (port.value.kind !== "media") throw new Error(`${endpoint.ports.model} port ${item.input.port} is not media`);
+    const names = exactModelMediaInputNames(item.input.name);
+    const bindingId = `${id}.${item.input.name}.binding`;
+    records.push({
+      id: bindingId,
+      type: binding.type,
+      value: {
+        kind: "inline",
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: "audio" }) as unknown as CanonicalValue,
+      },
+      range: element.range,
+    });
+    inputs[names.binding] = { kind: "record", id: bindingId };
+    inputs[names.artifact] = item.source.ref;
+  }
+  const fragment = createElevenLabsSpeechAudioFragment(
+    endpoint,
+    media.map((item) => item.input),
+    text.map((item) => item.input),
+  );
+  return {
+    records,
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs,
+      outputs: { audio: `${id}.${outputName}` },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+}
+
+function speechInput(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+) {
+  return {
+    input: { name: "speech", port: "text" },
+    source: speechText(resolved(element, "speech", resolveReference), `${element.name}.speech`),
+  } as const;
+}
+
+export const decodeElevenLabsVoiceDesignSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech"]);
+  return output(
+    element,
+    elevenLabsSpeechEndpoints.voiceDesign,
+    sealElevenLabsSpeechRequestDraft("eleven_ttv_v3", { voiceDescription: [body(element, true)!] }),
+    "reference",
+    [speechInput(element, resolveReference)],
+  );
+};

package/packages/endpoint-kit/README.md

@@ -13,6 +13,12 @@ import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit
 import { generationTypes, compileWireRequest, sealGeneratedImageSet } from "@hypit/hypit/generation";
 ```
 
+The shipped [project Provider example](../../examples/provider-package/README.md) follows an image
+request through configuration, support, upload, submission, receipt, polling, collection and pricing.
+It uses an explicitly illustrative service protocol and imports only public SDK subpaths.
+This SDK also exports `canonicalize`, `BlobRef`, `ResourceId`, `credentialRef` and
+`isStreamingResourceStore` for Providers that construct stored results or use streaming resource IO.
+
 For an existing model, name its exact versioned Capability and expected result Type. Map its request
 ports into the service's wire format; the Provider need not import the model's implementation.
 `@hypit/hypit/generation` supplies the common generated-media values and optional wire-mapping helpers.
@@ -29,6 +35,13 @@ without changing Core demand. Each resource declares a `limit` and optional `uni
 A capability may add `resources` and a pure `unitsForRequest(request)` resolver for quantities of
 already declared resources. Runtime admits all claims atomically for one `fulfill-need` Command.
 
+A long immediate call can report its current activity with
+`await context.reportProgress?.({ phase: "processing", completed: 12, total: 40, unit: "items" })`.
+The Provider chooses meaningful phases and quantities and reports non-secret, human-readable facts.
+The Runtime attaches them to the currently executing Command; they do not change its outcome,
+scheduling or Core facts. Completion clears the live activity. Direct callers may omit the callback.
+For asynchronous work, return `progress` in the existing pending outcome instead.
+
 Asynchronous execution moves forward through `start`, `poll`, and optional `collect`. `start` returns
 a task handle; `pending` means an acknowledged task is still running. `ready` records remote completion
 and hands its artifacts to `collect`, allowing download capacity to differ from task capacity.
@@ -109,3 +122,14 @@ represented by a semantic `pendingInputs` slot instead. A Provider may use the s
 media role to enforce support limits, but it never receives graph traversal rules or future bytes.
 It returns either `supported`, or `unsupported` with the Provider's reason. Selection infrastructure
 preserves that reason without interpreting request fields or maintaining a central limitation table.
+
+An Endpoint can additionally emit explicit, non-secret diagnostics:
+
+```ts
+await context.reportDiagnostic?.({ level: "info", message: "Encoder initialized" });
+```
+
+The Runtime binds each message to this call's Build, Command and Endpoint and owns persistence.
+The Provider does not select a log path or Result repository. Messages describe operational evidence;
+credentials, request bodies and opaque vendor payloads remain private. `reportProgress` continues to
+report current activity; repeated counters are not an append-only log. Phase names belong to the Provider.

package/packages/endpoint-kit/src/index.ts

@@ -20,7 +20,9 @@ import type {
 } from "@hypit/runtime";
 import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
 
-export type { CanonicalValue, CapabilityRef, ModuleRef, StoredValue, TypeRef } from "@hypit/protocol";
+export { canonicalize } from "@hypit/protocol";
+export type { BlobRef, CanonicalValue, CapabilityRef, ModuleRef, ResourceId, StoredValue, TypeRef } from "@hypit/protocol";
+export { credentialRef, isStreamingResourceStore } from "@hypit/runtime";
 export type {
   CapacityResourceClaim,
   CredentialAcquisition,
@@ -97,6 +99,10 @@ export type EndpointInvocationContext = {
   readonly resources: ResourceStore;
   /** Only slots explicitly declared by this configured Endpoint instance are present. */
   readonly credentials: Readonly<Record<string, EndpointCredential>>;
+  /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
+  readonly reportDiagnostic?: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) => Promise<void>;
+  /** Report non-secret activity of a long local call without creating a remote Operation. */
+  readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 
 export type ImmediateEndpointHandler = (

package/packages/estimate/README.md

@@ -14,9 +14,46 @@ hypit measure main.svml --segment opening --language en --pace normal
 hypit measure --text "Video editing begins with meaning." --language en --pace normal --rounding ceil
 ```
 
-The English pace presets are `slow = 4.2`, `normal = 4.6` and `fast = 5.0` syllables per second; a
-positive numeric `rate` replaces `pace`. `round` selects the nearest whole second, `ceil` a
-never-shorter one, `none` keeps the fraction.
+## Units and delivery
+
+English counts pronunciation syllables, not words or letters. Mandarin Chinese counts each Han
+character as one approximate syllable, with English syllables for embedded English words.
+Traditional and simplified Han use the same counting rule; punctuation separates words without
+adding units. This remains an approximation: connected English speech can reduce syllables,
+and Mandarin erhua can combine written characters into one syllable. An explicit `--language zh`
+keeps a Chinese passage with many English names under its intended delivery policy.
+
+Measure the spoken wording. `--segment` reads the Script's pronunciation side of Dual Text;
+`--text` reads literal speech, so spell numbers and letter names as they will be said. A count
+cannot resolve an unspecified pronunciation.
+
+| Language | slow | normal | fast | Unit |
+| --- | ---: | ---: | ---: | --- |
+| English (`en`) | 4.2 | 4.6 | 5.6 | syllables/s |
+| Mandarin Chinese (`zh`) | 4.2 | 5.25 | 6.5625 | approximate syllables/s |
+
+These are authoring starting points for whole-passage delivery, including ordinary speech pauses.
+`normal` suits conversational explanation; `fast` gives brisk, tightly delivered copy less time.
+The English fast preset is deliberately separated from normal so that choosing brisk delivery
+meaningfully changes the estimate. The Chinese normal preset is retained: available research
+does not establish that it is systematically too slow for whole passages. Neither table is a
+calibration of a particular video or voice model. For a specific delivery, a positive numeric
+`--rate` replaces the preset, including rates outside this table.
+
+```bash
+hypit measure main.svml --segment opening --language zh --pace fast --rounding round
+hypit measure main.svml --segment opening --language zh --rate 6 --rounding none
+```
+
+`seconds = pronunciation units / rate + padding`, followed by rounding. Add `--padding` for extra
+time deliberately reserved for a reaction, demonstration or held pause. Ordinary phrasing is
+already part of the chosen density; adding a generic pause allowance on top lengthens the passage
+again. `round` selects the nearest whole second, `ceil` rounds upward, and `none` keeps the fraction.
+The CLI shows the resolved rate and padding; JSON retains full numeric precision.
+
+For 60 Mandarin units, normal gives 11.43 seconds and fast gives 9.14 seconds before rounding.
+For 60 English syllables, normal gives 13.04 seconds and fast gives 10.71 seconds. Equal unit counts
+do not imply equal information, and 60 English words need not contain 60 syllables.
 
 The estimate reports the time the wording needs at that delivery. Use it to decide whether a passage
 needs merging, fuller wording, tightening, or splitting, then choose the request duration with the
@@ -30,3 +67,19 @@ performed media's semantic preparation.
 ```ts
 import { estimateSpeechDuration, sealSpeechEstimatePolicy, speechEstimatePolicyFromRecipe } from "@hypit/estimate";
 ```
+
+## Research basis and limits
+
+[Burchfield and Bradlow (2014)](https://doi.org/10.1121/1.4874357) measured Mandarin and English
+across clear reading, plain reading and spontaneous speech. Plain-reading means were 5.97 and
+5.39 canonical syllables/s respectively. Their articulation measure excludes errors, silence
+and non-speech, so those means cannot directly size an entire performance containing pauses.
+[Coupé et al. (2019)](https://doi.org/10.1126/sciadv.aaw2594) likewise counted canonical syllables
+and excluded pauses longer than 150 ms in their cross-language reading study. These studies
+support distinguishing language, pronunciation units and timing denominator; they do not
+establish one ideal pace for social video or validate these preset values.
+
+When an already understood reference passage provides useful timing, its spoken-unit count
+divided by its first-to-last-word span offers a starting density, including internal pauses.
+Choose how much of that rhythm belongs in the new performance. Requested clip length alone
+is not measured speaking time, and delivery density does not describe emphasis or expression.

package/packages/estimate/src/program.ts

@@ -14,9 +14,9 @@ const PACE_RATE: Readonly<Record<
   ResolvedSpeechEstimateLanguage,
   Readonly<Record<SpeechEstimatePace, number>>
 >> = {
-  // English is calibrated as delivery density, not pause-free articulation rate.
-  en: { slow: 4.2, normal: 4.6, fast: 5 },
-  // Preserve the existing non-English behavior until those languages are audited.
+  // Authoring delivery densities, including ordinary pauses, not measured model
+  // guarantees or pause-free articulation rates. See README for units and rationale.
+  en: { slow: 4.2, normal: 4.6, fast: 5.6 },
   zh: { slow: 4.2, normal: 5.25, fast: 6.5625 },
   ja: { slow: 6, normal: 7.5, fast: 9.375 },
   es: { slow: 4.72, normal: 5.9, fast: 7.375 },
@@ -35,7 +35,7 @@ function looksSpanish(text: string): boolean {
 }
 
 export function detectSpeechEstimateLanguage(text: string): ResolvedSpeechEstimateLanguage {
-  const han = (text.match(/[\u3400-\u9fff]/gu) ?? []).length;
+  const han = (text.match(/\p{Script=Han}/gu) ?? []).length;
   const kana = (text.match(/[\u3040-\u30ff]/gu) ?? []).length;
   const ascii = (text.match(/[A-Za-z]/gu) ?? []).length;
   if (kana > Math.max(han, ascii / 4)) return "ja";
@@ -117,10 +117,9 @@ export function countSpeechEstimateUnits(
   language: ResolvedSpeechEstimateLanguage,
 ): number {
   if (language === "zh" || language === "ja") {
-    const cjk = (text.match(/[\u3400-\u9fff\u3040-\u30ff]/gu) ?? []).length;
-    const latin = text
-      .replace(/[\u3400-\u9fff\u3040-\u30ff]/gu, " ")
-      .split(/\s+/u)
+    const characters = /[\p{Script=Han}\u3040-\u30ff]/gu;
+    const cjk = (text.match(characters) ?? []).length;
+    const latin = words(text.replace(characters, " "))
       .filter((word) => /[A-Za-z]/u.test(word));
     return cjk + latin.reduce((sum, word) => sum + englishSyllables(word), 0);
   }

package/packages/film/README.md

@@ -1,8 +1,7 @@
 # `@hypit/film`
 
-The Surface accepts `semantic={speech.semantic}` for performance time or `space={animation}` for an
-authored ProgramSpace. Its Fragment receives `space` directly; rendering does not require Script
-or prepared performance media. Both time sources use the same frame and audio pipeline.
+The Surface, Fragment and assembly Producers receive the same Timeline through a `timeline` input.
+Partial, overlapping or absent semantic coverage all use that complete range.
 
 Official package-owned assembly layer between peer Tracks and the generic Composition waist.
 Film is an ordinary author component and an optional Target, not a Core root or a privileged video
@@ -21,9 +20,9 @@ belongs to each Present's absolute stacking key.
 
 The official Structured Surface validates an imported generic SVS Recipe into a nominal
 `FilmProgram`, receives CanvasSpace and the selected time source through separate explicit edges,
-projects ProgramSpace when that source is a SemanticTrack, type-checks
+passes the Timeline directly, type-checks
 each `<film:Track source={...}/>` reference and generates the finite fold. CanvasSpace is the only
-dimension truth, ProgramSpace is the only frame-rate truth, and FilmProgram owns only assembly
+dimension truth, Timeline is the only time-range truth, and FilmProgram owns only assembly
 identity and clear color.
 Child order is organizational: Track and Present identity, timing and absolute stacking remain in
 their own typed values. Final rendering is a separate author package and capability.
@@ -31,10 +30,16 @@ their own typed values. Final rendering is a separate author package and capabil
 For example, after the named inputs are declared:
 
 ```svml
-<film:Film id="main" canvas={vertical} semantic={speech.semantic}
+<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={vertical} timeline={speech.timeline}
   appearance={recipes.film.vertical}>
   <film:Track source={performance.visual}/>
-  <film:Track source={speech.audio}/>
+  <film:Track source={voice.audio}/>
   <film:Track source={coverage.visual}/>
   <film:Track source={captions.track}/>
   <film:Track source={music.track}/>

package/packages/film/package.json

@@ -16,7 +16,7 @@
     "@hypit/elaborator": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/markup": "workspace:*",

package/packages/film/src/component.ts

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CanvasSpace } from "@hypit/spatial";
 import type { AudioTrack, VisualTrack } from "@hypit/composition";
 import type { StoredValue } from "@hypit/protocol";
@@ -28,7 +28,7 @@ export const filmComponent = {
       handler: ({ inputs }) => ({
         outputs: { set: { kind: "inline", value: canonicalize(appendFilmVisualTrack(
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<VisualTrack>(inputs.track?.value, "VisualTrack"),
         )) } },
         needs: {},
@@ -39,7 +39,7 @@ export const filmComponent = {
       handler: ({ inputs }) => ({
         outputs: { set: { kind: "inline", value: canonicalize(appendFilmAudioTrack(
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<AudioTrack>(inputs.track?.value, "AudioTrack"),
         )) } },
         needs: {},
@@ -51,7 +51,7 @@ export const filmComponent = {
         outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(
           inline<FilmProgram>(inputs.program?.value, "FilmProgram"),
           inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
-          inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+          inline<Timeline>(inputs.timeline?.value, "Timeline"),
           inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
         )) } },
         needs: {},

package/packages/film/src/fragment.ts

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { spatialTypes } from "@hypit/spatial";
 import { compositionTypes } from "@hypit/composition";
 import type { Track } from "@hypit/composition";
@@ -12,7 +13,7 @@ const input = (name: string) => ({ kind: "fragment-input" as const, name });
 const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
 
 function assertTrackInputs(tracks: readonly FilmTrackInput[]): FilmTrackInput[] {
-  const names = new Set(["program", "canvas", "space"]);
+  const names = new Set(["program", "canvas", "timeline"]);
   return [...tracks]
     .map((track) => ({ name: track.name.trim(), kind: track.kind }))
     .sort((left, right) => left.name.localeCompare(right.name))
@@ -45,7 +46,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     operations.push({
       id,
       producer: track.kind === "visual" ? filmProducers.appendVisualTrack : filmProducers.appendAudioTrack,
-      inputs: { set: operation(current), space: input("space"), track: input(track.name) },
+      inputs: { set: operation(current), timeline: input("timeline"), track: input(track.name) },
       result: { kind: "output" as const, name: "set" },
     });
     current = id;
@@ -56,7 +57,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     inputs: {
       program: input("program"),
       canvas: input("canvas"),
-      space: input("space"),
+      timeline: input("timeline"),
       set: operation(current),
     },
     result: { kind: "output" as const, name: "composition" },
@@ -65,7 +66,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)
     inputs: [
       { name: "program", type: filmTypes.program },
       { name: "canvas", type: spatialTypes.canvas },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...tracks.map((track) => ({
         name: track.name,
         type: track.kind === "visual" ? compositionTypes.visualTrack : compositionTypes.audioTrack,

package/packages/film/src/manifest.ts

@@ -1,8 +1,10 @@
+import { timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@hypit/composition";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import { spatialDependency, spatialTypes } from "@hypit/spatial";
 import { svsManifest, svsModuleRef, svsRecipeType } from "@hypit/svs";
 
@@ -47,7 +49,7 @@ export const filmMarkupSurfaces = [{
     outputs: [filmTypes.program],
     vocabulary: {
       summary:
-        "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a SemanticTrack.",
+        "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a Timeline.",
       appearance:
         "One flat fill of the entire Canvas, in the single hexadecimal color the Recipe's `background` carries, lying behind everything else in the Frame. It covers the full Canvas width and height, holds that one color from the first Frame to the last, and never moves, fades or changes. Wherever nothing is painted over it, that color is what the Frame shows; the Film puts no mark of its own on top of it.",
       attributes: [
@@ -79,9 +81,9 @@ export const filmMarkupSurfaces = [{
           summary: "The assembled Composition, addressed as `<id>.composition`." },
       ],
       example: [
-        '<film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>',
+        '<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>',
         "  <film:Track source={performance.visual}/>",
-        "  <film:Track source={speech.audio}/>",
+        "  <film:Track source={voice.audio}/>",
         "  <film:Track source={captions.track}/>",
         "</film:Film>",
       ].join("\n"),
@@ -99,8 +101,7 @@ export const filmManifest: ModuleManifest = {
   name: filmModuleRef.name,
   version: filmModuleRef.version,
   dependencies: [
-    programSpaceDependency,
-    semanticTrackDependency,
+    timelineDependency,
     spatialDependency,
     compositionDependency,
     { module: svsModuleRef },
@@ -121,7 +122,7 @@ export const filmManifest: ModuleManifest = {
       name: filmProducers.appendVisualTrack.name,
       inputs: [
         { name: "set", type: filmTypes.trackSet },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "track", type: compositionTypes.visualTrack },
       ],
       outputs: [{ name: "set", type: filmTypes.trackSet }],
@@ -131,7 +132,7 @@ export const filmManifest: ModuleManifest = {
       name: filmProducers.appendAudioTrack.name,
       inputs: [
         { name: "set", type: filmTypes.trackSet },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "track", type: compositionTypes.audioTrack },
       ],
       outputs: [{ name: "set", type: filmTypes.trackSet }],
@@ -142,7 +143,7 @@ export const filmManifest: ModuleManifest = {
       inputs: [
         { name: "program", type: filmTypes.program },
         { name: "canvas", type: spatialTypes.canvas },
-        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "timeline", type: timelineTypes.track },
         { name: "set", type: filmTypes.trackSet },
       ],
       outputs: [{ name: "composition", type: compositionTypes.composition }],