@hypit/hypit 0.1.3 → 0.1.5

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

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import {
   assertSpatialFrame,
   assertSpatialPath,
@@ -304,7 +304,7 @@ function append(
 export function appendProjectedTextItem(
   set: TypographyTrackSet,
   header: TypographyTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   placement: TextPlacement,
   spec: TextItemSpec,
   style: TextStyle,
@@ -312,7 +312,7 @@ export function appendProjectedTextItem(
   window: ProjectedWindow,
 ): TypographyTrackSet {
   assertTextPlacement(placement);
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
   return append(set, header, spec, style, motion, placement.geometry, window);
 }
 
@@ -332,18 +332,18 @@ export function sealTypographyTrackProgram(value: TypographyTrackProgram): Typog
   return programContent(value);
 }
 
-export function assertTypographyTrackProgramIdentity(program: TypographyTrackProgram, space: ProgramSpace): void {
-  assertProgramSpaceIdentity(space);
+export function assertTypographyTrackProgramIdentity(program: TypographyTrackProgram, timeline: Timeline): void {
+  assertProgramSpaceIdentity(timeline);
   nonEmpty(program.id, "TypographyTrackProgram id");
   if (program.items.length === 0) throw new Error("TypographyTrackProgram has no Items.");
-  const total = programSpaceFrameCount(space);
+  const total = programSpaceFrameCount(timeline);
   const ids = new Set<string>();
   for (const item of program.items) {
     nonEmpty(item.id, "Text Item id");
     if (ids.has(item.id)) throw new Error(`TypographyTrackProgram repeats ${item.id}.`);
     ids.add(item.id);
     if (item.span.startFrame < 0 || item.span.endFrameExclusive <= item.span.startFrame || item.span.endFrameExclusive > total) {
-      throw new Error(`${item.id} is outside ProgramSpace.`);
+      throw new Error(`${item.id} is outside Timeline.`);
     }
     assertGeometry(item.geometry);
     assertDocument(item.document, `${item.id} document`);
@@ -556,10 +556,10 @@ function elements(item: TextItem): VisualElement[] {
   return [root, motion, terminalTextElement(item, "motion", 2)];
 }
 
-export function renderTypographyTrack(space: ProgramSpace, program: TypographyTrackProgram): VisualTrack {
-  assertTypographyTrackProgramIdentity(program, space);
+export function renderTypographyTrack(timeline: Timeline, program: TypographyTrackProgram): VisualTrack {
+  assertTypographyTrackProgramIdentity(program, timeline);
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: program.id,
     presents: program.items.map((item) => ({
@@ -569,24 +569,24 @@ export function renderTypographyTrack(space: ProgramSpace, program: TypographyTr
       elements: elements(item),
     })),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }
 
 export function renderTextMaskTrack(
-  space: ProgramSpace,
+  timeline: Timeline,
   program: TypographyTrackProgram,
   material: CompositableSurfaceRef,
   spec: TextMaskSpec,
 ): VisualTrack {
-  assertTypographyTrackProgramIdentity(program, space);
+  assertTypographyTrackProgramIdentity(program, timeline);
   assertCompositableSurfaceRef(material);
   assertTextMaskSpec(spec);
   if (material.timing.kind !== "still") {
     throw new Error("Official Text Mask requires one explicit still material Surface; timed materials use an independent package.");
   }
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: spec.id,
     presents: program.items.map((item) => {
@@ -617,6 +617,6 @@ export function renderTextMaskTrack(
       };
     }),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }

package/packages/typography-track/src/surface.ts

@@ -1,5 +1,6 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
+
 import { compositionTypes } from "@hypit/composition";
 import type {
   VisualColorPaint,
@@ -649,7 +650,7 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
     }
     const append = `text:set:append:${String(index + 1).padStart(4, "0")}`;
     const common = {
-      set: operation(current), header: input("header"), space: input("space"), placement: operation(bind),
+      set: operation(current), header: input("header"), timeline: input("timeline"), placement: operation(bind),
       spec: item.contentName === undefined ? input(item.specName) : operation(materialized),
       style: input(item.styleName), motion: input(item.motionName), window: input(item.windowName),
     };
@@ -658,10 +659,10 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
   }
   operations.push(
     { id: "text:finalize", producer: typographyTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },
-    { id: "text:render", producer: typographyTrackProducers.render, inputs: { space: input("space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
+    { id: "text:render", producer: typographyTrackProducers.render, inputs: { timeline: input("timeline"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
   );
   const inputEntries = [
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "header", type: typographyTrackTypes.header },
     ...items.flatMap((item) => [
       { name: item.geometryName, type: item.placementKind === "point" ? spatialTypes.point : item.placementKind === "area" ? spatialTypes.frame : spatialTypes.path },
@@ -688,10 +689,9 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF
 }
 
 export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space"], ["id"]);
+  allowed(element, ["id", "timeline"], ["id"]);
   const id = text(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const headerId = `${id}.__header`;
   const records: SurfaceRecordDraft[] = [{
     id: headerId, type: typographyTrackTypes.header,
@@ -699,8 +699,8 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
   }];
   const defaultMotionId = `${id}.__still-motion`;
   records.push({ id: defaultMotionId, type: typographyTrackTypes.motion, value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range });
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
-  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
   const items: Array<FragmentItem & {
     readonly geometry: SurfaceResolvedReference;
     readonly style: SurfaceResolvedReference;
@@ -731,7 +731,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
       "id", "content", "placement", "style", "motion", ...temporalWindowAttributeNames,
     ], ["id", "placement", "style"]);
     const itemId = text(child, "id");
-    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, space: time.space, resolveReference });
+    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, resolveReference });
     records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
     const placementKind = form.toLowerCase() as "point" | "area" | "path";
     const geometry = reference(child.attributes.placement, `${child.name}.placement`, placementKind === "point" ? spatialTypes.point : placementKind === "area" ? spatialTypes.frame : spatialTypes.path, resolveReference);
@@ -777,7 +777,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
     components: [...temporalComponents, {
       id, fragment: fragment.id,
       inputs: {
-        space: time.space.ref, header: { kind: "record", id: headerId },
+        timeline: context.timeline.ref, header: { kind: "record", id: headerId },
         ...Object.fromEntries(items.flatMap((item) => [
           [item.geometryName, item.geometry.ref], [item.specName, { kind: "record" as const, id: item.specId }],
           [item.windowName, item.window],
@@ -794,7 +794,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element
 
 function createMaskFragment(id: string): GraphFragment {
   const inputs = [
-    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "timeline", type: timelineTypes.track },
     { name: "program", type: typographyTrackTypes.program },
     { name: "material", type: mediaTypes.compositableSurface },
     { name: "spec", type: typographyTrackTypes.maskSpec },
@@ -804,7 +804,7 @@ function createMaskFragment(id: string): GraphFragment {
     operations: [
       {
         id: "text-mask:render", producer: typographyTrackProducers.renderMask,
-        inputs: { space: input("space"), program: input("program"), material: input("material"), spec: input("spec") },
+        inputs: { timeline: input("timeline"), program: input("program"), material: input("material"), spec: input("spec") },
         result: { kind: "output", name: "track" },
       },
     ],
@@ -815,11 +815,10 @@ function createMaskFragment(id: string): GraphFragment {
 }
 
 export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space", "text", "material", "mode", "fit"], ["id", "text", "material"]);
+  allowed(element, ["id", "timeline", "text", "material", "mode", "fit"], ["id", "text", "material"]);
   empty(element);
   const id = text(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const program = reference(element.attributes.text, `${element.name}.text`, typographyTrackTypes.program, resolveReference);
   const material = reference(element.attributes.material, `${element.name}.material`, mediaTypes.compositableSurface, resolveReference);
   const specId = `${id}.__spec`;
@@ -831,12 +830,12 @@ export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element,
   const fragment = createMaskFragment(id);
   return {
     records: [{ id: specId, type: typographyTrackTypes.maskSpec, value: { kind: "inline", value: spec }, range: element.range }],
-    components: [...time.components, {
+    components: [{
       id, fragment: fragment.id,
-      inputs: { space: time.space.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
+      inputs: { timeline: context.timeline.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
       outputs: { track: `${id}.track` }, range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
     exports: [`${id}.track`],
   };
 };

package/packages/typography-track-studio/package.json

@@ -4,11 +4,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
   "type": "module",
-  "exports": { ".": "./src/index.ts" },
-  "hypit": { "activation": "./src/activation.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
   "dependencies": {
     "@hypit/composition": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
-    "@hypit/typography-track": "workspace:*"
+    "@hypit/typography-track": "workspace:*",
+    "@hypit/fonts-open": "workspace:*"
   }
 }

package/packages/typography-track-studio/src/index.ts

@@ -1,9 +1,12 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
 import { typographyTrackMarkupSurfaces, typographyTrackModuleRef, typographyTrackTypes } from "@hypit/typography-track";
 import type { TypographyTrackProgram } from "@hypit/typography-track";
 import { compositionTypes } from "@hypit/composition";
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
 import { childEntities, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource, textLayer } from "@hypit/studio-adapter";
 
+const fontInspector = openFontStudioFields("style");
+
 const typographyProperties = (typographyTrackMarkupSurfaces
   .find((surface) => surface.name === "style")?.vocabulary.attributes
   .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
@@ -105,11 +108,12 @@ export const typographyTrackStudioTrackCompanions: readonly StudioTrackCompanion
       { name: "content" },
       {
         name: "style",
+        referenced: [fontInspector.binding],
         recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
       },
       { name: "motion" },
     ],
-    inspector: typographyInspector,
+    inspector: [...fontInspector.fields, ...typographyInspector],
     requiredValues: ["program"], project: projectTypography,
     lane: { heightPx: 48 },
   },

package/packages/video-cli/README.md

@@ -37,14 +37,26 @@ Result or state. It names the Endpoint and its price page before it runs, and wr
 to the chosen file. `measure` estimates a passage locally:
 
 ```bash
-hypit transcribe reference.mp4 --to notes/reference.transcript.json [--language en|zh|es]
+hypit transcribe reference.mp4 --to notes/reference.transcript.json --language en
 hypit measure main.svml --segment hook --language en --pace normal --rounding round
 ```
 
+For `transcribe`, set `--language` to the spoken language: `en`, `zh` or `es`. Chinese speech uses `zh`, including
+Chinese speech containing English names; the requested language selects the recognition/alignment
+model, independently of the eventual caption font or script's simplified/traditional characters.
+
 `transcribe` uses the Profile's `whisperx-alignment` Endpoint (after
-extracting 16 kHz mono speech audio with ffmpeg). `measure` counts a Segment's pronunciation units at a
-delivery policy and prints the seconds to write as the literal `duration`; it opens no Profile and
-spends nothing. `--runtime <profile>` names the Profile; otherwise the project's `hypit runtime use`
+extracting 16 kHz mono speech audio with ffmpeg). Direct invocation forwards the Provider's progress
+and diagnostic callbacks; the CLI reports phase changes while waiting, with JSON progress on the
+separate progress stream when supplied. Immediate invocation has no durable remote task receipt and
+does not become resumable merely because it reports progress. `measure` counts a Segment's pronunciation units at a
+delivery policy and prints estimated seconds, the resolved rate, padding and rounding. Choose the
+literal `duration` from that estimate and the intended performance. `measure` opens no Profile and
+spends nothing. It accepts `--pace slow|normal|fast` or `--rate <units/s>`; JSON includes the resolved
+`rate` even when using a named pace. [Estimate](../estimate/README.md#units-and-delivery) explains
+Chinese/English units and choosing a whole-passage density.
+
+For `transcribe`, `--runtime <profile>` names the Profile; otherwise the project's `hypit runtime use`
 selection is read. Anything the Author Graph declares as an output is a Build, however quickly it
 comes back: pictures, clips and accepted voice references (`@hypit/mimo-speech`) carry the identity of the Source
 that produced them, so they are declared in the Source and go through `plan` and `build`. To hear a

package/packages/video-cli/package.json

@@ -20,6 +20,7 @@
     "@hypit/markup": "workspace:*",
     "@hypit/model-kit": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/provider-hypihub": "workspace:*",
     "@hypit/runtime": "workspace:*",
@@ -32,6 +33,6 @@
     "@hypit/whisperx": "workspace:*",
     "@hypit/workspace-fs-node": "workspace:*",
     "@hypit/yt-dlp": "workspace:*",
-    "sharp": "0.35.3"
+    "sharp": "0.35.4"
   }
 }

package/packages/video-cli/src/creation.ts

@@ -2,18 +2,20 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-import { findRuntimeProfile, loadDiscoveredSourcePackages, resolveProjectRoot } from "@hypit/cli";
+import { loadDiscoveredSourcePackages } from "@hypit/cli";
+import { findRuntimeProfile, resolveProjectRoot } from "@hypit/project-context-node";
 import type { CliIo } from "@hypit/cli";
 import { MemoryResourceStore } from "@hypit/driver-node";
 import {
   countSpeechEstimateUnits,
   estimateSpeechDuration,
   resolveSpeechEstimateLanguage,
+  resolveSpeechEstimateRate,
   speechEstimatePolicyFromAttributes,
 } from "@hypit/estimate";
 import type { CanonicalValue, CapabilityRef, Need, StoredValue } from "@hypit/protocol";
 import type { ResourceStore } from "@hypit/runtime";
-import type { RuntimeHostCapabilityProvider, RuntimeHostProviderQuery } from "@hypit/runtime-host-node";
+import type { RuntimeHostCapabilityProvider, RuntimeHostProviderQuery, RuntimeInvocationObservation } from "@hypit/runtime-host-node";
 import { sealSpeechEvidenceAudio } from "@hypit/speech";
 import { speechEvidenceTypes } from "@hypit/speech-evidence";
 import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
@@ -31,7 +33,7 @@ export type CreationCommand = typeof creationCommands[number];
 /** The slice of the Runtime host these commands use; tests hand in a fake. */
 export type CreationHost = {
   providers(requests: readonly RuntimeHostProviderQuery[]): Promise<readonly RuntimeHostCapabilityProvider[]>;
-  invoke(need: Need, resources: ResourceStore): Promise<{ readonly value: StoredValue }>;
+  invoke(need: Need, resources: ResourceStore, observation?: RuntimeInvocationObservation): Promise<{ readonly value: StoredValue }>;
 };
 
 export type CreationEnvironment = {
@@ -275,8 +277,9 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
   const parsed = parseArguments(argv, ["--language", "--to", "--runtime", "--workspace"]);
   assert(parsed.positionals.length === 1, "transcribe takes exactly one audio or video file");
   const source = resolve(environment.cwd, parsed.positionals[0]!);
-  const language = parsed.options.get("--language") ?? "en";
-  assert(language === "en" || language === "zh" || language === "es", "--language must be en, zh or es");
+  const language = parsed.options.get("--language");
+  assert(language === "en" || language === "zh" || language === "es",
+    "transcribe requires --language en|zh|es for the spoken language (use --language zh for Chinese)");
   const to = await destination(parsed, environment.cwd);
   const { profile, host } = await environment.openHost(
     parsed.options.get("--runtime"),
@@ -295,7 +298,16 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
   };
   const provider = await selectedProvider(host, need, profile);
   if (!parsed.json) io.write(`Transcribing through ${providerLine(provider)}\n`);
-  const fulfillment = await host.invoke(need, resources);
+  const report = parsed.json ? io.writeProgress : io.writeProgress ?? io.write;
+  let previousPhase: string | undefined;
+  const fulfillment = await host.invoke(need, resources, {
+    reportProgress: async (progress) => {
+      if (progress.phase === previousPhase) return;
+      previousPhase = progress.phase;
+      report?.(`  · ${progress.phase}\n`);
+    },
+    reportDiagnostic: async (diagnostic) => { report?.(`  · ${diagnostic.message}\n`); },
+  });
   assert(fulfillment.value.kind === "inline", "the transcript came back by reference");
   const passages = passagesInSeconds(fulfillment.value.value as unknown as AlignedTranscriptEvidence);
   const words = passages.reduce((total, passage) => total + passage.words.length, 0);
@@ -382,6 +394,7 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
   }
   const pace = parsed.options.get("--pace");
   const rate = parsed.options.get("--rate");
+  assert(pace === undefined || rate === undefined, "measure takes either --pace or --rate, not both");
   const policy = speechEstimatePolicyFromAttributes({
     language: parsed.options.get("--language") ?? "auto",
     ...(rate === undefined ? { pace: pace ?? "normal" } : { rate }),
@@ -391,6 +404,7 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
   const language = resolveSpeechEstimateLanguage(text, policy.language);
   const units = countSpeechEstimateUnits(text, language);
   const seconds = estimateSpeechDuration(sealText(text), policy);
+  const resolvedRate = resolveSpeechEstimateRate(policy, language);
   const view = {
     format: "hypit.video-cli-measure@1",
     ...where,
@@ -398,11 +412,13 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
     units,
     language,
     policy,
+    rate: resolvedRate,
     seconds,
   };
   if (parsed.json) { io.write(`${JSON.stringify(view, null, 2)}\n`); return; }
-  const delivery = policy.rate === undefined ? `${policy.pace} pace` : `${policy.rate} units/s`;
-  io.write(`${seconds}s\n\n  ${units} pronunciation units · ${language} · ${delivery} · rounding ${policy.rounding}\n`
+  const delivery = `${resolvedRate} units/s${policy.pace === undefined ? "" : ` (${policy.pace})`}`;
+  io.write(`${Number(seconds.toFixed(3))}s\n\n  ${units} pronunciation units · ${language} · ${delivery}\n`
+    + `  padding ${policy.paddingSec ?? 0}s · rounding ${policy.rounding}\n`
     + `  ${"segment" in where ? `${where.segment} in ${where.source}` : `${text.length} characters`}\n`
     + "  Choose the request duration from this estimate, the intended performance, and the selected model's supported values.\n");
 }
@@ -416,7 +432,7 @@ export function writeCreationHelp(io: CliIo, topic?: CreationCommand): void {
       "hypit transcribe",
       "Establish word times with the whisperx-alignment Endpoint of the selected Runtime Profile.",
       "",
-      "  hypit transcribe <audio|video> --to <transcript.json> [--language en|zh|es] [--runtime <profile>] [--workspace <project>]",
+      "  hypit transcribe <audio|video> --to <transcript.json> --language en|zh|es [--runtime <profile>] [--workspace <project>]",
       "",
       "Extracts 16 kHz mono speech audio with ffmpeg and writes every word with its start and end in",
       "seconds. One immediate request; no Build, Result or state.",

package/packages/video-cli/src/index.ts

@@ -28,7 +28,7 @@ export { runCaptureCli, writeCaptureHelp } from "./capture.js";
 export { listPackages, listSurfaces, runVocabularyCli, visualSchema, writeVocabularyHelp } from "./vocabulary.js";
 export type { PackageListing, SurfaceListing } from "./vocabulary.js";
 /** The project's selected Runtime Profile, read the way `hypit` reads it, for tools that run beside the CLI. */
-export { findRuntimeProfile } from "@hypit/cli";
+export { findRuntimeProfile } from "@hypit/project-context-node";
 
 export function runVideoCli(
   argv: readonly string[],

package/packages/video-cli/src/studio-distribution.ts

@@ -11,9 +11,10 @@ export const videoStudioCompanionPackages = [
   "@hypit/deck-track-studio",
   "@hypit/film-studio",
   "@hypit/media-track-studio",
+  "@hypit/performance-studio",
   "@hypit/ranking-studio",
   "@hypit/screen-overlay-studio",
   "@hypit/script-studio",
-  "@hypit/speech-track-studio",
+  "@hypit/sound-studio",
   "@hypit/typography-track-studio",
 ] as const;

package/packages/volcengine-matting/README.md

@@ -30,20 +30,20 @@ formats. The service's flat-background MP4 option is a different output treatmen
 This excerpt assumes the performance and Script exist. Normalize keeps the transparent picture
 and prepares the selected embedded audio on the program clock. WhisperX and semantic alignment
 associate that prepared performance with the Script. Use `opening-semantic.take` in
-[Speech Track](../speech-track/README.md); its screen position and stack order are independent
+[Timeline assembly](../timeline-author/README.md); its screen position and stack order are independent
 of its role as A-roll.
 
 For B-roll, normalize `cutout.video` with `audio="none"` when its sound is unwanted, then use
 `cutout-media.media` in [Media Track](../media-track/README.md). No SemanticTake is needed for
 that overlay. Existing transparency can enter Normalize directly.
 
-For example, this alternative uses the existing program's SemanticTrack and an authored Selection:
+For example, this alternative uses the existing program's Timeline and an authored Selection:
 
 ```svml
 <import as="media-track" from="@hypit/media-track@1"/>
 <pipeline:Normalize id="overlay-media" source={cutout.video} clock={clock}
   video="primary-moving" audio="none" span-authority="video"/>
-<media-track:Track id="overlay" semantic={speech.semantic} canvas={canvas}>
+<media-track:Track id="overlay" timeline={speech.timeline} canvas={canvas}>
   <media-track:Item media={overlay-media.media} during={story.selection.example}
     frame={overlay-frame} appearance={look.media.overlay}/>
 </media-track:Track>

package/packages/whisperx/README.md

@@ -17,6 +17,13 @@ projects the Take's audio to canonical 16 kHz mono `SpeechEvidenceAudio`; Whispe
 bytes. A deterministic local alignment then combines the returned evidence with the Segment and
 emits one self-contained `SemanticTake`.
 
+For Chinese speech, select `zh` (also `hypit transcribe --language zh` for a reference). WhisperX's
+Chinese alignment emits character-sized words, including letters inside some Latin names. The
+evidence adapter preserves those windows; the local alignment maps them onto Script's units, so
+a complete Latin name can consume several evidence words while neighboring Han characters retain
+their own times. Caption gets its displayed wording and Cue breaks from Script, independently of
+the recognizer's punctuation or simplified/traditional spelling.
+
 When the authored Segment has no Tokens, write the same Surface without `language`. Its start and
 end Anchors map directly to the prepared media's first and final frame. There are no words to align,
 so this branch requests no evidence audio and no WhisperX capability:
@@ -26,7 +33,7 @@ so this branch requests no evidence audio and no WhisperX capability:
   segment={story.segment.pause} media={pause-media.media}/>
 ```
 
-There is no whole-program WhisperX pass. Speech Track only receives already-semantic Takes and later
+There is no whole-program WhisperX pass. Timeline assembly only receives already-semantic Takes and later
 translates their local frames when assembling the final ProgramSpace and complete semantic map.
 
 `@hypit/provider-hypihub` is the default concrete adapter; it uploads the canonical evidence audio

package/packages/workspace/src/index.ts

@@ -9,6 +9,8 @@ import type { BlobRef } from "@hypit/protocol";
 /** Repeatably openable transfer bytes admitted by the selected Workspace. */
 export type ArtifactAttachment = {
   readonly artifact: BlobRef;
+  /** Stable external address, when the Workspace supplies a file by reference. */
+  readonly location?: string;
   open(): Awaitable<AsyncIterable<Uint8Array>>;
 };
 

package/packages/workspace-fs-node/README.md

@@ -4,7 +4,10 @@ Reference Node filesystem implementation of the host-neutral `Workspace` contrac
 
 Every `open()` call creates one isolated compilation session. It canonicalizes real paths, confines
 local SourceUnit and Source Asset reads to the configured root, rejects symlink escapes, locks each
-edge to the first bytes observed and returns defensive Resource attachments.
+Source edge to the first bytes observed and returns defensive Resource attachments. File attachments
+also carry their resolved `file:` URI so Result publication can preserve the external reference.
+The Resource's identity and metadata belong to the compilation session; its file remains a live
+dependency rather than becoming a persistent snapshot.
 
 A Host may supply an external Source resolver. One explicit non-relative Source locator can then
 open a SourceUnit in a separate canonical root; that Source's relative imports and assets remain

package/packages/workspace-fs-node/src/workspace.ts

@@ -1,3 +1,4 @@
+import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readFile, realpath, stat } from "node:fs/promises";
@@ -177,6 +178,7 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
     if (!this.#attachments.has(attachmentKey)) {
       this.#attachments.set(attachmentKey, {
         artifact: { ...artifact },
+        location: pathToFileURL(canonical).href,
         open: () => createReadStream(canonical),
       });
     }
@@ -189,7 +191,7 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
         const byResource = left.artifact.resource.localeCompare(right.artifact.resource);
         return byResource === 0 ? left.artifact.mediaType.localeCompare(right.artifact.mediaType) : byResource;
       })
-      .map((item) => ({ artifact: { ...item.artifact }, open: item.open }));
+      .map((item) => ({ ...item, artifact: { ...item.artifact } }));
   }
 }
 

package/services/whisperx/README.md

@@ -71,6 +71,14 @@ Configuration is deployment state:
 The Node Provider must configure the same model, device, compute, batch size, service version and
 WhisperX version. A mismatch fails before transcription results are accepted.
 
+## Package preparation
+
+Local package preparation includes `src/**/*.py` in uv's package cache inputs. Updating service code
+therefore rebuilds its small wheel instead of reusing one selected only by an unchanged
+`pyproject.toml`. This leaves dependency and speech-model caches intact. See
+[uv's local dependency caching](https://docs.astral.sh/uv/concepts/cache/#dynamic-metadata).
+This governs package installation; an already running service continues using its loaded code.
+
 ## Queue and concurrency
 
 The SVML Runtime Scheduler decides how many WhisperX Needs may enter this Provider lane. One service
@@ -80,3 +88,9 @@ second direct request receives `503 BUSY` instead of entering a hidden service q
 
 Run multiple service processes on different devices/ports only when the Runtime registers and
 locks them as distinct Provider instances.
+
+The local Provider reconciles this packaged project through `uv sync` before a cold service start.
+A passing version probe alone cannot establish that same-version checkout edits were installed;
+the declared uv source cache keys decide whether the service wheel needs rebuilding. A healthy
+running service remains untouched. To adopt edited service code, stop that selected helper when idle
+and start it again through its Profile; restarting only the Build Worker does not reinstall Python.

package/services/whisperx/pyproject.toml

@@ -24,3 +24,5 @@ where = ["src"]
 
 [tool.uv]
 package = true
+# Rebuild this small service wheel when its packaged Python implementation changes.
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/**/*.py" }]

package/services/whisperx/uv.lock

@@ -867,6 +867,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a8/af/48ac8483240de756d2438c380746e7130d1c6f75802ef22f3c6d49982787/huggingface_hub-0.36.2-py3-none-any.whl", hash = "sha256:48f0c8eac16145dfce371e9d2d7772854a4f591bcb56c9cf548accf531d54270", size = 566395, upload-time = "2026-02-06T09:24:11.133Z" },
 ]
 
+[[package]]
+name = "hypit-whisperx-service"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
+    { name = "whisperx" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "numpy", specifier = ">=2.1,<3" },
+    { name = "whisperx", specifier = "==3.8.6" },
+]
+
 [[package]]
 name = "idna"
 version = "3.18"
@@ -1410,7 +1427,7 @@ wheels = [
 
 [[package]]
 name = "nltk"
-version = "3.10.2"
+version = "3.10.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "click" },
@@ -1419,9 +1436,9 @@ dependencies = [
     { name = "regex" },
     { name = "tqdm" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/72/16/24d639531e73cbc6884fb251d116dfe469df9c595e0dcf24668c54d0e8d3/nltk-3.10.2.tar.gz", hash = "sha256:fcfd80fb77931868cea8357573c79838b8abc609942ef9914d1c9f6070d4645c", size = 3101716, upload-time = "2026-08-05T09:56:20.657Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e0/e6/fe51d2bb1a3b446f59c5c8165999a9fee208bc346af90a7cbf7657bc0d75/nltk-3.10.3.tar.gz", hash = "sha256:bb9327a461c3811c2fa4900e03840401f2126adfb30c0072827c433bd2444ea4", size = 5137152, upload-time = "2026-08-12T23:46:37.258Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1f/2b/bf677eb32ca6684b270c0d19ab133c2271e9f3375997e5a8dd2b08e3152d/nltk-3.10.2-py3-none-any.whl", hash = "sha256:2c7ccacb765c5e26b0cb60fb1b57080af522c6924d12a714a243305ba3637412", size = 1725815, upload-time = "2026-08-05T09:56:09.657Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/6d/ebd2af4640b12168fdf0cb74b6118df2f32a2f62ec7e0c06fbfd80706639/nltk-3.10.3-py3-none-any.whl", hash = "sha256:ff9598a8e20518ee0d557745890cc4435b9578489e2dcbc69c4f81fa060caf7c", size = 1798643, upload-time = "2026-08-12T23:44:13.478Z" },
 ]
 
 [[package]]
@@ -2907,23 +2924,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e2/22/dbf013a12ec759e54a34a119e9e217435b3f71b2dd5c61a7ade0a25dae87/sqlalchemy-2.0.51-py3-none-any.whl", hash = "sha256:bb024d8b621d0be75f4f44ecc7c950450026e76d66dc8f791bb5331d7fed59d5", size = 1944334, upload-time = "2026-06-15T16:09:22.418Z" },
 ]
 
-[[package]]
-name = "hypit-whisperx-service"
-version = "0.1.0"
-source = { editable = "." }
-dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
-    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
-    { name = "whisperx" },
-]
-
-[package.metadata]
-requires-dist = [
-    { name = "numpy", specifier = ">=2.1,<3" },
-    { name = "whisperx", specifier = "==3.8.6" },
-]
-
 [[package]]
 name = "sympy"
 version = "1.14.0"