@hypit/hypit 0.1.4 → 0.1.5

package/packages/runtime-local/src/worker.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from "node:crypto";
-import { setImmediate } from "node:timers/promises";
 import type { BuildState } from "@hypit/protocol";
 import type {
   ResourceStore,
@@ -10,12 +9,13 @@ import type {
   RuntimePreparation,
   RuntimeRunnableCommand,
   ScheduledBuildResult,
-  RuntimeWorkerRunOptions,
 } from "@hypit/runtime";
 import { LocalBuildScheduler } from "@hypit/runtime";
 import { BuildMachine } from "@hypit/core";
 
 type LocalWorkerOptions = {
+  readonly executionBuild?: string;
+  readonly executionLogs?: import("./log.js").LocalExecutionLogs;
   readonly stores: {
     readonly builds: import("@hypit/runtime").BuildStore;
     readonly operations: import("@hypit/runtime").OperationStore;
@@ -25,7 +25,6 @@ type LocalWorkerOptions = {
   readonly resourceStore: ResourceStore;
   readonly resourceStoreForBuild?: (build: string) => ResourceStore;
   readonly openBuildResultRepository: NonNullable<import("./types.js").CreateLocalRuntimeOptions["openBuildResultRepository"]>;
-  readonly assertEnvironment?: () => Promise<void> | void;
   readonly installComponentPackages: (specifiers: readonly string[]) => Promise<void>;
   readonly resultWriter: import("./types.js").LocalResultWriter;
 };
@@ -36,28 +35,6 @@ function assert(condition: unknown, message: string): asserts condition {
   if (!condition) throw new Error(message);
 }
 
-function positive(value: number, subject: string): number {
-  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
-  return value;
-}
-
-async function pause(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted === true) throw signal.reason ?? new Error("Worker stopped");
-  await new Promise<void>((resolve, reject) => {
-    const done = (): void => {
-      signal?.removeEventListener("abort", abort);
-      resolve();
-    };
-    const timer = setTimeout(done, ms);
-    const abort = (): void => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", abort);
-      reject(signal?.reason ?? new Error("Worker stopped"));
-    };
-    signal?.addEventListener("abort", abort, { once: true });
-  });
-}
-
 /** Shares declared capacity across independently advancing Builds. */
 class CapacityExecutor implements RuntimeCommandExecutor {
   readonly #delegate: RuntimeCommandExecutor;
@@ -87,9 +64,13 @@ class CapacityExecutor implements RuntimeCommandExecutor {
     context: { readonly build: string },
   ): Promise<RuntimeExecutionResult> {
     const store = this.#options.stores.executions;
+    const recordExecution = this.#options.executionLogs === undefined ? {} : {
+      recordExecution: (event: import("@hypit/runtime").ExecutionLogEvent) =>
+        this.#options.executionLogs!.record(context.build, descriptor.command.id, event),
+    };
     if (descriptor.capacityMode === "asynchronous") {
       return await this.#delegate.executeCommand(state, descriptor, {
-        ...context, releaseOperationCapacity: () => this.#options.stores.execution.releaseCapacity(context.build, descriptor.command.id),
+        ...context, ...recordExecution, releaseOperationCapacity: () => this.#options.stores.execution.releaseCapacity(context.build, descriptor.command.id),
       });
     }
     const begun = await store.begin(context.build, descriptor.command.id);
@@ -107,7 +88,10 @@ class CapacityExecutor implements RuntimeCommandExecutor {
       return { status: "completed", event };
     }
     try {
-      const result = await this.#delegate.executeCommand(state, descriptor, context);
+      const result = await this.#delegate.executeCommand(state, descriptor, {
+        ...context, ...recordExecution,
+        reportProgress: (activity) => store.reportProgress(context.build, descriptor.command.id, activity),
+      });
       assert(result.status === "completed",
         `Immediate Command ${descriptor.command.id} returned ${result.status}`);
       await store.complete(context.build, descriptor.command.id, result.event);
