@hypit/hypit 0.1.4 → 0.1.6

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.
 
@@ -64,7 +64,7 @@ CaptionDocument contracts.
 - **Role Cue**: a speaker turn, written as a bare tag such as `<ALICE>` inside a Segment. The next
   Role Cue or the Segment close ends that turn.
 - **Dual Text**: one authored speech span with separate display and spoken projections, written
-  `<display text | spoken text>`.
+  `<display text | spoken text>`. In `<display text|>`, omitted speech inherits the displayed prose.
 - **Selection marker**: a named semantic range, written `@name ... @/name`.
 - **Moment marker**: a named semantic point, written `@name!`.
 - **CaptionDocument**: the Script-owned caption truth; it contains **Display Words**,
@@ -73,11 +73,23 @@ CaptionDocument contracts.
   `really{emphasis,importance=2,tone=warm}`. Values may be strings, finite numbers or booleans. It
   becomes `CaptionDisplayWord.attributes`; it is not a Selection and does not carry timing.
 
-Within Dual Text, an unescaped `@` is legal only on the spoken side. The display side is literal; write
-`\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech
+Within Dual Text, an unescaped `@` belongs to the source of spoken text: the right side when supplied,
+or the shared left side in `<display text|>`. Write `\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech
 tokens and omits them from Caption. `||` is an authored Caption Cue Break and must occur between
 complete Alignment Units.
 
+`<组件化|>` is shorthand for `<组件化|组件化>`, using the same exported Caption Alignment Unit.
+It groups the displayed expression without merging its individual speech Tokens or time anchors.
+For example, `把<动效|><组件化|>。|| 之后<直接复用|>。` authors groups inside two Cues.
+Use groups where the expression should be treated together; ordinary prose needs no extra markup.
+Caption Styles choose whether to highlight, reveal or keep the text steady.
+
+In a shared side, markers and display attributes do not enter either text projection. Its speech
+Tokens retain offsets into the actually written left-hand text, so Studio can move an anchor inside
+`<组@beat!件化|>` without expanding the shorthand. Attributes still annotate the preceding display
+word, not the whole group. Whitespace-only speech is omitted; a group with no spoken text on either
+side is invalid. This adds no new public value type or protocol version.
+
 ## Segments, turns and Cues are different boundaries
 
 A Segment names a structural production passage. It can contain several Role turns and be performed
@@ -157,3 +169,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,
@@ -64,7 +64,8 @@ export const scriptMarkupSurfaces = [
         "A Script requires at least one Segment, and natural-language text is refused outside a Segment.",
         "A Segment is opened by its own lower-case name and closed by that exact name, or written self-closing as `<pause/>`; the name is the Segment id, must be unique within the Script, and `script` is reserved. Segments do not nest.",
         "A Role Cue such as `<HOST>` is a bare tag inside a Segment with no close; its turn runs until the next Cue or the end of the Segment, and a Cue may not follow unowned speech in the same Segment. Role state resets when the Segment closes.",
-        "Dual Text is written `<display | speech>`: the left side reaches the caption projection and the right side reaches dialogue and speech. The spoken side must not be empty; the displayed side may be, which speaks a word that is never displayed.",
+        "Dual Text is written `<display | speech>`: the left side reaches Caption and the right side reaches dialogue and speech. `<display|>` inherits speech from the displayed prose and forms the same complete alignment unit; its word times remain individual. `<|speech>` speaks without displaying. Both sides empty is invalid.",
+        "Inside Dual Text, semantic markers belong to the source of spoken text: the explicit right side, or the shared left side when speech is omitted. Display attributes remain visual metadata and never enter spoken text.",
         "A flat token attribute follows a complete display token as `{name}` or `{name=value}`; multiple attributes use one comma-separated block. Attributes do not nest, do not carry timing, and never split a Dual Alignment Unit.",
         "Selection and Moment markers are zero-width, share one name namespace, and may not split a speech token:",
         [

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,