@ninkch/dsh-infinite-canvas 0.18.7 → 0.19.0

package/docs/guide.en.md

@@ -24,7 +24,7 @@ Two ways to drive it, best combined:
 1. Install the plugin (bundle folder) and **restart Harness once**. Open a workspace session — the **Infinite Canvas** entry appears; open the canvas panel.
 2. The right panel has four tabs: **Projects / Assets / Bible / Settings**.
 
-![Projects tab](./images/panel-projects-en.png)
+![Projects tab (ZH UI)](./images/panel-projects-zh.png)
 
 3. First time: finish the basics in the **Settings** tab (see section 5), then start from the chat.
 
@@ -52,7 +52,7 @@ You don't have to flip between the **Chat** and **Canvas** views: the canvas als
 
 **The agent**: creates the project → writes the world view, style baseline, characters (Chen Shi / Granny Lin), scenes (Night Post Office / Wrinkled Alley / City Street), props (Fire-Seal Letter / Brass Pocket Watch / Canvas Mailbag…) into the **bible**.
 
-![Bible tab](./images/panel-bible-en.png)
+![Bible modal (ZH UI)](./images/panel-bible-zh.png)
 
 **Why the bible matters**: it is the single source of truth for cross-shot, cross-episode consistency — every script, storyboard and video call automatically carries it; an `@Chen Shi` mention in a prompt automatically attaches that entity's description and reference assets, so **you never re-describe a character's looks**.
 
@@ -80,7 +80,7 @@ Each storyboard is broken into a shot list by AI: per shot — visual, motion &
 
 The canvas after the episode is expanded (left: script → per-scene texts → per-scene storyboards):
 
-![Canvas overview — episode expanded](./images/overview-en.png)
+![Canvas overview (EN UI)](./images/overview-en.png)
 
 ### 3.4 Generate reference images (characters / scenes / props)
 
