@lokvis/runtime 0.2.0-beta.0 → 0.2.0

package/dist/degradation.js

@@ -0,0 +1,184 @@
+/**
+ * 能力降级阶梯(W3.4)
+ *
+ * 当 MemoryGuard 报告内存压力时,运行时需要按阶梯选择处理策略,
+ * 而非"要么全量要么崩溃"。本模块实现四级降级政策(whitepaper T1):
+ *
+ *   L1-full      完整质量——压力低/中,正常处理。
+ *   L2-tiled     分片处理——压力高,把输入按 tile 切分 + 中间结果溢出 OPFS,
+ *                内存里同时只持有一个 tile。
+ *   L3-degraded  降级输出——压力 critical,先缩小到 maxEdge 再处理,
+ *                降低质量,避免 OOM;产出可用但非最佳。
+ *   L4-reject    拒绝 + 引导——即使降级也无法安全处理(如单张图解码后即超
+ *                critical 且无法再缩),抛 DegradationRejectedError 携带
+ *                用户可读的引导(换更小源图 / 关闭其他 tab / 升级浏览器)。
+ *
+ * 设计取舍:
+ * - 本模块只做"决策"(policy),不直接执行图像操作。执行由 plugin-image
+ *   / executor 据 decision 调整参数后委托 engine-image。
+ * - 决策是纯函数(pickDegradation),便于单测与确定性回归。
+ * - L2 是否可走取决于操作是否支持 tiling(canTile);canvas 引擎对几何
+ *   变换可 tile,但对依赖全图的滤镜(模糊)与水印 tile 无意义 → 调用方
+ *   据操作语义传入 canTile。
+ */
+/** L3 降级输出时建议的最大边长(像素)——4K,兼顾可用性与内存 */
+export const DEGRADED_MAX_EDGE = 4096;
+/** L3 降级输出时建议的质量(0-100)——70 是视觉可接受的下限 */
+export const DEGRADED_QUALITY = 70;
+/**
+ * 根据内存压力与操作能力选择降级策略(纯函数)。
+ *
+ * 决策矩阵:
+ *   pressure  canTile  canSpill  →  level
+ *   low/elevated  *        *     →  L1-full
+ *   high          true    true   →  L2-tiled(spill)
+ *   high          true    false  →  L2-tiled(无 spill,仅靠 tile 控峰值)
+ *   high          false   *      →  L3-degraded(降到 maxEdge+quality)
+ *   critical      *       *      →  L3-degraded(若 decodedBytes 缩放后仍超
+ *                                              critical → L4-reject)
+ *
+ * L4 触发条件:pressure=critical 且 decodedBytes 已按 maxEdge 缩放后
+ * 估算仍 >= budget 的 critical 阈值(0.95),即"再怎么缩也会撑爆"。
+ *
+ * **调用方注意**:当 pressure=critical 且 canSpill=true 时,若不提供
+ * decodedBytes,函数将跳过 L4 判定直接返回 L3-degraded。这意味着对于
+ * 超大单张图(无法通过 spill 分块),L3 缩放后仍可能 OOM。
+ * 建议:尽可能通过 estimateDecodedBytes(width, height) 提供 decodedBytes,
+ * 以提高 L4 判定精度,避免静默降级后崩溃。
+ */
+export function pickDegradation(ctx) {
+    const { pressure, canTile, canSpill, inputBytes, budget, decodedBytes } = ctx;
+    // L1:压力低/中,完整处理
+    if (pressure === 'low' || pressure === 'elevated') {
+        return {
+            level: 'L1-full',
+            spill: false,
+            reason: `pressure=${pressure}, full quality`,
+        };
+    }
+    // L4 预判:输入本身已超预算且无法溢出 → 直接拒绝(避免无谓降级后仍 OOM)
+    // 仅当输入 blob 已 > budget 且不能溢出时,降级也救不了
+    if (pressure === 'critical' && inputBytes > budget && !canSpill) {
+        return rejectDecision(inputBytes, budget, 'input exceeds budget and OPFS spill unavailable');
+    }
+    if (pressure === 'high') {
+        // L2:可 tile 则分片处理(优先 spill 以降峰值)
+        if (canTile) {
+            return {
+                level: 'L2-tiled',
+                spill: canSpill,
+                reason: `pressure=high, tile-based${canSpill ? ' + OPFS spill' : ''}`,
+            };
+        }
+        // 不可 tile(模糊/水印等全图操作)→ L3 降级
+        return degradedDecision(canSpill, 'pressure=high but operation not tileable, degrade output');
+    }
+    // pressure === 'critical'
+    // 若提供 decodedBytes 且缩放到 maxEdge 后估算仍超 critical(0.95)→ L4
+    if (decodedBytes !== undefined) {
+        const scaledEstimate = scaleDecodedEstimate(decodedBytes, DEGRADED_MAX_EDGE);
+        if (scaledEstimate >= budget * 0.95) {
+            return rejectDecision(inputBytes, budget, `decoded ~${scaledEstimate}B even after ${DEGRADED_MAX_EDGE}px cap exceeds critical`);
+        }
+    }
+    // 否则 L3:降级输出
+    return degradedDecision(canSpill, 'pressure=critical, degrade output to fit budget');
+}
+/** L3 降级输出决策 */
+function degradedDecision(spill, reason) {
+    return {
+        level: 'L3-degraded',
+        maxEdge: DEGRADED_MAX_EDGE,
+        quality: DEGRADED_QUALITY,
+        spill,
+        reason,
+    };
+}
+/** L4 拒绝决策 */
+function rejectDecision(inputBytes, budget, reason) {
+    return {
+        level: 'L4-reject',
+        spill: false,
+        reason: `reject: ${reason} (input=${inputBytes}B, budget=${budget}B)`,
+    };
+}
+/**
+ * 估算把位图缩放到 maxEdge 后的解码字节数(按面积比例缩放)。
+ * 用于 L4 判定:若缩放后仍超 critical 则无救。
+ */
+function scaleDecodedEstimate(decodedBytes, maxEdge) {
+    // decodedBytes ∝ width*height。缩放到 maxEdge 按长边,面积比 = (max/orig)^2。
+    // 但我们不知原始 width/height,只有 decodedBytes。保守起见:若 decodedBytes
+    // 已大于 maxEdge*maxEdge*4(即缩放后的占用),说明原图比 maxEdge 大,缩放有效;
+    // 否则原图已 <= maxEdge,缩放无变化,估算 = decodedBytes。
+    const scaledCap = maxEdge * maxEdge * 4;
+    return Math.min(decodedBytes, scaledCap);
+}
+/**
+ * L4 拒绝时抛出的错误,携带用户可读的引导建议。
+ *
+ * 引导文案面向终端用户(经 UI 展示),而非开发者堆栈。
+ */
+export class DegradationRejectedError extends Error {
+    level = 'L4-reject';
+    inputBytes;
+    budget;
+    /** 用户可读的引导建议(UI 可直接渲染) */
+    guide;
+    constructor(inputBytes, budget, reason) {
+        super(`Operation rejected to avoid out-of-memory: ${reason}. ` +
+            `Input ${formatBytes(inputBytes)} exceeds memory budget ${formatBytes(budget)}.`);
+        this.name = 'DegradationRejectedError';
+        this.inputBytes = inputBytes;
+        this.budget = budget;
+        this.guide = buildGuide(inputBytes, budget);
+    }
+}
+/** 构造用户引导建议(按优先级) */
+function buildGuide(inputBytes, budget) {
+    const guide = [];
+    if (inputBytes > budget) {
+        guide.push(`This image (${formatBytes(inputBytes)}) is larger than the in-browser memory budget ` +
+            `(${formatBytes(budget)}). Try a smaller source image.`);
+    }
+    guide.push('Close other browser tabs to free memory, then retry.');
+    guide.push('For very large images, use the desktop app or process in smaller batches.');
+    return guide;
+}
+/** 字节数 → 人类可读(MB/GB) */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '0B';
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
+/**
+ * 把降级决策应用到 resize 参数(若 L3):确保输出最大边不超过 maxEdge。
+ *
+ * 调用方在 L3 时据此调整 params.width/height,再交给 engine.resize。
+ * L1/L2/L4 时原样返回 params。
+ */
+export function applyDegradationToResizeParams(params, decision) {
+    if (decision.level !== 'L3-degraded' || decision.maxEdge === undefined) {
+        return params;
+    }
+    const next = { ...params };
+    // 只要任一已指定的边超过 maxEdge,就注入 maxEdge 上限保护内存。
+    // undefined 视为"未约束",不参与 veto;已指定且 ≤ maxEdge 的边才排除 maxEdge。
+    const w = next.width;
+    const h = next.height;
+    const wOver = w !== undefined && w > decision.maxEdge;
+    const hOver = h !== undefined && h > decision.maxEdge;
+    const wUnset = w === undefined;
+    const hUnset = h === undefined;
+    if (wOver || hOver || (wUnset && hUnset)) {
+        next.maxEdge = decision.maxEdge;
+    }
+    return next;
+}
+//# sourceMappingURL=degradation.js.map

