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
docs: stop publishing rejected designs, and offer the skill in the README
rpone140615d43b69
diff --git a/README.md b/README.mdindex e7342885..0b404281 100644--- a/README.md+++ b/README.md@@ -103,6 +103,16 @@ Caption or Track component must explicitly consume that Selection. The full voca[Script](https://narratage.hypit.ai/quickstart/script); the complete checkable source is[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml).+## Use the Narratage skill++If you use a coding agent, send it this:++```text+Install and use the narratage skill from this repository. Set up my environment, ask for only the+API keys required by my Runtime Profile, and guide me through authoring and building my first SVML+video.+```+## Try it without API keysNode.js 22+ and pnpm 10.33.x:diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 10faaba8..6c03b092 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -92,6 +92,15 @@ Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在标记名本身不带行为:`@silence` 不会让音频静音,必须由 Audio、Caption 或 Track 组件显式消费这个Selection。完整词汇见 [Script](https://narratage.hypit.ai/zh/quickstart/script);完整且可检查的源码见[`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml)。+## 使用 Narratage skill++如果使用编程 Agent,把下面这段发给它:++```text+安装并使用这个仓库里的 narratage skill。配置我的环境,只向我索取当前 Runtime Profile+实际需要的 API key,然后带我完成第一支 SVML 视频的创作与 Build。+```+## 不需要 API Key 也能试需要 Node.js 22+ 与 pnpm 10.33.x:diff --git a/docs/guide/spec/audio-track.md b/docs/guide/spec/audio-track.mdindex 338dce0c..10caacec 100644--- a/docs/guide/spec/audio-track.md+++ b/docs/guide/spec/audio-track.md@@ -53,7 +53,7 @@ The Audio Track lowerer may derive the terminal Artifact duration from the normacount. It must not copy source identities, Narrative digests, provider names or other lineage intothe clip. Those relations remain graph edges and Derivations.-Do not introduce a new public `AudioMaterial` Type merely to shorten one edge. If several unrelated+Do not introduce a new public canonical-audio Type merely to shorten one edge. If several unrelatedpackages later need a first-class canonical-audio value, that focused intrinsic Type belongs in`@narratage/media`; it still does not belong in Core or an umbrella contracts package.diff --git a/docs/guide/spec/deck-track.md b/docs/guide/spec/deck-track.mdindex 41a577b4..311cdff5 100644--- a/docs/guide/spec/deck-track.md+++ b/docs/guide/spec/deck-track.md@@ -93,7 +93,7 @@ The intended relationship is:`@narratage/deck-track` may reuse focused implementation functions from Media Track or a laterimplementation-only media-lowering library. That code reuse does not make Deck a Media Track-component and does not expose a universal `MediaProgram` or `DeckProgram` through Core.+component, and Core exposes no universal media or deck program.The package does not:diff --git a/docs/guide/spec/media-track.md b/docs/guide/spec/media-track.mdindex 457c34ad..50151a14 100644--- a/docs/guide/spec/media-track.md+++ b/docs/guide/spec/media-track.md@@ -486,8 +486,8 @@ Entry/exit or handoff SFX are explicit audio Artifact inputs with explicit gain.the exact resolved entry, exit or boundary point. They are not package-global filenames, mutablesound-library defaults or hidden lane SFX.-The compiler does not return one atomic `MediaProduct` containing both terminal Tracks. It resolves-one package-owned Media Program and provides separate deterministic projection Operations:+The compiler resolves one package-owned Media Program and provides separate deterministic projection+Operations, rather than one atomic value carrying both terminal Tracks:```textResolved Media Program ─┬─> project visual ─> VisualTrack@@ -541,7 +541,7 @@ audio remains the separate canonical `SpeechAudioBasis -> AudioTrack` projectionvisual lowerer itself remains muted and does not rediscover container audio.This can be a code dependency on focused Media lowering helpers. It does not require exposing a-public `MediaProgram` graph Type when no external component consumes that intermediate value. If a+that intermediate value as a public graph Type when no external component consumes it. If areal graph consumer appears later, the package may expose its own versioned resolved Type; Corestill does not register Media meaning.diff --git a/docs/guide/spec/ranking-track.md b/docs/guide/spec/ranking-track.mdindex 1f217830..337e64b7 100644--- a/docs/guide/spec/ranking-track.md+++ b/docs/guide/spec/ranking-track.md@@ -172,7 +172,7 @@ settled life [stage.end, O)`[B, p1)` may show an explicitly authored empty board, but has no implicit active item. `[T, O)` isthe optional fully-settled suffix with no active item. These facts are package-owned siblingsequencing built on the shared temporal projection algebra in-[`track-authoring.md`](./track-authoring.md); they are not a new `Stage` contract.+[`track-authoring.md`](./track-authoring.md); they are not a new staging contract.### TierBoarddiff --git a/docs/guide/spec/screen-overlay.md b/docs/guide/spec/screen-overlay.mdindex 7a67486d..e7c9dd32 100644--- a/docs/guide/spec/screen-overlay.md+++ b/docs/guide/spec/screen-overlay.md@@ -187,7 +187,7 @@ Screen Overlay also cannot:- hide a sound effect inside a visual item.A visually masked hard cut remains two independent facts: the Media package owns the cut and the-Screen Overlay happens to cover some of the same frames. A combined authored `Impact` Fragment may+Screen Overlay happens to cover some of the same frames. A combined authored Fragment mayproduce one Visual Track and one Audio Track from the same Moment, but both outputs remain explicitpeer edges into Film.diff --git a/docs/guide/spec/spatial-layout.md b/docs/guide/spec/spatial-layout.mdindex 5607c0fb..594ac578 100644--- a/docs/guide/spec/spatial-layout.md+++ b/docs/guide/spec/spatial-layout.md@@ -428,10 +428,10 @@ Retained:Retired:-- `SpaceLocator` as a union mixing regions, VLM inference, avoidance, path signals and fixed boxes;+- one locator union mixing regions, VLM inference, avoidance, path signals and fixed boxes;- nine-grid codes as separate algorithms;- one `focalX/focalY` reused as both source and target point;-- `MediaBoxStyle` treating exactly one foreground and one special backing as the universal model;+- a media box style treating exactly one foreground and one special backing as the universal model;- embedding zoom into fit;- renderer-specific CSS and FFmpeg formulas as two sources of truth;- hidden `object-fit`, `object-position` or `backdrop-filter` defaults.diff --git a/docs/guide/spec/track-authoring.md b/docs/guide/spec/track-authoring.mdindex c4327116..b97c3b26 100644--- a/docs/guide/spec/track-authoring.md+++ b/docs/guide/spec/track-authoring.md@@ -254,7 +254,7 @@ hidden global auto-stitch behavior.Ranking, Tier, slides and other progressive components often have only an ordered set of triggerMoments. Reaching trigger `i` enters state `i`; reaching trigger `i + 1` hands off to the next state.-This case uses the same point location and window projection. It does not justify a `Stage` Type in+This case uses the same point location and window projection. It does not justify a staging Type inCore or another Script marker.`N` trigger points alone cannot bound `N` finite stages: the last stage still needs one terminal@@ -451,7 +451,7 @@ The executable acceptance coverage includes:The complete Ranking audit, component split, group schedule and executable migration are specified in[`ranking-track.md`](./ranking-track.md). Ranking now validates that the common temporal algebra cansupport cumulative state, exclusive current stages and a final settled suffix without adding-Ranking or `Stage` meaning to Core or the public Track contract.+Ranking or staging meaning to Core or the public Track contract.## 10. Migration statediff --git a/docs/guide/spec/track-composition.md b/docs/guide/spec/track-composition.mdindex cdb72bc4..967df71d 100644--- a/docs/guide/spec/track-composition.md+++ b/docs/guide/spec/track-composition.md@@ -1,6 +1,6 @@---title: SVML Track and Composition-description: executable repository-internal `@1` compatibility waist; all gates in.+description: Executable repository-internal `@1` compatibility waist for Track and Composition.---# SVML Track and Compositiondiff --git a/docs/guide/spec/track-expressiveness.md b/docs/guide/spec/track-expressiveness.mdindex c800b496..4cef7571 100644--- a/docs/guide/spec/track-expressiveness.md+++ b/docs/guide/spec/track-expressiveness.md@@ -19,7 +19,7 @@ This gate answers one question:> Can production-used text, media-box, caption, stacking and local-effect behavior lower into the> same Track waist without adding package-family fields to Track, Composition or Core?-Passing this gate does not make one universal `TrackProgram`. The six Track Program axes—content,+Passing this gate does not make one universal Track Program. The six Track Program axes—content,temporal source, window projection, spatial source, occupancy and presentation—remain a separationdiscipline for package authors, not six mandatory public fields. The shared authoring laws and thecurrent temporal design are specified in [`track-authoring.md`](./track-authoring.md).diff --git a/docs/guide/spec/typography-track.md b/docs/guide/spec/typography-track.mdindex abbf03d3..deb7c2d6 100644--- a/docs/guide/spec/typography-track.md+++ b/docs/guide/spec/typography-track.md@@ -1,6 +1,6 @@---title: Typography Track Authoring and Expressiveness-description: implemented pre-release authority for the official two-dimensional Text package. The.+description: Implemented pre-release authority for the official two-dimensional Text package.---# Typography Track Authoring and Expressiveness@@ -11,7 +11,7 @@ Track/Visual IR waist; the author Surface itself is not yet a published ABI.## 1. Conclusion-The complete Text model is not a larger `TextAppearance` object. It is the orthogonal product of:+The complete Text model is the orthogonal product of:```textauthored document@@ -40,91 +40,7 @@ The official Text package owns this author meaning. SVS only provides named immuparameters. Visual IR remains the shared terminal video language. HyperFrames is one renderer ofthat language, not the definition of Text.-## 2. Audit evidence--### 2.1 Current Narratage slice--The current `packages/typography-track` implementation has one fixed rectangular box, one plain string-and one `TextAppearance` containing color, size, family, weight, line height, horizontal/vertical-alignment, one background, radius, padding and tracking. Its Surface accepts exactly `text`,-`during` and `appearance`; its Recipe requires exactly eleven scalar properties.--It currently cannot represent:--- paragraphs, explicit line breaks or differently styled inline runs;-- exact font Artifact inputs on the author Surface;-- point text, intrinsic sizing or path text;-- independent frame/content/paragraph/line/run/word/grapheme Paint targets;-- gradients, repeated strokes, repeated shadows, glow or underline layers;-- Unicode-aware word/grapheme behavior, bidirectional runs or vertical text policy;-- item, line, word or grapheme animation;-- text masks or materialized advanced text.--This is a useful end-to-end witness only. Extending `TextAppearance` field by field would preserve-the wrong model.--### 2.2 Legacy evidence--The legacy `TextLayoutV2` discovered several correct separations:--- inline/block `hug | fixed` sizing;-- independent padding and inline/block alignment;-- no-wrap, word-wrap and character-wrap;-- visible, clip, ellipsis and shrink overflow;-- LTR/RTL and horizontal/vertical writing;-- frame/content/line/word background targets;-- line-box, cap-height and ink-bound metrics.--Its renderer also implemented solid/gradient glyph fill, outside stroke, shadow, glow, callout-tails, whole-item entry/loop motion, typewriter reveal and line/word backgrounds. Those are valuable-behavioral witnesses.--The implementation also exposes why it must not be copied as the new contract:--- one `TextFields` bag mixes content, layout, Paint, motion and decoration;-- gradient fill and background both compete for the CSS `background` property;-- word backgrounds split on a whitespace regular expression and therefore do not define Unicode- word behavior;-- typewriter slices JavaScript code units rather than grapheme clusters;-- outside stroke is an implicit duplicated-glyph renderer trick;-- line fragments, shrink-to-fit and cap/ink trimming depend on browser behavior not represented in- the authored value;-- a pointer silently creates a background and several defaults are renderer inventions;-- there is no rich-run, path-text or repeated Paint-layer model.--An audited historical export contained 32 Text Tracks and 53 Text items. The most frequently used-properties were alignment, font family/size, color, weight, background, radius and padding. Stroke,-uppercase, no-wrap, full-width background, tracking and shadow were also used. The sample contained-no Text animation usage. This proves the ordinary delivery baseline; it does not justify excluding-the broader, well-established editor capabilities below.--### 2.3 External editor attack matrix--The design was checked against official product documentation rather than inferred from UI labels:--| Capability family | Established examples | Required Narratage expression |-|---|---|---|-| advanced typography | tracking, kerning, leading, baseline shift, tabs, caps, super/subscript, underline and Tsume | typed typography and per-run overrides |-| layered appearance | solid/gradient fill, inner/center/outer and repeated strokes, repeated shadows, glow | ordered, repeatable Paint layers |-| geometric text boxes | point titles, area paragraphs, responsive alignment, rolls/crawls | separate Point and Area forms plus motion |-| fragment styling | character/word/line styling and animation | deterministic units and selectors |-| sequential animation | per-character delay, range/follower selectors, direction, spread and loops | selector plus property-animation stack |-| path text | text following and animating along open/closed paths | explicit Path Text form |-| text masks | text revealing explicitly owned media or graphics | sibling component with an explicit media input |-| real 3D text | extrusion, bevel, materials, lighting and per-character 3D | materialized 3D component, not fake 2D fields |--Reference documentation:--- Adobe Premiere: [Text Styles](https://helpx.adobe.com/uk/premiere/desktop/add-text-images/stylize-text/create-text-styles.html)- and [Text Style Parameters](https://helpx.adobe.com/ca/premiere/desktop/add-text-images/stylize-text/style-parameters-when-applying-from-style-browser.html)-- Adobe After Effects: [Animating Text](https://helpx.adobe.com/uk/after-effects/desktop/animating-text/text-animation/animating-text.html)-- Apple Final Cut Pro: [Adjust Titles](https://support.apple.com/en-qa/guide/final-cut-pro/ver4e32ca5/mac)-- Apple Motion: [Sequence Text Behavior](https://support.apple.com/en-lamr/guide/motion/motn1607c46e/mac)-- Blackmagic Design: [DaVinci Resolve 20 Visual Effects Guide](https://documents.blackmagicdesign.com/UserManuals/DaVinci-Resolve-20-Fusion-Visual-Effects.pdf?_v=1757574011000)--This is an expressiveness attack set, not a request to reproduce every product's UI or preset list.--## 3. Ownership and package boundary+## 2. Ownership and package boundaryThe ordinary two-dimensional package remains one package:@@ -141,7 +57,7 @@ The ordinary two-dimensional package remains one package:Point, Area and Path are separate author components because they assert different geometry. Theyare not a `mode` field which makes ports appear and disappear. They may still lower into one tagged-`TextItemProgram` union and coexist as peer items in one Text Track.+union and coexist as peer items in one Text Track.Two capabilities have materially different inputs and stay out of ordinary Text:@@ -159,7 +75,7 @@ shape and one explicit still `CompositableSurface`. Rich runs, multiline/Path flanimation and timed materials fail closed and use the same materialized-Surface escape route as 3DText. This boundary avoids pretending that browser `foreignObject` masking is portable or exact.-## 4. Authored Text Document+## 3. Authored Text DocumentA Text item consumes a bounded rich document rather than an HTML fragment or arbitrary tree:@@ -202,7 +118,7 @@ the smallest ordinary author-visible animation/decoration unit. A shaped glyph ione-to-one correspondence with a Unicode character or grapheme, so the public author model must notpretend otherwise.-## 5. Three spatial forms+## 4. Three spatial formsTemporal source and window projection remain governed by[`track-authoring.md`](./track-authoring.md). Text does not invent `full`, `from`, `until` or another@@ -212,13 +128,13 @@ Spatial placement is independent from Text flow. The shared model in[`spatial-layout.md`](./spatial-layout.md) provides resolved point/frame/path geometry; Text theninterprets that geometry through one of three forms.-### 5.1 Point Text+### 4.1 Point TextPoint Text is intrinsic text anchored at a resolved point. It normally hugs its content, does notsoft-wrap and uses an explicit inline/block anchor. Manual paragraph breaks remain valid. Ordinarytitles, labels and stickers are Point Text.-### 5.2 Area Text+### 4.2 Area TextArea Text flows inside a resolved frame. It explicitly chooses:@@ -239,7 +155,7 @@ explicit. `shrink` must declare a minimum scale and fail if the complete text stmust not silently cross that bound. This differs from Caption, which must never clip or discard theauthor's display Atoms.-### 5.3 Path Text+### 4.3 Path TextPath Text consumes an explicit owned vector path plus Text Document and Style. It owns path side,orientation, start/end margins, alignment, reversal and overflow. Animating a margin moves text@@ -249,7 +165,7 @@ another Track.Path Text requires either a generic vector/path terminal primitive or an owned materializedSurface. It cannot be claimed by serializing an untyped SVG/HTML string.-## 6. Typography+## 5. TypographyTypography is separate from Paint and layout but participates in layout measurement. It includes:@@ -268,7 +184,7 @@ Exact font bytes remain explicit author graph inputs. They are not names hiddennot selected by the Runtime. Font shaping/layout implementation identity is bound by the acceptingderivation/render receipt; Core still knows nothing about fonts.-## 7. Ordered Paint model+## 6. Ordered Paint modelPaint is an ordered list, not one mutually exclusive set of CSS shortcuts. The Text Program ownstyped layers such as:@@ -286,7 +202,7 @@ type TextPaintLayer =readonly continuity: "isolated" | "joined"; readonly decoration: BoxDecoration };```-`ColorPaint` supports solid, linear-gradient and radial-gradient Paint with an ordered list of color+`VisualColorPaint` supports solid, linear-gradient and radial-gradient Paint with an ordered list of colorand opacity stops. Repeating a Stroke or Shadow is legal and order remains semantic. A renderer maylower an outside stroke through duplicated glyph layers, but that is implementation, not an authorflag whose meaning changes by browser.@@ -319,7 +235,7 @@ and its own Paint. It does not silently force a background. Frosted glass is notPaint because it samples pixels behind the Track; it requires an explicitly owned media input or amaterialized self-contained component.-## 8. Motion and sequence selectors+## 7. Motion and sequence selectorsMotion is independent from Style so the same look can enter, loop and exit differently. One itemmay have:@@ -351,7 +267,7 @@ window; the Item window clips it without rewriting its timing. Sequence and Paththe same rule. This avoids rejecting a perfectly meaningful fast title animation merely because thetitle remains visible, and avoids silently retiming a slow animation to fit a short window.-## 9. Style declaration, SVS and readable authoring+## 8. Style declaration, SVS and readable authoringDeclaration and use remain separate. SVS stays a generic scalar Recipe language; it must not learnText Paint arrays or become a second renderer. A Text Style Surface reads named Recipes, exact Font@@ -411,7 +327,7 @@ properties are:- exact fonts and timing/placement facts travel on explicit graph edges;- the resulting Text Program contains no unresolved Recipe and no Runtime/provider choice.-## 10. Compiled pipeline and data gates+## 9. Compiled pipeline and data gates```textMarkup Surface@@ -444,7 +360,7 @@ It must bind the actual implementation and font bytes. Browser line boxes are nogeneric graph metadata; they are either deterministic terminal layout owned by the renderer receiptor package-owned resolved geometry used to materialize a Surface.-## 11. Terminal Visual IR findings+## 10. Terminal Visual IR findingsThe frozen repository-internal `svml.visual-ir@1` carries the smallest additions proven by thismigration:@@ -464,7 +380,7 @@ These remain video-terminal facts, never Core facts. Renderer receipts, Surface-Deck/Ranking witnesses and the final compatibility audit now pass without adding Text meaning tothe shared waist.-## 12. Feedback into Fine Caption+## 11. Feedback into Fine CaptionText and Caption share typography implementation problems, not author truth.@@ -496,7 +412,7 @@ Caption must **not** inherit Text ellipsis, clipping, shrink-to-fit, path flow,timing or selector-generated speech timing. It always displays the author's complete immutableAtoms and activates only from proven Atom windows.-## 13. Migration order and acceptance gates+## 12. Migration order and acceptance gatesImplementation replaced the earlier slice rather than accreting compatibility fields:diff --git a/docs/zh/guide/spec/typography-track.md b/docs/zh/guide/spec/typography-track.mdindex 25a64b89..278efb24 100644--- a/docs/zh/guide/spec/typography-track.md+++ b/docs/zh/guide/spec/typography-track.md@@ -36,81 +36,7 @@ Film 或 Composition 里开分支。官方 Text 包拥有这套作者语义。SVS 只提供具名的不可变 Recipe 参数。Visual IR 仍是共享的终端视频语言。HyperFrames 只是这门语言的一个渲染器,而不是 Text 的定义。-## 2. Audit evidence--### 2.1 Current Narratage slice--当前 `packages/typography-track` 的实现只有一个固定矩形框、一个纯字符串,以及一个包含颜色、字号、字族、字重、行高、水平/垂直对齐、单一背景、圆角、内边距和字距的 `TextAppearance`。它的 Surface 恰好只接受-`text`、`during` 和 `appearance`;它的 Recipe 恰好要求十一个标量属性。--它目前无法表达:--- 段落、显式换行或样式不同的内联 run;-- 作者 Surface 上的精确字体 Artifact 输入;-- point text、固有尺寸或路径文字;-- 相互独立的 frame/content/paragraph/line/run/word/grapheme Paint 目标;-- 渐变、可重复的描边、可重复的阴影、辉光或下划线 Layer;-- 具备 Unicode 意识的词/字素簇行为、双向 run 或竖排文字策略;-- item、行、词或字素簇级别的动画;-- 文字遮罩或物化的高级文字效果。--这只是一个有用的端到端见证。一个字段一个字段地扩展 `TextAppearance`,只会把错误的模型固化下来。--### 2.2 Legacy evidence--遗留的 `TextLayoutV2` 发现了几组正确的分离:--- 内联/块级 `hug | fixed` 尺寸;-- 相互独立的内边距与内联/块级对齐;-- 不换行、按词换行和按字符换行;-- visible、clip、ellipsis 和 shrink 四种溢出处理;-- LTR/RTL 与横排/竖排;-- frame/content/line/word 背景目标;-- line box、cap height 和 ink bound 三种度量。--它的渲染器还实现了纯色/渐变字形填充、外描边、阴影、辉光、气泡尾巴、整个 item 的入场/循环运动、打字机显现以及行/词背景。这些都是有价值的行为见证。--这份实现同样暴露了它为什么不能被照搬成新合同:--- 一个 `TextFields` 参数袋把内容、布局、Paint、运动和装饰混在一起;-- 渐变填充与背景都在抢 CSS 的 `background` 属性;-- 词背景按空白字符正则切分,因此根本没有定义 Unicode 的词行为;-- 打字机切的是 JavaScript code unit,而不是字素簇;-- 外描边是靠复制字形实现的隐式渲染器把戏;-- 行片段、缩放适配以及 cap/ink 裁切依赖浏览器行为,而这些行为并未体现在被声明的值里;-- 一个指针会悄悄创建出背景,而且好几个默认值是渲染器自己发明的;-- 完全没有富 run、路径文字或可重复 Paint Layer 的模型。--一份经过审计的历史导出包含 32 个 Text Track 和 53 个 Text item。使用频率最高的属性是对齐、字族/字号、颜色、字重、背景、圆角和内边距。描边、大写、不换行、全宽背景、字距和阴影也有使用。该样本中没有任何-Text 动画使用记录。这证明了常规交付的基线;但它不足以成为排除下文那些成熟编辑器能力的理由。--### 2.3 External editor attack matrix--本设计是对照官方产品文档核对的,而不是从 UI 标签反推的:--| 能力族 | 成熟产品的例子 | Narratage 中要求的表达 |-|---|---|---|-| advanced typography | 字距、字偶距、行距、基线偏移、制表位、大写、上/下标、下划线与 Tsume | 带类型的 typography 与逐 run 覆盖 |-| layered appearance | 纯色/渐变填充、内/中/外描边与可重复描边、可重复阴影、辉光 | 有序、可重复的 Paint Layer |-| geometric text boxes | point 标题、area 段落、响应式对齐、滚动字幕/横向滚动 | 分离的 Point 与 Area 形态,外加运动 |-| fragment styling | 字符/词/行级样式与动画 | 确定性单元与选择器 |-| sequential animation | 逐字符延迟、range/follower 选择器、方向、扩散与循环 | 选择器加属性动画栈 |-| path text | 文字沿开放/闭合路径排布并动画 | 显式的 Path Text 形态 |-| text masks | 用文字显现显式自有的媒体或图形 | 带显式媒体输入的兄弟组件 |-| real 3D text | 挤出、倒角、材质、灯光与逐字符 3D | 物化的 3D 组件,而不是伪造的 2D 字段 |--参考文档:--- Adobe Premiere:[Text Styles](https://helpx.adobe.com/uk/premiere/desktop/add-text-images/stylize-text/create-text-styles.html)- 与 [Text Style Parameters](https://helpx.adobe.com/ca/premiere/desktop/add-text-images/stylize-text/style-parameters-when-applying-from-style-browser.html)-- Adobe After Effects:[Animating Text](https://helpx.adobe.com/uk/after-effects/desktop/animating-text/text-animation/animating-text.html)-- Apple Final Cut Pro:[Adjust Titles](https://support.apple.com/en-qa/guide/final-cut-pro/ver4e32ca5/mac)-- Apple Motion:[Sequence Text Behavior](https://support.apple.com/en-lamr/guide/motion/motn1607c46e/mac)-- Blackmagic Design:[DaVinci Resolve 20 Visual Effects Guide](https://documents.blackmagicdesign.com/UserManuals/DaVinci-Resolve-20-Fusion-Visual-Effects.pdf?_v=1757574011000)--这是一组表达力攻击集,而不是要求复刻每个产品的 UI 或预设列表。--## 3. Ownership and package boundary+## 2. Ownership and package boundary常规二维能力仍然只用一个包:@@ -137,7 +63,7 @@ Text Track 中。官方的本地 Text Mask 见证刻意只接受一个精确的单行 Area Text 形状和一个显式的静态 `CompositableSurface`。富 run、多行/Path 排布、序列动画和定时素材都会 fail closed,并走与 3D Text 相同的“物化 Surface”逃生路线。这条边界避免了假装浏览器 `foreignObject` 遮罩是可移植且精确的。-## 4. Authored Text Document+## 3. Authored Text DocumentText item 消费的是一份有界的富文档,而不是 HTML 片段或任意树:@@ -176,7 +102,7 @@ document > paragraph > explicit run > rendered line > Unicode word > grapheme cl`rendered line` 只有在确定了精确字体和最终几何之后才存在。字素簇是常规情况下作者可见的最小动画/装饰单元。一个 shaped glyph 未必与某个 Unicode 字符或字素簇一一对应,因此公开的作者模型不得假装它们一一对应。-## 5. Three spatial forms+## 4. Three spatial forms时间源与窗口投影仍由 [`track-authoring.md`](./track-authoring.md) 规定。Text 不会发明 `full`、`from`、`until` 或另一套时序系统。@@ -184,11 +110,11 @@ document > paragraph > explicit run > rendered line > Unicode word > grapheme cl空间摆放与 Text 排布相互独立。[`spatial-layout.md`](./spatial-layout.md) 中的共享模型提供解析后的point/frame/path 几何;Text 随后用三种形态之一去解释这份几何。-### 5.1 Point Text+### 4.1 Point TextPoint Text 是锚定在某个解析点上的固有尺寸文字。它通常紧贴内容、不做软换行,并使用显式的内联/块级锚点。手动分段仍然有效。常规的标题、标签和贴纸都是 Point Text。-### 5.2 Area Text+### 4.2 Area TextArea Text 在解析出的 frame 内排布。它显式选择:@@ -206,7 +132,7 @@ Area Text 在解析出的 frame 内排布。它显式选择:溢出是诚实的作者意图。`ellipsis` 可能省略掉可见的被声明文字,因此必须显式写出。`shrink` 必须声明最小缩放比例,并在完整文字仍放不下时失败;它不得悄悄越过那个下限。这一点与 Caption 不同——Caption 绝不能裁剪或丢弃作者的显示 Atom。-### 5.3 Path Text+### 4.3 Path TextPath Text 消费一条显式自有的矢量路径,外加 Text Document 和 Style。它拥有路径侧、朝向、起止边距、对齐、反向和溢出。给边距做动画会让文字沿路径移动;给路径做动画则改变路径本身。它绝不会去发现或采样另一个Track 中的形状。@@ -214,7 +140,7 @@ Track 中的形状。Path Text 需要一个通用的矢量/路径终端原语,或者一个自有的物化 Surface。它不能靠序列化一段无类型的SVG/HTML 字符串来声称已实现。-## 6. Typography+## 5. TypographyTypography 与 Paint、布局相互分离,但参与布局度量。它包括:@@ -231,7 +157,7 @@ Typography 与 Paint、布局相互分离,但参与布局度量。它包括:精确的字体字节仍是显式的作者图输入。它们不是藏在 Recipe 里的名字,也不由 Runtime 挑选。字体 shaping/布局实现的身份由被接受的推导/渲染 receipt 绑定;Core 仍然对字体一无所知。-## 7. Ordered Paint model+## 6. Ordered Paint modelPaint 是一个有序列表,而不是一组互斥的 CSS 简写。Text Program 拥有这些带类型的 Layer:@@ -274,7 +200,7 @@ frame | content | paragraph | line | run | word | grapheme气泡尾巴是显式声明、附着在某个 Box Paint Layer 上的部件,带有方位、偏移、尺寸和自己的 Paint。它不会悄悄强制生成一个背景。毛玻璃不属于普通 Box Paint,因为它要采样 Track 背后的像素;它需要一个显式自有的媒体输入,或者一个物化的自包含组件。-## 8. Motion and sequence selectors+## 7. Motion and sequence selectors运动与 Style 相互独立,因此同一套外观可以有不同的入场、循环和退场。一个 item 可以拥有:@@ -295,7 +221,7 @@ unit selector × selected property channels × keyframes × stagger/order动画的生命期与 Item 的可见性相互独立。一段运动可以在 Item 窗口结束前就完成,此时它最终被声明的状态一直保持到 Item 消失。一段运动也可以超出窗口,此时 Item 窗口只是裁剪它,而不改写它的时序。序列运动和 PathText 运动遵循同样的规则。这既避免了仅仅因为标题一直可见就拒绝一段完全合理的快速标题动画,也避免了为了塞进短窗口而悄悄给慢速动画重新计时。-## 9. Style declaration, SVS and readable authoring+## 8. Style declaration, SVS and readable authoring声明与使用保持分离。SVS 仍是通用的标量 Recipe 语言;它不得学会 Text 的 Paint 数组,也不得变成第二个渲染器。Text Style Surface 读取具名 Recipe、精确的 Font 引用和重复的结构化 Layer 声明,校验它们,然后产出一份完整的、由包自有的 `TextStyle` Record。@@ -348,7 +274,7 @@ item 也可以改为消费一个普通的图 `Text` 值:- 精确字体以及时序/摆放事实都走显式的图边;- 最终得到的 Text Program 里没有未解析的 Recipe,也没有 Runtime/provider 选择。-## 10. Compiled pipeline and data gates+## 9. Compiled pipeline and data gates```textMarkup Surface@@ -377,7 +303,7 @@ Composition -> selected final renderer布局实现可以使用被锁定的浏览器、HarfBuzz/Skia/Pango 或其他精确引擎。它必须绑定实际的实现和字体字节。浏览器的 line box 不会作为通用图元数据向外传播;它要么是渲染器 receipt 所拥有的确定性终端布局,要么是包自有的、用于物化 Surface 的已解析几何。-## 11. Terminal Visual IR findings+## 10. Terminal Visual IR findings冻结的仓库内部 `svml.visual-ir@1` 只承载本次迁移所证明的最小增量:@@ -391,7 +317,7 @@ HyperFrames 参考编译器实现了这些原语,同时不向作者包暴露 H这些始终是视频终端的事实,绝不是 Core 的事实。渲染器 receipt、Surface 字节校验、Deck/Ranking 见证以及最终的兼容性审计,如今都在不向共享窄腰添加 Text 语义的前提下通过。-## 12. Feedback into Fine Caption+## 11. Feedback into Fine CaptionText 与 Caption 共享的是排版实现难题,而不是作者语义。@@ -416,7 +342,7 @@ Text 与 Caption 共享的是排版实现难题,而不是作者语义。Caption **不得**继承 Text 的 ellipsis、裁剪、缩放适配、路径排布、任意富 run 时序或选择器生成的语音时序。它始终展示作者完整的不可变 Atom,并且只从已证明的 Atom 窗口激活。-## 13. Migration order and acceptance gates+## 12. Migration order and acceptance gates实现是替换掉早期切片,而不是不断堆砌兼容字段: