@petercjl/infinite-canvas-cli 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,46 @@
 # Infinite Canvas CLI
 
-Registration placeholder. Install the stable latest release for the usable CLI.
+`@petercjl/infinite-canvas-cli` uses an existing SealSeek Infinite Canvas board to generate videos through its native Agent conversation. It imports ordered reference images, sends the supplied prompt in a fresh conversation, downloads the video, and groups the original image nodes and video node in a Frame.
+
+This package requires Node.js 22+, the independent ecommerce Chrome launcher and an installed `sealseek-media` CLI supporting image upload and canvas get/add. The browser uses port 9223 and the dedicated ecommerce profile. The website supplies the selected model and authenticated account. Each authorized generation can incur charges.
+
+Each board file uses exactly one browser tab. Concurrent videos run in separate Agent conversations within that tab; UI submissions and canvas writes are queued while remote generation runs in parallel. Duplicate tabs must be resolved before submission or saving.
+
+## Agent usage
+
+Provide the board ID, prompt and reference image attachments in their intended order. Send the Agent:
+
+> 使用 infinite-canvas，画板 ID 为「画板ID」，按所附图片顺序作为图1、图2，生成视频：「完整提示词」。
+
+To install:
+
+> 安装 @petercjl/infinite-canvas-cli，并将配套 Skill 安装到本机 Codex。
+
+To update:
+
+> 更新 @petercjl/infinite-canvas-cli 及其本机 Codex 配套 Skill。
+
+To recover:
+
+> 使用 infinite-canvas，恢复任务「任务ID」。
+
+To update the selected local Codex Skill:
+
+> 将 infinite-canvas 当前安装包配套的 Skill 同步到本机 Codex。
+
+Codex/macOS has completed six live video tasks across two boards. Other Agent adapters require runtime verification.
+
+## Developer entry points
+
+```sh
+npm install
+npm test
+node bin/infinite-canvas.mjs --help
+node bin/infinite-canvas.mjs doctor --json
+```
+
+See the bundled [Skill](skills/infinite-canvas-video/SKILL.md) and [runtime commands](skills/infinite-canvas-video/references/runtime.md). `capabilities --json` exposes machine-readable contracts. Video generation defaults to dry run; `--submit` starts a background job and returns its task ID. Resume never clicks Send again after a submission intent has been recorded.
+
+Canvas operations reuse the existing helper CLI. Frame grouping provides the missing atomic operation for reparenting existing nodes, with backup, fresh-read conflict checks and save/readback verification. Website-authenticated read and canvas operations are isolated in one browser adapter. The adapter does not directly submit generation endpoints.
+
+The service has no documented compare-and-swap canvas save contract. Avoid concurrent manual editing during a job; detected unsaved or conflicting changes stop progress for recovery. Canvas synchronization relies on the current webpage editor adapter and must be revalidated when the webpage changes.

