@uzooai/anime-ai-cli 0.6.0 → 0.6.2

package/.agents/skills/uzoo-anime-cli/references/commands.md

@@ -21,14 +21,14 @@
 | `model list` | 必填 `--space personal` 或 `--space team --team-uid UID`；可选 `--type image/video/text/audio`；以返回 `items[].label` 为模型名称，按目录能力选择参数 |
 | `canvas list` / `canvas get ID` | 列表必填 `--space personal` 或 `--space team --team-uid UID`，可带 `--project-id ID --cursor CURSOR --limit 1..100`；个人空间不能带团队/项目；生成使用已有或 CLI 创建的文档和节点 |
 | `canvas create` | 必填 `--name NAME` 及 `--space personal` 或 `--space team --team-uid UID`；团队可选 `--project-id ID`（映射 canvas_project_id）；返回完整画布及 id/version，不发起生成 |
-| `node add` | `--doc ID --type TYPE`；仅支持普通节点 text/image/video/audio、image_upload/video_upload/audio_upload、video-repaint；可选 `--node-id ID --input node-patch.json`；默认生成 UUID 节点 ID，返回 doc_id/node_id/version/node；派生节点由真实业务流程创建 |
+| `node add` | `--doc ID --type TYPE`；仅支持普通节点 text/image/video/audio、image_upload/video_upload/audio_upload、video-repaint；可选 `--node-id ID --input node-patch.json`；默认生成 UUID 节点 ID，未指定 `position` 时自动找空位，返回 doc_id/node_id/version/node；派生节点由真实业务流程创建 |
 | `node update` | `--doc ID --node-id ID --input node-patch.json`；只更新指定节点，不改 id/type，返回同上 |
 | `resource upload` | `--file FILE --doc ID --type image|video|audio --mime MIME`；普通素材节点加 `--node ID`，成功后补齐网页持久化引用，检查 canvas_bound；旧画布资产接口的图片加 `--asset-type character|scene|prop --name NAME`。返回 API 的资源引用，按实际返回字段使用 |
 | `resource bind` | `--doc ID --node ID --input upload-response.json`；复用真实上传响应，补齐普通素材节点的持久化媒体字段，不重新上传 |
 | `material folders/list/get ID` | 必填 `--space personal` 或 `--space team --team-uid UID`；list 可带 `--folder-id ID --keyword TEXT --limit 1..200 --offset N`，get 返回同空间素材 |
 | `material download ID` | 必填空间参数及--output FILE，可选--sha256 HEX；核对目录/素材归属，再请求素材专属download入口，匿名下载原格式完整url，返回output/bytes/sha256/asset_id/format/可选filename及无画布/生成/入库副作用标记。仅original，不支持自定义服务端名称或转换；拒绝不回退list/get的URL |
 | `material upload` | `--file FILE --mime MIME --folder-id ID --name NAME` 及空间参数；上传到独立素材空间，先核对实时限制和目标目录 |
-| `material use ID` | `--doc ID --node-id FIXED_ID` 及空间参数；可选 `--input position.json`；从库导入普通素材节点，复用真实引用，不重传 |
+| `material use ID` | `--doc ID --node-id FIXED_ID` 及空间参数；可选 `--input position.json`，未指定 `position` 时自动找空位；从库导入普通素材节点，复用真实引用，不重传 |
 | `material save` | `--input save.json --operation NAME` 默认只预检；加 --yes 直接保存原节点结果到素材库。输入 doc_id/node_id/space、团队 team_uid、folder_id，可选 name/description；限同空间已完成图片/视频真实任务；持久化原请求/幂等键，不写画布 |
 | `material save-get NAME` | 查询原入库 operation，已有 asset_id 时核验原素材，返回 state/task_id/folder_id/asset_id/asset/可选 last_failure；不发保存 POST |
 | `material save-recover NAME` | 默认只查询；未知结果且没有 asset_id 时，明确恢复才加 --yes 沿用原请求与幂等键。已知 asset_id 仅查询，rejected 不自动重提；账号/服务/来源改变停止 |

