@hypit/hypit 0.2.5 → 0.2.7

package/packages/provider-monid/package.json

@@ -12,7 +12,8 @@
     "@hypit/minimax-h3": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/runtime": "workspace:*",
-    "@hypit/runtime-kit": "workspace:*"
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/wan": "workspace:*"
   },
   "devDependencies": {
     "@hypit/seedance": "workspace:*"

package/packages/provider-monid/src/mapping.ts

@@ -3,6 +3,7 @@ import type { GenerationWireMapping } from "@hypit/generation";
 
 const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
 const MINIMAX_H3: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const WAN: ModuleRef = { name: "@hypit/wan", version: "1" };
 
 /**
  * One mapping plus the Monid provider that relays the endpoint. Monid addresses an endpoint by
@@ -57,10 +58,33 @@ const minimaxH3: MonidMapping = {
   },
 };
 
+/**
+ * Monid's `alibaba` Wan 2.7 image endpoints. Both variants take the same fields; the Pro variant
+ * adds a 4K band. Input images are plain public URLs rather than role-tagged items, and the model
+ * reads exclusions from the prompt, so it has no negative-prompt field.
+ */
+const wan = (name: string, endpoint: string): MonidMapping => ({
+  service: "alibaba",
+  capability: { module: WAN, name }, result: "image",
+  routes: [{ model: endpoint }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    images: { as: "urlArray", field: "images" },
+    resolution: { as: "value", field: "size" },
+    count: { as: "value", field: "n" },
+    imageSet: { as: "value", field: "enable_sequential" },
+    extendedReasoning: { as: "value", field: "thinking_mode" },
+    watermark: { as: "value", field: "watermark" },
+    seed: { as: "value", field: "seed" },
+  },
+});
+
 export const monidMappings: readonly MonidMapping[] = [
   seedance("seedance-2", "/v1/video/seedance-2.0"),
   seedance("seedance-2-fast", "/v1/video/seedance-2.0-fast"),
   seedance("seedance-2-mini", "/v1/video/seedance-2.0-mini"),
   seedance("seedance-2.5", "/v1/video/seedance-2.5"),
   minimaxH3,
+  wan("wan-2.7-image", "/v1/image/wan2.7-image"),
+  wan("wan-2.7-image-pro", "/v1/image/wan2.7-image-pro"),
 ];

package/packages/provider-monid/src/provider.ts

@@ -31,7 +31,7 @@ type Handle = {
   readonly runId: string;
   readonly route: string;
   readonly startedAt: number;
-  readonly url?: string;
+  readonly urls?: readonly string[];
 };
 
 function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
@@ -66,13 +66,21 @@ function httpsUrl(value: unknown, subject: string): string {
   return value;
 }
 /**
- * The relayed result. The ModelArk endpoints return the task's `video_url`; MiniMax-H3 returns the
- * video at `content.url`. The link expires, so collection downloads it rather than storing it.
+ * The relayed result. The ModelArk endpoints return the task's `video_url` and MiniMax-H3 its
+ * `content.url`; an image endpoint returns one entry per rendered picture. Every link expires, so
+ * collection downloads them rather than storing the addresses.
  */
-function outputVideoUrl(run: Record<string, unknown>): string {
+function outputUrls(run: Record<string, unknown>): readonly string[] {
   const output = object(run.output, "Monid run output");
   const content = output.content === undefined ? undefined : object(output.content, "Monid run output content");
-  return httpsUrl(output.video_url ?? content?.video_url ?? content?.url, "Monid run output");
+  const listed = [output.results, output.images, output.urls, content?.results, content?.images]
+    .find((value): value is readonly unknown[] => Array.isArray(value) && value.length > 0);
+  if (listed !== undefined) {
+    return listed.map((item, index) => httpsUrl(
+      typeof item === "string" ? item : object(item, `Monid run output ${index}`).url,
+      `Monid run output ${index}`));
+  }
+  return [httpsUrl(output.video_url ?? output.url ?? content?.video_url ?? content?.url, "Monid run output")];
 }
 const extensions: Readonly<Record<string, string>> = {
   "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",
@@ -180,7 +188,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         if (!ended) return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(run.status) }), receipt };
         const rejected = monidRunFailure(run, handle.runId);
         if (rejected !== undefined) return { ...failure(rejected), receipt };
