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: describe semantic Studio writeback
kashorin9d8c4bbc1dd4
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 2db30748..19e4b960 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -169,6 +169,7 @@ const enTheme = {{ text: "Component Anatomy", link: "/guide/component-anatomy" },{ text: "Adding a Provider", link: "/guide/providers" },{ text: "Runtime", link: "/guide/runtime" },+ { text: "Studio Companions", link: "/guide/studio-companion-architecture" },{ text: "Studio Temporal Lineage", link: "/guide/studio-temporal-windows" },{ text: "Testing", link: "/guide/testing" },{ text: "Conventions", link: "/guide/conventions" },@@ -213,6 +214,7 @@ const zhTheme = {{ text: "添加 Author 包", link: "/zh/guide/author-packages" },{ text: "添加 Provider", link: "/zh/guide/providers" },{ text: "Runtime", link: "/zh/guide/runtime" },+ { text: "Studio Companion", link: "/zh/guide/studio-companion-adapter-architecture" },{ text: "Studio 时间谱系", link: "/zh/guide/studio-temporal-windows" },{ text: "测试", link: "/zh/guide/testing" },{ text: "代码规范", link: "/zh/guide/conventions" },diff --git a/docs/guide/packages.md b/docs/guide/packages.mdindex 5a634e52..bfc33586 100644--- a/docs/guide/packages.md+++ b/docs/guide/packages.md@@ -95,6 +95,7 @@ specific Provider deployment.@hypit/speech shared speech products@hypit/speech-evidence acoustic evidence products@hypit/speech-alignment speech alignment+@hypit/semantic-take-estimate explicit syllable-weighted preview alignment@hypit/semantic-track continuous semantic program skeleton@hypit/speech-track ordered speech-take compilation@hypit/whisperx WhisperX component@@ -235,7 +236,7 @@ A physical package may expose independently activated facets:| `compute` | deterministic Producer, Type Validator | pure computation | compiler Host || `endpoint` | privileged external capability | network, filesystem, process, credentials | Runtime Profile || `infrastructure` | Scheduler, Worker and Store implementation | persistence, scheduling | Runtime Profile |-| `application` | Host-specific interpretation such as a Studio adapter | only that application's UI/operations | explicit application profile |+| `application` | Host-specific interpretation such as a Studio Track Companion | only that application's UI/operations | explicit application profile |A source `<import>` activates only author facets. It never grants network, filesystem, process,credential or queue authority.@@ -249,7 +250,7 @@ installs packages and owns their versions and integrity. Hypit has two explicit|---|---|| Source imports | Frontends, Surfaces, Producers and Validators || Runtime Profile `use` | Runtime Hosts, infrastructure and Provider Endpoints |-| Studio Profile `adapterPackages` | project companion adapters selected for that Studio session |+| Studio Profile `companionPackages` | project Companion packages selected for that Studio session |A Source import never grants network, filesystem, process, credential or queue authority. Thoseremain available only to packages explicitly selected by the Runtime Profile.diff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.mdindex 75320e91..0a192add 100644--- a/docs/guide/studio-temporal-windows.md+++ b/docs/guide/studio-temporal-windows.md@@ -1,101 +1,96 @@---title: Studio Temporal Lineage-description: How Hypit Studio reads authored, projected and consumed time without reconstructing it.+description: How author choice becomes an Instant or Window and returns to its real source.---# Studio Temporal Lineage-> Status: executed Point/Window lineage is implemented. Writeback is enabled only when a gesture-> has one explicit source preimage; cross-layer back-propagation remains forbidden. This does not-> define a new Core protocol.--A timeline item does not merely "have a start and end frame". Most authored Tracks begin with a-named semantic source such as a Selection, Segment or Moment, project that source into frame space,-and then consume the projected result as picture, sound, animation or an internal schedule. Studio-must preserve those three stages instead of flattening them into one anonymous rectangle.--## The three layers--### 1. Selection window--The selection window is the semantic source chosen by the author. It retains:--- the source kind: Selection, Segment, Moment or Program;-- the canonical source identity;-- its anchors on the selected Semantic Track;-- the source range of the author expression that refers to it.--For a Moment this is a point rather than a duration. A Selection is exactly one contiguous interval,-and a Moment is exactly one point. Equal frame coordinates do not make two semantic sources identical.--A Selection preserves the author's directed pair of Anchors. Script does not sort, swap or clamp-them. Anchor direction and the validity of a projected window are separate concerns: Temporal-Projection rejects a reversed or zero-width raw window, then rejects an intersection with-ProgramSpace that quantizes below one frame. A consumer of one Point can therefore retain the-original author identity while duration consumers never receive an invalid Window.--### 2. Projection point or window--The projection window is the result of applying the Track's temporal expression to one source. For-example, an item may use the complete Selection, begin three frames before a Moment, or run from-`segment.start + 2s` to `segment.end`. Projection includes offset evaluation, clipping to Program-Space and frame quantization.--One authored binding produces one `TemporalPoint` or `TemporalWindow` when it resolves. Activation-and terminal boundaries remain Points, including the exact `program.end` boundary; they are never-encoded as one-frame Windows. A component can combine several projected values, such as computing-disjoint reveal intervals. That relation belongs to the component's public programme or schedule,-not to a Studio guess.--### 3. Consumption window--The consumption window describes what the realized Track actually uses. It may equal the projected-window, but equality is not assumed. Examples include:--- a Media Item whose picture lifetime equals its projected window;-- a source-audio trim whose source samples differ from its target window;-- a Media Sequence with logical member spans, visual spans and a handoff span;-- a Ranking with one outer projected window and several reveal-consumption windows;-- an enter or exit animation whose motion occupies part of the Track item's lifetime.--Consumption is published by the domain programme, schedule, Visual Track or Audio Track. Studio-must not reconstruct it from naming conventions or reimplement a package's scheduling algorithm.--## Identity chain Studio must retain--Studio eventually needs a lossless chain with explicit identities:+Time has three layers:```text-author element- -> semantic binding (kind, source id, author range)- -> projection expression and projected Point/Window- -> consumed entity and consumed window(s)- -> terminal visual/audio realization+semantic choice (Program / Selection / Segment / Moment)+ -> projection (TemporalInstant / TemporalWindow)+ -> domain consumption (Program / Schedule / Track)```-The links matter more than coincident frame numbers. Several Tracks may consume the same Selection;-one projected window may feed several visual and audio facets; one component may expand one outer-window into many internal windows. These are shared bindings and projections, not duplicate clips.--Studio builds this chain from the exact executed dependency closure of each selected Track. It-indexes each Temporal record, its projection Spec, source identity and direct consumer edge, then-passes that stable view to the adapter registry. Domain packages remain unaware of Studio. A-required link that is absent stays unresolved; adapters do not infer it from attribute names, Spec-type names, runtime id prefixes, labels or equal spans.--## Timeline writeback--Studio exposes two author mutations: `timeline.adjust` and `parameter.adjust`. Move and trim are-gesture payloads of the former, not additional top-level operations. The concrete write target is-resolved from the entity's executed lineage:--- a Selection-backed rectangle moves or trims that shared Selection at Script's ordered semantic- Anchors, and every consumer follows it;-- a Moment-backed entity moves the shared Moment point, while an independently authored duration- may still own its right edge;-- direct absolute endpoints rewrite their exact Source ranges;-- Segment, Program and component-derived schedule phases remain read-only without a declared inverse.--This is an inverse over public identities, never an inference from equal frame spans. Component-details such as Ranking reveals use attached lanes only when their Point/Window inputs were explicitly-externalized. Invalid domain input is refused and the author mutation is rolled back.+Script's semantic ruler contains `2M + 2N + 2` ordered points: Token and Segment boundaries plus+distinct Program start/end anchors. Program anchors resolve at frame `0` and `frameCount` in the+SemanticTrack; they are author points and therefore never have to be forged inside a SemanticTake.+This does not make `during="program"` writable: that projection remains structurally fixed.++`@hypit/temporal-markup` owns the SVML author forms and lowers them before a domain component runs.+The compiler only composes records, components and fragments; it does not recognize `during`, `at`+or any time grammar. The graph also projects `ProgramSpace` through the public Semantic Track producer,+so domain components consume only ProgramSpace and projected time values and remain independent from+both semantic lookup and Studio.++## Runtime values++A `TemporalInstant` contains the runtime source used to evaluate it, the exact point expression and+resolved frame, and one author authority: `semantic`, `parameter` or `fixed`.++The identity chain is author-visible rather than synthesized by Studio:++- `<script id="story">` becomes `Narrative.id = story`; every Selection, Moment, Segment excerpt+ and CaptionDocument from that Script carries `narrativeId = story`;+- the selected Semantic Track id becomes `ProgramSpace.id`; every terminal Track carries that exact+ `programSpaceId`;+- every projected Instant/Window carries both identities plus the consumer's public domain identity+ (normally its SVML `id`) as `subjectId`.++The projection record `id` may be qualified to stay unique inside an expanded graph; it is not the+author identity. `subjectId` is kept separate and remains the exact board, card, item or sequence+identity published by the component's public Program.++These values are ordinary runtime provenance, not random hashes or Studio metadata. They let a+consumer and its inverse reject a same-named Selection from another Script or a Track projected on+another timeline. A Script id therefore names one Narrative across the active Source closure; if two+distinct Scripts declare the same id, Studio refuses the ambiguous inverse instead of choosing one.++A `TemporalWindow` contains two complete Instants and a non-empty half-open span. Its endpoints may+have different sources and different authorities, so a Window never pretends to have one source.+ProgramSpace boundaries are legal Instants; `program.end` is not disguised as a one-frame Window.+Out-of-range Instants and reversed or empty Windows are rejected, not clipped or repaired.++## Author forms++| Form | Start authority | End authority | Timeline writeback |+|---|---|---|---|+| `during={Selection}` | semantic Selection start | semantic Selection end | Script markers |+| `during={Segment}` / `during="program"` | fixed | fixed | read-only |+| `at={Moment} for="…"` | semantic Moment cue | parameter `for` | Script and/or SVML atomically |+| `until={Moment} for="…"` | parameter `for` | semantic Moment cue | Script and/or SVML atomically |+| `start="…" end="…"` | parameter `start` | parameter `end` | SVML timing attributes |++A point consumer uses `at={Moment}` (or a chosen Selection boundary) for semantic authority. The+explicit fallback is `instant="…"`. Text such as `at="moment.cue+3f"` is rejected because it hides+whether the author intended to move the Moment or the offset.++## Studio inverse++Studio indexes the actual executed `TemporalInstant` and `TemporalWindow` records plus their direct+consumer edges. Endpoint authority, not a component name or Companion declaration, determines the+inverse:++- semantic authority writes the shared Script identity;+- parameter authority names the author input selected by the runtime record;+- fixed authority disables a gesture that would change it.++For `at/for` and `until/for`, one gesture may touch both layers. For example, trimming the start of+an `at/for` Window moves the Moment and changes `for` so the end stays fixed. Studio applies both+source ranges as one revisioned transaction, recompiles, and rolls both back on failure.++Companion packages still decide how an entity looks and which Inspector fields are visible. They do+not declare common timeline inverse functions. A new component becomes time-editable by consuming+the same public Instant/Window protocol and carrying its executed lineage to its Studio entity.++Film and Script interpretation also remain outside Studio core. `film-studio` declares which Film+reference is the semantic axis and which child references are terminal Tracks; `script-studio` owns+Script source observation and marker relocation. Studio selects the Script source map whose+`narrativeId` exactly matches the active ProgramSpace and delegates the edit back to that companion.++The binding name is not used as a global address. Markup retains the exact author element and input+range while decoding, Elaborator hygienizes that endpoint with its Source unit, and the compiled+`AuthorProvenance` joins the executed authority to one author endpoint. Studio therefore never+chooses the first same-named `start`, output or local id across imported Sources. The provenance is+recomputed with the compilation and is not persisted as metadata, a lock or an index file.diff --git a/docs/quickstart/script.md b/docs/quickstart/script.mdindex b0dc7c6e..357fb05f 100644--- a/docs/quickstart/script.md+++ b/docs/quickstart/script.md@@ -172,6 +172,12 @@ marker; the value is a pair of semantic anchors, not a frame span:The `~` suffix/prefix controls whether the boundary snaps to the left or right. Default open isright-absorbing; default close is left-absorbing.+The complete Script has exactly `2M + 2N + 2` ordered semantic anchors: two for every Token, two for+every Segment, and the Program start/end. At the outer cuts, affinity keeps coincident meanings+distinct: `~@id` before the first Segment chooses Program start while `@id` chooses that Segment's+start; `@/id` after the final Segment chooses that Segment's end while `@/id~` chooses Program end.+Their frames may coincide after alignment, but their author identities do not.+### Multiple named SelectionsDifferent names may overlap or cross. Each name still has exactly one interval:diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 4a2b82f7..fd30226d 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -351,29 +351,34 @@ against the variant, so a Column recipe on a TierBoard is refused by name.| Attribute | Takes ||---|---|| `semantic` | the SemanticTrack the board is timed against |-| `frame` | a `space:Frame` — for `Column`, the fixed ranking rail |-| `during` | a Selection — the board is on screen for it |+| `frame` | a `space:Frame` — the compact board itself for TierBoard/Column |+| `during` | a Segment or Selection for TierBoard/Column; a Selection for TopThree || `style` | the matching style record, and only that variant's || `appear-sound`, `move-sound` | optional Synchronized Media |-| `terminal` | the Moment where the completed board settles. `TierBoard` and `TopThree` only |-| `canvas` | a `space:Canvas` — the reveal stage. `Column` only |+| `terminal` | the Moment where the completed board settles. `TopThree` only |+| `canvas` | a `space:Canvas` — the independent reveal stage. TierBoard/Column |-`Column` separates placement from reveal time, so it takes no `terminal`: each-item carries its own reveal window instead, and the Column resolves siblings into non-overlapping-windows inside the container's `during` span.+`TierBoard` and `Column` take no `terminal`: every non-preset item carries an explicit reveal+Selection. Sibling windows must already be non-overlapping and inside the container's `during`+span.`move-sound` is refused on `TopThree`, which has no move phase. On a `TierBoard` it needs at least-one item with `entry="stage"` — a sound with nothing to sound on is an authoring mistake, not a-silent no-op.+one item with `entry="drop"`. A drop Item appears in place on the independent Canvas stage when its+Selection starts, stays still while that Item is discussed, and only follows an eased curved glide+into its tier during the final `move-frames` ending at the Selection boundary. The move sound starts+with that final glide.### The item tagsEach variant takes its own, at least one, and ids must be unique within a board.-- **`TierItem`** — `tier`, `icon` and item-owned Moment `at` are required; `entry="direct" | "stage"`- and `stack` are optional. Row labels come from the recipe, not the tag.+- **`TierItem`** — `tier` and `icon` are required. A non-preset item owns a `during` Selection and+ must choose `entry="direct" | "drop"`; `preset="true"` has neither. Presets occupy inner cells+ first, then reveal-window order fills each tier outward. Both modes use a quick in-place overshoot;+ direct appears in its final cell, while drop uses the independent stage for the complete+ explanation window before settling. Row labels come from the recipe.- **`TopThreeItem`** — `label` and item-owned Moment `at` are required; `icon` and `stack` are optional.- At most three. TierBoard and TopThree reveal order comes from these Moments' actual frame order.+ At most three. TopThree reveal order comes from these Moments' actual frame order.- **`ColumnItem`** — `label` (required) and `rank` (required, a positive integer that decides thenumbered row and nothing else), optional `icon` and `stack`. Each item also owns its reveal time:`during` names a Selection whose projected window is when it prefers to appear, anddiff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdindex e7422d4f..28e6f4c3 100644--- a/docs/zh/guide/packages.md+++ b/docs/zh/guide/packages.md@@ -88,6 +88,7 @@ Frontend;不存在一个认识全部语法的中央解析器。@hypit/speech shared speech products@hypit/speech-evidence acoustic evidence products@hypit/speech-alignment speech alignment+@hypit/semantic-take-estimate 显式的音节加权预览对齐@hypit/semantic-track continuous semantic program skeleton@hypit/speech-track ordered speech-take compilation@hypit/whisperx WhisperX component@@ -217,7 +218,7 @@ packages/example/| `compute` | 确定性 Producer、Type Validator | 纯计算 | 编译器 Host || `endpoint` | 具备特权的外部能力 | 网络、文件系统、进程、凭据 | Runtime Profile || `infrastructure` | Scheduler、Worker 与 Store 实现 | 持久化、调度 | Runtime Profile |-| `application` | Studio adapter 等特定应用解释 | 仅该应用的 UI/操作 | 显式应用 profile |+| `application` | Studio Track Companion 等特定应用解释 | 仅该应用的 UI/操作 | 显式应用 profile |源码中的 `<import>` 只会 activate author facet。它绝不授予网络、文件系统、进程、凭据或队列权限。@@ -230,7 +231,7 @@ Hypit 不维护中央包注册表,也不维护自定义包锁。npm 或 pnpm|---|---|| Source import | Frontend、Surface、Producer、Validator || Runtime Profile 的 `use` | Runtime Host、基础设施与 Provider Endpoint |-| Studio Profile 的 `adapterPackages` | 当前 Studio 会话显式选择的项目 companion adapter |+| Studio Profile 的 `companionPackages` | 当前 Studio 会话显式选择的项目 Companion 包 |Source import 绝不授予网络、文件系统、进程、凭据或队列权限;这些权限只属于 RuntimeProfile 显式选择的包。diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.mdindex 1bab8772..8402de84 100644--- a/docs/zh/guide/studio-temporal-windows.md+++ b/docs/zh/guide/studio-temporal-windows.md@@ -1,84 +1,105 @@---title: Studio 时间谱系-description: Studio 如何沿真实执行图呈现选择、投影与消费,而不反向猜测。+description: 作者选择如何成为 Instant 或 Window,并准确回到真正的作者源。---# Studio 时间谱系-> 状态:Temporal Point/Window 的只读谱系已经接通。只有存在唯一源码逆像的编辑才允许写回;-> 跨层自动反推仍被禁止。这不新增 Core 协议。--时间线 item 并不只是一个起止帧矩形。大多数 Track 先选择 Program、Selection、Segment 或-Moment,再把它投影进帧空间,最后由领域组件消费。Studio 保留这三个层级:+时间只有三层:```text-作者选择层(Program / Selection / Segment / Moment)- -> 投影层(TemporalPoint / TemporalWindow)- -> 消费层(Item 生命周期、Sequence、Ranking Schedule、Track)+选择层(Program / Selection / Segment / Moment)+ -> 投影层(TemporalInstant / TemporalWindow)+ -> 消费层(Programme / Schedule / Track)```-## 选择层+Script 的语义标尺包含严格有序的 `2M + 2N + 2` 个点:Token 与 Segment 的首尾,再加彼此+独立的 Program start/end。Program 锚点由 SemanticTrack 在 `0` 和 `frameCount` 解析,不需要+伪造进某个 SemanticTake。它们是 Selection/Moment 可选择的作者语义点;这不会让+`during="program"` 变成可写,后者依然是结构固定的投影。++`@hypit/temporal-markup` 统一拥有 SVML 时间语法,并在领域组件运行前把它降低成普通的投影+组件和运行图边。编译器只会组合 Record、Component 和 Fragment,不认识 `during`、`at`,+各 Track 也不再各写一套找帧算法。运行图还会通过 Semantic Track 的公共 producer 显式投影+`ProgramSpace`;领域组件只消费 ProgramSpace 与时间投影结果,与选择层和 Studio 都解耦。++## 运行时对象-选择层保留来源种类与规范身份。Moment 是语义点,Selection/Segment 是语义区间;坐标相同-不表示身份相同。SVML 的 `during`、`at`、`until` 等属性只负责声明作者选择,不直接变成-领域组件中的找帧逻辑。+`TemporalInstant` 保存运行时求值来源、精确点表达式、解析后的帧,以及一个作者 authority:-Selection 保存作者明确写下的一对有方向 Anchor,不在 Script 层排序、交换或 clamp。端点方向与-最终投影是否合法是两件事:Temporal Projection 对表达式计算后的 raw window 负责,拒绝反向或-零宽窗口;与 ProgramSpace 相交后不足一帧也拒绝。这样只消费一个边界的 Point 仍可保留原始作者-身份,而持续内容不会收到非法 Window。+- `semantic`:作者权威在 Selection 或 Moment;+- `parameter`:作者权威在组件表面的某个作者时间参数;+- `fixed`:Program 或 Segment 结构决定,不开放轻量反写。-## 投影层+身份链全部来自作者声明,不由 Studio 临时生成:-Surface lowering 生成 `TemporalPointSpec` 或 `TemporalWindowSpec`,再连接正式 Temporal-Producer。投影结果保留来源身份、作者表达式与解析后的帧坐标:+- `<script id="story">` 产生 `Narrative.id = story`,它派生出的 Selection、Moment、Segment+ excerpt 与 CaptionDocument 全部携带 `narrativeId = story`;+- 被 Film 激活的 Semantic Track 的 `id` 就是 `ProgramSpace.id`,所有终端 Track 都携带同一个+ `programSpaceId`;+- 每个 Instant/Window 同时保留这两个身份,并用消费者的公开领域身份(通常就是 SVML `id`)+ 作为 `subjectId`。-- `TemporalPoint` 表示一个合法帧边界,范围是 `[0, frameCount]`;`program.end` 可以精确落在- `frameCount`。-- `TemporalWindow` 表示一个非空半开区间 `[startFrame, endFrameExclusive)`。+投影 record 的 `id` 可以为了展开后的图内唯一性带父级前缀,但它不是作者身份;`subjectId`+独立保留组件公共 Program 发布的 board、card、item 或 sequence 身份,Companion 只沿这一+身份接回实体。-激活点和末端点必须是 Point,不能再用 `+1f` 或 `-1f` 伪造成 Window。普通 Media、Audio、-Typography 等持续内容仍消费 Window。+这些是公开运行 provenance,不是随机哈希,也不是 Studio metadata。于是同名 Selection 来自+另一份 Script、或 Track 属于另一条时间轴时,会在边界处明确拒绝,不再靠“当前第一个”碰运气。+因此 Script id 在当前 Source closure 中必须唯一;两份不同 Script 声明同一个 id 时,Studio+不会等到逆写时再挑一份。Script Surface 把 `Narrative TypeRef + id` 声明为领域公开身份,+Elaborator 在整个 Source closure 编译期通用去重。编译器不认识 Script 或 Narrative,也不禁止+不同领域、不同父对象中的同名子项。-## 消费层+`TemporalWindow` 由两个完整 Instant 组合而成。两个端点可以有不同来源、不同 authority,+所以 Window 不再伪造一个“共同 source”。`program.end` 是合法 Instant,不再伪装成一帧窗口。+越出 ProgramSpace 的 Instant、反向窗口和零宽窗口直接拒绝,不裁切、不修复。-领域组件只接收已经投影好的 Point/Window 和确实需要的 ProgramSpace。它可以继续拥有真正-的领域算法,例如 Media Sequence handoff、Ranking 非重叠 reveal、素材 occupancy、动画阶段-和音频 sample mapping;但它不再接收 Selection/Moment 后偷偷定位帧。+## 作者模式-消费区间不保证等于投影区间。Deck Card 的可见区间由 activation Point、下一张卡和 terminal-Point 共同决定;Ranking 的 preferred Window 还会被 schedule 变成 active/settled 阶段。-这些关系必须读领域 Programme/Schedule,Studio 不重新实现。+| 写法 | 起点 authority | 终点 authority | 时间线写回 |+|---|---|---|---|+| `during={Selection}` | Selection start | Selection end | Script markers |+| `during={Segment}` / `during="program"` | fixed | fixed | 只读 |+| `at={Moment} for="…"` | Moment cue | parameter `for` | Script 与 SVML 可原子组合写回 |+| `until={Moment} for="…"` | parameter `for` | Moment cue | Script 与 SVML 可原子组合写回 |+| `start="…" end="…"` | `start` | `end` | 组件表面的 SVML 时间参数 |-## Studio 如何取得谱系+点消费用 `at={Moment}` 或 Selection 的明确边界表达语义 authority;没有语义意图时用+`instant="…"` 兜底。`at="moment.cue+3f"` 会被拒绝,因为这种写法没有说清作者想移动+Moment 还是偏移量。-Studio 对本次 Run 选中的每条 Track 做只读索引:+## Studio 如何反写-1. 从该 Track 的实际 BuildPlan selection 出发遍历执行依赖闭包;-2. 找出闭包中真实执行得到的 `TemporalPoint` / `TemporalWindow` 记录;-3. 保留投影 Spec、来源、表达式和精确坐标;-4. 保留直接消费该记录的 Producer、输入端口和同一消费节点的输入值;-5. 由 package-owned adapter 把领域实体连到这条真实消费边。+Studio 从本次 Run 的实际执行闭包读取 `TemporalInstant` / `TemporalWindow` 记录和直接消费边,+再逐端点读取 authority:-因此 Studio 不再通过以下信息猜谱系:+- `semantic` 写回共享 Script 身份;+- `parameter` 点名作者输入,再由编译来源定位它的精确 Source 端点;+- `fixed` 禁止会改变该端点的手势。-- `during/at/selection/moment` 等属性名字;-- `MediaItemSpec` 等硬编码 Spec 类型名;-- 运行时 id 前缀或 renderer id;-- 两个对象恰好相同的帧区间。+因此 `at/for`、`until/for` 可以出现一次手势同时修改 Script 与 SVML。例如拖动 `at/for`+的起点时,Moment 会移动,同时 `for` 会改变以保持终点不动。两处修改属于同一个 revision+事务;重新编译失败时一起回退。-Point 和 Window 在 ABI 与 Inspector 中保持不同:Point 显示 `At`,Window 显示 `From/To`。-链路缺失时保持 unresolved,不用近似规则补齐。+Companion 仍负责实体外观和 Inspector 展示,但不再声明通用时间逆函数。新组件只要消费公共+Instant/Window,并由 Companion 把真实执行谱系连到实体,就自动获得同一套时间行为。-## 写回边界+消费端也不是只读取 `frame`:每个官方组件在接收 Instant/Window 时核对 `subjectId`、+`ProgramSpace.id` 与 `narrativeId`。为此 Space 是运行图上的显式输入边;不通过全局状态、+当前 Film 或 renderer 上下文补猜。-修改语义来源、修改绝对投影端点、修改消费参数仍是不同的作者目标,但 UI 只公开-`timeline.adjust` 与 `parameter.adjust` 两种顶层操作。`timeline.adjust` 根据实体真实记录的 lineage-选择唯一目标:+字幕 Cue 保持独立:`CaptionDocument -> TimedCaptionProjection -> FineCaptionSchedule` 直接从+Semantic token evidence 得到只读 Cue 时间,不伪装成可拖动的 TemporalWindow。两种投影共享+`spaceId / narrativeId / documentId` 的来源校验,但只有 Fine 的 lead、tail、handoff 作为普通+参数允许修改。-- 来源是 Selection:move/trim 修改 Script 中该 Selection 的 Anchor markers,全部消费者一起更新;-- 来源是 Moment:move 修改该 Moment marker,显式 `for` 仍可单独 trim-end;-- 来源是绝对 `start/end`:修改精确的 Window 端点;-- Segment、Program、Schedule 派生阶段或链路缺失:保持只读。+Film 与 Script 的解释也不留在 Studio 核心:`film-studio` 声明 Film 的语义轴和终端 Track+引用规则;`script-studio` 拥有 Script Source map 与 marker 移动。Studio 只选择+`narrativeId` 与当前 ProgramSpace 严格一致的 Script,再把语义修改委托回该 Companion。-这是沿公开身份做逆变换,不是按矩形帧数反推。不能隐式猜测。+这里的 binding 名不是全局地址。Markup 在降低语法时保留作者元素和输入范围,Elaborator+把端点与 Record、Component、Output 一起按 Source unit hygienize;编译结果中的+`AuthorProvenance` 再把运行 authority 精确接回这个端点。Studio 不会在多份 import 中选择+第一个同名的 `start`、output 或本地 id。这份 provenance 每次编译重新产生,不落盘,也不是+lock、哈希清单或项目索引。diff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.mdindex 8dd32434..1ab41bc1 100644--- a/docs/zh/quickstart/script.md+++ b/docs/zh/quickstart/script.md@@ -161,6 +161,11 @@ Selection 是内联声明的具名语义**范围**。每个名字只能有一对`~` 后缀/前缀控制边界是吸附到左边还是右边。默认的打开标记为右吸附;默认的关闭标记为左吸附。+完整 Script 严格拥有 `2M + 2N + 2` 个有序语义锚点:每个 Token 两个、每个 Segment 两个,+再加 Program 自己的首尾。最外侧切口仍用 affinity 区分语义:第一个 Segment 前的 `~@id`+选择 Program start,`@id` 选择首 Segment start;末 Segment 后的 `@/id` 选择末 Segment end,+`@/id~` 选择 Program end。对齐后它们可能落在同一帧,但作者身份并不相同。+### 多个具名 Selection不同名字可以重叠或交叉,但每个名字仍然只有一个区间:diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdindex f511be0b..658c682a 100644--- a/docs/zh/quickstart/tracks.md+++ b/docs/zh/quickstart/tracks.md@@ -291,21 +291,21 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。| 属性 | 取值 ||---|---|| `semantic` | 板据以计时的 SemanticTrack |-| `frame` | 一个 `space:Frame`——对 `Column` 来说是固定的排名轨 |-| `during` | 一个 Selection——板在此期间留在画面上 |+| `frame` | 一个 `space:Frame`——TierBoard/Column 自己的紧凑板子 |+| `during` | TierBoard/Column 接 Segment 或 Selection;TopThree 接 Selection || `style` | 对应的样式记录,且只接受本变体的 |-| `terminal` | 完整板定格的 Moment。仅 `TierBoard` 与 `TopThree` |-| `canvas` | 一个 `space:Canvas`——揭示舞台。仅 `Column` |+| `terminal` | 完整板定格的 Moment。仅 `TopThree` |+| `canvas` | 一个 `space:Canvas`——独立揭示舞台。TierBoard/Column || `appear-sound`、`move-sound` | 可选,Synchronized Media |-`move-sound` 在 `TopThree` 上会被拒绝——它没有移动阶段。在 `TierBoard` 上它要求至少有一个 `entry="stage"` 的条目:声音没有可响之处是创作错误,而不是静默的空操作。+TierBoard 与 Column 都不使用 `terminal`:每个非 preset item 直接消费一个 `during` Selection,所有窗口必须位于外层区间内且互不相交。`move-sound` 在 `TopThree` 上会被拒绝;在 `TierBoard` 上它要求至少有一个 `entry="drop"` 的条目。drop 条目会在 Selection 开始时原地弹入独立的 Canvas 舞台,整段讲解期间保持静止,只在窗口末尾的 `move-frames` 内沿缓动弧线滑入 tier;移动音效也从这里开始。### 条目标签每个变体只接受自己的那一种,至少一个,且 id 在同一块板内不可重复。-- **`TierItem`** —— `tier`、`icon` 与 item 自己的 `at={story.moment...}` 必填,可选 `entry="direct" | "stage"` 与 `stack`。行的文字来自 recipe,不写在标签上。-- **`TopThreeItem`** —— `label` 与 item 自己的 `at={story.moment...}` 必填,可选 `icon` 与 `stack`,最多三条。TierBoard 与 TopThree 的揭示顺序由这些 Moment 的真实帧顺序决定。+- **`TierItem`** —— `tier` 与 `icon` 必填。非 preset item 用自己的 `during` Selection,并必须显式选择 `entry="direct" | "drop"`;`preset="true"` 不写 `during` 和 `entry`。preset 先占内侧,随后严格按窗口顺序向外填充。两种模式都用快速的原地放大回弹入场;direct 在最终格出现,drop 在独立舞台讲解完整窗口后才归入 tier。行文字来自 recipe。+- **`TopThreeItem`** —— `label` 与 item 自己的 `at={story.moment...}` 必填,可选 `icon` 与 `stack`,最多三条。揭示顺序由这些 Moment 的真实帧顺序决定。- **`ColumnItem`** —— `label` 与 `rank` 必填,可选 `icon` 与 `stack`。非 preset item 用自己的 `during` Selection;`preset="true"` 的 item 开场已在位且不写 `during`。```svml