package/dist/degradation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation.js","sourceRoot":"","sources":["../src/degradation.ts"],"names":[],"mappings":"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"}

package/dist/history-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * History Store —— 历史栈 IndexedDB 持久化(W7.2)
+ *
+ * 把每个工作流的 HistoryStack 快照(entries + cursor)连同 initialInputs /
+ * currentOutputs 一起持久化到独立 Dexie 库 `lokvis-history`,实现跨会话保留:
+ * 刷新页面后,undo/redo 历史与"当前输出"游标均可恢复(前提:outputs 引用的
+ * 资产仍在 OPFS/IDB 中,由 W6.6 元数据持久化保证)。
+ *
+ * 与 OpfsMetadataDatabase 同样的降级策略:IndexedDB 不可用时返回 undefined,
+ * runtime 退化为仅内存历史(刷新后丢失,与 W2 行为一致)。
+ *
+ * 持久化时机(由 runtime 驱动):
+ * - 历史变更(append/undo/redo/jumpTo/clear/reset):HistoryStack.onChanged 回调
+ *   → runtime.persistHistory(workflowId) → save
+ * - 条目清空(reset/clear):save 检测到 entries 为空时改为 delete,避免残留空记录
+ * - disposeWorkflow:stack.reset() 触发 onChanged → persistHistory → delete
+ *
+ * 恢复时机:
+ * - createRuntime 工厂构造完 impl 后调 loadPersistedHistory() 预加载所有快照
+ */
+import Dexie, { type Table } from 'dexie';
+import type { AssetId, HistoryEntry } from '@lokvis/schema';
+/** 持久化的历史记录(每个工作流一条) */
+export interface HistoryRecord {
+    /** 主键 = 工作流 ID */
+    workflowId: string;
+    /** 历史条目(按时间顺序) */
+    entries: HistoryEntry[];
+    /** 游标:-1 表示无已应用条目;i 表示第 i 条已应用 */
+    cursor: number;
+    /** 工作流初始输入 AssetId(undo 回到初始时使用) */
+    initialInputs: AssetId[];
+    /** 工作流当前输出 AssetId(undo/redo 后的"当前"状态) */
+    currentOutputs: AssetId[];
+    /** 最后更新时间戳(用于排查与潜在 TTL 清理) */
+    updatedAt: number;
+}
+/**
+ * 历史持久化数据库。
+ *
+ * 独立于 OpfsMetadataDatabase('lokvis-opfs-metadata')与 IdbAssetStore
+ * ('lokvis-assets'),避免与资产元数据冲突。表以 workflowId 为主键,
+ * 额外索引 updatedAt 便于未来按时间清理陈旧记录。
+ */
+export declare class HistoryDatabase extends Dexie {
+    history: Table<HistoryRecord, string>;
+    constructor(name?: string);
+}
+/** HistoryStore 抽象接口(便于测试注入 mock) */
+export interface HistoryStore {
+    /** 保存(或覆盖)一条历史记录 */
+    save(record: HistoryRecord): Promise<void>;
+    /** 读取指定工作流的历史记录 */
+    load(workflowId: string): Promise<HistoryRecord | undefined>;
+    /** 读取全部历史记录(用于启动时预加载) */
+    loadAll(): Promise<HistoryRecord[]>;
+    /** 删除指定工作流的历史记录 */
+    delete(workflowId: string): Promise<void>;
+    /** 清空所有历史记录 */
+    clear(): Promise<void>;
+}
+/** HistoryStore 工厂选项 */
+export interface HistoryStoreOptions {
+    /** 测试注入:自定义数据库实例 */
+    dbInstance?: HistoryDatabase;
+    /** 数据库名(默认 'lokvis-history';仅 dbInstance 未注入时生效) */
+    dbName?: string;
+}
+/**
+ * 创建 HistoryStore。
+ *
+ * IndexedDB 不可用时返回 undefined,调用方(runtime)据此跳过持久化,
+ * 退化为仅内存历史模式。
+ */
+export declare function createHistoryStore(options?: HistoryStoreOptions): HistoryStore | undefined;
+//# sourceMappingURL=history-store.d.ts.map