package/.agents/skills/uzoo-anime-cli/references/material-graph-workflow.md

@@ -16,7 +16,7 @@
 4. `canvas_bound=false` 表示文件已上传但兼容字段保存未确认。先读回节点；凭原始真实上传响应执行 `resource bind --doc DOC_ID --node NODE_ID --input upload-response.json` 仅修复原节点，不重传文件。响应须与画布/节点/媒体类型绑定，已有其他素材引用时停止。已打开网页可能持有旧快照；若出现节点或引用在后续快照反复消失，先暂停写入并协调关闭该画布页面，再核对是否为用户主动删除。用户允许恢复后才恢复缺失节点；优先复用原上传/原生成任务，不能通过重做生成弥补显示缺失。CAS 冲突不自动覆盖。
 5. 网页当前“素材库”使用独立素材空间 `/material-space`，不同于旧的 `/canvas/docs/.../assets`。使用 `material folders/list/get`，每次明确 `--space personal` 或 `--space team --team-uid UID`；分页为 limit/offset。目录来自实际列表，不猜文件夹 ID。团队没有素材时不能自动退回个人素材库。
 6. 素材库上传用 `material upload --file FILE --mime MIME --folder-id FOLDER_ID --name NAME --space team --team-uid UID`。CLI 校验同空间目录和实时上传限制，用通用直传会话上传再落素材空间。结果不明先查原目录/名称，不盲目重传；当前没有素材库分片恢复命令。
-7. 从库使用 `material use ASSET_ID --doc DOC_ID --node-id FIXED_ID --space team --team-uid UID`；可选 `--input position.json`（`{"position":{"x":120,"y":130}}`）。校验素材与画布同空间，从真实响应创建普通素材节点，复用 URL/file_ref，不重新上传。固定节点 ID 便于结果未知时读回核对。当前不支持跨空间导入、素材删除/迁移/收藏或文件夹编辑，不用临时 API 调用冒充已支持命令。
+7. 从库使用 `material use ASSET_ID --doc DOC_ID --node-id FIXED_ID --space team --team-uid UID`；默认在画布空位放置，可选 `--input position.json`（`{"position":{"x":120,"y":130}}`）指定位置。校验素材与画布同空间，从真实响应创建普通素材节点，复用 URL/file_ref，不重新上传。固定节点 ID 便于结果未知时读回核对。当前不支持跨空间导入、素材删除/迁移/收藏或文件夹编辑，不用临时 API 调用冒充已支持命令。
 
 ## 整理、分组和组合输出
 

package/.agents/skills/uzoo-anime-cli/references/node-workflow.md

@@ -36,19 +36,16 @@ CLI 业务命令直接通过 HTTP 调用后端，不加载网页或执行前端
 ## 执行顺序
 
 1. 复用有效登录，`canvas get DOC_ID` 核对 `team_uid` 与已确认空间一致，确认有写权限。记录当前版本、已有节点、边、视口和 meta；不要清空画布。
-2. 确定节点类型、标题及位置；用户只指定类型时可以用可读标题与互不重叠的位置。每个创建意图先记录固定 `--node-id` 与输入文件，再写入，便于断连后识别。
-3. UTF-8 保存 `node-patch.json`，例如：
+2. 确定节点类型和标题。用户未指定坐标时省略 `position`，由 CLI 根据最新快照避开已有节点和分组；指定坐标时原样使用。每个创建意图先记录固定 `--node-id` 与输入文件，再写入，便于断连后识别。
+3. 如需自定义字段，UTF-8 保存 `node-patch.json`，例如：
 
    ```json
    {
-     "position": {"x":120,"y":130},
-     "width":300,
-     "height":260,
      "data":{"title":"图片节点","prompt":""}
    }
    ```
 
