@cut-workbench/workbench 0.1.0 → 0.2.0

package/README.md

@@ -5,22 +5,55 @@
 
 ## 安装
 
+**只需要装这一个包**：
+
 ```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
+npm i @cut-workbench/workbench
 ```
 
-`@webav/*`、`react`、`react-dom`、`zustand` 是 peer 依赖，由宿主提供。
-`@webav/*` 必须与 core 用同一份实例，否则 clip 状态会互相破坏。
+`@cut-workbench/core`、`@cut-workbench/react` 以及引擎依赖
+`@webav/av-cliper`、`@webav/av-canvas`、`@webav/av-recorder` 都是它的
+**dependencies**，会一起装上 —— 不需要你再显式安装，也不需要知道有这些东西。
+
+选装（按需）：
+
+| 想要什么 | 装什么 |
+|---|---|
+| 只取纯逻辑，不渲染 UI | `npm i @cut-workbench/core` |
+| 只要 React hooks，自己写 UI | `npm i @cut-workbench/core @cut-workbench/react` |
+| Electron 宿主桥（「下载」→「保存到指定路径」） | `npm i @cut-workbench/host-electron` |
+| 需要控制 React 实例 | 宿主自己提供 `react` / `react-dom` / `zustand`（见下） |
+
+### 关于 `react` / `react-dom` / `zustand`
+
+这三个是 **peer 依赖**，由宿主提供，库不会替你装 —— 一旦出现两份 React，
+宿主会碰到 `Cannot read properties of null (reading 'useContext')`。项目已有
+React 时无需任何额外操作。
+
+`zustand` 同理：`@cut-workbench/react` 直接 import 它，两份实例会让订阅错乱，
+所以必须由宿主提供（React 项目通常已有）。
+
+### 为什么 WebAV 是 dependencies 而不是 peer
+
+`@webav/*` 是**运行时必需**的：没有 `av-cliper` / `av-canvas` 就没有预览和
+导出，功能直接不可用。所以这个包选择把它们带上，让「装一个包就能用」成立。
+
+`@cut-workbench/core` 则相反 —— 它的定位是「只取纯逻辑」，有人只要 timeline
+模型和工程序列化，不该被迫装 WebAV，所以 core 那边是 `optional` peer。
+
+> ⚠️ 0.1.0 的 WebAV 是 peer，只靠 npm 7+ 自动安装 peer 的隐式行为碰巧能跑；
+> **pnpm / yarn 不会自动装 peer**，在它们下面构建会报
+> `[MISSING_EXPORT] "Combinator" is not exported by "__vite-optional-peer-dep:…"`。
+> 0.2.0 起改为 dependencies，与包管理器无关。
 
 ## React 项目
 
+**推荐：用 `/auto` 子入口**，一行自带样式：
+
 ```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'
+import { CutWorkbench, CutWorkbenchProvider } from '@cut-workbench/workbench/auto'
 
 const editor = createEditor()
 
@@ -33,11 +66,77 @@ createRoot(el).render(
 )
 ```
 
