@wji.ai/cli 0.1.0

package/dist/commands/canvas.js

@@ -0,0 +1,915 @@
+import { Command } from 'commander';
+import { WjiClient } from '../core/client.js';
+import { confirm, parseKeyValues, readValue } from '../core/prompt.js';
+import { color, detail, info, isJsonMode, printJson, render, success, table, truncate, warn } from '../core/output.js';
+import { pollHistory, reportHistory, resolveAssets } from './gen.js';
+import { fetchModels } from './model.js';
+/**
+ * Infinite Canvas over the plain fsnode API.
+ *
+ * A canvas is a folder (`workspace-v2/canvas`). Each node is a child file with
+ * mimetype `canvas/node/<kind>`, and each connection is a child file with
+ * mimetype `canvas/edge` whose content is `{fromNodeId, toNodeId, …}`. Edges
+ * into a media generate node are its references, numbered per kind in edge
+ * order (`@image1`, `@image2`, …).
+ *
+ * The browser can "link" a canvas (link button in the canvas top bar). That
+ * stores the open workspace, canvas and selection on the user for 5 minutes,
+ * so these commands default to the linked canvas and can read what is
+ * selected. Writes go straight to the API; an open canvas picks them up
+ * through its normal live sync.
+ */
+const NODE_PREFIX = 'canvas/node/';
+const EDGE_MIMETYPE = 'canvas/edge';
+const CANVAS_MIMETYPE = 'workspace-v2/canvas';
+const CANVASES_MIMETYPE = 'workspace-v2/canvases';
+const CREATABLE_KINDS = ['text', 'title', 'comment', 'image', 'video', 'audio'];
+const MEDIA_KINDS = new Set(['image', 'video', 'audio']);
+const TEXT_KINDS = new Set(['text', 'title', 'comment']);
+/** Default names the canvas UI shows localized. */
+const DEFAULT_NAMES = {
+    text: '文本',
+    title: '标题',
+    comment: '备注',
+    image: '图片',
+    video: '视频',
+    audio: '音频',
+};
+/** The canvas lays media out on a 250px short side; text nodes are wider. */
+const MEDIA_BASE = 250;
+const PLACE_GAP = 80;
+const PENDING = 0;
+const idOf = (value) => value == null ? undefined : typeof value === 'string' ? value : value.id;
+function toList(result) {
+    return Array.isArray(result) ? result : result?.data || [];
+}
+// ── loading ─────────────────────────────────────────────────────────────────
+async function linkedState(client) {
+    const res = await client.get('/canvas-link');
+    return res?.linked ? res.state : null;
+}
+/** `--canvas` wins; otherwise the canvas linked from the browser. */
+async function resolveCanvasId(client, explicit) {
+    if (explicit)
+        return explicit;
+    const state = await linkedState(client);
+    if (state?.canvasId)
+        return String(state.canvasId);
+    throw new Error('No canvas. Pass --canvas <id>, or open the canvas in the browser and press the link button in its top bar.');
+}
+async function loadCanvas(client, canvasId) {
+    // getFresh: read-merge-write must not see the 10s server cache
+    const folder = await client.getFresh(`/fsnode/list/${canvasId}`);
+    if (folder?.mimetype !== CANVAS_MIMETYPE) {
+        throw new Error(`${canvasId} is not a canvas (mimetype ${folder?.mimetype || 'none'})`);
+    }
+    const children = toList(await client.getFresh(`/fsnode/list/${canvasId}/children`, { limit: -1 }));
+    const nodes = [];
+    const edges = [];
+    for (const raw of children) {
+        const mimetype = String(raw.mimetype || '');
+        if (mimetype === EDGE_MIMETYPE) {
+            edges.push({
+                id: raw.id,
+                sort: Number(raw.sort || 0),
+                fromNodeId: String(raw.content?.fromNodeId || ''),
+                toNodeId: String(raw.content?.toNodeId || ''),
+                content: raw.content || {},
+            });
+        }
+        else if (mimetype.startsWith(NODE_PREFIX)) {
+            nodes.push({
+                id: raw.id,
+                kind: mimetype.slice(NODE_PREFIX.length),
+                name: raw.name || '',
+                sort: Number(raw.sort || 0),
+                file: idOf(raw.file),
+                content: raw.content || {},
+                raw,
+            });
+        }
+    }
+    const assetIds = [...new Set(nodes.map((n) => n.file).filter(Boolean))];
+    const assets = new Map();
+    if (assetIds.length) {
+        for (const asset of await client.checkAssetStatus(assetIds))
+            assets.set(asset.id, asset);
+    }
+    return {
+        id: folder.id,
+        name: folder.name,
+        workspaceId: idOf(folder.workspace) || idOf(folder.root) || '',
+        nodes,
+        edges,
+        byId: new Map(nodes.map((n) => [n.id, n])),
+        assets,
+    };
+}
+function requireNode(canvas, id) {
+    const node = canvas.byId.get(id);
+    if (!node)
+        throw new Error(`Node ${id} is not on canvas "${canvas.name}" (${canvas.id})`);
+    return node;
+}
+/** Incoming edges in the order the canvas numbers them: sort, then id. */
+function referencesOf(canvas, node) {
+    const refs = canvas.edges
+        .filter((e) => e.toNodeId === node.id && canvas.byId.has(e.fromNodeId))
+        .sort((a, b) => a.sort - b.sort || a.id.localeCompare(b.id));
+    const counts = {};
+    return refs.map((edge) => {
+        const from = canvas.byId.get(edge.fromNodeId);
+        counts[from.kind] = (counts[from.kind] || 0) + 1;
+        return {
+            edgeId: edge.id,
+            nodeId: from.id,
+            kind: from.kind,
+            name: from.name,
+            label: edge.content.referenceLabel || `@${from.kind}${counts[from.kind]}`,
+            frameSlot: edge.content.videoFrameSlot,
+        };
+    });
+}
+function describe(canvas, node) {
+    const asset = node.file ? canvas.assets.get(node.file) : undefined;
+    const generate = node.content.generate;
+    const pending = asset && asset.status === PENDING && !asset.error;
+    return {
+        id: node.id,
+        kind: node.kind,
+        name: node.name,
+        position: node.content.position,
+        mode: MEDIA_KINDS.has(node.kind) ? node.content.mode || 'display' : undefined,
+        text: TEXT_KINDS.has(node.kind) ? node.content.text ?? '' : undefined,
+        assetId: node.file,
+        url: asset?.url || undefined,
+        assetType: asset?.type,
+        status: generate?.historyId ? (pending ? 'generating' : asset?.error ? 'failed' : asset?.url ? 'done' : 'pending') : undefined,
+        error: asset?.error?.message || asset?.error || undefined,
+        generate,
+        references: referencesOf(canvas, node),
+        outgoing: canvas.edges.filter((e) => e.fromNodeId === node.id).map((e) => e.toNodeId),
+    };
+}
+// ── models ──────────────────────────────────────────────────────────────────
+async function findModel(client, kind, name, workspaceId) {
+    const rows = await fetchModels(client, { features: [kind], workspace: workspaceId });
+    const usable = rows.filter((m) => m.enabled !== false);
+    const model = usable.find((m) => m.nickname === name) ?? usable.find((m) => m.name === name);
+    if (!model) {
+        throw new Error(`No ${kind} model "${name}". See \`wji models list --feature ${kind}\`.`);
+    }
+    return model;
+}
+/**
+ * Fill and validate generate settings the way the canvas generate panel does
+ * (shared/generate/formDefaults.ts): ratio from the model's list, resolution
+ * from `form.other.resolution`, other params from their defaults, and unknown
+ * params dropped.
+ */
+function applyModelDefaults(model, kind, generate, opts) {
+    const form = model.form || {};
+    const other = form.other || {};
+    const next = { ...generate, model: model.nickname || model.name };
+    const ratios = form.aspectRatio || [];
+    if (kind !== 'audio' && ratios.length) {
+        if (next.ratio && !ratios.includes(next.ratio)) {
+            if (opts.explicit.has('ratio')) {
+                throw new Error(`${next.model} does not support ratio ${next.ratio}. Use one of: ${ratios.join(' ')}`);
+            }
+            next.ratio = undefined;
+        }
+        if (!next.ratio) {
+            next.ratio = opts.workspaceRatio && ratios.includes(opts.workspaceRatio) ? opts.workspaceRatio : ratios[0];
+        }
+    }
+    const resField = other.resolution;
+    if (resField?.options?.length) {
+        const valid = resField.options.map((o) => String(o.value));
+        if (next.resolution && !valid.includes(String(next.resolution))) {
+            if (opts.explicit.has('resolution')) {
+                throw new Error(`${next.model} resolution must be one of: ${valid.join(' ')}`);
+            }
+            next.resolution = undefined;
+        }
+        if (!next.resolution)
+            next.resolution = String(resField.default ?? valid[0]);
+    }
+    const durationForm = form.video?.duration;
+    if (kind === 'video' && durationForm?.enable) {
+        if (next.duration != null) {
+            const d = Number(next.duration);
+            if (d < durationForm.min || d > durationForm.max) {
+                throw new Error(`${next.model} duration must be ${durationForm.min}–${durationForm.max}s`);
+            }
+        }
+        else {
+            next.duration = durationForm.default;
+        }
+    }
+    const values = {};
+    for (const [key, value] of Object.entries(next.values || {})) {
+        if (key in other && key !== 'resolution')
+            values[key] = value;
+        else if (opts.explicit.has(`values.${key}`))
+            warn(`${next.model} has no parameter "${key}" — ignored`);
+    }
+    for (const [key, field] of Object.entries(other)) {
+        if (key === 'resolution')
+            continue;
+        const current = values[key];
+        const empty = current === undefined || current === null || current === '';
+        if (empty && field.default !== undefined)
+            values[key] = field.default;
+        if (field.type === 'select' && field.options?.length) {
+            const valid = field.options.map((o) => o.value);
+            if (!empty && !valid.includes(current)) {
+                if (opts.explicit.has(`values.${key}`)) {
+                    throw new Error(`${next.model} parameter ${key} must be one of: ${valid.join(' ')}`);
+                }
+                values[key] = field.default ?? valid[0];
+            }
+        }
+    }
+    // An explicit duration is ignored while auto-duration is on, so turn it off.
+    if (kind === 'video' && opts.explicit.has('duration') && 'autoDuration' in other && !opts.explicit.has('values.autoDuration')) {
+        values.autoDuration = false;
+    }
+    next.values = values;
+    if (next.improvePromptEnabled === undefined)
+        next.improvePromptEnabled = false;
+    return next;
+}
+// ── writes ──────────────────────────────────────────────────────────────────
+/** Short side 250, like the canvas; text-ish nodes use a typical card size. */
+function estimateSize(canvas, node) {
+    if (!MEDIA_KINDS.has(node.kind))
+        return { width: 320, height: 200 };
+    const ratioText = node.content.mode === 'generate' ? node.content.generate?.ratio : undefined;
+    const asset = node.file ? canvas.assets.get(node.file) : undefined;
+    let ratio = node.kind === 'video' ? 16 / 9 : 1;
+    if (asset?.width && asset?.height)
+        ratio = asset.width / asset.height;
+    else if (ratioText && /^\d+(\.\d+)?:\d+(\.\d+)?$/.test(ratioText)) {
+        const [w, h] = ratioText.split(':').map(Number);
+        ratio = w / h;
+    }
+    if (node.kind === 'audio')
+        ratio = 1;
+    return ratio >= 1
+        ? { width: Math.round(MEDIA_BASE * ratio), height: MEDIA_BASE }
+        : { width: MEDIA_BASE, height: Math.round(MEDIA_BASE / ratio) };
+}
+/**
+ * Right of the anchor nodes, top-aligned (else right of everything), then
+ * pushed down past any node already sitting there.
+ */
+function placeNear(canvas, anchors, size) {
+    const pool = anchors.length ? anchors : canvas.nodes;
+    if (!pool.length)
+        return { x: 0, y: 0 };
+    let right = -Infinity;
+    let top = Infinity;
+    for (const node of pool) {
+        const p = node.content.position || { x: 0, y: 0 };
+        right = Math.max(right, Number(p.x) + estimateSize(canvas, node).width);
+        top = Math.min(top, Number(p.y));
+    }
+    const x = Math.round(right + PLACE_GAP);
+    let y = Math.round(top);
+    for (let guard = 0; guard < 200; guard++) {
+        const hit = canvas.nodes.find((node) => {
+            const p = node.content.position || { x: 0, y: 0 };
+            const s = estimateSize(canvas, node);
+            return x < p.x + s.width && x + size.width > p.x && y < p.y + s.height && y + size.height > p.y;
+        });
+        if (!hit)
+            break;
+        y = Math.round(Number(hit.content.position?.y || 0) + estimateSize(canvas, hit).height + PLACE_GAP);
+    }
+    return { x, y };
+}
+function usesFrameSlots(model) {
+    const support = model?.form?.video?.support || [];
+    return { start: support.includes('start'), end: support.includes('end') };
+}
+async function createEdge(client, canvas, fromId, toId, opts = {}) {
+    const from = requireNode(canvas, fromId);
+    const to = requireNode(canvas, toId);
+    if (from.id === to.id)
+        throw new Error('A node cannot reference itself');
+    if (canvas.edges.some((e) => e.fromNodeId === from.id && e.toNodeId === to.id)) {
+        throw new Error(`${from.id} is already connected to ${to.id}`);
+    }
+    const content = {
+        fromNodeId: from.id,
+        toNodeId: to.id,
+        sourceHandle: 'right',
+        targetHandle: 'left',
+    };
+    // First/last-frame video models take connected images as frame slots, in order.
+    if (opts.frameModel && to.kind === 'video' && from.kind === 'image') {
+        const support = usesFrameSlots(opts.frameModel);
+        const taken = new Set(referencesOf(canvas, to).map((r) => r.frameSlot).filter(Boolean));
+        if (support.start && !taken.has('start'))
+            content.videoFrameSlot = 'start';
+        else if (support.end && !taken.has('end'))
+            content.videoFrameSlot = 'end';
+    }
+    const raw = await client.post('/fsnode/create', {
+        name: '连线',
+        type: 'file',
+        mimetype: EDGE_MIMETYPE,
+        parent: canvas.id,
+        content,
+        sort: 0,
+    });
+    const edge = { id: raw.id, sort: 0, fromNodeId: from.id, toNodeId: to.id, content };
+    canvas.edges.push(edge);
+    return edge;
+}
+async function patchNode(client, node, body) {
+    return client.patch(`/fsnode/list/${node.id}`, body);
+}
+// ── output ──────────────────────────────────────────────────────────────────
+function summary(n) {
+    if (n.text !== undefined)
+        return String(n.text).replace(/\s+/g, ' ');
+    if (n.mode === 'generate') {
+        const g = n.generate || {};
+        const state = n.status === 'done' ? color.green('done') : n.status === 'failed' ? color.red('failed') : n.status ? color.yellow(n.status) : '';
+        return [state, [g.model, g.ratio, g.duration && `${g.duration}s`].filter(Boolean).join(' '), g.prompt && `"${g.prompt}"`]
+            .filter(Boolean)
+            .join(' · ');
+    }
+    return n.url || n.assetId || '';
+}
+function nodeTable(rows) {
+    table(rows, [
+        { header: 'id', value: (n) => n.id },
+        { header: 'kind', value: (n) => (n.mode === 'generate' ? `${n.kind}*` : n.kind) },
+        { header: 'name', value: (n) => truncate(n.name, 20) },
+        { header: 'refs', value: (n) => n.references.map((r) => r.label).join(',') },
+        { header: 'summary', value: (n) => truncate(summary(n), 64) },
+    ]);
+}
+function printNode(n) {
+    const g = n.generate || {};
+    detail([
+        ['id', n.id],
+        ['kind', n.mode ? `${n.kind} (${n.mode})` : n.kind],
+        ['name', n.name],
+        ['position', n.position && `${Math.round(n.position.x)},${Math.round(n.position.y)}`],
+        ['text', n.text],
+        ['asset', n.assetId],
+        ['url', n.url],
+        ['status', n.status],
+        ['error', n.error],
+        ['prompt', g.prompt],
+        ['model', g.model],
+        ['ratio', g.ratio],
+        ['resolution', g.resolution],
+        ['duration', g.duration],
+        ['params', g.values && Object.keys(g.values).length ? JSON.stringify(g.values) : undefined],
+        ['history', g.historyId],
+        [
+            'references',
+            n.references.length
+                ? n.references.map((r) => `${r.label}${r.frameSlot ? `(${r.frameSlot})` : ''} ← ${r.nodeId}`).join(', ')
+                : undefined,
+        ],
+    ]);
+}
+/** Prompts start with `@image1`, so a leading `@` is text here, not a file. */
+async function literalOrFile(value, file) {
+    if (file !== undefined)
+        return readValue(`@${file}`);
+    if (value === undefined)
+        return undefined;
+    return value === '-' ? readValue('-') : value;
+}
+function parsePoint(value, label) {
+    const [x, y] = value.split(',').map((v) => Number(v.trim()));
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        throw new Error(`${label} must look like x,y`);
+    return { x, y };
+}
+/** Collect generate options; `explicit` records what the user actually passed. */
+async function generateOptions(opts) {
+    const patch = {};
+    const explicit = new Set();
+    const prompt = await literalOrFile(opts.prompt, opts.promptFile);
+    if (prompt !== undefined)
+        (patch.prompt = prompt), explicit.add('prompt');
+    if (opts.model !== undefined)
+        (patch.model = opts.model), explicit.add('model');
+    if (opts.ratio !== undefined)
+        (patch.ratio = opts.ratio), explicit.add('ratio');
+    if (opts.resolution !== undefined)
+        (patch.resolution = opts.resolution), explicit.add('resolution');
+    if (opts.duration !== undefined) {
+        const d = Number(opts.duration);
+        if (!Number.isFinite(d))
+            throw new Error('--duration must be seconds');
+        patch.duration = d;
+        explicit.add('duration');
+    }
+    if (opts.set?.length) {
+        patch.values = parseKeyValues(opts.set);
+        for (const key of Object.keys(patch.values))
+            explicit.add(`values.${key}`);
+    }
+    return { patch, explicit };
+}
+function withGenerateOptions(cmd) {
+    return cmd
+        .option('-p, --prompt <text>', 'generation prompt; @image1 etc. are literal (- reads stdin)')
+        .option('--prompt-file <path>', 'read the prompt from a file')
+        .option('-m, --model <model>', 'model nickname (see `wji models list --feature <kind>`)')
+        .option('-r, --ratio <ratio>', 'aspect ratio, e.g. 16:9')
+        .option('--resolution <res>', 'e.g. 720p, 1K')
+        .option('-d, --duration <sec>', 'video duration (turns auto-duration off)')
+        .option('--set <key=value...>', 'model parameters from `wji models get`, merged into existing ones');
+}
+// ── generation ──────────────────────────────────────────────────────────────
+const UNSUPPORTED_REF_KINDS = new Set(['table', 'youtube', 'dataset', 'bundle', 'sprite', 'layer', 'panorama']);
+/**
+ * Build the same request the canvas generate button sends
+ * (shared/generate/buildSubmitPayload.ts): references in edge order, text
+ * references prefixed to the prompt, first/last frames from frame slots.
+ */
+function buildSubmit(canvas, node, model) {
+    const kind = node.kind;
+    const g = node.content.generate || {};
+    const userPrompt = String(g.prompt || '').trim();
+    const form = model.form || {};
+    const frames = usesFrameSlots(model);
+    const firstLast = frames.start && frames.end;
+    const texts = [];
+    const images = [];
+    const videos = [];
+    const audios = [];
+    let startImage;
+    let endImage;
+    for (const ref of referencesOf(canvas, node)) {
+        const from = canvas.byId.get(ref.nodeId);
+        if (from.kind === 'text') {
+            const body = String(from.content.text || '').trim();
+            if (body)
+                texts.push(from.name ? `[${from.name}]\n${body}` : body);
+            continue;
+        }
+        if (TEXT_KINDS.has(from.kind))
+            continue;
+        if (UNSUPPORTED_REF_KINDS.has(from.kind)) {
+            throw new Error(`Reference ${ref.label} is a ${from.kind} node, which only the canvas UI can submit. Generate this node from the browser.`);
+        }
+        const asset = from.file ? canvas.assets.get(from.file) : undefined;
+        if (!asset?.url) {
+            throw new Error(`Reference ${ref.label} (${from.id}) has no finished asset yet`);
+        }
+        const item = { assetId: asset.id };
+        const category = String(asset.category || asset.type || from.kind);
+        if (category.startsWith('image')) {
+            if (kind === 'video' && (frames.start || frames.end) && ref.frameSlot) {
+                if (ref.frameSlot === 'start' && frames.start && !startImage)
+                    startImage = item;
+                if (ref.frameSlot === 'end' && frames.end && !endImage)
+                    endImage = item;
+                continue;
+            }
+            images.push(item);
+        }
+        else if (category.startsWith('video'))
+            videos.push({ ...item, duration: asset.duration });
+        else if (category.startsWith('audio'))
+            audios.push(item);
+    }
+    const refMax = form.reference?.enable ? Number(form.reference.max || 0) : 0;
+    const imageRefs = kind === 'video' && firstLast ? [] : images;
+    if (imageRefs.length > refMax) {
+        throw new Error(`${g.model} accepts ${refMax} reference image(s); this node has ${imageRefs.length}. Disconnect some first.`);
+    }
+    if (videos.length && kind === 'video' && !form.referenceVideos) {
+        throw new Error(`${g.model} does not take reference videos`);
+    }
+    if (audios.length && !form.referenceAudios) {
+        throw new Error(`${g.model} does not take reference audio`);
+    }
+    const prompt = texts.length ? `${texts.join('\n\n')}${userPrompt ? `\n\n${userPrompt}` : ''}` : userPrompt;
+    if (!prompt)
+        throw new Error(`Node ${node.id} has no prompt. Set one with \`wji canvas set ${node.id} -p "…"\`.`);
+    const values = { ...(g.values || {}) };
+    const other = form.other || {};
+    let aspectRatio = g.ratio;
+    let duration = g.duration;
+    if (kind === 'video') {
+        const seedanceRef = !!other.taskMode;
+        const taskMode = values.taskMode === 'edit' || values.taskMode === 'extend' ? values.taskMode : 'generate';
+        if (seedanceRef && taskMode !== 'generate')
+            aspectRatio = 'adaptive';
+        const autoDuration = 'autoDuration' in other && !(seedanceRef && taskMode === 'edit') && values.autoDuration !== false;
+        if ((seedanceRef && taskMode === 'edit') || autoDuration)
+            duration = -1;
+        if (seedanceRef && taskMode === 'edit')
+            values.outputFormat = 'mov';
+    }
+    const body = {
+        originalPrompt: userPrompt,
+        prompt,
+        model: g.model,
+        aspectRatio,
+        n: kind === 'image' ? Math.max(1, Number(values.n) || 1) : 1,
+        workspace: canvas.workspaceId,
+        fsnode: node.id,
+        scope: 'canvas',
+        scopeId: canvas.id,
+        values: {
+            mode: kind === 'audio' ? 'text-to-audio' : kind,
+            ...values,
+            ...(kind !== 'audio' && g.resolution ? { resolution: g.resolution } : {}),
+        },
+    };
+    if (imageRefs.length)
+        body.referenceImages = imageRefs;
+    if (kind === 'video') {
+        body.duration = duration ?? 5;
+        if (startImage)
+            body.startImage = startImage;
+        if (endImage)
+            body.endImage = endImage;
+        if (videos.length)
+            body.referenceVideos = videos.map(({ assetId }) => ({ assetId }));
+    }
+    if (audios.length)
+        body.referenceAudios = audios;
+    return body;
+}
+// ── commands ────────────────────────────────────────────────────────────────
+export function canvasCommand(globals) {
+    const canvas = new Command('canvas').description('Read and edit Infinite Canvas nodes (defaults to the canvas linked from the browser)');
+    const client = () => new WjiClient(globals());
+    canvas
+        .command('status')
+        .alias('link')
+        .description('The canvas linked from the browser and the nodes selected there')
+        .action(async () => {
+        const c = client();
+        const res = await c.get('/canvas-link');
+        if (!res?.linked) {
+            if (isJsonMode())
+                return printJson(res);
+            return info('Not linked. Open a canvas in the browser and press the link button in its top bar.');
+        }
+        const state = res.state;
+        // The link carries ids; read the selected nodes fresh so prompts and assets are current.
+        let selected = [];
+        let canvasName = state.canvasName;
+        if (state.selectedNodeIds?.length) {
+            const loaded = await loadCanvas(c, state.canvasId);
+            canvasName = loaded.name;
+            selected = state.selectedNodeIds
+                .filter((id) => loaded.byId.has(id))
+                .map((id) => describe(loaded, loaded.byId.get(id)));
+        }
+        const out = { ...res, state: { ...state, canvasName }, selected };
+        render(out, () => {
+            const seconds = Math.max(0, Math.round((new Date(state.expiresAt).getTime() - Date.now()) / 1000));
+            detail([
+                ['workspace', `${state.workspaceName || ''} ${color.dim(state.workspaceId)}`],
+                ['canvas', `${canvasName || ''} ${color.dim(state.canvasId)}`],
+                ['selected', `${state.selectedNodeIds?.length || 0} node(s)`],
+                ['expires', seconds ? `in ${Math.floor(seconds / 60)}m ${seconds % 60}s` : color.red('expired')],
+                ['url', state.url],
+            ]);
+            if (selected.length) {
+                info('');
+                nodeTable(selected);
+            }
+        });
+    });
+    canvas
+        .command('unlink')
+        .description('Drop the browser link (the tab switches its link button off within a minute)')
+        .action(async () => {
+        const res = await client().delete('/canvas-link');
+        render(res, (r) => (r.released ? success('Unlinked') : info('Nothing was linked')));
+    });
+    canvas
+        .command('list')
+        .description('Canvases in a workspace')
+        .option('-w, --workspace <id>', 'workspace (defaults to the linked one, then the profile default)')
+        .action(async (opts) => {
+        const c = client();
+        const linked = opts.workspace ? null : await linkedState(c);
+        const wsId = opts.workspace || linked?.workspaceId || c.requireWorkspace();
+        const ws = await c.get(`/workspace/list/${wsId}`);
+        const apps = (ws.apps || []).filter((a) => a.app === 'InfiniteCanvas' || a.type === 'INFINITE_CANVAS');
+        const rows = [];
+        for (const app of apps) {
+            const tree = await c.get(`/workspace/list/${wsId}/fs/${app.id}`);
+            const folder = (tree?.children || []).find((n) => n.mimetype === CANVASES_MIMETYPE);
+            if (!folder)
+                continue;
+            const canvases = toList(await c.getFresh(`/fsnode/list/${folder.id}/children`, { limit: -1 }));
+            for (const it of canvases.filter((n) => n.mimetype === CANVAS_MIMETYPE)) {
+                rows.push({ id: it.id, name: it.name, app: app.id, linked: it.id === linked?.canvasId, updatedAt: it.updatedAt });
+            }
+        }
+        render(rows, () => table(rows, [
+            { header: '', value: (r) => (r.linked ? color.green('●') : '') },
+            { header: 'id', value: (r) => r.id },
+            { header: 'name', value: (r) => r.name },
+            { header: 'app', value: (r) => r.app },
+        ]));
+    });
+    canvas
+        .command('nodes')
+        .description('Nodes with references and a content summary (* = generate node)')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('-k, --kind <kind>', 'only this kind')
+        .action(async (opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const rows = cv.nodes.filter((n) => !opts.kind || n.kind === opts.kind).map((n) => describe(cv, n));
+        render({ canvas: { id: cv.id, name: cv.name, workspaceId: cv.workspaceId }, nodes: rows }, () => {
+            info(color.dim(`${cv.name} (${cv.id}) · ${rows.length} node(s) · ${cv.edges.length} edge(s)`));
+            nodeTable(rows);
+        });
+    });
+    canvas
+        .command('get <nodeId>')
+        .description('One node in full, with its references')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .action(async (id, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const n = describe(cv, requireNode(cv, id));
+        render(n, () => printNode(n));
+    });
+    canvas
+        .command('edges')
+        .description('Connections')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('--node <id>', 'only edges touching this node')
+        .action(async (opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const rows = cv.edges.filter((e) => !opts.node || e.fromNodeId === opts.node || e.toNodeId === opts.node);
+        render(rows, () => table(rows, [
+            { header: 'edge', value: (e) => e.id },
+            { header: 'from', value: (e) => `${e.fromNodeId} ${color.dim(cv.byId.get(e.fromNodeId)?.kind || '?')}` },
+            { header: 'to', value: (e) => `${e.toNodeId} ${color.dim(cv.byId.get(e.toNodeId)?.kind || '?')}` },
+            { header: 'slot', value: (e) => e.content.videoFrameSlot || '' },
+        ]));
+    });
+    withGenerateOptions(canvas
+        .command('add <kind>')
+        .description(`Create a node: ${CREATABLE_KINDS.join(' | ')}. Media with -p/-m becomes a generate node.`)
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('-n, --name <name>', 'node name')
+        .option('-t, --text <text>', 'text for text/title/comment (- reads stdin)')
+        .option('--text-file <path>', 'read the text from a file')
+        .option('--asset <assetId>', 'show an existing asset (display node)')
+        .option('--from <nodeIds...>', 'connect these nodes in as references, in order (@image1, @image2…)')
+        .option('--at <x,y>', 'position; default is right of the --from nodes')).action(async (kind, opts) => {
+        if (!CREATABLE_KINDS.includes(kind)) {
+            throw new Error(`Unknown kind "${kind}". Use one of: ${CREATABLE_KINDS.join(', ')}`);
+        }
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const from = (opts.from || []).map((id) => requireNode(cv, id));
+        const content = {};
+        const body = {
+            name: opts.name || DEFAULT_NAMES[kind],
+            type: 'file',
+            mimetype: `${NODE_PREFIX}${kind}`,
+            parent: cv.id,
+            sort: 0,
+        };
+        let model;
+        if (TEXT_KINDS.has(kind)) {
+            const text = await literalOrFile(opts.text, opts.textFile);
+            if (text === undefined)
+                throw new Error(`${kind} nodes need --text`);
+            content.text = text;
+        }
+        else {
+            const { patch, explicit } = await generateOptions(opts);
+            const wantsGenerate = Object.keys(patch).length > 0;
+            if (opts.asset && wantsGenerate)
+                throw new Error('Use --asset for a display node, or -p/-m for a generate node, not both');
+            if (opts.asset) {
+                content.mode = 'display';
+                body.file = opts.asset;
+            }
+            else {
+                const ws = await c.get(`/workspace/list/${cv.workspaceId}`);
+                const modelName = patch.model || ws.settings?.defaultModels?.[kind];
+                if (!modelName)
+                    throw new Error(`Pass -m <model>; the workspace has no default ${kind} model`);
+                model = await findModel(c, kind, modelName, cv.workspaceId);
+                content.mode = 'generate';
+                content.generate = applyModelDefaults(model, kind, patch, { workspaceRatio: ws.aspectRatio, explicit });
+            }
+        }
+        if (opts.at)
+            content.position = parsePoint(opts.at, '--at');
+        else {
+            const draft = { id: '', kind, name: '', sort: 0, file: body.file, content, raw: null };
+            content.position = placeNear(cv, from, estimateSize(cv, draft));
+        }
+        const raw = await c.post('/fsnode/create', { ...body, content });
+        const node = { id: raw.id, kind, name: raw.name, sort: 0, file: idOf(raw.file), content, raw };
+        cv.nodes.push(node);
+        cv.byId.set(node.id, node);
+        if (node.file) {
+            for (const asset of await c.checkAssetStatus([node.file]))
+                cv.assets.set(asset.id, asset);
+        }
+        for (const src of from) {
+            await createEdge(c, cv, src.id, node.id, { frameModel: kind === 'video' ? model : undefined });
+        }
+        const out = describe(cv, node);
+        render(out, () => {
+            success(`Created ${kind} node ${node.id}`);
+            printNode(out);
+        });
+    });
+    withGenerateOptions(canvas
+        .command('set <nodeId>')
+        .description('Update a node; only what you pass changes (content is merged, not replaced)')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('-n, --name <name>', 'rename')
+        .option('-t, --text <text>', 'replace the text of a text/title/comment node (- reads stdin)')
+        .option('--text-file <path>', 'read the text from a file')
+        .option('--move <x,y>', 'move to this position')).action(async (id, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const node = requireNode(cv, id);
+        const body = {};
+        const content = { ...node.content };
+        let changed = false;
+        if (opts.name !== undefined)
+            (body.name = opts.name), (changed = true);
+        const text = await literalOrFile(opts.text, opts.textFile);
+        if (text !== undefined) {
+            if (!TEXT_KINDS.has(node.kind))
+                throw new Error(`${node.kind} nodes have no text`);
+            content.text = text;
+            changed = true;
+        }
+        if (opts.move)
+            (content.position = parsePoint(opts.move, '--move')), (changed = true);
+        const { patch, explicit } = await generateOptions(opts);
+        if (Object.keys(patch).length) {
+            if (!MEDIA_KINDS.has(node.kind))
+                throw new Error(`${node.kind} nodes cannot generate`);
+            const current = content.generate || {};
+            const merged = {
+                ...current,
+                ...patch,
+                values: { ...(current.values || {}), ...(patch.values || {}) },
+            };
+            const modelName = merged.model;
+            if (!modelName)
+                throw new Error('This node has no model yet — pass -m');
+            const model = await findModel(c, node.kind, modelName, cv.workspaceId);
+            const ws = await c.get(`/workspace/list/${cv.workspaceId}`);
+            content.generate = applyModelDefaults(model, node.kind, merged, { workspaceRatio: ws.aspectRatio, explicit });
+            content.mode = 'generate';
+            changed = true;
+        }
+        if (!changed)
+            throw new Error('Nothing to update — pass at least one option');
+        body.content = content;
+        await patchNode(c, node, body);
+        node.content = content;
+        if (body.name)
+            node.name = body.name;
+        const out = describe(cv, node);
+        render(out, () => {
+            success(`Updated ${id}`);
+            printNode(out);
+        });
+    });
+    canvas
+        .command('connect <fromId> <toId>')
+        .description('Connect from → to; into a media node this adds a reference')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .action(async (fromId, toId, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const to = requireNode(cv, toId);
+        const g = to.content.generate;
+        const model = to.kind === 'video' && g?.model ? await findModel(c, 'video', g.model, cv.workspaceId).catch(() => undefined) : undefined;
+        await createEdge(c, cv, fromId, toId, { frameModel: model });
+        const out = describe(cv, to);
+        render(out, () => {
+            const ref = out.references.find((r) => r.nodeId === fromId);
+            success(`Connected ${fromId} → ${toId}${ref ? ` as ${ref.label}${ref.frameSlot ? ` (${ref.frameSlot} frame)` : ''}` : ''}`);
+        });
+    });
+    canvas
+        .command('disconnect <fromId> <toId>')
+        .description('Remove the connection from → to')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .action(async (fromId, toId, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const edges = cv.edges.filter((e) => e.fromNodeId === fromId && e.toNodeId === toId);
+        if (!edges.length)
+            throw new Error(`No connection ${fromId} → ${toId}`);
+        for (const edge of edges)
+            await c.delete(`/fsnode/list/${edge.id}`);
+        render({ removed: edges.map((e) => e.id) }, () => success(`Disconnected ${fromId} → ${toId}`));
+    });
+    canvas
+        .command('rm <nodeIds...>')
+        .description('Delete nodes and their connections')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('-y, --yes', 'skip confirmation')
+        .action(async (ids, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const nodes = ids.map((id) => requireNode(cv, id));
+        const edges = cv.edges.filter((e) => ids.includes(e.fromNodeId) || ids.includes(e.toNodeId));
+        const busy = nodes.filter((n) => describe(cv, n).status === 'generating');
+        if (busy.length)
+            throw new Error(`Still generating, not deleted: ${busy.map((n) => n.id).join(', ')}`);
+        const lines = nodes.map((n) => `${n.kind} "${n.name}" (${n.id})`).join('\n  ');
+        const prompt = `Delete from canvas "${cv.name}":\n  ${lines}\nand ${edges.length} connection(s)?`;
+        if (!(await confirm(prompt, opts.yes)))
+            return info('Aborted');
+        for (const edge of edges)
+            await c.delete(`/fsnode/list/${edge.id}`);
+        for (const node of nodes)
+            await c.delete(`/fsnode/list/${node.id}`);
+        render({ deleted: ids, edges: edges.map((e) => e.id) }, () => success(`Deleted ${nodes.length} node(s) and ${edges.length} connection(s)`));
+    });
+    canvas
+        .command('gen <nodeId>')
+        .description('Submit a generate node with its references (costs credits)')
+        .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
+        .option('-y, --yes', 'skip the cost confirmation')
+        .option('-w, --wait', 'wait for the result')
+        .option('--timeout <sec>', 'with --wait, give up after this many seconds', '600')
+        .option('--interval <sec>', 'with --wait, poll every N seconds', '5')
+        .action(async (id, opts) => {
+        const c = client();
+        const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
+        const node = requireNode(cv, id);
+        if (!MEDIA_KINDS.has(node.kind) || node.content.mode !== 'generate') {
+            throw new Error(`${id} is not a generate node. Create one with \`wji canvas add ${MEDIA_KINDS.has(node.kind) ? node.kind : 'image'} -m … -p …\`.`);
+        }
+        if (describe(cv, node).status === 'generating')
+            throw new Error(`${id} is already generating`);
+        const g = node.content.generate || {};
+        if (!g.model)
+            throw new Error(`${id} has no model — set one with \`wji canvas set ${id} -m …\``);
+        const model = await findModel(c, node.kind, g.model, cv.workspaceId);
+        const body = buildSubmit(cv, node, model);
+        const cost = await c.post('/ai/assets/preComputeCost', {
+            type: node.kind,
+            model: body.model,
+            n: body.n,
+            prompt: body.prompt,
+            // Auto-duration submits -1; price the node's configured length instead.
+            duration: body.duration && body.duration > 0 ? body.duration : g.duration,
+            aspectRatio: body.aspectRatio,
+            referenceImageCount: body.referenceImages?.length,
+            values: body.values,
+        });
+        const credits = typeof cost === 'object' ? cost?.cost ?? cost?.credits ?? cost?.total : cost;
+        const refs = referencesOf(cv, node).map((r) => r.label).join(', ') || 'none';
+        const auto = body.duration === -1 ? ` (auto duration — estimated for ${g.duration ?? '?'}s, final cost follows the real length)` : '';
+        const question = `Generate ${node.kind} "${node.name}" with ${body.model} (refs: ${refs}) for ${credits ?? '?'} credits${auto}?`;
+        if (!(await confirm(question, opts.yes)))
+            return info('Aborted');
+        const history = await c.post(`/ai/assets/history/${node.kind}/generations`, body);
+        const assetId = idOf((history?.images || [])[0]);
+        const nextGenerate = { ...g, historyId: String(history.id), pendingAssetId: assetId };
+        await patchNode(c, node, {
+            ...(assetId ? { file: assetId } : {}),
+            content: { ...node.content, generate: nextGenerate },
+        });
+        if (!opts.wait) {
+            if (isJsonMode())
+                return printJson(history);
+            success(`Submitted ${node.kind} generation for node ${id}`);
+            reportHistory(history, await resolveAssets(c, history));
+            info(color.dim(`The canvas shows progress. Poll with: wji canvas get ${id}  or  wji history get ${history.id} --wait`));
+            return;
+        }
+        info(color.dim(`Submitted ${history.id}, waiting…`));
+        const done = await pollHistory(c, history.id, {
+            timeoutMs: Number(opts.timeout) * 1000,
+            intervalMs: Number(opts.interval) * 1000,
+        });
+        if (isJsonMode())
+            return printJson({ ...done.history, images: done.assets });
+        success(`Node ${id} generated`);
+        reportHistory(done.history, done.assets);
+    });
+    return canvas;
+}