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.

docs: describe semantic Studio writeback

kashorin9d8c4bbc1dd4
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 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.md
index 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. Those
remain 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.md
index 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.md
index 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 is
right-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 Selections
Different names may overlap or cross. Each name still has exactly one interval:
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 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 tags
Each 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 the
numbered 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, and
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index 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 绝不授予网络、文件系统、进程、凭据或队列权限;这些权限只属于 Runtime
Profile 显式选择的包。
diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.md
index 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.md
index 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.md
index 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