@cut-workbench/workbench 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cut Workbench contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @cut-workbench/workbench
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+可嵌入的浏览器端剪辑台 UI：素材库、预览、时间轴、属性面板与导出对话框。
+基于 React 19 + Tailwind CSS v4 + Radix，样式已作用域化，嵌进任何宿主都不污染。
+
+## 安装
+
+```bash
+npm i @cut-workbench/workbench @cut-workbench/core @cut-workbench/react react react-dom
+# 引擎依赖（预览 / 导出必需）
+npm i @webav/av-cliper @webav/av-canvas @webav/av-recorder
+```
+
+`@webav/*`、`react`、`react-dom`、`zustand` 是 peer 依赖，由宿主提供。
+`@webav/*` 必须与 core 用同一份实例，否则 clip 状态会互相破坏。
+
+## React 项目
+
+```tsx
+import { createEditor } from '@cut-workbench/core/engine'
+import { CutEditorProvider } from '@cut-workbench/react'
+import { CutWorkbench, CutWorkbenchProvider } from '@cut-workbench/workbench'
+import '@cut-workbench/workbench/style.css'
+
+const editor = createEditor()
+
+createRoot(el).render(
+  <CutEditorProvider editor={editor}>
+    <CutWorkbenchProvider theme="dark">
+      <CutWorkbench className="h-screen" onSaveProject={save} onOpenProject={open} />
+    </CutWorkbenchProvider>
+  </CutEditorProvider>,
+)
+```
+
+## 非 React 项目
+
+```js
+import { initCutWorkbench } from '@cut-workbench/workbench'
+import '@cut-workbench/workbench/style.css'
+
+const wb = initCutWorkbench('#app', { theme: 'dark', namespace: 'my-project' })
+await wb.whenReady()
+wb.on('export:done', ({ blob, filename }) => upload(blob, filename))
+```
+
+## script 标签 / 微前端
+
+UMD 单文件已把 React、WebAV、Worker 与样式全部内联，暴露 `window.CutWorkbench`：
+
+```html
+<script src="https://unpkg.com/@cut-workbench/workbench/dist/umd/cut-workbench.umd.js"></script>
+<script>
+  const wb = CutWorkbench.initCutWorkbench('#app', { theme: 'dark' })
+</script>
+```
+
+> ⚠️ React 19 不再发布 UMD 产物，因此 UMD 版本内置了一份 React。有任何构建工具时
+> 都优先选 ESM。
+
+## 主题定制
+
+```tsx
+<CutWorkbenchProvider theme="inherit" />        // 跟随宿主 <html class="dark">
+<CutWorkbenchProvider tokens={{ primary: '#4d6bfe', radius: '8px' }} />
+```
+
+token 通过根节点 inline style 应用，优先级高于样式表，不依赖引入顺序；变量都带
+`--cw-` 前缀且挂在 `.cw-root` 上，不污染宿主 `:root`。
+
+## 样式隔离
+
+- 不引 preflight，宿主 `h1` / `button` 默认样式不变；
+- 每条 utility 前置 `.cw-root`，宿主的 `.flex` 与工作台的互不干扰；
+- 不使用 `@layer`，避免被宿主未分层样式压过。
+
+## 导出与 Worker
+
+导出默认在 Web Worker 中执行，产物里的 `assets/export.worker-*.js` 由
+`@cut-workbench/workbench` 自身携带。若宿主有严格 CSP，可用
+`HostBridge.createExportWorker` 完全接管 Worker 的创建。
+
+含文字片段的工程会自动回退主线程渲染（文字依赖 DOM）。
+
+## 浏览器要求
+
+仅支持 Chromium 内核（Chrome / Edge）：WebAV 依赖 WebCodecs 与 OPFS。
+
+## License
+
+MIT

package/dist/CutWorkbench.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 工作台容器：把「三栏骨架 + 顶栏 + 弹窗」组装成一个可配置组件。
+ *
+ * 与旧 `App` 的区别：
+ * - 不自己创建编辑器（由外层 Provider 注入），因此支持多实例；
+ * - 顶栏的保存/打开走调用方传入的回调，不写死 IndexedDB；
+ * - 每个面板都可以被 `slots` 替换，宿主想换掉哪块就换哪块；
+ * - 不强制能力阻断页（宿主可自行决定）。
+ */
+import { type ReactNode } from 'react';
+export interface CutWorkbenchSlots {
+    /** 替换内置顶栏；传 `null` 表示不要顶栏 */
+    topBar?: ReactNode | null;
+    mediaLibrary?: ReactNode;
+    preview?: ReactNode;
+    inspector?: ReactNode;
+    timeline?: ReactNode;
+}
+export interface CutWorkbenchProps {
+    slots?: CutWorkbenchSlots;
+    className?: string;
+    /**
+     * 工程持久化回调。
+     *
+     * 不传则顶栏的「保存 / 打开」按钮隐藏 —— 库不假设宿主用 IndexedDB、文件还是云端。
+     */
+    onSaveProject?: () => Promise<void> | void;
+    onOpenProject?: () => Promise<void> | void;
+    /** 是否在能力不足时显示阻断页（宿主自己负责环境校验时可关闭） */
+    enforceCapability?: boolean;
+}
+/**
+ * 工作台主体。
+ *
+ * 必须在 `<WorkbenchProvider>` + `<CutEditorProvider>` 之内使用。
+ */
+export declare function CutWorkbench({ slots, className, onSaveProject, onOpenProject, enforceCapability, }: CutWorkbenchProps): import("react").JSX.Element;

package/dist/app/debug-bridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 开发环境调试桥。
+ *
+ * 仅用于自动化测试 / DevTools 检查内部状态（例如验证音频是否真的排程、撤销是否正确）。
+ * 生产构建会被 `import.meta.env.DEV` 条件完全剔除。
+ */
+import type { CutEditorHandle } from '@cut-workbench/core/engine';
+export declare function installDebugBridge(editor: CutEditorHandle): void;