-4. 执行一次 `uzoo-anime --profile PROFILE node add --doc DOC_ID --type image --node-id NODE_ID --input node-patch.json`。同画布按顺序创建，不并发写入完整快照。其他普通节点换成表中的 CLI 类型；不额外拼接内部组件字段或流程派生标记。
+4. 执行一次 `uzoo-anime --profile PROFILE node add --doc DOC_ID --type image --node-id NODE_ID --input node-patch.json`，没有自定义字段可省略 `--input`。同画布按顺序创建，不并发写入完整快照。其他普通节点换成表中的 CLI 类型；不额外拼接内部组件字段或流程派生标记。
 5. `canvas get DOC_ID` 读回，验证节点 ID、API type、扩展 role、中文标题、位置、数量与版本；同时核对已有节点/边/meta 未丢失、归属未变化。不要只以命令退出 0 判定网页兼容通过。
 6. 网页可用时打开同一画布并刷新，检查组件、标题及空状态。网页可能自动保存并增加版本，后续操作始终重新读取，保留网页补齐的数据。网页暂不可用时仅标记 API 保存/读取通过，网页待验证。
 

package/CHANGELOG.md

@@ -1,13 +1,21 @@
 # 更新记录
 
+## 0.6.2
+
+- 新建普通节点和从素材库导入时，未指定坐标会自动避开已有节点和分组。
+- 保留手动指定的坐标，不移动画布上的已有节点。
+
+## 0.6.1
+
+- 更新产品介绍、安装指南和项目主页链接。
+
 ## 0.6.0
 
-- 新增可选的 `install` 命令，支持交互多选和显式指定 Agent。全局 CLI 同版本可复用，Skill 从同版本包同步；不覆盖手动安装或修改过的 Skill。
-- 普通 npm 安装保持原行为。Windows 的 Codex 与 WorkBuddy 桌面版已验证 Skill 发现与 CLI 调用。
-- 随包 Skill 指导 Agent 在首次使用时查询新版；是否更新由用户决定，CLI 不自动更新。
-- npm 归档仅包含运行资源和公开使用说明。
+- 新增 CLI 与 Agent Skill 一键安装。
+- 支持选择多个 Agent、同步同版本 Skill，并保护手动修改的 Skill。
+- Agent 可提示可用更新，是否更新由用户决定。
 
 ## 0.5.0
 
-- 初始公开版本。支持浏览器 CLI 授权、画布与节点管理、素材、普通生成与恢复、下载、样片转正片，以及已接入的图片和视频工具。
-- 包含完整 Skill。该版本无 `install` 子命令，请按[安装与更新说明](docs/Agent接入与版本更新.md)手动接入 Agent。
+- 支持浏览器授权、画布、素材、普通生成与下载。
+- 随包提供完整 Agent Skill。

package/README.md

@@ -1,46 +1,50 @@
 # Uzoo Anime CLI
 
-通过终端或 Agent 操作 Uzoo 的画布、素材和生成任务。支持 Node.js 22 或更高版本。
+Uzoo 官方命令行工具与 Agent Skills。通过终端或 Agent 管理画布和创作素材，发起图片与视频生成，并查询和下载结果。
 
