@petercjl/competitor-visual-canvas 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# Competitor visual canvas
 
-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.
+Application package for collecting Taobao/Tmall visual references into SealSeek Infinite Canvas. The application owns the collection workflow and layout. `@petercjl/tbcli` owns product collection; `@petercjl/sealseek-media-cli` owns service authentication and generic canvas operations.
+
+Requires Node.js 22+, `tbcli item media`, and SealSeek `canvas batch` (including text-batch) / `media inspect` capabilities. Service credentials stay with the dependency packages. The public npm package supports Codex, SealSeek and WorkBuddy adapters. macOS Codex business runs are verified; other host runtime evidence is separate from portable package tests.
+
+```sh
+competitor-visual-canvas doctor --json
+competitor-visual-canvas collect --input PRODUCT_ID --input OTHER_PRODUCT_ID --run NEW_DIR --json
+competitor-visual-canvas plan --run NEW_DIR --json
+competitor-visual-canvas canvas --run NEW_DIR --json
+competitor-visual-canvas canvas --run NEW_DIR --submit --json
+```
+
+Bare IDs default to Taobao. Each product has four Frames named after its shop. Main images and videos run horizontally; detail images run vertically with zero inter-image gap; SKU images form rows of five. Regions run left to right: main images, main videos, SKU, detail images. Between products, main-image/video/SKU Frames run vertically and detail Frames run horizontally. Each region has a text heading. Fixed column origins preserve existing positions during append. Empty video lists retain an empty Frame and explicit coverage evidence.
+
+The private run directory holds raw collection results, `assets.manifest.json`, `layout.plan.json`, `canvas.batch.json`, `canvas.state.json` and `collection-report.json`. Existing outputs are preserved. Replay reuses the recorded canvas and stable IDs. Unknown creation outcomes require checking existing canvases and explicit recovery; no automatic duplicate creation.
+
+Use `skill source/status/install/update --agent codex|sealseek --json` for the canonical bundled Skill and managed links. Unmanaged targets are preserved. Windows adapters remain unresolved. Source installs do not self-update. After future publication the explicit update path is `npm install -g @petercjl/competitor-visual-canvas@latest`, followed by `competitor-visual-canvas skill update --agent AGENT --json`; linked Skills follow the owning package. The host suite may manage that lifecycle after separate registration.
+
+Dependency entry points can be configured outside the package with `configure --tool tbcli|sealseek-media --entry ABSOLUTE_CLI_PATH --submit --json`. Inspect them with `doctor`, and delegate via `tool run TOOL ARGS...`; source discovery and execution use the same selected entry. No credentials are stored by the application.
+
+
+Append products using the newest completed run:
+
+```sh
+competitor-visual-canvas append --base-run BASE_DIR --run NEW_DIR --input NEW_PRODUCT_ID --json
+competitor-visual-canvas canvas --run NEW_DIR --json
+competitor-visual-canvas canvas --run NEW_DIR --submit --json
+```
+
+The new run records cumulative assets and uses the same canvas. Duplicate IDs are skipped. Old elements retain their positions; a stale base, manual changes or excessive column width stops before saving. Main-image/video/SKU columns reserve at least 2400/1600/1840 canvas units initially. Legacy vertical-region canvases require an explicitly requested `reflow --run DIR --submit`; normal append does not move existing elements.
+
+Find an existing application canvas by its exact name and append without a previous local run:
+
+```sh
+competitor-visual-canvas find --title "My canvas" --json
+competitor-visual-canvas append --title "My canvas" --run NEW_DIR --input NEW_PRODUCT_ID --json
+competitor-visual-canvas canvas --run NEW_DIR --json
+competitor-visual-canvas canvas --run NEW_DIR --submit --json
+```
+
+Name lookup scans all result pages and matches the full title. Multiple matches return `AMBIGUOUS_CANVAS` with candidates; select with `append --canvas ID`. A missing name returns `CANVAS_NOT_FOUND`. Lookup never creates a canvas. ID and title may be combined to verify the chosen name; `--base-run` is an alternative selector.
+
+Cloud recovery restores this application's four-region layout, product IDs and existing links from element source metadata, including empty Frames. Old coordinates stay intact and submission rechecks the saved snapshot. Incomplete or unrelated canvases return `CANVAS_STATE_UNSUPPORTED`. Recovery snapshots live in private application state, outside npm. Original product titles, SKU attributes and collection evidence unavailable in cloud metadata are marked unavailable; a completed local base run retains that richer evidence. The application controls these rules; the media CLI continues to provide generic canvas listing, reading and writing.
+
+Agent prompt: “用竞品视觉素材画板工具，找到画板‘我的竞品素材’，追加商品 ID：123456789012。”
+
+## Installation and updates
+
+Install `@petercjl/competitor-visual-canvas` globally, then use `competitor-visual-canvas skill install --agent codex|sealseek|workbuddy --json` for the current Agent. Its npm dependencies provide compatible tbcli and sealseek-media CLIs; service authorization remains separate. SealSeek resolves the active default workspace or a configured SEALSEEK_SKILLS_DIR; ambiguous roots require an explicit --path.
+
+Global installations check stable latest on business invocation once per day, download/install a newer version, refresh already managed Skills with backups and run the original command once. Local edits stop automatic synchronization. Offline checks keep the current version; interrupted updates retain package backups in private state. `update auto status|on|off` controls the policy, and `update install --yes` forces a check. Suite-local installations stay managed by taobao-ai-ops; Git development stays Git-owned. Custom Skill paths need explicit skill synchronization.
+
+Application run directories and credential profiles stay outside npm. Continue a canvas from its newest completed run; backup and unknown-write recovery use that existing canvas rather than creating another.

package/bin/competitor-visual-canvas.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {performUpdate,latestVersion,updateStatus,setAutomatic} from '../src/update.mjs';
+import {collect,planRun,publishCanvas,invoke,read,fail,configureTool,appendRun} from '../src/workflow.mjs';
+import {reflowRun} from '../src/reflow.mjs';
+import {findCanvases,appendToCanvas} from '../src/canvas-target.mjs';
+import {ROOT,META,skill} from '../src/lifecycle.mjs';
+const argv=process.argv.slice(2),command=argv.shift(),options={},args=[];
+function parse(){for(let i=0;i<argv.length;i++){const k=argv[i];if(k==='--json')continue;if(['--submit','--yes'].includes(k)){options[k.slice(2)]=true;continue;}if(k.startsWith('--')){const key=k.slice(2),value=argv[++i];if(!value||value.startsWith('--'))fail('INVALID_INPUT','Missing '+k);if(!['input','raw','run','title','agent','canvas','tool','entry','base-run','path'].includes(key))fail('INVALID_INPUT','Unknown '+k);(options[key]??=[]).push(value);}else args.push(k);}}
+const one=k=>options[k]?.at(-1);
+const help=`competitor-visual-canvas ${META.version}
+  collect --input ID_OR_URL [--input MORE] --run NEW_DIR [--raw SAVED_COLLECTION.json ...] --json
+  plan --run DIR [--title TEXT] [--base-run COMPLETED_DIR] --json
+  find --title EXACT_TITLE --json (read-only exact-name lookup)
+  append (--base-run COMPLETED_DIR | --title EXACT_TITLE | --canvas ID) --run NEW_DIR --input ID_OR_URL [--input MORE] [--raw FILE ...] --json
+  reflow --run DIR [--submit] --json (migrate a legacy canvas to horizontal regions)
+  canvas --run DIR [--submit] --json
+  recover --run DIR --canvas ID --submit --json (bind verified existing canvas after uncertain creation)
+  tool run tbcli|sealseek-media ARGS...
+  configure --tool tbcli|sealseek-media --entry CLI_PATH --submit --json
+  version | capabilities --json | doctor --json
+  skill source|status|install|update [--agent codex|sealseek|workbuddy] [--path DIR] --json
+  update check|install --yes --json
+  update auto status|on|off --json
+Requires tbcli item media and sealseek-media canvas batch/media inspect.
+Global npm installations check stable updates daily during use and synchronize managed Skills.
+Source development and suite-managed installations use their owner update path.`;
+async function main(){
+  if(!command||['--help','help'].includes(command))return {help};
+  if(command==='tool'&&argv[0]==='run'){const tool=argv[1];if(!['tbcli','sealseek-media'].includes(tool))fail('INVALID_INPUT','Unknown dependency.');return invoke(tool,argv.slice(2));}
+  parse();
+  if(command==='configure'){if(!options.submit)fail('SUBMIT_REQUIRED','Configuring dependency entry requires --submit.');return configureTool(one('tool'),one('entry'));}
+  if(command==='version')return {version:META.version};
+  if(command==='skill')return skill(args[0],one('agent'),one('path'));
+  if(command==='capabilities')return {...await read(path.join(ROOT,'skills','competitor-visual-canvas','capabilities.json')),execution:{frame_grouping:'four-per-product',inputs:'Taobao IDs or Taobao/Tmall detail URLs',archive:'canvas',supported_platform:process.platform==='darwin'?'macos':'unverified'}};
+  if(command==='doctor'){const checks=[];for(const tool of ['tbcli','sealseek-media'])try{const source=await invoke(tool,['skill','source','--json']),capabilities=await invoke(tool,['capabilities','--json']);const s=source.source??source.data?.source;const valid=tool==='tbcli'?JSON.stringify(capabilities).includes('item media'):['frame-batch','text-batch','media-inspect','source-metadata'].every(f=>capabilities.manifest?.canvas_contract?.features?.includes(f));checks.push({tool,source:s,ok:!!s&&valid});}catch(e){checks.push({tool,ok:false,code:e.code??'CLI_UNAVAILABLE'});}return {ok:checks.every(c=>c.ok),checks,node:process.version,service_access:'not-checked'};}
+  if(command==='update'){
+    if(args[0]==='check'){const latest=await latestVersion();return {current:META.version,latest,updateAvailable:latest!==META.version};}
+    if(args[0]==='auto'){if(args[1]==='status')return updateStatus();if(['on','off'].includes(args[1]))return setAutomatic(args[1]==='on');}
+    if(args[0]==='install'){if(!options.yes)fail('AUTHORIZATION_REQUIRED','Use --yes for package update.');return performUpdate({automatic:false});}
+    fail('INVALID_INPUT','Use update check/install or auto status/on/off.');
+  }
+  if(command==='find')return findCanvases(one('title'));
+  const run=one('run');if(!run)fail('INVALID_INPUT','Provide --run DIR.');
+  if(command==='collect'){const result=await collect(path.resolve(run),options.input||[],options.raw||[]);return {run_id:result.run_id,run:path.resolve(run),products:result.products.map(p=>({id:p.id,title:p.title,counts:Object.fromEntries(Object.entries(p.assets).map(([k,v])=>[k,v.length]))}))};}
+  if(command==='plan')return planRun(path.resolve(run),{title:one('title'),baseRun:one('base-run')?path.resolve(one('base-run')):undefined});
+  if(command==='append'){
+    if(one('base-run')){if(one('title')||one('canvas'))fail('INVALID_INPUT','Use a base run or a canvas selector.');return appendRun(path.resolve(run),path.resolve(one('base-run')),options.input||[],options.raw||[]);}
+    return appendToCanvas(path.resolve(run),{title:one('title'),canvas:one('canvas')},options.input||[],options.raw||[]);
+  }
+  if(command==='reflow')return reflowRun(path.resolve(run),!!options.submit);
+  if(command==='canvas')return publishCanvas(path.resolve(run),!!options.submit);
+  if(command==='recover'){if(!one('canvas')||!options.submit)fail('SUBMIT_REQUIRED','Recovery requires --canvas ID --submit.');const {checkpoint}=await import('../src/workflow.mjs');const plan=await read(path.join(run,'layout.plan.json')),board=await invoke('sealseek-media',['canvas','get',one('canvas'),'--json']);if(board.title!==plan.title)fail('STATE_CONFLICT','Recovered canvas title differs.');await checkpoint(path.join(run,'canvas.state.json'),{run_id:plan.run_id,canvas_id:board.canvas_id,canvas_url:board.canvas_url,status:'recovered'});return {recovered:true,...board};}
+  fail('INVALID_INPUT','Unknown command.');
+}
+async function execute(){
+ if(!['update','version','skill','capabilities','doctor','tool','help','--help'].includes(command)){
+  const u=await performUpdate();if(!u.ok)process.stderr.write('Automatic update deferred: '+(u.error?.code||'UPDATE_FAILED')+'\n');if(u.updated){const r=spawnSync(process.execPath,[process.argv[1],...process.argv.slice(2)],{stdio:'inherit',env:{...process.env,COMPETITOR_CANVAS_AUTO_UPDATE:'0'}});process.exit(r.status??1);}
+ }
+ return main();
+}
+execute().then(value=>console.log(JSON.stringify(value,null,2))).catch(e=>{console.error(JSON.stringify({ok:false,code:e.code??'FAILED',message:e.message,...(e.details?{details:e.details}:{})}));process.exitCode=1;});

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@petercjl/competitor-visual-canvas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Collect product visual assets and organize them into SealSeek canvas regions",
+  "bin": {
+    "competitor-visual-canvas": "bin/competitor-visual-canvas.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/competitor-visual-canvas.mjs && node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petercjl/competitor-visual-canvas.git"
+  },
+  "homepage": "https://github.com/petercjl/competitor-visual-canvas#readme",
+  "dependencies": {
+    "@petercjl/tbcli": "^0.10.5",
+    "@petercjl/sealseek-media-cli": "^0.5.1"
+  }
+}

