@lokvis/runtime 0.1.0

package/dist/worker-protocol.d.ts.map

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

package/dist/worker-protocol.js

@@ -0,0 +1,87 @@
+/**
+ * Worker 通信协议
+ *
+ * 定义 主线程(Host) ↔ Worker 之间的消息格式与握手/心跳规范。
+ * 协议本身与传输层解耦(纯类型 + 常量 + 校验助手),
+ * 既可用于浏览器 Web Worker,也可在测试中被 Fake 传输层复用。
+ *
+ * 设计目标(对应 whitepaper T1「浏览器内存/性能 ★★★★★」与 PROJECT_PLAN 1.6/1.7):
+ * - 每个请求有唯一 id,Response 按 id 关联,避免错配。
+ * - 心跳(Heartbeat):Host 周期性 ping,Worker 必须在超时内 pong,否则视为崩溃。
+ * - Ready 握手:Worker 启动后主动发 ready,Host 据此判定可用。
+ * - 错误通道:Worker 主动 error(可恢复) vs 传输层 error/exit(不可恢复,触发重启)。
+ *
+ * 消息流向:
+ *   Host → Worker:  request | ping
+ *   Worker → Host:  response | pong | event | ready | error
+ */
+/** 协议版本(Host 与 Worker 握手时校验,不一致则拒绝) */
+export const WORKER_PROTOCOL_VERSION = '0.1.0';
+// ─── 默认参数(可通过 WorkerHostOptions 覆盖)──────────────────────
+/** 心跳发送间隔 */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+/** 心跳超时:超过该时间未收到 pong 视为 Worker 无响应 */
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15_000;
+/** 单个请求的默认超时 */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+/** 崩溃后最大重启次数(超过则放弃,交由上层降级) */
+export const DEFAULT_MAX_RESTARTS = 3;
+/** Worker 启动后等待 ready 的超时 */
+export const DEFAULT_READY_TIMEOUT_MS = 10_000;
+// ─── 助手函数 ───────────────────────────────────────────────────
+/** 生成唯一请求/心跳 id */
+export function createRequestId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/** 类型守卫:是否为 Worker → Host 消息 */
+export function isWorkerMessageToHost(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const type = data.type;
+    return (type === 'response' ||
+        type === 'pong' ||
+        type === 'event' ||
+        type === 'ready' ||
+        type === 'error');
+}
+/** 类型守卫:是否为响应消息 */
+export function isWorkerResponse(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.type === 'response' &&
+        typeof data.id === 'string' &&
+        typeof data.ok === 'boolean');
+}
+/** 类型守卫:是否为 pong */
+export function isWorkerPong(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.type === 'pong');
+}
+/** 类型守卫:是否为 ready */
+export function isWorkerReady(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.type === 'ready');
+}
+/** 类型守卫:是否为 Worker 主动事件 */
+export function isWorkerEvent(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.type === 'event' &&
+        typeof data.event === 'string');
+}
+/** 类型守卫:是否为 Worker 主动上报错误 */
+export function isWorkerFatalError(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.type === 'error');
+}
+/** 协议版本是否兼容(目前采用严格相等) */
+export function isProtocolCompatible(version) {
+    return version === WORKER_PROTOCOL_VERSION;
+}
+//# sourceMappingURL=worker-protocol.js.map

