@hypit/hypit 0.1.3 → 0.1.5

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/manifest.ts

@@ -32,7 +32,7 @@ export const scriptMarkupSurfaces = [
       text: "The element's own content is the Script body: named Segments holding prose, Role Cues, Dual Text, flat token attributes, and zero-width Selection and Moment markers. It carries no timecode, no media reference and no generation parameter.",
       ports: [
         { name: "", type: narrativeType,
-          summary: "The whole authored Narrative, addressed by the element's own id." },
+          summary: "The complete authored Narrative, including speech structure, semantic anchors and its CaptionDocument, addressed by the element's own id." },
         { name: "segment.<id>", type: narrativeExcerptType,
           summary: "One Segment as a narrow Excerpt, used to associate a generated Take with that Segment." },
         { name: "segment.<id>.dialogue", type: textTypes.text,
@@ -40,7 +40,7 @@ export const scriptMarkupSurfaces = [
         { name: "segment.<id>.speech", type: textTypes.text,
           summary: "One Segment as pronunciation only, with Role Cue labels dropped." },
         { name: "caption", type: captionDocumentType,
-          summary: "The complete Script-owned CaptionDocument: display Words, N:M Alignment Units, Cue breaks and speech correspondence." },
+          summary: "The Narrative's CaptionDocument exported as a narrow view: display Words, N:M Alignment Units, Cue breaks and speech correspondence." },
         { name: "selection.<id>", type: narrativeSelectionType,
           summary: "One named range over the Narrative, reusable wherever a Selection is read." },
         { name: "moment.<id>", type: narrativeMomentType,

package/packages/script/src/narrative.ts

@@ -180,6 +180,7 @@ export function narrativeMomentValue(moment: ParsedNarrative["moments"][number],
 export function narrativeValue(parsed: ParsedNarrative, id: string): CanonicalValue {
   return canonicalize({
     id,
+    caption: captionDocument(parsed, `${id}.caption`, id),
     segments: parsed.segments.map((segment) => ({
       id: segment.id,
       startAnchorId: segment.startAnchorId,

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/surface.ts

@@ -1,6 +1,5 @@
 import { ScriptSyntaxError } from "./error.js";
 import {
-  captionDocumentValue,
   narrativeDialogueTextValue,
   narrativeSegmentExcerptValue,
   narrativeMomentValue,
@@ -73,6 +72,8 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
     input.source.slice(input.contentStart, close.start),
     input.contentStart,
   );
+  const narrative = narrativeValue(parsed, rawId);
+  const caption = (narrative as { readonly caption: import("@hypit/protocol").CanonicalValue }).caption;
   const captionId = `${rawId}.caption`;
   return {
     nextOffset: close.end,
@@ -80,7 +81,7 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
       {
         id: rawId,
         type: narrativeType,
-        value: { kind: "inline", value: narrativeValue(parsed, rawId) },
+        value: { kind: "inline", value: narrative },
         range: { start: input.openingStart, end: close.end },
       },
       ...parsed.segments.map((segment) => ({
@@ -106,7 +107,7 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
       {
         id: captionId,
         type: captionDocumentType,
-        value: { kind: "inline" as const, value: captionDocumentValue(parsed, captionId, rawId) },
+        value: { kind: "inline" as const, value: caption },
         range: { start: input.openingStart, end: close.end },
       },
       ...parsed.selections.map((selection) => ({

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 };
 
@@ -75,10 +77,12 @@ export type ParsedCaptionRegion = {
 
 export type ParsedNarrative = Omit<
   Narrative,
-  "id" | "segments" | "tokens" | "turns" | "selections" | "moments"
+  "id" | "segments" | "tokens" | "turns" | "selections" | "moments" | "caption"
 > & {
   /** 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/script-studio/package.json

@@ -4,10 +4,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
   "type": "module",
-  "exports": { ".": "./src/index.ts" },
-  "hypit": { "activation": "./src/activation.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
   "dependencies": {
     "@hypit/script": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*"
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*"
   }
 }

package/packages/script-studio/src/index.ts

@@ -1,9 +1,11 @@
+import { projectScriptTimeline } from "./projection.js";
 import { adjustScriptMoment, adjustScriptSelection, parseScript, scriptModuleRef } from "@hypit/script";
 import type { StudioScriptCompanion } from "@hypit/studio-adapter";
 
 export const scriptStudioCompanions: readonly StudioScriptCompanion[] = [{
   id: "script",
   match: { module: scriptModuleRef, surface: "script" },
+  project: projectScriptTimeline,
   observe(input) {
     const narrativeId = input.attributes.id ?? "script";
     if (typeof narrativeId !== "string" || narrativeId.length === 0) return undefined;