package/skills/competitor-visual-canvas/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: competitor-visual-canvas
+description: Collect Taobao or Tmall product main images, main videos, detail images and SKU images from IDs or links, then organize them into four regional Frames per product in SealSeek Infinite Canvas. Use for collecting competitor visual references into a canvas.
+---
+
+# 竞品视觉素材画板
+
+## 契约与边界
+
+输入：一个或多个商品 ID 或淘宝/天猫详情链接，可选画板名称。纯数字 ID 默认为淘宝，按输入顺序去重。输出：原始采集结果、可复用素材清单、排版计划、运行状态、核验报告和画板链接。
+
+应用负责素材组织、命名、Frame 分组、排版和业务验收；tbcli 负责商品媒体采集；sealseek-media-cli 负责认证、媒体元信息和画板写入。采用 direct 方法：业务规则来自用户确认，服务限制来自运行时能力契约。无需私有知识库。此流程导入已有素材，无需生图或生视频。
+
+每个商品建立四个 Frame，分别位于主图、主图视频、SKU、详情页四个大区；Frame 名称为商品所在店铺名称。四个大区从左到右依次为主图、主图视频、SKU、详情页，横向起点固定。前三个区域预留宽度，新增商品向下追加；最右侧详情页区向右追加。Frame 位置由实际尺寸和已保存区域边界确定，追加保持已有 Frame 和素材的坐标不变。单商品画板使用商品名称；多商品默认“首个商品名称 等N款”，用户指定名称优先。
+
+| 区域 | Frame 内部 | 同类 Frame 之间 |
+| --- | --- | --- |
+| 主图 | 原顺序横排 | 商品输入顺序上下排 |
+| 主图视频 | 原顺序横排 | 商品输入顺序上下排 |
+| SKU | 原顺序网格，每行最多5张 | 商品输入顺序上下排 |
+| 详情页 | 原顺序无间隙竖排，统一宽度、等比缩放 | 商品输入顺序左右排 |
+
+每个大区顶部写入独立文字标题：主图区、主图视频区、SKU区、详情页区。标题属于画板文字元素，追加商品时复用。详情页图片首尾相接，图片间距为0，保留 Frame 外边距。图片按真实宽高等比展示；长详情图保持完整。SKU 同一区域相同链接归并，属性和 SKU 对应关系保留。空视频列表仍保留对应 Frame，并在报告中注明；未读到视频列表标 unavailable，不视为没有视频。
+
+## 运行主线
+
+1. 解析当前平台，加载对应 `adapters/codex.json` 、`adapters/sealseek.json` 或 `adapters/workbuddy.json`。发现 `competitor-visual-canvas version` 和 `doctor --json`。doctor 成功只是本地依赖检查。依赖不满足时停止受影响节点。
+2. 解析精确依赖 Skill：分别执行 `competitor-visual-canvas tool run tbcli skill source --json` 和 `competitor-visual-canvas tool run sealseek-media skill source --json`，读取返回路径下完整当前 SKILL.md、当前主机适配与任务相关参考。通过同一 tool run 入口发现当前版本及 capabilities；要求 tbcli 支持 item media、SealSeek 支持 frame-batch、text-batch 和 media-inspect。认证和采集/写入安全规则遵循各自插件。依赖缺失返回 CAPABILITY_UNAVAILABLE，不能自行编写 API 替代。
+3. 选择新的运行目录，执行 `competitor-visual-canvas collect --input ID_OR_URL [--input MORE] --run NEW_DIR --json`。应用逐商品调用 tbcli，先保存 raw 与 assets.manifest.json。已有 item media 原始结果可用重复 `--raw FILE` 导入；身份必须匹配。每个成功商品立即落盘。
+4. 检查覆盖状态；登录、验证和访问异常按 tbcli 分支处理。采集错误不能据此继续请求下一个商品。返回主线第3步时使用新采集输出，保留既有结果。媒体缺失、unknown 和 absent 明确区分，部分交付须说明范围。
+5. 执行 `competitor-visual-canvas plan --run DIR [--title TEXT] --json`。通过 SealSeek 通用媒体检查取得真实尺寸，保存 layout.plan.json 与 canvas.batch.json。确定性检查元素顺序、Frame 边界和无重叠。元信息失败停止规划，不用猜测尺寸冒充验证。
+6. 执行 `competitor-visual-canvas canvas --run DIR --json` 预览数量与名称。在用户已授权收集到画板的范围内执行同命令加 `--submit`。首次创建一个画板；运行状态记录其 ID，恢复沿用该画板。新建和追加的 Frame 与媒体通过能力层 batch 保存，保存前保留服务内容备份。
+7. 读回校验每个 Frame 的名称/位置/尺寸、素材数量/归属/位置/链接。检查 collection-report.json 的商品覆盖和缺口。向用户交付可点击画板链接、素材分类数量及中间文件位置。实际浏览器未查看时仅称读回验证通过。
+
+依赖调用完成后分别返回采集节点3、规划节点5或写入节点6，最后回到第7步交付。依赖 Skill 的说明不复制到应用包，当前 CLI 改进通过运行时契约发现。
+
+## 向已有画板追加商品
+
+用户给出已有画板名称时，按完整名称精确查找：`competitor-visual-canvas find --title EXACT_TITLE --json`。唯一匹配时执行 `competitor-visual-canvas append --title EXACT_TITLE --run NEW_DIR --input ID_OR_URL [--input MORE] --json`，再按主线第6、7步预览、提交与核验。名称可包含空格与中文，作为完整参数传入。用户提供画板 ID 或链接时可使用 `append --canvas ID`。同名候选由用户选择，随后传 `--canvas ID`；也可同时传 `--title` 校验名称。CANVAS_NOT_FOUND 时报告未找到，不自动新建。
+
+名称或 ID 追加从服务端读取当前内容，恢复本应用四区域 Frame、商品来源、已有素材及布局边界；无需旧对话或本地运行目录。恢复快照保存在本应用私有状态目录，输出 recovered_base_run。恢复依据元素的来源元数据及稳定 Frame 标识，支持空视频 Frame；保留已有元素的坐标、链接、归属和区域标题尺寸。原始采集证据、商品完整标题、SKU 属性等未保存在云端的信息标为 unavailable，不凭空补全。该方式适用于本应用当前四区域结构；缺少元数据、Frame 不完整或混入无法识别元素时返回 CANVAS_STATE_UNSUPPORTED，保留画板，使用可用的完整运行目录或交由用户决定如何整理。恢复和选择均只读，canvas --submit 才写入画板。
+
+用户提出继续添加商品时，使用最新已完成运行目录 BASE，不新建画板。执行 `competitor-visual-canvas append --base-run BASE --run NEW_DIR --input ID_OR_URL [--input MORE] --json`，先采集并规划；预览 `canvas --run NEW_DIR --json`，再在用户授权范围内执行加 `--submit` 的同命令。可重复 `--raw FILE` 复用 item media 原始结果。
+
+追加计划和素材清单为累计结果，沿用原画板 ID、标题、区域横向起点及旧元素 ID/位置；新商品主图、视频、SKU Frame 分别从对应区域底部继续向下，详情页 Frame 从最右侧继续向右。重复商品 ID 跳过；全部已存在时返回 changed:false。后续追加以 NEW_DIR 为最新基准，保留 BASE 作为恢复点。
+
+默认主图/视频/SKU 区域宽度至少为2400/1600/1840画板单位，并以首批实际内容宽度扩展。既有区域的宽度固定；超宽新商品返回 REGION_CAPACITY_EXCEEDED。将限制交给用户或上层布局策略处理，不挪动旧内容，也不改变横排规则。扩展布局属于另一次明确调整。
+
+写入前读回基准画板，保留区域标题当前的文字尺寸与字号，吸收不超过1e-6画板单位的浮点差异；标题内容和起点、素材归属与链接、实质坐标变化仍严格校验。检测手动移动和过期运行。CANVAS_CHANGED 时停止，读取最新完成的运行或由用户决定如何调整。允许未知结果恢复为同一累计计划；禁止从过期基准直接覆盖。
+
+既有画板需要应用当前排版与标题时，先用 `competitor-visual-canvas reflow --run BASE --json` 预览迁移，再在用户明确要求调整布局时加 `--submit`。迁移通过插件通用 canvas place 执行，保持元素 ID、素材链接与归属，写前备份，读回后更新本地计划。普通追加保留既有坐标和区域标题。
+
+## 分支与恢复
+
+- 未知平台/短链接：通过 tbcli 支持的解析能力处理；缺失时报告 FEATURE_UNSUPPORTED，保留输入，返回第2步。
+- 素材 URL 失效：用 tbcli 重新采集受影响商品到新文件，再建立新的规划；保留旧清单及来源。不能以视频封面替代视频。
+- 规划失败：保留清单，修复元信息后返回第5步。已存在计划不覆盖，选择新的运行目录或保存可验证备份后开展授权修订。
+- 创建结果未知：状态为 creating 时禁止再次创建。先用插件 canvas list/get 核对既有画板；确认匹配后 `competitor-visual-canvas recover --run DIR --canvas ID --submit --json` 绑定，再回到第6步。
+- 保存结果未知：查询同一画板，复用同一批次和稳定 ID；再次执行 canvas 只恢复写入，不能新建另一个画板。ID 内容或布局冲突返回 IDEMPOTENCY_CONFLICT，交由应用决策。
+- 目标文件已存在：保留现有文件，选新路径。应用运行文件为私有数据，不随 npm 包发布。
+
+## 安装、维护与 QA
+
+通过本包 CLI `skill source/status/install/update --agent codex|sealseek|workbuddy --json` 管理当前 Skill，source 是唯一来源。安装不授予淘宝或 SealSeek 服务访问权限。全局 npm 安装在业务命令启动时每日检查 latest 并自动下载安装、同步已管理 Skill 后重新执行原命令；离线沿用当前版本，更新失败保留备份，已有运行状态与服务凭证保持在包外。套件内部安装由 taobao-ai-ops 统一更新，源码由 Git 管理。手动更新使用 update install --yes；检查或开关自动更新使用 update check 和 update auto status/on/off。依赖 CLI 优先使用显式配置，其次解析本 npm 包安装的依赖，最后从 PATH 发现；开发或托管环境可用 `configure --tool TOOL --entry ABSOLUTE_CLI_PATH --submit --json` 配置外部私有工具入口，所有依赖发现和执行使用同一路径。WorkBuddy 目标支持显式安装；维护本机其他 Agent 的安装需遵循用户授权。
+
+需要 Node.js22+、已安装的两个依赖 CLI、淘宝已登录浏览器和 SealSeek 已授权账户；视频元信息检查需要 ffprobe。平台支持以适配器证据为准。静态兼容不能代替真实 Agent 测试。
+
+验收：每商品四个 Frame，店铺命名正确，四类覆盖明确，主图/详情顺序正确，SKU每行最多5张，元素无重叠、均在所属 Frame 内；恢复不重复创建或导入，追加前后旧元素坐标逐项保持一致。收藏清单与画板来源可追溯。生成任务质量、创意策略及竞品商业判断不在本应用范围内。