package/dist/worker-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.js","sourceRoot":"","sources":["../src/worker-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,uCAAuC;AACvC,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAE/C,2DAA2D;AAC3D,aAAa;AACb,MAAM,CAAC,MAAM,6BAA6B,GAAG,KAAK,CAAC;AACnD,uCAAuC;AACvC,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AACnD,gBAAgB;AAChB,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AACjD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AACtC,6BAA6B;AAC7B,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AA+E/C,+DAA+D;AAE/D,mBAAmB;AACnB,MAAM,UAAU,eAAe;IAC7B,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC7E,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,qBAAqB,CACnC,IAAa;IAEb,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,CACL,IAAI,KAAK,UAAU;QACnB,IAAI,KAAK,MAAM;QACf,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,OAAO,CACjB,CAAC;AACJ,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAA2B,CAAC,IAAI,KAAK,UAAU;QAChD,OAAQ,IAAyB,CAAC,EAAE,KAAK,QAAQ;QACjD,OAAQ,IAAyB,CAAC,EAAE,KAAK,SAAS,CACnD,CAAC;AACJ,CAAC;AAED,oBAAoB;AACpB,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAA2B,CAAC,IAAI,KAAK,MAAM,CAC7C,CAAC;AACJ,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAA2B,CAAC,IAAI,KAAK,OAAO,CAC9C,CAAC;AACJ,CAAC;AAED,2BAA2B;AAC3B,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAA2B,CAAC,IAAI,KAAK,OAAO;QAC7C,OAAQ,IAA4B,CAAC,KAAK,KAAK,QAAQ,CACxD,CAAC;AACJ,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAA2B,CAAC,IAAI,KAAK,OAAO,CAC9C,CAAC;AACJ,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,OAAO,KAAK,uBAAuB,CAAC;AAC7C,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lokvis/runtime",
+  "version": "0.1.0",
+  "description": "Lokvis Runtime - Browser-local workflow execution engine",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.spec.ts",
+    "!**/*.spec.tsx"
+  ],
+  "dependencies": {
+    "dexie": "^4.0.10",
+    "mitt": "^3.0.1",
+    "@lokvis/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.0.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lokvis/lokvis.git",
+    "directory": "packages/runtime"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/asset-store.ts

@@ -0,0 +1,222 @@
+/**
+ * Lokvis Asset Store
+ *
+ * 资产存储管理。元数据存 IndexedDB，大文件存 OPFS。
+ * Runtime 只操作 AssetId，不直接持有 File 或 Blob。
+ *
+ * 降级链(createAssetStore 工厂,W2.8):
+ *   preferOpfs → OPFS → IndexedDB(Dexie) → Memory(始终可用,不持久化)
+ */
+
+import type { Asset, AssetId, AssetMetadata, AssetSource, BlobHandle } from '@lokvis/schema';
+import { createOpfsAssetStore, isOpfsSupported } from './opfs-asset-store.js';
+import { createIdbAssetStore, isIdbSupported } from './idb-asset-store.js';
+
+/** Asset 存储接口 */
+export interface AssetStore {
+  /** 导入资产（从 File / Blob / URL） */
+  import(source: AssetSource): Promise<Asset>;
+  /** 获取资产元数据 */
+  get(id: AssetId): Promise<Asset | undefined>;
+  /** 获取资产的 Blob 数据 */
+  getBlob(handle: BlobHandle): Promise<Blob>;
+  /** 删除资产 */
+  remove(id: AssetId): Promise<void>;
+  /** 列出所有资产 */
+  list(): Promise<Asset[]>;
+  /** 创建新 Asset（内部用，由 Capability 产出） */
+  create(blob: Blob, metadata: AssetMetadata, type: Asset['type']): Promise<Asset>;
+}
+
+/** 生成唯一 ID */
+export function generateId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `asset_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** 从 MIME 类型推断 Asset 类型 */
+export function inferAssetType(mimeType: string): Asset['type'] {
+  if (mimeType.startsWith('image/')) return 'image';
+  if (mimeType.startsWith('video/')) return 'video';
+  if (mimeType.startsWith('audio/')) return 'audio';
+  if (mimeType === 'application/pdf') return 'pdf';
+  if (mimeType.startsWith('text/')) return 'text';
+  if (mimeType === 'application/json' || mimeType.startsWith('application/'))
+    return 'data';
+  return 'unknown';
+}
+
+/** 从 MIME 类型获取格式扩展名 */
+export function getFormatFromMime(mimeType: string): string {
+  const parts = mimeType.split('/');
+  return parts[1] ?? 'bin';
+}
+
+/** 从 AssetSource 提取 Blob 与 MIME(支持 file/blob,其余抛 not supported) */
+export function extractBlobFromSource(source: AssetSource): {
+  blob: Blob;
+  mimeType: string;
+} {
+  if (source.kind === 'file') {
+    return { blob: source.file, mimeType: source.file.type };
+  }
+  if (source.kind === 'blob') {
+    return { blob: source.blob, mimeType: source.blob.type };
+  }
+  throw new Error(
+    `Asset source kind "${source.kind}" not supported by this store`
+  );
+}
+
+/** prepareImport 返回值:统一构造的导入数据(供三个 store 复用) */
+export interface PreparedImport {
+  id: AssetId;
+  blob: Blob;
+  metadata: AssetMetadata;
+  type: Asset['type'];
+}
+
+/**
+ * 从 AssetSource 准备导入数据(共享逻辑,供 Memory/OPFS/IDB store 复用):
+ * 提取 blob + MIME、生成 id、推断 type、构造 metadata。
+ * 各 store 只需负责"写入 blob + 存元数据"。
+ */
+export function prepareImport(source: AssetSource): PreparedImport {
+  const { blob, mimeType: rawMime } = extractBlobFromSource(source);
+  const id = generateId();
+  const mimeType = rawMime || 'application/octet-stream';
+  const type = inferAssetType(mimeType);
+  const metadata: AssetMetadata = {
+    mimeType,
+    size: blob.size,
+    format: getFormatFromMime(mimeType),
+  };
+  return { id, blob, metadata, type };
+}
+
+/** 从 BlobHandle.path 解析出 AssetId(共享,各 store 按 prefix 调用) */
+export function parseBlobPath(path: string, prefix: string): AssetId {
+  const fullPrefix = `${prefix}://`;
+  if (path.startsWith(fullPrefix)) {
+    return path.slice(fullPrefix.length);
+  }
+  return path;
+}
+
+/** 构造完整 Asset 元数据 + 默认字段(共享工厂) */
+export function buildAsset(
+  id: AssetId,
+  blob: Blob,
+  metadata: AssetMetadata,
+  type: Asset['type'],
+  pathPrefix: string
+): Asset {
+  const now = Date.now();
+  return {
+    id,
+    type,
+    metadata,
+    blob: {
+      path: `${pathPrefix}://${id}`,
+      size: blob.size,
+      mimeType: metadata.mimeType,
+    },
+    history: [],
+    tags: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/** Memory store 的 BlobHandle.path 前缀 */
+const MEMORY_PATH_PREFIX = 'memory';
+
+/** 创建内存版 AssetStore（降级方案，不持久化） */
+export function createMemoryAssetStore(): AssetStore {
+  const assets = new Map<AssetId, Asset>();
+  const blobs = new Map<AssetId, Blob>();
+
+  return {
+    async import(source) {
+      const { id, blob, metadata, type } = prepareImport(source);
+      blobs.set(id, blob);
+      const asset = buildAsset(id, blob, metadata, type, MEMORY_PATH_PREFIX);
+      assets.set(id, asset);
+      return asset;
+    },
+
+    async get(id) {
+      return assets.get(id);
+    },
+
+    async getBlob(handle) {
+      const id = parseBlobPath(handle.path, MEMORY_PATH_PREFIX);
+      const blob = blobs.get(id);
+      if (!blob) throw new Error(`Blob not found for path: ${handle.path}`);
+      return blob;
+    },
+
+    async remove(id) {
+      assets.delete(id);
+      blobs.delete(id);
+    },
+
+    async list() {
+      return Array.from(assets.values());
+    },
+
+    async create(blob, metadata, type) {
+      const id = generateId();
+      blobs.set(id, blob);
+      const asset = buildAsset(id, blob, metadata, type, MEMORY_PATH_PREFIX);
+      assets.set(id, asset);
+      return asset;
+    },
+  };
+}
+
+/** 工厂配置(W2.8) */
+export interface CreateAssetStoreOptions {
+  /** 是否优先使用 OPFS(默认 true);为 false 时跳过 OPFS */
+  preferOpfs?: boolean;
+}
+
+/**
+ * AssetStore 工厂:自动探测环境,按降级链创建存储(W2.8)。
+ *
+ * 顺序:
+ *   1. preferOpfs(默认 true)且 OPFS 可用 → OpfsAssetStore
+ *   2. IndexedDB 可用 → IdbAssetStore(Dexie)
+ *   3. 兜底 → MemoryAssetStore(始终可用,不持久化)
+ *
+ * 任一阶段抛错均自动降级,最终必定返回一个可用 store。
+ */
+export async function createAssetStore(
+  options: CreateAssetStoreOptions = {}
+): Promise<AssetStore> {
+  const preferOpfs = options.preferOpfs ?? true;
+
+  // 1. OPFS
+  if (preferOpfs && isOpfsSupported()) {
+    try {
+      return await createOpfsAssetStore();
+    } catch (err) {
+      // OPFS 初始化失败,降级到 IndexedDB
+      console.warn('[lokvis] OPFS unavailable, falling back to IndexedDB:', err);
+    }
+  }
+
+  // 2. IndexedDB
+  if (isIdbSupported()) {
+    try {
+      return await createIdbAssetStore();
+    } catch (err) {
+      console.warn('[lokvis] IndexedDB unavailable, falling back to memory:', err);
+    }
+  }
+
+  // 3. Memory(兜底,始终可用)
+  return createMemoryAssetStore();
+}

package/src/capability-registry.ts

@@ -0,0 +1,135 @@
+/**
+ * Lokvis Capability Registry
+ *
+ * 能力注册中心。Runtime 永远不知道 FFmpeg，只知道 Capability。
+ * Capability 由 Plugin 注册，由 Engine 实现。
+ */
+
+import type {
+  Capability,
+  CapabilityImplementation,
+  CapabilityName,
+  EngineSelectionStrategy,
+  PerformanceLevel,
+} from '@lokvis/schema';
+
+/** 能力注册表项 */
+interface RegistryEntry {
+  /** 能力声明 */
+  capability: Capability;
+  /** 能力实现列表（同一能力可由多个引擎实现） */
+  implementations: CapabilityImplementation[];
+}
+
+/** 性能等级排序权重(数值越小越快) */
+const PERFORMANCE_RANK: Record<PerformanceLevel, number> = {
+  fast: 0,
+  medium: 1,
+  slow: 2,
+};
+
+/** 能力注册中心 */
+export class CapabilityRegistry {
+  private registry = new Map<CapabilityName, RegistryEntry>();
+  private readonly defaultStrategy: EngineSelectionStrategy;
+
+  constructor(defaultStrategy: EngineSelectionStrategy = 'first') {
+    this.defaultStrategy = defaultStrategy;
+  }
+
+  /** 注册一个能力声明 */
+  registerCapability(capability: Capability): void {
+    const existing = this.registry.get(capability.name);
+    if (existing) {
+      throw new Error(`Capability "${capability.name}" is already registered`);
+    }
+    this.registry.set(capability.name, { capability, implementations: [] });
+  }
+
+  /** 注册能力实现 */
+  registerImplementation(impl: CapabilityImplementation): void {
+    const entry = this.registry.get(impl.capability);
+    if (!entry) {
+      throw new Error(
+        `Cannot register implementation for unknown capability "${impl.capability}". Register the capability first.`
+      );
+    }
+    entry.implementations.push(impl);
+  }
+
+  /** 列出所有能力声明 */
+  list(): Capability[] {
+    return Array.from(this.registry.values()).map((e) => e.capability);
+  }
+
+  /** 检查能力是否存在 */
+  has(name: CapabilityName): boolean {
+    return this.registry.has(name);
+  }
+
+  /** 获取能力声明 */
+  get(name: CapabilityName): Capability | undefined {
+    return this.registry.get(name)?.capability;
+  }
+
+  /**
+   * 解析能力实现。
+   * - 若指定 preferredEngine 且存在匹配实现,直接返回;
+   * - 否则按构造时设定的 defaultStrategy 选择('first'/'fastest'/'balanced')。
+   */
+  resolve(name: CapabilityName, preferredEngine?: string): CapabilityImplementation | undefined {
+    const entry = this.registry.get(name);
+    if (!entry || entry.implementations.length === 0) return undefined;
+
+    if (preferredEngine) {
+      const impl = entry.implementations.find((i) => i.engine === preferredEngine);
+      if (impl) return impl;
+    }
+
+    return this.selectByStrategy(entry.implementations, entry.capability);
+  }
+
+  /** 按默认策略从实现列表中选择一个 */
+  private selectByStrategy(
+    impls: CapabilityImplementation[],
+    capability: Capability
+  ): CapabilityImplementation {
+    switch (this.defaultStrategy) {
+      case 'first':
+        return impls[0]!;
+      case 'fastest':
+        return this.fastest(impls, capability);
+      case 'balanced': {
+        // 优先取与能力声明 performance 匹配的实现(同档按注册顺序)
+        const target = capability.performance;
+        const matching = impls.filter((i) => this.perfOf(i, capability) === target);
+        if (matching.length > 0) return matching[0]!;
+        // 无匹配则退化为最快
+        return this.fastest(impls, capability);
+      }
+    }
+  }
+
+  /** 取性能等级最优的实现(同档按注册顺序,稳定排序) */
+  private fastest(
+    impls: CapabilityImplementation[],
+    capability: Capability
+  ): CapabilityImplementation {
+    return impls.reduce((best, cur) => {
+      const a = PERFORMANCE_RANK[this.perfOf(best, capability)];
+      const b = PERFORMANCE_RANK[this.perfOf(cur, capability)];
+      // 仅当严格更优时替换,保证同档保留先注册的(稳定性)
+      return b < a ? cur : best;
+    }, impls[0]!);
+  }
+
+  /** 实现的性能等级:优先用实现自身声明,缺省回退到能力声明 */
+  private perfOf(impl: CapabilityImplementation, capability: Capability): PerformanceLevel {
+    return impl.performance ?? capability.performance;
+  }
+
+  /** 清除所有注册 */
+  clear(): void {
+    this.registry.clear();
+  }
+}

package/src/event-bus.ts

@@ -0,0 +1,41 @@
+/**
+ * Lokvis Event Bus Implementation
+ *
+ * 基于 mitt 的轻量事件总线实现。
+ * 所有操作发出标准事件，Analytics/Undo/AI/Plugin 都监听事件。
+ */
+
+import mitt from 'mitt';
+import type { EventBus, LokvisEvent } from '@lokvis/schema';
+
+type Events = Record<string, unknown>;
+
+export function createEventBus(): EventBus {
+  const emitter = mitt<Events>();
+  const anyHandlers = new Set<(event: LokvisEvent) => void>();
+
+  return {
+    on(type, handler) {
+      const wrapped = (e: unknown) => handler(e as never);
+      emitter.on(type, wrapped);
+      return () => emitter.off(type, wrapped);
+    },
+
+    onAny(handler) {
+      anyHandlers.add(handler);
+      return () => anyHandlers.delete(handler);
+    },
+
+    emit(event) {
+      emitter.emit(event.type, event);
+      for (const handler of anyHandlers) {
+        handler(event);
+      }
+    },
+
+    clear() {
+      emitter.all.clear();
+      anyHandlers.clear();
+    },
+  };
+}