package/dist/history-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-store.d.ts","sourceRoot":"","sources":["../src/history-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG5D,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,0CAA0C;IAC1C,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,OAAO,EAAG,KAAK,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;gBAE3B,IAAI,SAAmB;CAMpC;AAED,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,mBAAmB;IACnB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAC7D,yBAAyB;IACzB,OAAO,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACpC,mBAAmB;IACnB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,eAAe;IACf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAwB;AACxB,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,mBAAwB,GAChC,YAAY,GAAG,SAAS,CAqD1B"}

package/dist/history-store.js

@@ -0,0 +1,109 @@
+/**
+ * History Store —— 历史栈 IndexedDB 持久化(W7.2)
+ *
+ * 把每个工作流的 HistoryStack 快照(entries + cursor)连同 initialInputs /
+ * currentOutputs 一起持久化到独立 Dexie 库 `lokvis-history`,实现跨会话保留:
+ * 刷新页面后,undo/redo 历史与"当前输出"游标均可恢复(前提:outputs 引用的
+ * 资产仍在 OPFS/IDB 中,由 W6.6 元数据持久化保证)。
+ *
+ * 与 OpfsMetadataDatabase 同样的降级策略:IndexedDB 不可用时返回 undefined,
+ * runtime 退化为仅内存历史(刷新后丢失,与 W2 行为一致)。
+ *
+ * 持久化时机(由 runtime 驱动):
+ * - 历史变更(append/undo/redo/jumpTo/clear/reset):HistoryStack.onChanged 回调
+ *   → runtime.persistHistory(workflowId) → save
+ * - 条目清空(reset/clear):save 检测到 entries 为空时改为 delete,避免残留空记录
+ * - disposeWorkflow:stack.reset() 触发 onChanged → persistHistory → delete
+ *
+ * 恢复时机:
+ * - createRuntime 工厂构造完 impl 后调 loadPersistedHistory() 预加载所有快照
+ */
+import Dexie, {} from 'dexie';
+import { isIdbSupported } from './idb-asset-store.js';
+/**
+ * 历史持久化数据库。
+ *
+ * 独立于 OpfsMetadataDatabase('lokvis-opfs-metadata')与 IdbAssetStore
+ * ('lokvis-assets'),避免与资产元数据冲突。表以 workflowId 为主键,
+ * 额外索引 updatedAt 便于未来按时间清理陈旧记录。
+ */
+export class HistoryDatabase extends Dexie {
+    history;
+    constructor(name = 'lokvis-history') {
+        super(name);
+        this.version(1).stores({
+            history: 'workflowId, updatedAt',
+        });
+    }
+}
+/**
+ * 创建 HistoryStore。
+ *
+ * IndexedDB 不可用时返回 undefined,调用方(runtime)据此跳过持久化,
+ * 退化为仅内存历史模式。
+ */
+export function createHistoryStore(options = {}) {
+    const db = resolveHistoryDb(options);
+    if (!db)
+        return undefined;
+    return {
+        async save(record) {
+            try {
+                await db.history.put(record);
+            }
+            catch (err) {
+                // 持久化失败不阻断历史操作,仅 warn 便于排查
+                console.warn(`[lokvis] history store save failed for ${record.workflowId}:`, err);
+            }
+        },
+        async load(workflowId) {
+            try {
+                return await db.history.get(workflowId);
+            }
+            catch (err) {
+                console.warn(`[lokvis] history store load failed for ${workflowId}:`, err);
+                return undefined;
+            }
+        },
+        async loadAll() {
+            try {
+                return await db.history.toArray();
+            }
+            catch (err) {
+                console.warn('[lokvis] history store loadAll failed:', err);
+                return [];
+            }
+        },
+        async delete(workflowId) {
+            try {
+                await db.history.delete(workflowId);
+            }
+            catch (err) {
+                console.warn(`[lokvis] history store delete failed for ${workflowId}:`, err);
+            }
+        },
+        async clear() {
+            try {
+                await db.history.clear();
+            }
+            catch (err) {
+                console.warn('[lokvis] history store clear failed:', err);
+            }
+        },
+    };
+}
+/** 解析历史数据库实例(注入优先,否则在 IDB 可用时新建) */
+function resolveHistoryDb(options) {
+    if (options.dbInstance)
+        return options.dbInstance;
+    if (!isIdbSupported())
+        return undefined;
+    try {
+        return new HistoryDatabase(options.dbName);
+    }
+    catch (err) {
+        console.warn('[lokvis] history database init failed, falling back to memory-only:', err);
+        return undefined;
+    }
+}
+//# sourceMappingURL=history-store.js.map