package/skills/competitor-visual-canvas/adapters/codex.json

@@ -0,0 +1,62 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "codex",
+  "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
+    {
+      "capability_id": "product.media.collect",
+      "implementation": {
+        "type": "cli",
+        "command": "tbcli",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "four-media-categories",
+        "product-shop-identity",
+        "ordered-urls",
+        "coverage"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    },
+    {
+      "capability_id": "canvas.assets.write",
+      "implementation": {
+        "type": "cli",
+        "command": "sealseek-media",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "frame-batch",
+        "text-batch",
+        "explicit-placement",
+        "media-inspect",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    }
+  ],
+  "operating_systems": {
+    "macos": "implemented",
+    "windows": "unresolved"
+  }
+}

package/skills/competitor-visual-canvas/adapters/sealseek.json

@@ -0,0 +1,62 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "sealseek",
+  "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
+    {
+      "capability_id": "product.media.collect",
+      "implementation": {
+        "type": "cli",
+        "command": "tbcli",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "four-media-categories",
+        "product-shop-identity",
+        "ordered-urls",
+        "coverage"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    },
+    {
+      "capability_id": "canvas.assets.write",
+      "implementation": {
+        "type": "cli",
+        "command": "sealseek-media",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "frame-batch",
+        "text-batch",
+        "explicit-placement",
+        "media-inspect",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    }
+  ],
+  "operating_systems": {
+    "macos": "implemented",
+    "windows": "unresolved"
+  }
+}

package/skills/competitor-visual-canvas/adapters/workbuddy.json

@@ -0,0 +1,62 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "workbuddy",
+  "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
+    {
+      "capability_id": "product.media.collect",
+      "implementation": {
+        "type": "cli",
+        "command": "tbcli",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "four-media-categories",
+        "product-shop-identity",
+        "ordered-urls",
+        "coverage"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    },
+    {
+      "capability_id": "canvas.assets.write",
+      "implementation": {
+        "type": "cli",
+        "command": "sealseek-media",
+        "discovery": "PATH or configured TBCLI_ENTRY/SEALSEEK_MEDIA_ENTRY; skill source; capabilities"
+      },
+      "features": [
+        "frame-batch",
+        "text-batch",
+        "explicit-placement",
+        "media-inspect",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "CLI JSON; files and IDs are verified by application; errors stop the owning node."
+    }
+  ],
+  "operating_systems": {
+    "macos": "implemented",
+    "windows": "unresolved"
+  }
+}

package/skills/competitor-visual-canvas/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "竞品视觉素材画板"
+  short_description: "收集淘宝天猫商品主图、详情、SKU图和视频，按区域整理到无限画板"

package/skills/competitor-visual-canvas/capabilities.json

@@ -0,0 +1,81 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "skill": "competitor-visual-canvas",
+  "target_platforms": [
+    "codex",
+    "sealseek",
+    "workbuddy"
+  ],
+  "capabilities": [
+    {
+      "id": "canvas.product.append",
+      "purpose": "Resolve an exact canvas title or ID, recover application layout, and append products without moving existing assets",
+      "required": true,
+      "required_features": ["canvas-list", "canvas-get", "source-metadata"],
+      "input_fields": ["canvas_title_or_id_or_base_run", "product_ids", "new_run_directory"],
+      "output_fields": ["canvas_id", "recovered_base_run", "cumulative_plan"],
+      "errors": ["CANVAS_NOT_FOUND", "AMBIGUOUS_CANVAS", "CANVAS_STATE_UNSUPPORTED", "CANVAS_CHANGED"],
+      "side_effects": {
+        "reads": "authenticated canvas list and content",
+        "writes": "private recovery snapshot and new run files; canvas only on explicit submit",
+        "authorization": "user requested appending products to the selected canvas",
+        "external_mutation": true,
+        "may_cost_money": false
+      }
+    },
+    {
+      "id": "product.media.collect",
+      "purpose": "Read ordered product media and source evidence",
+      "required": true,
+      "required_features": [
+        "four-media-categories",
+        "product-shop-identity",
+        "ordered-urls",
+        "coverage"
+      ],
+      "input_fields": [
+        "product_id"
+      ],
+      "output_fields": [
+        "raw",
+        "manifest"
+      ],
+      "side_effects": {
+        "reads": "authenticated product pages",
+        "writes": "private local files",
+        "authorization": "user requested collection",
+        "external_mutation": false,
+        "may_cost_money": false
+      }
+    },
+    {
+      "id": "canvas.assets.write",
+      "purpose": "Place explicit Frames and existing media",
+      "required": true,
+      "required_features": [
+        "frame-batch",
+        "text-batch",
+        "explicit-placement",
+        "media-inspect",
+        "source-metadata"
+      ],
+      "input_fields": [
+        "canvas_id",
+        "frames",
+        "media"
+      ],
+      "output_fields": [
+        "canvas_url",
+        "readback"
+      ],
+      "side_effects": {
+        "writes": "new canvas and media elements",
+        "cost": "no media generation",
+        "authorization": "user requested canvas collection",
+        "external_mutation": true,
+        "may_cost_money": false
+      }
+    }
+  ]
+}

