@hypit/hypit 0.2.6 → 0.2.7

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 });

package/packages/script/src/surface.ts

@@ -24,6 +24,10 @@ function findClose(input: ScriptSurfaceInput): { readonly start: number; readonl
   const close = `</${input.tag}>`;
   let cursor = input.contentStart;
   while (cursor < input.source.length) {
+    if (input.source[cursor] === "\\") {
+      cursor += 2;
+      continue;
+    }
     if (input.source.startsWith("<!--", cursor)) {
       const commentEnd = input.source.indexOf("-->", cursor + 4);
       if (commentEnd < 0) {
@@ -33,9 +37,7 @@ function findClose(input: ScriptSurfaceInput): { readonly start: number; readonl
       continue;
     }
     if (input.source.startsWith(close, cursor)) {
-      let slashes = 0;
-      for (let before = cursor - 1; before >= 0 && input.source[before] === "\\"; before -= 1) slashes += 1;
-      if (slashes % 2 === 0) return { start: cursor, end: cursor + close.length };
+      return { start: cursor, end: cursor + close.length };
     }
     cursor += 1;
   }

package/packages/script/src/types.ts

@@ -35,7 +35,7 @@ export type ParsedSegment = NarrativeSegment & {
   readonly index: number;
   readonly atoms: readonly ParsedAtom[];
   readonly range: SourceRange;
-  /** Exact body range between the Segment tags, used only for source-preserving marker edits. */
+  /** Exact body range between Segment tags for Script-owned source edits and formatting. */
   readonly contentRange: SourceRange;
   readonly selfClosing: boolean;
 };

package/packages/source/README.md

@@ -9,5 +9,5 @@ It recognizes exactly one mandatory bounded Header:
 ```
 
 The Header selects an exact trusted Frontend. There is no suffix dispatch and no default parser.
-The package masks the Header while preserving character offsets, but does not recognize imports,
+The package masks the Header while preserving UTF-16 source offsets and line breaks, but does not recognize imports,
 XML, Script, Recipes, Run syntax or domain Types. Those belong to the selected Frontend.

package/packages/source/src/header.ts

@@ -75,6 +75,7 @@ export function parseSourceHeader(sourceName: string, text: string): SourceHeade
 
 /** Preserve every original offset while making the Header ordinary whitespace to body Frontends. */
 export function maskSourceHeader(text: string, header: SourceHeader): string {
-  const prefix = text.slice(0, header.end).replace(/[^\r\n]/gu, " ");
+  // Source ranges use UTF-16 offsets: replace each code unit, not each code point.
+  const prefix = text.slice(0, header.end).replace(/[^\r\n]/g, " ");
   return `${prefix}${text.slice(header.end)}`;
 }

package/packages/studio/README.md

@@ -1,5 +1,13 @@
 # Hypit Studio
 
+For direct picture inspection, `hypit snapshot --studio <studio-url>` reads the current compiled
+`HyperframesDocument` from `GET /__studio/document` and its existing `/__studio/material/<resource>`
+resources. `GET /__studio/visual.html` exposes the same materialized picture without the interactive
+Studio playback shim or audio. Both representations come from the same compilation as the displayed
+preview. The snapshot invocation uses the selected Runtime Profile's frame Provider and creates no
+Build. During a pending Source compilation the export route reports that state; a failed update
+reports its error instead of returning the previous picture as current.
+
 The single official Web Studio for SVML. It opens an explicit Run Source,
 traces its Film or Render target back to the semantic and visual projections
 Studio can edit, runs deterministic Producers and explicitly permitted transient Needs, and composites the
@@ -159,6 +167,11 @@ the selected entity. A reference can resolve to a shared Frame or Recipe, so one
 may affect several consumers. Structured fields save together when editing ends and the value is complete; missing required values stay in the editor with a completion hint.
 Check save status; source conflicts reject stale edits rather than overwrite newer files.
 
+Script source ranges come from its raw Surface and Companion. Marker edits use Script's parsed
+anchors and preserve unrelated prose, whitespace and word attributes; the displayed timeline words
+are not a replacement text source. Recipe parameter reads use the same Source Header preparation
+as compilation, preserving UTF-16 offsets for the exact property being edited.
+
 The Timeline owns the editor's complete range; displayed objects do not extend it. Take placement
 and complete extent are reference information in Studio.
 

package/packages/studio/src/feedback-server.ts

@@ -3,6 +3,7 @@ import { relative } from "node:path";
 import type { Plugin } from "vite";
 import { createFeedbackStore, FeedbackConflict } from "./feedback-store.js";
 import { readFeedbackMutation } from "./feedback.js";
+import { allowsStudioMutation } from "./mutation-origin.js";
 import type { FeedbackDocument, FeedbackView } from "./feedback.js";
 
 /** Review storage is separate from compilation, Results and Agent delivery. */
@@ -23,6 +24,12 @@ export function studioFeedbackPlugin(workspaceRoot: string, runPath: string): Pl
       server.httpServer?.once("close", () => watcher.close());
       server.middlewares.use((request, response, next) => {
         if (new URL(request.url ?? "/", "http://studio.hypit.local").pathname !== "/__studio/feedback") return next();
+        if (request.method === "POST" && !allowsStudioMutation(request.headers)) {
+          response.statusCode = 403;
+          response.setHeader("content-type", "application/json; charset=utf-8");
+          response.end(JSON.stringify({ error: "Studio mutation must come from this local Studio session." }));
+          return;
+        }
         response.setHeader("content-type", "application/json; charset=utf-8");
         response.setHeader("cache-control", "no-store");
         void (async () => {

package/packages/studio/src/mutation-origin.ts

@@ -0,0 +1,20 @@
+import type { IncomingHttpHeaders } from "node:http";
+
+/** Studio writes belong to the local page serving this Studio session. */
+export function allowsStudioMutation(headers: IncomingHttpHeaders): boolean {
+  const host = headers.host;
+  if (host === undefined) return false;
+  let target: URL;
+  try { target = new URL(`http://${host}`); } catch { return false; }
+  if (!["localhost", "127.0.0.1", "[::1]"].includes(target.hostname) || target.host !== host.toLowerCase()) return false;
+
+  const origin = headers.origin;
+  if (origin !== undefined) {
+    let source: URL;
+    try { source = new URL(origin); } catch { return false; }
+    if (source.origin !== origin || source.origin !== target.origin) return false;
+  }
+
+  const site = headers["sec-fetch-site"];
+  return site === undefined || site === "same-origin" || site === "none";
+}

package/packages/studio/src/parameters.ts

@@ -17,6 +17,7 @@ import type {
 } from "@hypit/studio-adapter";
 import { parseSvs } from "@hypit/svs";
 import { parseOpeningTag } from "@hypit/markup";
+import { prepareAuthorSource } from "@hypit/elaborator";
 import { parameterControlForSchema, parameterRecordSchema } from "./parameter-values.js";
 import type { CanonicalValue } from "@hypit/protocol";
 
@@ -132,12 +133,6 @@ function sourceAbsolute(root: string, path: string, base?: string): string {
   return resolve(directory, path);
 }
 
-function svsText(source: string): string {
-  const header = /^\s*<\?svml[\s\S]*?\?>/u.exec(source);
-  if (header === null) return source;
-  return `${header[0].replace(/[^\r\n]/gu, " ")}${source.slice(header[0].length)}`;
-}
-
 function recipeParameters(input: {
   readonly root: string;
   readonly files: readonly StudioSourceFile[];
@@ -176,7 +171,8 @@ function recipeParameters(input: {
   const source = sourceFor(input.root, imported.source, input.files, input.current.path);
   if (source === undefined || source.language !== "svs") return [];
   const recipePath = parts.join(".");
-  const parsed = parseSvs(source.path, svsText(source.text));
+  const prepared = prepareAuthorSource({ id: source.path, name: source.path, text: source.text });
+  const parsed = parseSvs(source.path, prepared.text);
   const recipe = parsed.recipes.find((item) => item.value.path === recipePath);
   if (recipe === undefined) return [];
   return input.recipe.bindings.flatMap((declaration): readonly StudioSourceBinding[] => {

package/packages/studio/src/preview/render.ts

@@ -1,5 +1,6 @@
 import type { AudioTrack, Composition } from "@hypit/composition";
 import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";
+import type { HyperframesDocument } from "@hypit/hyperframes";
 import type { ProgramSpace } from "@hypit/program-space";
 
 import { injectRuntimeShim } from "./runtime-shim.js";
@@ -19,6 +20,11 @@ export type RenderInput = {
  * material all come from the projection selected by the Run.
  */
 export function renderPreview(input: RenderInput): string {
+  return renderStudioProgramme(input).preview;
+}
+
+/** The same compiled picture serves immediate frame capture and interactive playback. */
+export function renderStudioProgramme(input: RenderInput): { readonly document: HyperframesDocument; readonly html: string; readonly preview: string } {
   const document = compileHyperframesDocument(input.composition, input.space);
   const html = materializeHyperframesHtml(document, (artifact) => {
     // The only Artifacts a preview can reference are files the author already
@@ -51,5 +57,5 @@ export function renderPreview(input: RenderInput): string {
         fadeInSamples: clip.fadeInSamples, fadeOutSamples: clip.fadeOutSamples,
       }))}"></audio>`;
     }).join("");
-  return injectRuntimeShim(html, audio);
+  return { document, html, preview: injectRuntimeShim(html, audio) };
 }

package/packages/studio/src/server.ts

@@ -15,6 +15,7 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
 import { loadStudioRun } from "./run.js";
+import { allowsStudioMutation } from "./mutation-origin.js";
 import { parameterAuthorValue, parameterOption, serializeParameterValue, serializeAttributeGroup, validateParameterValue } from "./parameter-values.js";
 import { readStudioSession } from "./session.js";
 import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
@@ -80,6 +81,8 @@ class StudioMutationRejected extends Error {}
 
 export function studioPlugin(options: StudioPluginOptions): Plugin {
   let snapshot: StudioSnapshot | undefined;
+  let visualHtml: string | undefined;
+  let visualDocument: import("@hypit/hyperframes").HyperframesDocument | undefined;
   let failure: StudioFailure | undefined;
   let material: ReadonlyMap<string, ServedFile> = new Map();
   let revision = 0;
@@ -158,6 +161,8 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       if (attempt !== requestedRevision) return;
       revision = attempt;
       snapshot = result.snapshot;
+      visualHtml = result.visualHtml;
+      visualDocument = result.document;
       material = result.material;
       failure = undefined;
       if (notify) server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
@@ -473,6 +478,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       value.middlewares.use((request, response, next) => {
         const url = new URL(request.url ?? "/", "http://studio.hypit.local");
         if (request.method === "PUT" && url.pathname === "/__studio/source") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             let acquired = false;
             try {
@@ -524,6 +533,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (request.method === "PUT" && url.pathname === "/__studio/artifact-name") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             try {
               const chunks: Buffer[] = [];
@@ -546,6 +559,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (request.method === "POST" && url.pathname === "/__studio/mutation") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             try {
               const chunks: Buffer[] = [];
@@ -580,6 +597,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           next();
           return;
         }
+        if (url.pathname === "/__studio/visual.html" || url.pathname === "/__studio/document") {
+          void (async () => {
+            if (timer !== undefined || publishing > 0) {
+              json(response, 409, { error: "Studio is compiling a Source change; capture after the updated preview is ready." });
+              return;
+            }
+            if (snapshot === undefined && failure === undefined) await publish(++requestedRevision);
+            if (failure !== undefined || visualHtml === undefined) {
+              json(response, 500, failure ?? { error: "Studio has no compiled picture." });
+              return;
+            }
+            if (url.pathname === "/__studio/document") {
+              json(response, 200, visualDocument);
+              return;
+            }
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            response.setHeader("cache-control", "no-store");
+            response.end(request.method === "HEAD" ? undefined : visualHtml);
+          })();
+          return;
+        }
         if (url.pathname === "/__studio/session") {
           void (async () => {
             if (snapshot === undefined && failure === undefined) {

package/packages/studio/src/session.ts

@@ -9,7 +9,7 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { Observations } from "./observe.js";
 import { preview } from "./programme.js";
-import { renderPreview } from "./preview/render.js";
+import { renderStudioProgramme } from "./preview/render.js";
 import type { RunPlan } from "./run.js";
 import type { StudioSnapshot } from "./shared.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
@@ -47,6 +47,8 @@ function sourceFiles(run: RunPlan): readonly StudioSourceFile[] {
 
 export type StudioSession = {
   readonly snapshot: StudioSnapshot;
+  readonly document: import("@hypit/hyperframes").HyperframesDocument;
+  readonly visualHtml: string;
   readonly material: ReadonlyMap<string, ServedFile>;
   readonly observations: Observations;
   readonly projections: readonly StudioViewRequirement[];
@@ -77,7 +79,7 @@ export async function readStudioSession(input: {
     projections: inspection.projections,
     ...(input.transientExecution === undefined ? {} : { transientExecution: input.transientExecution }),
   });
-  const rendered = renderPreview({
+  const rendered = renderStudioProgramme({
     composition: built.composition,
     space: built.space as never,
     served: new Set(built.served.keys()),
@@ -85,6 +87,8 @@ export async function readStudioSession(input: {
   const text = readFileSync(input.run.authorSource, "utf8");
   const files = sourceFiles(input.run);
   return {
+    document: rendered.document,
+    visualHtml: rendered.html,
     snapshot: snapshot(input.registry, built, {
       revision: input.revision,
       path: input.sourcePath ?? input.run.authorSource,
@@ -99,7 +103,7 @@ export async function readStudioSession(input: {
       },
       canvas: built.canvas,
       frameRate: built.frameRate,
-      preview: { kind: "hyperframes", srcdoc: rendered },
+      preview: { kind: "hyperframes", srcdoc: rendered.preview },
       workspaceRoot: input.workspaceRoot,
       sourceFiles: files,
       surfaces: input.domain.surfaces,

package/packages/studio/src/ui/syntax.ts

@@ -1,9 +1,8 @@
 /**
  * A tokenizer for SVML's own surface syntax.
  *
- * SVML has a small, closed grammar — tags, quoted strings, whole-value
- * references, and Script prose with markers — so it is tokenized directly rather
- * than through a general highlighter that has no grammar for it. The Script
+ * Recognize the common Markup shell and Script prose for highlighting, without
+ * validating package-owned Surfaces. The Script
  * markers are the point: `@{claim} … @{/claim}` is what a Media Item binds to, so it
  * has to read as a distinct thing from an ordinary attribute.
  *
@@ -105,8 +104,7 @@ export function tokenizeSvml(source: string): readonly Token[] {
       cursor = nameStart + name[0].length;
       cursor = tokenizeAttributes(source, cursor, push);
 
-      // Script is the language's one Raw Surface: its body is prose with
-      // markers, not markup, and must be scanned by different rules.
+      // Script's Raw Surface has its own prose grammar.
       if (!closing && localName(name[0]) === "script" && source[cursor - 2] !== "/") {
         cursor = tokenizeScriptBody(source, cursor, name[0], push);
       }
@@ -167,6 +165,7 @@ function tokenizeAttributes(source: string, from: number, push: Push): number {
 function tokenizeScriptBody(source: string, from: number, tag: string, push: Push): number {
   const close = `</${tag}>`;
   let cursor = from;
+  let inSegment = false;
   while (cursor < source.length) {
     if (source[cursor] === "\\") { cursor += 2; continue; }
     if (source.startsWith(close, cursor)) {
@@ -199,14 +198,16 @@ function tokenizeScriptBody(source: string, from: number, tag: string, push: Pus
       }
       const closing = source[cursor + 1] === "/";
       const nameStart = cursor + (closing ? 2 : 1);
-      const name = NAME.exec(source.slice(nameStart));
-      if (name === null) { cursor += 1; continue; }
       const end = source.indexOf(">", nameStart);
       const stop = end < 0 ? source.length : end + 1;
+      const selfClosing = end >= 0 && source[end - 1] === "/";
+      const nameEnd = end < 0 ? stop : end - (selfClosing ? 1 : 0);
       push(cursor, nameStart, "punct");
-      // An upper-case tag inside Script is a Role Cue, not a Segment.
-      push(nameStart, nameStart + name[0].length, /^[A-Z]/u.test(name[0]) ? "role" : "tag");
-      push(nameStart + name[0].length, stop, "punct");
+      // Context distinguishes Segments from Role Cues, regardless of language or case.
+      push(nameStart, nameEnd, inSegment && !closing ? "role" : "tag");
+      push(nameEnd, stop, "punct");
+      if (closing) inSegment = false;
+      else if (!inSegment && !selfClosing) inSegment = true;
       cursor = stop;
       continue;
     }

package/packages/temporal-markup/EDITING.md

@@ -164,7 +164,7 @@ write target. The `fixed` case means no temporal gesture writes that endpoint, n
 parameter editing is forbidden.
 
 - `@hypit/script` owns tokenization, anchor identities, legal marker sites, and structural writeback.
-  It normalizes equivalent marker whitespace, retains punctuation and attributes, writes coincident
+  It relocates markers without rewriting unrelated prose whitespace, retains punctuation and attributes, writes coincident
   markers together, and preserves all unrelated relationships and caption information.
 - `@hypit/temporal-markup` owns the interpretation of each time form and declares its write targets.
   Direct semantic references expose semantic targets; quoted time expressions expose parameter

package/packages/video-cli/README.md

@@ -1,8 +1,8 @@
 # `@hypit/video-cli`
 
 Official video command application. It selects the Markup compiler Host and supplies one editable
-starter Runtime Profile. The CLI still imports no Provider or Store implementation; installed packages
-are activated only by explicit Source imports or Profile `use` entries.
+starter Runtime Profile. Execution Endpoints are selected by Profile `use` entries; Source imports
+activate author packages. Immediate tools own their temporary input/output resource storage.
 
 Every Frontend, Surface, deterministic Producer and Validator is activated from Source imports.
 Installing a new author package therefore does not require a video CLI or Core release. Source
@@ -67,9 +67,35 @@ to the chosen file. `measure` estimates a passage locally:
 
 ```bash
 hypit transcribe reference.mp4 --to notes/reference.transcript.json --language en
+hypit transcribe assets/recorded-voice.wav --to notes/voice.transcript.json --language en
 hypit measure main.svml --segment hook --language en --pace normal --rounding round
 ```
 
+`snapshot` follows the same immediate invocation model for picture inspection. Prefer it for
+existing production states and motion sequences, keeping Studio for playback with sound and Builds
+for encoded delivery:
+
+```bash
+hypit snapshot --studio http://localhost:5191 --at-frame 240,255,269 --to evidence/states
+hypit snapshot --studio http://localhost:5191 --start-frame 240 --end-frame-exclusive 270 \
+  --grid 4x3 --cell 480 --to evidence/motion
+hypit snapshot ./picture/index.html --at-frame 240 --to evidence/detail
+```
+
+`--studio` reads Studio's current compiled document and its declared resources; a path or HTML URL
+reads materialized HTML with inline scripts/styles and directly addressed media/fonts. The Profile's
+`@hypit/render-hyperframes@1#render-frames` Endpoint returns PNGs in selected-frame order.
+`--runtime` and `--workspace` select the environment just as for `transcribe`. The call streams
+resources through a temporary `FileResourceStore`, writes full-size PNGs and optional grid pages,
+then releases that temporary storage. `--to` names a new directory. `--json` reports paths and original
+frame positions. Grid labels remain outside the picture. No Build, Worker receipt or video encoding
+is created. Provider-owned browser preparation is unchanged.
+
+`media frames --every-frame` and `media tiles --every-frame` decode every source frame in a selected
+half-open seconds interval once. Native timestamps, including variable frame rate, are read from
+decoder PTS and time base. `tiles --ranges <json> --every-frame` decodes each listed interval and
+paginates its images. `--transcript` adds word context. This native path uses no FPS resampling.
+
 For `transcribe`, set `--language` to an explicit lowercase two- or three-letter spoken language code,
 such as `en`, `zh` or `ko`. The selected service owns which languages it can align. Chinese speech uses `zh`, including
 Chinese speech containing English names. The request selects the recognition language and
@@ -106,6 +132,9 @@ prints what a Source may write:
 ```bash
 hypit media probe reference.mp4
 hypit media cut reference.mp4 --start 12 --end 19.5 --label-time --to notes/hook.mp4
+hypit media cut assets/talk.mp4 --start 12 --end 19.5 --to assets/opening.mp4
+hypit media cut assets/talk.mp4 --keep 12:15.5 --keep 16:19.5 --to assets/opening-edited.mp4
+hypit media cut assets/narration.wav --keep 0.3:4.1 --keep 4.6:9.2 --to assets/narration-edited.wav
 hypit media frames reference.mp4 --at 12.4,13.1 --label-time --to notes/hook-frames
 hypit media tile reference.mp4 --start 12 --end 19.5 --to notes/hook-grid.jpg
 hypit media tile reference.mp4 --at 12.4,13.1,14.8 --columns 3 --to notes/exact-grid.jpg
@@ -119,7 +148,21 @@ hypit vocabulary @hypit/media-pipeline --tag StillVideo
 hypit vocabulary --visual text
 ```
 
-`cut` isolates the requested interval and can visibly overlay source time on the evidence copy.
+`probe` accepts audio-only files as well as video. `cut` keeps one interval using `--start` and
+`--end`, or joins explicitly retained, ordered, non-overlapping intervals using repeated
+`--keep start:end` in source seconds. The latter is useful for removing gaps inside one recorded
+performance; it does not decide where Script Segments belong. Video retains its available picture
+and sound together (MP4 is a useful output container); audio-only outputs PCM WAV. A silent source
+video stays silent. The
+`--json` reports the source intervals, their nominal positions on the new local clock, and the
+measured output duration; actual frame and sample boundaries can differ slightly from the nominal
+positions. It writes a new file and refuses to
+overwrite an existing one. `--label-time` retains its single-video-interval role: it visibly
+overlays source time on an inspection copy, not on the clean production media.
+
+`transcribe` also accepts audio or video. Its transcript refers to the *input file's* clock. A
+cut or joined file has a new clock; use the final recorded performance and its Script in the
+Build's semantic preparation rather than treating source transcript timestamps as final timing.
 `frames` writes one JPEG per requested time, selecting the first decoded frame at or after it.
 Visible frame labels use that frame's actual timestamp, as do the labels below each `tile` cell.
 Sampling is shared by `frames`, `tile` and `tiles`:
@@ -149,7 +192,7 @@ and its Endpoint remain separate. `boundaries` reports adjacent-frame
 change candidates and their measured scores; it does not suppress short changes or call them shots.
 `prepare-fetch` explicitly prepares the locked downloader environment; `fetch` requires it and
 turns a link into a file with the pinned yt-dlp; [the downloader package](../yt-dlp/README.md)
-owns its dependencies, download choices and file handling. Commands that create evidence write only
+owns its dependencies, download choices and file handling. Commands that create files write only
 what `--to` names and refuse to overwrite. `vocabulary` reads the installed
 manifests: every package with its tags and models, or one package's Surfaces with their attributes,
 children and example, or the value shapes a drawing Producer must emit.

package/packages/video-cli/package.json

@@ -18,6 +18,7 @@
     "@hypit/driver-node": "workspace:*",
     "@hypit/estimate": "workspace:*",
     "@hypit/generation": "workspace:*",
+    "@hypit/hyperframes": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/model-kit": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
@@ -28,6 +29,8 @@
     "@hypit/provider-monid": "workspace:*",
     "@hypit/provider-pollo": "workspace:*",
     "@hypit/provider-tokendance": "workspace:*",
+    "@hypit/render-hyperframes": "workspace:*",
+    "@hypit/resource-store-fs": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-kit": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",