-        return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+        return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
       } catch (error) {
         return failure(error);
       }
@@ -201,7 +209,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         }
         const rejected = monidRunFailure(run, handle.runId);
         if (rejected !== undefined) return { ...failure(rejected), receipt };
-        return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+        return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
       } catch (error) {
         return failure(error);
       }
@@ -211,10 +219,15 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         const handle = object(context.handle, "Monid handle") as unknown as Handle;
         const route = monidRouteForCapability(context.need.capability);
         assert(route !== undefined && handle.route === route.key, "Monid collection route differs");
-        await context.reportProgress?.({ phase: "Receiving generated video" });
-        const downloaded = await client.download(httpsUrl(handle.url, "Monid handle"));
-        const blob = await context.resources.put(downloaded.bytes, downloaded.mediaType);
-        return { status: "completed", result: { value: route.packageResult([blob]) }, receipt: { id: handle.runId } };
+        const urls = handle.urls ?? [];
+        assert(urls.length > 0, "Monid handle carries no result");
+        await context.reportProgress?.({ phase: `Receiving ${urls.length} generated ${route.media}${urls.length === 1 ? "" : "s"}` });
+        const blobs: BlobRef[] = [];
+        for (const url of urls) {
+          const downloaded = await client.download(httpsUrl(url, "Monid handle"));
+          blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+        }
+        return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.runId } };
       } catch (error) {
         return failure(error);
       }

package/packages/provider-monid/src/routes.ts

@@ -2,6 +2,7 @@ import {
   compileWireRequest,
   selectWireModelForRequest,
   generationTypes,
+  sealGeneratedImageSet,
   sealGeneratedVideoSet,
 } from "@hypit/generation";
 import type { GenerationArtifactUrlResolver, GenerationRequest } from "@hypit/generation";