package/src/canvas-target.mjs

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {stateRoot} from './core.mjs';
+import {invoke,fail,uid,create,REGIONS,validateLayout,matchesBatch,appendRun} from './workflow.mjs';
+
+const labels=['主图区','主图视频区','SKU区','详情页区'];
+const geometry=e=>Object.fromEntries(['x','y','width','height'].map(k=>[k,e[k]]));
+const reject=message=>fail('CANVAS_STATE_UNSUPPORTED',message+' Use a completed --base-run when available. Existing canvas content was preserved.');
+
+// Discovery is read-only; service keyword search is fuzzy, application selection is exact.
+export async function findCanvases(title,call=invoke){
+  if(typeof title!=='string'||!title.trim())fail('INVALID_INPUT','Provide an exact canvas title.');
+  const found=new Map();let page=1;
+  for(;;){
+    const result=await call('sealseek-media',['canvas','list','--keyword',title,'--page',String(page),'--limit','100','--json']);
+    if(!Array.isArray(result.canvases))fail('OUTPUT_CONTRACT_FAILED','Invalid canvas list.');
+    for(const b of result.canvases)if(b.title===title)found.set(String(b.canvas_id),b);
+    const pages=Number(result.pages??1);
+    if(!Number.isInteger(pages)||pages<0||pages>10000)fail('OUTPUT_CONTRACT_FAILED','Invalid canvas pagination.');
+    if(page>=pages)break;page++;
+  }
+  return {title,count:found.size,canvases:[...found.values()]};
+}
+
+export async function selectCanvas({title,canvas},call=invoke){
+  let id=canvas;
+  if(title&&!canvas){
+    const result=await findCanvases(title,call);
+    if(!result.count)fail('CANVAS_NOT_FOUND','No canvas has this exact title.');
+    if(result.count>1)throw Object.assign(new Error('Multiple canvases have this title; select a canvas ID.'),{code:'AMBIGUOUS_CANVAS',details:result});
+    id=result.canvases[0].canvas_id;
+  }
+  if(!/^\d+$/.test(id||''))fail('INVALID_INPUT','Provide --title TEXT or --canvas ID.');
+  const board=await call('sealseek-media',['canvas','get',String(id),'--json']);
+  if(String(board.canvas_id)!==String(id))fail('OUTPUT_CONTRACT_FAILED','Canvas identity mismatch.');
+  if(title&&board.title!==title)fail('CANVAS_CHANGED','Selected canvas title differs.');
+  return board;
+}
+
+// The application reconstructs only its own four-region contract. No provider API is duplicated.
+// Frame hashes bind even empty video Frames to their product, category and collection run.
+export function restoreCanvas(board,run_id=crypto.randomUUID()){
+  if(!board.canvas_id||!Array.isArray(board.elements))reject('Canvas content is unavailable.');
+  const elements=board.elements.filter(e=>!e.isDeleted),images=elements.filter(e=>e.type==='image');
+  const texts=labels.map(text=>{const found=elements.filter(e=>e.type==='text'&&e.text===text&&typeof e.id==='string'&&e.id.startsWith('region-'));if(found.length!==1)reject('Four unique region headings are required.');const e=found[0];if(!['x','y','width','height','fontSize'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0||e.fontSize<8||e.fontSize>200)reject('Invalid heading geometry.');return {id:e.id,text,...geometry(e),fontSize:e.fontSize};});
+  if(texts.some((t,i)=>i&&t.x<=texts[i-1].x))reject('Unsupported region order.');
+  const products=new Map(),identities=new Map(),media=[],taskIds=new Set();
+  for(const e of images){
+    const s=e.customData?.sourceMetadata,task=e.customData?.cliTaskId;
+    if(!s||!REGIONS.includes(s.category)||!/^\d+$/.test(s.productId||'')||typeof s.assetId!=='string'||typeof task!=='string'||e.customData.cliOutputIndex!==0)reject('An image lacks application source metadata.');
+    const suffix='-'+s.assetId+'-'+s.category;
+    if(!task.endsWith(suffix))reject('Invalid application media identity.');
+    if(taskIds.has(task))reject('Duplicate application media identity.');taskIds.add(task);
+    const origin=task.slice(0,-suffix.length),key=origin+'|'+s.productId;
+    if(!origin)reject('Missing collection identity.');
+    if(!products.has(s.productId))products.set(s.productId,{id:s.productId,title:'商品 '+s.productId,url:s.sourceUrl,shop:{shopId:s.shopId,shopName:''},coverage:{recovered_from_canvas:true,original_collection:'unavailable'},assets:Object.fromEntries(REGIONS.map(c=>[c,[]]))});
+    identities.set(key,{origin,productId:s.productId});
+    const kind=s.category==='main_videos'?'video':'image',url=kind==='video'?e.customData.videoUrl:e.customData.fileUrl;
+    if(!url||(kind==='video'&&!e.customData.fileUrl)||!['x','y','width','height'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0)reject('Invalid media geometry or URL.');
+    media.push({id:task,kind,urls:[url],frameId:e.frameId,placement:{mode:'explicit',positions:[geometry(e)]},...(kind==='video'?{posterUrl:e.customData.fileUrl}:{}),sourceMetadata:structuredClone(s)});
+    products.get(s.productId).assets[s.category].push({asset_id:s.assetId,kind,url,width:e.width,height:e.height,recovered:true,source_index:0});
+  }
+  if(!products.size)reject('No recoverable products were found.');
+  const frames=[],members=new Map(REGIONS.map(c=>[c,[]])),frameKeys=new Set();
+  for(const e of elements.filter(e=>e.type==='frame')){
+    const candidates=[];
+    for(const v of identities.values())for(const category of REGIONS)if(e.id==='frame-'+uid([v.origin,v.productId,category]))candidates.push({...v,category});
+    if(candidates.length!==1)reject('A Frame cannot be bound to an application product.');
+    const identity=candidates[0],p=products.get(identity.productId);
+    const key=identity.productId+'|'+identity.category;
+    if(frameKeys.has(key)||typeof e.name!=='string'||!e.name.trim()||!['x','y','width','height'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0)reject('Duplicate Frame identity or invalid geometry.');
+    frameKeys.add(key);
+    if(p.shop.shopName&&p.shop.shopName!==e.name)reject('Product shop names differ across Frames.');
+    p.shop.shopName=e.name;
+    const frame={id:e.id,name:e.name,...geometry(e)};frames.push(frame);members.get(identity.category).push(frame);
+    for(const m of media.filter(m=>m.frameId===e.id))if(m.sourceMetadata.productId!==identity.productId||m.sourceMetadata.category!==identity.category)reject('Media source and Frame identity disagree.');
+  }
+  if(frames.length!==products.size*4||REGIONS.some(c=>members.get(c).length!==products.size)||media.some(m=>!frames.some(f=>f.id===m.frameId)))reject('Product Frames are incomplete.');
+  const known=new Set([...frames,...texts].map(e=>e.id));
+  if(elements.some(e=>!known.has(e.id)&&e.type!=='image'&&!(e.type==='rectangle'&&e.customData?.type==='frame-background'&&frames.some(f=>f.id===e.customData.ownerFrameId))))reject('The canvas contains unsupported elements.');
+  const regions=REGIONS.map((category,i)=>{
+    const list=members.get(category),horizontal=category==='detail_images',x=texts[i].x,y=Math.min(...list.map(f=>f.y));
+    list.sort((a,b)=>horizontal?a.x-b.x:a.y-b.y);
+    if(list.some(f=>horizontal?f.y!==y:f.x!==x)||list[0].x!==x)reject('Unsupported Frame alignment.');
+    const width=horizontal?Math.max(...list.map(f=>f.width)):texts[i+1].x-x-240;
+    if(list.some(f=>!horizontal&&f.width>width)||width<=0)reject('Unsupported region bounds.');
+    const bottom=Math.max(...list.map(f=>f.y+f.height)),right=Math.max(...list.map(f=>f.x+f.width));
+    return {category,x,y,width,axis:horizontal?'horizontal':'vertical',next_x:horizontal?right+96:x,next_y:horizontal?y:bottom+96,bottom,right,frame_ids:list.map(f=>f.id)};
+  });
+  const plan={schema_version:2,presentation_version:1,run_id,title:board.title,layout_options:{width:320,gap:32,padding:32,frameGap:96,regionGap:240},regions,batch:{frames,media,texts},recovered_from_canvas:String(board.canvas_id)};
+  validateLayout(plan);
+  if(!matchesBatch(board,plan.batch))reject('Recovered canvas does not match its source content.');
+  return {plan,manifest:{schema_version:1,run_id,captured_at:new Date().toISOString(),recovered_from_canvas:String(board.canvas_id),products:[...products.values()]}};
+}
+
+export async function appendToCanvas(run,selector,inputs,rawFiles=[],call=invoke){
+  const board=await selectCanvas(selector,call),{plan,manifest}=restoreCanvas(board);
+  const base=path.join(stateRoot(),'recovered-canvases',plan.run_id);
+  await create(path.join(base,'layout.plan.json'),plan);
+  await create(path.join(base,'canvas.batch.json'),plan.batch);
+  await create(path.join(base,'assets.manifest.json'),manifest);
+  await create(path.join(base,'canvas.state.json'),{run_id:plan.run_id,status:'completed',canvas_id:String(board.canvas_id),canvas_url:board.canvas_url});
+  return {...await appendRun(run,base,inputs,rawFiles),canvas_id:String(board.canvas_id),title:board.title,recovered_base_run:base};
+}

package/src/core.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const META = JSON.parse(await fs.readFile(path.join(ROOT, 'package.json'), 'utf8'));
+export class MediaError extends Error {
+  constructor(code, message, details = {}) { super(message); this.code = code; this.details = details; }
+}
+export function requireValue(condition, code, message, details) {
+  if (!condition) throw new MediaError(code, message, details);
+}
+export function stateRoot() { return path.resolve(process.env.COMPETITOR_CANVAS_STATE_DIR || path.join(os.homedir(), '.local', 'state', 'competitor-visual-canvas')); }
+export function hash(value) { return crypto.createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex'); }
+export async function exists(p) { try { return await fs.lstat(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
+export async function readJson(p) { return JSON.parse(await fs.readFile(p, 'utf8')); }
+export async function createJson(p, value) {
+  await fs.mkdir(path.dirname(p), { recursive: true, mode: 0o700 });
+  await fs.writeFile(p, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+}
+// Mutable state is package-owned and validated before each atomic replacement.
+export async function replaceJob(p, value, {rename=fs.rename} = {}) {
+  const current = await readJson(p);
+  requireValue(current.owner === META.name && current.id === value.id, 'UNMANAGED_STATE', 'State ownership mismatch.');
+  const tmp = `${p}.${crypto.randomUUID()}.tmp`;
+  await createJson(tmp, value);
+  // Windows readers and antivirus can briefly block an atomic replacement.
+  // Keep the old file and complete temporary file intact while retrying rename.
+  for(let attempt=0;;attempt++) {
+    try { await rename(tmp,p);break; }
+    catch(e) { if(!['EPERM','EBUSY','EACCES'].includes(e.code)||attempt>=7)throw e;await new Promise(r=>setTimeout(r,Math.min(20*2**attempt,200))); }
+  }
+}
+export function publicError(e) {
+  return { code: e.code && /^[A-Z_]+$/.test(e.code) ? e.code : 'PROVIDER_FAILURE', message: e instanceof MediaError ? e.message : 'Operation failed; inspect the structured error and saved run before retrying.', ...(e.details ? { details: e.details } : {}) };
+}

package/src/lifecycle.mjs

@@ -0,0 +1,9 @@
+export {ROOT,META} from './core.mjs';
+import {SOURCE,status,install} from './skills.mjs';
+import {META} from './core.mjs';
+export async function skill(action,agent='codex',custom){
+ if(action==='source')return {source:SOURCE,name:'competitor-visual-canvas',version:META.version};
+ if(action==='status'){const s=await status(agent,custom);return {...s,target:s.destination};}
+ if(['install','update'].includes(action)){const s=await install(agent,{path:custom});return {...s,target:s.destination};}
+ throw Object.assign(Error('Use skill source/status/install/update'),{code:'INVALID_INPUT'});
+}

package/src/reflow.mjs

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {read,layout,invoke,create,checkpoint,fail} from './workflow.mjs';
+export function backgroundPlacements(elements,frames){
+  const bounds=e=>Object.fromEntries(['x','y','width','height'].map(k=>[k,e[k]]));
+  return elements.filter(e=>!e.isDeleted&&e.customData?.type==='frame-background'&&e.customData.ownerFrameId===e.frameId).flatMap(e=>{
+    const frame=frames.find(f=>f.id===e.frameId);
+    return frame?[{id:e.id,...bounds(frame),expected:bounds(e)}]:[];
+  });
+}
+export async function reflowRun(run,submit=false){
+  const previous=await read(path.join(run,'layout.plan.json'));
+  if(previous.schema_version===2&&previous.presentation_version===1)return {changed:false,reason:'Current presentation already active.'};
+  const manifest=await read(path.join(run,'assets.manifest.json')),state=await read(path.join(run,'canvas.state.json'));
+  if(!state.canvas_id)fail('STATE_CONFLICT','No existing canvas for this run.');
+  const next=layout(manifest,{title:previous.title});
+  for(const r of next.regions){const old=previous.regions?.find(v=>v.category===r.category);if(old)r.frame_ids=r.frame_ids.map((id,i)=>{const oldId=old.frame_ids?.[i];if(oldId){next.batch.frames.find(f=>f.id===id).id=oldId;for(const m of next.batch.media)if(m.frameId===id)m.frameId=oldId;}return oldId||id;});}
+  for(const m of next.batch.media){const old=previous.batch.media.find(v=>v.sourceMetadata?.assetId===m.sourceMetadata.assetId&&v.sourceMetadata?.category===m.sourceMetadata.category&&v.sourceMetadata?.productId===m.sourceMetadata.productId);if(old)m.id=old.id;}
+  const oldBatch=await read(path.join(run,'canvas.batch.json'));
+  if(![previous.batch,next.batch].some(b=>JSON.stringify(b)===JSON.stringify(oldBatch)))fail('STATE_CONFLICT','Batch differs from the owned layout.');
+  const live=await invoke('sealseek-media',['canvas','get',state.canvas_id,'--json']);
+  const placements=[];
+  const bounds=e=>Object.fromEntries(['x','y','width','height'].map(k=>[k,e[k]]));
+  for(const f of next.batch.frames){const current=live.elements.find(e=>e.id===f.id&&!e.isDeleted);if(!current)fail('ELEMENT_NOT_FOUND','Frame missing during migration.');placements.push({id:current.id,...bounds(f),expected:bounds(current)});}
+  for(const m of next.batch.media){const current=live.elements.find(e=>e.customData?.cliTaskId===m.id&&!e.isDeleted);if(!current)fail('ELEMENT_NOT_FOUND','Media missing during migration.');placements.push({id:current.id,...m.placement.positions[0],expected:bounds(current)});}
+  placements.push(...backgroundPlacements(live.elements,next.batch.frames));
+  if(!submit)return {dry_run:true,canvas_id:state.canvas_id,frames:next.batch.frames.length,media:next.batch.media.length,regions:next.regions.map(r=>({category:r.category,x:r.x,axis:r.axis}))};
+  const file=path.join(run,'reflow-'+crypto.randomUUID()+'.json');await create(file,placements);
+  const saved=await invoke('sealseek-media',['canvas','place',state.canvas_id,'--file',file,'--submit','--json']);
+  const batchFile=path.join(run,'reflow-batch-'+crypto.randomUUID()+'.json');await create(batchFile,next.batch);
+  await invoke('sealseek-media',['canvas','batch',state.canvas_id,'--file',batchFile,'--submit','--json']);
+  const after=await invoke('sealseek-media',['canvas','get',state.canvas_id,'--json']);
+  if(!placements.every(p=>{const e=after.elements.find(e=>e.id===p.id);return e&&['x','y','width','height'].every(k=>e[k]===p[k]);}))fail('OUTPUT_CONTRACT_FAILED','Reflow readback mismatch.');
+  await checkpoint(path.join(run,'canvas.batch.json'),next.batch);
+  await checkpoint(path.join(run,'layout.plan.json'),next);
+  await checkpoint(path.join(run,'canvas.state.json'),{...state,status:'completed',layout_version:2,presentation_version:1});
+  return {saved:true,canvas_id:state.canvas_id,canvas_url:after.canvas_url,...saved};
+}

package/src/skills.mjs

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import {existsSync} from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { ROOT, META, exists, requireValue, hash, createJson, readJson, stateRoot } from './core.mjs';
+
+export const SOURCE = path.join(ROOT, 'skills', 'competitor-visual-canvas');
+const MARKER = '.competitor-visual-canvas-install.json';
+export function renderSkill(text, agent) { return text; }
+export function destination(agent, custom) {
+  const roots = { codex:'.codex', workbuddy:'.workbuddy', sealseek:'.sealseek' };
+  requireValue(agent in roots, 'UNKNOWN_TARGET', 'Supported agents: codex, workbuddy, sealseek.');
+  if(custom)return path.resolve(custom);
+  if(agent==='sealseek'){
+    const configured=process.env.SEALSEEK_SKILLS_DIR;
+    if(configured)return path.join(path.resolve(configured),'competitor-visual-canvas');
+    const home=process.env.SEALSEEK_HOME||path.join(os.homedir(),'.sealseek');
+    const candidates=[path.join(home,'workspaces','default','skills'),path.join(home,'workspace','skills')].filter(p=>existsSync(p));
+    if(candidates.length===1)return path.join(candidates[0],'competitor-visual-canvas');
+    requireValue(false,'TARGET_UNRESOLVED','Specify the active SealSeek Skill root with SEALSEEK_SKILLS_DIR or --path.');
+  }
+  return path.join(os.homedir(), roots[agent], 'skills','competitor-visual-canvas');
+}
+export async function hashes(dir) {
+  const result={};
+  async function walk(base='') {
+    for (const item of await fs.readdir(path.join(dir,base),{ withFileTypes:true })) {
+      if (item.name === MARKER) continue;
+      const rel=path.join(base,item.name);
+      requireValue(!item.isSymbolicLink(), 'UNMANAGED_TARGET', 'Nested symlinks are not managed Skill content.');
+      if (item.isDirectory()) await walk(rel); else result[rel]=hash(await fs.readFile(path.join(dir,rel)));
+    }
+  }
+  await walk();return result;
+}
+export async function status(agent, custom) {
+  const target=destination(agent,custom), stat=await exists(target), sourceHashes=await hashes(SOURCE);
+  sourceHashes['SKILL.md'] = hash(renderSkill(await fs.readFile(path.join(SOURCE,'SKILL.md'),'utf8'),agent));
+  if (!stat) return { ok:true, agent, destination:target, installed:false, managed:false, current:false };
+  if (stat.isSymbolicLink()) {
+    const actual=await fs.realpath(target).catch(()=>null);
+    return { ok:true, agent, destination:target, installed:true, managed:actual === await fs.realpath(SOURCE), current:actual === await fs.realpath(SOURCE), mode:'link' };
+  }
+  const manifest=await readJson(path.join(target,MARKER)).catch(()=>null);
+  const managed=manifest?.owner===META.name;
+  const actual=stat.isDirectory() ? await hashes(target) : {};
+  const edited=managed && (Object.entries(manifest.hashes).some(([name,digest])=> actual[name]!==digest && name !== path.join('agents','openai.yaml')) || Object.keys(actual).some(name=>!(name in manifest.hashes)));
+  return { ok:true,agent,destination:target,installed:true,managed,current:managed && !edited && manifest.version===META.version && manifest.source===SOURCE && Object.keys(actual).length===Object.keys(sourceHashes).length && Object.entries(sourceHashes).every(([name,digest])=> actual[name]===digest || name === path.join('agents','openai.yaml')), edited,mode:'copy',version:manifest?.version };
+}
+export async function install(agent, options = {}) {
+  const rename = options.rename || fs.rename;
+  const info=await status(agent,options.path), target=info.destination;
+  requireValue(!info.installed || info.managed, 'UNMANAGED_TARGET', 'Existing Skill is user-owned. Choose an unused --path.');
+  requireValue(!info.edited || options.force, 'LOCAL_EDITS', 'Managed Skill has local edits. Review them before --force; update will create a backup.');
+  if (info.current) return { ...info, state:'unchanged' };
+  await fs.mkdir(path.dirname(target), { recursive:true });
+  let backup;
+  if (info.installed) {
+    backup=path.join(stateRoot(),'skill-backups',`${agent}-${crypto.randomUUID()}`);
+    requireValue(!await exists(backup), 'TARGET_EXISTS', 'Backup target exists.');
+    await fs.mkdir(path.dirname(backup),{recursive:true,mode:0o700});
+    await fs.cp(target,backup,{ recursive:true,errorOnExist:true,force:false,dereference:true });
+    const originalHashes = await hashes(target), backupHashes = await hashes(backup);
+    requireValue(JSON.stringify(originalHashes) === JSON.stringify(backupHashes), 'BACKUP_VERIFICATION_FAILED', 'Backup hashes differ; update stopped.');
+  }
+  const staging=`${target}.staging-${crypto.randomUUID()}`;
+  await fs.cp(SOURCE,staging,{ recursive:true,errorOnExist:true,force:false });
+  const skillText = await fs.readFile(path.join(staging,'SKILL.md'),'utf8');
+  await fs.writeFile(path.join(staging,'SKILL.md'),renderSkill(skillText,agent));
+  if (backup && await exists(path.join(target,'agents','openai.yaml'))) {
+    const oldManifest=await readJson(path.join(target,MARKER));
+    const name=path.join('agents','openai.yaml');
+    if(hash(await fs.readFile(path.join(target,name)))!==oldManifest.hashes[name]) await fs.copyFile(path.join(target,name),path.join(staging,name));
+  }
+  const digest=await hashes(staging);
+  await createJson(path.join(staging,MARKER),{ owner:META.name,version:META.version,source:SOURCE,hashes:digest });
+  let retired;
+  try {
+    if (info.installed) { const candidate=`${target}.retired-${crypto.randomUUID()}`; await rename(target,candidate); retired=candidate; }
+    await rename(staging,target);
+  } catch (e) {
+    if (retired && !await exists(target)) await fs.rename(retired,target);
+    if (['EPERM','EBUSY','EACCES'].includes(e.code) && backup) {
+      // Recoverable in-place sync is restricted to known managed files.
+      for (const name of Object.keys(digest)) {
+        const q=path.join(target,name); await fs.mkdir(path.dirname(q),{ recursive:true }); await fs.copyFile(path.join(staging,name),q);
+      }
+      for (const name of Object.keys(await hashes(target))) if (!(name in digest)) await fs.unlink(path.join(target,name));
+      await fs.copyFile(path.join(staging,MARKER),path.join(target,MARKER));
+    } else throw e;
+  }
+  const actual=await hashes(target);
+  requireValue(Object.keys(actual).length===Object.keys(digest).length && Object.entries(digest).every(([name,h])=>actual[name]===h), 'INSTALL_VERIFICATION_FAILED', 'Installed Skill hashes differ; recover from the returned backup.', { backup });
+  if (await exists(staging)) await fs.rm(staging,{recursive:true});
+  if (retired && await exists(retired)) await fs.rm(retired,{recursive:true});
+  return { ...await status(agent,options.path), state:'installed', ...(backup ? { backup } : {}) };
+}

package/src/update.mjs

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { ROOT,META,stateRoot,exists,readJson,createJson,replaceJob,requireValue,publicError,hash } from './core.mjs';
+import { status } from './skills.mjs';
+
+const DAY=86400000;
+export function newer(candidate,current) {
+  if(!/^\d+\.\d+\.\d+$/.test(candidate)||!/^\d+\.\d+\.\d+$/.test(current))return false;
+  const a=candidate.split('.').map(Number),b=current.split('.').map(Number);
+  for(let i=0;i<3;i++){if(a[i]!==b[i])return a[i]>b[i];}return false;
+}
+export async function settings(dir=stateRoot()) {
+  const p=path.join(dir,'updates.json');
+  const value=await exists(p)?await readJson(p):{owner:META.name,id:'updates',enabled:true};
+  requireValue(value.owner===META.name&&value.id==='updates','UNMANAGED_STATE','Update settings ownership mismatch.');return value;
+}
+async function store(value,dir) {
+  const p=path.join(dir,'updates.json');
+  if(await exists(p))await replaceJob(p,value);else await createJson(p,value);
+}
+export async function setAutomatic(enabled) {
+  const dir=stateRoot(),value=await settings(dir),p=path.join(dir,'updates.json');
+  if(await exists(p))await createJson(path.join(dir,'update-backups',crypto.randomUUID()+'.json'),value);
+  value.enabled=enabled;await store(value,dir);return {ok:true,...await updateStatus()};
+}
+export async function updateStatus() {
+  const {owner,id,...value}=await settings();return {...value,channel:'latest',check_interval_hours:24,trigger:'CLI invocation',development_checkout:!!await exists(path.join(ROOT,'.git'))};
+}
+export async function latestVersion() {
+  const r=await fetch(`https://registry.npmjs.org/${encodeURIComponent(META.name)}/latest`,{signal:AbortSignal.timeout(3000)});
+  requireValue(r.ok,'REGISTRY_UNAVAILABLE','Stable npm registry metadata is unavailable.');
+  const v=await r.json();requireValue(v.name===META.name&&/^\d+\.\d+\.\d+$/.test(v.version),'INVALID_REGISTRY_METADATA','Expected this package and a stable semantic version.');return v.version;
+}
+export async function npmCli() {
+  const candidates=[process.env.npm_execpath,path.join(path.dirname(process.execPath),'node_modules','npm','bin','npm-cli.js'),... (process.env.PATH||'').split(path.delimiter).map(p=>path.join(p,process.platform==='win32'?'npm.cmd':'npm'))].filter(Boolean);
+  for(const candidate of candidates){
+    if(!await exists(candidate))continue;
+    const real=await fs.realpath(candidate);
+    const script=real.endsWith('npm-cli.js')?real:path.join(path.dirname(real),'node_modules','npm','bin','npm-cli.js');
+    if(await exists(script))return script;
+  }
+  requireValue(false,'NPM_UNAVAILABLE','A working npm installation is required for package updates.');
+}
+function run(script,args) {
+  const r=spawnSync(process.execPath,[script,...args],{encoding:'utf8',timeout:120000,windowsHide:true});
+  requireValue(r.status===0,'UPDATE_FAILED','npm update operation failed. Existing backups remain available.');return r.stdout.trim();
+}
+export async function globalInstallation(root=ROOT) {
+  const script=await npmCli(),global=run(script,['root','--global']);
+  const expected=path.join(global,...META.name.split('/'));
+  return (await fs.realpath(expected).catch(()=>null))===await fs.realpath(root);
+}
+export async function managedTargets() {
+  const targets=[];
+  for(const agent of ['codex','workbuddy','sealseek']) {
+    const info=await status(agent).catch(e=>{if(e.code==='TARGET_UNRESOLVED')return {managed:false};throw e;});
+    requireValue(!info.managed||!info.edited,'LOCAL_EDITS','A managed Skill has local edits; review it before updating.',{agent});
+    if(info.managed)targets.push(agent);
+  }return targets;
+}
+export async function activeWork(dir=stateRoot()) {
+  for(const folder of ['jobs','auth-sessions']) {
+    for(const file of await fs.readdir(path.join(dir,folder)).catch(()=>[])) {
+      if(!file.endsWith('.json'))continue;
+      const j=await readJson(path.join(dir,folder,file)).catch(()=>null);
+      if(j?.owner!==META.name||!['queued','running','generated','pending','verifying','starting'].includes(j.status))continue;
+      if(j.pid){try{process.kill(j.pid,0);return true;}catch(e){if(e.code!=='ESRCH')return true;}}
+      else if(Date.now()-Date.parse(j.created_at)<120000)return true;
+    }
+  }return false;
+}
+export async function installVersion(version,targets,{root=ROOT,dir=stateRoot(),npmScript=npmCli,execute=run,synchronize}={}) {
+  requireValue(/^\d+\.\d+\.\d+$/.test(version),'INVALID_INPUT','Expected a stable semantic version.');
+  const backup=path.join(dir,'package-backups',crypto.randomUUID());
+  requireValue(!await exists(backup),'TARGET_EXISTS','Package backup already exists.');
+  await fs.mkdir(path.dirname(backup),{recursive:true,mode:0o700});
+  await fs.cp(root,backup,{recursive:true,errorOnExist:true,force:false,dereference:true});
+  for(const file of ['package.json','bin/competitor-visual-canvas.mjs'])requireValue(hash(await fs.readFile(path.join(root,file)))===hash(await fs.readFile(path.join(backup,file))),'BACKUP_VERIFICATION_FAILED','Package backup verification failed.');
+  try {
+    await execute(await npmScript(),['install','--global',`${META.name}@${version}`,'--ignore-scripts','--no-audit','--no-fund']);
+    const installed=await readJson(path.join(root,'package.json'));
+    requireValue(installed.name===META.name&&installed.version===version,'UPDATE_VERIFICATION_FAILED','Installed package version mismatch.');
+    for(const agent of targets){
+      const r=synchronize?await synchronize(agent):spawnSync(process.execPath,[path.join(root,'bin','competitor-visual-canvas.mjs'),'skill','update','--agent',agent,'--json'],{encoding:'utf8',timeout:120000,env:{...process.env,COMPETITOR_CANVAS_AUTO_UPDATE:'0'},windowsHide:true});
+      requireValue(r.status===0,'SKILL_SYNC_FAILED','Package installed, but managed Skill synchronization failed.',{agent,backup});
+    }
+    return {version,backup,skills_synchronized:targets};
+  }catch(e){e.details={...e.details,backup};throw e;}
+}
+export async function performUpdate({automatic=true,dir=stateRoot(),root=ROOT,current=META.version,env=process.env,now=Date.now(),latest=latestVersion,isGlobal=globalInstallation,targets=managedTargets,busy=activeWork,install}={}) {
+  install ||= (version,selected)=>installVersion(version,selected,{root,dir});
+  if(await exists(path.join(root,'.git'))){requireValue(automatic,'DEVELOPMENT_CHECKOUT','Update a Git checkout through Git.');return {ok:true,skipped:'development_checkout'};}
+  const config=await settings(dir);
+  if(automatic&&(env.COMPETITOR_CANVAS_AUTO_UPDATE==='0'||!config.enabled))return {ok:true,skipped:'disabled'};
+  if(automatic&&now-(config.last_check||0)<DAY)return {ok:true,skipped:'not_due'};
+  const lock=path.join(dir,'update-lock.json'),id=crypto.randomUUID();
+  try{await createJson(lock,{owner:META.name,id,pid:process.pid});}
+  catch(e){if(e.code!=='EEXIST')throw e;const held=await readJson(lock);requireValue(held.owner===META.name,'UNMANAGED_STATE','Update lock ownership mismatch.');let alive=true;try{process.kill(held.pid,0);}catch(err){alive=err.code!=='ESRCH';}if(alive)return {ok:true,skipped:'update_in_progress'};await fs.unlink(lock);return performUpdate({automatic,dir,root,current,env,now,latest,isGlobal,targets,busy,install});}
+  try {
+    if(automatic&&!await isGlobal(root))return {ok:true,skipped:'package_manager_owned'};
+    requireValue(await isGlobal(root),'UNSUPPORTED_INSTALLATION','Automatic updates support global npm installations; use your package manager for other installations.');
+    if(await busy(dir))return {ok:true,skipped:'active_work'};
+    const selected=await targets();
+    config.last_check=now;await store(config,dir);
+    const version=await latest();config.latest=version;delete config.error;
+    if(!newer(version,current)){await store(config,dir);return {ok:true,current,latest:version,updated:false};}
+    const result=await install(version,selected);config.last_update=Date.now();config.installed=version;delete config.error;await store(config,dir);
+    return {ok:true,updated:true,...result};
+  }catch(e){
+    config.error=publicError(e);await store(config,dir);if(!automatic)throw e;return {ok:false,error:config.error};
+  }finally{const held=await readJson(lock).catch(()=>null);if(held?.id===id)await fs.unlink(lock);}
+}

package/src/workflow.mjs

@@ -0,0 +1,167 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import {spawn} from 'node:child_process';
+import {createRequire} from 'node:module';
+const dependencyRequire=createRequire(import.meta.url);
+function bundledEntry(tool){try{const name=tool==='tbcli'?'@petercjl/tbcli':'@petercjl/sealseek-media-cli';const file=dependencyRequire.resolve(name+'/package.json');const pkg=dependencyRequire(name+'/package.json');return path.join(path.dirname(file),pkg.bin[tool]);}catch{return null;}}
+
+export const fail=(code,message)=>{throw Object.assign(new Error(message),{code});};
+export const uid=x=>crypto.createHash('sha256').update(JSON.stringify(x)).digest('hex').slice(0,24);
+export const read=p=>fs.readFile(p,'utf8').then(JSON.parse);
+export async function exists(p){try{await fs.lstat(p);return true;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
+export async function create(p,v){if(await exists(p))fail('OUTPUT_EXISTS','Output exists: '+p);await fs.mkdir(path.dirname(p),{recursive:true});await fs.writeFile(p,JSON.stringify(v,null,2)+'\n',{flag:'wx',mode:0o600});}
+export async function checkpoint(p,v){if(await exists(p)){const old=await read(p);if(old.run_id!==v.run_id)fail('STATE_CONFLICT','Run state ownership mismatch.');const backup=p+'.'+crypto.randomUUID()+'.backup';await fs.copyFile(p,backup,fs.constants.COPYFILE_EXCL);if((await fs.stat(backup)).size!==(await fs.stat(p)).size)fail('BACKUP_FAILED','Backup failed.');await fs.writeFile(p,JSON.stringify(v,null,2)+'\n',{mode:0o600});}else await create(p,v);}
+export const TOOLS_FILE=path.join(os.homedir(),'.config','competitor-visual-canvas','tools.json');
+export async function configureTool(tool,entry){
+  if(!['tbcli','sealseek-media'].includes(tool))fail('INVALID_INPUT','Unknown dependency.');
+  if(!path.isAbsolute(entry)||!await exists(entry))fail('INVALID_INPUT','Entry must be an existing absolute CLI path.');
+  const old=await exists(TOOLS_FILE)?await read(TOOLS_FILE):{run_id:'competitor-visual-canvas-tools',owner:'@petercjl/competitor-visual-canvas',entries:{}};
+  if(old.owner!=='@petercjl/competitor-visual-canvas')fail('STATE_CONFLICT','User-owned tool configuration preserved.');
+  old.entries[tool]=entry;await checkpoint(TOOLS_FILE,old);return {configured:true,tool,entry,configuration:TOOLS_FILE};
+}
+export async function invoke(tool,args){
+  const cfg=await exists(TOOLS_FILE)?await read(TOOLS_FILE):null;
+  const entry=process.env[tool==='tbcli'?'TBCLI_ENTRY':'SEALSEEK_MEDIA_ENTRY']||cfg?.entries?.[tool]||bundledEntry(tool)||tool;
+  const node=/\.mjs$|\.js$/.test(entry),cmd=node?process.execPath:entry,argv=node?[entry,...args]:args;
+  return new Promise((resolve,reject)=>{const child=spawn(cmd,argv,{env:{...process.env,TBCLI_UPDATE_CHECK:'0',SEALSEEK_MEDIA_AUTO_UPDATE:'0'},stdio:['ignore','pipe','pipe']});let out='',err='';const timer=setTimeout(()=>child.kill(),180000);child.stdout.on('data',x=>out+=x);child.stderr.on('data',x=>err+=x);child.on('error',reject);child.on('close',code=>{clearTimeout(timer);if(code!==0)return reject(Object.assign(new Error(tool+' operation failed: '+(err||out).slice(-1200)),{code:'DEPENDENCY_FAILED'}));try{resolve(JSON.parse(out));}catch{reject(Object.assign(new Error(tool+' returned invalid JSON'),{code:'OUTPUT_CONTRACT_FAILED'}));}});});
+}
+export function normalizeInputs(inputs){
+  const seen=new Set(),result=[];
+  for(const input of inputs){let id,platform='taobao';if(/^\d{1,30}$/.test(input))id=input;else{let u;try{u=new URL(input);}catch{fail('INVALID_INPUT','Provide a product ID or Taobao/Tmall detail URL.');}if(!['item.taobao.com','detail.tmall.com','detail.tmall.hk'].includes(u.hostname))fail('FEATURE_UNSUPPORTED','Unsupported product URL; resolve share links with tbcli first.');id=u.searchParams.get('id');if(u.hostname!=='item.taobao.com')platform='tmall';}
+    if(!/^\d{1,30}$/.test(id||''))fail('INVALID_INPUT','Invalid product ID.');if(seen.has(id))continue;seen.add(id);result.push({id,platform,input,url:`https://${platform==='taobao'?'item.taobao.com/item.htm':'detail.tmall.com/item.htm'}?id=${id}`});
+  }if(!result.length)fail('INVALID_INPUT','Provide at least one product.');return result;
+}
+export function normalizeProduct(input,raw){
+  const d=raw.detail;if(raw.itemId!==input.id||d?.itemId!==input.id)fail('ITEM_ID_MISMATCH','Collection identity mismatch.');if(!d.title||!d.shop?.shopName)fail('OUTPUT_CONTRACT_FAILED','Product title and shop name are required.');
+  const make=(kind,values)=>{const seen=new Map();values.forEach((value,i)=>{const a=typeof value==='string'?{url:value}:value;if(!a?.url)return;const old=seen.get(a.url);if(old){if(a.skuOptions)old.skuOptions.push(...a.skuOptions);return;}seen.set(a.url,{...a,asset_id:uid([input.id,kind,a.url]),kind:kind==='main_videos'?'video':'image',source_index:i,...(a.skuOptions?{skuOptions:[...a.skuOptions]}:{})});});return [...seen.values()];};
+  return {...input,title:d.title,shop:d.shop,coverage:raw.coverage,assets:{
+    main_images:make('main_images',d.mainImages||[]),main_videos:make('main_videos',raw.mainVideos?.records||[]),
+    detail_images:make('detail_images',raw.description?.images||[]),
+    sku_images:make('sku_images',(d.properties||[]).flatMap(p=>p.values.filter(v=>v.imageUrl).map(v=>({url:v.imageUrl,skuOptions:[{pid:p.pid,property:p.name,vid:v.vid,name:v.name,skuIds:(d.skus||[]).filter(s=>s.options.some(o=>o.pid===p.pid&&o.vid===v.vid)).map(s=>s.skuId)}]}))))
+  }};
+}
+export async function collect(run,inputs,rawFiles=[]){
+  if(await exists(run))fail('OUTPUT_EXISTS','Choose a new run directory.');
+  const products=normalizeInputs(inputs),run_id=crypto.randomUUID();await fs.mkdir(run,{recursive:true,mode:0o700});await create(path.join(run,'inputs.json'),{run_id,products});
+  const manifest={schema_version:1,run_id,captured_at:new Date().toISOString(),products:[]};
+  for(const input of products){
+    let raw;if(rawFiles.length){for(const file of rawFiles){const r=await read(file);if(r.itemId===input.id){raw=r;break;}}if(!raw)fail('INPUT_MISSING','No raw collection for '+input.id);}else{const out=path.join(run,'raw',input.id+'.json');await fs.mkdir(path.dirname(out),{recursive:true});await invoke('tbcli',['item','media','--item-id',input.id,'--out',out,'--json']);raw=await read(out);}
+    if(rawFiles.length)await create(path.join(run,'raw',input.id+'.json'),raw);
+    manifest.products.push(normalizeProduct(input,raw));await checkpoint(path.join(run,'assets.manifest.json'),manifest);
+  }return manifest;
+}
+export const REGIONS=['main_images','main_videos','sku_images','detail_images'];
+export function layout(manifest,options={}){
+  const base=options.basePlan;
+  if(base&&(base.schema_version!==2||base.presentation_version!==1))fail('LAYOUT_MIGRATION_REQUIRED','Migrate the existing run with reflow before appending.');
+  const {width=320,gap=32,padding=32,frameGap=96,regionGap=240}=base?.layout_options||options;
+  if(![width,gap,padding,frameGap,regionGap].every(Number.isFinite)||width<=0||[gap,padding,frameGap,regionGap].some(x=>x<0))fail('INVALID_INPUT','Invalid layout dimensions.');
+  const local={};
+  for(const category of REGIONS){local[category]=[];
+    for(const product of manifest.products){
+      const id='frame-'+uid([manifest.run_id,product.id,category]),placements=[];let localX=padding,localY=padding,maxX=padding,maxY=padding,rowHeight=0;
+      for(const [i,a] of product.assets[category].entries()){
+        if(!(a.width>0&&a.height>0))fail('METADATA_REQUIRED','Missing real dimensions for '+a.asset_id);
+        const h=width*a.height/a.width;
+        if(category==='sku_images'&&i>0&&i%5===0){localX=padding;localY+=rowHeight+gap;rowHeight=0;}
+        placements.push({asset:a,x:localX,y:localY,width,height:h});maxX=Math.max(maxX,localX+width);maxY=Math.max(maxY,localY+h);rowHeight=Math.max(rowHeight,h);
+        if(category==='detail_images')localY+=h;else localX+=width+gap;
+      }
+      local[category].push({product,placements,frame:{id,name:product.shop.shopName,x:0,y:0,width:Math.max(width+padding*2,maxX+padding),height:Math.max(120,maxY+padding)}});
+    }
+  }
+  const frames=structuredClone(base?.batch.frames||[]),media=structuredClone(base?.batch.media||[]),regions=[];
+  const reserve={main_images:2400,main_videos:1600,sku_images:1840,...options.columnWidths};let regionX=0;
+  for(const category of REGIONS){
+    const previous=base?.regions.find(r=>r.category===category);
+    const horizontal=category==='detail_images';
+    const columnWidth=previous?.width??Math.max(reserve[category]||0,...local[category].map(v=>v.frame.width));
+    const x=previous?.x??regionX,y=previous?.y??80;
+    let fx=horizontal?(previous?.next_x??x):x,fy=horizontal?y:(previous?.next_y??y);
+    const frameIds=[...(previous?.frame_ids||[])];
+    for(const {product,placements,frame:f} of local[category]){
+      if(!horizontal&&f.width>columnWidth)fail('REGION_CAPACITY_EXCEEDED',category+' requires '+f.width+' units; reserved '+columnWidth+'. Existing elements were preserved.');
+      f.x=fx;f.y=fy;frames.push(f);frameIds.push(f.id);
+      for(const p of placements){const a=p.asset;media.push({id:manifest.run_id+'-'+a.asset_id+'-'+category,kind:a.kind,urls:[a.url],frameId:f.id,placement:{mode:'explicit',positions:[{x:fx+p.x,y:fy+p.y,width:p.width,height:p.height}]},...(a.posterUrl?{posterUrl:a.posterUrl}:{}),sourceMetadata:{sourceUrl:product.url,productId:product.id,shopId:String(product.shop.shopId||''),category,assetId:a.asset_id}});}
+      if(horizontal)fx+=f.width+frameGap;else fy+=f.height+frameGap;
+    }
+    const members=frames.filter(f=>frameIds.includes(f.id));
+    regions.push({category,x,y,width:columnWidth,axis:horizontal?'horizontal':'vertical',next_x:horizontal?fx:x,next_y:horizontal?y:fy,bottom:Math.max(y,...members.map(f=>f.y+f.height)),right:Math.max(x,...members.map(f=>f.x+f.width)),frame_ids:frameIds});
+    regionX=x+columnWidth+regionGap;
+  }
+  const name=base?.title||options.title||manifest.products[0].title+(manifest.products.length>1?` 等${manifest.products.length}款`:'');
+  if(name.length>200)fail('INVALID_INPUT','Canvas title exceeds 200 characters; provide --title.');
+  const labels={main_images:'主图区',main_videos:'主图视频区',sku_images:'SKU区',detail_images:'详情页区'};
+  const texts=base?.batch.texts?structuredClone(base.batch.texts):regions.map(r=>({id:'region-'+uid([manifest.run_id,r.category]),text:labels[r.category],x:r.x,y:r.y-72,width:320,height:40,fontSize:28}));
+  const result={schema_version:2,presentation_version:1,run_id:manifest.run_id,title:name,layout_options:{width,gap,padding,frameGap,regionGap},regions,batch:{frames,media,texts},...(base?{base_run_id:base.run_id}:{})};validateLayout(result);return result;
+}
+export function validateLayout(plan){
+  const overlap=(a,b)=>a.x<b.x+b.width-1e-6&&a.x+a.width>b.x+1e-6&&a.y<b.y+b.height-1e-6&&a.y+a.height>b.y+1e-6;
+  const {frames,media}=plan.batch;
+  for(let i=0;i<frames.length;i++)for(let j=i+1;j<frames.length;j++)if(overlap(frames[i],frames[j]))fail('LAYOUT_OVERLAP','Frames overlap.');
+  for(const f of frames){const items=media.filter(m=>m.frameId===f.id).map(m=>m.placement.positions[0]);for(const a of items)if(a.x<f.x||a.y<f.y||a.x+a.width>f.x+f.width+1e-6||a.y+a.height>f.y+f.height+1e-6)fail('LAYOUT_BOUNDS','Media outside frame.');for(let i=0;i<items.length;i++)for(let j=i+1;j<items.length;j++)if(overlap(items[i],items[j]))fail('LAYOUT_OVERLAP','Media overlaps.');}
+  return true;
+}
+export async function planRun(run,options={}){
+  for(const file of ['layout.plan.json','canvas.batch.json'])if(await exists(path.join(run,file)))fail('OUTPUT_EXISTS','Plan already exists; preserve it or use a new run.');
+  const manifest=await read(path.join(run,'assets.manifest.json'));let base,baseManifest,state;
+  if(options.baseRun){
+    base=await read(path.join(options.baseRun,'layout.plan.json'));baseManifest=await read(path.join(options.baseRun,'assets.manifest.json'));state=await read(path.join(options.baseRun,'canvas.state.json'));
+    if(base.schema_version!==2)fail('LAYOUT_MIGRATION_REQUIRED','Run reflow on the base canvas before append.');
+    if(state.status!=='completed'||!state.canvas_id)fail('STATE_CONFLICT','Base canvas must be completed.');
+    if(manifest.products.some(p=>baseManifest.products.some(old=>old.id===p.id)))fail('PRODUCT_ALREADY_PRESENT','A product is already in this canvas; existing materials are preserved.');
+  }
+  const cache=new Map(),all=manifest.products.flatMap(p=>Object.values(p.assets).flat()),urls=[...new Map(all.map(a=>[a.url,a])).values()];
+  for(let i=0;i<urls.length;i+=4)await Promise.all(urls.slice(i,i+4).map(async a=>cache.set(a.url,a.width>0&&a.height>0?{width:a.width,height:a.height}:await invoke('sealseek-media',['media','inspect','--url',a.url,'--kind',a.kind,'--json']))));
+  for(const a of all){const d=cache.get(a.url);a.width=d.width;a.height=d.height;}
+  const plan=layout(manifest,{...options,basePlan:base});
+  if(base){plan.target_canvas_id=state.canvas_id;plan.base_snapshot=base.batch;manifest.products=[...baseManifest.products,...manifest.products];}
+  await checkpoint(path.join(run,'assets.manifest.json'),manifest);
+  await create(path.join(run,'layout.plan.json'),plan);await create(path.join(run,'canvas.batch.json'),plan.batch);
+  return {run_id:plan.run_id,frames:plan.batch.frames.length,media:plan.batch.media.length,title:plan.title,...(state?{canvas_id:state.canvas_id,appending:true}:{})};
+}
+export async function appendRun(run,baseRun,inputs,rawFiles=[]){
+  const previous=await read(path.join(baseRun,'assets.manifest.json')),plan=await read(path.join(baseRun,'layout.plan.json'));
+  if(plan.schema_version!==2)fail('LAYOUT_MIGRATION_REQUIRED','Run reflow on base canvas first.');
+  const fresh=normalizeInputs(inputs).filter(p=>!previous.products.some(old=>old.id===p.id));
+  if(!fresh.length)return {changed:false,reason:'All requested products are already present.',base_run:baseRun};
+  await collect(run,fresh.map(p=>p.input),rawFiles);
+  return planRun(run,{baseRun});
+}
+export function matchesBatch(readback,batch){
+  const elements=readback.elements.filter(e=>!e.isDeleted);
+  if(elements.filter(e=>e.type==='frame').length!==batch.frames.length||elements.filter(e=>e.type==='image').length!==batch.media.length)return false;
+  if(!(batch.texts||[]).every(t=>{const e=elements.find(e=>e.id===t.id);return e&&e.type==='text'&&['text','x','y','width','height','fontSize'].every(k=>e[k]===t[k]);}))return false;
+  return batch.frames.every(f=>{const e=elements.find(e=>e.id===f.id);return e&&['name','x','y','width','height'].every(k=>e[k]===f[k]);})&&batch.media.every(m=>{const e=elements.find(e=>e.customData?.cliTaskId===m.id);return e&&e.frameId===m.frameId&&['x','y','width','height'].every(k=>e[k]===m.placement.positions[0][k])&&(m.kind==='video'?e.customData.videoUrl:e.customData.fileUrl)===m.urls[0];});
+}
+// Keep the actual server geometry for numerically equivalent bounds and caller-owned label formatting.
+export function reconcileBatch(readback,batch){
+  const result=structuredClone(batch),elements=readback.elements.filter(e=>!e.isDeleted);
+  const near=(a,b)=>Number.isFinite(a)&&Number.isFinite(b)&&Math.abs(a-b)<=1e-6;
+  for(const f of result.frames){const e=elements.find(e=>e.id===f.id);if(e&&e.type==='frame'&&e.name===f.name&&['x','y','width','height'].every(k=>near(e[k],f[k])))for(const k of ['x','y','width','height'])f[k]=e[k];}
+  for(const m of result.media){const e=elements.find(e=>e.customData?.cliTaskId===m.id),p=m.placement.positions[0];if(e&&e.frameId===m.frameId&&['x','y','width','height'].every(k=>near(e[k],p[k])))for(const k of ['x','y','width','height'])p[k]=e[k];}
+  for(const t of result.texts||[]){const e=elements.find(e=>e.id===t.id);if(e&&e.type==='text'&&e.text===t.text&&near(e.x,t.x)&&near(e.y,t.y)&&['width','height','fontSize'].every(k=>Number.isFinite(e[k])&&e[k]>0))for(const k of ['x','y','width','height','fontSize'])t[k]=e[k];}
+  return result;
+}
+export async function publishCanvas(run,submit=false){
+  const plan=await read(path.join(run,'layout.plan.json'));validateLayout(plan);
+  const file=path.join(run,'canvas.batch.json');let batch=await read(file);if(JSON.stringify(batch)!==JSON.stringify(plan.batch))fail('STATE_CONFLICT','Batch differs from validated layout.');
+  if(!submit)return {dry_run:true,title:plan.title,frames:batch.frames.length,media:batch.media.length};
+  await invoke('sealseek-media',['canvas','batch','preview','--file',file,'--json']);
+  if(plan.target_canvas_id){const current=await invoke('sealseek-media',['canvas','get',plan.target_canvas_id,'--json']);const baseline=reconcileBatch(current,plan.base_snapshot),normalized=reconcileBatch(current,batch);if(!matchesBatch(current,baseline)&&!matchesBatch(current,normalized))fail('CANVAS_CHANGED','Base canvas differs from the saved layout. Use the newest completed run; existing elements are preserved.');if(JSON.stringify(normalized)!==JSON.stringify(batch)){batch=normalized;plan.batch=batch;plan.base_snapshot=baseline;validateLayout(plan);await checkpoint(file,batch);await checkpoint(path.join(run,'layout.plan.json'),plan);}}
+  const statePath=path.join(run,'canvas.state.json');let state=await exists(statePath)?await read(statePath):{run_id:plan.run_id,status:'ready',...(plan.target_canvas_id?{canvas_id:plan.target_canvas_id}:{})};
+  if(state.run_id!==plan.run_id)fail('STATE_CONFLICT','Canvas state is from another run.');
+  if(!state.canvas_id){if(state.status==='creating')fail('SUBMISSION_UNCERTAIN','Canvas creation outcome unknown. Inspect canvas list and bind recovered ID before retrying.');state.status='creating';await checkpoint(statePath,state);const board=await invoke('sealseek-media',['canvas','create','--title',plan.title,'--submit','--json']);if(!board.canvas_id)fail('SUBMISSION_UNCERTAIN','No canvas ID.');state={...state,...board,status:'created'};await checkpoint(statePath,state);}
+  const saved=await invoke('sealseek-media',['canvas','batch',state.canvas_id,'--file',file,'--submit','--json']);
+  const readback=await invoke('sealseek-media',['canvas','get',state.canvas_id,'--json']);
+  const elements=readback.elements.filter(e=>!e.isDeleted),frames=elements.filter(e=>e.type==='frame'),media=elements.filter(e=>e.type==='image');
+  if(frames.length!==batch.frames.length||media.length!==batch.media.length)fail('OUTPUT_CONTRACT_FAILED','Readback element count mismatch.');
+  for(const f of batch.frames){const found=frames.find(e=>e.id===f.id);if(!found||!['name','x','y','width','height'].every(k=>found[k]===f[k]))fail('OUTPUT_CONTRACT_FAILED','Frame readback mismatch.');}
+  for(const m of batch.media){const e=media.find(e=>e.customData?.cliTaskId===m.id);if(!e||e.frameId!==m.frameId||!['x','y','width','height'].every(k=>e[k]===m.placement.positions[0][k])||(m.kind==='video'?e.customData.videoUrl:e.customData.fileUrl)!==m.urls[0])fail('OUTPUT_CONTRACT_FAILED','Media readback mismatch.');}
+  if(!matchesBatch(readback,batch))fail('OUTPUT_CONTRACT_FAILED','Canvas labels or content readback mismatch.');
+  await checkpoint(statePath,{...state,status:'completed',canvas_url:readback.canvas_url});
+  const manifest=await read(path.join(run,'assets.manifest.json')),report={run_id:plan.run_id,status:'completed',canvas_id:state.canvas_id,canvas_url:readback.canvas_url,frames:frames.length,media:media.length,products:manifest.products.map(p=>({id:p.id,title:p.title,shop:p.shop.shopName,coverage:p.coverage,counts:Object.fromEntries(Object.entries(p.assets).map(([k,v])=>[k,v.length]))})),saved,verification:'saved content read back and layout checked; browser visual inspection is separate'};
+  await checkpoint(path.join(run,'collection-report.json'),report);return report;
+}