@@ -190,11 +174,13 @@ class DurableLocalWorker {
   readonly #options: LocalWorkerOptions;
   readonly #executorWithCapacity: CapacityExecutor;
   readonly #owner = randomUUID();
+  readonly #ownedBuilds = new Set<string>();
   #buildRead = Promise.resolve();
 
   constructor(executor: RuntimeCommandExecutor, options: LocalWorkerOptions) {
     this.#executor = executor;
     this.#options = options;
+    if (options.executionBuild !== undefined) this.#ownedBuilds.add(options.executionBuild);
     this.#executorWithCapacity = new CapacityExecutor(executor, options, this.#owner);
   }
 
@@ -247,7 +233,14 @@ class DurableLocalWorker {
       }
       if (execution.stop.cause === "user-cancelled") {
         for (const operation of await this.#options.stores.operations.list({ build: execution.build })) {
-          if (operation.status === "pending") await this.#executor.cancelOperation?.(machine.view(), operation);
+          if (operation.status === "pending") {
+            const cancelled = await this.#executor.cancelOperation?.(machine.view(), operation);
+            if (cancelled !== undefined) await this.#options.executionLogs?.record(operation.build, operation.command, {
+              endpoint: operation.endpoint, kind: "diagnostic", level: "info",
+              message: `Cancellation: ${cancelled.cancellation?.outcome ?? "unsupported"}${
+                cancelled.cancellation?.message === undefined ? "" : `; ${cancelled.cancellation.message}`}`,
+            });
+          }
         }
       }
     }
