@sublane/core 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,3 +7,26 @@ Sublane 框架核心——视频字幕翻译能力的宿主契约层。Apache-2.
7
7
  - 总览与 quick start:[Sublane 仓库 README](https://github.com/ai-baymax-dabai/sublane/tree/master/video-subtitle-translation)
8
8
  - 接入指南:[docs/integration.md](https://github.com/ai-baymax-dabai/sublane/blob/master/video-subtitle-translation/docs/integration.md)
9
9
  - 公共 API(semver 承诺):仓库 README "Public API" 节——导出清单被 `release-gates.test.ts` 冻结
10
+
11
+ ## detached 渲染会话(0.2.0,F-27)
12
+
13
+ 把供应商引擎当**可复用渲染器**:在宿主提供的任意 `<video>` 元素上,用宿主注入的字幕轨数据(原文+可选译文)以 vendor 原生 UI 渲染双语字幕——数据面与渲染面解耦(提案:docs/integrations/2026-11-17-replaychannel-proposal.md;裁决:docs/integrations/2026-11-18-replaychannel-adjudication.md)。
14
+
15
+ ```ts
16
+ import { createDetachedSession } from '@sublane/core'
17
+
18
+ const session = await createDetachedSession({
19
+ ctx: { onInvalidated: () => {} }, // 宿主会话生命周期(如 Modal 关闭)
20
+ plugins, // 你的插件数组(与 live 同一批)
21
+ storage: frameworkStoragePort, // 复用同一配置键与车道算法
22
+ video: hostVideoElement, // 宿主提供的任意 video 元素
23
+ source: { getTrack: async () => ({ cues }) },// 注入轨:SubtitleCue[](含可选译文)
24
+ freezeConfig: false, // settings 实时跟随框架键;true=快照冻结
25
+ })
26
+ // session.handles: Map<SupplierId, DetachedHandle>——不支持 detached 的供应商如实缺席(宿主降级)
27
+ // session.dispose(): 会话结束全量卸载
28
+ ```
29
+
30
+ - **信任边界**:注入轨按 `TRACK_LIMITS` 契约默认校验(≤20,000 cues/≤4MB/≤4096 字符每 cue),per-supplier 覆盖经 `limits` 选项;超限拒载报 `REPLAY_TRACK_LIMIT`。
31
+ - **语义要点**:时间权威=宿主 video 的 currentTime(R3);缺译→原文行、无 pending 态(R5);`allowVendorTranslation=false` 不触发 vendor 翻译(N4);detached ctx 的 `emitConfigPatch` 中立化(M1)。
32
+ - **供应商支持矩阵**:read-frog ✅(0.2.0);fluent-read 🚧(P1 进行中)。不支持者缺席于 handles,宿主按 A8 降级。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sublane/core",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "exports": {
package/src/contract.ts CHANGED
@@ -63,6 +63,21 @@ export interface VideoSubtitlePluginInstance {
63
63
  mount(): void | Promise<void>
64
64
  unmount(): void | Promise<void>
65
65
  setConfig(config: SupplierRuntimeConfig): void
66
+ /** 0.3.0 可选(F-26, cue 只读数据事件流):订阅本实例的 cue 数据(原文+已得译文)。
67
+ * 语义:订阅即发一次 'reset'(当前已得全量);此后按 vendor 翻译节奏发 'upsert'(增量);
68
+ * 导航/轨重置发 'reset'。只读——宿主不得回写;翻译节奏归 vendor(宿主订阅即可,无按需命令)。
69
+ * provenance:engine 为产出译文的引擎/服务标识(vendor 自述,可缺省)。
70
+ * 不支持时缺席(宿主 feature-detect,同 A8 纪律)。 */
71
+ subscribeCues?(listener: (event: CueStreamEvent) => void): () => void
72
+ }
73
+
74
+ /** cue 数据事件(F-26/0.3.0):'reset' = cues 为当前全量快照;'upsert' = cues 为新增/变更增量。
75
+ * cue 形状复用 SubtitleCue(与 F-27 detached 注入同词汇表——F-26 流出/F-27 流入共用,裁决回函 §四)。 */
76
+ export interface CueStreamEvent {
77
+ type: 'reset' | 'upsert'
78
+ cues: SubtitleCue[]
79
+ /** provenance:本批译文产出引擎(vendor 自述,可缺省) */
80
+ engine?: string
66
81
  }
67
82
 
68
83
  /** 供应商对宿主 manifest 的声明式需求;宿主装配 manifest 时取并集(构建期读取,声明模块必须零浏览器依赖) */
@@ -154,6 +169,11 @@ export interface DetachedHandle {
154
169
  unmount(): void | Promise<void>
155
170
  /** 替换数据源(如切换 Clip 区间);不重挂 DOM */
156
171
  setSource(source: TrackSource): void
172
+ /** 0.3.1 可选(缺口3):订阅 detached 渲染器**有效轨**的只读事件流(回显语义——
173
+ * 事件 = 渲染器实际持有的规范化 cue 视图;订阅即 reset,onUpdate/setSource → upsert)。
174
+ * injected-only 下宿主本持有注入数据,此成员的契约价值 = 以统一词汇表观测渲染器
175
+ * 的有效视图(规范化后含推断区间),并为未来 hybrid 模式预留同一订阅面。 */
176
+ subscribeCues?(listener: (event: CueStreamEvent) => void): () => void
157
177
  }
158
178
 
159
179
  /** detached 会话上下文:与 live PluginMountContext 同形,但编排器已将 emitConfigPatch
package/src/runtime.ts CHANGED
@@ -175,6 +175,12 @@ export function createVideoSubtitleFramework({ ctx, plugins, storage: storagePor
175
175
  }
176
176
 
177
177
  return {
178
+ /** 0.3.1(缺口1):宿主访问 live 实例的唯一受支持通道——F-26 subscribeCues 消费入口。
179
+ * 快照语义:返回调用时刻的装配集(start 前为空;applyConfig 每次重建,旧快照冻结)。
180
+ * integration.md 曾承诺"经框架回调拿到实例引用"而代码缺位——本访问器补齐该行为。 */
181
+ instances(): ReadonlyMap<string, VideoSubtitlePluginInstance> {
182
+ return new Map([...running].map(([id, run]) => [id, run.instance]))
183
+ },
178
184
  async start(): Promise<void> {
179
185
  ctx.onInvalidated(() => {
180
186
  stopped = true