+**根入口不自带样式** —— 给已经有自己的构建流程、需要控制 CSS 顺序
+（例如要压过某条全局重置）的场景：
+
+```tsx
+import { CutWorkbench, CutWorkbenchProvider } from '@cut-workbench/workbench'
+import '@cut-workbench/workbench/style.css'   // ← 必须自己引，忘了就是无样式
+```
+
+两者的 API 完全一致，`/auto` 只是多了一行 `import './cut-workbench.css'`。
+**不要同时引两个入口** —— 样式会被引入两次（作用域化之后是幂等的，但没必要）。
+
+## 布局
+
+```
+┌───────────────────────────────────────────┐
+│ 顶栏                                      │
+├──────────┬──────────────┬─────────────────┤
+│ 素材库   │ 预览         │ 属性            │  ← 上半区，可纵向滚动
+├──────────┴──────────────┴─────────────────┤
+│ 时间轴（横跨整行）                        │  ← 下栏
+└───────────────────────────────────────────┘
+```
+
+时间轴**通栏占满底部一行**，不随左右面板宽度变化。左上「素材」、中「预览」、
+右「属性」三栏可拖拽调整，面板内的内容各自滚动。
+
+> 0.2.0 之前时间轴被塞在中间列里，左右面板一拉宽就把它挤窄，工具条按钮会
+> 溢出到属性面板上；窄列下播放控制条的时间码也会被裁掉。现在布局与控件都有
+> 容器级自适应（按容器宽度分档收起次要控件，而不是按视口宽度），
+> `scripts/layout-test.mjs` 守着这两条。
+
+## 顶栏定制
+
+内置顶栏分三层可定制，由浅到深：
+
+**1. 改文案** —— `labels`：
+
+```tsx
+<CutWorkbench toolbar={{ labels: { export: '导出成片', untitledProject: '新建项目' } }} />
+```
+
+**2. 改局部** —— `brand` / `title` / `status` / `actions`：
+
+```tsx
+<CutWorkbench
+  toolbar={{
+    brand: <MyLogo />,                      // 默认**没有**品牌区，避免露出本库名字
+    title: null,                            // 不要工程名区
+    status: <AutoSaveBadge />,              // 默认「空工程 · 16:9」
+    actions: <MyShareButton />,             // 追加在右侧按钮组末尾
+    editableTitle: true,                    // 双击工程名重命名（走撤销栈）
+    showCapabilityBadge: false,             // 隐藏引擎能力徽标
+  }}
+/>
+```
+
+**3. 整条替换** —— `slots.topBar`（优先级最高）：
+
+```tsx
+<CutWorkbench slots={{ topBar: <MyHeader /> }} />   // 传 null 表示完全不要顶栏
+```
+
+> `slots.topBar` 会替换**整条**顶栏，撤销/导出等内置动作一并由宿主负责；
+> `toolbar` 只换其中一块，其余保留。可运行示例见 playground 的
+> `/toolbar-demo.html`。
+
+
 ## 非 React 项目
 
 ```js
-import { initCutWorkbench } from '@cut-workbench/workbench'
-import '@cut-workbench/workbench/style.css'
+import { initCutWorkbench } from '@cut-workbench/workbench/auto'
 
 const wb = initCutWorkbench('#app', { theme: 'dark', namespace: 'my-project' })
 await wb.whenReady()
@@ -58,6 +157,51 @@ UMD 单文件已把 React、WebAV、Worker 与样式全部内联，暴露 `windo
 > ⚠️ React 19 不再发布 UMD 产物，因此 UMD 版本内置了一份 React。有任何构建工具时
 > 都优先选 ESM。
 
