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.

refactor: preserve temporal points through studio lineage

kashorin88a78d9c8f50
diff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.md
index dbce4fac..8eafe1c7 100644
--- a/docs/guide/studio-temporal-windows.md
+++ b/docs/guide/studio-temporal-windows.md
@@ -1,19 +1,20 @@
---
-title: Studio Temporal Windows
-description: Open design note for displaying authored, projected and consumed time in Hypit Studio.
+title: Studio Temporal Lineage
+description: How Hypit Studio reads authored, projected and consumed time without reconstructing it.
---
-# Studio Temporal Windows
+# Studio Temporal Lineage
-> Status: the read-only presentation is decided and being implemented. Timeline writeback remains
-> open. This does not define a new Core protocol.
+> 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 windows
+## The three layers
### 1. Selection window
@@ -27,16 +28,18 @@ The selection window is the semantic source chosen by the author. It retains:
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.
-### 2. Projection 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 projected window when it resolves. A component can combine the
-projected windows of several authored children, such as computing disjoint reveal intervals. That
-relation belongs to the component's public programme or schedule, not to a Studio guess.
+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
@@ -59,7 +62,7 @@ Studio eventually needs a lossless chain with explicit identities:
```text
author element
-> semantic binding (kind, source id, author range)
- -> projection expression and projected window
+ -> projection expression and projected Point/Window
-> consumed entity and consumed window(s)
-> terminal visual/audio realization
```
@@ -68,10 +71,11 @@ The links matter more than coincident frame numbers. Several Tracks may consume
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.
-The current Studio adapter registry is the right local place to interpret this chain. Domain
-packages remain unaware of Studio. Adapters should reuse author observations and the public values
-already emitted by Narrative, Temporal and each Track family. If a required link is not observable,
-Studio should call it unresolved rather than infer it from ids, labels or equal spans.
+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 questions that remain deliberately open
@@ -88,5 +92,7 @@ Before any drag or trim writeback is enabled, the product design must decide:
6. Which drag gesture owns which level. Moving a semantic source, changing a projection offset and
trimming a consumption window are different edits and must never be silently substituted.
-Until these questions are answered, timeline entities remain selectable and seekable but read-only.
-The rule is simple: difficulty is acceptable; implicit guessing is not.
+Direct absolute endpoints and authored durations may be rewritten when their exact source range is
+known. Selection/Moment bindings remain read-only from the downstream rectangle: editing a semantic
+source, changing a projection expression and changing a consumption parameter are distinct
+operations. The rule is simple: difficulty is acceptable; implicit guessing is not.
diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.md
index 784fd814..4fb2605a 100644
--- a/docs/zh/guide/studio-temporal-windows.md
+++ b/docs/zh/guide/studio-temporal-windows.md
@@ -1,206 +1,77 @@
---
-title: Studio 三窗口
-description: Studio 如何显式呈现选择、投影与消费窗口的待设计记录。
+title: Studio 时间谱系
+description: Studio 如何沿真实执行图呈现选择、投影与消费,而不反向猜测。
---
-# Studio 三窗口
+# Studio 时间谱系
-> 状态:只读呈现已经定案并开始实现;回写交互仍待讨论,不因此新增 Core 协议。
+> 状态:Temporal Point/Window 的只读谱系已经接通。只有存在唯一源码逆像的编辑才允许写回;
+> 跨层自动反推仍被禁止。这不新增 Core 协议。
-时间线上的 item 并不只是一个起止帧矩形。绝大多数 Track 先引用 Selection、Segment 或
-Moment,再把它投影到帧空间,最后才由画面、声音、动画或组件内部 schedule 消费。Studio
-必须保留这三个层级,不能压平后靠相同帧数、字符串 id 或组件名字猜回去。
-
-## 关键边界:选择与投影先于领域组件
-
-选择和投影不是组件内部偷偷完成的副作用,而是进入领域组件之前的通用前置阶段:
+时间线 item 并不只是一个起止帧矩形。大多数 Track 先选择 Program、Selection、Segment 或
+Moment,再把它投影进帧空间,最后由领域组件消费。Studio 保留这三个层级:
```text
-SVML 作者表达式
- -> Temporal Projection(来源、表达式、投影帧窗)
- -> 领域组件(Media / Text / Caption / Ranking ...)
- -> 组件自己的消费窗口与 schedule
+作者选择层(Program / Selection / Segment / Moment)
+ -> 投影层(TemporalPoint / TemporalWindow)
+ -> 消费层(Item 生命周期、Sequence、Ranking Schedule、Track)
```
-“出现在 SVML 里”指作者在 SVML 中声明来源和投影表达式,例如
-`during={story.selection.demo}`、`at={story.moment.reveal} for="12f"` 或
-`start="selection.start+3f"`;并不要求作者手写最终帧数。组件收到的是已经确定的投影结果,
-因此组件不需要猜 Selection、Moment 到底对应什么,也不需要把最终矩形反推成语义来源。
-
-这解决的是根本的边界混淆,但不抹掉组件自己的领域逻辑:例如 Ranking 仍可以在投影结果
-之上计算互不重叠的 reveal schedule,Media Sequence 仍可以计算 handoff。那是消费阶段的
-公开领域事实,不是组件重新解释 Selection/Projection。
-
-当前代码已经有这条概念边界:SVML 的时间表达式、`@hypit/temporal` 的投影能力和各领域
-的 programme/schedule 是分开的;部分 lowering 仍在领域函数内部直接调用 temporal helper,
-这属于实现边界尚未收紧的技术债,不应被当成作者语义被组件偷偷决定。后续应把 Projection
-作为显式的图中间值传入组件,并让 Studio 与组件消费同一份值。
-
-## 实现审计:目前哪些地方仍把投影隐藏在组件里
-
-### 根因
-
-`@hypit/temporal` 当前只是一个 TypeScript 算法库。它的模块清单没有声明任何 Type 或
-Producer,因此运行图里不可能出现一个 Temporal Projection 节点。领域 Surface 虽然把
-`during`、`at/for`、`start/end` 写在 SVML 中,lowering 后却仍然把:
-
-```text
-SemanticTrack + Selection/Segment/Moment + projection spec
-```
-
-一起交给领域 Producer,再由该 Producer 内部调用 `projectSelectionWindow()`、
-`projectMomentWindow()`、`projectSegmentWindow()` 或语义定位函数。作者语法是显式的,
-但图上的选择/投影步骤仍是隐藏的。
-
-`ProjectedWindow` 本身也只有拼接出的 `id` 和最终 `span`,没有公开来源种类、来源 id、
-端点表达式。各领域 Program 随后通常只保存最终 `span/window`。因此运行结果不能
-单独解释自己的三窗口谱系。
-
-### 完全隐藏的领域链路
-
-| 领域 | 当前隐藏方式 | 应显式前置的值 |
-|---|---|---|
-| Media Item | `appendProgram/Selection/Segment/MomentMediaItem` 内部执行窗口投影 | 一个 Projected Window |
-| Media Sequence | Member activation 和 terminal 在 Sequence 内部直接定位 Moment/Selection | Projected Point / Boundary |
-| Audio Clip | `appendProgram/Selection/MomentAudioItem` 内部执行窗口投影 | 一个 Projected Window |
-| Typography Item | `appendProgram/Selection/MomentTextItem` 内部执行窗口投影 | 一个 Projected Window |
-| Comment Sticker | 各种 append Producer 内部投影 | 一个 Projected Window |
-| Screen Overlay | 各种 append Producer 内部投影 | 一个 Projected Window |
-| Depth Stack | Card activation、terminal Moment/Selection 在组件内直接定位 | Projected Points / Boundary |
-
-这些包还分别复制了时间字符串解析与 binding 分支。Media、Audio、Typography、Comment
-Sticker、Screen Overlay 都各自实现了 duration、point、`during/at/start/end` 解析。这不只是
-代码重复,也让“时间语言属于谁”变得含糊。
-
-### Ranking 的特殊情况
-
-Column 已经比其他组件更接近正确形状:Fragment 中有独立的 outer-window、candidate 和
-schedule 操作。但是 outer 与 candidate 的投影 Producer 仍属于 Ranking,仍接收
-`SemanticTrack + Selection/Segment` 后在内部调用 Temporal。它们应改为通用 Temporal 输出;
-Ranking 只保留候选避让、clamp、非重叠 active window 和 settled phase 的 Schedule。
-
-TierBoard 与 TopThree 已不再使用一个重复 Moment:每个 Item 各自绑定一个 Moment,Ranking
-先收集 item-owned trigger candidate,再按真实帧顺序排程。outer window、每个 item point、
-terminal point 后续仍应先由 Temporal 显式产出,再进入 Ranking Schedule。
-
-### ProgramSpace 的同类隐藏
+## 选择层
-`SemanticTrack -> ProgramSpace` 已经有正式的 `semantic-track:project-program-space` Producer,
-但 Media、Audio、Typography、Ranking、Deck、Film 等 Producer 仍经常接收 SemanticTrack,
-在 handler 内直接调用 `projectSemanticProgramSpace()`。这不是 Selection Projection 本身,
-却是同一种边界问题:已有图节点没有被连接,确定性转换被藏进消费者。只需要帧域的消费者
-应直接接收 ProgramSpace;确实要读取词或 Anchor 的算法才接收 SemanticTrack。
+选择层保留来源种类与规范身份。Moment 是语义点,Selection/Segment 是语义区间;坐标相同
+不表示身份相同。SVML 的 `during`、`at`、`until` 等属性只负责声明作者选择,不直接变成
+领域组件中的找帧逻辑。
-### Studio 目前被迫做的反向拼接
+## 投影层
-由于没有显式 Projection 值,Studio adapter 当前只能:
+Surface lowering 生成 `TemporalPointSpec` 或 `TemporalWindowSpec`,再连接正式 Temporal
+Producer。投影结果保留来源身份、作者表达式与解析后的帧坐标:
-1. 用 Program item 的运行时 id 前缀匹配作者 child id;
-2. 只识别 `MediaItemSpec`、`TextItemSpec`、`PlainTextItemSpec` 等硬编码类型名;
-3. 从 `during/selection/segment/at/moment` 属性名与引用 Type 猜来源种类;
-4. 从 Spec 中补回表达式,从 Program 的 span 中补回最终帧;
-5. Ranking adapter 再单独写一套类似的拼接。
+- `TemporalPoint` 表示一个合法帧边界,范围是 `[0, frameCount]`;`program.end` 可以精确落在
+ `frameCount`。
+- `TemporalWindow` 表示一个非空半开区间 `[startFrame, endFrameExclusive)`。
-它没有重新计算 Temporal,但仍在重建一个本该直接存在的身份链。这正是“投影被隐藏”的可见
-症状:新增一个 Track family 后,Studio 无法自然理解它,必须再写一段领域猜测代码。
+激活点和末端点必须是 Point,不能再用 `+1f` 或 `-1f` 伪造成 Window。普通 Media、Audio、
+Typography 等持续内容仍消费 Window。
-### 不应误迁走的领域逻辑
+## 消费层
-下面这些发生在显式 Projection 之后,仍应由领域组件拥有:
+领域组件只接收已经投影好的 Point/Window 和确实需要的 ProgramSpace。它可以继续拥有真正
+的领域算法,例如 Media Sequence handoff、Ranking 非重叠 reveal、素材 occupancy、动画阶段
+和音频 sample mapping;但它不再接收 Selection/Moment 后偷偷定位帧。
-- Ranking 的候选避让、非重叠 active window、preset 和 settled phase;
-- Media Sequence 的相邻成员关系、handoff、transition 和 source occupancy;
-- Audio 的 source trim、loop/stretch、gain、fade 与 sample mapping;
-- Motion 的 enter/body/exit 生命周期;
-- Caption 的 Cue 分组、Atom 对应和显示策略。
+消费区间不保证等于投影区间。Deck Card 的可见区间由 activation Point、下一张卡和 terminal
+Point 共同决定;Ranking 的 preferred Window 还会被 schedule 变成 active/settled 阶段。
+这些关系必须读领域 Programme/Schedule,Studio 不重新实现。
-Caption Fine 已经提供了一个接近目标的正例:Fragment 先执行
-`caption:temporalize-plan`,得到具名 `TimedCaptionProjection`,随后 renderer 才消费它。
-它的 Atom/Cue 时间连接是 Caption 领域语义,因此可以由 Caption 拥有;关键是连接结果已经
-作为显式图值存在,而不是藏在 renderer 内。
+## Studio 如何取得谱系
-Speech 也不是这次迁移的对象。SemanticTake 已经自带局部词窗和 Anchor,Speech Track 负责
-拼装 SemanticTrack 并投影视听同源 facet;它不是某个 Selection/Moment 到组件窗口的隐式投影。
+Studio 对本次 Run 选中的每条 Track 做只读索引:
-### 收紧后的目标形状
+1. 从该 Track 的实际 BuildPlan selection 出发遍历执行依赖闭包;
+2. 找出闭包中真实执行得到的 `TemporalPoint` / `TemporalWindow` 记录;
+3. 保留投影 Spec、来源、表达式和精确坐标;
+4. 保留直接消费该记录的 Producer、输入端口和同一消费节点的输入值;
+5. 由 package-owned adapter 把领域实体连到这条真实消费边。
-不要求把 SVML 写得冗长。`during`、`at/for`、`start/end` 仍可作为组件标签上的语法糖,
-但 Surface lowering 必须先生成通用 Temporal 图操作,再把它的输出接入领域组件:
+因此 Studio 不再通过以下信息猜谱系:
-```text
-SVML timing sugar
- -> Temporal projection spec + semantic source reference
- -> temporal:project-* Producer
- -> Projected Window/Point value
- -> domain append/build Producer
-```
-
-Projected 值至少必须让消费方与 Studio 观察到:作者实体 id、来源种类与 id、
-端点表达式、最终帧窗。它们是 Projection 自身的定义和实际输入,不是随链路传播的“质量”元信息。
-领域 Program 不必复制一份;Studio 应沿真实图边读取同一个 Temporal 输出,避免双重真相。
-
-## 一、选择窗口
-
-这是作者选中的语义来源,需要保留来源种类、规范 id、Semantic Track 上的 Anchor,以及
-引用它的 SVML 源码范围。Selection 恰好是一个连续区间,Moment 恰好是一个点。两个来源
-落在相同帧上,不代表它们是同一件事。
-
-## 二、投影窗口
-
-这是 Track 把一个语义来源按时间表达式投进帧空间后的结果。例如完整使用
-Selection、从 Moment 前三帧开始,或从 `segment.start + 2s` 到 `segment.end`。它包括
-offset 计算、Program Space 裁切与帧量化。
-
-一个可解析的作者绑定产出一个投影窗口;组件也可能组合多个子 item 的投影窗口并施加关系,
-例如算出互不重叠的 Ranking reveal。关系必须来自领域组件公开的 programme/schedule,
-不能由 Studio 重新实现。
-
-## 三、消费窗口
-
-这是最终 Track 实际使用的窗口。它可能与投影窗口相同,但不能预设相同:Media Sequence
-同时有 logical span、visual span 与 handoff;源音频有 source trim 和 target window;
-Ranking 有一个外层窗口和多个内部 reveal;进入、持续、退出动画也会消费生命周期的不同
-部分。Studio 应读取领域 programme、schedule、Visual Track 或 Audio Track 公开的事实,
-不能从渲染 id 猜。
-
-## 时间线呈现约定
-
-三者是时间谱系的三层,不保证都是区间。Semantic Lane 始终显示语义来源:Selection 和
-Segment 是括号区间,Moment 是精确时间点。每个 Track 的作者 item 仍用实心块表达实际
-消费;它的顶部用空心细线表达投影窗口。投影与消费完全重合时也保留细线,不能因此抹掉
-恒等投影。选中 item 后,Semantic Lane 会强调它绑定的来源。
-
-组件内部 schedule 不制造额外 Track item。Ranking Column 的整个 Column 是父 item;每个
-ColumnItem 是子 item,`preferred` 显示为投影线,`active` 和 `settled` 显示为同一子 item
-底部的阶段条。Preset 没有独立语义投影,明确标记为由父 schedule 派生。
-
-投影端点必须逐个保留原表达式,例如 `selection.start+3f` 和 `selection.end+3f`,不能在
-Studio 中概括成一次“整体平移”。Program 给出解析后的帧窗口,Surface 真正封存的 Spec
-给出端点表达式;Studio adapter 只把它们按作者实体重新组合,不重新执行 Temporal。
-
-## 必须保留的身份链
-
-```text
-作者元素
- -> 语义绑定(种类、来源 id、源码范围)
- -> 投影表达式与投影窗口
- -> 消费实体与消费窗口
- -> 最终画面/声音实现
-```
+- `during/at/selection/moment` 等属性名字;
+- `MediaItemSpec` 等硬编码 Spec 类型名;
+- 运行时 id 前缀或 renderer id;
+- 两个对象恰好相同的帧区间。
-多个 Track 可以共享同一个 Selection;一个投影可以生成同源的 visual/audio facet;一个
-组件的外层投影也可以展开成多个内部消费窗口。它们是共享绑定和投影,不是若干恰好重叠
-的 clip。
+Point 和 Window 在 ABI 与 Inspector 中保持不同:Point 显示 `At`,Window 显示 `From/To`。
+链路缺失时保持 unresolved,不用近似规则补齐。
-Studio adapter registry 是解释这条链的本地中心。领域包和 Core 不认识 Studio;adapter
-复用 Narrative、Temporal 和 Track family 已公开的值。如果链上某一环不可观察,就明确
-显示 unresolved,绝不通过名称或相同 span 补猜。
+## 写回边界
-## 回写前必须显式讨论的问题
+修改语义来源、修改投影表达式、修改消费参数是三种不同操作,不能互相替代。当前规则是:
-1. 共享 Selection 如何展示所有消费者及修改影响范围。
-2. Inspector 如何在语义来源、投影窗口、消费实体和最终 realization 之间切换。
-3. 每种拖动到底修改哪一层:移动语义来源、修改 projection offset、裁切消费窗口是三种
- 不同操作,严禁相互替代。
+- 作者直接写下、且 Studio 持有唯一源码范围的绝对 `start/end` 可以移动或裁切;
+- `at + for` 只允许修改明确的 duration;
+- Selection/Moment 引用产生的下游矩形不能自动反推并移动语义来源;
+- 修改共享语义来源必须作为独立的语义层操作展示影响范围,不能伪装成普通 clip drag。
-这些问题定案前,时间线可以选中、定位,但保持只读。可以难,不能隐式猜。
+可以暂时只读,不能隐式猜测。
diff --git a/packages/deck-track/README.md b/packages/deck-track/README.md
index 6e38b84d..a67f79bf 100644
--- a/packages/deck-track/README.md
+++ b/packages/deck-track/README.md
@@ -35,6 +35,10 @@ silently depend on renderer playback history.
Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs and
media metadata are never treated as label truth.
+The Surface projects every Card `at` and the deck terminal to `TemporalPoint` values before the
+Deck component runs. Card append and finalization consume those Points directly; they never locate
+a Moment/Selection or manufacture a one-frame terminal Window internally.
+
`deck:Label` accepts either literal body copy or `content={Text}`. It binds that copy to exact font
and label appearance in a small explicit Fragment. The Deck Track receives the resulting label as
one normal edge; it never reads filenames, URLs or hidden media metadata.
diff --git a/packages/deck-track/src/component.ts b/packages/deck-track/src/component.ts
index 1c92c9a3..380f0439 100644
--- a/packages/deck-track/src/component.ts
+++ b/packages/deck-track/src/component.ts
@@ -1,16 +1,15 @@
import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-import type { SemanticTrack } from "@hypit/semantic-track";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
+import type { ProgramSpace } from "@hypit/program-space";
import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint } from "@hypit/temporal";
import type { MediaLayerSet } from "@hypit/media-track";
import type { Text } from "@hypit/text";
import { renderDepthStack } from "./lower.js";
import { depthStackProducers, depthStackTypes } from "./manifest.js";
-import { appendDepthStackProjectedCard, assertDepthStackProgram, createDepthStackCardSet, finalizeDepthStackAtWindow, bindDepthStackCardLabelText } from "./program.js";
+import { appendDepthStackCard, assertDepthStackProgram, createDepthStackCardSet, finalizeDepthStack, bindDepthStackCardLabelText } from "./program.js";
import type {
DepthStackCardLabel,
DepthStackCardLabelStyle,
@@ -33,7 +32,7 @@ function finalizeInputs(inputs: ProducerHandlerContext["inputs"]) {
header: inline<DepthStackHeader>(inputs.header?.value, "DepthStackHeader"),
frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
spec: inline<DepthStackSpec>(inputs.spec?.value, "DepthStackSpec"),
- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
};
}
@@ -52,50 +51,29 @@ export const depthStackComponent = {
},
{
producer: depthStackProducers.appendCard,
- handler: ({ inputs }) => ({ outputs: { set: output(appendDepthStackProjectedCard(
+ handler: ({ inputs }) => ({ outputs: { set: output(appendDepthStackCard(
inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),
inline<MediaLayerSet>(inputs.material?.value, "MediaLayerSet"),
inline<DepthStackCardLabel>(inputs.label?.value, "DepthStackCardLabel"),
inline<DepthStackCardSpec>(inputs.spec?.value, "DepthStackCardSpec"),
- inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),
)) }, needs: {} }),
},
{
- producer: depthStackProducers.finalizeProgramEnd,
+ producer: depthStackProducers.finalize,
handler: ({ inputs }) => {
const value = finalizeInputs(inputs);
- return { outputs: { program: output(finalizeDepthStackAtWindow(
+ return { outputs: { program: output(finalizeDepthStack(
value.set, value.header, value.frame, value.spec,
- inline<TemporalWindow>(inputs.terminal?.value, "TemporalWindow"), value.semantic, "end",
+ inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"), value.space,
)) }, needs: {} };
},
},
- {
- producer: depthStackProducers.finalizeUntilMoment,
- handler: ({ inputs }) => {
- const value = finalizeInputs(inputs);
- return { outputs: { program: output(finalizeDepthStackAtWindow(
- value.set, value.header, value.frame, value.spec,
- inline<TemporalWindow>(inputs.terminal?.value, "TemporalWindow"), value.semantic, "start",
- )) }, needs: {} };
- },
- },
- ...([depthStackProducers.finalizeUntilSelectionStart, depthStackProducers.finalizeUntilSelectionEnd] as const)
- .map((producer) => ({
- producer,
- handler: ({ inputs }: ProducerHandlerContext) => {
- const value = finalizeInputs(inputs);
- return { outputs: { program: output(finalizeDepthStackAtWindow(
- value.set, value.header, value.frame, value.spec,
- inline<TemporalWindow>(inputs.terminal?.value, "TemporalWindow"), value.semantic, "start",
- )) }, needs: {} };
- },
- })),
{
producer: depthStackProducers.render,
handler: ({ inputs }) => ({ outputs: { track: output(renderDepthStack(
inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
inline<DepthStackProgram>(inputs.program?.value, "DepthStackProgram"),
)) }, needs: {} }),
},
diff --git a/packages/deck-track/src/fragment.ts b/packages/deck-track/src/fragment.ts
index e8ea1cc6..c333de06 100644
--- a/packages/deck-track/src/fragment.ts
+++ b/packages/deck-track/src/fragment.ts
@@ -5,7 +5,7 @@ import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
import { mediaTypes } from "@hypit/media";
import { mediaTrackProducers, mediaTrackTypes } from "@hypit/media-track";
import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialTypes } from "@hypit/spatial";
import { temporalProducers, temporalTypes } from "@hypit/temporal";
@@ -25,7 +25,7 @@ export type DepthStackFragmentCard = {
readonly labelName: string;
readonly cardSpecName: string;
readonly momentName: string;
- readonly windowSpecName: string;
+ readonly pointSpecName: string;
};
export type DepthStackFragmentTerminal =
@@ -67,7 +67,7 @@ export function createDepthStackFragment(
{ name: card.labelName, type: depthStackTypes.cardLabel },
{ name: card.cardSpecName, type: depthStackTypes.cardSpec },
{ name: card.momentName, type: narrativeTypes.moment },
- { name: card.windowSpecName, type: temporalTypes.windowSpec },
+ { name: card.pointSpecName, type: temporalTypes.pointSpec },
);
if (card.framePaintSpecName !== undefined) {
inputs.push({ name: card.framePaintSpecName, type: mediaTrackTypes.paintLayerSpec });
@@ -107,12 +107,12 @@ export function createDepthStackFragment(
result: { kind: "output", name: "layers" },
});
const appendId = `append-${card.suffix}`;
- const windowId = `window-${card.suffix}`;
+ const pointId = `point-${card.suffix}`;
operations.push({
- id: windowId,
- producer: temporalProducers.projectMoment,
- inputs: { semantic: input("semantic"), moment: input(card.momentName), spec: input(card.windowSpecName) },
- result: { kind: "output", name: "window" },
+ id: pointId,
+ producer: temporalProducers.projectMomentPoint,
+ inputs: { semantic: input("semantic"), moment: input(card.momentName), spec: input(card.pointSpecName) },
+ result: { kind: "output", name: "point" },
});
operations.push({
id: appendId,
@@ -122,54 +122,55 @@ export function createDepthStackFragment(
material: operation(sampleId),
label: input(card.labelName),
spec: input(card.cardSpecName),
- window: operation(windowId),
+ activation: operation(pointId),
},
result: { kind: "output", name: "set" },
});
cardSet = operation(appendId);
}
- const terminalProducer = terminal.kind === "program-end"
- ? depthStackProducers.finalizeProgramEnd
- : terminal.kind === "moment" ? depthStackProducers.finalizeUntilMoment
- : terminal.kind === "selection-start" ? depthStackProducers.finalizeUntilSelectionStart
- : depthStackProducers.finalizeUntilSelectionEnd;
if (terminal.kind !== "program-end") {
inputs.push({
name: terminal.inputName,
type: terminal.kind === "moment" ? narrativeTypes.moment : narrativeTypes.selection,
});
- inputs.push({ name: terminal.specName, type: temporalTypes.windowSpec });
+ inputs.push({ name: terminal.specName, type: temporalTypes.pointSpec });
}
- const terminalWindow = terminal.kind === "program-end" ? "program-window" : "terminal-window";
+ const terminalPoint = terminal.kind === "program-end" ? "program-point" : "terminal-point";
if (terminal.kind === "program-end") {
- inputs.push({ name: "program-spec", type: temporalTypes.windowSpec });
- operations.push({ id: terminalWindow, producer: temporalProducers.projectProgram,
- inputs: { semantic: input("semantic"), spec: input("program-spec") }, result: { kind: "output", name: "window" } });
+ inputs.push({ name: "program-spec", type: temporalTypes.pointSpec });
+ operations.push({ id: terminalPoint, producer: temporalProducers.projectProgramPoint,
+ inputs: { semantic: input("semantic"), spec: input("program-spec") }, result: { kind: "output", name: "point" } });
} else {
- operations.push({ id: terminalWindow,
- producer: terminal.kind === "moment" ? temporalProducers.projectMoment : temporalProducers.projectSelection,
+ operations.push({ id: terminalPoint,
+ producer: terminal.kind === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint,
inputs: {
semantic: input("semantic"), spec: input(terminal.specName),
[terminal.kind === "moment" ? "moment" : "selection"]: input(terminal.inputName),
- }, result: { kind: "output", name: "window" } });
+ }, result: { kind: "output", name: "point" } });
}
+ operations.push({
+ id: "space",
+ producer: semanticTrackProducers.projectProgramSpace,
+ inputs: { track: input("semantic") },
+ result: { kind: "output", name: "space" },
+ });
operations.push({
id: "program",
- producer: terminalProducer,
+ producer: depthStackProducers.finalize,
inputs: {
set: cardSet,
header: input("header"),
frame: input("frame"),
spec: input("spec"),
- semantic: input("semantic"),
- terminal: operation(terminalWindow),
+ space: operation("space"),
+ terminal: operation(terminalPoint),
},
result: { kind: "output", name: "program" },
});
operations.push({
id: "track",
producer: depthStackProducers.render,
- inputs: { canvas: input("canvas"), semantic: input("semantic"), program: operation("program") },
+ inputs: { canvas: input("canvas"), space: operation("space"), program: operation("program") },
result: { kind: "output", name: "track" },
});
return sealGraphFragment({
diff --git a/packages/deck-track/src/index.ts b/packages/deck-track/src/index.ts
index d623b13d..1794f603 100644
--- a/packages/deck-track/src/index.ts
+++ b/packages/deck-track/src/index.ts
@@ -12,5 +12,5 @@ export {
} from "./surface.js";
export { renderDepthStack } from "./lower.js";
export { depthStackCardLabelSchema, depthStackCardLabelStyleSchema, depthStackCardSetSchema, depthStackCardSpecSchema, depthStackDependency, depthStackHeaderSchema, depthStackManifest, depthStackMarkupSurfaces, depthStackModuleRef, depthStackProducers, depthStackProgramSchema, depthStackSpecSchema, depthStackTypes } from "./manifest.js";
-export { appendDepthStackProjectedCard, assertDepthStackCardLabel, assertDepthStackCardLabelStyle, assertDepthStackCardSet, assertDepthStackCardSpec, assertDepthStackHeader, assertDepthStackProgram, assertDepthStackProgramIdentity, assertDepthStackSpec, createDepthStackCardSet, finalizeDepthStackAtWindow, noDepthStackCardLabel, resolveDepthStackPose, resolveDepthStackState, sealDepthStackCardLabel, sealDepthStackCardLabelStyle, bindDepthStackCardLabelText, sealDepthStackCardSpec, sealDepthStackHeader, sealDepthStackSpec } from "./program.js";
+export { appendDepthStackCard, assertDepthStackCardLabel, assertDepthStackCardLabelStyle, assertDepthStackCardSet, assertDepthStackCardSpec, assertDepthStackHeader, assertDepthStackProgram, assertDepthStackProgramIdentity, assertDepthStackSpec, createDepthStackCardSet, finalizeDepthStack, noDepthStackCardLabel, resolveDepthStackPose, resolveDepthStackState, sealDepthStackCardLabel, sealDepthStackCardLabelStyle, bindDepthStackCardLabelText, sealDepthStackCardSpec, sealDepthStackHeader, sealDepthStackSpec } from "./program.js";
export type * from "./types.js";
diff --git a/packages/deck-track/src/manifest.ts b/packages/deck-track/src/manifest.ts
index 5cb35fdc..2ebdd894 100644
--- a/packages/deck-track/src/manifest.ts
+++ b/packages/deck-track/src/manifest.ts
@@ -18,6 +18,7 @@ import {
mediaTrackTypes,
} from "@hypit/media-track";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
@@ -44,10 +45,7 @@ export const depthStackTypes = {
export const depthStackProducers = {
createCards: { module: depthStackModuleRef, name: "create-depth-stack-card-set" },
appendCard: { module: depthStackModuleRef, name: "append-depth-stack-card" },
- finalizeProgramEnd: { module: depthStackModuleRef, name: "finalize-depth-stack-at-program-end" },
- finalizeUntilMoment: { module: depthStackModuleRef, name: "finalize-depth-stack-until-moment" },
- finalizeUntilSelectionStart: { module: depthStackModuleRef, name: "finalize-depth-stack-until-selection-start" },
- finalizeUntilSelectionEnd: { module: depthStackModuleRef, name: "finalize-depth-stack-until-selection-end" },
+ finalize: { module: depthStackModuleRef, name: "finalize-depth-stack" },
render: { module: depthStackModuleRef, name: "render-depth-stack" },
bindLabelText: { module: depthStackModuleRef, name: "bind-depth-stack-label-text" },
} satisfies Record<string, ProducerRef>;
@@ -118,7 +116,7 @@ export const depthStackProgramSchema: ValueSchema = object({
const finalizeInputs = [
{ name: "set", type: depthStackTypes.cardSet }, { name: "header", type: depthStackTypes.header },
{ name: "frame", type: spatialTypes.frame }, { name: "spec", type: depthStackTypes.spec },
- { name: "semantic", type: semanticTrackTypes.track },
+ { name: "space", type: programSpaceTypes.programSpace },
] as const;
export const depthStackMarkupSurfaces = [
@@ -159,7 +157,7 @@ export const depthStackMarkupSurfaces = [
depthStackTypes.header, depthStackTypes.spec, depthStackTypes.cardSpec,
spatialTypes.fit, mediaTrackTypes.sampleLayerSpec, mediaTrackTypes.paintLayerSpec,
depthStackTypes.cardLabel, depthStackTypes.cardLabelStyle, textTypes.text,
- temporalTypes.windowSpec,
+ temporalTypes.pointSpec,
depthStackTypes.program, compositionTypes.visualTrack,
],
vocabulary: {
@@ -410,7 +408,7 @@ export const depthStackMarkupSurfaces = [
export const depthStackManifest: ModuleManifest = {
format: "hypit.module@1", name: depthStackModuleRef.name, version: depthStackModuleRef.version,
- dependencies: [narrativeDependency, semanticTrackDependency, spatialDependency, temporalDependency, mediaDependency, mediaTrackDependency, compositionDependency, textDependency],
+ dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, mediaDependency, mediaTrackDependency, compositionDependency, textDependency],
types: [
{ name: depthStackTypes.header.name },
{ name: depthStackTypes.spec.name },
@@ -426,19 +424,13 @@ export const depthStackManifest: ModuleManifest = {
{ name: depthStackProducers.appendCard.name, inputs: [
{ name: "set", type: depthStackTypes.cardSet }, { name: "material", type: mediaTrackTypes.layerSet },
{ name: "label", type: depthStackTypes.cardLabel }, { name: "spec", type: depthStackTypes.cardSpec },
- { name: "window", type: temporalTypes.window },
+ { name: "activation", type: temporalTypes.point },
], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [] },
- { name: depthStackProducers.finalizeProgramEnd.name, inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.window }], outputs: [{ name: "program", type: depthStackTypes.program }], needs: [] },
- ...([
- [depthStackProducers.finalizeUntilMoment, narrativeTypes.moment],
- [depthStackProducers.finalizeUntilSelectionStart, narrativeTypes.selection],
- [depthStackProducers.finalizeUntilSelectionEnd, narrativeTypes.selection],
- ] as const).map(([producer, terminalType]) => ({
- name: producer.name, inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.window }],
- outputs: [{ name: "program", type: depthStackTypes.program }], needs: [],
- })),
+ { name: depthStackProducers.finalize.name,
+ inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.point }],
+ outputs: [{ name: "program", type: depthStackTypes.program }], needs: [] },
{ name: depthStackProducers.render.name, inputs: [
- { name: "canvas", type: spatialTypes.canvas }, { name: "semantic", type: semanticTrackTypes.track },
+ { name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace },
{ name: "program", type: depthStackTypes.program },
], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
],
diff --git a/packages/deck-track/src/program.ts b/packages/deck-track/src/program.ts
index 9291fd75..e745185a 100644
--- a/packages/deck-track/src/program.ts
+++ b/packages/deck-track/src/program.ts
@@ -14,11 +14,9 @@ import type { ProgramSpace } from "@hypit/program-space";
import { canonicalize } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
-import type { SemanticTrack } from "@hypit/semantic-track";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
import { assertSpatialFrame } from "@hypit/spatial";
import type { SpatialFrame } from "@hypit/spatial";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint } from "@hypit/temporal";
import type {
DeckCardTone,
@@ -228,15 +226,14 @@ function appendDepthStackCardAtFrame(
return canonicalize(result) as unknown as DepthStackCardSet;
}
-export function appendDepthStackProjectedCard(
+export function appendDepthStackCard(
set: DepthStackCardSet,
material: DepthStackCardSet["cards"][number]["material"],
label: DepthStackCardLabel,
spec: DepthStackCardSpec,
- window: TemporalWindow,
+ activation: TemporalPoint,
): DepthStackCardSet {
- assert(window.source.kind === "moment", `DepthStack Card ${spec.id} requires a Moment window.`);
- return appendDepthStackCardAtFrame(set, material, label, spec, window.span.startFrame);
+ return appendDepthStackCardAtFrame(set, material, label, spec, activation.frame);
}
function finalizeDepthStackAtFrame(
@@ -245,9 +242,8 @@ function finalizeDepthStackAtFrame(
frame: SpatialFrame,
spec: DepthStackSpec,
terminalFrame: number,
- semantic: SemanticTrack,
+ space: ProgramSpace,
): DepthStackProgram {
- const space = projectSemanticProgramSpace(semantic);
assertDepthStackCardSet(set);
assertDepthStackHeader(header);
assertSpatialFrame(frame);
@@ -268,17 +264,15 @@ function finalizeDepthStackAtFrame(
return canonicalize(program) as unknown as DepthStackProgram;
}
-export function finalizeDepthStackAtWindow(
+export function finalizeDepthStack(
set: DepthStackCardSet,
header: DepthStackHeader,
frame: SpatialFrame,
spec: DepthStackSpec,
- window: TemporalWindow,
- semantic: SemanticTrack,
- boundary: "start" | "end" = "end",
+ terminal: TemporalPoint,
+ space: ProgramSpace,
): DepthStackProgram {
- return finalizeDepthStackAtFrame(set, header, frame, spec,
- boundary === "start" ? window.span.startFrame : window.span.endFrameExclusive, semantic);
+ return finalizeDepthStackAtFrame(set, header, frame, spec, terminal.frame, space);
}
export function assertDepthStackProgram(program: DepthStackProgram): void {
diff --git a/packages/deck-track/src/surface.ts b/packages/deck-track/src/surface.ts
index 06870a9c..6f4b42bb 100644
--- a/packages/deck-track/src/surface.ts
+++ b/packages/deck-track/src/surface.ts
@@ -222,17 +222,17 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
canvas: canvas.ref, frame: frame.ref, header: { kind: "record", id: headerId }, semantic: semantic.ref,
spec: { kind: "record", id: specId },
};
- const terminalSpecId = `${id}.terminal.window`;
+ const terminalSpecId = `${id}.terminal.point`;
const terminalSpecName = terminalValue.terminal.kind === "program-end" ? "program-spec" : terminalValue.terminal.specName;
- records.push({ id: terminalSpecId, type: temporalTypes.windowSpec, value: { kind: "inline", value: {
+ records.push({ id: terminalSpecId, type: temporalTypes.pointSpec, value: { kind: "inline", value: {
id: `${id}.terminal`,
projection: terminalValue.terminal.kind === "program-end"
- ? { start: { ref: "program.end", offset: { unit: "frames", value: -1 } }, end: { ref: "program.end" } }
+ ? { ref: "program.end" }
: terminalValue.terminal.kind === "moment"
- ? { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } }
+ ? { ref: "moment.cue" }
: terminalValue.terminal.kind === "selection-start"
- ? { start: { ref: "selection.start" }, end: { ref: "selection.start", offset: { unit: "frames", value: 1 } } }
- : { start: { ref: "selection.end" }, end: { ref: "selection.end", offset: { unit: "frames", value: 1 } } },
+ ? { ref: "selection.start" }
+ : { ref: "selection.end" },
} }, range: element.range });
if (terminalValue.reference !== undefined) inputs.terminal = terminalValue.reference.ref;
inputs[terminalSpecName] = { kind: "record", id: terminalSpecId };
@@ -273,19 +273,19 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
const sampleSpecName = `card-${suffix}-sample-spec`;
const cardSpecName = `card-${suffix}-spec`;
const momentName = `card-${suffix}-moment`;
- const windowSpecName = `card-${suffix}-window-spec`;
+ const pointSpecName = `card-${suffix}-point-spec`;
const labelName = `card-${suffix}-label`;
inputs[sourceName] = source.ref;
inputs[fitName] = { kind: "record", id: fitId };
inputs[sampleSpecName] = { kind: "record", id: sampleId };
inputs[cardSpecName] = { kind: "record", id: cardSpecId };
inputs[momentName] = moment.ref;
- const windowSpecId = `${id}.card.${suffix}.window`;
- records.push({ id: windowSpecId, type: temporalTypes.windowSpec, value: { kind: "inline", value: {
+ const pointSpecId = `${id}.card.${suffix}.point`;
+ records.push({ id: pointSpecId, type: temporalTypes.pointSpec, value: { kind: "inline", value: {
id: `${id}.${cardId}`,
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
+ projection: { ref: "moment.cue" },
} }, range: child.range });
- inputs[windowSpecName] = { kind: "record", id: windowSpecId };
+ inputs[pointSpecName] = { kind: "record", id: pointSpecId };
let labelRef: typeof semantic.ref;
if (child.attributes.label === undefined) {
const labelId = `${id}.card.${suffix}.label-none`;
@@ -309,7 +309,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
}
cards.push({
suffix, sourceKind, sourceName, ...(extentName === undefined ? {} : { extentName }), fitName, sampleSpecName,
- ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, momentName, windowSpecName,
+ ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, momentName, pointSpecName,
});
}
if (cards.length === 0) throw new Error(`${element.name} requires at least one Card.`);
diff --git a/packages/deck-track/test/deck-track.test.ts b/packages/deck-track/test/deck-track.test.ts
index 9dbef198..a566ab00 100644
--- a/packages/deck-track/test/deck-track.test.ts
+++ b/packages/deck-track/test/deck-track.test.ts
@@ -10,14 +10,14 @@ import { createResolvedClosure } from "@hypit/core";
import {
decodeDepthStackLabelSurface,
decodeDepthStackSurface,
- appendDepthStackProjectedCard,
+ appendDepthStackCard,
createDepthStackCardSet,
decodeDepthStackSpec,
depthStackManifest,
depthStackMarkupSurfaces,
depthStackProducers,
depthStackTypes,
- finalizeDepthStackAtWindow,
+ finalizeDepthStack,
noDepthStackCardLabel,
renderDepthStack,
resolveDepthStackPose,
@@ -40,7 +40,8 @@ import { narrativeTypes } from "@hypit/narrative";
import { sealProgramSpace } from "@hypit/program-space";
import type { ModuleManifest } from "@hypit/protocol";
import { semanticTrackTypes } from "@hypit/semantic-track";
-import type { TemporalWindow } from "@hypit/temporal";
+import { temporalTypes } from "@hypit/temporal";
+import type { TemporalPoint } from "@hypit/temporal";
import { sealCanvasSpace, sealSpatialFrame, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { sealText, textManifest, textTypes } from "@hypit/text";
@@ -101,6 +102,7 @@ test("DepthStack Surface declares every sealed Record it may emit", () => {
depthStackTypes.cardLabel,
depthStackTypes.cardLabelStyle,
textTypes.text,
+ temporalTypes.pointSpec,
depthStackTypes.program,
compositionTypes.visualTrack,
]) {
@@ -202,21 +204,21 @@ function cardSpec(id: string, past: "hold-tail" | "continue" | "hide" = "hold-ta
});
}
-function momentWindow(id: string, frameValue: number): TemporalWindow {
+function momentPoint(id: string, frameValue: number): TemporalPoint {
return {
id: `${id}::moment`,
source: { kind: "moment", id },
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
- span: { startFrame: frameValue, endFrameExclusive: frameValue + 1 },
+ projection: { ref: "moment.cue" },
+ frame: frameValue,
};
}
-function programWindow(endFrame: number): TemporalWindow {
+function programPoint(endFrame: number): TemporalPoint {
return {
id: "program::program",
source: { kind: "program", id: "program" },
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
- span: { startFrame: 0, endFrameExclusive: endFrame },
+ projection: { ref: "program.end" },
+ frame: endFrame,
};
}
@@ -232,21 +234,21 @@ function program(input: {
let set = createDepthStackCardSet();
for (const [index, trigger] of triggers.entries()) {
const id = `card-${index + 1}`;
- set = appendDepthStackProjectedCard(
+ set = appendDepthStackCard(
set,
input.materials?.[index] ?? stillMaterial(id),
input.labels?.[index] ?? noDepthStackCardLabel(),
input.playbacks?.[index] ?? cardSpec(id),
- momentWindow(id, trigger),
+ momentPoint(id, trigger),
);
}
- return finalizeDepthStackAtWindow(
+ return finalizeDepthStack(
set,
sealDepthStackHeader({ id: "proof-stack" }),
frame,
input.spec ?? baseSpec(),
- programWindow(input.terminal ?? 60),
- semantic,
+ programPoint(input.terminal ?? 60),
+ space,
);
}
@@ -278,9 +280,9 @@ test("explicit wrapping never aliases one Card into several relative depths", ()
});
test("missing, equal, reversed and terminal-crossing triggers fail in authored order", () => {
- assert.throws(() => finalizeDepthStackAtWindow(
+ assert.throws(() => finalizeDepthStack(
createDepthStackCardSet(), sealDepthStackHeader({ id: "empty" }),
- frame, baseSpec(), programWindow(60), semantic,
+ frame, baseSpec(), programPoint(60), space,
), /at least one Card/u);
assert.throws(() => program({ triggers: [0, 20, 20] }), /strictly increasing/u);
assert.throws(() => program({ triggers: [0, 30, 20] }), /strictly increasing/u);
@@ -440,7 +442,8 @@ test("the author Surface keeps every source, trigger, terminal, Frame and option
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-still-media-layer"));
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-timed-media-layer"));
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-depth-stack-card"));
- assert.ok(fragment.operations.some((operation) => operation.producer.name === "finalize-depth-stack-until-selection-end"));
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "finalize-depth-stack"));
+ assert.ok(fragment.operations.some((operation) => operation.producer.name === "project-selection-point"));
assert.equal(fragment.inputs.filter((input) => input.type.name === narrativeTypes.moment.name).length, 2);
assert.ok(fragment.inputs.some((input) => input.name === "frame"));
assert.ok(fragment.inputs.some((input) => input.name === "terminal"));
diff --git a/packages/media-track/README.md b/packages/media-track/README.md
index c939fa46..89f13726 100644
--- a/packages/media-track/README.md
+++ b/packages/media-track/README.md
@@ -11,6 +11,11 @@ stream, frame rate or audio policy. `Sequence` owns an ordered replacement surfa
activation points and pairwise Handoffs. Package-owned Recipes cover fitting, source occupancy,
frame Paint, clipping, borders, shadows, lifecycle motion and sampling motion.
+Ordinary Items consume projected `TemporalWindow` values. Sequence Member activations and the
+Sequence terminal consume projected `TemporalPoint` values instead; the Sequence component owns
+only the schedule and handoff consumption that follows those points. All domain Producers receive
+ProgramSpace explicitly and do not locate semantic sources themselves.
+
Visual and audio are separate deterministic projections. A visual-only Track exports only
`VisualTrack`; selecting one source layer's audio or adding explicit enter/exit/handoff sounds also
exports a peer `AudioTrack`. Speech Track reuses the same lowering laws through a deliberately
diff --git a/packages/media-track/src/component.ts b/packages/media-track/src/component.ts
index a22d40b6..7b0ae521 100644
--- a/packages/media-track/src/component.ts
+++ b/packages/media-track/src/component.ts
@@ -2,10 +2,9 @@ import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-
import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import type { ProgramSpace } from "@hypit/program-space";
import type { CanvasSpace, ContentFit, IntrinsicExtent, SpatialFrame, SpatialPath } from "@hypit/spatial";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";
import {
appendMediaPaintLayer,
@@ -15,9 +14,9 @@ import {
createMediaLayerSet,
} from "./layers.js";
import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
-import { appendMediaSequenceAtWindow, appendProjectedMediaItem, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaTrackProgram, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack } from "./program.js";
+import { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaTrackProgram, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack } from "./program.js";
import {
- appendMediaSequenceProjectedMember,
+ appendMediaSequenceMember,
createMediaSequenceMemberSet,
} from "./sequence.js";
import {
@@ -53,7 +52,7 @@ function itemInputs(inputs: ProducerHandlerContext["inputs"]) {
return {
set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
@@ -68,7 +67,7 @@ function memberInputs(inputs: ProducerHandlerContext["inputs"]) {
members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
spec: inline<MediaSequenceMemberSpec>(inputs.spec?.value, "MediaSequenceMemberSpec"),
- window: inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ activation: inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),
};
}
@@ -76,13 +75,13 @@ function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {
return {
set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
spec: inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),
sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
- window: inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ terminal: inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"),
};
}
@@ -115,7 +114,7 @@ export const mediaTrackComponent = {
{ producer: mediaTrackProducers.createSet, handler: () => ({ outputs: { set: output(createMediaTrackSet()) }, needs: {} }) },
{ producer: mediaTrackProducers.appendItem, handler: ({ inputs }) => {
const value = itemInputs(inputs);
- return { outputs: { set: output(appendProjectedMediaItem(value.set, value.header, value.semantic, value.canvas, value.layers, value.frame, value.spec, value.sounds, value.window)) }, needs: {} };
+ return { outputs: { set: output(appendMediaItem(value.set, value.header, value.space, value.canvas, value.layers, value.frame, value.spec, value.sounds, value.window)) }, needs: {} };
} },
{ producer: mediaTrackProducers.bindItemClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindMediaItemClipPath(
inline<MediaItemSpec>(inputs.spec?.value, "MediaItemSpec"),
@@ -128,43 +127,25 @@ export const mediaTrackComponent = {
{ producer: mediaTrackProducers.createMembers, handler: () => ({ outputs: { members: output(createMediaSequenceMemberSet()) }, needs: {} }) },
{ producer: mediaTrackProducers.appendMember, handler: ({ inputs }) => {
const value = memberInputs(inputs);
- return { outputs: { members: output(appendMediaSequenceProjectedMember(
- value.members, value.layers, value.spec, value.window,
+ return { outputs: { members: output(appendMediaSequenceMember(
+ value.members, value.layers, value.spec, value.activation,
)) }, needs: {} };
} },
- { producer: mediaTrackProducers.appendSequenceProgramEnd, handler: ({ inputs }) => {
+ { producer: mediaTrackProducers.appendSequence, handler: ({ inputs }) => {
const value = sequenceInputs(inputs);
- return { outputs: { set: output(appendMediaSequenceAtWindow(
- value.set, value.header, value.semantic, value.canvas, value.members, value.frame, value.spec, value.sounds, value.window,
- )) }, needs: {} };
- } },
- { producer: mediaTrackProducers.appendSequenceUntilMoment, handler: ({ inputs }) => {
- const value = sequenceInputs(inputs);
- return { outputs: { set: output(appendMediaSequenceAtWindow(
- value.set, value.header, value.semantic, value.canvas, value.members, value.frame, value.spec, value.sounds, value.window, "start",
- )) }, needs: {} };
- } },
- { producer: mediaTrackProducers.appendSequenceUntilSelectionStart, handler: ({ inputs }) => {
- const value = sequenceInputs(inputs);
- return { outputs: { set: output(appendMediaSequenceAtWindow(
- value.set, value.header, value.semantic, value.canvas, value.members, value.frame, value.spec, value.sounds, value.window, "start",
- )) }, needs: {} };
- } },
- { producer: mediaTrackProducers.appendSequenceUntilSelectionEnd, handler: ({ inputs }) => {
- const value = sequenceInputs(inputs);
- return { outputs: { set: output(appendMediaSequenceAtWindow(
- value.set, value.header, value.semantic, value.canvas, value.members, value.frame, value.spec, value.sounds, value.window, "start",
+ return { outputs: { set: output(appendMediaSequence(
+ value.set, value.header, value.space, value.canvas, value.members, value.frame, value.spec, value.sounds, value.terminal,
)) }, needs: {} };
} },
{ producer: mediaTrackProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeMediaTrack(
inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"), inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
)) }, needs: {} }) },
{ producer: mediaTrackProducers.projectVisual, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaVisualTrack(
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
)) }, needs: {} }) },
{ producer: mediaTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaAudioTrack(
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
)) }, needs: {} }) },
],
validators: [{
diff --git a/packages/media-track/src/fragment.ts b/packages/media-track/src/fragment.ts
index e811b312..7f4610a0 100644
--- a/packages/media-track/src/fragment.ts
+++ b/packages/media-track/src/fragment.ts
@@ -1,7 +1,7 @@
import { artifactTypes } from "@hypit/artifact";
import { compositionTypes } from "@hypit/composition";
import { sealGraphFragment } from "@hypit/elaborator";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialTypes } from "@hypit/spatial";
import { temporalProducers, temporalTypes } from "@hypit/temporal";
@@ -34,15 +34,18 @@ export const stillMediaTrackFragment = sealGraphFragment({
{ id: "window", producer: temporalProducers.projectProgram, inputs: {
semantic: input("semantic"), spec: input("window-spec"),
}, result: { kind: "output", name: "window" } },
+ { id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: {
+ track: input("semantic"),
+ }, result: { kind: "output", name: "space" } },
{ id: "append", producer: mediaTrackProducers.appendItem, inputs: {
- set: operation("set"), header: input("header"), semantic: input("semantic"), canvas: input("canvas"), layers: operation("sample"),
+ set: operation("set"), header: input("header"), space: operation("space"), canvas: input("canvas"), layers: operation("sample"),
frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: operation("window"),
}, result: { kind: "output", name: "set" } },
{ id: "finalize", producer: mediaTrackProducers.finalize, inputs: {
- set: operation("append"), header: input("header"), semantic: input("semantic"),
+ set: operation("append"), header: input("header"), space: operation("space"),
}, result: { kind: "output", name: "program" } },
{ id: "visual", producer: mediaTrackProducers.projectVisual, inputs: {
- semantic: input("semantic"), program: operation("finalize"),
+ space: operation("space"), program: operation("finalize"),
}, result: { kind: "output", name: "track" } },
],
exports: [
@@ -53,6 +56,9 @@ export const stillMediaTrackFragment = sealGraphFragment({
export const renderMediaTrackFragment = sealGraphFragment({
inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: mediaTrackTypes.program }],
- operations: [{ id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { semantic: input("semantic"), program: input("program") }, result: { kind: "output", name: "track" } }],
+ operations: [
+ { id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
+ { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { space: operation("space"), program: input("program") }, result: { kind: "output", name: "track" } },
+ ],
exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("visual") }],
});
diff --git a/packages/media-track/src/index.ts b/packages/media-track/src/index.ts
index e155fb2a..1ebb751d 100644
--- a/packages/media-track/src/index.ts
+++ b/packages/media-track/src/index.ts
@@ -43,13 +43,13 @@ export {
createMediaSoundSet,
sealMediaSoundSpec,
} from "./sounds.js";
-export { appendMediaSequenceAtWindow, appendProjectedMediaItem, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaItemSpec, assertMediaTrackHeader, assertMediaTrackProgram, assertMediaTrackProgramIdentity, assertMediaTrackSet, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaTrackHeader, sealMediaTrackProgram } from "./program.js";
+export { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaItemSpec, assertMediaTrackHeader, assertMediaTrackProgram, assertMediaTrackProgramIdentity, assertMediaTrackSet, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaTrackHeader, sealMediaTrackProgram } from "./program.js";
export { resolveVisualSampling } from "./sampling.js";
export { lowerRestrictedSpeechVisualPresents } from "./restricted-speech.js";
export type { RestrictedSpeechVisualClip } from "./restricted-speech.js";
export { decodeMediaTrackSurface } from "./surface.js";
export {
- appendMediaSequenceProjectedMember,
+ appendMediaSequenceMember,
assertMediaHandoffSpec,
assertMediaSequenceMemberSet,
assertMediaSequenceMemberSpec,
diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.ts
index 9d429aeb..647f3fdf 100644
--- a/packages/media-track/src/manifest.ts
+++ b/packages/media-track/src/manifest.ts
@@ -8,6 +8,7 @@ import {
mediaTypes,
} from "@hypit/media";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
import {
@@ -57,10 +58,7 @@ export const mediaTrackProducers = {
bindSequenceClipPath: { module: mediaTrackModuleRef, name: "bind-media-sequence-clip-path" },
createMembers: { module: mediaTrackModuleRef, name: "create-media-sequence-member-set" },
appendMember: { module: mediaTrackModuleRef, name: "append-media-sequence-member" },
- appendSequenceProgramEnd: { module: mediaTrackModuleRef, name: "append-media-sequence-until-program-end" },
- appendSequenceUntilMoment: { module: mediaTrackModuleRef, name: "append-media-sequence-until-moment" },
- appendSequenceUntilSelectionStart: { module: mediaTrackModuleRef, name: "append-media-sequence-until-selection-start" },
- appendSequenceUntilSelectionEnd: { module: mediaTrackModuleRef, name: "append-media-sequence-until-selection-end" },
+ appendSequence: { module: mediaTrackModuleRef, name: "append-media-sequence" },
finalize: { module: mediaTrackModuleRef, name: "finalize-media-track" },
projectVisual: { module: mediaTrackModuleRef, name: "project-media-visual-track" },
projectAudio: { module: mediaTrackModuleRef, name: "project-media-audio-track" },
@@ -251,21 +249,21 @@ export const mediaTrackHeaderSchema: ValueSchema = object({
const itemInputs = [
{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
- { name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+ { name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
{ name: "layers", type: mediaTrackTypes.layerSet },
{ name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.itemSpec },
{ name: "sounds", type: mediaTrackTypes.soundSet }, { name: "window", type: temporalTypes.window },
] as const;
const memberInputs = [
{ name: "members", type: mediaTrackTypes.memberSet }, { name: "layers", type: mediaTrackTypes.layerSet },
- { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "window", type: temporalTypes.window },
+ { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "activation", type: temporalTypes.point },
] as const;
const sequenceInputs = [
{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
- { name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+ { name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
{ name: "members", type: mediaTrackTypes.memberSet },
{ name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.sequenceSpec },
- { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "window", type: temporalTypes.window },
+ { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "terminal", type: temporalTypes.point },
] as const;
const appearanceRecipeProperties = [
@@ -359,7 +357,8 @@ export const mediaTrackMarkupSurfaces = [{
outputs: [spatialTypes.fit, mediaTrackTypes.header, mediaTrackTypes.paintLayerSpec, mediaTrackTypes.sampleLayerSpec,
mediaTrackTypes.layerSet, mediaTrackTypes.soundSpec, mediaTrackTypes.soundSet,
mediaTrackTypes.itemSpec, mediaTrackTypes.memberSpec, mediaTrackTypes.memberSet,
- mediaTrackTypes.handoffSpec, mediaTrackTypes.sequenceSpec, mediaTrackTypes.set, temporalTypes.windowSpec, mediaTrackTypes.program,
+ mediaTrackTypes.handoffSpec, mediaTrackTypes.sequenceSpec, mediaTrackTypes.set,
+ temporalTypes.pointSpec, temporalTypes.windowSpec, mediaTrackTypes.program,
compositionTypes.visualTrack, compositionTypes.audioTrack],
vocabulary: {
summary: "One Media Track: independently timed Items and replacement Sequences placed on a shared SemanticTrack and Canvas, lowered to one peer VisualTrack and, when audio is authored, one peer AudioTrack.",
@@ -571,6 +570,7 @@ export const mediaTrackManifest: ModuleManifest = {
artifactDependency,
mediaDependency,
narrativeDependency,
+ programSpaceDependency,
semanticTrackDependency,
temporalDependency,
spatialDependency,
@@ -606,13 +606,10 @@ export const mediaTrackManifest: ModuleManifest = {
{ name: mediaTrackProducers.bindSequenceClipPath.name, inputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }], needs: [] },
{ name: mediaTrackProducers.createMembers.name, inputs: [], outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
{ name: mediaTrackProducers.appendMember.name, inputs: memberInputs, outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
- { name: mediaTrackProducers.appendSequenceProgramEnd.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.appendSequenceUntilMoment.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.appendSequenceUntilSelectionStart.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.appendSequenceUntilSelectionEnd.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.finalize.name, inputs: [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header }, { name: "semantic", type: semanticTrackTypes.track }], outputs: [{ name: "program", type: mediaTrackTypes.program }], needs: [] },
- { name: mediaTrackProducers.projectVisual.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
- { name: mediaTrackProducers.projectAudio.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
+ { name: mediaTrackProducers.appendSequence.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
+ { name: mediaTrackProducers.finalize.name, inputs: [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header }, { name: "space", type: programSpaceTypes.programSpace }], outputs: [{ name: "program", type: mediaTrackTypes.program }], needs: [] },
+ { name: mediaTrackProducers.projectVisual.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: mediaTrackProducers.projectAudio.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
],
};
diff --git a/packages/media-track/src/program.ts b/packages/media-track/src/program.ts
index 15ed37d9..c6abd8a7 100644
--- a/packages/media-track/src/program.ts
+++ b/packages/media-track/src/program.ts
@@ -13,13 +13,11 @@ import {
} from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
import { canonicalize, isDigest } from "@hypit/protocol";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type { CanvasSpace } from "@hypit/spatial";
import { assertSpatialPath } from "@hypit/spatial";
import type { SpatialPath } from "@hypit/spatial";
-import type { ProjectedWindow } from "@hypit/temporal";
+import type { ProjectedWindow, TemporalPoint } from "@hypit/temporal";
import {
assertMediaIdentity,
@@ -173,10 +171,10 @@ function realizedItems(
}
/** Component entry point: timing has already been projected by @hypit/temporal. */
-export function appendProjectedMediaItem(
+export function appendMediaItem(
set: MediaTrackSet,
header: MediaTrackHeader,
- semantic: SemanticTrack,
+ space: ProgramSpace,
canvas: CanvasSpace,
layers: MediaLayerSet,
frame: MediaItemProgram["frame"],
@@ -184,7 +182,6 @@ export function appendProjectedMediaItem(
sounds: MediaSoundSet,
window: ProjectedWindow,
): MediaTrackSet {
- const space = projectSemanticProgramSpace(semantic);
return realizedItems(set, header, space, canvas, layers, frame, spec, sounds, window);
}
@@ -247,21 +244,18 @@ function appendMediaSequenceAtFrame(
return { ...set, sequences: [...set.sequences, sequence] };
}
-export function appendMediaSequenceAtWindow(
+export function appendMediaSequence(
set: MediaTrackSet,
header: MediaTrackHeader,
- semantic: SemanticTrack,
+ space: ProgramSpace,
canvas: CanvasSpace,
members: MediaSequenceMemberSet,
frame: MediaSequenceProgram["frame"],
spec: MediaSequenceSpec,
sounds: MediaSoundSet,
- window: ProjectedWindow,
- boundary: "start" | "end" = "end",
+ terminal: TemporalPoint,
): MediaTrackSet {
- const space = projectSemanticProgramSpace(semantic);
- const terminalFrame = boundary === "start" ? window.span.startFrame : window.span.endFrameExclusive;
- return appendMediaSequenceAtFrame(set, header, space, canvas, members, frame, spec, sounds, terminalFrame);
+ return appendMediaSequenceAtFrame(set, header, space, canvas, members, frame, spec, sounds, terminal.frame);
}
function assertSequence(sequence: MediaSequenceProgram, space: ProgramSpace, label: string): void {
diff --git a/packages/media-track/src/sequence.ts b/packages/media-track/src/sequence.ts
index 5acca886..8507f464 100644
--- a/packages/media-track/src/sequence.ts
+++ b/packages/media-track/src/sequence.ts
@@ -10,7 +10,7 @@ import { canonicalize } from "@hypit/protocol";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type { CanvasSpace } from "@hypit/spatial";
import { resolveTriggeredSchedule } from "@hypit/temporal";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint } from "@hypit/temporal";
import { assertMediaIdentity, assertMediaLayerSet } from "./layers.js";
import { lowerMediaItemElements } from "./lower.js";
@@ -107,13 +107,13 @@ function appendMediaSequenceMemberAtFrame(
}) as unknown as MediaSequenceMemberSet;
}
-export function appendMediaSequenceProjectedMember(
+export function appendMediaSequenceMember(
set: MediaSequenceMemberSet,
layers: MediaLayerSet,
spec: MediaSequenceMemberSpec,
- window: TemporalWindow,
+ activation: TemporalPoint,
): MediaSequenceMemberSet {
- return appendMediaSequenceMemberAtFrame(set, layers, spec, window.span.startFrame);
+ return appendMediaSequenceMemberAtFrame(set, layers, spec, activation.frame);
}
export function assertMediaHandoffSpec(value: MediaHandoffSpec): void {
diff --git a/packages/media-track/src/surface.ts b/packages/media-track/src/surface.ts
index 3b7ddecd..24d1c618 100644
--- a/packages/media-track/src/surface.ts
+++ b/packages/media-track/src/surface.ts
@@ -16,7 +16,7 @@ import { sealGraphFragment } from "@hypit/elaborator";
import type { FragmentOperation } from "@hypit/elaborator";
import { mediaTypes } from "@hypit/media";
import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
@@ -226,7 +226,7 @@ type FragmentMember = {
readonly suffix: string;
readonly binding: "moment" | "selection-start" | "selection-end";
readonly sourceName: string;
- readonly windowSpecName: string;
+ readonly pointSpecName: string;
readonly specName: string;
readonly layers: readonly FragmentLayer[];
};
@@ -280,7 +280,10 @@ function appendSounds(operations: FragmentOperation[], prefix: string, sounds: r
}
function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: string; readonly type: TypeRef }[], items: readonly FragmentItem[], sequences: readonly FragmentSequence[], audio: boolean) {
- const operations: FragmentOperation[] = [{ id: "track:set:empty", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } }];
+ const operations: FragmentOperation[] = [
+ { id: "track:space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
+ { id: "track:set:empty", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
+ ];
let set = "track:set:empty";
for (const item of items) {
const prefix = `item:${item.suffix}`;
@@ -304,7 +307,7 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
spec = operation(bindId);
}
const common = {
- set: operation(set), header: input("header"), semantic: input("semantic"), canvas: input("canvas"),
+ set: operation(set), header: input("header"), space: operation("track:space"), canvas: input("canvas"),
layers: operation(layers), frame: input(item.frameName), spec, sounds: operation(sounds), window: operation(windowId),
};
operations.push({ id: appendId, producer: mediaTrackProducers.appendItem, inputs: common, result: { kind: "output", name: "set" } });
@@ -319,14 +322,14 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
const memberPrefix = `${prefix}:member:${member.suffix}`;
const layers = appendLayers(operations, memberPrefix, member.layers);
const appendId = `${memberPrefix}:append`;
- const windowId = `${memberPrefix}:window`;
- const windowProducer = member.binding === "moment" ? temporalProducers.projectMoment : temporalProducers.projectSelection;
- operations.push({ id: windowId, producer: windowProducer, inputs: {
- semantic: input("semantic"), spec: input(member.windowSpecName),
+ const pointId = `${memberPrefix}:point`;
+ const pointProducer = member.binding === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint;
+ operations.push({ id: pointId, producer: pointProducer, inputs: {
+ semantic: input("semantic"), spec: input(member.pointSpecName),
[member.binding === "moment" ? "moment" : "selection"]: input(member.sourceName),
- }, result: { kind: "output", name: "window" } });
+ }, result: { kind: "output", name: "point" } });
operations.push({ id: appendId, producer: mediaTrackProducers.appendMember, inputs: {
- members: operation(members), layers: operation(layers), spec: input(member.specName), window: operation(windowId),
+ members: operation(members), layers: operation(layers), spec: input(member.specName), activation: operation(pointId),
}, result: { kind: "output", name: "members" } });
members = appendId;
}
@@ -341,30 +344,27 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
spec = operation(bindId);
}
const common = {
- set: operation(set), header: input("header"), semantic: input("semantic"), canvas: input("canvas"),
+ set: operation(set), header: input("header"), space: operation("track:space"), canvas: input("canvas"),
members: operation(members), frame: input(sequence.frameName), spec, sounds: operation(sounds),
};
- const terminalWindowId = `${prefix}:window`;
- const terminalProducer = sequence.terminal === "program-end" ? temporalProducers.projectProgram
- : sequence.terminal === "moment" ? temporalProducers.projectMoment : temporalProducers.projectSelection;
- operations.push({ id: terminalWindowId, producer: terminalProducer, inputs: {
+ const terminalPointId = `${prefix}:terminal`;
+ const terminalProducer = sequence.terminal === "program-end" ? temporalProducers.projectProgramPoint
+ : sequence.terminal === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint;
+ operations.push({ id: terminalPointId, producer: terminalProducer, inputs: {
semantic: input("semantic"), spec: input(sequence.terminalSpecName),
...(sequence.terminal === "program-end" ? {} : {
[sequence.terminal === "moment" ? "moment" : "selection"]: input(sequence.terminalSourceName!),
}),
- }, result: { kind: "output", name: "window" } });
- const producer = sequence.terminal === "program-end" ? mediaTrackProducers.appendSequenceProgramEnd
- : sequence.terminal === "moment" ? mediaTrackProducers.appendSequenceUntilMoment
- : sequence.terminal === "selection-start" ? mediaTrackProducers.appendSequenceUntilSelectionStart
- : mediaTrackProducers.appendSequenceUntilSelectionEnd;
- operations.push({ id: appendId, producer, inputs: { ...common, window: operation(terminalWindowId) }, result: { kind: "output", name: "set" } });
+ }, result: { kind: "output", name: "point" } });
+ operations.push({ id: appendId, producer: mediaTrackProducers.appendSequence,
+ inputs: { ...common, terminal: operation(terminalPointId) }, result: { kind: "output", name: "set" } });
set = appendId;
}
operations.push(
- { id: "track:finalize", producer: mediaTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), semantic: input("semantic") }, result: { kind: "output", name: "program" } },
- { id: "track:visual", producer: mediaTrackProducers.projectVisual, inputs: { semantic: input("semantic"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
+ { id: "track:finalize", producer: mediaTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), space: operation("track:space") }, result: { kind: "output", name: "program" } },
+ { id: "track:visual", producer: mediaTrackProducers.projectVisual, inputs: { space: operation("track:space"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
);
- if (audio) operations.push({ id: "track:audio", producer: mediaTrackProducers.projectAudio, inputs: { semantic: input("semantic"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } });
+ if (audio) operations.push({ id: "track:audio", producer: mediaTrackProducers.projectAudio, inputs: { space: operation("track:space"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } });
return sealGraphFragment({
inputs: inputTypes,
operations,
@@ -751,21 +751,21 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
const selectedAudio = sourceAudio(member);
if (selectedAudio !== undefined) hasAudio = true;
const specName = `${unitSuffix}-spec`;
- const windowSpecName = `${unitSuffix}-window-spec`;
+ const pointSpecName = `${unitSuffix}-point-spec`;
state.addRecord(specName, `${trackId}.${unitSuffix}.spec`, mediaTrackTypes.memberSpec,
sealMediaSequenceMemberSpec({ id: memberIds[index]!,
...(selectedAudio === undefined ? {} : { sourceAudio: selectedAudio }) }), member.range);
- state.addRecord(windowSpecName, `${trackId}.${unitSuffix}.window`, temporalTypes.windowSpec, {
+ state.addRecord(pointSpecName, `${trackId}.${unitSuffix}.point`, temporalTypes.pointSpec, {
id: `${id}.${memberIds[index]}`,
projection: binding === "moment"
- ? { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } }
+ ? { ref: "moment.cue" }
: boundary === "start"
- ? { start: { ref: "selection.start" }, end: { ref: "selection.start", offset: { unit: "frames", value: 1 } } }
- : { start: { ref: "selection.end" }, end: { ref: "selection.end", offset: { unit: "frames", value: 1 } } },
+ ? { ref: "selection.start" }
+ : { ref: "selection.end" },
}, member.range);
const sourceName = `${unitSuffix}-${binding === "moment" ? "moment" : "selection"}`;
state.addReference(sourceName, at);
- members.push({ suffix: memberSuffix, binding, sourceName, specName, windowSpecName, layers });
+ members.push({ suffix: memberSuffix, binding, sourceName, specName, pointSpecName, layers });
}
const sequenceSounds: FragmentSound[] = [];
for (const soundChild of child.children) {
@@ -802,16 +802,16 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
decodeMediaSequenceSpec(appearance, id, decodeMediaMotion(motionRecipe), handoffs), child.range);
const terminalSourceName = terminalReference === undefined ? undefined : `sequence-${sequenceSuffix}-terminal`;
if (terminalReference !== undefined) state.addReference(terminalSourceName!, terminalReference);
- const terminalSpecName = `sequence-${sequenceSuffix}-terminal-window-spec`;
- state.addRecord(terminalSpecName, `${trackId}.sequence.${sequenceSuffix}.terminal-window`, temporalTypes.windowSpec, {
+ const terminalSpecName = `sequence-${sequenceSuffix}-terminal-point-spec`;
+ state.addRecord(terminalSpecName, `${trackId}.sequence.${sequenceSuffix}.terminal-point`, temporalTypes.pointSpec, {
id: `${id}.terminal`,
projection: terminal === "program-end"
- ? { start: { ref: "program.end", offset: { unit: "frames", value: -1 } }, end: { ref: "program.end" } }
+ ? { ref: "program.end" }
: terminal === "moment"
- ? { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } }
+ ? { ref: "moment.cue" }
: terminal === "selection-start"
- ? { start: { ref: "selection.start" }, end: { ref: "selection.start", offset: { unit: "frames", value: 1 } } }
- : { start: { ref: "selection.end" }, end: { ref: "selection.end", offset: { unit: "frames", value: 1 } } },
+ ? { ref: "selection.start" }
+ : { ref: "selection.end" },
}, child.range);
sequences.push({ suffix: sequenceSuffix, terminal, ...(terminalSourceName === undefined ? {} : { terminalSourceName }), terminalSpecName, frameName, specName,
...(clipPathName === undefined ? {} : { clipPathName }), members, sounds: sequenceSounds });
diff --git a/packages/media-track/test/media-track.test.ts b/packages/media-track/test/media-track.test.ts
index 861ff48a..58cd2e3a 100644
--- a/packages/media-track/test/media-track.test.ts
+++ b/packages/media-track/test/media-track.test.ts
@@ -13,9 +13,9 @@ import { narrativeTypes } from "@hypit/narrative";
import {
appendMediaPaintLayer,
appendMediaSound,
- appendMediaSequenceAtWindow,
- appendMediaSequenceProjectedMember,
- appendProjectedMediaItem,
+ appendMediaItem,
+ appendMediaSequence as appendProjectedMediaSequence,
+ appendMediaSequenceMember as appendProjectedMediaSequenceMember,
appendStillMediaLayer,
appendSurfaceMediaLayer,
appendTimedMediaLayer,
@@ -138,7 +138,7 @@ function appendProgramMediaItem(
) {
const projection = "projection" in authored ? authored.projection : defaultItemProjection;
const { projection: _ignored, ...spec } = authored as TestMediaItemSpec;
- return appendProjectedMediaItem(set, trackHeader, semanticTrack, canvasSpace, layers, frameValue, spec, sounds,
+ return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
projectProgramWindow({ itemId: spec.id, semantic: semanticTrack, projection }));
}
@@ -148,7 +148,7 @@ function appendSelectionMediaItem(
authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
) {
const { projection, ...spec } = authored;
- return appendProjectedMediaItem(set, trackHeader, semanticTrack, canvasSpace, layers, frameValue, spec, sounds,
+ return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
projectSelectionWindow({ itemId: spec.id, semantic: semanticTrack, selection, projection }));
}
@@ -158,7 +158,7 @@ function appendSegmentMediaItem(
authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
) {
const { projection, ...spec } = authored;
- return appendProjectedMediaItem(set, trackHeader, semanticTrack, canvasSpace, layers, frameValue, spec, sounds,
+ return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
projectSegmentWindow({ itemId: spec.id, semantic: semanticTrack, segment, projection }));
}
@@ -168,7 +168,7 @@ function appendMomentMediaItem(
authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
) {
const { projection, ...spec } = authored;
- return appendProjectedMediaItem(set, trackHeader, semanticTrack, canvasSpace, layers, frameValue, spec, sounds,
+ return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
projectMomentWindow({ itemId: spec.id, semantic: semanticTrack, moment, projection }));
}
@@ -228,11 +228,11 @@ function sequenceMembers(
id: `member-${index + 1}`,
sourceAudio: { fromLayer: "video", gain: 1 - (index * 0.1) },
});
- members = appendMediaSequenceProjectedMember(members, layerFactory(index), spec, {
+ members = appendProjectedMediaSequenceMember(members, layerFactory(index), spec, {
id: `${spec.id}::test`,
source: { kind: "program", id: "program" },
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
- span: { startFrame: activationFrame, endFrameExclusive: activationFrame + 1 },
+ projection: { ref: "program.start" },
+ frame: activationFrame,
});
}
return members;
@@ -248,22 +248,24 @@ function testProgramWindow(endFrameExclusive: number): TemporalWindow {
}
function appendMediaSequence(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, _space: typeof space, _canvas: typeof canvas,
+ set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, spaceValue: typeof space, canvasValue: typeof canvas,
members: ReturnType<typeof createMediaSequenceMemberSet>, frameValue: typeof frame, spec: MediaSequenceSpec,
sounds: ReturnType<typeof createMediaSoundSet>, terminalFrame: number,
) {
- return appendMediaSequenceAtWindow(set, trackHeader, semantic, canvas, members, frameValue, spec, sounds,
- testProgramWindow(terminalFrame));
+ return appendProjectedMediaSequence(set, trackHeader, spaceValue, canvasValue, members, frameValue, spec, sounds, {
+ id: `${spec.id}::terminal`, source: { kind: "program", id: "program" },
+ projection: { ref: "program.end" }, frame: terminalFrame,
+ });
}
function appendMediaSequenceMember(
set: ReturnType<typeof createMediaSequenceMemberSet>, layers: MediaLayerSet, spec: ReturnType<typeof sealMediaSequenceMemberSpec>, activationFrame: number,
) {
- return appendMediaSequenceProjectedMember(set, layers, spec, {
+ return appendProjectedMediaSequenceMember(set, layers, spec, {
id: `${spec.id}::test`,
source: { kind: "program", id: "program" },
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
- span: { startFrame: activationFrame, endFrameExclusive: activationFrame + 1 },
+ projection: { ref: "program.start" },
+ frame: activationFrame,
});
}
@@ -767,7 +769,8 @@ test("the Media author Surface emits explicit graph edges for layers, semantic t
assert.ok(producers.includes("append-media-paint-layer"));
assert.ok(producers.includes("bind-media-item-clip-path"));
assert.ok(producers.includes("append-media-sequence-member"));
- assert.ok(producers.includes("append-media-sequence-until-selection-end"));
+ assert.ok(producers.includes("append-media-sequence"));
+ assert.ok(producers.includes("project-selection-point"));
assert.ok(producers.includes("append-media-sound"));
assert.ok(fragment.inputs.some((entry) => entry.type.name === artifactTypes.blob.name));
assert.ok(fragment.inputs.some((entry) => entry.type.name === mediaTypes.synchronized.name));
diff --git a/packages/ranking/README.md b/packages/ranking/README.md
index c3e9da2b..eacdc499 100644
--- a/packages/ranking/README.md
+++ b/packages/ranking/README.md
@@ -41,6 +41,11 @@ Column resolves those sibling candidates into non-overlapping windows inside the
Segment/Selection `during` span. Candidate time, child order and rank may all differ. A preset Item
has no child `during` and is settled from the beginning of the outer window.
+TierBoard and TopThree triggers and terminals are explicit `TemporalPoint` values. Column outer and
+reveal candidates remain `TemporalWindow` values. Ranking consumes those projections plus
+ProgramSpace and owns only the subsequent chronological or non-overlap schedule; it does not locate
+Moment/Selection frames internally.
+
The Column's `frame` is the fixed left ranking rail; `canvas` supplies the independent coordinate
space for the large reveal stage. `stage-x` and `stage-y` are normalized Canvas coordinates. Each
normal reveal rises from below the Canvas, holds on that stage, then shrinks and moves into its
diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.ts
index 041738f6..022beabb 100644
--- a/packages/ranking/src/component.ts
+++ b/packages/ranking/src/component.ts
@@ -3,14 +3,12 @@ import type { SynchronizedMedia } from "@hypit/media";
import type { ProgramSpace } from "@hypit/program-space";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
-import type { SemanticTrack } from "@hypit/semantic-track";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";
import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
import type { Text } from "@hypit/text";
import { rankingProducers, rankingTypes } from "./manifest.js";
-import { appendColumnItem, appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidateWindow, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildRankingScheduleFromWindows, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";
+import { appendColumnItem, appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";
import {
renderColumn,
renderRankingAudio,
@@ -87,20 +85,20 @@ export const rankingComponent = {
},
{
producer: rankingProducers.appendTriggeredCandidate,
- handler: ({ inputs }) => ({ outputs: { set: output(appendTriggeredRankingCandidateWindow(
+ handler: ({ inputs }) => ({ outputs: { set: output(appendTriggeredRankingCandidate(
inline<TriggeredRankingCandidateSet>(inputs.set?.value, "TriggeredRankingCandidateSet"),
inline<RankingItemSpec>(inputs.spec?.value, "RankingItemSpec"),
- inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),
)) }, needs: {} }),
},
{
producer: rankingProducers.schedule,
- handler: ({ inputs }) => ({ outputs: { schedule: output(buildRankingScheduleFromWindows({
+ handler: ({ inputs }) => ({ outputs: { schedule: output(buildTriggeredRankingSchedule({
header: inline(inputs.header?.value, "RankingHeader"), items: inline(inputs.items?.value, "RankingItemSpecSet"),
- semantic: inline(inputs.semantic?.value, "SemanticTrack"),
+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
outer: inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"),
candidates: inline(inputs.candidates?.value, "TriggeredRankingCandidateSet"),
- terminal: inline<TemporalWindow>(inputs.terminal?.value, "TemporalWindow"),
+ terminal: inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"),
})) }, needs: {} }),
},
{
@@ -216,7 +214,7 @@ export const rankingComponent = {
{
producer: rankingProducers.renderAudio,
handler: ({ inputs }) => ({ outputs: { track: output(renderRankingAudio(
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
inline<RankingSoundEventPlan>(inputs.events?.value, "RankingSoundEventPlan"),
inline<RankingSoundStyle>(inputs.style?.value, "RankingSoundStyle"),
inline<RankingSoundSet>(inputs.sounds?.value, "RankingSoundSet"),
@@ -229,7 +227,7 @@ export const rankingComponent = {
] as const).map(([producer, render, label]) => ({
producer,
handler: ({ inputs }: ProducerHandlerContext) => ({ outputs: { track: output(render(
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")), inline(inputs.program?.value, label) as never,
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline(inputs.program?.value, label) as never,
)) }, needs: {} }),
})),
],
diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.ts
index e53034d2..d0623a25 100644
--- a/packages/ranking/src/fragment.ts
+++ b/packages/ranking/src/fragment.ts
@@ -3,7 +3,7 @@ import { sealGraphFragment } from "@hypit/elaborator";
import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
import { mediaTypes } from "@hypit/media";
import { narrativeTypes } from "@hypit/narrative";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialTypes } from "@hypit/spatial";
import { textTypes } from "@hypit/text";
import { temporalProducers, temporalTypes } from "@hypit/temporal";
@@ -64,13 +64,15 @@ export function createRankingFragment(
{ name: "outer-spec", type: temporalTypes.windowSpec },
...(variant === "column" ? [] : [
{ name: "terminal", type: narrativeTypes.moment },
- { name: "terminal-spec", type: temporalTypes.windowSpec },
+ { name: "terminal-spec", type: temporalTypes.pointSpec },
]),
...(variant === "column" ? [{ name: "canvas", type: spatialTypes.canvas }] : []),
{ name: "frame", type: spatialTypes.frame },
{ name: "style", type: selected.style },
];
const operations: FragmentOperation[] = [
+ { id: "space", producer: semanticTrackProducers.projectProgramSpace,
+ inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
{ id: "specs", producer: rankingProducers.createSpecs, inputs: { header: input("header") }, result: { kind: "output", name: "set" } },
{ id: "resolved", producer: selected.create, inputs: {}, result: { kind: "output", name: "set" } },
{ id: "candidates", producer: variant === "column"
@@ -88,7 +90,8 @@ export function createRankingFragment(
name: item.timingName,
type: variant === "column" ? narrativeTypes.selection : narrativeTypes.moment,
});
- if (item.timingSpecName !== undefined) inputs.push({ name: item.timingSpecName, type: temporalTypes.windowSpec });
+ if (item.timingSpecName !== undefined) inputs.push({ name: item.timingSpecName,
+ type: variant === "column" ? temporalTypes.windowSpec : temporalTypes.pointSpec });
const materializedId = `materialize-${item.suffix}`;
if (item.contentName !== undefined) operations.push({
id: materializedId,
@@ -118,15 +121,15 @@ export function createRankingFragment(
});
resolved = operation(visualId);
if (item.timingName !== undefined) {
- const windowId = `window-${item.suffix}`;
+ const projectionId = `${variant === "column" ? "window" : "point"}-${item.suffix}`;
operations.push({
- id: windowId,
- producer: variant === "column" ? temporalProducers.projectSelection : temporalProducers.projectMoment,
+ id: projectionId,
+ producer: variant === "column" ? temporalProducers.projectSelection : temporalProducers.projectMomentPoint,
inputs: {
semantic: input("semantic"), spec: input(item.timingSpecName!),
[variant === "column" ? "selection" : "moment"]: input(item.timingName),
},
- result: { kind: "output", name: "window" },
+ result: { kind: "output", name: variant === "column" ? "window" : "point" },
});
const timingId = `timing-${item.suffix}`;
operations.push({
@@ -136,7 +139,7 @@ export function createRankingFragment(
: rankingProducers.appendTriggeredCandidate,
inputs: {
set: candidates, spec: resolvedSpec,
- window: operation(windowId),
+ [variant === "column" ? "window" : "activation"]: operation(projectionId),
},
result: { kind: "output", name: "set" },
});
@@ -167,17 +170,17 @@ export function createRankingFragment(
result: { kind: "output", name: "window" },
});
operations.push({
- id: "terminal-window",
- producer: temporalProducers.projectMoment,
+ id: "terminal-point",
+ producer: temporalProducers.projectMomentPoint,
inputs: { semantic: input("semantic"), moment: input("terminal"), spec: input("terminal-spec") },
- result: { kind: "output", name: "window" },
+ result: { kind: "output", name: "point" },
});
operations.push({
id: "schedule",
producer: rankingProducers.schedule,
inputs: {
- header: input("header"), items: specs, semantic: input("semantic"),
- outer: operation("outer-window"), candidates, terminal: operation("terminal-window"),
+ header: input("header"), items: specs, space: operation("space"),
+ outer: operation("outer-window"), candidates, terminal: operation("terminal-point"),
},
result: { kind: "output", name: "schedule" },
});
@@ -195,7 +198,7 @@ export function createRankingFragment(
operations.push({
id: "visual",
producer: selected.render,
- inputs: { semantic: input("semantic"), program: operation("program") },
+ inputs: { space: operation("space"), program: operation("program") },
result: { kind: "output", name: "track" },
});
const hasAudio = sound.appearName !== undefined || sound.moveName !== undefined;
@@ -224,7 +227,7 @@ export function createRankingFragment(
}
operations.push({
id: "audio", producer: rankingProducers.renderAudio,
- inputs: { semantic: input("semantic"), events: operation("events"), style: input("sound-style"), sounds },
+ inputs: { space: operation("space"), events: operation("events"), style: input("sound-style"), sounds },
result: { kind: "output", name: "track" },
});
}
diff --git a/packages/ranking/src/index.ts b/packages/ranking/src/index.ts
index a20805b7..60b9d7d1 100644
--- a/packages/ranking/src/index.ts
+++ b/packages/ranking/src/index.ts
@@ -1,4 +1,4 @@
-export { appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidateWindow, assertColumnProgram, assertColumnStyle, assertColumnWindowCandidateSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildRankingScheduleFromWindows, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
+export { appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertColumnStyle, assertColumnWindowCandidateSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
export {
decodeColumnStyle,
decodeTierBoardStyle,
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
index a529a543..3a96ddfc 100644
--- a/packages/ranking/src/manifest.ts
+++ b/packages/ranking/src/manifest.ts
@@ -4,6 +4,7 @@ import { artifactDependency } from "@hypit/artifact";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { mediaDependency, mediaTypes } from "@hypit/media";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
@@ -107,10 +108,9 @@ export const rankingItemSpecSetSchema: ValueSchema = object({
const frameSpan = object({ startFrame: { schema: unsigned }, endFrameExclusive: { schema: unsigned } });
export const triggeredRankingCandidateSetSchema: ValueSchema = object({
entries: { schema: { kind: "array", items: object({
- itemId: { schema: string }, window: { schema: object({
+ itemId: { schema: string }, activation: { schema: object({
id: { schema: string }, source: { schema: object({ kind: { schema: string }, id: { schema: string } }) },
- projection: { schema: object({ start: { schema: object({}, true) }, end: { schema: object({}, true) } }) },
- span: { schema: frameSpan },
+ projection: { schema: object({}, true) }, frame: { schema: unsigned },
}) },
}) } },
});
@@ -429,7 +429,7 @@ export const rankingMarkupSurfaces = [
"Every other property is refused by name, except the board Paint and `stage-stack` keys, which a podium accepts and never reads.",
],
} },
- { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],
+ { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.pointSpec, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],
vocabulary: {
summary: "Places ordered Items into tier rows at the Moment owned by each Item, and publishes the board and the Tracks it renders to.",
appearance:
@@ -564,7 +564,7 @@ export const rankingMarkupSurfaces = [
"Authoring either sound also connects the Style's `.sound` output, so `style` must name a ColumnStyle written in this Source.",
],
} },
- { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],
+ { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.pointSpec, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],
vocabulary: {
summary: "Fills a podium one slot at a time at the Moment owned by each Item, and publishes the board and the Tracks it renders to.",
appearance:
@@ -633,7 +633,7 @@ export const rankingMarkupSurfaces = [
export const rankingManifest: ModuleManifest = {
format: "hypit.module@1", name: rankingModuleRef.name, version: rankingModuleRef.version,
- dependencies: [artifactDependency, mediaDependency, narrativeDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency, textDependency],
+ dependencies: [artifactDependency, mediaDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency, textDependency],
types: [
{ name: rankingTypes.header.name },
{ name: rankingTypes.itemSpec.name },
@@ -665,13 +665,13 @@ export const rankingManifest: ModuleManifest = {
], needs: [] },
{ name: rankingProducers.appendTriggeredCandidate.name, inputs: [
{ name: "set", type: rankingTypes.triggeredCandidates }, { name: "spec", type: rankingTypes.itemSpec },
- { name: "window", type: temporalTypes.window },
+ { name: "activation", type: temporalTypes.point },
], outputs: [{ name: "set", type: rankingTypes.triggeredCandidates }], needs: [] },
{ name: rankingProducers.schedule.name, inputs: [
{ name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },
- { name: "semantic", type: semanticTrackTypes.track },
+ { name: "space", type: programSpaceTypes.programSpace },
{ name: "outer", type: temporalTypes.window }, { name: "candidates", type: rankingTypes.triggeredCandidates },
- { name: "terminal", type: temporalTypes.window },
+ { name: "terminal", type: temporalTypes.point },
], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },
{ name: rankingProducers.createColumnCandidates.name, inputs: [], outputs: [
{ name: "set", type: rankingTypes.columnCandidates },
@@ -714,7 +714,7 @@ export const rankingManifest: ModuleManifest = {
{ name: eventProducer.name, inputs: [
{ name: "schedule", type: rankingTypes.schedule }, { name: "style", type: styleType }, { name: "specs", type: rankingTypes.itemSpecs },
], outputs: [{ name: "events", type: rankingTypes.soundEvents }], needs: [] },
- { name: renderProducer.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: programType }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: renderProducer.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: programType }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
]),
{ name: rankingProducers.createSounds.name, inputs: [], outputs: [{ name: "sounds", type: rankingTypes.sounds }], needs: [] },
...([
@@ -724,7 +724,7 @@ export const rankingManifest: ModuleManifest = {
name: producer.name, inputs: [{ name: "sounds", type: rankingTypes.sounds }, { name: "media", type: mediaTypes.synchronized }], outputs: [{ name: "sounds", type: rankingTypes.sounds }], needs: [],
})),
{ name: rankingProducers.renderAudio.name, inputs: [
- { name: "semantic", type: semanticTrackTypes.track }, { name: "events", type: rankingTypes.soundEvents },
+ { name: "space", type: programSpaceTypes.programSpace }, { name: "events", type: rankingTypes.soundEvents },
{ name: "style", type: rankingTypes.soundStyle }, { name: "sounds", type: rankingTypes.sounds },
], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
],
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index c1458ada..7521e0ab 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -11,12 +11,10 @@ import type { ProgramSpace } from "@hypit/program-space";
import { canonicalize, isDigest } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type { CanvasSpace } from "@hypit/spatial";
import { resolveTriggeredSchedule } from "@hypit/temporal";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";
import type {
ColumnItem,
@@ -291,38 +289,33 @@ export function assertTriggeredRankingCandidateSet(value: TriggeredRankingCandid
identity(entry.itemId, `TriggeredRankingCandidateSet.entries.${index}.itemId`);
assert(!itemIds.has(entry.itemId), `TriggeredRankingCandidateSet repeats ${entry.itemId}.`);
itemIds.add(entry.itemId);
- assert(entry.window.source.kind === "moment", `TriggeredRankingCandidateSet.entries.${index}.window must come from a Moment.`);
- frame(entry.window.span.startFrame, `TriggeredRankingCandidateSet.entries.${index}.window.span.startFrame`);
- frame(entry.window.span.endFrameExclusive, `TriggeredRankingCandidateSet.entries.${index}.window.span.endFrameExclusive`);
- assert(entry.window.span.endFrameExclusive > entry.window.span.startFrame,
- `TriggeredRankingCandidateSet.entries.${index}.window is empty.`);
+ frame(entry.activation.frame, `TriggeredRankingCandidateSet.entries.${index}.activation.frame`);
}
}
-export function appendTriggeredRankingCandidateWindow(
+export function appendTriggeredRankingCandidate(
set: TriggeredRankingCandidateSet,
spec: RankingItemSpec,
- window: TemporalWindow,
+ activation: TemporalPoint,
): TriggeredRankingCandidateSet {
assertTriggeredRankingCandidateSet(set);
assertRankingItemSpec(spec);
assert(spec.variant !== "column", `Column Item ${spec.id} consumes a Selection window, not a Moment.`);
- assert(window.source.kind === "moment", `Ranking Item ${spec.id} requires a Moment-projected window.`);
assert(!set.entries.some((entry) => entry.itemId === spec.id), `Ranking Item ${spec.id} already has a Moment.`);
const result: TriggeredRankingCandidateSet = {
- entries: [...set.entries, { itemId: spec.id, window: structuredClone(window) }],
+ entries: [...set.entries, { itemId: spec.id, activation: structuredClone(activation) }],
};
assertTriggeredRankingCandidateSet(result);
return canonicalize(result) as unknown as TriggeredRankingCandidateSet;
}
-function buildRankingScheduleFromWindows(input: {
+export function buildTriggeredRankingSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
- readonly semantic: SemanticTrack;
+ readonly space: ProgramSpace;
readonly outer: TemporalWindow;
readonly candidates: TriggeredRankingCandidateSet;
- readonly terminal: TemporalWindow;
+ readonly terminal: TemporalPoint;
}): TriggeredRankingSchedule {
assertRankingHeader(input.header);
assertRankingItemSpecSet(input.items);
@@ -330,19 +323,16 @@ function buildRankingScheduleFromWindows(input: {
assert(input.header.variant !== "column", "Column uses item-owned Selection windows, not the triggered Ranking schedule.");
assert(input.items.items.length > 0, "Ranking requires at least one Item.");
assertTriggeredRankingCandidateSet(input.candidates);
- assert(input.outer.source.kind === "selection", "Triggered Ranking outer window must come from a Selection.");
- assert(input.terminal.source.kind === "moment", "Triggered Ranking terminal window must come from a Moment.");
- const space = projectSemanticProgramSpace(input.semantic);
const expected = new Set(input.items.items.map((item) => item.id));
const received = new Set(input.candidates.entries.map((entry) => entry.itemId));
assert(expected.size === received.size && [...expected].every((id) => received.has(id)),
"Ranking Items and item-owned Moments differ.");
const ordered = [...input.candidates.entries].sort((left, right) =>
- left.window.span.startFrame - right.window.span.startFrame || left.itemId.localeCompare(right.itemId));
+ left.activation.frame - right.activation.frame || left.itemId.localeCompare(right.itemId));
const resolved = resolveTriggeredSchedule({
outer: { ...input.outer.span },
- terminalFrame: input.terminal.span.startFrame,
- triggers: ordered.map((item) => ({ id: item.itemId, frame: item.window.span.startFrame })),
+ terminalFrame: input.terminal.frame,
+ triggers: ordered.map((item) => ({ id: item.itemId, frame: item.activation.frame })),
});
const entries = ordered.map((candidate, index) => {
const exclusive = resolved.exclusive[index]!;
@@ -362,13 +352,10 @@ function buildRankingScheduleFromWindows(input: {
terminalFrame: resolved.terminalFrame,
entries,
};
- assertRankingSchedule(result, space);
+ assertRankingSchedule(result, input.space);
return canonicalize(result) as unknown as TriggeredRankingSchedule;
}
-export { buildRankingScheduleFromWindows };
-
-
export function createColumnWindowCandidateSet(): ColumnWindowCandidateSet {
return { entries: [] };
}
@@ -380,7 +367,6 @@ export function assertColumnWindowCandidateSet(value: ColumnWindowCandidateSet):
identity(entry.itemId, `ColumnWindowCandidateSet.entries.${index}.itemId`);
assert(!ids.has(entry.itemId), `ColumnWindowCandidateSet repeats ${entry.itemId}.`);
ids.add(entry.itemId);
- assert(entry.window.source.kind === "selection", `ColumnWindowCandidateSet.entries.${index}.window must come from a Selection.`);
frame(entry.window.span.startFrame, `ColumnWindowCandidateSet.entries.${index}.window.span.startFrame`);
frame(entry.window.span.endFrameExclusive, `ColumnWindowCandidateSet.entries.${index}.window.span.endFrameExclusive`);
assert(entry.window.span.endFrameExclusive > entry.window.span.startFrame,
@@ -396,7 +382,6 @@ export function appendColumnWindowCandidateWindow(
assertColumnWindowCandidateSet(set);
assertRankingItemSpec(spec);
assert(!spec.preset, `Preset Column Item ${spec.id} cannot consume a Selection window.`);
- assert(window.source.kind === "selection", `Column Item ${spec.id} requires a Selection-projected window.`);
assert(!set.entries.some((entry) => entry.itemId === spec.id), `Column Item ${spec.id} already has a Selection window.`);
const result: ColumnWindowCandidateSet = {
entries: [...set.entries, { itemId: spec.id, window: structuredClone(window) }]
@@ -432,7 +417,6 @@ function resolveColumnActiveWindows(
})).sort((left, right) =>
left.clamped.startFrame - right.clamped.startFrame
|| left.clamped.endFrameExclusive - right.clamped.endFrameExclusive
- || left.window.source.id.localeCompare(right.window.source.id)
|| left.itemId.localeCompare(right.itemId));
const resolved = new Map<string, { readonly startFrame: number; readonly endFrameExclusive: number }>();
let cursor = outer.startFrame;
@@ -459,8 +443,6 @@ export function buildColumnSchedule(input: {
assert(input.items.variant === "column", "Column Schedule requires Column Items.");
assert(input.items.items.length > 0, "Column requires at least one Item.");
assertColumnWindowCandidateSet(input.candidates);
- assert(input.outer.source.kind === "selection" || input.outer.source.kind === "segment",
- "Column outer window must come from a Selection or Segment.");
frame(input.outer.span.startFrame, "Column outer window start");
frame(input.outer.span.endFrameExclusive, "Column outer window end");
assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, "Column outer window is empty.");
diff --git a/packages/ranking/src/surface.ts b/packages/ranking/src/surface.ts
index 8efc22ee..aa90d1f9 100644
--- a/packages/ranking/src/surface.ts
+++ b/packages/ranking/src/surface.ts
@@ -235,13 +235,13 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
} as unknown as CanonicalValue },
range: element.range,
});
- const terminalSpecId = `${id}.terminal.window`;
+ const terminalSpecId = `${id}.terminal.point`;
if (terminal !== undefined) records.push({
id: terminalSpecId,
- type: temporalTypes.windowSpec,
+ type: temporalTypes.pointSpec,
value: { kind: "inline", value: {
id: `${id}.terminal`,
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
+ projection: { ref: "moment.cue" },
} as unknown as CanonicalValue },
range: element.range,
});
@@ -276,17 +276,18 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
if (authored.content !== undefined) inputs[contentName!] = authored.content.ref;
const timingName = authored.timing === undefined ? undefined : `item-${suffix}-timing`;
if (authored.timing !== undefined) inputs[timingName!] = authored.timing.ref;
- const timingSpecName = authored.timing === undefined ? undefined : `item-${suffix}-window-spec`;
+ const timingSpecName = authored.timing === undefined ? undefined
+ : `item-${suffix}-${variant === "column" ? "window" : "point"}-spec`;
if (authored.timing !== undefined) {
- const timingSpecId = `${id}.item.${suffix}.window`;
+ const timingSpecId = `${id}.item.${suffix}.${variant === "column" ? "window" : "point"}`;
records.push({
id: timingSpecId,
- type: temporalTypes.windowSpec,
+ type: variant === "column" ? temporalTypes.windowSpec : temporalTypes.pointSpec,
value: { kind: "inline", value: {
id: `${id}.item.${suffix}`,
projection: variant === "column"
? { start: { ref: "selection.start" }, end: { ref: "selection.end" } }
- : { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
+ : { ref: "moment.cue" },
} as unknown as CanonicalValue },
range: child.range,
});
diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.ts
index 0d7f2676..c46e8d54 100644
--- a/packages/ranking/src/types.ts
+++ b/packages/ranking/src/types.ts
@@ -5,7 +5,7 @@ import type {
} from "@hypit/media";
import type { BlobRef } from "@hypit/protocol";
import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
-import type { TemporalWindow } from "@hypit/temporal";
+import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";
export type RankingVariant = "tier-board" | "column" | "top-three";
@@ -32,7 +32,7 @@ export type TriggeredRankingSchedule = {
export type TriggeredRankingCandidate = {
readonly itemId: string;
- readonly window: TemporalWindow;
+ readonly activation: TemporalPoint;
};
export type TriggeredRankingCandidateSet = {
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index 23226eed..2a8296b3 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -19,11 +19,11 @@ import {
appendRankingSound,
appendTierBoardItem,
appendTopThreeItem,
- appendTriggeredRankingCandidateWindow,
+ appendTriggeredRankingCandidate as appendProjectedTriggeredRankingCandidate,
buildColumnProgram,
buildColumnSchedule,
buildColumnSoundEvents,
- buildRankingScheduleFromWindows,
+ buildTriggeredRankingSchedule,
buildTierBoardProgram,
buildTierBoardSoundEvents,
buildTopThreeProgram,
@@ -71,7 +71,7 @@ import { semanticTrackTypes } from "@hypit/semantic-track";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { sealText, textManifest, textTypes } from "@hypit/text";
-import { projectMomentWindow, projectSegmentWindow, projectSelectionWindow } from "@hypit/temporal";
+import { projectMomentPoint, projectSegmentWindow, projectSelectionWindow } from "@hypit/temporal";
import type { TemporalWindow } from "@hypit/temporal";
import type {
StructuredElement,
@@ -168,9 +168,9 @@ function appendTriggeredRankingCandidate(
set: ReturnType<typeof createTriggeredRankingCandidateSet>, spec: RankingItemSpec,
semantic: typeof semanticTrack, moment: NarrativeMomentRef,
) {
- return appendTriggeredRankingCandidateWindow(set, spec, projectMomentWindow({
+ return appendProjectedTriggeredRankingCandidate(set, spec, projectMomentPoint({
itemId: spec.id, semantic, moment,
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
+ projection: { ref: "moment.cue" },
}));
}
@@ -182,18 +182,18 @@ function buildRankingSchedule(input: {
readonly candidates: TriggeredRankingCandidateSet;
readonly terminal: NarrativeMomentRef;
}): TriggeredRankingSchedule {
- return buildRankingScheduleFromWindows({
+ return buildTriggeredRankingSchedule({
header: input.header,
items: input.items,
- semantic: input.semantic,
+ space,
outer: projectSelectionWindow({
itemId: input.outer.id, semantic: input.semantic, selection: input.outer,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}),
candidates: input.candidates,
- terminal: projectMomentWindow({
+ terminal: projectMomentPoint({
itemId: input.terminal.id, semantic: input.semantic, moment: input.terminal,
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "frames", value: 1 } } },
+ projection: { ref: "moment.cue" },
}),
});
}
diff --git a/packages/studio-adapter/README.md b/packages/studio-adapter/README.md
index 520cbdce..2369e94b 100644
--- a/packages/studio-adapter/README.md
+++ b/packages/studio-adapter/README.md
@@ -4,6 +4,11 @@ The stable companion-package ABI understood by Hypit Studio. It carries only
presentation, lineage, inspector and interaction DTOs plus helpers that do not
encode the official video UI policy. Domain packages do not depend on it.
+`StudioAdapterContext.temporalBindings` exposes the executed Point/Window records in the selected
+Track closure, including projection expressions, source identity and direct consumer inputs.
+`temporalLineageFor()` joins a domain entity to those edges through the identity of a value consumed
+beside the projection; it does not inspect author attribute names.
+
A project companion contributes package-local adapter ids through
`createStudioAdapterHostFacet()`. The Host qualifies them with the selected
physical package identity, so executable package code cannot impersonate an
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index f0f46ca6..542c66a5 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -18,13 +18,22 @@ export type StudioTemporalSource = {
readonly id?: string;
};
-export type StudioTemporalProjection = {
+export type StudioTemporalPointProjection = {
+ readonly kind: "point";
+ readonly expression: string;
+ readonly frame: number;
+};
+
+export type StudioTemporalWindowProjection = {
+ readonly kind: "window";
readonly startExpression: string;
readonly endExpression: string;
readonly startFrame: number;
readonly endFrameExclusive: number;
};
+export type StudioTemporalProjection = StudioTemporalPointProjection | StudioTemporalWindowProjection;
+
export type StudioTemporalPhase = {
readonly id: string;
readonly label: string;
@@ -39,6 +48,31 @@ export type StudioTemporalLineage = {
readonly phases: readonly StudioTemporalPhase[];
};
+export type StudioTemporalConsumerInput = {
+ readonly name: string;
+ readonly record: string;
+ readonly type: { readonly module: { readonly name: string; readonly version: string }; readonly name: string };
+ readonly value?: unknown;
+};
+
+export type StudioTemporalConsumer = {
+ readonly step: string;
+ readonly producer: { readonly module: { readonly name: string; readonly version: string }; readonly name: string };
+ readonly input: string;
+ readonly inputs: readonly StudioTemporalConsumerInput[];
+};
+
+/** One executed Point/Window and the graph edges that consumed that exact record. */
+export type StudioTemporalBinding = {
+ readonly record: string;
+ readonly specRecord?: string;
+ readonly specId?: string;
+ readonly id: string;
+ readonly source: StudioTemporalSource;
+ readonly projection: StudioTemporalProjection;
+ readonly consumers: readonly StudioTemporalConsumer[];
+};
+
export type StudioInteraction = {
readonly select: boolean;
readonly seek: "start" | "pointer" | "none";
@@ -310,6 +344,8 @@ export type StudioAdapterContext = {
readonly surfacePreview?: StudioMaterialPreview;
readonly spans: readonly StudioSpan[];
readonly values: ReadonlyMap<string, unknown>;
+ /** Temporal values in this Track's actual executed dependency closure. */
+ readonly temporalBindings: readonly StudioTemporalBinding[];
readonly semantic: StudioSemanticTimeline;
readonly generic: () => readonly StudioEntityDraft[];
};
@@ -413,6 +449,35 @@ export function sameSurfaceValue(context: StudioAdapterContext, port: string): u
return ref === undefined ? undefined : context.values.get(ref);
}
+function carriesIdentity(value: unknown, id: string): boolean {
+ return value !== null && typeof value === "object"
+ && !Array.isArray(value) && (value as { readonly id?: unknown }).id === id;
+}
+
+/** Find executed projections directly consumed beside a domain value with this identity. */
+export function temporalBindingsFor(
+ context: StudioAdapterContext,
+ subjectId: string,
+ input?: string,
+): readonly StudioTemporalBinding[] {
+ return context.temporalBindings.filter((binding) => binding.consumers.some((consumer) =>
+ (input === undefined || consumer.input === input)
+ && consumer.inputs.some((candidate) => carriesIdentity(candidate.value, subjectId))));
+}
+
+export function temporalLineageFor(
+ context: StudioAdapterContext,
+ subjectId: string,
+ input?: string,
+): StudioTemporalLineage | undefined {
+ const found = temporalBindingsFor(context, subjectId, input)[0];
+ return found === undefined ? undefined : {
+ source: found.source,
+ projection: found.projection,
+ phases: [],
+ };
+}
+
export function childEntities(
context: StudioAdapterContext,
items: readonly { readonly id: string; readonly startFrame: number; readonly endFrameExclusive: number; readonly stackOrder: number }[],
diff --git a/packages/studio-video-adapters/README.md b/packages/studio-video-adapters/README.md
index 146f59bf..0e0976bb 100644
--- a/packages/studio-video-adapters/README.md
+++ b/packages/studio-video-adapters/README.md
@@ -6,3 +6,8 @@ Media, Audio, Text, Caption, Ranking and generic terminal Track fallbacks.
This package owns video-specific lane ranges, entity projection and timeline
semantics. `@hypit/studio` owns session assembly and uniform UI chrome. Author
and domain packages know neither package exists.
+
+Temporal presentation consumes Studio's executed-graph bindings. Window-backed Items show their
+actual endpoints, while Deck activations, Media Sequence terminals and triggered Ranking Items show
+their actual Point expression. The adapters do not recreate projection lineage from markup or
+renderer naming conventions.
diff --git a/packages/studio-video-adapters/src/deck.ts b/packages/studio-video-adapters/src/deck.ts
index 8bd75b78..567a960b 100644
--- a/packages/studio-video-adapters/src/deck.ts
+++ b/packages/studio-video-adapters/src/deck.ts
@@ -1,5 +1,5 @@
import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { readonlyInteraction, sameSurfaceValue } from "@hypit/studio-adapter";
+import { readonlyInteraction, sameSurfaceValue, temporalLineageFor } from "@hypit/studio-adapter";
import { videoLaneHeights } from "./presentation.js";
type DepthStackProgram = {
@@ -16,8 +16,8 @@ function projectDeck(context: StudioAdapterContext): readonly StudioEntityDraft[
child.id === undefined ? [] : [[child.id, child] as const]));
return cards.map((card, index): StudioEntityDraft => {
const child = children.get(card.id);
- const markerId = child?.referenceAttributes.at?.split(".").at(-1)
- ?? child?.referenceAttributes.moment?.split(".").at(-1);
+ const temporal = temporalLineageFor(context, card.id, "activation");
+ const markerId = temporal?.source.id;
const endFrameExclusive = cards[index + 1]?.activationFrame ?? program.terminalFrame;
const render = context.spans.find((span) => span.id === card.id
|| span.id.startsWith(`${card.id}:`) || span.id.startsWith(`${card.id}#`));
@@ -32,16 +32,7 @@ function projectDeck(context: StudioAdapterContext): readonly StudioEntityDraft[
...(child === undefined ? {} : { elementRange: child.range }),
...(render === undefined ? {} : { presentId: render.id, renderIds: [render.id] }),
presentation: { entity: "deck-card", shape: "picture", depth: 0 },
- temporal: {
- source: { kind: "moment", ...(markerId === undefined ? {} : { id: markerId }) },
- projection: {
- startExpression: "moment.cue",
- endExpression: "next moment / terminal",
- startFrame: card.activationFrame,
- endFrameExclusive,
- },
- phases: [],
- },
+ ...(temporal === undefined ? {} : { temporal }),
interaction: readonlyInteraction,
};
});
diff --git a/packages/studio-video-adapters/src/generic.ts b/packages/studio-video-adapters/src/generic.ts
index 174e4e7b..7747ed11 100644
--- a/packages/studio-video-adapters/src/generic.ts
+++ b/packages/studio-video-adapters/src/generic.ts
@@ -94,11 +94,12 @@ function projectText(context: StudioAdapterContext): readonly StudioEntityDraft[
if (item === undefined) return entity;
const document = program.items?.[index]?.document;
const label = document === undefined ? "" : textOf(document);
- const temporal = itemTemporalLineage({
- runtimeId: item.id, span: item,
- ...(context.placement === undefined ? {} : { placement: context.placement }),
- });
- const named = label.length === 0 ? entity : { ...entity, label };
+ const temporal = itemTemporalLineage(context, item.id);
+ const named = {
+ ...entity,
+ ...(label.length === 0 ? {} : { label }),
+ ...(temporal?.source.kind === "program" || temporal?.source.id === undefined ? {} : { markerId: temporal.source.id }),
+ };
return temporal === undefined ? named : { ...named, temporal };
});
}
diff --git a/packages/studio-video-adapters/src/media.ts b/packages/studio-video-adapters/src/media.ts
index 188536c2..f8902b1e 100644
--- a/packages/studio-video-adapters/src/media.ts
+++ b/packages/studio-video-adapters/src/media.ts
@@ -62,23 +62,23 @@ function projectMedia(context: StudioAdapterContext): readonly StudioEntityDraft
...(program.items ?? []).map((item) => ({
id: item.id, startFrame: item.span.startFrame, endFrameExclusive: item.span.endFrameExclusive,
stackOrder: item.stacking.order, preview: materialPreview(item.layers, facet, item.sourceAudio?.fromLayer),
+ temporalInput: "window",
})),
...(program.sequences ?? []).map((item) => ({
id: item.id, startFrame: item.span.startFrame, endFrameExclusive: item.span.endFrameExclusive,
stackOrder: item.stacking.order,
preview: materialPreview(item.members?.[0]?.layers, facet, item.members?.[0]?.sourceAudio?.fromLayer),
+ temporalInput: "terminal",
})),
];
return childEntities(context, items, "media-item",
context.track.type === "AudioTrack" ? "waveform" : "picture").map((entity, index) => {
const item = items[index];
if (item === undefined) return entity;
- const temporal = itemTemporalLineage({
- runtimeId: item.id, span: item,
- ...(context.placement === undefined ? {} : { placement: context.placement }),
- });
+ const temporal = itemTemporalLineage(context, item.id, item.temporalInput);
return {
...entity,
+ ...(temporal?.source.kind === "program" || temporal?.source.id === undefined ? {} : { markerId: temporal.source.id }),
...(item.preview === undefined ? {} : { preview: item.preview }),
...(temporal === undefined ? {} : { temporal }),
};
diff --git a/packages/studio-video-adapters/src/ranking.ts b/packages/studio-video-adapters/src/ranking.ts
index 6c5a1a8c..2cadbb2d 100644
--- a/packages/studio-video-adapters/src/ranking.ts
+++ b/packages/studio-video-adapters/src/ranking.ts
@@ -1,16 +1,23 @@
import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { readonlyInteraction } from "@hypit/studio-adapter";
+import { readonlyInteraction, temporalLineageFor } from "@hypit/studio-adapter";
import { frameParameters } from "./geometry.js";
type RankingSchedule = {
readonly variant?: string;
readonly outer?: { readonly startFrame: number; readonly endFrameExclusive: number };
+ readonly terminalFrame?: number;
readonly entries?: readonly ({ readonly itemId: string; readonly mode: "preset"; readonly settled: Span } | {
readonly itemId: string;
readonly mode: "reveal";
readonly preferred: Span;
readonly active: Span;
readonly settled: Span;
+ } | {
+ readonly itemId: string;
+ readonly triggerFrame: number;
+ readonly stage: Span;
+ readonly cumulative: Span;
+ readonly settled: Span;
})[];
};
@@ -46,17 +53,15 @@ function projectRanking(context: StudioAdapterContext): readonly StudioEntityDra
const placement = context.placement;
const scheduleRef = context.track.trace.outputPorts.find((port) => port.name === "schedule")?.ref;
const schedule = scheduleRef === undefined ? undefined : context.values.get(scheduleRef) as RankingSchedule | undefined;
- if (placement === undefined || schedule?.outer === undefined || schedule.variant !== "column") return context.generic();
+ if (placement === undefined || schedule?.outer === undefined) return context.generic();
const boardId = placement.id ?? context.track.outputRef;
const parent = `${context.track.outputRef}:entity:${boardId}`;
- const outerMarkerId = placement.referenceAttributes.during?.split(".").at(-1);
- const outerSourceType = placement.referenceTypes.during;
- const outerSourceKind = outerSourceType === "NarrativeExcerpt" ? "segment" as const : "selection" as const;
- const outerStartExpression = outerSourceKind === "segment" ? "segment.start" : "selection.start";
- const outerEndExpression = outerSourceKind === "segment" ? "segment.end" : "selection.end";
+ const outerTemporal = temporalLineageFor(context, boardId, "outer");
+ const outerMarkerId = outerTemporal?.source.id;
const group: StudioEntityDraft = {
id: parent,
authoredId: boardId,
+ ...(outerMarkerId === undefined ? {} : { markerId: outerMarkerId }),
label: boardId,
startFrame: schedule.outer.startFrame,
endFrameExclusive: schedule.outer.endFrameExclusive,
@@ -64,45 +69,31 @@ function projectRanking(context: StudioAdapterContext): readonly StudioEntityDra
elementRange: placement.range,
renderIds: context.spans.map((span) => span.id),
presentation: { entity: "ranking", shape: "group", depth: 0 },
- temporal: {
- source: { kind: outerSourceKind, ...(outerMarkerId === undefined ? {} : { id: outerMarkerId }) },
- projection: {
- startExpression: outerStartExpression,
- endExpression: outerEndExpression,
- ...schedule.outer,
- },
- phases: [],
- },
+ ...(outerTemporal === undefined ? {} : { temporal: outerTemporal }),
interaction: readonlyInteraction,
};
const children = new Map(placement.children.flatMap((child) =>
child.id === undefined ? [] : [[child.id, child] as const]));
const reveals = (schedule.entries ?? []).flatMap((entry): readonly StudioEntityDraft[] => {
- if (entry.mode !== "reveal") return [];
+ if ("mode" in entry && entry.mode !== "reveal") return [];
const child = children.get(entry.itemId);
- const markerId = child?.referenceAttributes.during?.split(".").at(-1);
+ const temporal = temporalLineageFor(context, entry.itemId, "mode" in entry ? "window" : "activation");
+ const markerId = temporal?.source.id;
const preview = itemPreview(context, entry.itemId);
+ const visible = "mode" in entry ? entry.active : entry.cumulative;
return [{
id: `${context.track.outputRef}:entity:${entry.itemId}`,
authoredId: entry.itemId,
...(markerId === undefined ? {} : { markerId }),
label: child?.attributes.label ?? entry.itemId,
- startFrame: entry.active.startFrame,
- endFrameExclusive: entry.active.endFrameExclusive,
+ startFrame: visible.startFrame,
+ endFrameExclusive: visible.endFrameExclusive,
stackOrder: group.stackOrder + 1,
...(child === undefined ? {} : { elementRange: child.range }),
...(preview === undefined ? {} : { preview }),
- lane: "reveal",
+ lane: "mode" in entry ? "reveal" : "activation",
presentation: { entity: "ranking-reveal", shape: "picture", depth: 0 },
- temporal: {
- source: { kind: "selection", ...(markerId === undefined ? {} : { id: markerId }) },
- projection: {
- startExpression: "selection.start",
- endExpression: "selection.end",
- ...entry.preferred,
- },
- phases: [],
- },
+ ...(temporal === undefined ? {} : { temporal }),
interaction: readonlyInteraction,
}];
}).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id));
@@ -156,4 +147,32 @@ export const rankingAdapters: readonly StudioAdapter[] = [
}],
interaction: readonlyInteraction, project: projectRanking,
},
+ ...([[
+ "ranking-tier", "tier", "Tier Board",
+ ], [
+ "ranking-top-three", "top-three", "Top Three",
+ ]] as const).map(([id, surface, label]): StudioAdapter => ({
+ id, role: "track",
+ output: { type: "VisualTrack", surface, modules: ["@hypit/ranking"] },
+ family: "component", label, icon: "ranking", realizationPorts: ["schedule"],
+ parameters: [
+ { name: "semantic", label: "Semantic", writable: false },
+ { name: "style", label: "Style", writable: false },
+ { name: "during", label: "During", writable: false },
+ { name: "terminal", label: "Terminal", writable: false },
+ { name: "at", label: "At", writable: false },
+ { name: "frame", label: "Frame", writable: false, referenced: frameParameters },
+ { name: "label", label: "Label", writable: true },
+ { name: "icon", label: "Icon", writable: false },
+ ],
+ poster: { source: "surface-preview" },
+ lane: { layout: "flat", height: { minPx: 64, preferredPx: 80, maxPx: 112 }, groupId: `${id}-activations` },
+ attachments: [{
+ id: "activation", family: "ranking-reveal", label: "Activations", icon: "ranking", facet: "visual",
+ lane: { layout: "flat", height: { minPx: 34, preferredPx: 40, maxPx: 56 } },
+ parameters: [{ name: "at", label: "At", writable: false }],
+ }],
+ interaction: readonlyInteraction,
+ project: projectRanking,
+ })),
];
diff --git a/packages/studio-video-adapters/src/temporal.ts b/packages/studio-video-adapters/src/temporal.ts
index a41da28e..2ef1e9aa 100644
--- a/packages/studio-video-adapters/src/temporal.ts
+++ b/packages/studio-video-adapters/src/temporal.ts
@@ -1,109 +1,11 @@
-import type {
- StudioPlacement as Placement,
- StudioTemporalLineage,
- StudioTemporalProjection,
- StudioTemporalSource,
-} from "@hypit/studio-adapter";
-
-type Point = {
- readonly ref: "program.start" | "program.end" | "selection.start" | "selection.end" | "segment.start" | "segment.end" | "moment.cue" | "absolute";
- readonly offset?: unknown;
- readonly at?: unknown;
-};
-
-type Projection = { readonly start: Point; readonly end: Point };
-type Spec = { readonly id?: string; readonly projection?: Projection };
-
-function valueOf(child: Placement["children"][number]): Spec | undefined {
- const found = child.values.find((value) => value.type.name === "MediaItemSpec"
- || value.type.name === "TextItemSpec" || value.type.name === "PlainTextItemSpec");
- return found?.value as Spec | undefined;
-}
-
-function authoredId(runtimeId: string, children: readonly Placement["children"][number][]): string | undefined {
- return children
- .filter((child): child is Placement["children"][number] & { readonly id: string } => child.id !== undefined)
- .map((child) => child.id)
- .sort((left, right) => right.length - left.length)
- .find((id) => runtimeId === id || runtimeId.startsWith(`${id}::`));
-}
-
-function expression(point: Point): string {
- if (point.ref === "absolute") return duration(point.at);
- return point.offset === undefined ? point.ref : `${point.ref}${signed(point.offset)}`;
-}
-
-function duration(value: unknown): string {
- const item = value as { readonly unit?: string; readonly value?: number; readonly numerator?: number; readonly denominator?: number } | undefined;
- if (item?.unit === "frames") return `${item.value ?? 0}f`;
- if (item?.unit === "milliseconds") return `${item.value ?? 0}ms`;
- if (item?.unit === "seconds") return item.denominator === 1
- ? `${item.numerator ?? 0}s`
- : `${item.numerator ?? 0}/${item.denominator ?? 1}s`;
- return "?";
-}
-
-function signed(value: unknown): string {
- const item = value as { readonly unit?: string; readonly value?: number; readonly numerator?: number } | undefined;
- if (item === undefined) return "+?";
- const negative = item?.unit === "seconds" ? (item.numerator ?? 0) < 0 : (item?.value ?? 0) < 0;
- if (!negative) return `+${duration(value)}`;
- if (item?.unit === "seconds") return `-${duration({ ...item, numerator: Math.abs(item.numerator ?? 0) })}`;
- return `-${duration({ ...item, value: Math.abs(item.value ?? 0) })}`;
-}
-
-function markerId(child: Placement["children"][number]): string | undefined {
- const path = child.referenceAttributes.during
- ?? child.referenceAttributes.selection
- ?? child.referenceAttributes.segment
- ?? child.referenceAttributes.at
- ?? child.referenceAttributes.moment;
- return path?.slice(path.lastIndexOf(".") + 1);
-}
-
-function sourceOf(
- child: Placement["children"][number],
- projection: Projection,
-): StudioTemporalSource {
- const marker = markerId(child);
- const refs = [projection.start.ref, projection.end.ref];
- const sourceType = child.referenceTypes.during ?? child.referenceTypes.selection
- ?? child.referenceTypes.segment ?? child.referenceTypes.at ?? child.referenceTypes.moment;
- const kind = sourceType === "NarrativeSelection" || refs.some((ref) => ref.startsWith("selection."))
- ? "selection"
- : sourceType === "NarrativeExcerpt" || refs.some((ref) => ref.startsWith("segment."))
- ? "segment"
- : sourceType === "NarrativeMoment" || refs.some((ref) => ref === "moment.cue")
- ? "moment"
- : "program";
- return {
- kind,
- ...(marker === undefined ? {} : { id: marker }),
- };
-}
-
-/**
- * Join one resolved Program item back to the exact child-authored projection.
- * The Program supplies the frame truth; the observed inline Spec supplies the
- * endpoint expressions. Nothing here evaluates or reimplements Temporal.
- */
-export function itemTemporalLineage(input: {
- readonly runtimeId: string;
- readonly span: { readonly startFrame: number; readonly endFrameExclusive: number };
- readonly placement?: Placement;
-}): StudioTemporalLineage | undefined {
- const children = input.placement?.children ?? [];
- const id = authoredId(input.runtimeId, children);
- const child = id === undefined ? undefined : children.find((candidate) => candidate.id === id);
- const spec = child === undefined ? undefined : valueOf(child);
- const projection = spec?.projection;
- if (child === undefined || projection === undefined) return undefined;
- const source = sourceOf(child, projection);
- const projected: StudioTemporalProjection = {
- startExpression: expression(projection.start),
- endExpression: expression(projection.end),
- startFrame: input.span.startFrame,
- endFrameExclusive: input.span.endFrameExclusive,
- };
- return { source, projection: projected, phases: [] };
+import type { StudioAdapterContext, StudioTemporalLineage } from "@hypit/studio-adapter";
+import { temporalLineageFor } from "@hypit/studio-adapter";
+
+/** Resolve a domain item's Window from the executed edge that consumed it. */
+export function itemTemporalLineage(
+ context: StudioAdapterContext,
+ runtimeId: string,
+ input = "window",
+): StudioTemporalLineage | undefined {
+ return temporalLineageFor(context, runtimeId, input);
}
diff --git a/packages/studio/src/programme.ts b/packages/studio/src/programme.ts
index 5d0557c5..7402147b 100644
--- a/packages/studio/src/programme.ts
+++ b/packages/studio/src/programme.ts
@@ -6,7 +6,7 @@ import {
semanticTrackSpans,
} from "@hypit/semantic-track";
import type { SemanticTrack } from "@hypit/semantic-track";
-import type { StudioResolvedTrack } from "@hypit/studio-adapter";
+import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-adapter";
import type { StudioArchive } from "./archive.js";
import type { CompiledSource, ServedFile } from "./compile.js";
@@ -15,6 +15,7 @@ import { executeDeterministic, MemoryArtifactStore } from "./execute.js";
import type { RunPlan } from "./run.js";
import type { StudioProjection } from "./studio-preflight.js";
import { studioSurfacePreview } from "./surface-preview.js";
+import { executedTemporalBindings } from "./temporal-graph.js";
const PLAYABLE = new Set(["VisualTrack", "AudioTrack"]);
const TIMING = "SemanticTrack";
@@ -26,6 +27,7 @@ export type Preview = {
readonly tracks: readonly BuiltTrack[];
/** Resolved adapter realizations keyed by exact graph output ref. */
readonly values: ReadonlyMap<string, unknown>;
+ readonly temporalBindings: ReadonlyMap<string, readonly StudioTemporalBinding[]>;
readonly composition: Composition;
readonly timing: "measured";
readonly timingOutput?: { readonly name: string; readonly ref: string };
@@ -201,6 +203,10 @@ export async function preview(input: {
value: stored.value,
}];
});
+ const temporalBindings = new Map(tracks.map((track) => [
+ track.outputRef,
+ executedTemporalBindings(executed.state, track.outputRef),
+ ] as const));
const values = new Map<string, unknown>();
for (const target of targets) {
const stored = selectedValue(executed.state, target.ref);
@@ -234,6 +240,7 @@ export async function preview(input: {
source: input.source,
tracks,
values,
+ temporalBindings,
composition,
timing: "measured",
timingOutput: { name: timingOutput.name, ref: timingOutput.ref },
diff --git a/packages/studio/src/snapshot.ts b/packages/studio/src/snapshot.ts
index 94812f42..b14421bd 100644
--- a/packages/studio/src/snapshot.ts
+++ b/packages/studio/src/snapshot.ts
@@ -336,6 +336,7 @@ export function snapshot(registry: StudioAdapterRegistry, built: Preview, input:
...(item.surfacePreview === undefined ? {} : { surfacePreview: item.surfacePreview }),
spans: projectedSpans,
values: built.values,
+ temporalBindings: built.temporalBindings.get(item.outputRef) ?? [],
semantic,
generic,
}).map((draft) => {
diff --git a/packages/studio/src/temporal-graph.ts b/packages/studio/src/temporal-graph.ts
new file mode 100644
index 00000000..d4889d18
--- /dev/null
+++ b/packages/studio/src/temporal-graph.ts
@@ -0,0 +1,189 @@
+import type { BuildState, ProducerStep, StoredValue, TypedRecord } from "@hypit/protocol";
+import type {
+ StudioTemporalBinding,
+ StudioTemporalProjection,
+ StudioTemporalSource,
+} from "@hypit/studio-adapter";
+
+const TEMPORAL_MODULE = "@hypit/temporal";
+const TEMPORAL_TYPES = new Set(["TemporalPoint", "TemporalWindow"]);
+
+type PointExpression = {
+ readonly ref?: string;
+ readonly offset?: unknown;
+ readonly at?: unknown;
+};
+
+function inline(value: StoredValue): unknown | undefined {
+ return value.kind === "inline" ? value.value : undefined;
+}
+
+function duration(value: unknown): string {
+ const item = value as {
+ readonly unit?: string;
+ readonly value?: number;
+ readonly numerator?: number;
+ readonly denominator?: number;
+ } | undefined;
+ if (item?.unit === "frames") return `${item.value ?? 0}f`;
+ if (item?.unit === "milliseconds") return `${item.value ?? 0}ms`;
+ if (item?.unit === "seconds") return item.denominator === 1
+ ? `${item.numerator ?? 0}s`
+ : `${item.numerator ?? 0}/${item.denominator ?? 1}s`;
+ return "?";
+}
+
+function signed(value: unknown): string {
+ const item = value as { readonly unit?: string; readonly value?: number; readonly numerator?: number } | undefined;
+ if (item === undefined) return "+?";
+ const negative = item.unit === "seconds" ? (item.numerator ?? 0) < 0 : (item.value ?? 0) < 0;
+ if (!negative) return `+${duration(value)}`;
+ return item.unit === "seconds"
+ ? `-${duration({ ...item, numerator: Math.abs(item.numerator ?? 0) })}`
+ : `-${duration({ ...item, value: Math.abs(item.value ?? 0) })}`;
+}
+
+function expression(value: unknown): string {
+ const point = value as PointExpression;
+ if (point.ref === "absolute") return duration(point.at);
+ if (typeof point.ref !== "string") return "?";
+ return point.offset === undefined ? point.ref : `${point.ref}${signed(point.offset)}`;
+}
+
+function source(value: unknown): StudioTemporalSource | undefined {
+ const held = value as { readonly kind?: unknown; readonly id?: unknown } | undefined;
+ if (held?.kind !== "program" && held?.kind !== "selection"
+ && held?.kind !== "segment" && held?.kind !== "moment") return undefined;
+ return {
+ kind: held.kind,
+ ...(typeof held.id === "string" ? { id: held.id } : {}),
+ };
+}
+
+function projection(record: TypedRecord): {
+ readonly id: string;
+ readonly source: StudioTemporalSource;
+ readonly projection: StudioTemporalProjection;
+} | undefined {
+ const held = inline(record.value) as {
+ readonly id?: unknown;
+ readonly source?: unknown;
+ readonly projection?: unknown;
+ readonly frame?: unknown;
+ readonly span?: { readonly startFrame?: unknown; readonly endFrameExclusive?: unknown };
+ } | undefined;
+ const temporalSource = source(held?.source);
+ if (typeof held?.id !== "string" || temporalSource === undefined) return undefined;
+ if (record.type.name === "TemporalPoint") {
+ if (!Number.isSafeInteger(held.frame)) return undefined;
+ return {
+ id: held.id,
+ source: temporalSource,
+ projection: {
+ kind: "point",
+ expression: expression(held.projection),
+ frame: held.frame as number,
+ },
+ };
+ }
+ const window = held.projection as { readonly start?: unknown; readonly end?: unknown } | undefined;
+ if (!Number.isSafeInteger(held.span?.startFrame) || !Number.isSafeInteger(held.span?.endFrameExclusive)) return undefined;
+ return {
+ id: held.id,
+ source: temporalSource,
+ projection: {
+ kind: "window",
+ startExpression: expression(window?.start),
+ endExpression: expression(window?.end),
+ startFrame: held.span!.startFrame as number,
+ endFrameExclusive: held.span!.endFrameExclusive as number,
+ },
+ };
+}
+
+function recordIndex(state: BuildState): ReadonlyMap<string, TypedRecord> {
+ return new Map([...state.program.records, ...state.records].map((record) => [record.id, record] as const));
+}
+
+function producingSteps(state: BuildState): ReadonlyMap<string, ProducerStep> {
+ return new Map(state.plan.steps.flatMap((step) =>
+ Object.values(step.outputs).map((record) => [record, step] as const)));
+}
+
+function closure(state: BuildState, output: string): ReadonlySet<string> {
+ const selected = state.plan.selections.find((selection) => selection.output === output);
+ if (selected === undefined) return new Set();
+ const producers = producingSteps(state);
+ const steps = new Set<string>();
+ const records = new Set<string>();
+ const visit = (record: string): void => {
+ if (records.has(record)) return;
+ records.add(record);
+ const step = producers.get(record);
+ if (step === undefined || steps.has(step.id)) return;
+ steps.add(step.id);
+ for (const input of Object.values(step.inputs)) visit(input);
+ };
+ visit(selected.record);
+ return steps;
+}
+
+function specOf(step: ProducerStep | undefined, records: ReadonlyMap<string, TypedRecord>): {
+ readonly record: string;
+ readonly id: string;
+} | undefined {
+ const id = step?.inputs.spec;
+ if (id === undefined) return undefined;
+ const value = records.get(id);
+ const spec = value === undefined ? undefined : inline(value.value) as { readonly id?: unknown } | undefined;
+ return typeof spec?.id === "string" ? { record: id, id: spec.id } : undefined;
+}
+
+/**
+ * Read Temporal lineage from the exact executed dependency closure of one
+ * logical output. Projection and consumption are graph facts; source markup is
+ * deliberately not consulted here.
+ */
+export function executedTemporalBindings(
+ state: BuildState,
+ output: string,
+): readonly StudioTemporalBinding[] {
+ const records = recordIndex(state);
+ const producers = producingSteps(state);
+ const stepIds = closure(state, output);
+ const steps = state.plan.steps.filter((step) => stepIds.has(step.id));
+ return [...records.values()]
+ .filter((record) => record.type.module.name === TEMPORAL_MODULE && TEMPORAL_TYPES.has(record.type.name))
+ .flatMap((record): readonly StudioTemporalBinding[] => {
+ const projected = projection(record);
+ if (projected === undefined) return [];
+ const spec = specOf(producers.get(record.id), records);
+ const consumers = steps.flatMap((step) => Object.entries(step.inputs)
+ .filter(([, input]) => input === record.id)
+ .map(([input]) => ({
+ step: step.id,
+ producer: { module: { ...step.producer.module }, name: step.producer.name },
+ input,
+ inputs: Object.entries(step.inputs).flatMap(([name, id]) => {
+ const found = records.get(id);
+ if (found === undefined) return [];
+ const value = inline(found.value);
+ return [{
+ name,
+ record: id,
+ type: { module: { ...found.type.module }, name: found.type.name },
+ ...(value === undefined ? {} : { value: structuredClone(value) }),
+ }];
+ }).sort((left, right) => left.name.localeCompare(right.name)),
+ })));
+ if (consumers.length === 0) return [];
+ return [{
+ record: record.id,
+ ...(spec === undefined ? {} : { specRecord: spec.record, specId: spec.id }),
+ ...projected,
+ consumers: consumers.sort((left, right) => left.step.localeCompare(right.step)
+ || left.input.localeCompare(right.input)),
+ }];
+ })
+ .sort((left, right) => left.record.localeCompare(right.record));
+}
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index 7435e1c7..0d07dfdb 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -107,7 +107,7 @@ timeline.element.addEventListener("studio:write", (event) => {
// Program-level facts never change while a Source is being read, so they live in
// the header rather than taking a panel that would have to sit over something.
function renderMeta(snapshot: StudioSnapshot): void {
- project.textContent = snapshot.source.path.split("/").at(-1) ?? snapshot.source.path;
+ project.textContent = snapshot.source.path.split(/[\\/]/u).at(-1) ?? snapshot.source.path;
project.title = snapshot.source.path;
// Sequence facts belong to the project/inspector, not the application chrome.
// The timeline transport is the single persistent time readout.
@@ -317,10 +317,13 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
]);
const source = clip.temporal === undefined ? undefined : group("Binding", [
property("Source", `${clip.temporal.source.kind}${clip.temporal.source.id === undefined ? "" : ` · ${clip.temporal.source.id}`}`, "property-wide property-code"),
- ...(clip.temporal.projection === undefined ? [] : [
- property("From", clip.temporal.projection.startExpression, "property-wide property-code"),
- property("To", clip.temporal.projection.endExpression, "property-wide property-code"),
- ]),
+ ...(clip.temporal.projection === undefined ? []
+ : clip.temporal.projection.kind === "point"
+ ? [property("At", clip.temporal.projection.expression, "property-wide property-code")]
+ : [
+ property("From", clip.temporal.projection.startExpression, "property-wide property-code"),
+ property("To", clip.temporal.projection.endExpression, "property-wide property-code"),
+ ]),
]);
const run = track === undefined ? undefined : group("Run", [
property("Run", snapshot.run.path, "property-wide property-code"),
diff --git a/packages/studio/test/temporal-graph.test.ts b/packages/studio/test/temporal-graph.test.ts
new file mode 100644
index 00000000..8eaaccc6
--- /dev/null
+++ b/packages/studio/test/temporal-graph.test.ts
@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { BuildState, ProducerStep, TypeRef, TypedRecord } from "@hypit/protocol";
+
+import { executedTemporalBindings } from "../src/temporal-graph.js";
+
+const module = (name: string) => ({ name, version: "1" });
+const type = (owner: string, name: string): TypeRef => ({ module: module(owner), name });
+const record = (id: string, owner: string, name: string, value: unknown): TypedRecord => ({
+ id, type: type(owner, name), value: { kind: "inline", value: value as never },
+});
+const producer = (owner: string, name: string) => ({ module: module(owner), name });
+const step = (id: string, owner: string, name: string, inputs: ProducerStep["inputs"], outputs: ProducerStep["outputs"]): ProducerStep => ({
+ id, producer: producer(owner, name), inputs, outputs, needs: {},
+});
+
+test("Studio reads Point lineage from the executed projection and consumption edges", () => {
+ const program = [
+ record("semantic", "@hypit/semantic-track", "SemanticTrack", { id: "speech" }),
+ record("moment", "@hypit/narrative", "NarrativeMoment", { id: "cue", anchorId: "cue-anchor" }),
+ record("point-spec", "@hypit/temporal", "TemporalPointSpec", { id: "deck.card", projection: { ref: "moment.cue" } }),
+ record("card-spec", "@hypit/deck-track", "DepthStackCardSpec", { id: "card" }),
+ ];
+ const executed = [
+ record("point", "@hypit/temporal", "TemporalPoint", {
+ id: "deck.card::cue", source: { kind: "moment", id: "cue" }, projection: { ref: "moment.cue" }, frame: 42,
+ }),
+ record("cards", "@hypit/deck-track", "DepthStackCardSet", { cards: [{ id: "card", activationFrame: 42 }] }),
+ record("track", "@hypit/composition", "VisualTrack", { presents: [] }),
+ record("unused-point", "@hypit/temporal", "TemporalPoint", {
+ id: "unused::cue", source: { kind: "moment", id: "cue" }, projection: { ref: "moment.cue" }, frame: 7,
+ }),
+ ];
+ const steps = [
+ step("project", "@hypit/temporal", "project-moment-point", { semantic: "semantic", moment: "moment", spec: "point-spec" }, { point: "point" }),
+ step("append", "@hypit/deck-track", "append-depth-stack-card", { set: "empty", spec: "card-spec", activation: "point" }, { set: "cards" }),
+ step("render", "@hypit/deck-track", "render-depth-stack", { program: "cards" }, { track: "track" }),
+ ];
+ const state = {
+ format: "hypit.build@1",
+ program: { closure: { modules: [] }, records: program },
+ graph: { format: "hypit.graph@1", outputs: [], candidates: [], operations: [] },
+ request: { format: "hypit.build-request@1", targets: [{ output: "visual" }] },
+ plan: {
+ format: "hypit.plan@1", steps, goals: [{ record: "track", type: type("@hypit/composition", "VisualTrack") }],
+ selections: [{ output: "visual", candidate: "visual-candidate", record: "track" }],
+ },
+ status: "complete", records: executed, steps: steps.map(({ id }) => ({ id, status: "complete" as const })),
+ needs: [], outstanding: [], diagnostics: [],
+ } as unknown as BuildState;
+
+ const bindings = executedTemporalBindings(state, "visual");
+ assert.equal(bindings.length, 1);
+ assert.deepEqual(bindings[0], {
+ record: "point",
+ specRecord: "point-spec",
+ specId: "deck.card",
+ id: "deck.card::cue",
+ source: { kind: "moment", id: "cue" },
+ projection: { kind: "point", expression: "moment.cue", frame: 42 },
+ consumers: [{
+ step: "append",
+ producer: producer("@hypit/deck-track", "append-depth-stack-card"),
+ input: "activation",
+ inputs: [
+ { name: "activation", record: "point", type: type("@hypit/temporal", "TemporalPoint"), value: executed[0]!.value.kind === "inline" ? executed[0]!.value.value : undefined },
+ { name: "spec", record: "card-spec", type: type("@hypit/deck-track", "DepthStackCardSpec"), value: { id: "card" } },
+ ],
+ }],
+ });
+});
diff --git a/packages/temporal/README.md b/packages/temporal/README.md
index 12abcb15..79caf385 100644
--- a/packages/temporal/README.md
+++ b/packages/temporal/README.md
@@ -1,14 +1,18 @@
# `@hypit/temporal`
-Focused video-domain temporal projection. It locates one authored Selection or Moment through
-`@hypit/semantic-track`, evaluates exact rational point expressions, intersects them with
-ProgramSpace and returns a validated half-open frame span.
-
-The graph-facing protocol is explicit: author surfaces publish a `TemporalWindowSpec`, the
-`@hypit/temporal` component projects it once to a `TemporalWindow`, and downstream components
-consume that value. A component does not receive a Selection or Moment to project internally.
-The resolved value retains its source identity and authored projection alongside the frame span,
-so a Studio or another consumer can trace the interval without inventing a second timing truth.
+Focused video-domain temporal projection. It locates one authored Program, Selection, Segment or
+Moment through `@hypit/semantic-track`, evaluates exact rational point expressions and projects
+them into ProgramSpace.
+
+The graph-facing protocol has two distinct results. `TemporalPointSpec -> TemporalPoint` preserves
+one frame boundary, including `program.end`; `TemporalWindowSpec -> TemporalWindow` preserves a
+non-empty half-open frame span. Author Surfaces emit the appropriate Spec and one `project-*-point`
+or `project-*` operation. Downstream components consume the projected value and ProgramSpace; they
+do not receive a Selection or Moment to locate internally.
+
+Both results retain source identity and the authored projection expression. Studio reads those
+executed records and their real consumer edges, so Point values are never disguised as one-frame
+Windows and no second timing truth is reconstructed from source attribute names.
The package also provides pure sibling-window validation and triggered-stage scheduling. It defines
no Core branch, renderer behavior, media playback policy, Provider or authoring super-program.
diff --git a/packages/temporal/src/component.ts b/packages/temporal/src/component.ts
index f7835db7..cb702da2 100644
--- a/packages/temporal/src/component.ts
+++ b/packages/temporal/src/component.ts
@@ -5,13 +5,17 @@ import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from
import type { SemanticTrack } from "@hypit/semantic-track";
import {
+ projectMomentPoint,
projectMomentWindow,
+ projectProgramPoint,
projectProgramWindow,
+ projectSegmentPoint,
projectSegmentWindow,
+ projectSelectionPoint,
projectSelectionWindow,
} from "./projection.js";
import { temporalProducers, temporalTypes } from "./index.js";
-import type { TemporalWindowSpec } from "./types.js";
+import type { TemporalPointSpec, TemporalWindowSpec } from "./types.js";
function inline<T>(value: StoredValue | undefined, label: string): T {
if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
@@ -20,34 +24,61 @@ function inline<T>(value: StoredValue | undefined, label: string): T {
const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-function spec(inputs: ProducerHandlerContext["inputs"]): TemporalWindowSpec {
+function windowSpec(inputs: ProducerHandlerContext["inputs"]): TemporalWindowSpec {
return inline<TemporalWindowSpec>(inputs.spec?.value, "TemporalWindowSpec");
}
+function pointSpec(inputs: ProducerHandlerContext["inputs"]): TemporalPointSpec {
+ return inline<TemporalPointSpec>(inputs.spec?.value, "TemporalPointSpec");
+}
+
export const temporalComponent = {
producers: [
+ { producer: temporalProducers.projectProgramPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectProgramPoint({
+ itemId: pointSpec(inputs).id,
+ semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ projection: pointSpec(inputs).projection,
+ })) }, needs: {} }) },
+ { producer: temporalProducers.projectSelectionPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectSelectionPoint({
+ itemId: pointSpec(inputs).id,
+ semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
+ projection: pointSpec(inputs).projection,
+ })) }, needs: {} }) },
+ { producer: temporalProducers.projectSegmentPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectSegmentPoint({
+ itemId: pointSpec(inputs).id,
+ semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
+ projection: pointSpec(inputs).projection,
+ })) }, needs: {} }) },
+ { producer: temporalProducers.projectMomentPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectMomentPoint({
+ itemId: pointSpec(inputs).id,
+ semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+ moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),
+ projection: pointSpec(inputs).projection,
+ })) }, needs: {} }) },
{ producer: temporalProducers.projectProgram, handler: ({ inputs }) => ({ outputs: { window: output(projectProgramWindow({
- itemId: spec(inputs).id,
+ itemId: windowSpec(inputs).id,
semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
- projection: spec(inputs).projection,
+ projection: windowSpec(inputs).projection,
})) }, needs: {} }) },
{ producer: temporalProducers.projectSelection, handler: ({ inputs }) => ({ outputs: { window: output(projectSelectionWindow({
- itemId: spec(inputs).id,
+ itemId: windowSpec(inputs).id,
semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
- projection: spec(inputs).projection,
+ projection: windowSpec(inputs).projection,
})) }, needs: {} }) },
{ producer: temporalProducers.projectSegment, handler: ({ inputs }) => ({ outputs: { window: output(projectSegmentWindow({
- itemId: spec(inputs).id,
+ itemId: windowSpec(inputs).id,
semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
- projection: spec(inputs).projection,
+ projection: windowSpec(inputs).projection,
})) }, needs: {} }) },
{ producer: temporalProducers.projectMoment, handler: ({ inputs }) => ({ outputs: { window: output(projectMomentWindow({
- itemId: spec(inputs).id,
+ itemId: windowSpec(inputs).id,
semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),
- projection: spec(inputs).projection,
+ projection: windowSpec(inputs).projection,
})) }, needs: {} }) },
],
} satisfies ComponentPackage;
diff --git a/packages/temporal/src/index.ts b/packages/temporal/src/index.ts
index c6d7fdde..a79a1339 100644
--- a/packages/temporal/src/index.ts
+++ b/packages/temporal/src/index.ts
@@ -37,10 +37,16 @@ export type * from "./types.js";
export const temporalModuleRef = { name: "@hypit/temporal", version: "1" } as const;
export const temporalTypes = {
+ pointSpec: { module: temporalModuleRef, name: "TemporalPointSpec" },
+ point: { module: temporalModuleRef, name: "TemporalPoint" },
windowSpec: { module: temporalModuleRef, name: "TemporalWindowSpec" },
window: { module: temporalModuleRef, name: "TemporalWindow" },
} satisfies Record<string, TypeRef>;
export const temporalProducers = {
+ projectProgramPoint: { module: temporalModuleRef, name: "project-program-point" },
+ projectSelectionPoint: { module: temporalModuleRef, name: "project-selection-point" },
+ projectSegmentPoint: { module: temporalModuleRef, name: "project-segment-point" },
+ projectMomentPoint: { module: temporalModuleRef, name: "project-moment-point" },
projectProgram: { module: temporalModuleRef, name: "project-program-window" },
projectSelection: { module: temporalModuleRef, name: "project-selection-window" },
projectSegment: { module: temporalModuleRef, name: "project-segment-window" },
@@ -52,11 +58,25 @@ export const temporalManifest: ModuleManifest = {
version: temporalModuleRef.version,
dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency],
types: [
+ { name: temporalTypes.pointSpec.name },
+ { name: temporalTypes.point.name },
{ name: temporalTypes.windowSpec.name },
{ name: temporalTypes.window.name },
],
capabilities: [],
producers: [
+ { name: temporalProducers.projectProgramPoint.name,
+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: temporalTypes.pointSpec }],
+ outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },
+ { name: temporalProducers.projectSelectionPoint.name,
+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.pointSpec }],
+ outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },
+ { name: temporalProducers.projectSegmentPoint.name,
+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.pointSpec }],
+ outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },
+ { name: temporalProducers.projectMomentPoint.name,
+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.pointSpec }],
+ outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },
{ name: temporalProducers.projectProgram.name,
inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: temporalTypes.windowSpec }],
outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },
@@ -73,6 +93,12 @@ export const temporalManifest: ModuleManifest = {
};
export const temporalDependency = { module: temporalModuleRef } as const;
+export const temporalPointSpecSchema: ValueSchema = object({
+ id: { schema: string }, projection: { schema: point },
+});
+export const temporalPointSchema: ValueSchema = object({
+ id: { schema: string }, source: { schema: sourceSchema }, projection: { schema: point }, frame: { schema: unsignedInteger },
+});
export const temporalWindowSpecSchema: ValueSchema = object({
id: { schema: string }, projection: { schema: projectionSchema },
});
diff --git a/packages/temporal/src/projection.ts b/packages/temporal/src/projection.ts
index 3c06dc88..6b6b4ab9 100644
--- a/packages/temporal/src/projection.ts
+++ b/packages/temporal/src/projection.ts
@@ -21,8 +21,10 @@ import type {
LocatedProgram,
LocatedSegment,
LocatedSelection,
+ ProjectedPoint,
ProjectedWindow,
TemporalSource,
+ TemporalPointSpec,
TemporalWindowSpec,
TemporalPointExpression,
TemporalWindowProjection,
@@ -103,6 +105,26 @@ export function projectTemporalWindow(
return { startFrame, endFrameExclusive };
}
+export function projectTemporalPoint(
+ projection: TemporalPointExpression,
+ environment: PointEnvironment,
+ space: ProgramSpace,
+): number {
+ assertProgramSpaceIdentity(space);
+ const totalFrames = programSpaceFrameCount(space);
+ const raw = evaluatePoint(projection, environment, space);
+ const lower = rational(0n);
+ const upper = rational(BigInt(totalFrames));
+ if (compare(raw, lower) < 0 || compare(raw, upper) > 0) {
+ throw new Error("Temporal point projection falls outside ProgramSpace.");
+ }
+ const frame = quantizeBoundary(raw);
+ if (frame < 0 || frame > totalFrames) {
+ throw new Error("Temporal point projection quantizes outside ProgramSpace.");
+ }
+ return frame;
+}
+
function projectedId(itemId: string, sourceId: string): string {
if (itemId.length === 0) throw new Error("Projected item id must not be empty.");
return `${itemId}::${sourceId}`;
@@ -121,6 +143,81 @@ function projectedWindow(
};
}
+function projectedPoint(
+ spec: TemporalPointSpec,
+ source: TemporalSource,
+ frame: number,
+): ProjectedPoint {
+ return {
+ id: projectedId(spec.id, source.id),
+ source: { ...source },
+ projection: structuredClone(spec.projection),
+ frame,
+ };
+}
+
+export function projectSelectionPoint(input: {
+ readonly itemId: string;
+ readonly semantic: SemanticTrack;
+ readonly selection: NarrativeSelectionRef;
+ readonly projection: TemporalPointExpression;
+}): ProjectedPoint {
+ const space = projectSemanticProgramSpace(input.semantic);
+ const program = locateProgram(input.semantic);
+ const selection = locateSelection(input.semantic, input.selection);
+ return projectedPoint(
+ { id: input.itemId, projection: input.projection },
+ { kind: "selection", id: selection.id },
+ projectTemporalPoint(input.projection, { program, selection }, space),
+ );
+}
+
+export function projectMomentPoint(input: {
+ readonly itemId: string;
+ readonly semantic: SemanticTrack;
+ readonly moment: NarrativeMomentRef;
+ readonly projection: TemporalPointExpression;
+}): ProjectedPoint {
+ const space = projectSemanticProgramSpace(input.semantic);
+ const program = locateProgram(input.semantic);
+ const moment = locateMoment(input.semantic, input.moment);
+ return projectedPoint(
+ { id: input.itemId, projection: input.projection },
+ { kind: "moment", id: moment.id },
+ projectTemporalPoint(input.projection, { program, moment }, space),
+ );
+}
+
+export function projectProgramPoint(input: {
+ readonly itemId: string;
+ readonly semantic: SemanticTrack;
+ readonly projection: TemporalPointExpression;
+}): ProjectedPoint {
+ const space = projectSemanticProgramSpace(input.semantic);
+ const program = locateProgram(input.semantic);
+ return projectedPoint(
+ { id: input.itemId, projection: input.projection },
+ { kind: "program", id: program.id },
+ projectTemporalPoint(input.projection, { program }, space),
+ );
+}
+
+export function projectSegmentPoint(input: {
+ readonly itemId: string;
+ readonly semantic: SemanticTrack;
+ readonly segment: NarrativeExcerpt;
+ readonly projection: TemporalPointExpression;
+}): ProjectedPoint {
+ const space = projectSemanticProgramSpace(input.semantic);
+ const program = locateProgram(input.semantic);
+ const segment = locateSegment(input.semantic, input.segment);
+ return projectedPoint(
+ { id: input.itemId, projection: input.projection },
+ { kind: "segment", id: segment.id },
+ projectTemporalPoint(input.projection, { program, segment }, space),
+ );
+}
+
export function projectSelectionWindow(input: {
readonly itemId: string;
readonly semantic: SemanticTrack;
diff --git a/packages/temporal/src/types.ts b/packages/temporal/src/types.ts
index 0e373717..c3866c0b 100644
--- a/packages/temporal/src/types.ts
+++ b/packages/temporal/src/types.ts
@@ -58,6 +58,12 @@ export type TemporalWindowSpec = {
readonly projection: TemporalWindowProjection;
};
+/** Input value for a Temporal point projection producer. */
+export type TemporalPointSpec = {
+ readonly id: string;
+ readonly projection: TemporalPointExpression;
+};
+
export type FrameSpan = {
readonly startFrame: number;
readonly endFrameExclusive: number;
@@ -70,9 +76,19 @@ export type ProjectedWindow = {
readonly span: FrameSpan;
};
+export type ProjectedPoint = {
+ readonly id: string;
+ readonly source: TemporalSource;
+ readonly projection: TemporalPointExpression;
+ readonly frame: number;
+};
+
/** Public protocol name for the resolved window consumed by domain programs. */
export type TemporalWindow = ProjectedWindow;
+/** Public protocol name for the resolved boundary consumed by domain programs. */
+export type TemporalPoint = ProjectedPoint;
+
export type WindowRelation = "independent" | "disjoint";
export type TriggerPoint = {
diff --git a/packages/temporal/test/temporal.test.ts b/packages/temporal/test/temporal.test.ts
index 34c159da..19d6b30a 100644
--- a/packages/temporal/test/temporal.test.ts
+++ b/packages/temporal/test/temporal.test.ts
@@ -9,8 +9,11 @@ import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import {
assertWindowRelation,
locateSelection,
+ projectMomentPoint,
projectMomentWindow,
+ projectProgramPoint,
projectProgramWindow,
+ projectSelectionPoint,
projectSegmentWindow,
projectSelectionWindow,
resolveTriggeredSchedule,
@@ -34,6 +37,7 @@ const semantic = semanticTrackFixture(space, {
{ identity: "c", frame: 90 },
{ identity: "d", frame: 120 },
{ identity: "late", frame: 240 },
+ { identity: "end", frame: 300 },
{ identity: "segment:answer:start", frame: 60 },
{ identity: "segment:answer:end", frame: 120 },
],
@@ -61,6 +65,58 @@ test("one Selection projects exact local points and stable source identity", ()
});
});
+test("points preserve source identity and admit both ProgramSpace boundaries", () => {
+ assert.deepEqual(projectProgramPoint({
+ itemId: "terminal",
+ semantic,
+ projection: { ref: "program.end" },
+ }), {
+ id: "terminal::program",
+ source: { kind: "program", id: "program" },
+ projection: { ref: "program.end" },
+ frame: 300,
+ });
+ assert.deepEqual(projectMomentPoint({
+ itemId: "terminal",
+ semantic,
+ moment: moment("done", "end"),
+ projection: { ref: "moment.cue" },
+ }), {
+ id: "terminal::done",
+ source: { kind: "moment", id: "done" },
+ projection: { ref: "moment.cue" },
+ frame: 300,
+ });
+ assert.equal(projectProgramPoint({
+ itemId: "start",
+ semantic,
+ projection: { ref: "program.start" },
+ }).frame, 0);
+});
+
+test("a point may consume one boundary of a crossed Selection", () => {
+ const crossed = selection("crossed", "d", "a");
+ assert.equal(projectSelectionPoint({
+ itemId: "boundary",
+ semantic,
+ selection: crossed,
+ projection: { ref: "selection.end" },
+ }).frame, 30);
+});
+
+test("points reject exact coordinates outside ProgramSpace", () => {
+ assert.throws(() => projectProgramPoint({
+ itemId: "before",
+ semantic,
+ projection: { ref: "program.start", offset: frames(-1) },
+ }), /falls outside ProgramSpace/u);
+ assert.throws(() => projectProgramPoint({
+ itemId: "after",
+ semantic,
+ projection: { ref: "program.end", offset: frames(1) },
+ }), /falls outside ProgramSpace/u);
+});
+
test("one Segment projects from its own structural start and end anchors", () => {
const result = projectSegmentWindow({
itemId: "answer-card",