@hypit/hypit 0.1.3 → 0.1.4

package/packages/script/README.md

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

package/packages/script/src/edit.ts

@@ -1,7 +1,9 @@
 import type { SourceRange } from "@hypit/protocol";
 
-import { narrativeValue } from "./narrative.js";
+import { canonicalStringify } from "@hypit/protocol";
+import { captionDocument, narrativeValue } from "./narrative.js";
 import { parseScript } from "./parser.js";
+import { cleanHorizontalProse } from "./lexical.js";
 import type { Affinity, ParsedNarrative, SemanticAnchor } from "./types.js";
 
 export type ScriptAnchorEditSite = {
@@ -47,18 +49,16 @@ export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptA
     const segment = segments.get(segmentId);
     if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${segmentId}.`);
     if (anchor.kind === "segment-start") {
-      const first = parsed.tokens[segment.tokenStart];
       return {
         anchorId: anchor.id, kind: anchor.kind, segmentId,
-        offset: first?.range.start ?? segment.contentRange.start,
+        offset: segment.contentRange.start,
         affinity: "left", placement: "before",
       };
     }
     if (anchor.kind === "segment-end") {
-      const last = parsed.tokens[segment.tokenEndExclusive - 1];
       return {
         anchorId: anchor.id, kind: anchor.kind, segmentId,
-        offset: last?.range.end ?? segment.contentRange.end,
+        offset: segment.contentRange.end,
         affinity: "right", placement: "after",
       };
     }
@@ -66,10 +66,10 @@ export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptA
     if (token === undefined) throw new Error(`Semantic Anchor ${anchor.id} names no Script Token.`);
     return anchor.kind === "token-start" ? {
       anchorId: anchor.id, kind: anchor.kind, segmentId,
-      offset: token.range.start, affinity: "right", placement: "before",
+      offset: token.editRange.start, affinity: "right", placement: "before",
     } : {
       anchorId: anchor.id, kind: anchor.kind, segmentId,
-      offset: token.range.end, affinity: "left", placement: "after",
+      offset: token.editRange.end, affinity: "left", placement: "after",
     };
   });
 }
@@ -79,16 +79,6 @@ function marker(id: string, edge: "open" | "close", affinity: Affinity): string
   return affinity === "left" ? `@/${id}` : `@/${id}~`;
 }
 
-function insertion(id: string, edge: "open" | "close", site: ScriptAnchorEditSite): string {
-  const value = marker(id, edge, site.affinity);
-  return site.placement === "before" ? `${value} ` : ` ${value}`;
-}
-
-function momentInsertion(id: string, site: ScriptAnchorEditSite): string {
-  const value = site.affinity === "left" ? `~@${id}!` : `@${id}!`;
-  return site.placement === "before" ? `${value} ` : ` ${value}`;
-}
-
 function applyEdits(source: string, edits: readonly Edit[]): string {
   let next = source;
   const ordered = [...edits].sort((left, right) =>
@@ -102,73 +92,133 @@ function applyEdits(source: string, edits: readonly Edit[]): string {
   return next;
 }
 
-/**
- * Relocate one shared Selection by anchor identity. The returned Source is accepted only when
- * reparsing proves the requested public Narrative, so Studio never edits prose by frame guess.
- */
-export function adjustScriptSelection(input: {
+type AdjustmentInput = {
   readonly sourceName: string;
   readonly source: string;
   readonly parsed: ParsedNarrative;
-  readonly adjustment: ScriptSelectionAdjustment;
-}): string {
-  const selection = input.parsed.selections.find((candidate) => candidate.id === input.adjustment.id);
-  if (selection === undefined) throw new Error(`Script Selection ${input.adjustment.id} does not exist.`);
-  const sites = new Map(scriptAnchorEditSites(input.parsed).map((site) => [site.anchorId, site] as const));
-  const start = sites.get(input.adjustment.startAnchorId);
-  const end = sites.get(input.adjustment.endAnchorId);
-  if (start === undefined) throw new Error(`Selection start Anchor ${input.adjustment.startAnchorId} does not exist.`);
-  if (end === undefined) throw new Error(`Selection end Anchor ${input.adjustment.endAnchorId} does not exist.`);
+};
+
+type NamedAnchor = { readonly id: string; readonly edge: "open" | "close" | "moment"; readonly anchorId: string };
 
+/** Normalize only parser-owned prose. Indentation is read from this edit's input, never stored. */
+function normalizedProse(source: string, parsed: ParsedNarrative, original: string): string {
+  const bodyStarts = new Set(parsed.segments.flatMap(segment => [segment.contentRange.start,
+    ...segment.atoms.filter(atom => atom.kind === "role").map(atom => atom.range.end)]));
+  const bodyEnds = new Set(parsed.segments.map(segment => segment.contentRange.end));
+  const indentation = original.split(/\r\n|\r|\n/u).map(line => /^[ \t]*/u.exec(line)![0].length);
+  const lines: Array<{ start: number; end: number; indentEnd: number }> = [];
+  let offset = 0;
+  const parts = source.split(/(\r\n|\r|\n)/u);
+  for (let index = 0; index < parts.length; index += 2) {
+    const text = parts[index]!;
+    lines.push({ start: offset, end: offset + text.length, indentEnd: offset + indentation[index / 2]! });
+    offset += text.length + (parts[index + 1]?.length ?? 0);
+  }
   const edits: Edit[] = [];
-  if (selection.startAnchorId !== start.anchorId) {
-    edits.push({ range: selection.open.range, replacement: "" });
-    edits.push({ range: { start: start.offset, end: start.offset }, replacement: insertion(selection.id, "open", start) });
+  for (const range of parsed.proseRanges) for (const line of lines) {
+    const start = Math.max(range.start, line.indentEnd);
+    const end = Math.min(range.end, line.end);
+    if (start >= end) continue;
+    let text = cleanHorizontalProse(source.slice(start, end));
+    const outside = !parsed.segments.some(segment => range.start >= segment.contentRange.start && range.end <= segment.contentRange.end);
+    if (start === line.indentEnd || bodyStarts.has(start) || outside) text = text.replace(/^[ \t]+/u, "");
+    if (end === line.end || bodyEnds.has(end) || outside) text = text.replace(/[ \t]+$/u, "");
+    edits.push({ range: { start, end }, replacement: text });
+  }
+  return applyEdits(source, edits);
+}
+
+/** One canonical boundary spelling, independent of the order of previous gestures. */
+function rewrite(input: AdjustmentInput, markers: readonly NamedAnchor[]): string {
+  const ranges = [
+    ...input.parsed.moments.map((item) => item.range),
+    ...input.parsed.selections.flatMap((item) => [item.open.range, item.close.range]),
+  ].map((range) => ({ start: range.start - input.parsed.sourceRange.start, end: range.end - input.parsed.sourceRange.start }))
+    .sort((a, b) => a.start - b.start);
+  const edits: Edit[] = ranges.map(range => ({ range, replacement: "" }));
+  for (const segment of input.parsed.segments) {
+    if (segment.selfClosing) edits.push({ range: { start: segment.range.start - input.parsed.sourceRange.start, end: segment.range.end - input.parsed.sourceRange.start }, replacement: `<${segment.id}></${segment.id}>` });
   }
-  if (selection.endAnchorId !== end.anchorId) {
-    edits.push({ range: selection.close.range, replacement: "" });
-    edits.push({ range: { start: end.offset, end: end.offset }, replacement: insertion(selection.id, "close", end) });
+  const unmarked = applyEdits(input.source, edits);
+  const base = normalizedProse(unmarked, parseScript(input.sourceName, unmarked), input.source);
+  const parsed = parseScript(input.sourceName, base);
+  const sites = new Map(scriptAnchorEditSites(parsed).map((site, order) => [site.anchorId, { ...site, order }]));
+  const groups = new Map<number, Array<NamedAnchor & { affinity: Affinity; order: number }>>();
+  for (const value of markers) {
+    const site = sites.get(value.anchorId);
+    if (!site) throw new Error(`Semantic Anchor ${value.anchorId} does not exist.`);
+    let offset = site.offset;
+    const lineStart = Math.max(base.lastIndexOf("\n", offset - 1), base.lastIndexOf("\r", offset - 1)) + 1;
+    const indentEnd = lineStart + /^[ \t]*/u.exec(base.slice(lineStart))![0].length;
+    if (offset < indentEnd) offset = indentEnd;
+    // Reuse horizontal separators without moving a word marker ahead of line indentation.
+    let gapStart = offset;
+    while (gapStart > 0 && /[ \t]/u.test(base[gapStart - 1]!)) gapStart -= 1;
+    if (gapStart > 0 && !/[\r\n]/u.test(base[gapStart - 1]!)) offset = gapStart;
+    const group = groups.get(offset) ?? [];
+    group.push({ ...value, affinity: site.affinity, order: site.order });
+    groups.set(offset, group);
   }
-  if (edits.length === 0) return input.source;
-  const next = applyEdits(input.source, edits);
+  const insertions: Edit[] = [...groups].map(([offset, group]) => {
+    group.sort((a, b) => a.order - b.order
+      || (a.edge === "open" ? 0 : a.edge === "moment" ? 1 : 2) - (b.edge === "open" ? 0 : b.edge === "moment" ? 1 : 2)
+      || a.id.localeCompare(b.id));
+    let replacement = group.map((item) => item.edge === "moment"
+      ? `${item.affinity === "left" ? "~" : ""}@${item.id}!`
+      : marker(item.id, item.edge, item.affinity)).join("");
+    let end = offset;
+    while (end < base.length && /[ \t]/u.test(base[end]!)) end += 1;
+    if (end > offset) replacement += " ";
+    // Only undelimited names followed by an ASCII name character need a separator.
+    if (/[a-z0-9_-]$/u.test(replacement) && /[A-Za-z0-9_-]/u.test(base[offset] ?? "")) replacement += " ";
+    return { range: { start: offset, end }, replacement };
+  });
+  const next = applyEdits(base, insertions);
   const reparsed = parseScript(input.sourceName, next);
-  const rewritten = reparsed.selections.find((candidate) => candidate.id === selection.id);
-  if (rewritten?.startAnchorId !== start.anchorId || rewritten.endAnchorId !== end.anchorId) {
-    throw new Error(`Script refused to move Selection ${selection.id} to the requested Anchors.`);
+  const actual = namedAnchors(reparsed);
+  if (canonicalStringify(actual) !== canonicalStringify(markers)) {
+    throw new Error("Script marker adjustment did not preserve the requested semantic bindings.");
   }
-  const before = narrativeValue(input.parsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };
-  const after = narrativeValue(reparsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };
-  if (before.selections.length !== after.selections.length
-    || before.selections.some((item) => !after.selections.some((candidate) => candidate.id === item.id))) {
-    throw new Error("Script Selection adjustment changed authored identities.");
+  // Compare public content, not source offsets or marker-induced parser atom boundaries.
+  const content = (value: ParsedNarrative) => ({
+    ...narrativeValue(value, "comparison") as Record<string, unknown>, selections: [], moments: [],
+    caption: captionDocument(value, "caption", "comparison"),
+  });
+  if (canonicalStringify(content(input.parsed)) !== canonicalStringify(content(reparsed))) {
+    throw new Error("Script marker adjustment changed authored content.");
   }
   return next;
 }
 
-/** Relocate one Moment to an exact semantic Anchor without changing its identity. */
-export function adjustScriptMoment(input: {
-  readonly sourceName: string;
-  readonly source: string;
-  readonly parsed: ParsedNarrative;
-  readonly adjustment: ScriptMomentAdjustment;
-}): string {
-  const moment = input.parsed.moments.find((candidate) => candidate.id === input.adjustment.id);
-  if (moment === undefined) throw new Error(`Script Moment ${input.adjustment.id} does not exist.`);
-  const site = scriptAnchorEditSites(input.parsed).find((candidate) => candidate.anchorId === input.adjustment.anchorId);
-  if (site === undefined) throw new Error(`Moment Anchor ${input.adjustment.anchorId} does not exist.`);
-  if (moment.anchorId === site.anchorId) return input.source;
-  const next = applyEdits(input.source, [
-    { range: moment.range, replacement: "" },
-    { range: { start: site.offset, end: site.offset }, replacement: momentInsertion(moment.id, site) },
-  ]);
-  const reparsed = parseScript(input.sourceName, next);
-  const rewritten = reparsed.moments.find((candidate) => candidate.id === moment.id);
-  if (rewritten?.anchorId !== site.anchorId) {
-    throw new Error(`Script refused to move Moment ${moment.id} to the requested Anchor.`);
-  }
-  if (reparsed.moments.length !== input.parsed.moments.length
-    || input.parsed.moments.some((item) => !reparsed.moments.some((candidate) => candidate.id === item.id))) {
-    throw new Error("Script Moment adjustment changed authored identities.");
-  }
-  return next;
+function namedAnchors(parsed: ParsedNarrative): NamedAnchor[] {
+  return [
+    ...parsed.selections.flatMap((item): NamedAnchor[] => [
+      { id: item.id, edge: "open", anchorId: item.startAnchorId },
+      { id: item.id, edge: "close", anchorId: item.endAnchorId },
+    ]),
+    ...parsed.moments.map((item): NamedAnchor => ({ id: item.id, edge: "moment", anchorId: item.anchorId })),
+  ];
+}
+
+/** Rewrite a Selection's two endpoints together; Script owns order, not projected time. */
+export function adjustScriptSelection(input: AdjustmentInput & { readonly adjustment: ScriptSelectionAdjustment }): string {
+  const { adjustment, parsed } = input;
+  const selection = parsed.selections.find((item) => item.id === adjustment.id);
+  if (!selection) throw new Error(`Script Selection ${adjustment.id} does not exist.`);
+  const order = parsed.semanticIndex.anchors.map((anchor) => anchor.id);
+  const start = order.indexOf(adjustment.startAnchorId);
+  const end = order.indexOf(adjustment.endAnchorId);
+  if (start < 0 || end < start) throw new Error("Selection endpoints must follow Script anchor order.");
+  return rewrite(input, namedAnchors(parsed).map((item) => item.id !== adjustment.id ? item : {
+    ...item, anchorId: item.edge === "open" ? adjustment.startAnchorId : adjustment.endAnchorId,
+  }));
+}
+
+/** Relocate a Moment by identity, independently of coincident projected Frames. */
+export function adjustScriptMoment(input: AdjustmentInput & { readonly adjustment: ScriptMomentAdjustment }): string {
+  const moment = input.parsed.moments.find((item) => item.id === input.adjustment.id);
+  if (!moment) throw new Error(`Script Moment ${input.adjustment.id} does not exist.`);
+  return rewrite(input, namedAnchors(input.parsed).map((item) => item.id !== input.adjustment.id ? item : {
+    ...item, anchorId: input.adjustment.anchorId,
+  }));
 }

package/packages/script/src/lexical.ts

@@ -50,17 +50,51 @@ export function lexicalCount(value: string): number {
   return lexicalUnits(value).length;
 }
 
+/** Source positions for markers; unlike timing units, these include attached punctuation. */
+export function lexicalEditRanges(value: string): readonly { start: number; end: number }[] {
+  const units = lexicalUnits(value);
+  return units.map((unit, index) => {
+    const previousEnd = index === 0 ? 0 : units[index - 1]!.index + units[index - 1]!.text.length;
+    const nextStart = units[index + 1]?.index ?? value.length;
+    const leading = value.slice(previousEnd, unit.index);
+    let start = unit.index;
+    for (const [position, character] of [...leading.matchAll(/./gu)].map((match) => [match.index, match[0]] as const)) {
+      if (isOpeningPunctuation(character, leading, position, index > 0)) { start = previousEnd + position; break; }
+    }
+    let end = unit.index + unit.text.length;
+    const trailing = value.slice(end, nextStart);
+    for (const match of trailing.matchAll(/./gu)) {
+      if (/\s/u.test(match[0]) || isOpeningPunctuation(match[0], trailing, match.index, true)) break;
+      end += match[0].length;
+    }
+    return { start, end };
+  });
+}
+
 /** Canonical prose spacing; punctuation remains display/speech information, never a timing token. */
-export function cleanProjection(value: string): string {
+function attachProseSpacing(value: string): string {
   return value
-    .replace(/\s+/gu, " ")
-    .replace(/\s+([,.;:!?%…，。！？；：、％‰）】》」』〕〉}\]])/gu, "$1")
-    .replace(/([([{（【《「『〔〈“‘])\s+/gu, "$1")
+    .replace(/ +([,.;:!?%…，。！？；：、％‰）】》」』〕〉}\]])/gu, "$1")
+    .replace(/([([{（【《「『〔〈“‘]) +/gu, "$1")
     // Do not erase a cross-script space: `here 你好` must remain two semantic regions.
     // Only collapse explicit spaces inside one CJK run; the lexical tokenizer already keeps
     // adjacent Latin and CJK runs separate when no space was authored.
-    .replace(/([\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}])\s+(?=[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}])/gu, "$1")
-    .trim();
+    .replace(/([\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]) +(?=[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}])/gu, "$1");
+}
+
+export function cleanProjection(value: string): string {
+  return attachProseSpacing(value.replace(/\s+/gu, " ")).trim();
+}
+
+/** Source formatting keeps line breaks and lexical boundaries, including spaced decimal-like prose. */
+export function cleanHorizontalProse(value: string): string {
+  const collapsed = value.replace(/[ \t]+/gu, " ");
+  const attached = attachProseSpacing(collapsed);
+  const words = (text: string) => lexicalUnits(text).map(unit => unit.text);
+  // A separator in `3 .14` cannot be erased into the different token `3.14`.
+  const before = words(collapsed);
+  const after = words(attached);
+  return before.length === after.length && before.every((word, index) => word === after[index]) ? attached : collapsed;
 }
 
 /** Structural markers split atoms but must not invent prose whitespace when those atoms rejoin. */

package/packages/script/src/parser.ts

@@ -5,6 +5,7 @@ import {
   displayWordSurfaces,
   joinProjection,
   lexicalUnits,
+  lexicalEditRanges,
   splitLeadingClosingPunctuation,
 } from "./lexical.js";
 import type {
@@ -141,6 +142,7 @@ export function parseScript(
 
   const segments: ParsedSegment[] = [];
   const tokens: ParsedToken[] = [];
+  const proseRanges: Array<{ start: number; end: number }> = [];
   const captionRegions: ParsedCaptionRegion[] = [];
   const selections = new Map<string, RawSelection>();
   const moments = new Map<string, RawMoment>();
@@ -237,12 +239,13 @@ export function parseScript(
     raw: string,
     absoluteStart: number,
     dual = false,
-  ): Array<{ readonly value: string; readonly start: number; readonly end: number }> => {
-    const pieces: Array<{ value: string; start: number; end: number }> = [];
+  ): Array<{ readonly value: string; readonly start: number; readonly end: number; readonly positions: readonly number[] }> => {
+    const pieces: Array<{ value: string; start: number; end: number; positions: readonly number[] }> = [];
     let buffer = "";
     let bufferStart = 0;
+    const positions = [absoluteStart];
     const flush = (end: number): void => {
-      if (buffer) pieces.push({ value: buffer, start: absoluteStart + bufferStart, end: absoluteStart + end });
+      if (buffer) pieces.push({ value: buffer, start: absoluteStart + bufferStart, end: absoluteStart + end, positions });
       buffer = "";
       bufferStart = end;
     };
@@ -255,10 +258,12 @@ export function parseScript(
           ?? fail("SCRIPT_ESCAPE", `Unknown Script escape "${raw.slice(index, index + 2)}".`, absoluteStart + index);
         buffer += escape.value;
         index += escape.length;
+        positions.push(absoluteStart + index);
         continue;
       }
       buffer += raw[index];
       index += 1;
+      positions.push(absoluteStart + index);
     }
     flush(raw.length);
     return pieces;
@@ -424,6 +429,7 @@ export function parseScript(
     start: number,
     end: number,
     captureCaptionRegion = true,
+    sourcePositions?: readonly number[],
   ): void => {
     if (!current) {
       if (speech.trim() || caption.trim()) {
@@ -433,7 +439,19 @@ export function parseScript(
     }
     current.lexicalRun += speech;
     const tokenStart = tokens.length;
-    for (const match of lexicalUnits(speech)) {
+    const editRanges = lexicalEditRanges(speech);
+    const units = lexicalUnits(speech);
+    // Decoded characters may occupy more than one source character (for example \@).
+    const position = (index: number): number => sourceOffset + (sourcePositions?.[index] ?? start + index);
+    // A punctuation-only piece can follow a display attribute or escaped source piece.
+    const preceding = tokens.at(-1);
+    const closing = splitLeadingClosingPunctuation(speech).previous;
+    if (preceding?.segmentId === current.id && preceding.editRange.end === sourceOffset + start && closing && speech.startsWith(closing)) {
+      tokens[tokens.length - 1] = { ...preceding, editRange: {
+        start: preceding.editRange.start, end: position(closing.length),
+      } };
+    }
+    for (const [unitIndex, match] of units.entries()) {
       const normalized = normalizeWord(match.text);
       if (!normalized) continue;
       const index = tokens.length;
@@ -449,8 +467,12 @@ export function parseScript(
         text: match.text,
         normalized,
         range: {
-          start: sourceOffset + start + match.index,
-          end: sourceOffset + start + match.index + match.text.length,
+          start: position(match.index),
+          end: position(match.index + match.text.length),
+        },
+        editRange: {
+          start: position(editRanges[unitIndex]!.start),
+          end: position(editRanges[unitIndex]!.end),
         },
       });
     }
@@ -486,7 +508,7 @@ export function parseScript(
     let emittedCaption = false;
     const addLiteral = (part: string, start: number): void => {
       for (const piece of literalPieces(part, start, true)) {
-        addText(piece.value, emittedCaption ? "" : caption, piece.start, piece.end, false);
+        addText(piece.value, emittedCaption ? "" : caption, piece.start, piece.end, false, piece.positions);
         emittedCaption = true;
       }
     };
@@ -654,13 +676,18 @@ export function parseScript(
       offset += 1;
     }
     const raw = source.slice(textStart, offset);
-    for (const piece of literalPieces(raw, textStart)) addText(piece.value, piece.value, piece.start, piece.end);
+    if (raw) proseRanges.push({ start: sourceOffset + textStart, end: sourceOffset + offset });
+    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)) {
         fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must immediately follow a display token.", offset);
       }
       markLastCaptionSurface(block.attributes, offset);
+      const token = tokens.at(-1)!;
+      tokens[tokens.length - 1] = { ...token, editRange: {
+        start: token.editRange.start, end: sourceOffset + offset + block.length,
+      } };
       offset += block.length;
       continue;
     }
@@ -815,6 +842,7 @@ export function parseScript(
   return {
 
     sourceRange: { start: sourceOffset, end: sourceOffset + source.length },
+    proseRanges,
     segments,
     tokens,
     turns,

package/packages/script/src/types.ts

@@ -45,6 +45,8 @@ export type ParsedToken = NarrativeToken & {
   readonly index: number;
   readonly segmentTokenIndex: number;
   readonly range: SourceRange;
+  /** Writable word surface, including attached punctuation and display attributes. */
+  readonly editRange: SourceRange;
 };
 export type ParsedTurn = NarrativeTurn & { readonly range: SourceRange };
 
@@ -79,6 +81,8 @@ export type ParsedNarrative = Omit<
 > & {
   /** Exact Script body range, used only for source-preserving Program-boundary edits. */
   readonly sourceRange: SourceRange;
+  /** Ordinary source prose/whitespace; excludes tags, Dual Text, attributes and comments. */
+  readonly proseRanges: readonly SourceRange[];
   readonly segments: readonly ParsedSegment[];
   readonly tokens: readonly ParsedToken[];
   readonly turns: readonly ParsedTurn[];

package/packages/seedance-kits/README.md

@@ -78,7 +78,9 @@ no duration-estimation node on the generation route.
 
 The Recipe carries recurring choices exposed by the selected template. `dialogue` receives the
 Script Segment's `.dialogue` Text, retaining pronunciation and Role turns. Optional `action` supplies
-this passage's attitude, attention, interaction and any motivated cuts admitted by the Kit.
+this passage's attitude, vocal delivery, attention, interaction and any motivated cuts admitted by
+the Kit. In Speaker, `performance` selects the recurring approach to voice and visible expression;
+`gesture` selects body language, while `action` directs the particular thought and response.
 Do not retype the complete spoken text into action or treat each Role turn as a required new Take.
 For B-roll, `story` carries the silent visual events rather than spoken dialogue.
 

package/packages/seedance-kits/kits/speaker-v1.svs

@@ -75,19 +75,19 @@
   }
 
   text-template.speaker-v1.choice.performance.natural-explainer {
-    text: "PERFORMANCE: natural explainer energy with clear eye focus, expressive eyebrows, small nods, and a friendly conversational rhythm.";
+    text: "PERFORMANCE: engaged, friendly conversation with responsive intonation and clear emphasis as the thought develops. Let gaze, expression, and gesture convey the speaker's attitude to what they are saying.";
   }
 
   text-template.speaker-v1.choice.performance.high-energy-ugc {
-    text: "PERFORMANCE: vivid high-energy short-form delivery with expressive face changes on key words.";
+    text: "PERFORMANCE: vivid, energetic short-form delivery with nimble phrasing, animated intonation, and emphatic key ideas. Let the voice and visible reactions develop together as the speaker makes their point.";
   }
 
   text-template.speaker-v1.choice.performance.calm-authority {
-    text: "PERFORMANCE: composed, confident, precise, and trustworthy, with deliberate emphasis.";
+    text: "PERFORMANCE: composed, thoughtful conviction with measured phrasing and purposeful vocal emphasis. Let focused attention and small, deliberate reactions express how the speaker weighs the idea and reaches a judgment.";
   }
 
   text-template.speaker-v1.choice.performance.reactive-playful {
-    text: "PERFORMANCE: playful and reactive, with amused looks, quick smiles, skeptical eyebrows, and lively timing.";
+    text: "PERFORMANCE: playful, responsive delivery with teasing inflection, lively timing, and an audible smile where the thought amuses the speaker. Let curiosity, skepticism, or delight come through in the voice and matching visible reactions as the passage calls for them.";
   }
 
   text-template.speaker-v1.block.gesture {
@@ -131,6 +131,6 @@
     order: 100;
     slot: action;
     optional: true;
-    label: "ACTION DIRECTION:";
+    label: "PERFORMANCE AND ACTION DIRECTION:";
   }
 </sheet>

package/packages/speech-alignment/src/align.ts

@@ -66,6 +66,9 @@ function pairedCost(
 ): number {
   const sourceText = comparisonText(source);
   const evidenceText = comparisonText(evidence);
+  // Identical wording with different token boundaries is a segmentation difference. Its cost
+  // must not grow with the number of letters a recognizer happens to emit for one word.
+  if (sourceText === evidenceText) return source.length === 1 && evidence.length === 1 ? 0 : 0.055;
   const width = Math.max([...sourceText].length, [...evidenceText].length, 1);
   const distance = editDistance([...sourceText], [...evidenceText]) / width;
   const grouping = 0.055 * Math.max(0, source.length + evidence.length - 2);
@@ -74,6 +77,17 @@ function pairedCost(
   return distance * evidenceReliability(evidence) + grouping + 0.06 * unmatchedWordBoundaries;
 }
 
+function exactRunLength(target: string, parts: readonly string[], start: number): number {
+  if (target.length === 0) return 0;
+  let joined = "";
+  for (let index = start; index < parts.length; index += 1) {
+    joined += parts[index];
+    if (joined === target) return index - start + 1;
+    if (!target.startsWith(joined)) return 0;
+  }
+  return 0;
+}
+
 function better(candidate: Cell, current: Cell | undefined): boolean {
   if (!current) return true;
   if (candidate.cost < current.cost - EPSILON) return true;
@@ -155,34 +169,44 @@ export function alignWordGroups(
     }
   };
 
+  const sourceTexts = source.map((token) => normalizeForAlignment(token.text));
+  const evidenceTexts = evidence.map((word) => normalizeForAlignment(word.text));
   for (let sourceIndex = 0; sourceIndex <= source.length; sourceIndex += 1) {
     for (let evidenceIndex = 0; evidenceIndex <= evidence.length; evidenceIndex += 1) {
       if (!rows[sourceIndex]![evidenceIndex]) continue;
+      const pair = (sourceCount: number, evidenceCount: number): void => {
+        const sourceGroup = source.slice(sourceIndex, sourceIndex + sourceCount);
+        const evidenceGroup = evidence.slice(evidenceIndex, evidenceIndex + evidenceCount);
+        const exactOneToOne = sourceCount === 1
+          && evidenceCount === 1
+          && sourceGroup[0]!.normalized === normalizeForAlignment(evidenceGroup[0]!.text);
+        const cost = pairedCost(sourceGroup, evidenceGroup);
+        update(
+          sourceIndex,
+          evidenceIndex,
+          sourceIndex + sourceCount,
+          evidenceIndex + evidenceCount,
+          {
+            sourceSegmentId,
+            sourceTokenIds: sourceGroup.map((token) => token.id),
+            evidenceWordStart: evidenceIndex,
+            evidenceWordEndExclusive: evidenceIndex + evidenceCount,
+            relation: relation(sourceCount, evidenceCount, exactOneToOne),
+            cost,
+          },
+          exactOneToOne ? 1 : 0,
+        );
+      };
       for (let sourceCount = 1; sourceCount <= maxGroupSize && sourceIndex + sourceCount <= source.length; sourceCount += 1) {
         for (let evidenceCount = 1; evidenceCount <= maxGroupSize && evidenceIndex + evidenceCount <= evidence.length; evidenceCount += 1) {
-          const sourceGroup = source.slice(sourceIndex, sourceIndex + sourceCount);
-          const evidenceGroup = evidence.slice(evidenceIndex, evidenceIndex + evidenceCount);
-          const exactOneToOne = sourceCount === 1
-            && evidenceCount === 1
-            && sourceGroup[0]!.normalized === normalizeForAlignment(evidenceGroup[0]!.text);
-          const cost = pairedCost(sourceGroup, evidenceGroup);
-          update(
-            sourceIndex,
-            evidenceIndex,
-            sourceIndex + sourceCount,
-            evidenceIndex + evidenceCount,
-            {
-              sourceSegmentId,
-              sourceTokenIds: sourceGroup.map((token) => token.id),
-              evidenceWordStart: evidenceIndex,
-              evidenceWordEndExclusive: evidenceIndex + evidenceCount,
-              relation: relation(sourceCount, evidenceCount, exactOneToOne),
-              cost,
-            },
-            exactOneToOne ? 1 : 0,
-          );
+          pair(sourceCount, evidenceCount);
         }
       }
+      // Bound fuzzy alternatives, but follow a complete exact split/merge regardless of token count.
+      const evidenceRun = exactRunLength(sourceTexts[sourceIndex] ?? "", evidenceTexts, evidenceIndex);
+      if (evidenceRun > maxGroupSize) pair(1, evidenceRun);
+      const sourceRun = exactRunLength(evidenceTexts[evidenceIndex] ?? "", sourceTexts, sourceIndex);
+      if (sourceRun > maxGroupSize) pair(sourceRun, 1);
       if (sourceIndex < source.length) {
         const token = source[sourceIndex]!;
         update(