@@ -92,7 +92,7 @@ The canvas after the episode is expanded (left: script → per-scene texts → p
 
 Generated assets land in the **Assets** tab, organized by category (Character / Scene / Prop / Script / Storyboard / Voice / Final cut):
 
-![Assets tab](./images/panel-assets-en.png)
+![Assets modal (EN UI)](./images/panel-assets-en.png)
 
 > 💡 Batch tip: ten reference images and six storyboards are exactly the kind of repetitive work the chat side is fastest at — one sentence does it all; you just review the images.
 
@@ -111,7 +111,7 @@ Generated assets land in the **Assets** tab, organized by category (Character /
 
 Scene 1's result: the video node with preview, bound references, and the tail-frame asset (the Assets panel gains "Ep1-Scene1 video" and "tail frame" cards):
 
-![Scene 1: storyboard + references → video](./images/video-node-refs.png)
+![Scene 1: storyboard + references → video](./images/scene1-zh.png)
 
 ### 3.6 Post-production with the Craft family
 
@@ -143,6 +143,10 @@ After the chat batch is done, the canvas is where you polish:
 
 **Recommended rhythm**: let chat finish the 80% batch → polish the 20% you care about on the canvas → have chat re-run the changed parts.
 
+Shortcuts and gestures:
+
+![Shortcuts and gestures (EN UI)](./images/shortcuts-en.png)
+
 ---
 
 ## 5. Model configuration: providers + models
@@ -152,11 +156,11 @@ Settings tab → Image models / Video models / TTS voices, organized in **two le
 1. **Provider** (collapsed row): configure the endpoint + API key **once** (+ optional extra params);
 2. **Models**: list several model IDs under it (same vendor, different tiers); **star ★ one as the default** — nodes without an explicit pick route there automatically.
 
-![Settings tab (data root / Craft / skills / text model / image models / video models / TTS)](./images/panel-settings-en.png)
+![Settings tab (data root / Craft / skill boost / text model / image models / video models / TTS) (EN UI)](./images/panel-settings-en.png)
 
 Expand a provider to edit its details (endpoint, key, output format, extra params, model list):
 
-![Provider detail](./images/provider-detail.png)
+
 
 Key points:
 
@@ -225,7 +229,75 @@ Media lives on disk, organized by project — **copying the folder IS the full m
 
 ---
 
-## 8. Troubleshooting
+## 8. 3D Director Stage
+
+A blocking & previz workspace inside the same project. Place real glTF characters and set dressing, frame them with real cameras, and send the result back to the canvas as an image or video node.
+
+Open it from the left icon rail → **3D Director Stage**.
+
+### 8.1 Workspace map
+
+| Area | What it does |
+|---|---|
+| **Left tool rail** | Select (0) / Move (1) / Rotate (2) / Scale (3) / Drop to ground (G) / Focus / Upload |
+| **Asset library** | Tabbed and searchable: characters · trees · furniture · buildings · primitives |
+| **Viewport** | Studio or final look, object labels, move/rotate/scale gizmo, shortcut overlay |
+| **Camera PiP** (top right) | Live view of the active camera; switch cameras from here |
+| **Right panel** | Context-sensitive: object properties when something is selected, lens/shot settings when nothing is selected, render settings in Live render |
+| **Timeline** (Dynamic previz / Live render) | Scrub, shot rail, per-shot start/end, keyframe tools, zoom |
+
+![Static previz — studio viewport, object properties and shortcut list](./images/director-static-en.png)
+
+### 8.2 Three viewing modes
+
+| Mode | Look | Playback |
+|---|---|---|
+| **Static previz** | Studio: dark backdrop, grid, neutral two-light rig | Paused — for blocking |
+| **Dynamic previz** | Same fixed studio look | Timeline playback |
+| **Live render** | Final look: daylight, shadows, materials, no guides | Plays the shot sequence |
+
+Static and Dynamic deliberately keep a **fixed studio look**, so placement does not drift when you tune the sun, ground or exposure. Those render settings apply only to **Live render** and the exported clip.
+
+![Dynamic previz — timeline, shot rail and camera keyframes](./images/director-dynamic-en.png)
+
+![Live render — daylight environment, real shadows and sun controls](./images/director-daylight-en.png)
+
+### 8.3 Asset library
+
+Five tabs share one search box. Click an asset to drop it into the scene; characters are real skinned glTF assets with animation clips (idle / walk / run / sneak).
+
+![Characters](./images/director-assets-characters-en.png)
+
+![Trees](./images/director-assets-trees-en.png)
+
+![Furniture](./images/director-assets-furniture-en.png)
+
+![Buildings](./images/director-assets-buildings-en.png)
+
+![Primitives, plus ancient-street set pieces](./images/director-assets-primitives-en.png)
+
+### 8.4 Moving things
+
+- **Gizmo**: axis shafts move, axis-end cubes scale, rings rotate. It follows the object's local axes.
+- **Alt + drag a scale handle** = uniform scale — x/y/z keep their relative proportions.
+- **Shift** while dragging = fine adjust; **Ctrl/⌘** = snap (0.5 m / 5°).
+- **Ctrl/⌘/Shift + left-drag** = box select; a plain click toggles a single object.
+- **W/A/S/D + Q/E** = fly the camera (forward/back, strafe, down/up). Hold **Shift** for 4x speed; the mouse still looks around.
+
+### 8.5 Shots, timeline and cameras
+
+- **Shot rail**: every shot has a start and end; edit them under the timeline.
+- **Camera keyframes**: select a camera, move it, then press **Add key**. Ease can be Smooth / Linear / Constant.
+- **Shot size and move**: presets that also drive the camera distance; **Framing %** shows how much of the subject fills the frame.
+- **Lens**: FOV, focal length and sensor size stay consistent; roll is in degrees.
+
+### 8.6 Export
+
+**Export video** renders the current range at 1280×720 with the same renderer as Live render, then drops the clip back on the canvas as a **video node**. The camera button exports a single **PNG** as an image node. Encoding follows the browser: MP4 (H.264) when available, WebM otherwise.
+
+---
+
+## 9. Troubleshooting
 
 | Symptom | Cause & fix |
 |---|---|
@@ -235,3 +307,7 @@ Media lives on disk, organized by project — **copying the folder IS the full m
 | Deleted nodes come back | Old sync race — upgrade to 0.17.11+ |
 | Storyboards always have exactly 6 shots | Old anchoring issue — since 0.17.11 shot counts follow the content beats |
 | Demo-mode images | No model configured, or the node has no pick and no starred default — see section 5 |
+
+Stuck? Open **Help & feedback** from the right panel to join the group or file an issue:
+
+![Help & feedback (EN UI)](./images/help-en.png)

package/docs/guide.zh-CN.md

@@ -24,7 +24,7 @@
 1. 安装插件（bundle 目录）后**重启一次 Harness**，进入工作区会话，侧边栏/工具栏出现**无限画布**入口。
 2. 点开画布面板，右侧是四个页签：**项目 / 资产 / 设定集 / 设置**。
 
-![项目页签](./images/panel-projects-zh.png)
+![项目下拉](./images/panel-projects-zh.png)
 
 3. 首次使用先到**设置**页签完成基础配置（见第 5 节），回到对话即可开工。
 
@@ -52,7 +52,7 @@
 
 **Agent 做的事**：创建项目 → 把世界观、风格基调、角色（陈拾/林婆婆）、场景（深夜邮局/褶皱巷/城市街头）、道具（火漆信/黄铜怀表/帆布邮包…）逐条写入**设定集**。
 
-![设定集页签](./images/panel-bible-zh.png)
+![设定集弹窗](./images/panel-bible-zh.png)
 
 **为什么设定集重要**：它是跨镜、跨集一致性的唯一事实源——之后每次剧本生成、分镜拆解、视频生成都自动注入设定集；提示词里 `@陈拾` 这样的引用会自动携带该实体的设定描述与参考图资产，**不需要在每个提示词里重复描述人物长相**。
 
@@ -80,11 +80,11 @@
 
 整集铺开后的画布（左侧：剧本 → 各场文本 → 各场分镜表的连线组）：
 
-![画布全览：剧本与铺开的场景组](./images/overview-zh.png)
+![画布全览](./images/overview-zh.png)
 
 场1 的连线细节（场1文本 → 场1分镜表 → 场1视频）：
 
-![场1 连线细节](./images/pipeline-zh.png)
+![场1 分镜与参考图](./images/scene1-zh.png)
 
 ### 3.4 生成资产图（角色/场景/道具参考图）
 
@@ -96,7 +96,7 @@
 
 生成完的资产进入右侧**资产页签**，按分类（角色/场景/道具/剧本/分镜表/配音/成片）归档：
 
-![资产页签](./images/panel-assets-zh.png)
+![资产弹窗](./images/panel-assets-zh.png)
 
 > 💡 批量提示：10 张参考图、6 个分镜表这类重复性批量工作是对话驱动的最大收益点——一句话全做完，你只检查画面细节。
 
@@ -115,7 +115,7 @@
 
 场1 的成品：视频节点带预览、参考图绑定、尾帧资产（右侧资产页同时出现「第一节-场1视频」与「尾帧」卡片）：
 
-![场1：分镜+参考图 → 视频](./images/scene1-zh.png)
+![场1：分镜 + 参考图 → 视频](./images/video-node-refs.png)
 
 ### 3.6 调用 Craft 家族做后期
 
@@ -147,6 +147,10 @@
 
 **推荐节奏**：对话干完 80% 批量活 → 画布上精修不满意的 20% → 再让对话批量重跑改过的部分。
 
+快捷键与操作：
+
+![快捷键与操作](./images/shortcuts-zh.png)
+
 ---
 
 ## 5. 模型配置：供应商 + 模型
@@ -156,11 +160,11 @@
 1. **供应商**（折叠行）：**一个供应商只配一次**接口地址 + API Key（+ 可选扩展参数）；
 2. **模型**：供应商下挂多个模型 ID（同厂不同等级），**点 ★ 星标 = 默认模型**——节点上没选模型时自动路由到这里。
 
-![设置页签（数据目录 / Craft / 技能 / 文本模型 / 图片模型 / 视频模型 / TTS）](./images/panel-settings-zh.png)
+![设置页签（数据目录 / Craft / 技能增强 / 文本模型 / 图片模型 / 视频模型 / TTS）](./images/panel-settings-zh.png)
 
 展开某个供应商即可编辑详情（地址、Key、输出格式、扩展参数、模型列表）：
 
-![供应商详情](./images/provider-detail.png)
+
 
 要点：
 
@@ -229,7 +233,75 @@
 
 ---
 
-## 8. 常见问题
+## 8. 3D 导演台
+
+同一项目里内置的摆位与预演工作台。把真实 glTF 角色与场景陈设摆进场景，用真实机位取景，再把结果作为图片或视频节点导回画布。
+
+入口：左侧图标列 → **3D 导演台**。
+
+### 8.1 界面分区
+
+| 区域 | 作用 |
+|---|---|
+| **左侧工具列** | 选择(0) / 移动(1) / 旋转(2) / 缩放(3) / 落地(G) / 聚焦 / 上传 |
+| **资产库** | 页签 + 搜索：人物 · 树木 · 家具 · 建筑 · 几何体 |
+| **视口** | 影棚或成片外观、对象名称标签、移动/旋转/缩放操作轴、快捷键浮层 |
+| **机位缩略图**（右上） | 当前机位的实时画面；也可在这里切换机位 |
+| **右侧面板** | 随上下文变化：选中对象时是对象属性；未选中时是镜头/机位设置；实时渲染下是渲染参数 |
+| **时间轴**（动态预演 / 实时渲染） | 拖动播放头、分镜轨、单镜起止、关键帧工具、缩放 |
+
+![静态预演——影棚视口、对象属性与快捷键列表](./images/director-static-zh.png)
+
+### 8.2 三种观看模式
+
+| 模式 | 画面 | 播放 |
+|---|---|---|
+| **静态预演** | 影棚：深色背景、网格、中性双灯 | 暂停，用于摆位 |
+| **动态预演** | 同样是固定影棚外观 | 时间轴播放 |
+| **实时渲染** | 成片外观：日光、阴影、材质，无辅助线 | 播放整段分镜 |
+
+静态/动态刻意保持**固定影棚外观**，这样你调太阳、地面、曝光时，摆位画面不会跟着漂移；这些渲染参数只影响**实时渲染**和导出的成片。
+
+![动态预演——时间轴、分镜轨与机位关键帧](./images/director-dynamic-zh.png)
+
+![实时渲染——日光环境、真实阴影与太阳参数](./images/director-live-render-zh.png)
+
+### 8.3 资产库
+
+五个页签共用一个搜索框。点一下资产即可放入场景；人物是真实的骨骼 glTF 资产，带待机/行走/奔跑/潜行等动画片段。
+
+![人物](./images/director-assets-characters-zh.png)
+
+![树木](./images/director-assets-trees-zh.png)
+
+![家具](./images/director-assets-furniture-zh.png)
+
+![建筑](./images/director-assets-buildings-zh.png)
+
+![几何体，含古街陈设](./images/director-assets-primitives-zh.png)
+
+### 8.4 移动与操作
+
+- **操作轴**：轴身拖动=移动，轴端方块=缩放，圆环=旋转；轴跟随物体的局部朝向。
+- **Alt + 拖轴端方块**：等比缩放，x/y/z 保持原有比例。
+- **拖动时按 Shift**：精调；按 **Ctrl/⌘**：吸附（0.5m / 5°）。
+- **Ctrl/⌘/Shift + 左键拖动**：框选；只点一下则是增删单个对象。
+- **W/A/S/D + Q/E**：键盘漫游（前进/后退、左右平移、下降/上升）；按住 **Shift** 加速 4 倍，鼠标仍负责转向。
+
+### 8.5 分镜、时间轴与机位
+
+- **分镜轨**：每个分镜有起止时间，可在时间轴下方直接改。
+- **机位关键帧**：选中机位 → 移动相机 → 点「添加关键帧」；缓动可选平滑 / 线性 / 恒定。
+- **景别与运镜**：预设会同时调整机位距离；「当前构图」显示主体占画面的百分比。
+- **镜头**：FOV、焦段、传感器尺寸三者联动一致；滚筒角以度为单位。
+
+### 8.6 导出
+
+**导出视频**用与实时渲染同一套渲染器，按当前区间输出 1280×720，再作为**视频节点**落回画布；相机按钮导出单帧 **PNG** 作为图片节点。编码取决于浏览器能力：支持时输出 MP4（H.264），否则 WebM。
+
+---
+
+## 9. 常见问题
 
 | 现象 | 原因与处理 |
 |---|---|
@@ -239,3 +311,7 @@
 | 删除的节点又出现 | 旧版本同步竞态，升级到 0.17.11+ |
 | 分镜只有固定 6 镜 | 旧版锚定问题，0.17.11 起镜头数按内容节拍自动决定 |
 | 演示模式出图 | 没配对应模型，或节点上没选且无星标默认——按第 5 节配置 |
+
+遇到问题？右侧面板的 **帮助与反馈** 可以扫码进群或到 GitHub 提 Issue：
+
+![帮助与反馈](./images/help-zh.png)