@@ -22,6 +23,8 @@ export type MonidPreparedRequest = {
 export type MonidRoute = MonidMapping & {
   readonly key: string;
   readonly returns: TypeRef;
+  /** What the run produces, which decides how many results collection expects. */
+  readonly media: "image" | "video";
   readonly supports: (request: EndpointRequest) => EndpointSupport;
   readonly prepare: (constraints: CanonicalValue) => MonidPreparedRequest;
   readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
@@ -42,7 +45,20 @@ function referenceToVideo(request: GenerationRequest): boolean {
   return present(request, "referenceImage") || present(request, "referenceVideo") || present(request, "referenceAudio");
 }
 
+function wanRejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+  const set = scalar(request, "imageSet") === true;
+  if (scalar(request, "resolution") === "4K" && (present(request, "images") || set)) {
+    return "Wan renders 4K from a prompt alone, without reference images or an image set";
+  }
+  const count = scalar(request, "count");
+  if (typeof count === "number" && count > 4 && !set) {
+    return `Wan renders at most 4 pictures outside an image set, not ${count}`;
+  }
+  return undefined;
+}
+
 function rejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+  if (mapping.capability.module.name === "@hypit/wan") return wanRejection(mapping, request);
   if (mapping.capability.name === "minimax-h3") {
     // MiniMax-H3 resolves the framing from the uploaded image in frame mode and defaults
     // reference-to-video to adaptive. Text-to-video carries no such source, and the endpoint
@@ -103,7 +119,8 @@ function capabilityKey(capability: CapabilityRef): string {
 export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) => ({
   ...mapping,
   key: capabilityKey(mapping.capability),
-  returns: generationTypes.videoSet,
+  returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+  media: mapping.result === "image" ? "image" as const : "video" as const,
   supports: (request) => {
     const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
     return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
@@ -112,7 +129,10 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
     const request = constraints as unknown as GenerationRequest;
     const reason = rejection(mapping, request);
     if (reason !== undefined) throw new Error(reason);
-    const body = mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
+    // The Wan endpoints take the compiled fields as their body; the ModelArk endpoints fold their
+    // media into one role-tagged `content` array first.
+    const body = mapping.capability.module.name === "@hypit/wan" ? (input: Record<string, unknown>) => input
+      : mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
     return {
       service: mapping.service,
       endpoint: selectWireModelForRequest(mapping, request),
@@ -121,7 +141,9 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
   },
   packageResult: (artifacts) => ({
     kind: "inline",
-    value: canonicalize(sealGeneratedVideoSet({ videos: artifacts })),
+    value: canonicalize(mapping.result === "image"
+      ? sealGeneratedImageSet({ images: artifacts })
+      : sealGeneratedVideoSet({ videos: artifacts })),
   }),
 }));
 

package/packages/provider-pollo/README.md

@@ -37,6 +37,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "pollo.default": {
       "use": "@hypit/provider-pollo",
@@ -47,7 +54,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-tokendance/README.md

@@ -46,6 +46,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "tokendance.default": {
       "use": "@hypit/provider-tokendance",
@@ -56,7 +63,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-whisperx-local/README.md

@@ -91,16 +91,19 @@ torch caches and their environment settings. Changing a running service's cache
 an explicit restart when idle, just like changing its model or hardware. The managed installation
 does not require a global `whisperx` shell command.
 
-Preparation and service processes inherit the environment of the command starting them. Set
-network and cache variables there before `programs up` or `runtime up`. A service already running
-retains its earlier environment. Inspect its reported log before deciding whether a selected
-Program needs restarting, and account for active work using it.
+Preparation and service processes inherit the environment of the command starting them. Set download
+route variables on `programs prepare` (or the preparation performed by `programs up` / `runtime up`).
+Changing only a download source does not require restarting a running service using the same cache.
+Cache settings must select the same resource location for preparation and the service. A running
+service retains its earlier environment; arrange an idle restart when changing that location or its
+inference settings. Inspect its reported configuration and logs, and account for active work.
 
 If NLTK refuses a proxied fetch during preparation, follow the service’s
 [explicit proxy preparation](../../services/whisperx/README.md#preparing-sentence-data-through-a-proxy).
 
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
-`program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
+`program.err.log` on Windows. Inspect service logs for Python model-loading and inference messages;
+download messages belong to preparation's `install.log`.
 `programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
 exist, even before installation finishes. Preparation notices name the Python environment and selected model/language resources separately. The service logs the start and completion of ASR loading, transcription,
 language-alignment model loading and alignment, with elapsed times. Downloads happen only in

package/packages/render-hyperframes/README.md

@@ -6,6 +6,15 @@ semantic coverage through the same frame and audio pipeline.
 
 Explicit author and capability boundary for final HyperFrames video rendering.
 
+`@hypit/render-hyperframes@1#render-frames` captures an existing programme's selected frames.
+`hyperframesFramesRequest({ document, frames })` accepts a `HyperframesDocument` and strictly
+increasing original-frame indices. `{ project: { html, assets }, frames }` accepts already
+materialized HTML with its URL-addressed assets. The `Frames` result is a PNG `BlobRef[]` in request
+order; the request already owns the frame identities. Canvas and clock stay in the input.
+This capability requests picture capture only. File names, contact sheets and pagination belong to
+the caller. `hypit snapshot` invokes it immediately through a selected Profile; there is no Build
+or video encoding in that observation path.
+
 The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
 
 1. obtain the `ProgramSpace` from the Timeline input and compile the referenced `Composition` into a `HyperframesDocument`;

package/packages/render-hyperframes/src/index.ts

@@ -4,3 +4,6 @@ export { renderHyperframesCapabilities, renderHyperframesManifest, renderHyperfr
 export { hyperframesVisualRequest, verifyHyperframesVisualRequest } from "./product.js";
 export type { HyperframesVisualRequest } from "./product.js";
 export { decodeHyperframesRenderSurface } from "./surface.js";
+export { renderHyperframesTypes } from "./manifest.js";
+export { hyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesFramesRequest, verifyHyperframesFrames } from "./product.js";
+export type { HyperframesFramesRequest, HyperframesFrames } from "./product.js";

package/packages/render-hyperframes/src/manifest.ts

@@ -12,6 +12,7 @@ import type {
   CapabilityRef,
   ModuleManifest,
   ProducerRef,
+  TypeRef,
 } from "@hypit/protocol";
 import {
   mediaPipelineModuleRef,
@@ -20,7 +21,11 @@ import {
 export const renderHyperframesModuleRef = { name: "@hypit/render-hyperframes", version: "1" } as const;
 export const renderHyperframesCapabilities = {
   renderVisual: { module: renderHyperframesModuleRef, name: "render-visual" },
+  renderFrames: { module: renderHyperframesModuleRef, name: "render-frames" },
 } satisfies Record<string, CapabilityRef>;
+export const renderHyperframesTypes = {
+  frames: { module: renderHyperframesModuleRef, name: "Frames" },
+} satisfies Record<string, TypeRef>;
 export const renderHyperframesProducers = {
   requestVisualRange: { module: renderHyperframesModuleRef, name: "request-visual-range" },
   requestVisual: { module: renderHyperframesModuleRef, name: "request-visual-render" },
@@ -70,11 +75,11 @@ export const renderHyperframesManifest: ModuleManifest = {
     { module: hyperframesModuleRef },
     { module: mediaPipelineModuleRef },
   ],
-  types: [],
+  types: [{ name: renderHyperframesTypes.frames.name }],
   capabilities: [{
     name: renderHyperframesCapabilities.renderVisual.name,
     returns: mediaTypes.renderedVisual,
-  }],
+  }, { name: renderHyperframesCapabilities.renderFrames.name, returns: renderHyperframesTypes.frames }],
   producers: [
     {
       name: renderHyperframesProducers.requestVisual.name,

package/packages/render-hyperframes/src/product.ts

@@ -1,6 +1,8 @@
 import type { CanonicalValue } from "@hypit/protocol";
-import { assertHyperframesDocument } from "@hypit/hyperframes";
-import type { HyperframesDocument } from "@hypit/hyperframes";
+import { assertHyperframesDocument, assertHyperframesHtmlProject, hyperframesHtmlDomain } from "@hypit/hyperframes";
+import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
+import type { BlobRef } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
 import { verifyMediaFrameRange } from "@hypit/media";
 import type { MediaFrameRange } from "@hypit/media";
 
@@ -9,6 +11,43 @@ export type HyperframesVisualRequest = {
   readonly range?: MediaFrameRange;
 };
 
+/** Select original programme frames, in strictly increasing order. */
+export type HyperframesFramesRequest = ({ readonly document: HyperframesDocument } | { readonly project: HyperframesHtmlProject }) & {
+  readonly frames: readonly number[];
+};
+/** PNG images in request order. The request already supplies each frame's identity. */
+export type HyperframesFrames = readonly BlobRef[];
+
+export function hyperframesFramesDomain(request: HyperframesFramesRequest) {
+  return "document" in request ? request.document : hyperframesHtmlDomain(request.project.html);
+}
+
+export function verifyHyperframesFramesRequest(value: unknown): asserts value is HyperframesFramesRequest {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).some(key => !["document", "project", "frames"].includes(key))
+    || ("document" in value) === ("project" in value)) throw new Error("Frame request needs exactly one document or HTML project, and frames");
+  const request = value as HyperframesFramesRequest;
+  if ("document" in request) assertHyperframesDocument(request.document);
+  else assertHyperframesHtmlProject(request.project);
+  const { frameCount } = hyperframesFramesDomain(request);
+  if (!Array.isArray(request.frames) || request.frames.length === 0 || request.frames.some((frame, index) =>
+    !Number.isSafeInteger(frame) || frame < 0 || frame >= frameCount || (index > 0 && frame <= request.frames[index - 1]!))) {
+    throw new Error(`Frames must be strictly increasing integers in [0, ${frameCount})`);
+  }
+}
+
+export function hyperframesFramesRequest(request: HyperframesFramesRequest): CanonicalValue {
+  verifyHyperframesFramesRequest(request);
+  return request as unknown as CanonicalValue;
+}
+
+export function verifyHyperframesFrames(value: unknown): asserts value is HyperframesFrames {
+  if (!Array.isArray(value) || value.length === 0 || value.some(blob => !blob || blob.kind !== "blob"
+    || !isResourceId(blob.resource) || blob.mediaType !== "image/png" || !Number.isSafeInteger(blob.size) || blob.size <= 0)) {
+    throw new Error("HyperFrames frames must be PNG BlobRefs in request order");
+  }
+}
+
 export function verifyHyperframesVisualRequest(value: unknown): asserts value is HyperframesVisualRequest {
   if (value === null || typeof value !== "object" || Array.isArray(value)
     || Object.keys(value).some((key) => key !== "document" && key !== "range")) {

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

@@ -23,7 +23,10 @@ function signal(pid: number, force: boolean): ProcessStopResult {
       process.kill(target, name);
       return "sent";
     } catch (error) {
-      if (errorCode(error) === "EPERM") return "denied";
+      if (errorCode(error) === "EPERM") {
+        if (target < 0) continue;
+        return "denied";
+      }
       if (errorCode(error) !== "ESRCH") throw error;
     }
   }

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

@@ -196,13 +196,25 @@ function powershellLiteral(value: string): string {
  * as `-e` followed by the first word of the script, and node exits on the syntax error. Given one
  * string it passes that string through as the command line, which is what this builds.
  */
-function windowsCommandLine(args: readonly string[]): string {
+export function windowsCommandLine(args: readonly string[]): string {
   return args.map((value) => {
     if (value !== "" && !/[\s"]/u.test(value)) return value;
     // A quote is escaped by the backslashes before it, so those double; a trailing run doubles too,
     // because the closing quote would otherwise escape itself against them.
-    const escaped = value.replace(/(\\*)"/gu, '$1$1\\"').replace(/(\\*)$/u, "$1$1");
-    return `"${escaped}"`;
+    let escaped = '"';
+    let backslashes = 0;
+    for (const character of value) {
+      if (character === "\\") {
+        backslashes++;
+      } else if (character === '"') {
+        escaped += "\\".repeat(backslashes * 2 + 1) + '"';
+        backslashes = 0;
+      } else {
+        escaped += "\\".repeat(backslashes) + character;
+        backslashes = 0;
+      }
+    }
+    return escaped + "\\".repeat(backslashes * 2) + '"';
   }).join(" ");
 }
 

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

@@ -119,7 +119,14 @@ export async function superviseBuilds(options: {
         if (options.signal.aborted) break;
         accepting ??= launch();
         const carrier = accepting;
-        await carrier.ready;
+        try {
+          await carrier.ready;
+        } catch (error) {
+          if (accepting === carrier) accepting = undefined;
+          if (options.signal.aborted) break;
+          await finishInterrupted(build, `Build executor startup failed: ${error instanceof Error ? error.message : String(error)}; create a new Build to continue`);
+          continue;
+        }
         if (carrier.exited) break;
         if (accepting !== carrier) continue;
         await state.execution.start(build);

package/packages/script/README.md

@@ -27,8 +27,10 @@ parser is inside a Segment, a valid bare tag such as `<ALICE>` is a Role Cue. Th
 not indentation: the compact spelling
 `<opening><ALICE>I speak first.<BOB>I answer.</opening>` has the same semantic value.
 
-A Role Cue is optional. Text before the first Role Cue is a roleless Turn, and Role state is reset
-when every Segment closes; a Role can never leak into the following Segment.
+A Role Cue is optional. A Segment without Role Cues contains a roleless Turn. If Roles are used,
+the first Cue must precede that Segment's spoken text. Role state resets when the Segment closes;
+a Role can never leak into the following Segment. Role labels may use Unicode letters, marks and
+numbers; capitalization does not distinguish Roles from Segments.
 
 An empty Segment such as `<empty></empty>` (or `<empty/>`) is valid. `empty` is an ordinary
 author-chosen name, not a reserved keyword. It retains the Segment identity and both boundary anchors
@@ -101,7 +103,7 @@ Units; it does not split the Segment, cut the picture or end a Selection.
 <script id="story">
   <exchange>
     <HOST> I use it || every day, || since <2012 | twenty twelve>.
-    <GUEST> Even @{proof} on holiday @{/proof}?
+    <GUEST> Even @{proof}on holiday?@{/proof}
     <HOST> @{answer!} Especially then.
   </exchange>
 </script>
@@ -118,13 +120,18 @@ These units support precise timing and highlighting. A Caption Cue can hold a wh
 `||` chooses its handoff independently of character counts or visual line wrapping.
 
 Annotations do not create speech boundaries. Comments are transparent (`hel<!--note-->lo`
-remains `hello`); a postfix attribute or `||` inside a word is invalid. Script analyzes a complete
+remains `hello`), including when an attribute follows a comment or zero-width marker:
+`hello<!--note-->{emphasis}` and `hello@{beat!}{emphasis}` still annotate `hello`.
+An authored space before the attribute remains invalid. A postfix attribute or `||` inside a word
+is invalid. Script analyzes a complete
 prose run before binding these constructs. An explicit Dual correspondence and a speaker/Segment
 boundary remain authored structure. Shared Dual groups still expose their internal speech anchors.
 
 A Dual display side is literal authored text, including symbols and emoji: `<😀|smile>` and
 `<.|dot>` have explicit speech correspondence and require no invented speech token for the symbol.
 A literal-only display is one display surface within that correspondence.
+Every Dual needs at least one spoken word on its explicit or shared speech side. `<API|...>` cannot
+provide timed correspondence for `API` and is rejected; punctuation and markers are not spoken words.
 
 ## Display spelling and separators
 

package/packages/script/src/format.ts

@@ -3,38 +3,25 @@ import { canonicalStringify } from "@hypit/protocol";
 import { ScriptSyntaxError } from "./error.js";
 import { narrativeValue } from "./narrative.js";
 import { parseScript } from "./parser.js";
-
-const ROLE = /^[\p{L}\p{M}\p{N}_](?:[\p{L}\p{M}\p{N}_. -]{0,30}[\p{L}\p{M}\p{N}_.-])?$/u;
+import type { ParsedSegment } from "./types.js";
 
 function compact(value: string): string {
   return value.replace(/\s+/gu, " ").trim();
 }
 
-function formatSegment(raw: string, id: string, selfClosing: boolean): string[] {
+function formatSegment(source: string, segment: ParsedSegment): string[] {
+  const { id, selfClosing, contentRange, atoms } = segment;
   if (selfClosing) return [`<${id}/>`];
-  const openEnd = raw.indexOf(">") + 1;
-  const closeStart = raw.lastIndexOf(`</${id}>`);
-  const body = raw.slice(openEnd, closeStart);
   const lines: string[] = [`<${id}>`];
   const turns: string[] = [];
-  let chunkStart = 0;
-  let cursor = 0;
-  while (cursor < body.length) {
-    if (body[cursor] !== "<" || body.startsWith("<!--", cursor)) {
-      cursor += 1;
-      continue;
-    }
-    const end = body.indexOf(">", cursor + 1);
-    if (end < 0) break;
-    const inside = body.slice(cursor + 1, end);
-    if (!inside.includes("|") && ROLE.test(inside)) {
-      const before = compact(body.slice(chunkStart, cursor));
-      if (before) turns.push(before);
-      chunkStart = cursor;
-    }
-    cursor = end + 1;
+  let chunkStart = contentRange.start;
+  for (const atom of atoms) {
+    if (atom.kind !== "role") continue;
+    const before = compact(source.slice(chunkStart, atom.range.start));
+    if (before) turns.push(before);
+    chunkStart = atom.range.start;
   }
-  const tail = compact(body.slice(chunkStart));
+  const tail = compact(source.slice(chunkStart, contentRange.end));
   if (tail) turns.push(tail);
   lines.push(...turns.map((turn) => `  ${turn}`));
   lines.push(`</${id}>`);
@@ -64,7 +51,7 @@ export function formatScript(sourceName: string, source: string): string {
     } else if (output.length) {
       output.push("");
     }
-    output.push(...formatSegment(source.slice(start, end), segment.id, segment.selfClosing));
+    output.push(...formatSegment(source, segment));
     cursor = end;
   }
   const tail = formatOutside(source.slice(cursor));

package/packages/script/src/manifest.ts

@@ -64,9 +64,9 @@ 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 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.",
+        "Dual Text is written `<display | speech>`: the left side reaches Caption and the right side reaches dialogue and speech. `<display|>` shares the displayed prose with speech and forms the same complete alignment unit; its word times remain individual. `<|speech>` speaks without displaying. The explicit or shared speech must contain a spoken word; markers and punctuation alone supply no correspondence.",
         "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.",
+        "A flat token attribute follows a complete display token as `{name}` or `{name=value}`; multiple attributes use one comma-separated block. Zero-width markers and ordinary-prose comments do not interrupt that attachment; prose whitespace does. Attributes do not nest, do not carry timing, and never split a Dual Alignment Unit.",
         "Selection and Moment markers are fully enclosed in `@{...}` with all sigils inside. They are zero-width, share one name namespace, and may not split a speech token. Surrounding prose spaces remain content; do not add spaces to delimit a name:",
         [
           "| Marker | Meaning |",

package/packages/script/src/parser.ts

@@ -492,10 +492,10 @@ export function parseScript(
       if (!shared && raw[index] === "{") fail("SCRIPT_DUAL_SPEECH_ATTRIBUTE", "Display attributes belong to the display side; escape literal braces in speech.", absoluteStart + index);
       if (shared && raw[index] === "{") {
         const before = raw.slice(partStart, index);
-        if (!before || /\s$/u.test(before)) {
+        addLiteral(before, absoluteStart + partStart);
+        if (!runText || /\s$/u.test(runText)) {
           fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must immediately follow a display token.", absoluteStart + index);
         }
-        addLiteral(before, absoluteStart + partStart);
         const block = parseAttributeBlock(raw.slice(index), absoluteStart + index);
         runAttributes.push({ position: runText.length, offset: absoluteStart + index,
           end: absoluteStart + index + block.length, attributes: block.attributes });
@@ -517,20 +517,20 @@ export function parseScript(
     addLiteral(raw.slice(partStart), absoluteStart + partStart);
     const display = caption ?? spokenParts.join("");
     const sharedMarks = finishLexicalRun();
-    if (shared && tokens.length === startToken) {
-      fail("SCRIPT_DUAL_EMPTY", "Dual Text with omitted speech must contain spoken text on its display side.", absoluteStart);
-    }
-    if (tokens.length > startToken) {
-      addCaptionRegion(
-        display,
-        current!.id,
-        startToken,
-        tokens.length,
-        cleanProjection(display) ? "alias" : "hidden",
-        { start: sourceOffset + absoluteStart, end: sourceOffset + absoluteStart + raw.length },
-        shared ? sharedMarks : marks,
-      );
+    if (tokens.length === startToken) {
+      fail("SCRIPT_DUAL_EMPTY", shared
+        ? "Dual Text with omitted speech must contain spoken text on its display side."
+        : "Dual Text speech side must contain a spoken word, not only markers or punctuation.", absoluteStart);
     }
+    addCaptionRegion(
+      display,
+      current!.id,
+      startToken,
+      tokens.length,
+      cleanProjection(display) ? "alias" : "hidden",
+      { start: sourceOffset + absoluteStart, end: sourceOffset + absoluteStart + raw.length },
+      shared ? sharedMarks : marks,
+    );
   };
 
   const closeCurrent = (end: number, selfClosing: boolean, contentEnd = end): void => {
@@ -626,18 +626,13 @@ export function parseScript(
         const speech = inside.slice(pipe + 1);
         if (!speech.trim()) {
           consumeSpeechSide(inside.slice(0, pipe), offset + 1, undefined);
-          finishLexicalRun();
           offset = end + 1;
           continue;
         }
         assertDualDisplayLiteral(inside.slice(0, pipe), offset + 1);
         const markedDisplay = parseMarkedDisplay(inside.slice(0, pipe), offset + 1);
         const display = markedDisplay.display;
-        if (!speech.replace(/@\{[^{}]*\}/gu, "").trim()) {
-          fail("SCRIPT_DUAL_EMPTY", "Dual Text speech side must not be empty.", offset);
-        }
         consumeSpeechSide(speech, offset + pipe + 2, display, markedDisplay.marks);
-        finishLexicalRun();
         offset = end + 1;
         continue;
       }
@@ -674,7 +669,7 @@ export function parseScript(
     for (const piece of literalPieces(raw, textStart)) addText(piece.value, piece.value, piece.start, piece.end, true, piece.positions);
     if (source[offset] === "{") {
       const block = parseAttributeBlock(source.slice(offset), offset);
-      if (!raw || /\s$/u.test(raw)) {
+      if (!runText || /\s$/u.test(runText)) {
         fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must immediately follow a display token.", offset);
       }
       runAttributes.push({ position: runText.length, offset, end: offset + block.length, attributes: block.attributes });