@@ -322,7 +315,13 @@ class DurableLocalWorker {
           hydrated?.();
           const actions = await Promise.allSettled(pending.map(async (operation) => {
             if (operation === undefined) throw new Error(`Build ${execution.build} lost a waiting Operation`);
-            const result = await this.#executor.advanceOperation!(operation);
+            const result = await this.#executor.advanceOperation!(operation, {
+              build: operation.build,
+              ...(this.#options.executionLogs === undefined ? {} : {
+                recordExecution: (event: import("@hypit/runtime").ExecutionLogEvent) =>
+                  this.#options.executionLogs!.record(operation.build, operation.command, event),
+              }),
+            });
             if (result.remoteEnded || result.status !== "pending") {
               await this.#options.stores.execution.releaseCapacity(execution.build, result.command);
             }
@@ -380,65 +379,38 @@ class DurableLocalWorker {
     return finished;
   }
 
-  async runOnce(): Promise<WorkerTurnResult | undefined> {
-    await this.#options.assertEnvironment?.();
-    const execution = await this.#options.stores.execution.claim(this.#owner, Date.now());
-    if (execution === undefined) return undefined;
-    const [result] = await this.#runClaimed([execution]);
-    return result;
-  }
-
-  async run(options: RuntimeWorkerRunOptions): Promise<void> {
-    positive(options.idlePollMs, "Worker idlePollMs");
-    const active = new Set<Promise<void>>();
-    // The Runtime Host admits one Worker process. Any stored turn owner therefore belongs to the
-    // previous process; clearing it changes no external fact and performs no Result action.
-    await this.#options.assertEnvironment?.();
-    await this.#options.stores.execution.reclaimActionCapacity();
-    await this.#options.stores.execution.reclaimTurns(Date.now());
-    await this.#options.stores.execution.reclaimResultWrites();
-    for (const execution of await this.#options.stores.execution.list()) {
-      if (execution.decision !== undefined && execution.attention === undefined) {
-        await this.#options.stores.execution.setAttention(execution.build, {
-          step: "result",
-          error: "Result writing was interrupted; run `hypit result finish <build-id>`",
-        });
-      }
+  async runOnce(options: { readonly build?: string; readonly hydrated?: () => void } = {}): Promise<WorkerTurnResult | undefined> {
+    const store = this.#options.stores.execution;
+    const assigned = this.#options.executionBuild;
+    if (assigned !== undefined && options.build !== undefined && options.build !== assigned) {
+      throw new Error(`This execution context belongs to Build ${assigned}, not ${options.build}`);
     }
-    await options.ready?.();
-    try {
-      while (options.signal?.aborted !== true) {
-        await this.#options.assertEnvironment?.();
-        while (!Boolean(options.signal?.aborted)) {
-          const execution = await this.#options.stores.execution.claim(this.#owner, Date.now());
-          if (execution === undefined) break;
-          let markHydrated!: () => void;
-          const hydration = new Promise<void>((resolve) => { markHydrated = resolve; });
-          let task: Promise<void>;
-          task = this.#runClaimed([execution], markHydrated)
-            .then(() => undefined)
-            .finally(() => active.delete(task));
-          active.add(task);
-          // The next Build may execute concurrently, but its persisted snapshot is
-          // not hydrated until this one has left the single-threaded JSON boundary.
-          await Promise.race([hydration, task]);
-          // Awaiting synchronous stores only drains microtasks. Let sockets, timers and
-          // stop signals run before claiming another piece of ready work.
-          await setImmediate();
+    const selected = options.build ?? assigned;
+    for (const build of selected === undefined ? await store.listReady() : [selected]) {
+      const current = await store.read(build);
+      if (current === undefined || current.decision !== undefined) continue;
+      if (current.startedAt !== undefined && !this.#ownedBuilds.has(build)) {
+        if (selected === undefined) continue;
+        throw new Error(`Build ${build} already belongs to another execution context; create a new Build to continue`);
+      }
+      const execution = await store.claim(this.#owner, Date.now(), build);
+      if (execution === undefined) continue;
+      if (!this.#ownedBuilds.has(build)) {
+        if (execution.startedAt !== undefined) {
+          await store.releaseTurn(build, this.#owner, execution.wakeAt, execution.operationWait);
+          throw new Error(`Build ${build} was assigned to another execution context`);
         }
-        const idle = new AbortController();
-        const signal = options.signal === undefined ? idle.signal : AbortSignal.any([idle.signal, options.signal]);
-        try {
-          await Promise.race([...active, pause(options.idlePollMs, signal)]);
-        } catch (error) {
-          if (!Boolean(options.signal?.aborted)) throw error;
-        } finally { idle.abort(); }
-
+        await store.start(build);
+        this.#ownedBuilds.add(build);
       }
-    } finally {
-      await Promise.allSettled(active);
+      const [result] = await this.#runClaimed([execution], options.hydrated);
+      if (result !== undefined && ("outcome" in result || result.decision !== undefined)) this.#ownedBuilds.delete(build);
+      return result;
     }
+    return undefined;
   }
+
+
 }
 
 export function createDurableLocalWorker(

package/packages/screen-overlay/README.md

@@ -1,12 +1,12 @@
 # `@hypit/screen-overlay`
 
-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.
 
 Official provider-free self-contained screen-paint package.
 
-Every item consumes its typed parameters, explicit Temporal source, CanvasSpace, ProgramSpace,
+Every item consumes its typed parameters, explicit Temporal source, CanvasSpace, Timeline,
 seed and local frame. Flash, ColorWash, Vignette, ScanLines, DirectionalMatte, WhipVeil,
 GlitchVeil, Grain, LightLeak, Bokeh and TVStatic lower to ordinary absolute-stack `VisualTrack`
 Presents. These effects generate their own pixels over the selected interval.

package/packages/screen-overlay/package.json

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

package/packages/screen-overlay/src/component.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
 import { canonicalize } from "@hypit/protocol";
 import type { StoredValue } from "@hypit/protocol";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CanvasSpace } from "@hypit/spatial";
 import { screenOverlayProducers, screenOverlayTypes } from "./manifest.js";
 import { appendProjectedScreenOverlay, assertScreenOverlayProgram, createScreenOverlaySet, finalizeScreenOverlay, renderScreenOverlay } from "./program.js";
@@ -12,9 +12,9 @@ const output = (value: unknown) => ({ kind: "inline" as const, value: canonicali
 export const screenOverlayComponent = {
   producers: [
     { producer: screenOverlayProducers.createSet, handler: () => ({ outputs: { set: output(createScreenOverlaySet()) }, needs: {} }) },
-    { producer: screenOverlayProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<ScreenOverlayItemSpec>(inputs.spec?.value, "ScreenOverlayItemSpec"), inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"))) }, needs: {} }) },
+    { producer: screenOverlayProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"), inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ScreenOverlayItemSpec>(inputs.spec?.value, "ScreenOverlayItemSpec"), inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"))) }, needs: {} }) },
     { producer: screenOverlayProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"))) }, needs: {} }) },
-    { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },
+    { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },
   ],
   validators: [{ type: screenOverlayTypes.program, handler: ({ value }) => assertScreenOverlayProgram(inline<ScreenOverlayProgram>(value, "ScreenOverlayProgram")) }],
 } satisfies ComponentPackage;

package/packages/screen-overlay/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";
@@ -22,16 +23,16 @@ export function createScreenOverlayFragment(items: readonly ScreenOverlayFragmen
     const id = `overlay:set:append:${String(index + 1).padStart(4, "0")}`;
     operations.push({ id, producer: screenOverlayProducers.appendItem,
       inputs: { set: operation(current), header: input("header"), spec: input(item.specName),
-        space: input("space"), window: input(item.windowName) }, result: { kind: "output", name: "set" } });
+        timeline: input("timeline"), window: input(item.windowName) }, result: { kind: "output", name: "set" } });
     current = id;
   });
   operations.push(
     { id: "overlay:program", producer: screenOverlayProducers.finalize, inputs: { set: operation(current), header: input("header") }, result: { kind: "output", name: "program" } },
-    { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { canvas: input("canvas"), space: input("space"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },
+    { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { canvas: input("canvas"), timeline: input("timeline"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },
   );
   return sealGraphFragment({ inputs: [
     { name: "canvas", type: spatialTypes.canvas }, { name: "header", type: screenOverlayTypes.header },
-    { name: "space", type: programSpaceTypes.programSpace }, ...[...types].map(([inputName, type]) => ({ name: inputName, type })),
+    { name: "timeline", type: timelineTypes.track }, ...[...types].map(([inputName, type]) => ({ name: inputName, type })),
   ], operations, exports: [
     { name: "program", type: screenOverlayTypes.program, root: operation("overlay:program") },
     { name: "track", type: compositionTypes.visualTrack, root: operation("overlay:track") },

package/packages/screen-overlay/src/manifest.ts

@@ -1,11 +1,12 @@
+import { timelineTypes } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { readFile } from "node:fs/promises";
 
 import { compositionDependency, compositionTypes } from "@hypit/composition";
 import { narrativeDependency } from "@hypit/narrative";
-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 { temporalDependency, temporalTypes } from "@hypit/temporal";
 import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
@@ -65,7 +66,7 @@ export const screenOverlayHeaderSchema: ValueSchema = object({ id: { schema: str
 export const screenOverlayItemSpecSchema: ValueSchema = itemSpec;
 export const screenOverlaySetSchema: ValueSchema = object({ items: { schema: { kind: "array", items: item } } });
 export const screenOverlayProgramSchema: ValueSchema = object({ id: { schema: string }, items: { schema: { kind: "array", minItems: 1, items: item } } });
-const appendInputs = [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: screenOverlayTypes.itemSpec }, { name: "window", type: temporalTypes.window }] as const;
+const appendInputs = [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }, { name: "timeline", type: timelineTypes.track }, { name: "spec", type: screenOverlayTypes.itemSpec }, { name: "window", type: temporalTypes.window }] as const;
 
 const itemAttributes = [
   { name: "id", kind: "identifier", required: false,
@@ -269,7 +270,7 @@ export const screenOverlayMarkupSurfaces = [
         { name: "track", type: compositionTypes.visualTrack,
           summary: "The rendered overlay, an ordinary peer VisualTrack." },
       ],
-      example: `<screen:Track id="effects" semantic={speech.semantic} canvas={vertical}>
+      example: `<screen:Track id="effects" timeline={speech.timeline} canvas={vertical}>
   <screen:Flash during={story.selection.overlay} z="80"
     color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
 </screen:Track>`,
@@ -288,7 +289,7 @@ export const screenOverlayMarkupSurfaces = [
 
 export const screenOverlayManifest: ModuleManifest = {
   format: "hypit.module@1", name: screenOverlayModuleRef.name, version: screenOverlayModuleRef.version,
-  dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],
+  dependencies: [narrativeDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency],
   types: [
     { name: screenOverlayTypes.header.name },
     { name: screenOverlayTypes.itemSpec.name },
@@ -299,7 +300,7 @@ export const screenOverlayManifest: ModuleManifest = {
     { name: screenOverlayProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
     { name: screenOverlayProducers.appendItem.name, inputs: [...appendInputs], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
     { name: screenOverlayProducers.finalize.name, inputs: [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }], outputs: [{ name: "program", type: screenOverlayTypes.program }], needs: [] },
-    { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+    { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
   ],
 };
 export const screenOverlayDependency = { module: screenOverlayModuleRef } as const;

package/packages/screen-overlay/src/program.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
 import type { VisualAnimation, VisualElement, VisualStyleDeclaration, VisualTrack } from "@hypit/composition";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { canonicalize } from "@hypit/protocol";
 import { assertCanvasSpace } from "@hypit/spatial";
 import type { CanvasSpace } from "@hypit/spatial";
@@ -107,11 +107,11 @@ export function assertScreenOverlaySet(value: ScreenOverlaySet): void {
 }
 
 function realized(
-  set: ScreenOverlaySet, header: ScreenOverlayHeader, space: ProgramSpace, spec: ScreenOverlayItemSpec,
+  set: ScreenOverlaySet, header: ScreenOverlayHeader, timeline: Timeline, spec: ScreenOverlayItemSpec,
   window: ProjectedWindow,
 ): ScreenOverlaySet {
   assertScreenOverlaySet(set); assertScreenOverlayHeader(header); assertScreenOverlayItemSpec(spec);
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
   const addition = {
     id: window.id,
     subjectId: spec.id,
@@ -128,11 +128,11 @@ function realized(
 export function appendProjectedScreenOverlay(
   set: ScreenOverlaySet,
   header: ScreenOverlayHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   spec: ScreenOverlayItemSpec,
   window: ProjectedWindow,
 ): ScreenOverlaySet {
-  return realized(set, header, space, spec, window);
+  return realized(set, header, timeline, spec, window);
 }
 export function sealScreenOverlayProgram(value: ScreenOverlayProgram): ScreenOverlayProgram {
   const normalized = { id: value.id,
@@ -307,15 +307,15 @@ function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, d
   }
 }
 
-export function renderScreenOverlay(canvas: CanvasSpace, space: ProgramSpace, program: ScreenOverlayProgram): VisualTrack {
-  assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertScreenOverlayProgram(program);
+export function renderScreenOverlay(canvas: CanvasSpace, timeline: Timeline, program: ScreenOverlayProgram): VisualTrack {
+  assertCanvasSpace(canvas); assertProgramSpaceIdentity(timeline); assertScreenOverlayProgram(program);
   const track = sealVisualTrack({
-    programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,
+    programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
     presents: program.items.map((item) => ({
       id: item.id, subjectId: item.subjectId, span: { ...item.span }, stacking: { ...item.stacking },
       elements: overlayElements(item.content, canvas, item.span.endFrameExclusive - item.span.startFrame),
     })),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }

package/packages/screen-overlay/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { spatialTypes } from "@hypit/spatial";
 import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
 import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
@@ -57,16 +57,15 @@ function content(element: StructuredElement): { readonly value: ScreenOverlayCom
 }
 
 export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "canvas", "semantic"]); const id = text(element, "id");
+  allowed(element, ["id", "canvas", "timeline"]); const id = text(element, "id");
   const canvas = ref(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const headerId = `${id}.header`; const records: SurfaceRecordDraft[] = [{ id: headerId, type: screenOverlayTypes.header,
     value: { kind: "inline", value: sealScreenOverlayHeader({ id }) }, 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 fragmentItems: Parameters<typeof createScreenOverlayFragment>[0][number][] = [];
-  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, space: time.space.ref };
+  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
   let index = 0;
   for (const child of element.children) {
     if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts only component children.`); continue; }
@@ -76,7 +75,7 @@ export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element,
     const itemSpec = sealScreenOverlayItemSpec({
       id: optionalText(child, "id") ?? `${id}.${decoded.value.kind}.${suffix}`, content: decoded.value,
       stackingOrder: integer(child, "z") });
-    const temporal = createTemporalWindowProjection({ id: itemSpec.id, element: child, ...context, space: time.space, resolveReference });
+    const temporal = createTemporalWindowProjection({ id: itemSpec.id, element: child, ...context, resolveReference });
     records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
     const specId = `${id}.item.${suffix}.spec`; const specName = `item-${suffix}-spec`;
     records.push({ id: specId, type: screenOverlayTypes.itemSpec, value: { kind: "inline", value: itemSpec }, range: child.range });

package/packages/script/README.md

@@ -53,8 +53,8 @@ The Surface exports one full Narrative plus narrow, immutable views:
 - `script.moment.<id>` is a reusable explicit Moment.
 
 `@hypit/caption` projects `script.selection.<id>` or a Role onto complete Caption Alignment Units;
-it then joins those units to a SemanticTrack for frame timing. Seedance consumes dialogue `Text`,
-Estimate and TTS consume speech `Text`, and Speech Track consumes the Segment excerpt. None imports
+it then joins those units to a Timeline for frame timing. Seedance consumes dialogue `Text`,
+Estimate and TTS consume speech `Text`, and semantic preparation consumes the Segment excerpt. None imports
 Script's parser AST. Another authoring package may produce the same ordinary Text, Narrative and
 CaptionDocument contracts.
 
@@ -157,3 +157,16 @@ distinct boundaries writable.
 Writeback reparses the result to retain the intended identities and unchanged narrative/caption
 content. These checks concern authored order, not frame order. A consumer's temporal projection
 determines whether the resulting Instant or Window is usable.
+
+## Complete authored content and narrow exports
+
+The root `story` Record contains the complete Narrative: speech structure, semantic references and
+its CaptionDocument. `story.caption`, `story.selection.<id>`, Segment excerpts and dialogue/speech
+Text outputs remain explicit narrow exports derived from that content. Caption rendering can read
+the document and Timeline. Timed Uses change its presentation; their semantic references are
+projected through the same Timeline as other components. Word attributes remain in the document
+for families that give those words structural visual roles.
+
+For content lookup, use the Narrative package's `narrativeTokensForSelection` or
+`narrativeSelectionTokenRange`. These query authored order; Timeline separately locates the same
+anchors in the assembled video. No timestamps or display Styles enter the Script value.

package/packages/script/src/manifest.ts

@@ -32,7 +32,7 @@ export const scriptMarkupSurfaces = [
       text: "The element's own content is the Script body: named Segments holding prose, Role Cues, Dual Text, flat token attributes, and zero-width Selection and Moment markers. It carries no timecode, no media reference and no generation parameter.",
       ports: [
         { name: "", type: narrativeType,
-          summary: "The whole authored Narrative, addressed by the element's own id." },
+          summary: "The complete authored Narrative, including speech structure, semantic anchors and its CaptionDocument, addressed by the element's own id." },
         { name: "segment.<id>", type: narrativeExcerptType,
           summary: "One Segment as a narrow Excerpt, used to associate a generated Take with that Segment." },
         { name: "segment.<id>.dialogue", type: textTypes.text,
@@ -40,7 +40,7 @@ export const scriptMarkupSurfaces = [
         { name: "segment.<id>.speech", type: textTypes.text,
           summary: "One Segment as pronunciation only, with Role Cue labels dropped." },
         { name: "caption", type: captionDocumentType,
-          summary: "The complete Script-owned CaptionDocument: display Words, N:M Alignment Units, Cue breaks and speech correspondence." },
+          summary: "The Narrative's CaptionDocument exported as a narrow view: display Words, N:M Alignment Units, Cue breaks and speech correspondence." },
         { name: "selection.<id>", type: narrativeSelectionType,
           summary: "One named range over the Narrative, reusable wherever a Selection is read." },
         { name: "moment.<id>", type: narrativeMomentType,

package/packages/script/src/narrative.ts

@@ -180,6 +180,7 @@ export function narrativeMomentValue(moment: ParsedNarrative["moments"][number],
 export function narrativeValue(parsed: ParsedNarrative, id: string): CanonicalValue {
   return canonicalize({
     id,
+    caption: captionDocument(parsed, `${id}.caption`, id),
     segments: parsed.segments.map((segment) => ({
       id: segment.id,
       startAnchorId: segment.startAnchorId,

package/packages/script/src/surface.ts

@@ -1,6 +1,5 @@
 import { ScriptSyntaxError } from "./error.js";
 import {
-  captionDocumentValue,
   narrativeDialogueTextValue,
   narrativeSegmentExcerptValue,
   narrativeMomentValue,
@@ -73,6 +72,8 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
     input.source.slice(input.contentStart, close.start),
     input.contentStart,
   );
+  const narrative = narrativeValue(parsed, rawId);
+  const caption = (narrative as { readonly caption: import("@hypit/protocol").CanonicalValue }).caption;
   const captionId = `${rawId}.caption`;
   return {
     nextOffset: close.end,
@@ -80,7 +81,7 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
       {
         id: rawId,
         type: narrativeType,
-        value: { kind: "inline", value: narrativeValue(parsed, rawId) },
+        value: { kind: "inline", value: narrative },
         range: { start: input.openingStart, end: close.end },
       },
       ...parsed.segments.map((segment) => ({
@@ -106,7 +107,7 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
       {
         id: captionId,
         type: captionDocumentType,
-        value: { kind: "inline" as const, value: captionDocumentValue(parsed, captionId, rawId) },
+        value: { kind: "inline" as const, value: caption },
         range: { start: input.openingStart, end: close.end },
       },
       ...parsed.selections.map((selection) => ({

package/packages/script/src/types.ts

@@ -77,7 +77,7 @@ export type ParsedCaptionRegion = {
 
 export type ParsedNarrative = Omit<
   Narrative,
-  "id" | "segments" | "tokens" | "turns" | "selections" | "moments"
+  "id" | "segments" | "tokens" | "turns" | "selections" | "moments" | "caption"
 > & {
   /** Exact Script body range, used only for source-preserving Program-boundary edits. */
   readonly sourceRange: SourceRange;

package/packages/script-studio/package.json

@@ -4,10 +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/script": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*"
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*"
   }
 }

package/packages/script-studio/src/index.ts

@@ -1,9 +1,11 @@
+import { projectScriptTimeline } from "./projection.js";
 import { adjustScriptMoment, adjustScriptSelection, parseScript, scriptModuleRef } from "@hypit/script";
 import type { StudioScriptCompanion } from "@hypit/studio-adapter";
 
 export const scriptStudioCompanions: readonly StudioScriptCompanion[] = [{
   id: "script",
   match: { module: scriptModuleRef, surface: "script" },
+  project: projectScriptTimeline,
   observe(input) {
     const narrativeId = input.attributes.id ?? "script";
     if (typeof narrativeId !== "string" || narrativeId.length === 0) return undefined;