package/bin/infinite-canvas.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {META,ROOT,need,parse,readJSON,execute,stateRoot,newJSON,redact,safeId} from '../src/core.mjs';
+import {manifest,HELP} from '../src/contracts.mjs';
+import {automaticCheck,checkUpdate,installUpdate,updatePolicy,SKILL,skillStatus,installSkill} from '../src/lifecycle.mjs';
+
+const out=v=>console.log(JSON.stringify(v,null,2));
+async function main(argv){
+  const [command,action,...rest]=argv;
+  if(!command||['help','--help','-h'].includes(command))return console.log(HELP);
+  need(Number(process.versions.node.split('.')[0])>=22,'CAPABILITY_UNAVAILABLE','Node.js 22 or newer is required.');
+  if(['version','--version','-v'].includes(command)){const {args,options}=parse(argv.slice(1),{booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');return options.json?out({ok:true,name:META.name,version:META.version,entry:path.join(ROOT,'bin/infinite-canvas.mjs')}):console.log('infinite-canvas '+META.version);}
+  if(argv.includes('--help')||argv.includes('-h')){need(['video','task','frame','browser','board','skill','update','doctor','capabilities'].includes(command),'UNKNOWN_COMMAND','Unknown command.');return console.log(HELP);}
+  if(command==='_worker'){need(argv.length===2,'INVALID_ARGUMENT','Invalid worker invocation.');const {processJob}=await import('../src/workflow.mjs');return out(await processJob(action));}
+  if(command==='skill'){
+    const {options:o,args}=parse(rest,{values:['agent','path'],booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');
+    if(action==='source')return out({ok:true,source:SKILL,name:'infinite-canvas-video',version:META.version,installation:{named_agents:['codex'],fallback_agent:'generic',custom_path_required:true,scope:'selected Agent only'}});
+    if(action==='status')return out(await skillStatus(o.agent||'codex',o.path));
+    need(['install','update'].includes(action),'UNKNOWN_COMMAND','Use skill source/status/install/update.');return out(await installSkill(o.agent||'codex',o.path));
+  }
+  if(command==='update'){
+    if(action==='auto'){const [mode,...flags]=rest;const {args}=parse(flags,{booleans:['json']});need(['on','off','status'].includes(mode)&&!args.length,'INVALID_ARGUMENT','Use update auto on/off/status.');return out(await updatePolicy(mode));}
+    const {options:o,args}=parse(rest,{values:['agent','path'],booleans:['yes','json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');
+    if(action==='check')return out({ok:true,...await checkUpdate({force:true})});
+    need(action==='install','UNKNOWN_COMMAND','Use update check/install.');return out(await installUpdate({yes:o.yes,agent:o.agent,destination:o.path}));
+  }
+  if(command==='capabilities'){const {args}=parse(argv.slice(1),{booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');await automaticCheck();return out({ok:true,...manifest});}
+  if(command==='doctor'){
+    const {options:o,args}=parse(argv.slice(1),{values:['canvas'],booleans:['live','json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');await automaticCheck();const checks={node:process.version,entry:path.join(ROOT,'bin/infinite-canvas.mjs'),platform:process.platform,skill:SKILL};
+    for(const library of ['playwright-core','image-size']){try{await import(library);checks[library]={ok:true};}catch{checks[library]={ok:false};}}
+    try{checks.media={ok:true,version:(await execute(process.env.INFINITE_CANVAS_MEDIA_BIN||'sealseek-media',['--version'],{timeout:15000})).stdout.trim()};}catch{checks.media={ok:false};}
+    try{checks.browser=JSON.parse((await execute(process.env.INFINITE_CANVAS_BROWSER_BIN||path.join(os.homedir(),'.local','bin','ecommerce-browser'),['status','--json'],{timeout:15000})).stdout);}catch{checks.browser={ok:false};}
+    if(o.live){need(o.canvas,'INVALID_ARGUMENT','Live doctor requires --canvas ID.');const {BrowserDriver,LOCATORS}=await import('../src/browser.mjs');const driver=new BrowserDriver();try{await driver.connect(o.canvas,{open:false});const board=await driver.getBoard();checks.live={canvas_id:String(board.id),title:board.title,locators:{}};for(const [k,s]of Object.entries(LOCATORS))checks.live.locators[k]=await driver.page.locator(s).count();}finally{await driver.close();}}
+    const ok=checks.media.ok&&checks['playwright-core'].ok&&checks['image-size'].ok&&checks.browser.state==='ready';if(!ok)process.exitCode=1;return out({ok,checks,paid_action:false,end_to_end:'not-tested-by-doctor'});
+  }
+  if(command==='browser'&&action==='status'){const {args}=parse(rest,{booleans:['json']});need(!args.length,'INVALID_ARGUMENT','Unexpected arguments.');const r=await execute(process.env.INFINITE_CANVAS_BROWSER_BIN||path.join(os.homedir(),'.local','bin','ecommerce-browser'),['status','--json'],{timeout:15000});return out(JSON.parse(r.stdout));}
+  if(command==='board'&&action==='inspect'){const {options:o,args}=parse(rest,{values:['canvas'],booleans:['json']});need(!args.length&&o.canvas,'INVALID_ARGUMENT','Provide --canvas ID.');const {MediaCLI}=await import('../src/media-cli.mjs');return out(await new MediaCLI().get(o.canvas));}
+  if(command==='video'&&action==='generate'){
+    const {options:o,args}=parse(rest,{values:['canvas','prompt','prompt-file','output','request-id'],repeat:['reference'],booleans:['new','submit','dry-run','json']});need(!args.length&&!(o.submit&&o['dry-run']),'INVALID_ARGUMENT','Conflicting options or extra arguments.');need(!!o.prompt!==!!o['prompt-file'],'INVALID_ARGUMENT','Provide exactly one prompt source.');need(!(o.new&&o['request-id']),'INVALID_ARGUMENT','Use new or request-id.');
+    const {prepareInput,createJob,summary}=await import('../src/state.mjs');const input=await prepareInput({canvas:o.canvas,prompt:o.prompt??await fs.readFile(o['prompt-file'],'utf8'),references:o.reference,output:o.output});await automaticCheck();
+    if(!o.submit)return out({ok:true,dry_run:true,paid_action:false,canvas_id:input.canvasId,prompt:input.prompt,references:input.references.map((r,i)=>({label:'图'+(i+1),source:r.source,sha256:r.sha256||null})),workflow:['import-references','new-native-conversation','ordered-attachments','send-prompt','follow-run','download','deduplicate-video','group-original-nodes-in-frame'],generation_submission:'webpage Agent Send button',model:'inherit webpage settings'});
+    const {job,reused}=await createJob(input,{requestId:o['request-id'],newRequest:!!o.new});if(!reused){const {spawnWorker}=await import('../src/workflow.mjs');await spawnWorker(job.id);}return out({...summary(job),reused});
+  }
+  if(command==='task'){
+    const {options:o,args}=parse(rest,{values:['timeout'],booleans:['json']});need(args.length===1,'INVALID_ARGUMENT','Provide one task ID.');const {getJob,summary}=await import('../src/state.mjs');
+    if(action==='get'){need(!o.timeout,'INVALID_ARGUMENT','timeout applies only to wait.');return out(summary(await getJob(args[0])));}
+    const {resumeJob,waitJob,syncJob}=await import('../src/workflow.mjs');if(['resume','sync'].includes(action)){need(!o.timeout,'INVALID_ARGUMENT','timeout applies only to wait.');return out(await (action==='sync'?syncJob:resumeJob)(args[0]));}need(action==='wait','UNKNOWN_COMMAND','Use task get/wait/resume/sync.');return out(await waitJob(args[0],Number(o.timeout||30)));
+  }
+  if(command==='frame'&&action==='group'){
+    const {options:o,args}=parse(rest,{values:['canvas','elements','frame-id','name'],booleans:['submit','json']});need(!args.length&&o.canvas&&o.elements&&o['frame-id'],'INVALID_ARGUMENT','Provide canvas, elements JSON file, and frame-id.');safeId(o.canvas,'canvas ID');safeId(o['frame-id'],'Frame ID');const ids=await readJSON(o.elements);need(Array.isArray(ids)&&ids.length>0&&ids.length<=30&&new Set(ids).size===ids.length,'INVALID_INPUT','Provide unique element IDs.');ids.forEach(id=>safeId(id,'element ID'));await automaticCheck();
+    const {BrowserDriver}=await import('../src/browser.mjs');const {groupIntoFrame}=await import('../src/frame.mjs');const driver=new BrowserDriver();try{await driver.connect(o.canvas);const group=content=>groupIntoFrame(content,{ids,frameId:o['frame-id'],name:o.name});if(!o.submit){const board=await driver.getBoard();const preview=group(board.content);delete preview.content;return out({ok:true,dry_run:true,...preview});}const directory=path.join(stateRoot(),'frame-operations',crypto.randomUUID());return out({ok:true,...await driver.saveFrame(group,directory),content:undefined});}finally{await driver.close();}
+  }
+  need(false,'UNKNOWN_COMMAND','Unknown command. Use --help.');
+}
+main(process.argv.slice(2)).catch(e=>{out({ok:false,error:redact(e)});process.exitCode=1;});

package/capabilities.json

@@ -0,0 +1,219 @@
+{
+  "schema": "infinite-canvas-capabilities",
+  "schema_version": "1.0.0",
+  "package": "@petercjl/infinite-canvas-cli",
+  "version": "0.1.0",
+  "input": {
+    "required": [
+      "canvas_id",
+      "prompt",
+      "references"
+    ],
+    "references": "ordered PNG/JPEG/WebP local files or HTTPS URLs"
+  },
+  "output": {
+    "terminal": "local MP4 + saved Frame containing original reference nodes and one video node",
+    "fields": [
+      "task_id",
+      "status",
+      "canvas_id",
+      "session_id",
+      "run_id",
+      "frame_id",
+      "reference_element_ids",
+      "video_element_id",
+      "artifacts"
+    ]
+  },
+  "operations": [
+    "browser.status",
+    "board.inspect",
+    "video.generate.native-agent",
+    "task.inspect",
+    "task.wait",
+    "task.resume",
+    "task.sync",
+    "frame.group-existing"
+  ],
+  "generationTransport": {
+    "kind": "native-browser-ui",
+    "newConversationPerLogicalVideo": true,
+    "singleTabPerCanvas": true,
+    "concurrency": "separate conversations in the same tab; queued UI submissions and canvas writes; parallel remote runs",
+    "submission": "click native Send",
+    "directGenerationAPI": false,
+    "recovery": "saved sessionId/runId; read-only run and history APIs",
+    "model": "inherit webpage settings"
+  },
+  "dependencies": {
+    "node": ">=22",
+    "browser": "ecommerce-browser, fixed loopback CDP 9223 and current-user ecommerce profile",
+    "canvasAPI": "sealseek-media >=0.6.7, public CLI commands",
+    "libraries": [
+      "playwright-core",
+      "image-size"
+    ],
+    "optional": [
+      "ffprobe"
+    ]
+  },
+  "platforms": {
+    "codex:macos": "tested: six native Agent video tasks across two boards; one tab per board; downloads, deduplication and Frame readback verified",
+    "generic:macos": "spec-compatible, runtime untested",
+    "sealseek:macos": "spec-compatible, runtime untested",
+    "generic:windows": "runtime unresolved: ecommerce browser launcher required"
+  },
+  "commandContracts": {
+    "video generate": {
+      "options": {
+        "--canvas": {
+          "type": "string"
+        },
+        "--prompt": {
+          "type": "string"
+        },
+        "--prompt-file": {
+          "type": "string"
+        },
+        "--reference": {
+          "type": "string",
+          "repeatable": true
+        },
+        "--output": {
+          "type": "string"
+        },
+        "--request-id": {
+          "type": "string"
+        },
+        "--new": {
+          "type": "boolean"
+        },
+        "--submit": {
+          "type": "boolean"
+        },
+        "--dry-run": {
+          "type": "boolean"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write",
+      "externalMutation": "With --submit: import references, send native Agent conversation, import a missing video, group selected elements in a Frame.",
+      "paid": "Only native webpage sending may charge credits."
+    },
+    "task get|wait|resume|sync": {
+      "options": {
+        "--timeout": {
+          "type": "string"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write",
+      "externalMutation": "resume continues original task; sync reapplies existing video archival and grouping; never a second generation."
+    },
+    "frame group": {
+      "options": {
+        "--canvas": {
+          "type": "string"
+        },
+        "--elements": {
+          "type": "string"
+        },
+        "--frame-id": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        },
+        "--submit": {
+          "type": "boolean"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write",
+      "externalMutation": "With --submit: reparent existing nodes and preserve their identities."
+    },
+    "doctor": {
+      "options": {
+        "--canvas": {
+          "type": "string"
+        },
+        "--live": {
+          "type": "boolean"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status|install|update": {
+      "options": {
+        "--agent": {
+          "type": "string"
+        },
+        "--path": {
+          "type": "string"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update check|install": {
+      "options": {
+        "--yes": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--path": {
+          "type": "string"
+        },
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    },
+    "update auto": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    }
+  },
+  "automaticUpdates": {
+    "enabledByDefault": true,
+    "defaultMode": "notify",
+    "intervalHours": 24,
+    "timeoutMs": 1500,
+    "trigger": "ordinary video/frame/doctor/capabilities entry; excludes help/version/skill/task polling",
+    "configuration": "private update-policy.json; update auto on|off|status",
+    "disable": "INFINITE_CANVAS_AUTO_UPDATE=0",
+    "recovery": "offline backoff preserves installation; source checkout updates through Git; explicit install keeps a package backup",
+    "installation": "explicit --yes only; no automatic installation"
+  },
+  "limitations": [
+    "No service-side atomic canvas revision check; stop on detected user edits.",
+    "Frame grouping first version supports unrotated image/video nodes.",
+    "Do not submit another generation after unknown submission."
+  ]
+}

package/package.json

@@ -1,16 +1,40 @@
 {
   "name": "@petercjl/infinite-canvas-cli",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Package registration placeholder; stable CLI is released through GitHub Actions OIDC.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/petercjl/infinite-canvas-cli.git"
+  "version": "0.1.0",
+  "description": "Drive native Infinite Canvas Agent conversations and organize reference images and results in a Frame.",
+  "type": "module",
+  "bin": {
+    "infinite-canvas": "bin/infinite-canvas.mjs"
   },
   "files": [
-    "README.md"
+    "bin",
+    "src",
+    "skills",
+    "capabilities.json",
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/infinite-canvas.mjs && node --test"
+  },
+  "dependencies": {
+    "playwright-core": "1.62.1",
+    "image-size": "2.0.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petercjl/infinite-canvas-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/petercjl/infinite-canvas-cli/issues"
+  },
+  "homepage": "https://github.com/petercjl/infinite-canvas-cli#readme"
 }

package/skills/infinite-canvas-video/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: infinite-canvas-video
+description: "Use infinite-canvas to generate a video through an existing SealSeek Infinite Canvas Agent conversation UI, using a board ID, an unchanged user prompt, and ordered reference images; retrieve the video and group original image and video nodes in a Frame. Use when the user explicitly selects this canvas workflow."
+---
+
+# Infinite Canvas Video
+
+Execute an explicitly selected canvas video request with the installed `infinite-canvas` capability. The application or user owns creative choices, prompt, reference selection/order and acceptance. The CLI owns native submission, authentication reuse, canvas writes, idempotency and recovery.
+
+## Input and output
+
+Require a board file ID, the exact prompt and 1–20 ordered PNG, JPEG or WebP references (local paths or HTTPS URLs). Ask only for missing required inputs. Preserve the prompt and image order; 图1 means the first attached image. Inherit model settings from the webpage. An authorized generation request allows one paid native Agent submission. A planning or dry-run request allows validation only.
+
+Return the local MP4 from `artifacts[].path`, task ID, board ID and Frame ID. Success means `status=succeeded`, a nonempty downloaded video, original reference node IDs plus one video node in the saved Frame, and verified readback. A generated video with unfinished grouping is a partial result, reported with its task ID and recovery action.
+
+## Capability resolution
+
+Resolve `infinite-canvas` from PATH. Run `version --json`, `capabilities --json` and `skill source --json` to inspect the installed implementation and current canonical Skill. Minimum contract: native Agent Send, ordered references, existing-node grouping, task get/wait/resume, local video output. Load the selected host adapter in `adapters/`; `generic.json` is the portable fallback. If the entry or required feature is missing, return `CAPABILITY_UNAVAILABLE`; report the missing dependency instead of substituting another generation provider.
+
+External dependencies are Node.js 22+, `playwright-core` and `image-size` (package managed), the independent `ecommerce-browser` launcher, and `sealseek-media` with image upload, canvas get/add capabilities. This Skill invokes the helper through the CLI contract; it does not compose another generation Skill. Browser authentication stays in the user's dedicated Chrome profile. Never copy cookies or tokens into a prompt, output or package.
+
+## Main line
+
+1. Validate required inputs and authorization. Run `doctor --json`; for a UI compatibility check use `doctor --live --canvas ID --json`. On missing login or board, ask the user to sign in/open the board in the dedicated ecommerce Chrome, then return here. The CLI uses CDP port 9223 and the dedicated ecommerce profile. Enforce the single-tab constraint below before any submission or canvas write.
+2. Prepare the exact prompt in a new file when needed; preserve any existing file. Run `video generate --canvas ID --prompt-file FILE --reference IMAGE1 --reference IMAGE2 --dry-run --json`, repeating `--reference` in order. Dry run checks local inputs; it does not prove provider availability.
+3. For an authorized real request, run the same inputs with `--submit --json`. Save the returned task ID immediately. Repeated identical inputs reuse the same task. `--request-id KEY` provides caller-controlled idempotency; `--new` deliberately creates a new paid task and requires explicit intent to generate another video.
+4. Follow `task wait TASK_ID --timeout 30 --json` or `task get TASK_ID --json`. The worker imports references, creates a new native Agent conversation, attaches images, pastes the exact prompt and clicks Send. Status/history reads track the captured session and run. Generation is submitted only through the native UI.
+5. On completion, inspect the returned artifact and report its local path. The worker deduplicates the generated video against the board and groups the already imported image nodes and video into one actual Frame. Use the same task ID for any unfinished download or grouping.
+
+## Single-tab constraint and concurrency
+
+**Each board file must be open in exactly one browser tab.** Multiple tabs editing the same board cause save conflicts and the website may suspend editing. Reuse that board's existing tab. A different board may have its own tab.
+
+Run concurrent videos through separate native Agent conversations inside the board's single tab. Serialize the short UI operations: import references, create a fresh conversation, attach images, send once and capture session/run IDs. After submission, track each run independently while preparing another conversation in the same tab. Serialize canvas imports and Frame writes per board; remote generation waiting does not hold that queue. Keep the requested board file count unchanged when adding concurrent video tasks.
+
+Start one `video generate --submit` task per requested video, record every returned ID, and poll all tasks together. Submit the remaining tasks while earlier runs generate. The CLI queues tab selection and composition per board, including simultaneous first use. Use the installed CLI's verified selectors and transport; ordinary runs require no new selector or endpoint exploration.
+
+Conversation readiness means native session creation has completed before attaching references. Attachment readiness counts only the current composer and waits for uploaded HTTPS images. Other conversations may still stream during these steps. After canvas API writes, the CLI synchronizes the editor in place and verifies saved/live scene agreement. Page reload is excluded from this write path because the old scene's auto-save can replace newly imported nodes or Frames. Webpage contract changes return an adapter error for a separate repair cycle.
+
+If duplicate tabs for a board are detected, stop new submissions and writes with `BOARD_SELECTION_REQUIRED`. Preserve all task/session/run IDs, resolve the duplicate tabs, then resume existing tasks. When the website displays its other-tab editing protection, restore editing in the single retained tab after duplicates are closed. Claim resumed generation only from the existing run; a tab conflict never authorizes another paid submission.
+
+## Branches and recovery
+
+- `waiting`: the monitoring window or a connection ended; use `task resume TASK_ID --json`, then return to step 4. Remote runs continue independently.
+- `uncertain` / `SUBMISSION_UNCERTAIN`: preserve the task; resume inspects the captured session for exactly one run. If identity cannot be resolved, report the uncertainty and request inspection. Never start another paid task as an automatic retry.
+- `canvas_pending`: return any downloaded video as a partial result, then resume the same task for import/grouping. It does not resubmit generation.
+- For an explicitly requested repair of canvas archival after a completed task, use `task sync TASK_ID --json`. It reapplies the existing video's import/grouping with the original reference nodes and never generates another video. Preserve intentional user deletions unless restoration is authorized.
+- `UI_LOCATOR_CHANGED`, `AGENT_MODE_REQUIRED`, `REFERENCE_ORDER_CHANGED`: stop and report the adapter issue. If sending may have happened, preserve the task and inspect its history before further action.
+- `CANVAS_UNSAVED`, `CANVAS_CHANGED`, `UI_BUSY`: ask the user to finish active work and save; resume the same task after the board is settled.
+- `PROVIDER_FAILURE`: report the existing run's failure. Another video attempt is a new paid action.
+- File conflicts or unmanaged Skill/state: preserve existing files and report the exact conflict.
+
+Read [runtime reference](references/runtime.md) only when command details or recovery diagnostics are needed, then return to the relevant main-line step. Do not infer completion from chat prose alone.
+
+## QA and evolution
+
+Check one clean user message, captured native session/run IDs, attachment order at submission, exactly one result URL, returned reference metadata when provided, artifact bytes/hash and saved Frame membership. Report unavailable reference metadata or absent ffprobe verification honestly. Scope claims to actually tested hosts and operating systems. The current browser adapter needs live validation after webpage changes; independent clean-context regression is user gated.
+
+Install/update only the requested Agent through package-managed `skill install/update --agent codex`. The package is the source of truth. Automatic update detection is bounded and can be disabled; installation is explicit. Keep model defaults and private assets outside the package.

package/skills/infinite-canvas-video/adapters/codex.json

@@ -0,0 +1,24 @@
+{
+  "schema": "portable-skill-adapter",
+  "platform": "codex",
+  "mappings": [
+    {
+      "capability_id": "canvas.video.execute",
+      "status": "implemented",
+      "features": [
+        "native-agent-send",
+        "new-conversation",
+        "ordered-reference-images",
+        "canvas-import",
+        "existing-node-frame-group",
+        "task-recovery",
+        "local-video-output"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "command": "infinite-canvas",
+        "instructions": "Resolve from PATH. Run version, capabilities and doctor. Requires Node.js >=22, ecommerce-browser and sealseek-media. Use structured JSON. Codex/macOS end-to-end verified with six native Agent videos across two boards, one tab per board, downloads and saved Frame readback. Other hosts require their own runtime validation."
+      }
+    }
+  ]
+}

package/skills/infinite-canvas-video/adapters/generic.json

@@ -0,0 +1,24 @@
+{
+  "schema": "portable-skill-adapter",
+  "platform": "generic",
+  "mappings": [
+    {
+      "capability_id": "canvas.video.execute",
+      "status": "implemented",
+      "features": [
+        "native-agent-send",
+        "new-conversation",
+        "ordered-reference-images",
+        "canvas-import",
+        "existing-node-frame-group",
+        "task-recovery",
+        "local-video-output"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "command": "infinite-canvas",
+        "instructions": "Resolve from PATH. Run version, capabilities and doctor. Requires Node.js >=22, ecommerce-browser and sealseek-media. Use structured JSON. Named-host runtime end-to-end verification is pending."
+      }
+    }
+  ]
+}

package/skills/infinite-canvas-video/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "无限画板视频"
+  short_description: "通过网页 Agent 生成参考图视频并将输入和成片归入同一 Frame"
+  default_prompt: "使用 $infinite-canvas-video 按提供的画板、提示词和参考图片生成短视频。"

package/skills/infinite-canvas-video/capabilities.json

@@ -0,0 +1,52 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "skill": "infinite-canvas-video",
+  "target_platforms": [
+    "codex",
+    "generic"
+  ],
+  "host_resolution": {
+    "fallback_adapter": "generic"
+  },
+  "capabilities": [
+    {
+      "id": "canvas.video.execute",
+      "purpose": "Execute native Agent video generation and verified canvas grouping",
+      "required": true,
+      "required_features": [
+        "native-agent-send",
+        "new-conversation",
+        "ordered-reference-images",
+        "canvas-import",
+        "existing-node-frame-group",
+        "task-recovery",
+        "local-video-output"
+      ],
+      "input_fields": [
+        "canvas_id",
+        "prompt",
+        "references"
+      ],
+      "output_fields": [
+        "task_id",
+        "status",
+        "session_id",
+        "run_id",
+        "frame_id",
+        "artifacts"
+      ],
+      "side_effects": {
+        "external_mutation": true,
+        "may_cost_money": true,
+        "authorization": "An authorized video request permits one native generation; resume never resubmits."
+      },
+      "errors": [
+        "CAPABILITY_UNAVAILABLE",
+        "SUBMISSION_UNCERTAIN",
+        "CANVAS_SYNC_PENDING",
+        "OUTPUT_CONTRACT_FAILED"
+      ]
+    }
+  ]
+}

package/skills/infinite-canvas-video/references/runtime.md

@@ -0,0 +1,30 @@
+# Runtime command reference
+
+These commands are for the executing Agent and developers.
+
+Browser invariant: one board file, one tab. Reuse the existing tab for that canvas ID. Concurrent tasks use distinct native conversations and captured session/run IDs within that tab. `BOARD_SELECTION_REQUIRED` means resolve duplicate tabs before continuing; preserve the existing tasks. UI submission and canvas writes are queued per board, while remote runs can progress concurrently.
+
+```sh
+infinite-canvas version --json
+infinite-canvas capabilities --json
+infinite-canvas doctor --json
+infinite-canvas skill source --json
+infinite-canvas skill status --agent codex --json
+infinite-canvas skill install --agent codex --json
+infinite-canvas skill update --agent codex --json
+infinite-canvas video generate --canvas BOARD_ID --prompt-file PROMPT_FILE --reference IMAGE_1 --reference IMAGE_2 --dry-run --json
+infinite-canvas video generate --canvas BOARD_ID --prompt-file PROMPT_FILE --reference IMAGE_1 --reference IMAGE_2 --submit --json
+infinite-canvas task get TASK_ID --json
+infinite-canvas task wait TASK_ID --timeout 30 --json
+infinite-canvas task resume TASK_ID --json
+infinite-canvas task sync TASK_ID --json
+infinite-canvas update auto off --json
+```
+
+`--output` is an output directory; the MP4 filename is the unique task ID. Existing different bytes are preserved. HTTPS reference downloads are bounded to 30 MiB, local images are validated, and redirecting media URLs are rejected. An interrupted task is resumed with its original inputs and captured run.
+
+`board inspect --canvas ID --json` reads the board. `frame group --canvas ID --elements ELEMENT_IDS_JSON --frame-id FRAME_ID --json` previews grouping; `--submit` saves it. Only the selected existing unrotated image/video nodes are moved into the actual Frame. Layout uses a horizontal row with bounded media dimensions. Existing unrelated elements are preserved; conflicting Frame membership stops the operation.
+
+State resides under the user's application-data directory (`INFINITE_CANVAS_STATE_DIR` can select another private location). It contains task state, reference copies, readback backups, download metadata and worker logs. Preserve it for recovery; treat media URLs and prompts as private. `INFINITE_CANVAS_AUTO_UPDATE=0` disables automatic registry detection. Explicit update installation requires `update install --yes`, refuses source checkouts and backs up the installed package. Unpublished development versions have no registry update available.
+
+The CLI never prints browser credentials. Changing source, a live webpage deployment or a helper CLI version may require revalidation. JSON failures include `error.code` and `error.message`; keep the original task ID in user-facing recovery advice.

package/src/browser.mjs

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {chromium} from 'playwright-core';
+import {execute,need,Fault,sleep,hash,canonical,newJSON,lock} from './core.mjs';
+import {sceneSignature,verifyGrouping} from './frame.mjs';
+
+export const LOCATORS={newChat:'button:has(svg.lucide-square-plus)',upload:'input[type=file][accept="image/*,video/mp4,video/webm,video/*"]',editor:'[contenteditable=true][role=textbox]',send:'button[aria-label="发送消息"]'};
+export async function handleBrowserDialog(dialog){try{if(dialog.type()==='beforeunload'||dialog.type()==='alert')await dialog.accept();else await dialog.dismiss();return true;}catch{return false;}}
+export function composerImageState(expected){let node=document.querySelector('[contenteditable=true][role=textbox]');while(node&&!node.querySelector('input[type=file]'))node=node.parentElement;const imgs=[...(node?.querySelectorAll('[data-horizontal-media-strip] img')||[])];if(typeof expected!=='number')return imgs.length;return imgs.length===expected&&imgs.every(e=>e.src.startsWith('https://')&&e.complete&&e.naturalWidth>0)&&!node.innerText.includes('上传中');}
+export function allowedGateway(route,method='GET'){
+  if(method==='POST')return route==='/canvas/save';
+  return method==='GET'&&(/^\/canvas\/detail\/[A-Za-z0-9_-]+$/.test(route)||route==='/chat/v3/history'||/^\/threads\/[A-Za-z0-9_-]+\/runs(?:\/[A-Za-z0-9_-]+)?$/.test(route));
+}
+export function nativeSubmission(body,expectedPrompt,files){
+  need(body?.config?.configurable?.chat_mode==='agent','AGENT_MODE_REQUIRED','The webpage did not submit in Agent mode.');
+  need(body.input?.messages?.length===1,'CONTEXT_NOT_CLEAN','Expected one message in a new conversation.');
+  const content=body.input.messages[0].content,text=typeof content==='string'?content:content?.filter(c=>c.type==='text').map(c=>c.text).join('');
+  need(text===expectedPrompt,'UI_CHANGED','The webpage submitted a different prompt.');
+  const refs=Array.isArray(content)?content.filter(c=>c.type==='image_url'):[];
+  need(refs.length===files.length&&refs.every((r,i)=>r.name===path.basename(files[i])),'REFERENCE_ORDER_CHANGED','The submitted reference order differs from the input.');
+  return {sessionId:body.metadata?.session_id,referenceUrls:refs.map(r=>r.image_url.url),videoSettings:body.config.configurable.video_params,traceId:body.config.configurable.trace_id};
+}
+
+export class BrowserDriver {
+  async connect(canvasId,{open=true}={}){
+    this.canvasId=canvasId;
+    let launcher=process.env.INFINITE_CANVAS_BROWSER_BIN||'ecommerce-browser',r;
+    try{r=await execute(launcher,['status','--json'],{timeout:15000});}catch(e){if(e.code==='ENOENT'&&!process.env.INFINITE_CANVAS_BROWSER_BIN){launcher=path.join(os.homedir(),'.local','bin','ecommerce-browser');r=await execute(launcher,['status','--json'],{timeout:15000});}else throw new Fault('BROWSER_UNAVAILABLE','Cannot inspect the ecommerce browser.');}
+    let status=JSON.parse(r.stdout);if(status.state!=='ready'&&open){await execute(launcher,['open'],{timeout:30000});status=JSON.parse((await execute(launcher,['status','--json'],{timeout:15000})).stdout);}
+    need(status.state==='ready'&&status.cdp==='http://127.0.0.1:9223','BROWSER_UNAVAILABLE','The fixed ecommerce CDP browser is unavailable.');
+    const profile=path.join(os.homedir(),'.dianshang-chrome-profile');need(path.resolve(status.profile)===profile,'PROFILE_MISMATCH','Ecommerce browser profile mismatch.');
+    if(process.platform!=='win32'){let verified=false;for(const pid of status.pids||[]){try{const ps=await execute('ps',['-p',String(pid),'-o','command=']);verified ||= ps.stdout.includes('--remote-debugging-port=9223')&&ps.stdout.includes('--user-data-dir='+profile);}catch{}}need(verified,'PROFILE_MISMATCH','Chrome process arguments could not be verified.');}
+    this.status=status;this.browser=await chromium.connectOverCDP(status.cdp,{timeout:15000});
+    for(const context of this.browser.contexts()){for(const page of context.pages())page.on('dialog',handleBrowserDialog);context.on('page',page=>page.on('dialog',handleBrowserDialog));}
+    await this.composerLock(()=>this.selectBoardTab({open}));
+    const resumeEditor=this.page.getByRole('button',{name:'在此继续编辑',exact:true});if(await resumeEditor.count()===1)await resumeEditor.click();
+    try{await this.page.locator('.excalidraw').waitFor({state:'attached',timeout:25000});await this.page.locator(LOCATORS.editor).waitFor({state:'attached',timeout:25000});await this.unique(LOCATORS.editor);}catch{throw new Fault('AUTH_OR_BOARD_REQUIRED','Sign in and open an editable board in the ecommerce browser.');}
+    this.baseline=sceneSignature(await this.liveElements());return this;
+  }
+  async selectBoardTab({open=true}={}){
+    const canvasId=this.canvasId,pages=this.browser.contexts().flatMap(c=>c.pages()),matching=pages.filter(p=>this.boardId(p.url())===canvasId);
+    need(matching.length<=1,'BOARD_SELECTION_REQUIRED','The same board is open in multiple tabs. Keep one target tab.');this.page=matching[0];
+    if(!this.page){need(open,'BOARD_NOT_OPEN','Open the requested board in the ecommerce browser.');const context=this.browser.contexts()[0];need(context,'BROWSER_UNAVAILABLE','Browser context unavailable.');this.page=await context.newPage();await this.page.goto('https://sealseek.cn/board/#/canvas/'+encodeURIComponent(canvasId),{waitUntil:'domcontentloaded'});}
+    return this.page;
+  }
+  boardId(url){try{const u=new URL(url);return u.protocol==='https:'&&u.hostname==='sealseek.cn'?u.hash.match(/^#\/canvas\/([^?]+)/)?.[1]:null;}catch{return null;}}
+  assertBoard(){need(this.boardId(this.page.url())===this.canvasId,'BOARD_CHANGED','The browser navigated to another board.');}
+  async unique(selector){const l=this.page.locator(selector);need(await l.count()===1,'UI_LOCATOR_CHANGED','Expected one matching webpage control.',{selector});return l;}
+  async idle(){need(await this.page.locator('button[aria-label="停止生成"],button[aria-label="视频生成中，任务提交后暂不可停止"]').count()===0,'UI_BUSY','A conversation is still generating in this page.');}
+  async gateway(route,{method='GET',params,data}={}){
+    this.assertBoard();need(allowedGateway(route,method),'FORBIDDEN_OPERATION','This driver only permits status, history and canvas operations.');
+    const request=this.page.evaluate(async({route,method,params,data})=>{
+      const urls=performance.getEntriesByType('resource').filter(r=>r.initiatorType==='script'&&/\/board\/static\/index-[^/]+\.js$/.test(r.name)).map(r=>r.name);
+      let client;for(const u of urls.slice(0,8)){const m=await import(u);const candidates=[...new Set(Object.values(m).filter(v=>typeof v==='function'&&v.interceptors?.request&&String(v.defaults?.baseURL||'').includes('/api/sealseek-infinitecanvas')))];if(candidates.length===1){client=candidates[0];break;}}
+      if(!client)throw Error('WEB_CLIENT_UNAVAILABLE: webpage client export changed');
+      const origin=new URL(client.defaults.baseURL).origin;
+      const target=route.startsWith('/threads/')?origin+'/api/canvas/v2'+route:route;
+      const r=await client(target,{method,params,data,timeout:20000});
+      if(r?.code!==undefined&&r.code!==200)throw Error('PROVIDER_FAILURE: '+String(r.msg||r.code));
+      return r?.code===200?r.data:r;
+    },{route,method,params,data});
+    let timer;try{return await Promise.race([request,new Promise((_,reject)=>{timer=setTimeout(()=>reject(new Fault('WEB_REQUEST_TIMEOUT','Browser API request did not complete; inspect saved state before retrying.')),25000);})]);}finally{clearTimeout(timer);}
+  }
+  getBoard(){return this.gateway('/canvas/detail/'+this.canvasId,{params:{_ic_read:crypto.randomUUID()}});}
+  history(sessionId){return this.gateway('/chat/v3/history',{params:{sessionId,limit:100}});}
+  run(sessionId,runId){return this.gateway(`/threads/${sessionId}/runs/${runId}`);}
+  runs(sessionId){return this.gateway(`/threads/${sessionId}/runs`);}
+  async liveElements(){
+    await this.page.locator('.excalidraw').waitFor({state:'attached',timeout:25000});
+    return this.page.evaluate(()=>{
+      const el=document.querySelector('.excalidraw');if(!el)throw Error('EDITOR_UNAVAILABLE');const k=Object.keys(el).find(k=>k.startsWith('__reactFiber$'));let f=k&&el[k];while(f?.return)f=f.return;
+      const seen=new Set();let result;function walk(n){if(!n||seen.has(n)||result)return;seen.add(n);if(seen.size>30000)return;const a=n.stateNode;if(a&&typeof a.getSceneElements==='function'){result=JSON.parse(JSON.stringify(a.getSceneElements()));return;}walk(n.child);walk(n.sibling);}walk(f);if(!result)throw Error('EDITOR_ADAPTER_UNSUPPORTED');return result;
+    });
+  }
+  async beforeWrite(){
+    this.assertBoard();const end=Date.now()+12000;
+    while(Date.now()<end){const before=await this.getBoard(),live=await this.liveElements();if(sceneSignature(live)===sceneSignature(JSON.parse(before.content).elements))return {before,signature:sceneSignature(live)};if(sceneSignature(live)===this.baseline){await this.syncLive(before.content);this.baseline=sceneSignature(await this.liveElements());}await sleep(500);}
+    throw new Fault('CANVAS_UNSAVED','Webpage and saved canvas differ. Finish manual edits and save before retrying.');
+  }
+  async afterWrite(token){
+    need(sceneSignature(await this.liveElements())===token.signature,'CANVAS_SYNC_PENDING','Canvas was updated remotely, but the user changed the page. Save/reload must be resolved before continuing.');
+    await this.syncLive((await this.getBoard()).content);
+    const end=Date.now()+15000;while(Date.now()<end){const saved=await this.getBoard();if(sceneSignature(await this.liveElements())===sceneSignature(JSON.parse(saved.content).elements)){this.baseline=sceneSignature(await this.liveElements());return;}await sleep(500);}
+    throw new Fault('CANVAS_SYNC_PENDING','Canvas saved, but webpage synchronization was not verified.');
+  }
+  async syncLive(content){
+    await this.page.evaluate(async content=>{const data=JSON.parse(content||'{}'),el=document.querySelector('.excalidraw');if(!el)throw Error('EDITOR_UNAVAILABLE');const key=Object.keys(el).find(k=>k.startsWith('__reactFiber$'));let root=el[key];while(root?.return)root=root.return;const seen=new Set();let api;function walk(n){if(!n||seen.has(n)||api)return;seen.add(n);if(typeof n.stateNode?.getSceneElements==='function'){api=n.stateNode;return;}walk(n.child);walk(n.sibling);}walk(root);if(typeof api?.updateScene!=='function'||typeof api.addFiles!=='function')throw Error('EDITOR_ADAPTER_UNSUPPORTED');const files=Object.entries(data.imageUrlMap||{}).map(([id,url])=>({id,dataURL:url,mimeType:data.elements?.find(e=>e.fileId===id)?.customData?.fileMimeType||'image/png',created:Date.now(),lastRetrieved:Date.now()}));if(files.length)await api.addFiles(files);await api.updateScene({elements:data.elements||[],captureUpdate:'NEVER'});},content);
+  }
+  async writeLock(action){for(let i=0;i<120;i++){try{return await lock('board-write:'+this.canvasId,action);}catch(e){if(e.code!=='BUSY')throw e;await sleep(1000);}}throw new Fault('BUSY','Canvas write queue did not become available.');}
+  async composerLock(action){for(let i=0;i<300;i++){try{return await lock('board-ui:'+this.canvasId,action);}catch(e){if(e.code!=='BUSY')throw e;await sleep(1000);}}throw new Fault('BUSY','Canvas conversation queue did not become available.');}
+  async helperMutation(action){return this.writeLock(async()=>{const token=await this.beforeWrite();const out=await action();await this.afterWrite(token);return out;});}
+  async newConversation(){
+    this.assertBoard();const editor=await this.unique(LOCATORS.editor);
+    need(!(await editor.innerText()).replaceAll('\u200b','').trim(),'CHAT_DRAFT_PRESENT','Preserve the existing unsent chat draft.');
+    need(await this.page.evaluate(composerImageState)===0,'CHAT_DRAFT_PRESENT','Preserve the existing unsent attachments.');
+    const created=this.page.waitForResponse(r=>r.request().method()==='POST'&&r.url().includes('/chat/createSession'),{timeout:20000});created.catch(()=>{});
+    await (await this.unique(LOCATORS.newChat)).click();const response=await created;need(response.ok(),'SESSION_CREATE_FAILED','Native conversation creation failed.');await response.finished();
+    await this.page.waitForTimeout(300);
+    await this.page.getByText('SealSeek AI 助手',{exact:true}).waitFor({timeout:15000});
+    need(await this.page.locator('button:has(svg.lucide-bot)').count()===1,'AGENT_MODE_REQUIRED','Select Agent mode in the webpage composer.');
+  }
+  async attach(files){
+    await (await this.unique(LOCATORS.upload)).setInputFiles(files);
+    await this.page.waitForFunction(composerImageState,files.length,{timeout:60000});
+  }
+  async send(prompt,files,onCaptured){
+    this.assertBoard();await (await this.unique(LOCATORS.editor)).fill(prompt);
+    const requestWait=this.page.waitForRequest(r=>r.method()==='POST'&&/\/api\/canvas\/v2\/threads\/[^/]+\/runs\/stream$/.test(r.url()),{timeout:25000});
+    requestWait.catch(()=>{});
+    await (await this.unique(LOCATORS.send)).click();
+    const req=await requestWait,body=req.postDataJSON();
+    const captured={sessionId:body.metadata?.session_id,requestObserved:true,referenceUrls:(body.input?.messages?.[0]?.content||[]).filter?.(c=>c.type==='image_url').map(c=>c.image_url.url)||[],videoSettings:body.config?.configurable?.video_params};
+    await onCaptured(captured);
+    const context=nativeSubmission(body,prompt,files);
+    need(context.sessionId,'SUBMISSION_UNCERTAIN','Native request has no session ID.');await onCaptured({...context,requestObserved:true});
+    const response=await req.response();need(response&&response.ok(),'SUBMISSION_UNCERTAIN','Native submission response was not verified.');
+    const headers=response.headers(),runId=headers['x-run-id']||headers['content-location']?.match(/\/runs\/([^/]+)$/)?.[1];
+    need(runId,'SUBMISSION_UNCERTAIN','Native submission did not expose a run ID.');await onCaptured({...context,runId});return {...context,runId};
+  }
+  async saveFrame(change,directory){
+    return this.composerLock(()=>this.writeLock(()=>this.saveFrameLocked(change,directory)));
+  }
+  async saveFrameLocked(change,directory){
+    const token=await this.beforeWrite(),next=change(token.before.content);
+    if(!next.changed){verifyGrouping(token.before.content,token.before.content,next);return {...next,changed:false};}
+    await newJSON(path.join(directory,`canvas-before-frame-${crypto.randomUUID()}.json`),{content:token.before.content,id:this.canvasId,createdAt:new Date().toISOString()});
+    const fresh=await this.getBoard();need(fresh.content===token.before.content,'CANVAS_CHANGED','Canvas changed before grouping.');
+    await this.gateway('/canvas/save',{method:'POST',data:{id:this.canvasId,content:next.content,thumbnail:token.before.thumbnail,triggerType:'auto'}});
+    const after=await this.getBoard();verifyGrouping(token.before.content,after.content,next);await this.afterWrite(token);return next;
+  }
+  async close(){await this.browser?.close();}
+}

package/src/contracts.mjs

@@ -0,0 +1,55 @@
+import {META} from './core.mjs';
+const s={type:'string'},b={type:'boolean'};
+export const commandContracts={
+  'video generate':{options:{'--canvas':s,'--prompt':s,'--prompt-file':s,'--reference':{...s,repeatable:true},'--output':s,'--request-id':s,'--new':b,'--submit':b,'--dry-run':b,'--json':b},sideEffects:'local-write',externalMutation:'With --submit: import references, send native Agent conversation, import a missing video, group selected elements in a Frame.',paid:'Only native webpage sending may charge credits.'},
+  'task get|wait|resume|sync':{options:{'--timeout':s,'--json':b},sideEffects:'local-write',externalMutation:'resume continues original task; sync reapplies existing video archival and grouping; never a second generation.'},
+  'frame group':{options:{'--canvas':s,'--elements':s,'--frame-id':s,'--name':s,'--submit':b,'--json':b},sideEffects:'local-write',externalMutation:'With --submit: reparent existing nodes and preserve their identities.'},
+  'doctor':{options:{'--canvas':s,'--live':b,'--json':b},sideEffects:'none'},
+  'skill source':{options:{'--json':b},sideEffects:'none'},
+  'skill status|install|update':{options:{'--agent':s,'--path':s,'--json':b},sideEffects:'local-write'},
+  'update check|install':{options:{'--yes':b,'--agent':s,'--path':s,'--json':b},sideEffects:'package-and-skill-update'},
+  'update auto':{options:{'--json':b},sideEffects:'local-write'}
+};
+export const manifest={schema:'infinite-canvas-capabilities',schema_version:'1.0.0',package:META.name,version:META.version,
+  input:{required:['canvas_id','prompt','references'],references:'ordered PNG/JPEG/WebP local files or HTTPS URLs'},
+  output:{terminal:'local MP4 + saved Frame containing original reference nodes and one video node',fields:['task_id','status','canvas_id','session_id','run_id','frame_id','reference_element_ids','video_element_id','artifacts']},
+  operations:['browser.status','board.inspect','video.generate.native-agent','task.inspect','task.wait','task.resume','task.sync','frame.group-existing'],
+  generationTransport:{kind:'native-browser-ui',newConversationPerLogicalVideo:true,singleTabPerCanvas:true,concurrency:'separate conversations in the same tab; queued UI submissions and canvas writes; parallel remote runs',submission:'click native Send',directGenerationAPI:false,recovery:'saved sessionId/runId; read-only run and history APIs',model:'inherit webpage settings'},
+  dependencies:{node:'>=22',browser:'ecommerce-browser, fixed loopback CDP 9223 and current-user ecommerce profile',canvasAPI:'sealseek-media >=0.6.7, public CLI commands',libraries:['playwright-core','image-size'],optional:['ffprobe']},
+  platforms:{'codex:macos':'tested: six native Agent video tasks across two boards; one tab per board; downloads, deduplication and Frame readback verified','generic:macos':'spec-compatible, runtime untested','sealseek:macos':'spec-compatible, runtime untested','generic:windows':'runtime unresolved: ecommerce browser launcher required'},
+  commandContracts,
+  automaticUpdates:{enabledByDefault:true,defaultMode:'notify',intervalHours:24,timeoutMs:1500,trigger:'ordinary video/frame/doctor/capabilities entry; excludes help/version/skill/task polling',configuration:'private update-policy.json; update auto on|off|status',disable:'INFINITE_CANVAS_AUTO_UPDATE=0',recovery:'offline backoff preserves installation; source checkout updates through Git; explicit install keeps a package backup',installation:'explicit --yes only; no automatic installation'},
+  limitations:['No service-side atomic canvas revision check; stop on detected user edits.','Frame grouping first version supports unrotated image/video nodes.','Do not submit another generation after unknown submission.']
+};
+export const HELP=`infinite-canvas ${META.version}
+
+video generate --canvas ID (--prompt TEXT | --prompt-file FILE)
+  --reference IMAGE ... [--output DIR] [--request-id KEY | --new]
+  [--dry-run | --submit] --json
+  Default: validate only. --submit starts one background native Agent task.
+  Each logical video uses a fresh conversation. The prompt is sent unchanged.
+  Final output: MP4 and a Frame containing the input nodes and resulting video.
+
+task get TASK_ID --json
+task wait TASK_ID [--timeout 30] --json       (1–60 seconds per wait)
+task resume TASK_ID --json                  (same session/run, no resubmission)
+task sync TASK_ID --json                    (reapply existing output to canvas, no generation)
+frame group --canvas ID --elements IDS.json --frame-id ID [--name TEXT]
+  [--submit] --json                         (preview by default)
+browser status --json
+board inspect --canvas ID --json
+doctor [--live --canvas ID] --json
+capabilities --json
+version [--json]
+skill source --json
+skill status|install|update [--agent codex|generic|AGENT_NAME] [--path DIR] --json
+update check --json
+update install --yes [--agent AGENT_NAME --path DIR] --json
+update auto on|off|status --json
+
+Runtime: Node >=22; ecommerce-browser; sealseek-media; logged-in board.
+Configuration: INFINITE_CANVAS_STATE_DIR, INFINITE_CANVAS_BROWSER_BIN,
+INFINITE_CANVAS_MEDIA_BIN. Credentials remain with their existing providers.
+Package update detection is throttled and can be disabled using
+INFINITE_CANVAS_AUTO_UPDATE=0. No generation is submitted by installation.
+`;

package/src/core.mjs

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import {constants} from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+
+export const ROOT=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
+export const META=JSON.parse(await fs.readFile(path.join(ROOT,'package.json'),'utf8'));
+export const execute=promisify(execFile);
+export class Fault extends Error {constructor(code,message,details={}){super(message);this.code=code;this.details=details;}}
+export function need(value,code,message,details){if(!value)throw new Fault(code,message,details);return value;}
+export const canonical=v=>JSON.stringify(sort(v));
+function sort(v){return Array.isArray(v)?v.map(sort):v&&typeof v==='object'?Object.fromEntries(Object.keys(v).sort().map(k=>[k,sort(v[k])])):v;}
+export const hash=v=>crypto.createHash('sha256').update(Buffer.isBuffer(v)?v:typeof v==='string'?v:canonical(v)).digest('hex');
+export const stateRoot=()=>path.resolve(process.env.INFINITE_CANVAS_STATE_DIR||path.join(os.homedir(),'.local','share','infinite-canvas'));
+export const exists=async p=>!!await fs.lstat(p).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
+export const readJSON=async p=>JSON.parse(await fs.readFile(p,'utf8'));
+export async function mkdir(p){await fs.mkdir(p,{recursive:true,mode:0o700});}
+export async function newFile(p,data){need(!await exists(p),'OUTPUT_EXISTS','Preserve the existing file.',{path:p});await mkdir(path.dirname(p));await fs.writeFile(p,data,{flag:'wx',mode:0o600});return p;}
+export const newJSON=(p,data)=>newFile(p,JSON.stringify(data,null,2)+'\n');
+export async function replaceOwned(p,data){
+  if(!await exists(p))return newJSON(p,data);
+  const stat=await fs.lstat(p);need(stat.isFile()&&!stat.isSymbolicLink(),'UNMANAGED_STATE','State must be a regular file.');
+  const old=await readJSON(p);need(old.owner===META.name,'UNMANAGED_STATE','Preserve user-owned state.',{path:p});
+  const backup=p+'.'+crypto.randomUUID()+'.backup';await fs.copyFile(p,backup,constants.COPYFILE_EXCL);
+  need((await fs.stat(backup)).size===stat.size,'BACKUP_FAILED','State backup could not be verified.');
+  const tmp=p+'.'+crypto.randomUUID()+'.tmp';await newJSON(tmp,data);await fs.rename(tmp,p);await fs.chmod(p,0o600);return p;
+}
+export const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+export function alive(pid){try{process.kill(pid,0);return true;}catch{return false;}}
+export async function lock(key,fn,{root=stateRoot()}={}){
+  const p=path.join(root,'locks',hash(key)+'.json');await mkdir(path.dirname(p));
+  if(await exists(p)){const old=await readJSON(p);need(old.owner===META.name,'UNMANAGED_STATE','Unrecognized lock.');need(!alive(old.pid),'BUSY','Another process owns this operation.',{pid:old.pid});await fs.rename(p,p+'.'+crypto.randomUUID()+'.abandoned');}
+  try{await newJSON(p,{owner:META.name,pid:process.pid,key,createdAt:new Date().toISOString()});}catch(e){if(['EEXIST','OUTPUT_EXISTS'].includes(e.code))throw new Fault('BUSY','Operation is already locked.');throw e;}
+  try{return await fn();}finally{await fs.unlink(p);}
+}
+export function safeId(v,label='ID'){need(typeof v==='string'&&/^[A-Za-z0-9_-]{1,100}$/.test(v),'INVALID_INPUT','Invalid '+label+'.');return v;}
+export function httpsUrl(v){const u=new URL(v);need(u.protocol==='https:'&&!u.username&&!u.password,'INVALID_INPUT','Use an HTTPS media URL.');return u;}
+export function redact(e){return {code:e.code||'OPERATION_FAILED',message:String(e.message||e).replace(/Bearer\s+\S+/g,'Bearer [redacted]').replace(/\beyJ[\w-]+\.[\w-]+\.[\w-]+/g,'[redacted]'),details:e.details||{}};}
+export function parse(argv,{values=[],booleans=[],repeat=[]}={}){
+  const o={},args=[];for(let i=0;i<argv.length;i++){
+    const token=argv[i];if(!token.startsWith('--')){args.push(token);continue;}
+    const k=token.slice(2);need([...values,...booleans,...repeat].includes(k),'INVALID_ARGUMENT','Unknown option: '+token);
+    need(!(k in o)||repeat.includes(k),'INVALID_ARGUMENT','Duplicate option: '+token);
+    if(booleans.includes(k)){o[k]=true;continue;}
+    const v=argv[++i];need(v!==undefined&&!v.startsWith('--'),'INVALID_ARGUMENT','Missing value for '+token);
+    if(repeat.includes(k))(o[k]??=[]).push(v);else o[k]=v;
+  }return {options:o,args};
+}

package/src/frame.mjs

@@ -0,0 +1,35 @@
+import {need,hash,canonical} from './core.mjs';
+
+export function mediaUrl(e){return e.customData?.videoUrl||e.customData?.fileUrl||e.src||null;}
+export function comparableUrl(s){try{const u=new URL(s);return u.origin+u.pathname;}catch{return s;}}
+export function findVideo(elements,url){return elements.filter(e=>!e.isDeleted&&e.customData?.isVideoThumbnail&&comparableUrl(mediaUrl(e))===comparableUrl(url));}
+export function sceneSignature(elements=[]){return hash(elements.filter(e=>!e.isDeleted&&!(e.type==='rectangle'&&e.customData?.type==='frame-background'&&e.customData.ownerFrameId===e.frameId&&e.id===e.frameId+'__bg')).map(e=>{const data={...e.customData};if(data.originalUrl===data.fileUrl||data.originalUrl===data.videoUrl)delete data.originalUrl;if(e.type==='frame'&&Array.isArray(data.fills))data.fills=data.fills.map(({id,...fill})=>fill);return Object.fromEntries(['id','type','x','y','width','height','angle','frameId','fileId','text','name','customData'].filter(k=>e[k]!==undefined).map(k=>[k,k==='customData'?data:e[k]]));}));}
+export function groupIntoFrame(content,{ids,frameId,name='Video references and result',padding=32,gap=24,width=320,retireIds=[]}){
+  need(Array.isArray(ids)&&ids.length>0&&ids.length<=30&&new Set(ids).size===ids.length,'INVALID_INPUT','Provide unique element IDs.');
+  need(/^[A-Za-z0-9_-]{1,100}$/.test(frameId)&&typeof name==='string'&&name.trim()&&name.length<=200,'INVALID_INPUT','Invalid Frame ID or name.');
+  need([padding,gap,width].every(n=>Number.isFinite(n)&&n>=0)&&width>0&&width<=2000,'INVALID_INPUT','Invalid layout values.');
+  const v=JSON.parse(content),before=canonical(v);need(Array.isArray(v.elements),'OUTPUT_CONTRACT_FAILED','Canvas elements are unavailable.');
+  const selected=ids.map(id=>need(v.elements.find(e=>e.id===id&&!e.isDeleted),'ELEMENT_NOT_FOUND','Selected element is missing.',{id}));
+  for(const id of retireIds){const e=v.elements.find(e=>e.id===id);if(!e)continue;need(!ids.includes(id)&&e.customData?.cliTaskId?.startsWith('ic-video-')&&selected.some(s=>s.customData?.isVideoThumbnail&&comparableUrl(mediaUrl(s))===comparableUrl(mediaUrl(e))),'FEATURE_UNSUPPORTED','Only a CLI-owned duplicate of the selected video can be retired.');if(!e.isDeleted){e.isDeleted=true;e.version=(e.version||1)+1;e.updated=Date.now();}}
+  need(selected.every(e=>e.type==='image'&&e.width>0&&e.height>0&&(!e.angle||e.angle===0)),'FEATURE_UNSUPPORTED','Frame grouping supports unrotated image/video nodes.');
+  const old=v.elements.find(e=>e.id===frameId);need(!old||(!old.isDeleted&&old.type==='frame'),'IDEMPOTENCY_CONFLICT','Frame ID conflicts with another element.');
+  if(old)need(!v.elements.some(e=>!e.isDeleted&&e.frameId===frameId&&!ids.includes(e.id)&&!(e.id===frameId+'__bg'&&e.type==='rectangle'&&e.customData?.type==='frame-background'&&e.customData.ownerFrameId===frameId)),'FRAME_CONFLICT','Frame contains unrelated elements.');
+  const others=v.elements.filter(e=>!e.isDeleted&&!ids.includes(e.id)&&e.id!==frameId);
+  const x=old?.x??0,y=old?.y??(others.length?Math.max(0,...others.map(e=>e.y+e.height))+80:0);
+  let cursor=x+padding,maxHeight=0;
+  for(const e of selected){const scale=Math.min(width/e.width,600/e.height),w=e.width*scale,h=e.height*scale;const next={x:cursor,y:y+padding,width:w,height:h,frameId};if(Object.entries(next).some(([k,val])=>e[k]!==val)){Object.assign(e,next);e.version=(e.version||1)+1;e.versionNonce=Number.parseInt(hash({id:e.id,next}).slice(0,7),16);e.updated=Date.now();}cursor+=w+gap;maxHeight=Math.max(maxHeight,h);}
+  const bounds={x,y,width:cursor-x-gap+padding,height:maxHeight+2*padding};
+  const frame=old||{id:frameId,type:'frame',angle:0,strokeColor:'#bbb',backgroundColor:'transparent',fillStyle:'solid',strokeWidth:1,strokeStyle:'solid',roughness:0,opacity:100,groupIds:[],frameId:null,index:null,roundness:null,seed:1,version:1,versionNonce:1,isDeleted:false,boundElements:null,link:null,locked:false};
+  frame.customData??={fills:[{id:'fill-'+frameId,type:'solid',color:'#FFFFFF',opacity:100,visible:true,blendMode:'normal'}],cornerRadius:8,schemaVersion:1,__sealseekFrameTreeParentId:null};
+  if(!old||frame.name!==name||Object.entries(bounds).some(([k,val])=>frame[k]!==val)){Object.assign(frame,bounds,{name,updated:Date.now(),version:(old?.version||0)+1});}
+  if(!old)v.elements.push(frame);
+  return {content:JSON.stringify(v),changed:canonical(v)!==before,frameId,elementIds:ids,bounds,retiredElementIds:retireIds.filter(id=>v.elements.some(e=>e.id===id))};
+}
+export function verifyGrouping(before,after,{frameId,elementIds,retiredElementIds=[]}){
+  const a=JSON.parse(after),b=JSON.parse(before),frame=a.elements.find(e=>e.id===frameId&&!e.isDeleted);
+  need(frame?.type==='frame','CANVAS_SAVE_UNCERTAIN','Frame was not saved.');
+  for(const id of elementIds){const e=a.elements.find(e=>e.id===id&&!e.isDeleted),old=b.elements.find(e=>e.id===id);need(e?.frameId===frameId&&e.x>=frame.x&&e.y>=frame.y&&e.x+e.width<=frame.x+frame.width+1e-6&&e.y+e.height<=frame.y+frame.height+1e-6,'CANVAS_SAVE_UNCERTAIN','Frame membership or bounds were not saved.');need(e.fileId===old.fileId&&canonical(e.customData)===canonical(old.customData),'CANVAS_SAVE_UNCERTAIN','Media identity changed during grouping.');}
+  for(const id of retiredElementIds){const old=b.elements.find(e=>e.id===id),e=a.elements.find(e=>e.id===id);need(old?.customData?.cliTaskId?.startsWith('ic-video-')&&e?.isDeleted&&e.fileId===old.fileId&&canonical(e.customData)===canonical(old.customData),'CANVAS_SAVE_UNCERTAIN','CLI duplicate retirement was not verified.');}
+  for(const e of b.elements.filter(e=>!elementIds.includes(e.id)&&!retiredElementIds.includes(e.id)&&e.id!==frameId))need(canonical(a.elements.find(n=>n.id===e.id))===canonical(e),'CANVAS_SAVE_UNCERTAIN','Unrelated canvas content changed.');
+  return true;
+}

package/src/lifecycle.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {ROOT,META,need,exists,readJSON,newJSON,newFile,replaceOwned,stateRoot,hash,mkdir,lock,execute,Fault} from './core.mjs';
+
+export const SKILL=path.join(ROOT,'skills','infinite-canvas-video');
+export async function treeFiles(root,prefix=''){
+  const out=[];for(const e of await fs.readdir(path.join(root,prefix),{withFileTypes:true})){need(!e.isSymbolicLink(),'UNMANAGED_STATE','Skill resources must not be symbolic links.');const rel=path.posix.join(prefix,e.name);if(e.isDirectory())out.push(...await treeFiles(root,rel));else out.push(rel);}return out.sort();
+}
+const marker='.infinite-canvas-managed.json';
+const hashes=async root=>Object.fromEntries(await Promise.all((await treeFiles(root)).filter(n=>n!==marker).map(async n=>[n,hash(await fs.readFile(path.join(root,n)))])));
+export function skillTarget(agent='codex',destination){
+  need(/^[a-z][a-z0-9-]{0,63}$/.test(agent),'INVALID_ARGUMENT','Malformed Agent name.');
+  const dest=destination?path.resolve(destination):agent==='codex'?path.join(os.homedir(),'.codex','skills','infinite-canvas-video'):null;
+  need(dest,'INVALID_ARGUMENT','This Agent requires an explicit --path for its own Skill directory.');
+  return {agent,adapter:agent==='codex'?'codex':'generic',destination:dest};
+}
+export async function skillStatus(agent,destination){
+  const target=skillTarget(agent,destination),current=await hashes(SKILL);if(!await exists(target.destination))return {ok:true,...target,installed:false,current:false,version:META.version};
+  const s=await fs.lstat(target.destination);need(s.isDirectory()&&!s.isSymbolicLink(),'UNMANAGED_TARGET','Preserve the existing Skill target.');
+  const p=path.join(target.destination,marker);need(await exists(p),'UNMANAGED_TARGET','Existing Skill is not managed by this package.');const old=await readJSON(p);need(old.owner===META.name,'UNMANAGED_TARGET','Skill belongs to a different package.');
+  const actual=await hashes(target.destination),edited=Object.entries(old.hashes).filter(([k,v])=>k!=='agents/openai.yaml'&&actual[k]!==v).map(([k])=>k);
+  return {ok:true,...target,installed:true,current:old.version===META.version&&Object.entries(current).every(([k,v])=>k==='agents/openai.yaml'||actual[k]===v),edited,version:old.version,source_version:META.version,hashes:actual};
+}
+export async function installSkill(agent,destination,{failAfterCopy=false}={}){
+  const status=await skillStatus(agent,destination);need(!status.edited?.length,'LOCAL_EDITS','Managed Skill was edited; preserve it.',{files:status.edited});
+  if(status.installed&&status.current)return {...status,changed:false};
+  return lock('skill:'+status.destination,async()=>{
+    const fresh=await skillStatus(agent,destination);need(!fresh.edited?.length,'LOCAL_EDITS','Skill changed before synchronization.');
+    let backup;if(fresh.installed){backup=path.join(stateRoot(),'skill-backups',crypto.randomUUID());await mkdir(path.dirname(backup));await fs.cp(fresh.destination,backup,{recursive:true,errorOnExist:true,force:false});need(JSON.stringify(await hashes(backup))===JSON.stringify(fresh.hashes),'BACKUP_FAILED','Skill backup verification failed.');}
+    const files=await treeFiles(SKILL);const previous=new Set(fresh.installed?await treeFiles(fresh.destination):[]);
+    const previousRecord=fresh.installed?await readJSON(path.join(fresh.destination,marker)):null;
+    if(previousRecord)for(const rel of files)need(!previous.has(rel)||Object.hasOwn(previousRecord.hashes,rel),'UNMANAGED_TARGET','A new managed resource conflicts with a user-owned file.',{file:rel});
+    const customUI=fresh.installed&&fresh.hashes['agents/openai.yaml']!==(previousRecord.canonicalHashes||previousRecord.hashes)['agents/openai.yaml'];
+    await mkdir(fresh.destination);
+    try{
+      for(const rel of files){if(rel==='agents/openai.yaml'&&customUI)continue;const p=path.join(fresh.destination,rel),data=await fs.readFile(path.join(SKILL,rel));await mkdir(path.dirname(p));if(await exists(p)){const stat=await fs.lstat(p);need(stat.isFile()&&!stat.isSymbolicLink(),'UNMANAGED_TARGET','Managed file type changed.');await fs.writeFile(p,data);}else await newFile(p,data);}
+      if(failAfterCopy)throw new Fault('TEST_SYNC_FAILURE','Injected synchronization failure.');
+      const actual=await hashes(fresh.destination),canonicalHashes=await hashes(SKILL);
+      const record={owner:META.name,version:META.version,hashes:Object.fromEntries(files.map(f=>[f,actual[f]])),canonicalHashes,source:SKILL};const p=path.join(fresh.destination,marker);await replaceOwned(p,record);
+      const verified=await skillStatus(agent,destination);need(verified.current,'SKILL_SYNC_FAILED','Installed bytes differ from canonical source.');return {...verified,changed:true,backup,metadata_preserved:!!customUI};
+    }catch(e){
+      if(backup){for(const rel of await treeFiles(backup)){const p=path.join(fresh.destination,rel);await mkdir(path.dirname(p));await fs.copyFile(path.join(backup,rel),p);}for(const rel of files.filter(f=>!previous.has(f)))await fs.unlink(path.join(fresh.destination,rel)).catch(()=>{});}
+      else {for(const rel of files)await fs.unlink(path.join(fresh.destination,rel)).catch(()=>{});const dirs=[...new Set(files.map(f=>path.dirname(f)).filter(d=>d!=='.'))].sort((a,b)=>b.length-a.length);for(const rel of dirs)await fs.rmdir(path.join(fresh.destination,rel)).catch(()=>{});await fs.rmdir(fresh.destination).catch(()=>{});}
+      throw new Fault('SKILL_SYNC_FAILED','Skill synchronization failed; existing content was restored.',{backup,cause:e.code||e.message});
+    }
+  });
+}
+const cacheFile=()=>path.join(stateRoot(),'update-cache.json');
+const policyFile=()=>path.join(stateRoot(),'update-policy.json');
+export async function updatePolicy(mode){
+  let policy={owner:META.name,enabled:true};if(await exists(policyFile())){policy=await readJSON(policyFile());need(policy.owner===META.name&&typeof policy.enabled==='boolean','UNMANAGED_STATE','Preserve malformed update policy.');}
+  if(mode&&mode!=='status'){policy.enabled=mode==='on';await replaceOwned(policyFile(),policy);}return {ok:true,enabled:policy.enabled,automatic_installation:false};
+}
+export async function checkUpdate({force=false,fetcher=fetch,now=Date.now()}={}){
+  if(process.env.INFINITE_CANVAS_AUTO_UPDATE==='0'&&!force)return {enabled:false};
+  if(!force&&!(await updatePolicy()).enabled)return {enabled:false};
+  let old;if(await exists(cacheFile())){old=await readJSON(cacheFile());need(old.owner===META.name&&Number.isFinite(old.checkedAt),'UNMANAGED_STATE','Preserve malformed update cache.');if(!force&&now-old.checkedAt<(old.available===false?3600000:86400000))return {...old,cached:true};}
+  return lock('update-check',async()=>{
+    let record={owner:META.name,checkedAt:now,current:META.version,available:false};
+    try{const r=await fetcher('https://registry.npmjs.org/'+encodeURIComponent(META.name)+'/latest',{signal:AbortSignal.timeout(1500)});if(r.status===404)record={...record,published:false};else{need(r.ok,'REGISTRY_UNAVAILABLE','Registry check failed.');const d=await r.json();need(typeof d.version==='string'&&/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(d.version),'REGISTRY_UNAVAILABLE','Invalid registry version.');record={...record,available:true,published:true,latest:d.version,update_available:d.version!==META.version};}}
+    catch{record={...record,reason:'offline-or-timeout'};}
+    await replaceOwned(cacheFile(),record);return record;
+  });
+}
+export async function automaticCheck(){try{const r=await checkUpdate();if(r.update_available&&!r.cached)process.stderr.write(JSON.stringify({update_available:true,current:META.version,latest:r.latest,installation:'explicit update install --yes required'})+'\n');}catch(e){process.stderr.write(JSON.stringify({update_check:'unavailable',code:e.code||'UPDATE_BUSY'})+'\n');}}
+export async function installUpdate({yes,agent,destination}={}){
+  need(yes,'PERMISSION_REQUIRED','Package update requires --yes.');
+  need(!await exists(path.join(ROOT,'.git')),'SOURCE_CHECKOUT','This is a Git-owned source checkout; update it through its repository.');
+  const version=await checkUpdate({force:true});need(version.published&&version.available,'REGISTRY_UNAVAILABLE','A published version is unavailable.');
+  if(version.latest===META.version){const skill=agent?await installSkill(agent,destination):null;return {ok:true,changed:!!skill?.changed,version:META.version,skill};}
+  const backup=path.join(stateRoot(),'package-backups',crypto.randomUUID());await mkdir(path.dirname(backup));await fs.cp(ROOT,backup,{recursive:true,errorOnExist:true,force:false});
+  try{
+    await execute(process.platform==='win32'?'npm.cmd':'npm',['install','--global',META.name+'@'+version.latest],{timeout:180000,maxBuffer:1024*1024});
+    const entry=process.platform==='win32'?'infinite-canvas.cmd':'infinite-canvas';const r=JSON.parse((await execute(entry,['version','--json'],{timeout:15000})).stdout);need(r.version===version.latest,'UPDATE_VERIFY_FAILED','Installed CLI version differs.');
+    let skill;if(agent){const args=['skill','update','--agent',agent,'--json',...(destination?['--path',destination]:[])];skill=JSON.parse((await execute(entry,args,{timeout:30000})).stdout);need(skill.ok,'SKILL_SYNC_FAILED','Package upgraded but selected Skill did not synchronize.');}
+    return {ok:true,version:r.version,changed:true,backup,skill};
+  }catch(e){throw new Fault('UPDATE_FAILED','Update did not verify. The complete previous package is backed up.',{backup,cause:e.code||e.message});}
+}

package/src/media-cli.mjs

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import {execute,newJSON,readJSON,exists,canonical,need,Fault} from './core.mjs';
+
+export class MediaCLI {
+  constructor(){this.bin=process.env.INFINITE_CANVAS_MEDIA_BIN||'sealseek-media';}
+  async call(args){
+    try{const {stdout}=await execute(this.bin,[...args,'--json'],{timeout:90000,maxBuffer:32*1024*1024,env:{...process.env,SEALSEEK_MEDIA_AUTO_UPDATE:'0'}});const r=JSON.parse(stdout);need(r.ok!==false,r.error?.code||'MEDIA_API_FAILED',r.error?.message||'Canvas operation failed.');return r;}
+    catch(e){if(e instanceof Fault)throw e;let r;try{r=JSON.parse(e.stdout);}catch{}throw new Fault(r?.error?.code||'MEDIA_CLI_FAILED',r?.error?.message||'sealseek-media could not complete this operation.',{command:args.slice(0,2),cause:e.code});}
+  }
+  get(canvas){return this.call(['canvas','get',canvas]);}
+  upload(file){return this.call(['image','upload',file,'--submit']);}
+  async add(canvas,media,directory){const file=path.join(directory,`import-${media.id}.json`);if(await exists(file))need(canonical(await readJSON(file))===canonical(media),'IDEMPOTENCY_CONFLICT','Import record differs.');else await newJSON(file,media);return this.call(['canvas','add',canvas,'--media',file,'--submit']);}
+}

package/src/state.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {imageSize} from 'image-size';
+import {META,stateRoot,newFile,newJSON,readJSON,replaceOwned,exists,need,hash,safeId,httpsUrl,mkdir} from './core.mjs';
+
+export const jobDir=id=>path.join(stateRoot(),'jobs',safeId(id));
+export const jobFile=id=>path.join(jobDir(id),'job.json');
+export async function getJob(id){const j=await readJSON(jobFile(id));need(j.owner===META.name&&j.id===id,'UNMANAGED_STATE','Unrecognized task.');return j;}
+export async function saveJob(j){j.updatedAt=new Date().toISOString();await replaceOwned(jobFile(j.id),j);return j;}
+export async function prepareInput({canvas,prompt,references,output}){
+  safeId(canvas,'canvas ID');need(typeof prompt==='string'&&prompt.trim()&&prompt.length<=20000,'INVALID_INPUT','Provide a non-empty prompt of at most 20000 characters.');
+  need(Array.isArray(references)&&references.length>0&&references.length<=20,'INVALID_INPUT','Provide 1–20 ordered reference images.');
+  const refs=[];for(const value of references){
+    need(typeof value==='string'&&value,'INVALID_INPUT','Reference must be a path or HTTPS URL.');
+    if(/^https:/i.test(value)){httpsUrl(value);refs.push({source:value,url:value});continue;}
+    const file=path.resolve(value),stat=await fs.stat(file);need(stat.isFile()&&stat.size>0&&stat.size<=30*1024*1024,'INVALID_REFERENCE','Image is missing, empty or larger than 30 MiB.');
+    const b=await fs.readFile(file),dim=imageSize(b);need(['png','jpg','webp'].includes(dim.type),'INVALID_REFERENCE','Use PNG, JPEG or WebP reference images.');
+    refs.push({source:file,file,sha256:hash(b),bytes:b.length,width:dim.width,height:dim.height,extension:dim.type==='jpg'?'jpg':dim.type});
+  }
+  return {canvasId:canvas,prompt,references:refs,output:output?path.resolve(output):null};
+}
+export async function createJob(input,{requestId,newRequest=false}={}){
+  need(!requestId||!newRequest,'INVALID_INPUT','Use either request-id or new, not both.');
+  const digest=hash({...input,output:undefined,references:input.references.map(r=>({sha256:r.sha256,url:r.url}))});
+  requestId=requestId||(newRequest?crypto.randomUUID():digest);safeId(requestId,'request ID');
+  const index=path.join(stateRoot(),'requests',hash(requestId)+'.json');
+  if(await exists(index)){const old=await readJSON(index);need(old.owner===META.name,'UNMANAGED_STATE','Unrecognized request record.');need(old.digest===digest,'IDEMPOTENCY_CONFLICT','Request ID is associated with different inputs.');const job=await getJob(old.id);need(job.input.output===input.output,'IDEMPOTENCY_CONFLICT','Existing request uses a different output directory; its original task is preserved.');return {job,reused:true};}
+  const id=crypto.randomUUID();await mkdir(jobDir(id));
+  const job={owner:META.name,id,requestId,digest,createdAt:new Date().toISOString(),status:'queued',stage:'created',input,referenceElements:[],references:[],warnings:[]};
+  await newJSON(jobFile(id),job);
+  try{await newJSON(index,{owner:META.name,id,digest});}catch(e){if(['EEXIST','OUTPUT_EXISTS'].includes(e.code)){const old=await readJSON(index);need(old.owner===META.name&&old.digest===digest,'IDEMPOTENCY_CONFLICT','Concurrent request conflict.');const existing=await getJob(old.id);need(existing.input.output===input.output,'IDEMPOTENCY_CONFLICT','Concurrent request uses another output directory.');return {job:existing,reused:true};}throw e;}
+  return {job,reused:false};
+}
+export async function cacheReferences(job){
+  for(let i=0;i<job.input.references.length;i++){
+    if(job.references[i]?.file)continue;
+    const ref=job.input.references[i];let bytes;
+    if(ref.file){bytes=await fs.readFile(ref.file);need(hash(bytes)===ref.sha256,'REFERENCE_CHANGED','A reference changed after preparation.');}
+    else{const r=await fetch(httpsUrl(ref.url),{signal:AbortSignal.timeout(30000),redirect:'error'});need(r.ok,'REFERENCE_DOWNLOAD_FAILED','Could not download the reference.');const max=30*1024*1024;need(Number(r.headers.get('content-length')||0)<=max,'INVALID_REFERENCE','Reference exceeds 30 MiB.');const chunks=[];let size=0;for await(const c of r.body){size+=c.length;need(size<=max,'INVALID_REFERENCE','Reference exceeds 30 MiB.');chunks.push(c);}bytes=Buffer.concat(chunks);}
+    const dim=imageSize(bytes);need(['png','jpg','webp'].includes(dim.type),'INVALID_REFERENCE','Unsupported reference format.');
+    const file=path.join(jobDir(job.id),'references',`${String(i+1).padStart(2,'0')}-reference.${dim.type==='jpg'?'jpg':dim.type}`);
+    if(await exists(file))need(hash(await fs.readFile(file))===hash(bytes),'REFERENCE_CHANGED','Cached reference differs.');else await newFile(file,bytes);
+    job.references[i]={...ref,file,sha256:hash(bytes),width:dim.width,height:dim.height,bytes:bytes.length};await saveJob(job);
+  }
+}
+export function summary(j){return {ok:j.status!=='failed'&&j.status!=='uncertain',task_id:j.id,status:j.status,stage:j.stage,canvas_id:j.input.canvasId,session_id:j.sessionId||null,run_id:j.runId||null,frame_id:j.frameId||null,reference_element_ids:j.referenceElements||[],video_element_id:j.videoElementId||null,artifacts:j.artifacts||[],result:j.result?{reference_count:j.result.referenceCount,billing:j.result.billing}:null,error:j.error||null,warnings:j.warnings||[],created_at:j.createdAt,updated_at:j.updatedAt};}

package/src/sync-contract.mjs

@@ -0,0 +1,13 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {ROOT} from './core.mjs';
+import {manifest} from './contracts.mjs';
+const target=path.join(ROOT,'capabilities.json');
+const stat=await fs.lstat(target);
+if(!stat.isFile()||stat.isSymbolicLink())throw Error('Unmanaged capability manifest');
+const old=await fs.readFile(target);
+const backup=target+'.'+crypto.randomUUID()+'.backup';
+await fs.copyFile(target,backup,fs.constants.COPYFILE_EXCL);
+if(!(await fs.readFile(backup)).equals(old))throw Error('Manifest backup failed');
+await fs.writeFile(target,JSON.stringify(manifest,null,2)+'\n');

package/src/workflow.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {spawn} from 'node:child_process';
+import {ROOT,META,need,hash,lock,sleep,newFile,newJSON,exists,httpsUrl,redact,alive,execute} from './core.mjs';
+import {getJob,saveJob,jobDir,jobFile,cacheReferences,summary} from './state.mjs';
+import {BrowserDriver} from './browser.mjs';
+import {MediaCLI} from './media-cli.mjs';
+import {findVideo,groupIntoFrame,comparableUrl} from './frame.mjs';
+
+export function selectResult(history,referenceUrls=[]){
+  const bubbles=history?.bubbles;need(Array.isArray(bubbles),'RESULT_UNAVAILABLE','Conversation history is unavailable.');
+  need(bubbles.filter(b=>b.role==='user').length===1,'CONTEXT_NOT_CLEAN','Task conversation has more than one user message.');
+  const videos=bubbles.filter(b=>b.type==='video').map(b=>({bubble:b,url:b.videoParams?.videoUrl||b.content})).filter(v=>typeof v.url==='string'&&/^https:/.test(v.url));
+  const unique=[...new Map(videos.map(v=>[v.url,v])).values()];need(unique.length===1,'RESULT_UNAVAILABLE','Expected exactly one video in this conversation.',{count:unique.length});
+  const {bubble,url}=unique[0],p=bubble.videoParams||{},refs=p.referenceImageUrls||p.referenceImages?.map(r=>typeof r==='string'?r:r.url)||bubble.referenceImageUrls||[];
+  need(!refs.length||refs.length===referenceUrls.length&&referenceUrls.every(u=>refs.some(r=>comparableUrl(u)===comparableUrl(r))),'REFERENCE_MISMATCH','Returned reference metadata differs from the submitted images.');
+  return {url,params:p,referenceCount:refs.length,referenceVerified:refs.length>0,bubbleId:bubble.id,toolCallId:bubble.toolCallId,billing:bubbles.map(b=>b.totalPoints??b.billingXidou).filter(v=>v!=null).at(-1)??null};
+}
+export async function spawnWorker(id){
+  const log=path.join(jobDir(id),'worker-'+crypto.randomUUID()+'.log');const file=await fs.open(log,'wx',0o600);
+  try{const child=spawn(process.execPath,[path.join(ROOT,'bin/infinite-canvas.mjs'),'_worker',id],{detached:true,stdio:['ignore',file.fd,file.fd],env:process.env});await new Promise((r,j)=>{child.once('spawn',r);child.once('error',j)});child.unref();return child.pid;}finally{await file.close();}
+}
+async function importReferences(job,driver,media){
+  const api=await media.get(job.input.canvasId);need(api.canvas_id===job.input.canvasId,'BOARD_MISMATCH','API and browser board IDs differ.');
+  const web=await driver.getBoard();need(String(web.id)===api.canvas_id,'BOARD_MISMATCH','API and browser board IDs differ.');
+  for(let i=0;i<job.references.length;i++){
+    const ref=job.references[i],key='ic-ref-'+job.id+'-'+i;
+    if(job.referenceElements[i]){const current=await media.get(job.input.canvasId);need(current.elements.some(e=>e.id===job.referenceElements[i]&&!e.isDeleted),'ELEMENT_NOT_FOUND','A previously imported reference was deleted.');continue;}
+    if(!ref.uploadedUrl){ref.uploadedUrl=(await media.upload(ref.file)).url;need(ref.uploadedUrl,'UPLOAD_FAILED','Reference upload returned no URL.');await saveJob(job);}
+    let existing=(await media.get(job.input.canvasId)).elements.filter(e=>!e.isDeleted&&e.customData?.cliTaskId===key);
+    if(!existing.length){const spec={id:key,kind:'image',urls:[ref.uploadedUrl],ratio:ref.width+':'+ref.height};await driver.helperMutation(()=>media.add(job.input.canvasId,spec,jobDir(job.id)));existing=(await media.get(job.input.canvasId)).elements.filter(e=>!e.isDeleted&&e.customData?.cliTaskId===key);}
+    need(existing.length===1,'ELEMENT_AMBIGUOUS','Reference import identity is ambiguous.');job.referenceElements[i]=existing[0].id;await saveJob(job);
+  }
+}
+export async function recoverNative(job,driver){
+  if(job.runId)return;
+  need(job.sessionId,'SUBMISSION_UNCERTAIN','No session ID was captured. Inspect the webpage; this task will not resend.');
+  const runs=await driver.runs(job.sessionId);const list=Array.isArray(runs)?runs:runs.runs;
+  need(Array.isArray(list)&&list.length===1&&list[0].run_id,'SUBMISSION_UNCERTAIN','Unable to identify one native run.');job.runId=list[0].run_id;job.stage='running';await saveJob(job);
+}
+async function follow(job,driver,{budgetMs=3600000}={}){
+  const end=Date.now()+budgetMs;while(Date.now()<end){
+    let run;try{run=await driver.run(job.sessionId,job.runId);}catch(e){job.lastReadError=redact(e);await sleep(1500);continue;}job.remoteStatus=run.status;
+    if(run.status==='success'){job.result=selectResult(await driver.history(job.sessionId),job.referenceUrls);job.stage='generated';job.status='running';if(!job.result.referenceVerified)job.warnings.push('The provider did not expose returned reference metadata.');await saveJob(job);return;}
+    need(!['error','failed','timeout','interrupted','cancelled'].includes(run.status),'PROVIDER_FAILURE','Native Agent run did not succeed.',{status:run.status,reason:run.error?.message||run.error||null});
+    await sleep(5000);
+  }
+  job.status='waiting';await saveJob(job);throw Object.assign(Error('Native run is still active; resume this task without resending.'),{code:'MONITOR_WINDOW_ENDED'});
+}
+async function downloadResult(job){
+  const directory=job.input.output||path.join(jobDir(job.id),'output');const file=path.join(directory,job.id+'.mp4');
+  if(job.artifacts?.[0]){need(await exists(file)&&hash(await fs.readFile(file))===job.artifacts[0].sha256,'OUTPUT_CHANGED','Saved video changed.');return;}
+  const response=await fetch(httpsUrl(job.result.url),{signal:AbortSignal.timeout(120000),redirect:'error'});need(response.ok,'DOWNLOAD_FAILED','Video download failed.');
+  need(!/text|json/.test(response.headers.get('content-type')||''),'OUTPUT_CONTRACT_FAILED','Video URL returned text.');
+  const chunks=[];let size=0;for await(const c of response.body){size+=c.length;need(size<=1024*1024*1024,'OUTPUT_CONTRACT_FAILED','Video exceeds the download limit.');chunks.push(c);}const data=Buffer.concat(chunks);need(data.length>0,'OUTPUT_CONTRACT_FAILED','Video is empty.');
+  if(await exists(file))need(hash(await fs.readFile(file))===hash(data),'OUTPUT_EXISTS','Preserve a different existing output file.');else await newFile(file,data);
+  let inspect;try{const r=await execute('ffprobe',['-v','error','-show_entries','stream=codec_type,width,height,duration:format=duration,size','-of','json',file],{timeout:20000});inspect=JSON.parse(r.stdout);need(inspect.streams?.some(s=>s.codec_type==='video'&&s.width>0&&s.height>0),'OUTPUT_CONTRACT_FAILED','Downloaded file has no video stream.');}catch(e){if(e.code!=='ENOENT')throw e;job.warnings.push('ffprobe is unavailable; dimensions and duration are unverified.');}
+  job.artifacts=[{path:file,bytes:data.length,sha256:hash(data),inspect:inspect||null}];await saveJob(job);
+}
+function resolveVideoMatches(job,matches){
+  job.duplicateVideoIds=[];
+  if(matches.length<=1)return matches;
+  const native=matches.filter(e=>e.customData?.sessionId===job.sessionId&&!e.customData?.cliTaskId),owned=matches.filter(e=>e.customData?.cliTaskId==='ic-video-'+job.runId);
+  need(native.length===1&&native.length+owned.length===matches.length,'VIDEO_ELEMENT_AMBIGUOUS','Multiple matching video elements exist; preserve unrelated nodes.');
+  job.duplicateVideoIds=owned.map(e=>e.id);return native;
+}
+async function ensureVideo(job,driver,media,{settle=()=>sleep(1500)}={}){
+  let board=await media.get(job.input.canvasId),matches=findVideo(board.elements,job.result.url);
+  job.duplicateVideoIds=[];
+  for(let i=0;i<8&&!matches.length;i++){await settle();board=await media.get(job.input.canvasId);matches=findVideo(board.elements,job.result.url);}
+  matches=resolveVideoMatches(job,matches);
+  if(!matches.length){
+    const spec={id:'ic-video-'+job.runId,kind:'video',urls:[job.result.url],ratio:job.result.params.aspectRatio||'16:9',generationParams:{...job.result.params,referenceImageUrls:job.referenceUrls}};
+    await driver.helperMutation(()=>media.add(job.input.canvasId,spec,jobDir(job.id)));board=await media.get(job.input.canvasId);matches=findVideo(board.elements,job.result.url);
+    for(let i=0;i<8&&!matches.length;i++){await settle();board=await media.get(job.input.canvasId);matches=findVideo(board.elements,job.result.url);}
+    matches=resolveVideoMatches(job,matches);
+  }
+  need(matches.length===1,'CANVAS_SYNC_PENDING','Video was generated, but its canvas node is unresolved.');job.videoElementId=matches[0].id;await saveJob(job);
+}
+export async function processJob(id,{driver=new BrowserDriver(),media=new MediaCLI(),budgetMs,download=downloadResult,settleVideo}={}){
+  let job=await getJob(id);
+  return lock('job:'+id,async()=>{
+    job=await getJob(id);if(job.status==='succeeded')return summary(job);
+    job.pid=process.pid;job.status='running';delete job.error;await saveJob(job);
+    try{
+      await driver.connect(job.input.canvasId);
+      if(!['sending','running','generated','framing','complete'].includes(job.stage)){
+        const compose=async()=>{
+        await cacheReferences(job);job.stage='references';await saveJob(job);
+        await importReferences(job,driver,media);job.stage='imported';await saveJob(job);
+        await driver.newConversation();await driver.attach(job.references.map(r=>r.file));
+        job.stage='sending';job.sendIntentAt=new Date().toISOString();await saveJob(job);
+        await driver.send(job.input.prompt,job.references.map(r=>r.file),async context=>{Object.assign(job,context);await saveJob(job);});job.stage='running';await saveJob(job);
+        };await (driver.composerLock?driver.composerLock(compose):compose());
+      }
+      if(['sending','running'].includes(job.stage)){await recoverNative(job,driver);await follow(job,driver,{budgetMs});}
+      await download(job);job.stage='framing';await saveJob(job);
+      await ensureVideo(job,driver,media,{settle:settleVideo});
+      job.frameId='ic-frame-'+job.id;await saveJob(job);
+      const grouped=await driver.saveFrame(content=>groupIntoFrame(content,{ids:[...job.referenceElements,job.videoElementId],frameId:job.frameId,name:'Video '+job.id.slice(0,8),retireIds:job.duplicateVideoIds||[]}),jobDir(job.id));
+      job.frame={id:grouped.frameId,elementIds:grouped.elementIds,bounds:grouped.bounds};job.stage='complete';job.status='succeeded';await saveJob(job);
+    }catch(e){job.error=redact(e);job.status=e.code==='PROVIDER_FAILURE'?'failed':e.code==='MONITOR_WINDOW_ENDED'?'waiting':job.stage==='sending'?'uncertain':job.result?'canvas_pending':job.runId?'waiting':'failed';await saveJob(job);}
+    finally{delete job.pid;await saveJob(job);await driver.close();}
+    return summary(job);
+  });
+}
+export async function resumeJob(id){const job=await getJob(id);if(job.status==='succeeded'||job.pid&&alive(job.pid))return {...summary(job),reused:true};await spawnWorker(id);return {...summary(job),resuming:true};}
+export async function syncJob(id,{spawn=spawnWorker}={}){const job=await lock('job:'+id,async()=>{const j=await getJob(id);need(j.result?.url&&j.artifacts?.length,'RESULT_UNAVAILABLE','Canvas synchronization requires an existing generated video.');need(!j.pid||!alive(j.pid),'BUSY','The task already has an active worker.');j.stage='framing';j.status='canvas_pending';delete j.error;await saveJob(j);return j;});await spawn(id);return {...summary(job),syncing:true};}
+export async function waitJob(id,seconds=30){need(Number.isInteger(seconds)&&seconds>=1&&seconds<=60,'INVALID_ARGUMENT','Wait timeout must be 1–60 seconds.');const end=Date.now()+seconds*1000;let j;while(Date.now()<end){j=await getJob(id);if(!['queued','running'].includes(j.status))break;await sleep(500);}return summary(j||await getJob(id));}