@hypit/hypit 0.2.6 → 0.2.8

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

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/seedance/README.md

@@ -34,22 +34,20 @@ responsible for any additional service-specific input limits.
 
 ## Visual reference metadata
 
-Declare whether each image or video contains a person/avatar reference, including an AI-generated
-human likeness. This describes the supplied material, independently of the prompt's requested action:
+Every supplied image or video must explicitly declare `person-reference`: `true` if it contains
+a person, `false` otherwise. Classify the supplied material, not the requested result.
 
 ```xml
-<seedance:ReferenceVideo id="dance" model="mini" prompt={direction} duration="8">
+<seedance:ReferenceVideo id="take" model="mini" prompt={direction} duration="8">
   <seedance:Reference image={presenter.image} person-reference="true"/>
-  <seedance:Reference video={motion.video} person-reference="true"/>
+  <seedance:Reference video={presenter.video} person-reference="true"/>
   <seedance:Reference image={room.image} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
-`person-reference` is optional, accepts literal `true` or `false`, and applies to image/video, not
-voice audio. Omission carries no classification; it is distinct from explicitly declaring false.
-Inspect the actual reference when deciding the value. For `FrameVideo`, use
-`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
-inputs. A last-frame classification requires a last-frame input.
+Missing or non-boolean declarations are rejected; there is no default or automatic face detection.
+Audio must omit this field. `FrameVideo` requires `first-frame-person-reference` and, when a last
+frame is supplied, `last-frame-person-reference`. A last-frame classification requires a last frame.
 
 | Supplied visual input | Authored attribute | Request port |
 | --- | --- | --- |
@@ -66,23 +64,18 @@ These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
   last-frame={empty-room.image} last-frame-person-reference="false"/>
 ```
 
-Classify the material supplied to this request, not the intended result. A dance video with a person
-still needs `true` when used only for motion, even if the prompt asks for a different performer.
-An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
-excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
-Identity and action direction remain in the prompt and references.
+Inspect the selected video excerpt, not only its opening frame. An empty room stays `false` when
+the prompt asks to add a person. The flag does not lock identity; direction and references own that.
 
 The SVML author declares this parameter on each reference input. Admitted files, generated
 images/videos and reused Results use the same attributes. For a future output, declare the intended
 reference classification explicitly; if its contents are uncertain, generate and inspect that
 material before using it downstream.
 
-The model's media ports carry this as `fields.personReference`. Providers interpret it through their
-service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
+Direct requests require the same boolean in `fields.personReference`. Providers interpret it through
+their service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
 `is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
 request. A project Provider maps it according to its own API.
-Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
-as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
 
 Video references can carry motion or camera behavior while image references carry the target
 appearance. Request duration and reference-clip duration are different limits. Check the selected

package/packages/seedance/src/index.ts

@@ -17,7 +17,7 @@ export type SeedanceModel = typeof seedanceModels[number];
 
 const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
 
-const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" }, optional: true }] as const;
+const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" } }] as const;
 
 const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
 
@@ -175,9 +175,9 @@ const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
   },
 ];
 
-const personReferenceAttribute = (name: string): SurfaceAttributeVocabulary => ({
-  name, kind: "literal", required: false, values: ["true", "false"],
-  summary: "Declares whether this visual input contains a person/avatar reference, including an AI-generated human likeness. Omission leaves it unclassified.",
+const personReferenceAttribute = (name: string, required = false): SurfaceAttributeVocabulary => ({
+  name, kind: "literal", required, values: ["true", "false"],
+  summary: "Required for each supplied image/video, including first/last frames: true if it contains a person, false otherwise. Audio must omit it.",
 });
 
 const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
@@ -235,7 +235,7 @@ export const seedanceMarkupSurfaces = [
       summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
       attributes: [
         ...seedanceCommonAttributes,
-        personReferenceAttribute("first-frame-person-reference"),
+        personReferenceAttribute("first-frame-person-reference", true),
         personReferenceAttribute("last-frame-person-reference"),
         {
           name: "first-frame",
@@ -253,7 +253,7 @@ export const seedanceMarkupSurfaces = [
         },
       ],
       ports: seedanceVideoPort,
-      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>',
       notes: [
         ...seedanceSettingNotes,
         "Both frames are ordinary image Artifact edges; the Surface copies no runtime media into request metadata.",
@@ -316,7 +316,7 @@ export const seedanceMarkupSurfaces = [
       notes: [
         ...seedanceSettingNotes,
         "The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
-        "`person-reference` applies to image/video references; voice audio carries no visual classification. The Provider transports the declared fact according to its API.",
+        "Every image/video Reference requires `person-reference=\"true|false\"`. Classify the supplied material; audio must omit the field. The Provider transports it according to its API.",
         "A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
       ],
     },

package/packages/seedance/src/surface.ts

@@ -146,8 +146,10 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
 }
 
 function personReferenceFields(element: StructuredElement, name: string) {
-  return element.attributes[name] === undefined ? undefined
-    : { personReference: booleanAttribute(element, name, false) };
+  if (element.attributes[name] === undefined) {
+    throw new Error(`${element.name}.${name} is required for this visual reference; set true if it contains a person, false otherwise`);
+  }
+  return { personReference: booleanAttribute(element, name, false) };
 }
 
 function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
@@ -217,8 +219,8 @@ function referenceInputs(
     const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
     if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
     const role = kinds[0]!;
-    const fields = personReferenceFields(child, "person-reference");
-    if (role === "audio" && fields !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    if (role === "audio" && child.attributes["person-reference"] !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    const fields = role === "audio" ? undefined : personReferenceFields(child, "person-reference");
     result.push({
       ...(fields === undefined ? {} : { fields }),
       role,
@@ -242,13 +244,12 @@ function frameInputs(
 ): MediaInput[] {
   const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
   const firstFields = personReferenceFields(element, "first-frame-person-reference");
-  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, ...(firstFields === undefined ? {} : { fields: firstFields }) }];
-  const lastFields = personReferenceFields(element, "last-frame-person-reference");
-  if (lastFields !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
+  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, fields: firstFields }];
+  if (element.attributes["last-frame-person-reference"] !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
   if (element.attributes["last-frame"] !== undefined) {
     result.push({
       port: "lastFrame",
-      ...(lastFields === undefined ? {} : { fields: lastFields }),
+      fields: personReferenceFields(element, "last-frame-person-reference"),
       role: "image",
       source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
     });

package/packages/seedance-kits/README.md

@@ -23,8 +23,8 @@ ordinary explicit graph edges:
 
 <seedance:ReferenceVideo id="broll" model="mini" prompt={broll-prompt}
   duration="5" resolution="720p" aspect-ratio="9:16">
-  <seedance:Reference image={scene}/>
-  <seedance:Reference image={product}/>
+  <seedance:Reference image={scene} person-reference="false"/>
+  <seedance:Reference image={product} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
@@ -154,7 +154,8 @@ For a multi-scene B-roll montage, `story` can name the references in scene order
 action. Choose an edit language compatible with cuts. “Continuous within each scene” and “one
 continuous shot for the whole montage” ask for different results.
 
-Visual input classification belongs to the Seedance Reference, separately from Kit text. The
+Every Seedance image/video Reference requires `person-reference="true|false"`: true if the supplied
+material contains a person, false otherwise. Audio must omit it. The
 [Seedance author package](../seedance/README.md#visual-reference-metadata) explains `person-reference`
 and its frame variants. The Kit supplies direction; the actual reference edges supply media and
 metadata. For movement-led work, a reference video can carry the motion while the text explains what

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) {