@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/undoShortcuts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 窗口级撤销/重做快捷键(spec §8.3):studio 自带快捷键只在其 UI 焦点内
+ * 生效(9-23 终审遗留),画布焦点下 Ctrl+Z 石沉大海——playground 在
+ * window 级接管,直达 studio.undo()/redo()(Task 1 公共 API)。
+ * 两个不抢:可编辑目标(输入框自己的文本撤销);事件穿过 studio UI
+ * (studio 会自己处理,一次按键撤两步是大坑)。
+ */
+export type UndoKeyEventLike = {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    isEditableTarget: boolean;
+    insideStudioUi: boolean;
+    /** 事件已被上游监听 preventDefault(另一方已接管此按键,不得重复处理) */
+    defaultPrevented?: boolean;
+};
+export declare function undoIntentFromKeyEvent(ev: UndoKeyEventLike): 'undo' | 'redo' | null;
+/**
+ * studio UI 挂在 shadow DOM;事件 composedPath 含其宿主即视为 studio 内部。
+ * 根标识实证:packages/studio/src/UI/UINonSSRBits.ts:17 设
+ * `containerEl.id = 'theatrejs-studio-root'`(playground pipLayout.ts 同 id)。
+ * 导出复用:姿势退出 Enter 守卫(F3)同样跳过 studio 内部按键。
+ */
+export declare function isInsideStudioUi(ev: KeyboardEvent): boolean;
+/** App 接线:返回注销函数 */
+export declare function bindUndoShortcuts(undo: () => void, redo: () => void): () => void;
+//# sourceMappingURL=undoShortcuts.d.ts.map

package/dist/undoShortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undoShortcuts.d.ts","sourceRoot":"","sources":["../src/undoShortcuts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB,EAAE,OAAO,CAAA;IACzB,cAAc,EAAE,OAAO,CAAA;IACvB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,GACnB,MAAM,GAAG,MAAM,GAAG,IAAI,CAWxB;AAYD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAQ3D;AAED,oBAAoB;AACpB,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,IAAI,EAChB,IAAI,EAAE,MAAM,IAAI,GACf,MAAM,IAAI,CAkBZ"}

package/dist/undoShortcuts.js

