Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix(script): preserve semantic anchors during marker edits

kashorin1859f4ccfa81
diff --git a/packages/script/README.md b/packages/script/README.md
index bac9d1c5..ea7b6bf7 100644
--- a/packages/script/README.md
+++ b/packages/script/README.md
@@ -135,3 +135,15 @@ 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. Equivalent horizontal marker spacing is normalized on edit; 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.
diff --git a/packages/script/src/edit.ts b/packages/script/src/edit.ts
index 563d0a9d..29b67e54 100644
--- a/packages/script/src/edit.ts
+++ b/packages/script/src/edit.ts
@@ -1,6 +1,7 @@
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 type { Affinity, ParsedNarrative, SemanticAnchor } from "./types.js";
@@ -47,18 +48,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 +65,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 +78,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 +91,120 @@ 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 };
- 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) });
+/** 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 removals: Edit[] = [];
+ for (const range of ranges) {
+ let start = range.start;
+ let end = range.end;
+ while (start > 0 && /[ \t]/u.test(input.source[start - 1]!)) start -= 1;
+ while (end < input.source.length && /[ \t]/u.test(input.source[end]!)) end += 1;
+ const previous = removals.at(-1);
+ if (previous && start <= previous.range.end) {
+ removals[removals.length - 1] = { range: { start: previous.range.start, end }, replacement: "" };
+ } else removals.push({ range: { start, end }, replacement: "" });
}
- 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 edits = removals.map(({ range }): Edit => {
+ const original = input.source.slice(range.start, range.end);
+ // Keep line indentation; elsewhere all horizontal spellings of this gap are one space.
+ const indentation = range.start === 0 || /[\r\n]/u.test(input.source[range.start - 1]!);
+ const gap = indentation ? /^[ \t]*/u.exec(original)![0] : /[ \t]/u.test(original) ? " " : "";
+ return { range, replacement: gap };
+ });
+ 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}>` });
+ }
+ const base = applyEdits(input.source, edits);
+ 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;
+ // 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.");
+ if (selection.startAnchorId === adjustment.startAnchorId && selection.endAnchorId === adjustment.endAnchorId) return input.source;
+ 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.`);
+ if (moment.anchorId === input.adjustment.anchorId) return input.source;
+ return rewrite(input, namedAnchors(input.parsed).map((item) => item.id !== input.adjustment.id ? item : {
+ ...item, anchorId: input.adjustment.anchorId,
+ }));
}
diff --git a/packages/script/src/lexical.ts b/packages/script/src/lexical.ts
index 73642677..82e08eff 100644
--- a/packages/script/src/lexical.ts
+++ b/packages/script/src/lexical.ts
@@ -50,6 +50,27 @@ 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 {
return value
diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.ts
index 3375c36f..95e2fa71 100644
--- a/packages/script/src/parser.ts
+++ b/packages/script/src/parser.ts
@@ -5,6 +5,7 @@ import {
displayWordSurfaces,
joinProjection,
lexicalUnits,
+ lexicalEditRanges,
splitLeadingClosingPunctuation,
} from "./lexical.js";
import type {
@@ -433,7 +434,17 @@ export function parseScript(
}
current.lexicalRun += speech;
const tokenStart = tokens.length;
- for (const match of lexicalUnits(speech)) {
+ const editRanges = lexicalEditRanges(speech);
+ const units = lexicalUnits(speech);
+ // 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: sourceOffset + start + closing.length,
+ } };
+ }
+ for (const [unitIndex, match] of units.entries()) {
const normalized = normalizeWord(match.text);
if (!normalized) continue;
const index = tokens.length;
@@ -452,6 +463,10 @@ export function parseScript(
start: sourceOffset + start + match.index,
end: sourceOffset + start + match.index + match.text.length,
},
+ editRange: {
+ start: sourceOffset + start + editRanges[unitIndex]!.start,
+ end: sourceOffset + start + editRanges[unitIndex]!.end,
+ },
});
}
current.atoms.push({
@@ -661,6 +676,10 @@ export function parseScript(
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;
}
diff --git a/packages/script/src/types.ts b/packages/script/src/types.ts
index cc6c4e66..6c8262a7 100644
--- a/packages/script/src/types.ts
+++ b/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 };
diff --git a/packages/script/test/edit.test.ts b/packages/script/test/edit.test.ts
new file mode 100644
index 00000000..3ea925a1
--- /dev/null
+++ b/packages/script/test/edit.test.ts
@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { adjustScriptMoment, adjustScriptSelection, captionDocument, narrativeValue, parseScript } from "@hypit/script";
+
+const fixtures = [
+ '<one><HOST>“Hello,” world{emphasis}! @beat!</one>',
+ '<one><HOST>你好,世界!@beat!</one>',
+ '<one><HOST>用<Hypit|Hai Pit>做视频 || 很好。@beat!</one>',
+ '<one/>\r\n<two><HOST>Hello. @beat!</two>',
+ '<one> <HOST>first @beat! second.\n <GUEST>Third.</one><two></two>',
+];
+
+for (const source of fixtures) test(`Moment round trips through structural and lexical anchors: ${source}`, () => {
+ const original = parseScript("edit", source);
+ const move = (text: string, anchorId: string) => adjustScriptMoment({
+ sourceName: "edit", source: text, parsed: parseScript("edit", text), adjustment: { id: "beat", anchorId },
+ });
+ for (const anchor of original.semanticIndex.anchors) {
+ const first = move(source, anchor.id);
+ const back = move(first, original.moments[0]!.anchorId);
+ assert.deepEqual(narrativeValue(parseScript("edit", back), "story"), narrativeValue(original, "story"));
+ assert.deepEqual(captionDocument(parseScript("edit", back), "caption", "story"), captionDocument(original, "caption", "story"));
+ // A second visit uses exactly the same spelling; spacing cannot accumulate.
+ assert.equal(move(back, anchor.id), first);
+ }
+});
+
+test("Selection endpoints sharing a source position are written together in semantic order", () => {
+ const source = '<one><HOST>@range hello @/range world.</one><empty/>';
+ const original = parseScript("edit", source);
+ const anchors = original.semanticIndex.anchors;
+ for (let start = 0; start < anchors.length; start++) for (let end = start; end < anchors.length; end++) {
+ const adjustment = { id: "range", startAnchorId: anchors[start]!.id, endAnchorId: anchors[end]!.id };
+ const next = adjustScriptSelection({ sourceName: "edit", source, parsed: original, adjustment });
+ const parsed = parseScript("edit", next);
+ assert.equal(parsed.selections[0]!.startAnchorId, adjustment.startAnchorId);
+ assert.equal(parsed.selections[0]!.endAnchorId, adjustment.endAnchorId);
+ }
+});
+
+test("Moving one relationship preserves crossing selections, cues and other moments", () => {
+ const source = '<one><HOST>@a One @b two @/a || three @/b. @beat! ~@other!</one>';
+ const parsed = parseScript("edit", source);
+ const next = adjustScriptMoment({ sourceName: "edit", source, parsed,
+ adjustment: { id: "beat", anchorId: parsed.tokens[0]!.endAnchorId } });
+ const result = parseScript("edit", next);
+ assert.deepEqual(result.selections.map(({ id, startAnchorId, endAnchorId }) => ({ id, startAnchorId, endAnchorId })),
+ parsed.selections.map(({ id, startAnchorId, endAnchorId }) => ({ id, startAnchorId, endAnchorId })));
+ assert.equal(result.moments.find((item) => item.id === "other")!.anchorId,
+ parsed.moments.find((item) => item.id === "other")!.anchorId);
+});
diff --git a/packages/script/test/script.test.ts b/packages/script/test/script.test.ts
index fab497ca..0a4c1a74 100644
--- a/packages/script/test/script.test.ts
+++ b/packages/script/test/script.test.ts
@@ -58,8 +58,8 @@ test("Program boundaries are distinct writable semantic Anchors", () => {
});
const selection = parseScript("program-boundaries.svml", withSelection).selections[0]!;
assert.deepEqual([selection.startAnchorId, selection.endAnchorId], ["program:start", "program:end"]);
- assert.match(withSelection, /^~@focus /u);
- assert.match(withSelection, / @\/focus~$/u);
+ assert.match(withSelection, /^~@focus(?=[ <])/u);
+ assert.match(withSelection, /@\/focus~$/u);
const withMoment = adjustScriptMoment({
sourceName: "program-boundaries.svml",
@@ -71,7 +71,7 @@ test("Program boundaries are distinct writable semantic Anchors", () => {
adjustment: { id: "cue", anchorId: "program:end" },
});
assert.equal(parseScript("program-boundaries.svml", withMoment).moments[0]!.anchorId, "program:end");
- assert.match(withMoment, / @cue!$/u);
+ assert.match(withMoment, /@cue!$/u);
});
test("Moment source edits relocate one marker to an exact semantic Anchor", () => {