package/dist/history-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-store.js","sourceRoot":"","sources":["../src/history-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,EAAc,MAAM,OAAO,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAkBtD;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,OAAO,CAAgC;IAEvC,YAAY,IAAI,GAAG,gBAAgB;QACjC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACrB,OAAO,EAAE,uBAAuB;SACjC,CAAC,CAAC;IACL,CAAC;CACF;AAwBD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAA+B,EAAE;IAEjC,MAAM,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAE1B,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,MAAM;YACf,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,2BAA2B;gBAC3B,OAAO,CAAC,IAAI,CACV,0CAA0C,MAAM,CAAC,UAAU,GAAG,EAC9D,GAAG,CACJ,CAAC;YACJ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,UAAU;YACnB,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC1C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CACV,0CAA0C,UAAU,GAAG,EACvD,GAAG,CACJ,CAAC;gBACF,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACpC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;gBAC5D,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,UAAU;YACrB,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CACV,4CAA4C,UAAU,GAAG,EACzD,GAAG,CACJ,CAAC;YACJ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,KAAK;YACT,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,oCAAoC;AACpC,SAAS,gBAAgB,CACvB,OAA4B;IAE5B,IAAI,OAAO,CAAC,UAAU;QAAE,OAAO,OAAO,CAAC,UAAU,CAAC;IAClD,IAAI,CAAC,cAAc,EAAE;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,qEAAqE,EACrE,GAAG,CACJ,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/idb-asset-store.js