-## 安装 CLI 与 Skill
+[Uzoo 官网](https://uzooai.com/) · [npm 软件包](https://www.npmjs.com/package/@uzooai/anime-ai-cli)
+
+## 安装与更新
+
+需要 **Node.js 22 或更高版本**。
+
+**CLI + Agent Skill**
 
 ```sh
-npm install --global @uzooai/anime-ai-cli@latest
-uzoo-anime --version
-uzoo-anime --help
+npx @uzooai/anime-ai-cli@latest install
 ```
 
-**如果版本是 0.5.0：该版本没有 `install` 子命令。** 运行 `npx @uzooai/anime-ai-cli@latest install` 时出现“未知命令”，请使用上面的 npm 命令，再按 [Agent 接入与版本更新](docs/Agent接入与版本更新.md) 手动添加 Skill。重复下载同一个版本不会增加命令。
+按提示选择要接入的 Agent。支持选择 Codex、WorkBuddy 桌面版或 Claude Code，可一次选择多个。已有同版本 CLI 时，运行 `uzoo-anime install` 即可为其他 Agent 添加 Skill。
 
-从 0.6.0 起支持一键安装。在该版本进入 npm 的 `latest` 后，可运行：
+**仅安装 CLI**
 
 ```sh
-npx @uzooai/anime-ai-cli@latest install
+npm install --global @uzooai/anime-ai-cli@latest
 ```
 
-按提示选择一个或多个 Agent。已有同版本 CLI 的用户可以直接运行 `uzoo-anime install` 加装 Skill。
+该命令不会修改 Agent 的技能目录。若需要手动接入，运行 `uzoo-anime skill path` 找到随包 Skill，将完整目录导入对应 Agent。
 
-普通 npm 安装附带完整 Skill 文件，不会修改 Agent 的技能目录。用 `uzoo-anime skill path --format json` 找到目录后，将整个目录（含 `references`）复制到目标宿主。
+更新 CLI 和 Skill 可重跑一键安装命令，选择要同步的 Agent。更新由用户决定，CLI 不会自动安装新版。
 
-## 登录与使用
+## 快速开始
 
 ```sh
-uzoo-anime service status
+uzoo-anime --version
 uzoo-anime auth login
-uzoo-anime auth status
+uzoo-anime canvas list --space personal
 ```
 
-默认服务是 [Uzoo](https://uzooai.com)。浏览器登录和 CLI 授权由用户本人完成；不要把密码、验证码或令牌粘贴到 Agent。可用 `--profile NAME` 区分本地配置，已有有效登录可继续使用。
+在浏览器中登录 Uzoo 并授权 CLI 后即可使用。团队操作须选择对应团队。使用 Agent 时，可直接提出任务，例如：“列出我的个人画布，并帮我查看指定画布中的素材。”
 
-- [CLI 命令](.agents/skills/uzoo-anime-cli/references/commands.md)：画布和节点、素材、生成、查询与下载。
-- [支持的节点与工具](.agents/skills/uzoo-anime-cli/references/node-capabilities.md)：区分 CLI 能力和网页专属操作。
-- [生成与恢复](.agents/skills/uzoo-anime-cli/references/generation-workflow.md)：先确认素材、参数和实际报价；中断时查询并恢复原 operation。
-- [图片工具](.agents/skills/uzoo-anime-cli/references/image-tools-workflow.md)与[视频工具](.agents/skills/uzoo-anime-cli/references/video-tools-workflow.md)：按需检查 FFmpeg；CLI 不自动安装媒体工具。
+## 主要功能
 
-使用 CLI 写画布前，先确认对应网页标签已关闭且离开保存完成。付费任务在用户确认本次实际报价后提交。转绘旧命令仅用于有明确授权的原结果查询、下载或排障。
+- **画布与节点**：查询和管理画布、节点、分组及连线。新增普通节点或从素材库导入时，未指定坐标会自动找空位。
+- **素材管理**：上传、查询、导入和下载素材。
+- **图片与视频**：准备生成请求、查询任务和获取结果；支持样片转正片，以及裁剪、标注、抠图、剪辑和截帧等工具。
+- **任务恢复**：查询或继续原任务，保留已知任务和结果。
 
-## 更新
+付费任务会在提交前展示报价，由用户确认。运行 `uzoo-anime --help` 查看可用命令及参数。部分媒体工具需要本机 FFmpeg。
 
-CLI 不会后台检查或自动安装新版。使用随包 Skill 的 Agent 会在会话首次使用时尝试查询 npm 稳定版，有新版才提示，由你决定是否更新；查询失败不影响原任务。手动升级 CLI 后，也请同步手动接入的 Skill。见 [Agent 接入与版本更新](docs/Agent接入与版本更新.md)。
+## 许可证
 
-[更新记录](CHANGELOG.md) · [MIT 许可证](LICENSE)
+CLI 源码采用 [MIT 许可证](LICENSE)。Uzoo 在线服务适用相应服务条款。

package/docs/Agent/346/216/245/345/205/245/344/270/216/347/211/210/346/234/254/346/233/264/346/226/260.md

@@ -1,43 +1,41 @@
 # Agent 接入与版本更新
 
-## npm 0.5.0：先安装 CLI，再接入 Skill
+需要 Node.js 22 或更高版本。CLI 和完整 Skill 由同一个 npm 包分发。
 
-如果 `npx ... install` 返回“未知命令”，先运行 `uzoo-anime --version`（未安装时可用 `npx @uzooai/anime-ai-cli@latest --version`）。**0.5.0 没有一键安装入口。**
+## 一键安装
 
-```powershell
+```sh
+npx @uzooai/anime-ai-cli@latest install
+```
+
+安装器会列出检测到的本地 Agent，支持多选。也可明确指定：
+
+```sh
+npx @uzooai/anime-ai-cli@latest install --agent codex --agent workbuddy
+```
+
+可选名称为 `codex`、`workbuddy`（WorkBuddy 桌面版）和 `claude-code`。重复传入 `--agent` 可安装到多个宿主。自动化脚本须明确指定目标并传入 `--yes`；用 `--dry-run` 可先查看安装计划。已有同版本 CLI 时，运行 `uzoo-anime install` 即可添加 Agent Skill。
+
+## 只安装 CLI 或手动接入
+
+```sh
 npm install --global @uzooai/anime-ai-cli@latest
 uzoo-anime --version
 uzoo-anime skill path --format json
 ```
 
-将返回的 `directory` **整个复制**到宿主技能目录，保留 `SKILL.md` 和 `references/`。已有同名 Skill 先备份并比较自定义修改，备份不要留在技能扫描目录内。
+普通 npm 安装不修改 Agent 的技能目录。需要手动接入时，复制完整的 `directory`，保留 `SKILL.md` 与 `references/`：
 
-| 本地宿主 | 用户级目标目录 |
+| 宿主 | 用户级目标目录 |
 | --- | --- |
 | Codex | `~/.agents/skills/uzoo-anime-cli` |
 | WorkBuddy 桌面版 | `~/.workbuddy/skills/uzoo-anime-cli` |
 | Claude Code | `~/.claude/skills/uzoo-anime-cli` |
 
-只在当前项目使用 Codex 时，可放到该项目的 `.agents/skills/uzoo-anime-cli`。其他 Agent 按各自的技能导入方式接入。打开新会话，确认能找到 Skill 且能运行 `uzoo-anime --version`；找不到命令时检查宿主的 PATH 是否包含 npm 全局命令目录。
-
-## 含一键安装入口的版本
-
-仅在 `uzoo-anime install --help` 可用时使用本节。0.6.0 的安装入口已在 Windows 的 Codex、WorkBuddy 桌面版验证；Claude Code 可明确指定，尚未验收真实宿主。WorkBuddy AI 或远程 Claw 不在此范围。
-
-```sh
-uzoo-anime install
-uzoo-anime install --agent codex --agent workbuddy
-uzoo-anime install --agent workbuddy --dry-run
-```
-
-默认列出检测到的 Agent，允许多选，确认后才写入。脚本须明确传入至少一个 `--agent` 并使用 `--yes`。安装器复用同版本全局 CLI，只给选中的宿主同步 Skill。发现手动安装或改过的副本会停止，给出目录，供用户先备份或只选择其他宿主。安装器不会代登录、安装 Agent 或改 PATH。
-
-当包含该功能的版本成为 npm 的 `latest` 后，才可用 `npx @uzooai/anime-ai-cli@latest install` 首次一键接入或主动升级。为已有同版本 CLI 加装新 Agent，直接用本机 `uzoo-anime install` 即可。
+打开新的 Agent 会话，确认能发现 Skill 并运行 `uzoo-anime --version`。找不到命令时，检查宿主的 PATH 是否包含 npm 全局命令目录。登录 Uzoo 时运行 `uzoo-anime auth login`，并在浏览器中本人授权。
 
-## 主动更新
+## 更新与已有配置
 
-- 普通 npm 用户：运行 `npm install --global @uzooai/anime-ai-cli@latest`，核对版本，再从该版本更新已复制的 Skill。
-- 一键安装用户：通过含一键安装功能的新版入口更新 CLI，并选择所有要同步的 Agent。
-- 更新不要求重新登录；可继续使用原 profile 和 operation。不要因更新重提未知任务。
+要同时更新 CLI 和 Skill，重跑一键安装并选中要同步的 Agent。安装器不会覆盖手动安装或修改过的 Skill；先备份至技能扫描目录外，再按需要更新。只更新 CLI 可运行普通 npm 安装命令。
 
-CLI 不会后台查询或自动更新。使用随包 Skill 的 Agent 会在每个会话首次实际使用时尝试只读查询 npm 稳定版。若有新版，会展示本机和新版版本号，由你选择继续当前版或更新，以及是否同步所选 Agent 的 Skill。查不到版本不影响使用，进行中的操作先处理完再更新。版本号也可用 `uzoo-anime --version` 查看，已发布版本可用 `npm view @uzooai/anime-ai-cli version` 查询。
+Agent 首次使用时可查询 npm 稳定版；有新版时由用户决定是否更新。查询失败不影响正常使用。更新时保留原 profile 和任务记录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzooai/anime-ai-cli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "private": false,
   "type": "module",
   "engines": {
@@ -36,7 +36,8 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "description": "Uzoo Anime CLI for canvas, media references and authorized generation workflows",
+  "description": "Official Uzoo CLI and Agent Skills for canvases, media assets, and image and video generation.",
+  "homepage": "https://uzooai.com/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/UzooAI/uzooai-cli.git"

package/src/canvas.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto'
+import { findNodePosition } from './node-placement.js'
 import { segment } from './workflows.js'
 
 // Public CLI names map to the persisted API types and roles used by the web canvas.
@@ -10,7 +11,7 @@ function createNode(id, type) {
     apiType = 'video_repain_begain'
     data = { extra: { repaint: { role: 'entry', splitMode: 'intelligent' } } }
   }
-  return { id, type: apiType, position: { x: 120, y: 130 }, data }
+  return { id, type: apiType, data }
 }
 
 const object = v => v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -89,6 +90,7 @@ export async function writeNode(client, { docId, nodeId, type, patch = {}, updat
   if (!update && matches.length) throw new Error('节点 id 已存在；请读取节点确认，勿重复创建')
   const node = update ? patchNode(matches[0], patch) : candidate
   if (update && !isDerivedNode(matches[0]) && isDerivedNode(node)) throw new Error(derivedNodeMessage)
+  if (!update && node.position === undefined) node.position = findNodePosition(doc, node)
   const nodes = update ? doc.nodes.map(n => n.id === id ? node : n) : [...doc.nodes, node]
   const body = { version: doc.version, name: doc.name, viewport: doc.viewport, nodes, edges: doc.edges, meta: doc.meta }
   // Backend CAS protects concurrent website edits. Do not reload and overwrite on conflict.

package/src/materials.js

@@ -131,7 +131,7 @@ export async function materialUse(client, { space, teamUid, assetId, docId, node
     expectedSpace: space,
     expectedTeamUid: teamUid,
     patch: {
-      position: position || { x: 120, y: 130 },
+      position,
       data: {
         title: asset.name,
         url: asset.url,

package/src/node-placement.js

@@ -0,0 +1,78 @@
+const ORIGIN = { x: 120, y: 130 }
+const COLUMNS = 4
+const GAP_X = 80
+const GAP_Y = 64
+
+const positive = value => Number.isFinite(Number(value)) && Number(value) > 0 ? Number(value) : 0
+
+// Match the web snapshot's fallback sizes. data.width/height are media pixels, not canvas sizes.
+function fallbackSize({ type, data = {} }) {
+  if (type === 'text') return [300, 300]
+  if (type === 'audio' || type === 'audio_upload') return [266, 156]
+  if (type === 'video_repain_begain') return [590, 760]
+  if (data.extra?.repaint?.role === 'split-detail') return [480, 540]
+  if (!['image', 'image_upload', 'video', 'video_upload'].includes(type)) return [486, 300]
+
+  const asset = type.endsWith('_upload')
+  const ratioFields = asset
+    ? [data.node_output?.aspect_ratio, data.aspectRatio, data.aspect_ratio, data.extra?.aspect_ratio]
+    : [data.generation_config?.aspect_ratio, data.extra?.aspect_ratio, data.aspectRatio, data.aspect_ratio]
+  const ratioValue = [...ratioFields, data.result?.aspect_ratio].find(value => String(value ?? '').trim())
+  const ratioMatch = /^(\d+(?:\.\d+)?)[:：](\d+(?:\.\d+)?)$/.exec(String(ratioValue ?? '').trim())
+  const w = positive(ratioMatch?.[1])
+  const h = positive(ratioMatch?.[2])
+  const mediaWidth = positive(data.result?.width) || positive(data.width)
+  const mediaHeight = positive(data.result?.height) || positive(data.height)
+  const ratio = w && h ? positive(w / h) : asset && mediaHeight ? positive(mediaWidth / mediaHeight) : 0
+  if (!ratio && type === 'image_upload') return [266, 300]
+  const previewRatio = type === 'image'
+    ? Math.min(21 / 9, Math.max(9 / 16, ratio || 16 / 9))
+    : ratio || 16 / 9
+  // The browser sizes the preview from a 272px short side, plus its border and title.
+  return [
+    positive(Math.round(272 * Math.max(1, previewRatio)) + 2) || 486,
+    positive(Math.round(272 * Math.max(1, 1 / previewRatio)) + 28) || 300,
+  ]
+}
+
+function nodeSize(node) {
+  const [width, height] = fallbackSize({ ...node, data: node.data ?? {} })
+  return [
+    Math.max(positive(node.width) || positive(node.w), width),
+    Math.max(positive(node.height) || positive(node.h), height),
+  ]
+}
+
+export function findNodePosition(doc, node) {
+  const [width, height] = nodeSize(node)
+  const bounds = []
+  const add = (position, w, h) => {
+    if (!position || !w || !h) return
+    const x = Number(position.x) || 0
+    const y = Number(position.y) || 0
+    if (Number.isFinite(x) && Number.isFinite(y)) bounds.push({ x, y, right: x + w, bottom: y + h })
+  }
+  for (const existing of doc.nodes) add(existing.position, ...nodeSize(existing))
+  for (const group of Array.isArray(doc.meta.canvas_groups) ? doc.meta.canvas_groups : []) {
+    add(group?.position, positive(group?.size?.width), positive(group?.size?.height))
+  }
+  bounds.sort((a, b) => a.y - b.y)
+
+  // Find the highest free slot in each column. Skipping to a blocker’s bottom
+  // avoids scanning a pixel grid when the canvas already contains large nodes.
+  const stride = Math.ceil(Math.max(486, width)) + GAP_X
+  let best
+  for (let column = 0; column < COLUMNS; column++) {
+    const x = ORIGIN.x + column * stride
+    let y = ORIGIN.y
+    for (const box of bounds) {
+      if (box.y >= y + height + GAP_Y) break
+      if (box.x >= x + width + GAP_X || box.right + GAP_X <= x || box.bottom + GAP_Y <= y) continue
+      y = Math.ceil(box.bottom + GAP_Y)
+    }
+    if (Number.isFinite(x) && Number.isFinite(y) && (!best || y < best.y)) best = { x, y }
+    if (best?.y === ORIGIN.y) break
+  }
+  if (!best) throw new Error('无法计算新节点位置；请显式指定 position')
+  return best
+}