@hypit/hypit 0.1.3 → 0.1.5

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

@@ -3,7 +3,6 @@ import { randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
-import { canonicalStringify } from "@hypit/protocol";
 
 import { processAlive, stopProcessTree } from "./process-control.js";
 import { readProcessLogs } from "./process-logs.js";
@@ -17,7 +16,6 @@ export type RuntimeWorkerLaunch = {
 
 export type RuntimeProcessState = {
   readonly state: "running" | "stopped";
-  readonly configuration?: "current" | "changed";
   readonly profile: string;
   readonly pid?: number;
   readonly startedAt?: number;
@@ -26,7 +24,6 @@ export type RuntimeProcessState = {
 
 type ProcessRecord = {
   readonly profile: string;
-  readonly profileConfig: string;
   readonly owner: string;
   readonly pid: number;
   readonly startedAt: number;
@@ -68,12 +65,11 @@ async function rotateLog(path: string): Promise<void> {
   await rename(path, previous);
 }
 
-async function record(profile: string, dataRoot: string): Promise<ProcessRecord | undefined> {
+async function record(dataRoot: string): Promise<ProcessRecord | undefined> {
   const path = paths(dataRoot).pid;
   try {
     const value = JSON.parse(await readFile(path, "utf8")) as ProcessRecord;
-    if (value.profile !== resolve(profile)
-      || typeof value.profileConfig !== "string" || value.profileConfig.length === 0
+    if (typeof value.profile !== "string" || value.profile.length === 0
       || typeof value.owner !== "string" || value.owner.length === 0
       || !Number.isSafeInteger(value.pid) || value.pid < 1
       || !Number.isSafeInteger(value.startedAt) || value.startedAt < 0) {
@@ -86,10 +82,6 @@ async function record(profile: string, dataRoot: string): Promise<ProcessRecord
   }
 }
 
-async function profileConfig(profile: string): Promise<string> {
-  return canonicalStringify(JSON.parse(await readFile(resolve(profile), "utf8")));
-}
-
 async function readyOwner(path: string): Promise<string | undefined> {
   try {
     const value = (await readFile(path, "utf8")).trim();
@@ -105,13 +97,12 @@ export async function runtimeProcessStatus(
   dataRoot: string,
 ): Promise<RuntimeProcessState> {
   const location = paths(dataRoot);
-  const current = await record(profile, dataRoot);
+  const current = await record(dataRoot);
   if (current === undefined || !processAlive(current.pid)) {
     return { state: "stopped", profile: resolve(profile), logPath: location.log };
   }
   return {
     state: "running",
-    configuration: current.profileConfig === await profileConfig(profile) ? "current" : "changed",
     profile: current.profile,
     pid: current.pid,
     startedAt: current.startedAt,
@@ -159,7 +150,7 @@ async function waitForReady(
   const location = paths(dataRoot);
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
-    const current = await record(profile, dataRoot);
+    const current = await record(dataRoot);
     if (current === undefined || !processAlive(current.pid)) {
       const log = await readProcessLogs(location.log, LOG_TAIL_BYTES);
       throw new Error(`Runtime Worker exited before becoming ready${log.length === 0 ? "" : `: ${log.trim().split("\n").at(-1)}`}`);
@@ -197,18 +188,14 @@ export async function ensureRuntimeProcess(
   try {
     const current = await runtimeProcessStatus(profile, dataRoot);
     if (current.state === "running") {
-      if (current.configuration === "changed") {
-        throw new Error("Runtime Profile changed while its Worker is running; stop and start the Worker to activate it");
-      }
       return current;
     }
-    const stale = await record(profile, dataRoot).catch(() => undefined);
+    const stale = await record(dataRoot).catch(() => undefined);
     if (stale !== undefined && !processAlive(stale.pid)) {
       await rm(location.pid, { force: true });
       await rm(location.ready, { force: true });
     }
     const owner = `worker_${randomUUID()}`;
-    const activeProfileConfig = await profileConfig(absolute);
     await rm(location.ready, { force: true });
     await rotateLog(location.log);
     const log = await open(location.log, "a");
@@ -252,7 +239,6 @@ export async function ensureRuntimeProcess(
       const startedAt = Date.now();
       await writeFile(location.pid, JSON.stringify({
         profile: absolute,
-        profileConfig: activeProfileConfig,
         owner,
         pid: child.pid,
         startedAt,
@@ -260,9 +246,6 @@ export async function ensureRuntimeProcess(
       child.unref?.();
       try {
         const ready = await waitForReady(absolute, dataRoot, owner, timeoutMs);
-        if (ready.configuration === "changed") {
-          throw new Error("Runtime Profile changed while its Worker was starting; start it again to activate the new Profile");
-        }
         return ready;
       } catch (error) {
         const stopped = await stopProcessTree(child.pid, true).catch(() => "denied" as const);
@@ -272,7 +255,7 @@ export async function ensureRuntimeProcess(
             { cause: error },
           );
         }
-        const saved = await record(profile, dataRoot).catch(() => undefined);
+        const saved = await record(dataRoot).catch(() => undefined);
         if (saved?.owner === owner) {
           await rm(location.pid, { force: true });
           await rm(location.ready, { force: true });
@@ -288,7 +271,7 @@ export async function ensureRuntimeProcess(
 }
 
 async function stopRuntimeProcessUnlocked(profile: string, dataRoot: string, timeoutMs: number): Promise<RuntimeProcessState> {
-  const current = await record(profile, dataRoot);
+  const current = await record(dataRoot);
   const location = paths(dataRoot);
   if (current === undefined || !processAlive(current.pid)) {
     await rm(location.pid, { force: true });

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.
 
@@ -135,3 +135,38 @@ These are alternative spellings, not two occurrences to put in the same Script.
 pause. In the second, the next “my” starts both touching boundaries, so the coffee Selection owns it.
 Plain `@/coffee @smoothie` leaves the gap between previous word end and next word start outside both.
 The media consumer still decides playback and visual coverage inside those projected Windows.
+
+## Marker writeback
+
+`adjustScriptSelection` and `adjustScriptMoment` accept explicit anchor identities. A Selection's
+two endpoints are written together. Script owns their legal source sites: token punctuation and
+postfix attributes stay attached, Segment boundaries stay structural, and coincident markers are
+ordered together. Writeback reads the current source, removes the markers, normalizes ordinary
+same-line prose, and places the markers at their requested anchors. Repeated spaces and tabs in
+prose become necessary separators; punctuation uses the same attachment rules as Script's text
+projection. Newlines, blank lines and each line's leading spaces/tabs remain intact. A marker at
+the start of a line is placed after its indentation; whitespace after that marker is prose, not
+additional indentation. Marker-only lines remain blank when the marker leaves. Comments, tags,
+Dual Text and display attributes retain their own syntax and are not passed through prose cleanup.
+
+Normalization keeps lexical units unchanged and does not restore earlier whitespace spellings.
+It has no persistent formatting state: the same text structure and anchor relationships produce
+the same spelling on repeated edits. Empty self-closing Segments expand when needed to make their
+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.