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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(script): support shared display and speech alignment units
kashorin395775536ddd
diff --git a/docs/quickstart/script.md b/docs/quickstart/script.mdindex 4244546f..d9d0dbc6 100644--- a/docs/quickstart/script.md+++ b/docs/quickstart/script.md@@ -104,10 +104,26 @@ An empty left side is legal:```This means "um" is spoken but never displayed as a caption. The two sides can have different word-counts — this is an N:M Alignment Unit, not a 1:1 substitution. A Selection cannot split that unit.+counts — this is an N:M Alignment Unit, not a 1:1 substitution. Its displayed unit stays complete+even when a semantic marker locates a word within the spoken side.-Markers belong to the spoken side of Dual Text. The display side is literal; an unescaped `@` there-is rejected. Escape it as `\@` when the at-sign should be shown.+When both sides are written, markers belong to the spoken side of Dual Text. The display side is+literal; an unescaped `@` there is rejected. Escape it as `\@` when the at-sign should be shown.++When both wordings are identical, omit the speech after the pipe:++```svml+<explanation><HOST>把<动效|><组件化|>。|| 以后就能<直接复用|>。</explanation>+```++`<组件化|>` means `<组件化|组件化>`: one complete Caption unit, with the same three individually+timed spoken characters. Caption Styles can highlight the group together. Ordinary text remains+valid without grouping, and `||` still chooses the Cue handoff. This works for phrases and names+in other languages too, such as `<Git Hub|>`.++Here the left side also supplies speech, so markers can be written and moved there:+`<组@beat!件化|>`. Markers and display attributes never become spoken text. An explicit spoken side+still owns its own markers. Both sides empty is invalid.`||` is the **Caption Cue Break** syntax. It records a boundary between complete Alignment Units;it cannot appear inside Dual Text or split an N:M unit. Cue timing is still obtained later bydiff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.mdindex f700b349..fda47df6 100644--- a/docs/zh/quickstart/script.md+++ b/docs/zh/quickstart/script.md@@ -97,11 +97,25 @@ dialogue `Text` 包含 Role Cue 前缀,speech `Text` 和 CaptionDocument 会```这意味着 "um" 会被说出但永远不会显示为字幕。两侧可以有不同的单词数量——这是一种 N:M-对齐单元,而非 1:1 替换;Selection 不能切开这个单元。+对齐单元,而非 1:1 替换;即使语义标记定位到口播内部的一个词,显示单元仍然保持完整。-标记只能出现在 Dual Text 的 spoken side。display side 是字面文本,未转义的 `@` 会报错;+两侧都明确书写时,标记只能出现在 Dual Text 的 spoken side。display side 是字面文本,未转义的 `@` 会报错;如果确实要显示 at-sign,请写成 `\@`。+两边文案相同时,可以省略竖线后面的口播:++```svml+<explanation><HOST>把<动效|><组件化|>。|| 以后就能<直接复用|>。</explanation>+```++`<组件化|>` 等价于 `<组件化|组件化>`:字幕是一个完整单元,口播中的三个字仍各自保留时间。+字幕样式可以让这组文字一起高亮;普通文本仍然可以直接书写,不必逐词包裹。`||` 继续决定+Cue 的切换。这同样适用于其他语言的短语或名字,例如 `<Git Hub|>`。++这时左侧同时提供口播,因此标记也可以放在左侧,Studio 会回写到实际文字上:+`<组@beat!件化|>`。标记和显示属性不会成为口播内容。若明确写了右侧口播,标记仍然属于+右侧。两侧都没有口播文字时无效。+`||` 是 **Caption Cue Break** 语法,只能位于完整对齐单元之间,不能写进 Dual Text 或切开N:M 单元。字幕稍后才把 CaptionDocument 与 Timeline 汇合得到帧时间。diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.mdindex 57330b64..58feb8c0 100644--- a/packages/caption-fine/README.md+++ b/packages/caption-fine/README.md@@ -87,6 +87,13 @@ individual Han characters as Display Words; punctuation stays with its display wthose units for timing and active Paint, while authored Cues remain complete reading phrases.Dual Text retains its complete alignment unit even when it displays or speaks several words.+`<组件化|>` authors the same unit as `<组件化|组件化>` without repeating the speech. Fine's `step`+karaoke, active underline and active box treat that unit together using its first-to-last speech+interval. Ordinary Chinese characters around it retain their own activation times. This is an+explicit authored group, not a renderer-selected segmentation, and does not introduce a new Cue.+The underlying character anchors remain available to other Timeline consumers. `wipe` and+`typewriter` still animate inside the complete unit over its interval when deliberately selected.+`word-gap` applies between Latin words and at Chinese/Latin boundaries. Adjacent Han characters andfull-width punctuation carry no extra word gap. `letter-spacing` controls glyph tracking. Exactfont fallbacks supply the required glyphs; the layout does not select a font by language.diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.tsindex 75b3614b..640dce2b 100644--- a/packages/caption-fine/test/caption-fine.test.ts+++ b/packages/caption-fine/test/caption-fine.test.ts@@ -328,6 +328,31 @@ function numericStyleAt(element: import("@hypit/composition").VisualElement, fra: value(left) + (value(right) - value(left)) * (frame - left.atFrame) / (right.atFrame - left.atFrame);}+for (const mode of ["current", "trail"] as const) test(`shared-text groups use existing ${mode} whole-unit caption effects`, () => {+ const make = (script: string) => {+ const { document, program, projection } = fixture(script);+ const style = fineCaptionStyle("plain", { ...recipe, properties: { ...recipe.properties,+ karaoke: mode, "karaoke-transition": "step", "active-box": mode, "active-underline": mode,+ } }, [font]);+ const styled = { ...program, styles: [style] };+ return renderFineCaption(scheduleFineCaption(projection, styled, document), styled, document,+ sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));+ };+ const track = make('<line><动效|><组件化|> || <直接|><复用|></line>');+ assert.deepEqual(track, make('<line><动效|动效><组件化|组件化> || <直接|直接><复用|复用></line>'));+ const present = track.presents[0]!;+ for (const [index, [start, end]] of [[10, 20], [20, 30]].entries()) {+ for (const suffix of ["active", "underline", "box"]) {+ const element = present.elements.find(item => item.id === `atom-${index + 1}-${suffix}`)!;+ assert.ok(element);+ for (let frame = present.span.startFrame; frame < present.span.endFrameExclusive; frame++) {+ assert.equal(numericStyleAt(element, frame - present.span.startFrame, "opacity"),+ Number(frame >= start! && (mode === "trail" || frame < end!)));+ }+ }+ }+});+for (const mode of ["current", "trail"] as const) {test(`Chinese ${mode} karaoke, underline and boxes follow unequal character times and pauses`, () => {const { track, windows } = unevenChineseCaption({diff --git a/packages/caption/test/chinese-pipeline.test.ts b/packages/caption/test/chinese-pipeline.test.tsindex fc0b1a0d..d08fa371 100644--- a/packages/caption/test/chinese-pipeline.test.ts+++ b/packages/caption/test/chinese-pipeline.test.ts@@ -9,8 +9,8 @@ import { selectionFrameSpan } from "@hypit/timeline";import { temporalizeCaptionDocument } from "../src/index.js";import { fixtureResource } from "../../../test/fixture-resource.js";-test("Chinese Script, WhisperX response, semantic assembly and captions preserve words, cue breaks and timing", () => {- const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@brand ElevenLabs @/brand做视频,|| 真方便。</opening>+for (const grouped of [false, true]) test(`Chinese Script through WhisperX and Timeline preserves caption timing (shared groups: ${grouped})`, () => {+ const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@brand ElevenLabs @/brand做${grouped ? '<视频|>' : '视频'},|| 真方便。</opening><answer><GUEST>今年<2026|二零二六>年,這個很好。</answer>`);const narrative = narrativeValue(parsed, "story") as unknown as Narrative;const document = captionDocument(parsed, "story.caption", "story");@@ -54,6 +54,9 @@ test("Chinese Script, WhisperX response, semantic assembly and captions preserveassert.deepEqual(windowsFor("用"), [first[0]]);assert.deepEqual(windowsFor("ElevenLabs"), [[first[1]![0], first[10]![1]]]);assert.deepEqual(windowsFor("做"), [first[11]]);+ if (grouped) assert.deepEqual(windowsFor("视频,"), [[first[12]![0], first[13]![1]]]);+ assert.deepEqual(semantic.items[0]!.take.tokens.filter(token => ["做", "视", "频"].includes(token.text))+ .map(token => [token.startFrame, token.endFrameExclusive]), first.slice(11, 14));const span = selectionFrameSpan(semantic, { ...narrative.selections[0]!, narrativeId: narrative.id });assert.deepEqual(span, { startFrame: first[1]![0], endFrameExclusive: first[10]![1] });const second = evidenceWindows[1]!;diff --git a/packages/script/README.md b/packages/script/README.mdindex 764b6824..c0e52cdb 100644--- a/packages/script/README.md+++ b/packages/script/README.md@@ -64,7 +64,7 @@ CaptionDocument contracts.- **Role Cue**: a speaker turn, written as a bare tag such as `<ALICE>` inside a Segment. The nextRole Cue or the Segment close ends that turn.- **Dual Text**: one authored speech span with separate display and spoken projections, written- `<display text | spoken text>`.+ `<display text | spoken text>`. In `<display text|>`, omitted speech inherits the displayed prose.- **Selection marker**: a named semantic range, written `@name ... @/name`.- **Moment marker**: a named semantic point, written `@name!`.- **CaptionDocument**: the Script-owned caption truth; it contains **Display Words**,@@ -73,11 +73,23 @@ CaptionDocument contracts.`really{emphasis,importance=2,tone=warm}`. Values may be strings, finite numbers or booleans. Itbecomes `CaptionDisplayWord.attributes`; it is not a Selection and does not carry timing.-Within Dual Text, an unescaped `@` is legal only on the spoken side. The display side is literal; write-`\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech+Within Dual Text, an unescaped `@` belongs to the source of spoken text: the right side when supplied,+or the shared left side in `<display text|>`. Write `\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speechtokens and omits them from Caption. `||` is an authored Caption Cue Break and must occur betweencomplete Alignment Units.+`<组件化|>` is shorthand for `<组件化|组件化>`, using the same exported Caption Alignment Unit.+It groups the displayed expression without merging its individual speech Tokens or time anchors.+For example, `把<动效|><组件化|>。|| 之后<直接复用|>。` authors groups inside two Cues.+Use groups where the expression should be treated together; ordinary prose needs no extra markup.+Caption Styles choose whether to highlight, reveal or keep the text steady.++In a shared side, markers and display attributes do not enter either text projection. Its speech+Tokens retain offsets into the actually written left-hand text, so Studio can move an anchor inside+`<组@beat!件化|>` without expanding the shorthand. Attributes still annotate the preceding display+word, not the whole group. Whitespace-only speech is omitted; a group with no spoken text on either+side is invalid. This adds no new public value type or protocol version.+## Segments, turns and Cues are different boundariesA Segment names a structural production passage. It can contain several Role turns and be performeddiff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.tsindex 9d2dd50b..ec8a618c 100644--- a/packages/script/src/manifest.ts+++ b/packages/script/src/manifest.ts@@ -64,7 +64,8 @@ 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 the caption projection and the right side reaches dialogue and speech. The spoken side must not be empty; the displayed side may be, which speaks a word that is never displayed.",+ "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.",+ "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.","Selection and Moment markers are zero-width, share one name namespace, and may not split a speech token:",[diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.tsindex 839ef74c..d7c2ab08 100644--- a/packages/script/src/parser.ts+++ b/packages/script/src/parser.ts@@ -499,16 +499,22 @@ export function parseScript(const consumeSpeechSide = (raw: string,absoluteStart: number,- caption: string,+ caption: string | undefined,marks: ParsedCaptionRegion["marks"] = [],): void => {const startToken = tokens.length;+ // An omitted speech side shares the written display source. Keep its original offsets:+ // marker edits target these words, not a synthetic copy beyond the pipe.+ const shared = caption === undefined;+ const spokenParts: string[] = [];+ const sharedMarks: Array<ParsedCaptionRegion["marks"][number]> = [];let partStart = 0;let index = 0;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, piece.positions);+ spokenParts.push(piece.value);+ addText(piece.value, shared ? piece.value : emittedCaption ? "" : caption!, piece.start, piece.end, false, piece.positions);emittedCaption = true;}};@@ -520,6 +526,29 @@ export function parseScript(if (raw.startsWith("||", index)) {fail("SCRIPT_CAPTION_BREAK_DUAL", "Caption Cue break cannot occur inside Dual Text; split the Dual Text into separate units.", absoluteStart + index);}+ if (shared && raw[index] === "{") {+ const before = raw.slice(partStart, index);+ if (!before || /\s$/u.test(before)) {+ 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);+ const displayIndex = displayWordSurfaces(spokenParts.join("")).length - 1;+ if (displayIndex < 0 || tokens.length === startToken) {+ fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must follow a visible display token.", absoluteStart + index);+ }+ if (sharedMarks.some(mark => mark.displayIndex === displayIndex)) {+ fail("SCRIPT_ATTRIBUTE_OVERLAP", "A display token cannot receive two separate attribute blocks.", absoluteStart + index);+ }+ sharedMarks.push({ displayIndex, attributes: block.attributes });+ const token = tokens.at(-1)!;+ tokens[tokens.length - 1] = { ...token, editRange: {+ start: token.editRange.start, end: sourceOffset + absoluteStart + index + block.length,+ } };+ index += block.length;+ partStart = index;+ continue;+ }const marker = parseMarker(raw, index);if (!marker) {if (raw[index] === "@") fail("SCRIPT_MARKER", "Unescaped @ must begin a valid marker.", absoluteStart + index);@@ -532,15 +561,19 @@ export function parseScript(partStart = index;}addLiteral(raw.slice(partStart), absoluteStart + partStart);+ const display = caption ?? spokenParts.join("");+ 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(- caption,+ display,current!.id,startToken,tokens.length,- cleanProjection(caption) ? "alias" : "hidden",+ cleanProjection(display) ? "alias" : "hidden",{ start: sourceOffset + absoluteStart, end: sourceOffset + absoluteStart + raw.length },- marks,+ shared ? sharedMarks : marks,);}};@@ -636,10 +669,16 @@ export function parseScript(const pipe = findUnescaped(inside, "|");if (pipe >= 0) {finishLexicalRun();+ 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;- const speech = inside.slice(pipe + 1);if (!speech.replace(/~?@\/?[A-Za-z_][A-Za-z0-9_.-]*!?~?/gu, "").trim()) {fail("SCRIPT_DUAL_EMPTY", "Dual Text speech side must not be empty.", offset);}diff --git a/packages/script/test/edit.test.ts b/packages/script/test/edit.test.tsindex 9be4ac54..efe600ef 100644--- a/packages/script/test/edit.test.ts+++ b/packages/script/test/edit.test.ts@@ -16,6 +16,8 @@ const fixtures = ['<one>Find \\@hypit now. @beat!</one>','<one>Use \\{braces\\} here. @beat!</one>','<one><Hypit|Hai \\@ Pit> works. @beat!</one>',+ '<one><HOST>把<动效|><组件化|>。@beat!</one>',+ '<one><HOST><Git Hub|> <图{emphasis}像|> <\\@Hypit|>。@beat!</one>',];test("horizontal formatting preserves lexical distinctions and line breaks", () => {@@ -88,6 +90,7 @@ for (const source of ['<one>A ~@s B . @/s</one>','<one>@s A @/s B .</one>','<one>@s A @/s~ B .</one>',+ '<one><HOST>@s <动效|><组件化|> @/s</one>',]) test(`Selection affinity survives every structural round trip: ${source}`, () => {const original = parseScript("edit", source);const selection = original.selections[0]!;diff --git a/packages/script/test/narrative-views.test.ts b/packages/script/test/narrative-views.test.tsindex dbd141f8..30d69a16 100644--- a/packages/script/test/narrative-views.test.ts+++ b/packages/script/test/narrative-views.test.ts@@ -1,6 +1,7 @@import assert from "node:assert/strict";import test from "node:test";-import { decodeScriptSurface, narrativeValue, parseScript } from "@hypit/script";+import { captionDocument, decodeScriptSurface, formatScript, narrativeDialogueTextValue,+ narrativeSpeechTextValue, narrativeValue, parseScript } from "@hypit/script";import { assertNarrativeIdentity, narrativeAnchorTokenBoundary, narrativeSelectionTokenRange,narrativeTokensForSelection, narrativeTypes } from "@hypit/narrative";import type { Narrative, NarrativeSelectionRef } from "@hypit/narrative";@@ -8,6 +9,8 @@ import { captionUnitsForSelection, captionTypes, decodeHiddenCaptionStyleSurfaceimport type { CaptionProgram } from "@hypit/caption";import { parseStructuredElement } from "@hypit/markup";import type { SurfaceResolvedReference } from "@hypit/markup";+import { countSpeechEstimateUnits } from "@hypit/estimate";+import type { Text } from "@hypit/text";const body = `<intro><HOST>Try @brand <hypit|Hai-Pit> @/brand today. ||</intro><gap/>@@ -17,6 +20,42 @@ function authored() {return narrativeValue(parseScript("views.svml", body), "story") as unknown as Narrative;}+test("omitted speech shares display prose while retaining ordinary Narrative and caption exports", () => {+ for (const [short, expanded] of [+ ['把<动效|><组件化|>。|| <直接复用|>。', '把<动效|动效><组件化|组件化>。|| <直接复用|直接复用>。'],+ ['<Git Hub|> 和 <API|A P I>。<|只说不显示>', '<Git Hub|Git Hub> 和 <API|A P I>。<|只说不显示>'],+ ['<图{emphasis}像|> 与 <\\@Hypit|>。', '<图{emphasis}像|图像> 与 <\\@Hypit|\\@Hypit>。'],+ ]) {+ const body = `<intro><HOST>${short}</intro>`;+ const parsed = parseScript("short.svml", body);+ const full = parseScript("full.svml", `<intro><HOST>${expanded}</intro>`);+ assert.deepEqual(narrativeValue(parsed, "story"), narrativeValue(full, "story"));+ assert.deepEqual(narrativeSpeechTextValue(parsed.segments[0]!), narrativeSpeechTextValue(full.segments[0]!));+ assert.deepEqual(narrativeDialogueTextValue(parsed.segments[0]!), narrativeDialogueTextValue(full.segments[0]!));+ const speech = narrativeSpeechTextValue(parsed.segments[0]!) as unknown as Text;+ assert.equal(countSpeechEstimateUnits(speech.value, "zh"), countSpeechEstimateUnits(full.serializations.speech, "zh"));+ assert.deepEqual(narrativeValue(parseScript("formatted", formatScript("short", body)), "story"), narrativeValue(parsed, "story"));+ const source = `<script id="story">${body}</script>`;+ const decoded = decodeScriptSurface({ sourceName: "short.svml", source, tag: "script",+ attributes: { id: "story" }, openingStart: 0, contentStart: source.indexOf(">") + 1 });+ assert.deepEqual(decoded.records.find(record => record.id === "story")?.value,+ { kind: "inline", value: narrativeValue(parsed, "story") });+ }+});++test("shared text permits semantic markers without changing display; empty groups still fail", () => {+ const parsed = parseScript("shared", '<intro><HOST><组@part 件@/part化|></intro>');+ assert.equal(parsed.serializations.speech, "组件化");+ assert.equal(parsed.captionProjection.text, "组件化");+ assert.equal(parsed.selections[0]!.startAnchorId, parsed.tokens[1]!.startAnchorId);+ assert.equal(captionDocument(parsed, "caption", "story").units[0]!.sourceTokenIds.length, 3);+ for (const body of ['<|>', '< | >', '<@beat!|>', '<...|>']) {+ assert.throws(() => parseScript("empty", `<intro>${body}</intro>`), /omitted speech must contain spoken text/u);+ }+ assert.throws(() => parseScript("cue", '<intro><动效|动||效></intro>'), /Cue break cannot occur inside/u);+ assert.throws(() => parseScript("explicit", '<intro><@bad 字|word></intro>'), /spoken text, not the Dual display side/u);+});+test("Script exports complete author content and a caption view from that same value", () => {const source = `<script id="story">${body}</script>`;const result = decodeScriptSurface({ sourceName: "views.svml", source, tag: "script",diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.mdindex cab4c2a7..5f9f529e 100644--- a/skills/hypit/references/creation/script-and-time.md+++ b/skills/hypit/references/creation/script-and-time.md@@ -61,6 +61,7 @@ The author-facing forms are:| `<pause/>` | A self-closing Segment with identity and boundaries but no words. || `<HOST>` | A Role Cue inside the current Segment; it applies until another Role Cue or the Segment end. || `<display text \| spoken text>` | One Dual Text unit with separate visible and pronounced wording. |+| `<display text\|>` | One complete display/speech unit using the same wording for both; individual spoken word times remain available. || `< \| spoken text>` | Spoken words that keep semantic timing while contributing no visible Caption words. || `||` | A Caption Cue handoff between complete Alignment Units. || `word{emphasis,keyword}` | Boolean attributes on one complete display word for a Caption family to interpret. |@@ -82,6 +83,17 @@ complete Dual Text unit, not inside it. Attributes for a displayed Dual Text wordisplay side before the pipe. Inside that display side, use `\@` when the visible text itself needs anat-sign.+When the wording is identical, `<组件化|>` is shorthand for `<组件化|组件化>`. It can group a name,+compound or phrase for Caption presentation while leaving its spoken Tokens and timing intact:+`把<动效|><组件化|>。|| 以后就能<直接复用|>。` Choose groups for the intended expression; ordinary+Chinese prose does not require word-by-word markup. The group's Style determines its visual response;+`||` still controls which reading phrases appear as separate Cues.++With speech omitted, the left side supplies both projections, so semantic markers can be placed+there and Studio writes back there: `<组@beat!件化|>`. Display attributes and markers are metadata,+not spoken words. Attributes still apply to the preceding display word rather than the whole group.+With an explicit spoken side, markers continue to belong on that right-hand side.+Script comments use ordinary Markup comments outside the prose:```svmldiff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.mdindex 8055821e..0fec5fd6 100644--- a/skills/hypit/references/playbooks/craft/captions.md+++ b/skills/hypit/references/playbooks/craft/captions.md@@ -137,6 +137,13 @@ Choose `trail` instead of `current` when the already spoken characters should stsweeps inside its glyphs. Both follow each unit's own speech time, including uneven delivery andpauses. Making a Cue longer changes its reading group, not its character timing.+When a compound, name or short phrase should respond together, author it as `<组件化|>` in Script.+The omitted spoken side inherits the same words. Fine's existing whole-unit `step` highlighting,+underline and active box then follow that group's first-to-last speech interval, while each spoken+character keeps its own Timeline anchors. A Cue can mix these groups with ordinary characters.+Use this for deliberate whole-expression treatment, not as a requirement to annotate every Chinese+word. `||` remains the reading handoff; group markup does not create another Cue.+Text appearing and text changing color are separate choices. `atom-reveal: all` keeps the completeCue available to read while Karaoke supplies emphasis; `on-start` reveals whole spoken units, and`typewriter` reveals whole graphemes within them. A pronunciation span such as `<API|A P I>`