@@ -41,7 +41,7 @@ export async function createIdbAssetStore(options = {}) {
     const db = options.dbInstance ?? new AssetDatabase(options.dbName);
     return {
         async import(source) {
-            const { id, blob, metadata, type } = prepareImport(source);
+            const { id, blob, metadata, type } = await prepareImport(source);
             const asset = buildAsset(id, blob, metadata, type, IDB_PATH_PREFIX);
             await db.assets.put({ id, asset, blob });
             return asset;

package/dist/idb-asset-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"idb-asset-store.js","sourceRoot":"","sources":["../src/idb-asset-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"idb-asset-store.js","sourceRoot":"","sources":["../src/idb-asset-store.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -14,6 +14,11 @@ export * from './executor.js';
 export * from './worker-protocol.js';
 export * from './worker-host.js';
 export * from './history.js';
+export * from './history-store.js';
+export * from './memory-guard.js';
+export * from './degradation.js';
+export * from './batch-processor.js';
+export * from './workflow-builder.js';
 export * from './runtime.js';
 export { RUNTIME_VERSION } from './runtime.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -14,6 +14,11 @@ export * from './executor.js';
 export * from './worker-protocol.js';
 export * from './worker-host.js';
 export * from './history.js';
+export * from './history-store.js';
+export * from './memory-guard.js';
+export * from './degradation.js';
+export * from './batch-processor.js';
+export * from './workflow-builder.js';
 export * from './runtime.js';
 export { RUNTIME_VERSION } from './runtime.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/memory-guard.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 内存阈值监测与 OPFS 溢出(W3.3)
+ *
+ * 目标(对应 whitepaper T1「浏览器内存/性能 ★★★★★」):
+ * 浏览器单 tab 内存有限(桌面典型 2-4GB,移动端更少),大图批量处理
+ * 极易触发 OOM 崩溃(整个 tab 被杀,丢失所有中间结果)。MemoryGuard 通过
+ * 显式追踪中间结果占用 + 周期性压力评估,在逼近预算时把中间 Blob 溢出
+ * 到 OPFS,把"OPFS 当虚拟内存用"——内存里只留当前活跃的一两个 Blob。
+ *
+ * 设计取舍:
+ * - tracked:显式登记的中间分配(decode 结果、canvas 输出等大对象)。
+ *   相比 `performance.memory`(Chrome-only、deprecated、MB 粒度、跨浏览器
+ *   不可用),tracked 是可控、可测、确定性的信号,适合做预算判定主依据。
+ * - budget:512MB(经验值——留出 JS runtime / DOM / 其他 tab 的余量,
+ *   实际由 RuntimeConfig.memoryBudget 传入,默认 512MB)。
+ * - pressure:low(<60%) / elevated(60-80%) / high(80-95%) / critical(≥95%)。
+ * - shouldSpill:pressure >= high 时建议把当前中间结果落 OPFS。
+ * - spill/restore/evict:经由 AssetStore(OPFS-backed when available;
+ *   runtime 已用 wrapAssetStoreWithQuota 包裹,溢出受 storageQuota 约束,
+ *   避免无限溢出把磁盘填满)。
+ *
+ * 集成方式(由 W3.4 degradation 编排):
+ *   const guard = new MemoryGuard({ budget, assetStore });
+ *   const alloc = guard.track(blob.size);          // 登记
+ *   if (guard.shouldSpill()) { const a = await guard.spill(blob); blob = null; }  // 溢出
+ *   ...
+ *   alloc.release();                                // 回退
+ */
+import type { Asset, AssetType } from '@lokvis/schema';
+import type { AssetStore } from './asset-store.js';
+/** 默认内存预算:512MB(见上) */
+export declare const DEFAULT_MEMORY_BUDGET: number;
+/** 内存压力等级(降级阶梯 W3.4 据此选择策略) */
+export type MemoryPressure = 'low' | 'elevated' | 'high' | 'critical';
+export interface MemoryGuardOptions {
+    /** 总内存预算(字节),超出 high 阈值则建议溢出 */
+    budget?: number;
+    /** elevated 阈值占 budget 比例(默认 0.6) */
+    elevatedRatio?: number;
+    /** high 阈值(默认 0.8):达到则 shouldSpill=true */
+    highRatio?: number;
+    /** critical 阈值(默认 0.95):达到则降级阶梯走 L4 拒绝 */
+    criticalRatio?: number;
+    /** 溢出目标(通常为 OPFS-backed AssetStore);不提供则 shouldSpill 永远 false */
+    assetStore?: AssetStore;
+}
+/** track() 返回的分配句柄:丢弃引用时调用 release() 回退计数(幂等) */
+export interface MemoryAllocation {
+    /** 该笔登记的字节数 */
+    readonly bytes: number;
+    /** 回退登记;重复调用幂等(仅首次生效) */
+    release(): void;
+}
+/**
+ * 估算解码后位图占用的内存(RGBA,4 字节/像素)。
+ *
+ * 一个 4000×3000 的 JPEG,blob 可能只有 2MB,但 decode 成 ImageBitmap 后
+ * 占 4000*3000*4 ≈ 46MB。追踪中间结果时应以此为准而非 blob.size,
+ * 否则严重低估内存压力。
+ */
+export declare function estimateDecodedBytes(width: number, height: number): number;
+/** 估算 Blob 在内存中占用的字节数(对未解码的 Blob,以其 size 为准) */
+export declare function estimateBlobBytes(blob: Blob): number;
+/** 内存守卫:追踪中间结果占用 + 触发 OPFS 溢出 */
+export declare class MemoryGuard {
+    private tracked;
+    private readonly budget;
+    private readonly elevatedRatio;
+    private readonly highRatio;
+    private readonly criticalRatio;
+    private readonly assetStore?;
+    constructor(opts?: MemoryGuardOptions);
+    /** 当前已登记的字节数 */
+    get currentUsage(): number;
+    /** 总预算(字节) */
+    get budgetBytes(): number;
+    /** 当前是否已配置可溢出的 AssetStore */
+    get canSpill(): boolean;
+    /**
+     * 登记一笔内存占用。返回 release 句柄,丢弃引用时调用以回退计数。
+     * 用于追踪 decode 结果 / canvas 输出等大对象的生命周期。
+     */
+    track(bytes: number): MemoryAllocation;
+    /** 当前压力等级(基于 tracked / budget) */
+    getPressure(): MemoryPressure;
+    /** 已用比例(0-1+) */
+    getUsageRatio(): number;
+    /**
+     * 是否应溢出(pressure >= high)。无 assetStore 时永远 false(无法溢出,
+     * 交由降级阶梯 L3/L4 处理)。
+     */
+    shouldSpill(): boolean;
+    /**
+     * 把一个中间 Blob 溢出到 OPFS(assetStore.create),返回 Asset 句柄。
+     * 调用方应在 spill 后丢弃内存中的 Blob 引用,以真正释放内存。
+     *
+     * @param blob 要溢出的中间结果
+     * @param mimeType Blob 的 MIME(用于元数据);默认取 blob.type
+     * @param assetType 资产类型(默认 'image');video/pdf 管线可传对应类型
+     */
+    spill(blob: Blob, mimeType?: string, assetType?: AssetType): Promise<Asset>;
+    /** 从 OPFS 读回之前 spill 的中间结果 */
+    restore(asset: Asset): Promise<Blob>;
+    /** 丢弃已 spill 的中间结果(处理完成后回收 OPFS 空间) */
+    evict(asset: Asset): Promise<void>;
+    /** 重置所有登记(用于工作流结束 / 取消后的清理,tracked 归零) */
+    reset(): void;
+}
+//# sourceMappingURL=memory-guard.d.ts.map

package/dist/memory-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-guard.d.ts","sourceRoot":"","sources":["../src/memory-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAiB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,uBAAuB;AACvB,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAEvD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtE,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEpD;AAED,iCAAiC;AACjC,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;gBAE7B,IAAI,GAAE,kBAAuB;IAgBzC,gBAAgB;IAChB,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,cAAc;IACd,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,6BAA6B;IAC7B,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAgBtC,kCAAkC;IAClC,WAAW,IAAI,cAAc;IAQ7B,iBAAiB;IACjB,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,WAAW,IAAI,OAAO;IAMtB;;;;;;;OAOG;IACG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,SAAmB,GAAG,OAAO,CAAC,KAAK,CAAC;IAgB1F,8BAA8B;IACxB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C,uCAAuC;IACjC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC,0CAA0C;IAC1C,KAAK,IAAI,IAAI;CAGd"}