+## 类型与依赖缺失
+
+如果引擎依赖没解析到（例如被 npm 的 hoisting 拔掉、或在 pnpm 下版本冲突），
+工作台不会白屏：能力探测会把「缺依赖」和「浏览器不支持」分开报告，
+阻断页直接给出可执行的安装命令：
+
+```
+缺少 @webav/av-cliper，请执行 npm i @webav/av-cliper @webav/av-canvas @webav/av-recorder
+```
+
+注意缺失依赖只在**构建期**解析 —— 装完必须重新跑一次构建，刷新浏览器没用。
+
+## 关掉能力实验室（可选）
+
+`config.features.lab` 是**运行时**开关，默认 `false`。lab 本体是独立子入口
+`@cut-workbench/workbench/lab`，主包对它做动态 import —— 所以默认配置下
+lab 的代码（含 `@webav/av-recorder`）不会加载，但打包器仍会产出一个约 33 KB 的
+lab chunk。
+
+要在产物里**彻底删掉**它，在宿主的构建配置里把子入口指到空实现：
+
+```ts
+// vite.config.ts
+export default {
+  resolve: {
+    alias: [
+      {
+        find: /^@cut-workbench\/workbench\/lab$/,
+        replacement: '@cut-workbench/workbench/lab-disabled',
+      },
+    ],
+  },
+}
+```
+
+验证方式：
+
+```bash
+grep -c "FrameCounterClip" dist/assets/*.js   # 应为 0
+```
+
+> 为什么不是 `define: { __CUT_WORKBENCH_LAB__: 'false' }`：实测（Vite 8 /
+> Rolldown）动态 import 只要出现在模块图里，chunk 就会被写进 dist，即便所在
+> 分支已被折成死代码。只有把模块解析本身换掉才真正生效。
+
 ## 主题定制
 
 ```tsx

package/dist/CutWorkbench.d.ts

@@ -8,6 +8,7 @@
  * - 不强制能力阻断页（宿主可自行决定）。
  */
 import { type ReactNode } from 'react';
+import { type WorkbenchToolbarLabels } from './components/layout/WorkbenchToolbar';
 export interface CutWorkbenchSlots {
     /** 替换内置顶栏；传 `null` 表示不要顶栏 */
     topBar?: ReactNode | null;
@@ -16,8 +17,32 @@ export interface CutWorkbenchSlots {
     inspector?: ReactNode;
     timeline?: ReactNode;
 }
+/**
+ * 顶栏的局部自定义。
+ *
+ * 与 `slots.topBar` 的区别：`slots.topBar` 会替换**整条**顶栏（撤销、导出等
+ * 内置动作一并消失，宿主自己负责）；`toolbar` 只替换其中某一块，其余保留。
+ */
+export interface CutWorkbenchToolbarOptions {
+    /** 左侧品牌区；传 `null` 表示不要（默认就没有，避免在宿主产品里露出本库品牌） */
+    brand?: ReactNode | null;
+    /** 工程名区；传 `null` 表示不要 */
+    title?: ReactNode | null;
+    /** 工程名右侧状态（默认「空工程 · 16:9」）；传 `null` 表示不要 */
+    status?: ReactNode | null;
+    /** 在右侧按钮组末尾追加宿主动作 */
+    actions?: ReactNode;
+    /** 是否显示引擎能力徽标，默认 true */
+    showCapabilityBadge?: boolean;
+    /** 是否允许双击工程名重命名，默认 false */
+    editableTitle?: boolean;
+    /** 覆盖内置文案 */
+    labels?: WorkbenchToolbarLabels;
+}
 export interface CutWorkbenchProps {
     slots?: CutWorkbenchSlots;
+    /** 顶栏的局部自定义（`slots.topBar` 优先级更高） */
+    toolbar?: CutWorkbenchToolbarOptions;
     className?: string;
     /**
      * 工程持久化回调。
@@ -34,4 +59,4 @@ export interface CutWorkbenchProps {
  *
  * 必须在 `<WorkbenchProvider>` + `<CutEditorProvider>` 之内使用。
  */
-export declare function CutWorkbench({ slots, className, onSaveProject, onOpenProject, enforceCapability, }: CutWorkbenchProps): import("react").JSX.Element;
+export declare function CutWorkbench({ slots, toolbar: toolbarOptions, className, onSaveProject, onOpenProject, enforceCapability, }: CutWorkbenchProps): import("react").JSX.Element;

package/dist/auto.cjs

@@ -0,0 +1,4 @@
+// 由 build.mjs 生成：自带样式的入口，见 src/auto.ts
+// ⚠️ 同 auto.js：需在 package.json 的 "sideEffects" 白名单里，否则样式会被裁掉。
+require('./cut-workbench.css')
+module.exports = require('./index.cjs')

package/dist/auto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 自带样式的接入入口。
+ *
+ * 根入口（`@cut-workbench/workbench`）刻意**不带**样式：宿主若已有自己的构建
+ * 流程、需要控制 CSS 顺序（例如要压过某条全局重置），可以自己决定何时引入
+ * `@cut-workbench/workbench/style.css`。
+ *
+ * 这个入口把「引入样式 + 导出 API」合成一步：
+ *
+ * ```ts
+ * import { CutWorkbench, CutWorkbenchProvider } from '@cut-workbench/workbench/auto'
+ * ```
+ *
+ * ⚠️ 下面这行 import 是 Vite 产出 CSS 的唯一依据（`build.mjs` 会把产物写进
+ * `dist/cut-workbench.css`）。它会被 tsc 原样写进 `dist/auto.d.ts`，而 dist 下
+ * 没有 `styles/` 目录，接入方关掉 skipLibCheck 会报 TS2882 ——
+ * 由 `scripts/fix-dts-paths.mjs` 在构建后剥离。
+ */
+export * from './index';

package/dist/auto.js

@@ -0,0 +1,8 @@
+// 由 build.mjs 生成：自带样式的入口，见 src/auto.ts
+//
+// ⚠️ 本文件必须留在 package.json 的 "sideEffects" 白名单里。打包器会按
+// sideEffects 判定「整个模块可丢弃」，而 auto 的唯一副作用就是下面这行
+// CSS 导入 —— 一旦被判为无副作用，宿主 bundle 里不会报错、日志里没有痕迹，
+// 只是页面彻底没有样式（实测 Vite/Rolldown 行为）。
+import './cut-workbench.css'
+export * from './index.js'

package/dist/components/common/UnsupportedBrowser.d.ts

@@ -4,6 +4,11 @@ interface UnsupportedBrowserProps {
     loading: boolean;
     error?: string | null;
 }
-/** 不满足运行条件时的阻断页：逐项说明缺失能力，不做静默降级 */
+/**
+ * 不满足运行条件时的阻断页：逐项说明缺失能力，不做静默降级。
+ *
+ * 「依赖没装」与「浏览器不支持」要分开呈现 —— 前者是宿主的构建问题（可执行
+ * 安装命令解决），后者只能换浏览器。混在一起会让人对着一条装包报错去升浏览器。
+ */
 export declare function UnsupportedBrowser({ report, loading, error }: UnsupportedBrowserProps): import("react").JSX.Element;
 export {};

package/dist/components/layout/AppShell.d.ts

@@ -17,10 +17,24 @@ interface AppShellProps {
     className?: string;
 }
 /**
- * 三栏 + 底部时间轴骨架。
+ * 工作台骨架：顶栏 + 上半区（素材 / 预览 / 属性）+ 底部通栏时间轴。
  *
- * 布局用 inline style 的像素宽度做「受控」尺寸，配合 PanelResizer 的拖拽回写；
- * 这样不会因为 tailwind 的动态 class 被 purge 掉而失效。
+ * ```
+ * ┌───────────────────────────────────────────┐
+ * │ 顶栏                                      │
+ * ├──────────┬──────────────┬─────────────────┤
+ * │ 素材库   │ 预览         │ 属性            │  上半区
+ * ├──────────┴──────────────┴─────────────────┤
+ * │ 时间轴（横跨整行）                        │  下栏
+ * └───────────────────────────────────────────┘
+ * ```
+ *
+ * 时间轴必须是**通栏**的：它曾被塞进中间列，于是左右面板一拉宽就把时间轴
+ * 挤窄，工具条上的按钮直接溢出到属性面板上（实测右栏拉宽时溢出 203px）。
+ * 与此同时，几乎所有 NLE 都是「轨道占满底部一条」，通栏也更符合预期。
+ *
+ * 尺寸一律用 inline style 的像素值（受控），配合 PanelResizer 的拖拽回写；
+ * 不用 tailwind 动态 class，避免被 purge 掉导致尺寸失效。
  */
 export declare function AppShell({ topBar, left, center, right, timeline, leftWidth, rightWidth, timelineHeight, leftResizer, rightResizer, timelineResizer, className, }: AppShellProps): import("react").JSX.Element;
 export {};

package/dist/components/layout/WorkbenchToolbar.d.ts

@@ -5,9 +5,30 @@
  * - 品牌区可替换（`brand`），不强制显示项目名；
  * - 保存/打开是可选回调，宿主不提供就不渲染按钮；
  * - 「视图切换（编辑器/实验室）」只在开启 lab 特性时显示。
+ *
+ * 可自定义的层次（由浅到深）：
+ * 1. **文案**：`labels` 覆盖工程名占位、能力徽标等；
+ * 2. **局部**：`brand` / `title` / `status` / `actions` / `showCapabilityBadge`
+ *    逐块替换；
+ * 3. **整条**：`slots.topBar`（传 `null` 表示完全不要顶栏）。
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { CapabilityInfo } from './use-capability-info';
+/** 可覆盖的文案；缺省用内置中文 */
+export interface WorkbenchToolbarLabels {
+    /** 空工程的占位名（工程名称为空时显示） */
+    untitledProject?: string;
+    /** 「空工程」/「N 个片段」里的占位 */
+    emptyProject?: string;
+    export?: string;
+    canvasSettings?: string;
+    showLab?: string;
+    backToEditor?: string;
+    save?: string;
+    open?: string;
+    undo?: string;
+    redo?: string;
+}
 export interface WorkbenchToolbarProps {
     capability: CapabilityInfo;
     onExport: () => void;
@@ -17,8 +38,24 @@ export interface WorkbenchToolbarProps {
     onOpenProject?: () => void;
     /** 替换左侧品牌区；传 null 表示不要 */
     brand?: ReactNode | null;
+    /**
+     * 替换「工程名」区；传 null 表示不要。
+     *
+     * 不传时用内置的只读展示（工程名 + 未保存圆点）。
+     */
+    title?: ReactNode | null;
+    /** 替换工程名右侧的状态文案区（默认「空工程 · 16:9」）；传 null 表示不要 */
+    status?: ReactNode | null;
+    /** 在右侧按钮组**末尾**追加宿主自己的动作 */
+    actions?: ReactNode;
+    /** 是否显示引擎能力徽标，默认 true */
+    showCapabilityBadge?: boolean;
+    /** 是否允许双击工程名重命名，默认 false（宿主可能用自己的工程体系） */
+    editableTitle?: boolean;
     /** 是否显示「实验室」入口 */
     showLab?: boolean;
+    /** 覆盖内置文案 */
+    labels?: WorkbenchToolbarLabels;
 }
 /** 顶栏：品牌 / 工程名 / 撤销重做 / 保存 / 导出 / 能力徽标 / 视图切换 */
-export declare function WorkbenchToolbar({ capability, onExport, onSaveProject, onOpenProject, brand, showLab, }: WorkbenchToolbarProps): import("react").JSX.Element;
+export declare function WorkbenchToolbar({ capability, onExport, onSaveProject, onOpenProject, brand, title, status, actions, showCapabilityBadge, showLab, editableTitle, labels, }: WorkbenchToolbarProps): import("react").JSX.Element;

package/dist/cut-workbench.css

@@ -112,7 +112,6 @@
   --font-weight-normal: 400;
   --font-weight-medium: 500;
   --font-weight-semibold: 600;
-  --tracking-tight: -.025em;
   --tracking-wide: .025em;
   --tracking-widest: .1em;
   --leading-tight: 1.25;
@@ -132,6 +131,10 @@
   container: card-header / inline-size;
 }
 
+.cw-root .\@container {
+  container-type: inline-size;
+}
+
 .cw-root .pointer-events-auto {
   pointer-events: auto;
 }
@@ -636,6 +639,10 @@
   min-height: calc(var(--spacing) * 16);
 }
 
+.cw-root .min-h-\[220px\] {
+  min-height: 220px;
+}
+
 .cw-root .min-h-screen {
   min-height: 100vh;
 }
@@ -676,6 +683,10 @@
   width: calc(var(--spacing) * 44);
 }
 
+.cw-root .w-48 {
+  width: calc(var(--spacing) * 48);
+}
+
 .cw-root .w-72 {
   width: calc(var(--spacing) * 72);
 }
@@ -853,6 +864,10 @@
   cursor: row-resize;
 }
 
+.cw-root .cursor-text {
+  cursor: text;
+}
+
 .cw-root .touch-none {
   touch-action: none;
 }
@@ -1051,6 +1066,10 @@
   overflow-y: auto;
 }
 
+.cw-root .overflow-y-hidden {
+  overflow-y: hidden;
+}
+
 .cw-root .rounded {
   border-radius: .25rem;
 }
@@ -1185,6 +1204,16 @@
   border-color: currentColor;
 }
 
+.cw-root .border-destructive\/40 {
+  border-color: var(--cw-destructive);
+}
+
+@supports (color: color-mix(in lab, red, red)) {
+  .cw-root .border-destructive\/40 {
+    border-color: color-mix(in oklab, var(--cw-destructive) 40%, transparent);
+  }
+}
+
 .cw-root .border-destructive\/50 {
   border-color: var(--cw-destructive);
 }
@@ -1895,11 +1924,6 @@
   font-weight: var(--font-weight-semibold);
 }
 
-.cw-root .tracking-tight {
-  --tw-tracking: var(--tracking-tight);
-  letter-spacing: var(--tracking-tight);
-}
-
 .cw-root .tracking-wide {
   --tw-tracking: var(--tracking-wide);
   letter-spacing: var(--tracking-wide);
@@ -2566,6 +2590,11 @@
   color: var(--cw-accent-foreground);
 }
 
+.cw-root .focus\:ring-1:focus {
+  --tw-ring-shadow: var(--tw-ring-inset, ) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color, currentcolor);
+  box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
+}
+
 .cw-root .focus\:ring-2:focus {
   --tw-ring-shadow: var(--tw-ring-inset, ) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color, currentcolor);
   box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
@@ -3044,6 +3073,12 @@
   border-radius: 0;
 }
 
+@media not all and (min-width: 560px) {
+  .cw-root .max-\[560px\]\:hidden {
+    display: none;
+  }
+}
+
 @media (min-width: 40rem) {
   .cw-root .sm\:inline {
     display: inline;
@@ -3119,6 +3154,12 @@
   }
 }
 
+@container (min-width: 720px) {
+  .cw-root .\@\[720px\]\:flex {
+    display: flex;
+  }
+}
+
 .dark\:border-input:where([data-cw-theme="dark"], .cw-root[data-cw-theme="dark"] *) {
   border-color: var(--cw-input);
 }

package/dist/features/lab/index.d.ts

@@ -1,4 +1,8 @@
 /**
- * Lab feature 的公开 API。
+ * Lab feature 的公开 API（内部模块，不对宿主暴露）。
+ *
+ * 对外入口是 `@cut-workbench/workbench/lab`（见 src/lab.ts）；这里只做转发，
+ * 避免 `CutWorkbench` 直接触达 `components/LabPage`（那样会把 lab 及其
+ * `@webav/av-recorder` 拉回主包的模块图）。
  */
 export { LabPage } from './components/LabPage';