@@ -0,0 +1,59 @@
+export function undoIntentFromKeyEvent(ev) {
+    // 与 studio 的 window 级快捷键(useKeyboardShortcuts)互认 defaultPrevented:
+    // 两个监听都挂在 window 上、注册顺序不定,先跑的一方 preventDefault,
+    // 后跑的一方见到即跳过——否则画布焦点下一次 Cmd+Z 撤两步(2026-10-01 实证)
+    if (ev.defaultPrevented)
+        return null;
+    if (ev.isEditableTarget || ev.insideStudioUi)
+        return null;
+    if (!ev.ctrlKey && !ev.metaKey)
+        return null;
+    const key = ev.key.toLowerCase();
+    if (key === 'z')
+        return ev.shiftKey ? 'redo' : 'undo';
+    if (key === 'y' && !ev.shiftKey)
+        return 'redo';
+    return null;
+}
+function isEditableTarget(target) {
+    const el = target;
+    return !!(el &&
+        (el.tagName === 'INPUT' ||
+            el.tagName === 'TEXTAREA' ||
+            el.isContentEditable));
+}
+/**
+ * studio UI 挂在 shadow DOM;事件 composedPath 含其宿主即视为 studio 内部。
+ * 根标识实证:packages/studio/src/UI/UINonSSRBits.ts:17 设
+ * `containerEl.id = 'theatrejs-studio-root'`(playground pipLayout.ts 同 id)。
+ * 导出复用:姿势退出 Enter 守卫(F3)同样跳过 studio 内部按键。
+ */
+export function isInsideStudioUi(ev) {
+    const path = ev.composedPath();
+    return path.some((el) => el instanceof HTMLElement &&
+        (el.id === 'theatrejs-studio-root' ||
+            el.dataset?.['theatreStudioRoot'] !== undefined));
+}
+/** App 接线:返回注销函数 */
+export function bindUndoShortcuts(undo, redo) {
+    const onKey = (ev) => {
+        const intent = undoIntentFromKeyEvent({
+            key: ev.key,
+            ctrlKey: ev.ctrlKey,
+            metaKey: ev.metaKey,
+            shiftKey: ev.shiftKey,
+            isEditableTarget: isEditableTarget(ev.target),
+            insideStudioUi: isInsideStudioUi(ev),
+            defaultPrevented: ev.defaultPrevented,
+        });
+        if (!intent)
+            return;
+        ev.preventDefault();
+        if (intent === 'undo')
+            undo();
+        else
+            redo();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+}

package/dist/undoShortcuts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=undoShortcuts.test.d.ts.map

package/dist/undoShortcuts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undoShortcuts.test.d.ts","sourceRoot":"","sources":["../src/undoShortcuts.test.ts"],"names":[],"mappings":""}

package/dist/undoShortcuts.test.js

@@ -0,0 +1,37 @@
+/**
+ * 窗口级撤销/重做快捷键(spec §8.3):
+ *   Cmd/Ctrl+Z → undo;Cmd/Ctrl+Shift+Z 与 Ctrl+Y → redo。
+ * 排除:可编辑目标(输入框/textarea/contentEditable);事件穿过 studio UI
+ * 根(studio 自己处理,避免一次按键撤两步)。
+ */
+import { undoIntentFromKeyEvent } from './undoShortcuts';
+const z = (over = {}) => undoIntentFromKeyEvent({
+    key: 'z',
+    ctrlKey: true,
+    metaKey: false,
+    shiftKey: false,
+    isEditableTarget: false,
+    insideStudioUi: false,
+    ...over,
+});
+test('Ctrl/Cmd+Z = undo;加 Shift = redo;Ctrl+Y = redo', () => {
+    expect(z()).toBe('undo');
+    expect(z({ metaKey: true, ctrlKey: false })).toBe('undo');
+    expect(z({ shiftKey: true })).toBe('redo');
+    expect(z({ metaKey: true, ctrlKey: false, shiftKey: true })).toBe('redo');
+    expect(z({ key: 'y' })).toBe('redo');
+});
+test('无修饰键/其他键 = null', () => {
+    expect(z({ ctrlKey: false })).toBe(null);
+    expect(z({ key: 'x' })).toBe(null);
+});
+test('可编辑目标与 studio UI 内事件 = null(不抢 studio/输入框的撤销)', () => {
+    expect(z({ isEditableTarget: true })).toBe(null);
+    expect(z({ insideStudioUi: true })).toBe(null);
+});
+test('已被上游 preventDefault 的按键 = null(另一方已撤,不重复撤)', () => {
+    // 2026-10-01 冒烟实证:studio 快捷键实为 window 级(非注释原假设的
+    // 「只在 UI 焦点内」),画布焦点下一次 Cmd+Z 撤两步。双侧互认
+    // defaultPrevented 后,先跑的一方处理,后跑的一方跳过
+    expect(z({ defaultPrevented: true })).toBe(null);
+});

package/dist/useCameraStudio.d.ts

@@ -0,0 +1,3 @@
+import type { CameraStudioConfig, CameraStudioHandle } from './config';
+export declare function useCameraStudio(config?: CameraStudioConfig): CameraStudioHandle;
+//# sourceMappingURL=useCameraStudio.d.ts.map

package/dist/useCameraStudio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCameraStudio.d.ts","sourceRoot":"","sources":["../src/useCameraStudio.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,kBAAkB,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAmBpE,wBAAgB,eAAe,CAC7B,MAAM,GAAE,kBAAuB,GAC9B,kBAAkB,CAyEpB"}

package/dist/useCameraStudio.js

@@ -0,0 +1,86 @@
+/**
+ * useCameraStudio(spec §3/§7):宿主唯一的初始化入口。
+ *
+ * - config 只在首帧取一次(useRef 锁存):后续渲染传新配置不热更,
+ *   与 theatre.init 的一次性语义对齐;已 boot 后重挂换 config 不生效
+ *   (模块级 promise 复用首 boot),console.warn 点名差异键,换配置需
+ *   整页刷新。
+ * - 状态机:idle → initializing → ready / error;init 挂 bootstrap 的
+ *   共享 promise,StrictMode 双跑/重复触发只复用。
+ * - 单页单实例(studio 全局单例):同页第二个实例不占位、直接 error。
+ * - 卸载清理由 disposeCameraStudio 对称执行(编辑器注销/状态订阅断开+
+ *   flush/ui.hide);重挂幂等复用 boot,会话级资源重新装配 + ui.restore。
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { acquireCameraStudioConsumer, disposeCameraStudio, getBootConfig, initCameraStudio, isBootedWithDifferentConfig, releaseCameraStudioConsumer, resolveSceneProps, } from './bootstrap';
+import { getCameraStudioApi } from './agent/api';
+export function useCameraStudio(config = {}) {
+    // config 首帧锁存(变更不热更)
+    const configRef = useRef(config);
+    const [phase, setPhase] = useState({
+        ready: false,
+        error: undefined,
+        ctx: undefined,
+    });
+    useEffect(() => {
+        const slot = acquireCameraStudioConsumer();
+        if (slot > 1) {
+            setPhase({
+                ready: false,
+                error: new Error('单页只允许一个 CameraScene 实例:同页第二个 useCameraStudio 被拒绝'),
+                ctx: undefined,
+            });
+            return () => {
+                // 报错实例不占会话;但若是最后离场者,要替正常实例补拆(其 cleanup
+                // 在还有消费者时按守卫跳过拆解)
+                if (releaseCameraStudioConsumer() === 0)
+                    void disposeCameraStudio();
+            };
+        }
+        let cancelled = false;
+        let ctxRef;
+        void initCameraStudio(configRef.current).then((ctx) => {
+            if (cancelled) {
+                // 卸载先于 init 解析:补一次 dispose(内部末位守卫决定拆不拆)
+                void disposeCameraStudio(ctx);
+                return;
+            }
+            ctxRef = ctx;
+            setPhase({ ready: true, error: undefined, ctx });
+        }, (error) => {
+            if (cancelled)
+                return;
+            setPhase({
+                ready: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+                ctx: undefined,
+            });
+        });
+        return () => {
+            cancelled = true;
+            const remaining = releaseCameraStudioConsumer();
+            // 最后一位消费者退场才拆解会话;init 未解析则由上面 cancelled 分支补
+            if (remaining === 0 && ctxRef)
+                void disposeCameraStudio(ctxRef);
+        };
+    }, []);
+    // sceneProps 同步解析(getProject 渲染期调用安全,App 既有先例):
+    // ready 前的占位也是真值,宿主提前渲染不炸;boot 完成后与 ctx 内一致。
+    // 已 boot 且本次 config 与首 boot 不一致时,占位按首 boot 配置解析
+    // (沿用首次配置,不为新 config 调 getProject 造闲置 IProject;差异
+    // 告警由 initCameraStudio 发出,终审 I-1(b)③)
+    const earlySceneProps = useMemo(() => {
+        const cfg = isBootedWithDifferentConfig(configRef.current)
+            ? getBootConfig() ?? configRef.current
+            : configRef.current;
+        return resolveSceneProps(cfg);
+    }, []);
+    const sceneProps = phase.ctx?.sceneProps ?? earlySceneProps;
+    // api 是模块级单例:首帧(占位)与 boot 完成后返回同一对象(Task 15)
+    return {
+        ready: phase.ready,
+        error: phase.error,
+        sceneProps,
+        api: getCameraStudioApi(),
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const CAMERA_STUDIO_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,qBAAqB,EAAE,MAAgB,CAAA"}

package/dist/version.js

@@ -0,0 +1,11 @@
+/**
+ * CAMERA_STUDIO_VERSION 的唯一事实源是 package.json。
+ *
+ * 不启 resolveJsonModule:tsconfig rootDir=src,JSON import 用 ts-ignore
+ * 压掉类型解析;产物保留 ../package.json 相对引用(npm 包必含 package.json)。
+ * 宿主打包器(Vite/Rollup/webpack)与 jest-esbuild 都原生处理 JSON;发布脚本
+ * 先改 package.json 再构建,产物版本因此自动同步。
+ */
+// @ts-ignore JSON 不在 rootDir 内;d.ts 只导出 string 常量
+import { version } from '../package.json';
+export const CAMERA_STUDIO_VERSION = version;

package/dist/videoExport/BlobCollectSink.d.ts

@@ -0,0 +1,25 @@
+import type { ExportSink, ExportSinkMeta } from './sinks';
+export declare class BlobCollectSink implements ExportSink {
+    readonly id = "collect";
+    readonly label = "\u6536\u96C6\u5230\u5185\u5B58";
+    readonly description = "Agent \u5BFC\u51FA\u7528:\u5F55\u5236\u5B8C\u6210\u540E\u6574\u5305\u53D6\u8D70,\u4E0D\u89E6\u53D1\u4E0B\u8F7D";
+    private chunks;
+    private meta;
+    private aborted;
+    available(): boolean;
+    start(meta: ExportSinkMeta): Promise<void>;
+    write(chunk: Uint8Array): Promise<void>;
+    /** 不落盘、不下载:收尾什么都不做,文件由 blob() 取 */
+    finish(): Promise<void>;
+    abort(): Promise<void>;
+    /**
+     * 收集到的文件(start 时已收到的 MIME 为容器类型)。
+     * 未 start 或已 abort 抛 INVALID_STATE —— 没有可交付的产出。
+     */
+    blob(): Blob;
+    /** start 时编码器给出的建议文件名;未 start 为 undefined */
+    get fileName(): string | undefined;
+    /** start 时的容器 MIME;未 start 为 undefined */
+    get mimeType(): string | undefined;
+}
+//# sourceMappingURL=BlobCollectSink.d.ts.map

package/dist/videoExport/BlobCollectSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlobCollectSink.d.ts","sourceRoot":"","sources":["../../src/videoExport/BlobCollectSink.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,SAAS,CAAA;AAEvD,qBAAa,eAAgB,YAAW,UAAU;IAChD,QAAQ,CAAC,EAAE,aAAY;IACvB,QAAQ,CAAC,KAAK,oCAAU;IACxB,QAAQ,CAAC,WAAW,oHAA8B;IAClD,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,OAAO,CAAQ;IAEvB,SAAS,IAAI,OAAO;IAId,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,mCAAmC;IAC7B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAEvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;OAGG;IACH,IAAI,IAAI,IAAI;IAUZ,6CAA6C;IAC7C,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED,0CAA0C;IAC1C,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;CACF"}

package/dist/videoExport/BlobCollectSink.js

@@ -0,0 +1,56 @@
+/**
+ * BlobCollectSink(2026-10-17,Task 13):内存收集导出目标——Agent 视频导出
+ * (exports.startVideo)的默认 sink。编码器产出的块按序攒在内存,finish
+ * 后由 blob() 整包取走;不触发浏览器下载,不进 listSinks 的 UI 菜单。
+ *
+ * 生命周期约束:abort 后 blob() 抛 INVALID_STATE、后续 write 拒绝;
+ * 重复 start 清空旧块(同一个 sink 可随新任务复用)。
+ */
+import { AgentApiError } from '../agent/errors';
+export class BlobCollectSink {
+    constructor() {
+        this.id = 'collect';
+        this.label = '收集到内存';
+        this.description = 'Agent 导出用:录制完成后整包取走,不触发下载';
+        this.chunks = [];
+        this.aborted = false;
+    }
+    available() {
+        return true;
+    }
+    async start(meta) {
+        this.chunks = [];
+        this.meta = meta;
+        this.aborted = false;
+    }
+    async write(chunk) {
+        if (this.aborted) {
+            throw new AgentApiError('INVALID_STATE', '导出已取消,拒绝继续写入');
+        }
+        this.chunks.push(chunk);
+    }
+    /** 不落盘、不下载:收尾什么都不做,文件由 blob() 取 */
+    async finish() { }
+    async abort() {
+        this.aborted = true;
+        this.chunks = [];
+    }
+    /**
+     * 收集到的文件(start 时已收到的 MIME 为容器类型)。
+     * 未 start 或已 abort 抛 INVALID_STATE —— 没有可交付的产出。
+     */
+    blob() {
+        if (this.aborted || !this.meta) {
+            throw new AgentApiError('INVALID_STATE', '导出已取消或尚未开始,无可交付文件');
+        }
+        return new Blob(this.chunks, { type: this.meta.mimeType });
+    }
+    /** start 时编码器给出的建议文件名;未 start 为 undefined */
+    get fileName() {
+        return this.meta?.suggestedName;
+    }
+    /** start 时的容器 MIME;未 start 为 undefined */
+    get mimeType() {
+        return this.meta?.mimeType;
+    }
+}

package/dist/videoExport/BlobCollectSink.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BlobCollectSink.test.d.ts.map

package/dist/videoExport/BlobCollectSink.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlobCollectSink.test.d.ts","sourceRoot":"","sources":["../../src/videoExport/BlobCollectSink.test.ts"],"names":[],"mappings":""}

package/dist/videoExport/BlobCollectSink.test.js

@@ -0,0 +1,78 @@
+/**
+ * BlobCollectSink(2026-10-17,Task 13):Agent 视频导出的内存收集 sink。
+ *
+ * 契约:
+ *  - start 后按序 write,finish 后 blob() 返回正确 MIME/大小/字节;
+ *  - abort 后 blob() 抛 INVALID_STATE,后续 write 拒绝;
+ *  - 重复 start 清空旧块;
+ *  - 不触发浏览器下载(无 DOM 依赖,node 环境直接测)。
+ */
+import { AgentApiError } from '../agent/errors';
+import { BlobCollectSink } from './BlobCollectSink';
+const meta = { mimeType: 'video/webm', suggestedName: '镜头-test.webm' };
+async function bytesOf(blob) {
+    return [...new Uint8Array(await blob.arrayBuffer())];
+}
+/** blob() 是同步抛错(非 Promise 拒绝),用 try/catch 断言错误码 */
+function expectBlobThrows(sink) {
+    let caught;
+    try {
+        sink.blob();
+    }
+    catch (error) {
+        caught = error;
+    }
+    expect(caught).toBeInstanceOf(AgentApiError);
+    expect(caught.code).toBe('INVALID_STATE');
+}
+test('start → 按序 write 两块 → finish → blob() 返回正确 MIME、大小和字节', async () => {
+    const sink = new BlobCollectSink();
+    await sink.start(meta);
+    await sink.write(new Uint8Array([1, 2, 3]));
+    await sink.write(new Uint8Array([4, 5]));
+    await sink.finish();
+    const blob = sink.blob();
+    expect(blob.type).toBe('video/webm');
+    expect(blob.size).toBe(5);
+    expect(await bytesOf(blob)).toEqual([1, 2, 3, 4, 5]);
+    expect(sink.fileName).toBe('镜头-test.webm');
+    expect(sink.mimeType).toBe('video/webm');
+});
+test('abort 后 blob() 抛 INVALID_STATE,后续 write 拒绝', async () => {
+    const sink = new BlobCollectSink();
+    await sink.start(meta);
+    await sink.write(new Uint8Array([1]));
+    await sink.abort();
+    expectBlobThrows(sink);
+    await expect(sink.write(new Uint8Array([2]))).rejects.toMatchObject({
+        code: 'INVALID_STATE',
+    });
+});
+test('重复 start 清空旧块', async () => {
+    const sink = new BlobCollectSink();
+    await sink.start(meta);
+    await sink.write(new Uint8Array([9, 9, 9]));
+    await sink.start({ mimeType: 'video/mp4', suggestedName: 'second.mp4' });
+    await sink.write(new Uint8Array([7]));
+    await sink.finish();
+    const blob = sink.blob();
+    expect(blob.type).toBe('video/mp4');
+    expect(blob.size).toBe(1);
+    expect(await bytesOf(blob)).toEqual([7]);
+    expect(sink.fileName).toBe('second.mp4');
+});
+test('abort 后重新 start 可再次收集(恢复可用)', async () => {
+    const sink = new BlobCollectSink();
+    await sink.start(meta);
+    await sink.abort();
+    await sink.start(meta);
+    await sink.write(new Uint8Array([1, 2]));
+    const blob = sink.blob();
+    expect(blob.size).toBe(2);
+});
+test('未 start 就 blob() 抛 INVALID_STATE', () => {
+    expectBlobThrows(new BlobCollectSink());
+});
+test('available 恒 true(不依赖 File System Access 等可选能力)', () => {
+    expect(new BlobCollectSink().available()).toBe(true);
+});

package/dist/videoExport/encoder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 视频编码器:把 canvas 画面流转成数据块序列。
+ * 一期实现是 MediaRecorder 实时编码(边播边录);以后换 WebCodecs
+ * 离线编码(逐帧喂画面、可控码率、产出 mp4)时实现同一个接口,
+ * 导出流程和 ExportSink 都不用动。
+ */
+export interface VideoEncoder {
+    /** 实际使用的 MIME(由浏览器能力决定) */
+    readonly mimeType: string;
+    /** 每产出一个数据块回调一次;保证按顺序,且 stop()  resolve 前全部发完 */
+    onChunk: ((chunk: Uint8Array) => void) | null;
+    /**
+     * 启动编码;resolve 时 MediaRecorder 的 'start' 事件已落地(编码后端
+     * 真正就绪)。必须 await:软件渲染/冷页面下 init 实测可达 400ms+,不等
+     * 就开录会让 stop() 抢在 'start' 之前——短片段整段丢失、产出 0 字节
+     * (2026-10-19,E2E 实测时间线)。启动前 'error' 事件 → reject
+     */
+    start(): Promise<void>;
+    /** 停止编码;resolve 时最后一个块已经通过 onChunk 发出 */
+    stop(): Promise<void>;
+}
+/** 选出第一个受支持的 MIME;都不支持返回 undefined(纯函数,可测) */
+export declare function pickMimeType(isSupported: (mimeType: string) => boolean): string | undefined;
+/**  MIME → 文件扩展名(纯函数,可测) */
+export declare function extForMime(mimeType: string): string;
+/**
+ * MediaRecorder 实时编码器:canvas.captureStream() 的画面流边播边编。
+ * 返回 undefined = 浏览器连一种支持的格式都没有(极少见)。
+ */
+export declare function createMediaRecorderEncoder(stream: MediaStream, options?: {
+    videoBitsPerSecond?: number;
+    timesliceMs?: number;
+}): VideoEncoder | undefined;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/videoExport/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/videoExport/encoder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,yCAAyC;IACzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAUD,8CAA8C;AAC9C,wBAAgB,YAAY,CAC1B,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,4BAA4B;AAC5B,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAM,GAChE,YAAY,GAAG,SAAS,CA8C1B"}

package/dist/videoExport/encoder.js

@@ -0,0 +1,61 @@
+/** 按偏好顺序给出浏览器支持的容器/编码;一期优先 webm/mp4 都行 */
+const MIME_CANDIDATES = [
+    'video/webm;codecs=vp9',
+    'video/webm;codecs=vp8',
+    'video/webm',
+    'video/mp4',
+];
+/** 选出第一个受支持的 MIME;都不支持返回 undefined(纯函数,可测) */
+export function pickMimeType(isSupported) {
+    return MIME_CANDIDATES.find((t) => isSupported(t));
+}
+/**  MIME → 文件扩展名(纯函数,可测) */
+export function extForMime(mimeType) {
+    return mimeType.includes('mp4') ? 'mp4' : 'webm';
+}
+/**
+ * MediaRecorder 实时编码器:canvas.captureStream() 的画面流边播边编。
+ * 返回 undefined = 浏览器连一种支持的格式都没有(极少见)。
+ */
+export function createMediaRecorderEncoder(stream, options = {}) {
+    const mimeType = pickMimeType((t) => MediaRecorder.isTypeSupported(t));
+    if (!mimeType)
+        return undefined;
+    const recorder = new MediaRecorder(stream, {
+        mimeType,
+        videoBitsPerSecond: options.videoBitsPerSecond ?? 12000000,
+    });
+    // dataavailable 的 Blob 转字节是异步的,stop 的 onstop 可能先 resolve;
+    // 用链条把所有转换串起来,stop() 等链条清空才算完,保证块不丢不乱序
+    let chunkChain = Promise.resolve();
+    const encoder = {
+        mimeType,
+        onChunk: null,
+        start() {
+            // 等 'start' 事件再放行:recorder.start() 只是发起,后端异步初始化
+            return new Promise((resolve, reject) => {
+                recorder.addEventListener('start', () => resolve(), { once: true });
+                recorder.addEventListener('error', (event) => reject(event.error ??
+                    new Error('MediaRecorder 启动失败')), { once: true });
+                recorder.start(options.timesliceMs ?? 1000);
+            });
+        },
+        stop() {
+            return new Promise((resolve) => {
+                recorder.onstop = () => {
+                    chunkChain.then(() => resolve());
+                };
+                recorder.stop();
+            });
+        },
+    };
+    recorder.ondataavailable = (event) => {
+        if (event.data.size === 0)
+            return;
+        chunkChain = chunkChain.then(async () => {
+            const buf = await event.data.arrayBuffer();
+            encoder.onChunk?.(new Uint8Array(buf));
+        });
+    };
+    return encoder;
+}

package/dist/videoExport/encoder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=encoder.test.d.ts.map

package/dist/videoExport/encoder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.test.d.ts","sourceRoot":"","sources":["../../src/videoExport/encoder.test.ts"],"names":[],"mappings":""}

package/dist/videoExport/encoder.test.js

@@ -0,0 +1,21 @@
+import { extForMime, pickMimeType } from './encoder';
+describe('pickMimeType', () => {
+    it('优先选 vp9 的 webm', () => {
+        expect(pickMimeType(() => true)).toBe('video/webm;codecs=vp9');
+    });
+    it('按候选顺序回退', () => {
+        expect(pickMimeType((t) => t === 'video/webm')).toBe('video/webm');
+        expect(pickMimeType((t) => t === 'video/mp4')).toBe('video/mp4');
+    });
+    it('全不支持返回 undefined', () => {
+        expect(pickMimeType(() => false)).toBeUndefined();
+    });
+});
+describe('extForMime', () => {
+    it('mp4 容器给 mp4 扩展名', () => {
+        expect(extForMime('video/mp4')).toBe('mp4');
+    });
+    it('其余(webm)给 webm 扩展名', () => {
+        expect(extForMime('video/webm;codecs=vp9')).toBe('webm');
+    });
+});

package/dist/videoExport/exporter.d.ts

@@ -0,0 +1,24 @@
+import type { ISheet } from '@dreamerbird/core';
+import type { ExportSink } from './sinks';
+export interface ShotExportHandle {
+    /** 提前结束并保存已录内容 */
+    finishEarly(): void;
+    /** 取消录制,丢弃已录内容 */
+    abort(): void;
+    /** 正常结束 resolve;出错或取消 reject(Error) */
+    done: Promise<void>;
+}
+/**
+ * 导出镜头视频:序列从头播到尾,canvas 画面实时编码,数据块流式写给 sink。
+ * 调用前先把画面切到镜头视角(录的就是 canvas 当前内容)。
+ *
+ * 一期限制:实时录制——序列多长就录多久,播放掉帧录出来也掉帧;
+ * 容器格式看浏览器(webm 为主)。离线逐帧渲染 + mp4 留作以后升级。
+ */
+export declare function startShotExport(args: {
+    canvas: HTMLCanvasElement;
+    sheet: ISheet;
+    sink: ExportSink;
+    onError?: (message: string) => void;
+}): ShotExportHandle | undefined;
+//# sourceMappingURL=exporter.d.ts.map

package/dist/videoExport/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../../src/videoExport/exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AAG7C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,SAAS,CAAA;AAEvC,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB;IAClB,WAAW,IAAI,IAAI,CAAA;IACnB,kBAAkB;IAClB,KAAK,IAAI,IAAI,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CACpB;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC,GAAG,gBAAgB,GAAG,SAAS,CA+D/B"}