@neta-art/cohub-cli 3.12.0 → 4.0.0

package/dist/commands/board-domain.js

@@ -1,8 +1,10 @@
 import { registerBoardAnimationCommands } from "./boards/animation.js";
 import { registerBoardAppearanceCommands } from "./boards/appearance.js";
+import { registerBoardItemCommands } from "./boards/items.js";
 import { registerBoardNodeCommands } from "./boards/nodes.js";
 export function registerBoardDomainCommands(boards) {
     registerBoardAppearanceCommands(boards);
     registerBoardNodeCommands(boards);
+    registerBoardItemCommands(boards);
     registerBoardAnimationCommands(boards);
 }

package/dist/commands/boards/animation.js

@@ -1,18 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { BoardCameraFocusParamsSchema, boardEffectDeleteOperation, boardEffectUpsertOperation, boardSequenceDeleteOperation, boardSequenceUpsertOperation, } from "@neta-art/cohub/board";
+import { boardCompositionApplyOperation, boardCompositionDeleteOperation, boardEffectDeleteOperation, boardEffectUpsertOperation, } from "@neta-art/cohub/board";
+import { BoardEffectSchema, parseBoardCompositionInput, } from "@neta-art/cohub";
 import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
 import { handleHttp, json, jsonRequested, table } from "../../output.js";
-import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
-function rect(value) {
-    const parts = value.split(",").map(Number);
-    if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
-        throw new Error("--rect must be x,y,width,height");
-    }
-    const [x, y, width, height] = parts;
-    if (width <= 0 || height <= 0)
-        throw new Error("--rect width and height must be positive");
-    return { x, y, width, height };
-}
+import { resolvedBoard, showUpdated, withJson, } from "./context.js";
 export function registerBoardAnimationCommands(boards) {
     const effects = boards.command("effects").description("Manage Board effects");
     withJson(effects.command("list <board>").alias("ls").description("List effects"))
@@ -33,17 +23,13 @@ export function registerBoardAnimationCommands(boards) {
             handleHttp(cause);
         }
     });
-    withJson(effects.command("upsert <board>")
-        .description("Create or replace an effect")
-        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin")
-        .addHelpText("after", `
-Minimal pulse effect:
-  {"id":"pulse-title","target":{"type":"node","nodeId":"title"},"kind":"effects.pulse","kindVersion":1,"lifecycle":"when-visible","timeOrigin":"visible","seed":"pulse-title"}
-
-Run boards capabilities <board> to discover supported effect kinds.`))
+    withJson(effects.command("apply <board>")
+        .description("Atomically create or replace an effect")
+        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin"))
         .action(async (target, options) => {
         try {
-            const effect = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const effect = BoardEffectSchema.omit({ boardId: true, revision: true }).parse(input);
             const board = await resolvedBoard(boards, target);
             showUpdated(await board.mutate({ build: () => [boardEffectUpsertOperation(effect)] }), options);
         }
@@ -61,18 +47,29 @@ Run boards capabilities <board> to discover supported effect kinds.`))
             handleHttp(cause);
         }
     });
-    const sequences = boards.command("sequences").description("Manage Board sequences");
-    withJson(sequences.command("list <board>").alias("ls").description("List sequences"))
+    const compositions = boards
+        .command("compositions")
+        .description("Manage atomic Board animation compositions");
+    withJson(compositions.command("list <board>").alias("ls").description("List compositions"))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["sequences"] });
+            const result = await board.inspect({ include: ["compositions"] });
             if (jsonRequested(options))
-                return json(result.sequences);
-            table(result.sequences, [
+                return json(result.compositions);
+            table(result.compositions.map((composition) => ({
+                id: composition.id,
+                name: composition.name,
+                duration: composition.timeline.duration,
+                tracks: composition.timeline.tracks.length,
+                clips: composition.timeline.clips.length,
+                revision: composition.revision,
+            })), [
                 { key: "id", label: "ID" },
                 { key: "name", label: "NAME" },
                 { key: "duration", label: "DURATION" },
+                { key: "tracks", label: "TRACKS" },
+                { key: "clips", label: "CLIPS" },
                 { key: "revision", label: "REVISION" },
             ]);
         }
@@ -80,145 +77,66 @@ Run boards capabilities <board> to discover supported effect kinds.`))
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("get <board> <sequence-id>").description("Get a sequence and its clips"))
-        .action(async (target, sequenceId, options) => {
+    withJson(compositions.command("get <board> <composition-id>").description("Get one complete composition"))
+        .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["sequences", "clips"] });
-            const sequence = result.sequences.find((item) => item.id === sequenceId);
-            if (!sequence)
-                throw new Error(`Sequence not found: ${sequenceId}`);
-            const output = {
-                sequence,
-                clips: result.clips.filter((clip) => clip.sequenceId === sequenceId),
-            };
+            const result = await board.inspect({ include: ["compositions"] });
+            const composition = result.compositions.find((item) => item.id === compositionId);
+            if (!composition)
+                throw new Error(`Composition not found: ${compositionId}`);
             if (jsonRequested(options))
-                return json(output);
-            table([sequence], [
+                return json(composition);
+            table([{
+                    id: composition.id,
+                    name: composition.name,
+                    duration: composition.timeline.duration,
+                    tracks: composition.timeline.tracks.length,
+                    clips: composition.timeline.clips.length,
+                    revision: composition.revision,
+                }], [
                 { key: "id", label: "ID" },
                 { key: "name", label: "NAME" },
                 { key: "duration", label: "DURATION" },
+                { key: "tracks", label: "TRACKS" },
+                { key: "clips", label: "CLIPS" },
                 { key: "revision", label: "REVISION" },
             ]);
-            table(output.clips, [
-                { key: "id", label: "CLIP" },
-                { key: "kind", label: "KIND" },
-                { key: "start", label: "START" },
-                { key: "duration", label: "DURATION" },
-            ]);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("upsert <board>")
-        .description("Create or replace a sequence and clips")
-        .requiredOption("-i, --input <file>", "{ sequence, clips } JSON; use - for stdin")
+    withJson(compositions.command("apply <board>")
+        .description("Atomically create or replace a composition")
+        .requiredOption("-i, --input <file>", "BoardComposition JSON; use - for stdin")
         .addHelpText("after", `
-Minimal sequence with one clip:
-  {"sequence":{"id":"intro","name":"Intro","duration":1200,"seed":"intro"},"clips":[{"id":"reveal-title","kind":"text.reveal","kindVersion":1,"target":{"type":"node","nodeId":"title"},"start":0,"duration":600,"seed":"reveal-title"}]}
+Property changes use timeline.tracks with registered channels and keyframes.
+Procedural behavior such as text reveal, particles, and camera focus uses timeline.clips.
+Run boards capabilities to discover channels and clip schemas.
 
-Coordinate rules:
-  node motion x/y and path points are Board-world offsets; camera.pan x/y are screen-pixel offsets.
-
-Edit an existing sequence:
-  cohub boards sequences get <board> intro --json > intro.json
-  cohub boards sequences upsert <board> -i intro.json`))
+Minimal fade composition:
+  {"id":"intro","name":"Intro","timeline":{"duration":800,"tracks":[{"id":"title-opacity","target":{"type":"item","itemId":"title"},"channel":"style.opacity","fill":"both","keyframes":[{"time":0,"value":0},{"time":800,"value":1,"easing":"ease-out-cubic"}]}],"clips":[],"markers":[]},"playback":{"loop":false,"endBehavior":"hold","reducedMotion":{"mode":"base"}}}`))
         .action(async (target, options) => {
         try {
             const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardSequenceUpsertOperation(input)] }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(sequences.command("camera-focus <board> <sequence-id>")
-        .description("Add or replace a semantic camera focus clip")
-        .option("--id <id>", "Stable clip id")
-        .option("--node <id>", "Focus one node")
-        .option("--nodes <ids>", "Focus comma-separated nodes")
-        .option("--frame <id>", "Focus a frame")
-        .option("--rect <rect>", "Board world rect as x,y,width,height")
-        .requiredOption("--at <ms>", "Clip start time")
-        .option("--duration <ms>", "Transition duration", "700")
-        .option("--padding <px>", "Screen padding in CSS pixels", "32")
-        .option("--fit <mode>", "contain or cover", "contain")
-        .option("--min-zoom <zoom>", "Minimum zoom multiplier")
-        .option("--max-zoom <zoom>", "Maximum zoom multiplier")
-        .option("--easing <name>", "Easing", "ease-out-cubic")
-        .addHelpText("after", `
-Examples:
-  cohub boards sequences camera-focus plan.board intro --node hero --at 1200
-  cohub boards sequences camera-focus plan.board intro --rect 120,80,640,360 --at 2000 --duration 800`))
-        .action(async (target, sequenceId, options) => {
-        try {
-            const selected = [options.node, options.nodes, options.frame, options.rect].filter(Boolean);
-            if (selected.length !== 1)
-                throw new Error("Choose one of --node, --nodes, --frame, or --rect");
-            const focus = options.node
-                ? { type: "node", nodeId: options.node }
-                : options.nodes
-                    ? { type: "nodes", nodeIds: options.nodes.split(",").map((id) => id.trim()).filter(Boolean) }
-                    : options.frame
-                        ? { type: "frame", frameId: options.frame }
-                        : { type: "rect", rect: rect(options.rect) };
-            const params = BoardCameraFocusParamsSchema.parse({
-                focus,
-                fit: options.fit,
-                padding: finite(options.padding, "padding"),
-                ...(options.minZoom === undefined ? {} : { minZoom: finite(options.minZoom, "min zoom") }),
-                ...(options.maxZoom === undefined ? {} : { maxZoom: finite(options.maxZoom, "max zoom") }),
-            });
-            const start = finite(options.at, "start");
-            const duration = finite(options.duration, "duration");
-            if (start < 0 || duration <= 0)
-                throw new Error("start must be non-negative and duration must be positive");
-            const clipId = options.id ?? randomUUID();
+            const composition = parseBoardCompositionInput(input);
             const board = await resolvedBoard(boards, target);
             showUpdated(await board.mutate({
-                include: ["sequences", "clips"],
-                build(current) {
-                    const currentSequence = current.sequences.find((sequence) => sequence.id === sequenceId);
-                    if (!currentSequence)
-                        throw new Error(`Sequence not found: ${sequenceId}`);
-                    const { boardId: _boardId, revision: _revision, ...sequence } = currentSequence;
-                    const clips = current.clips
-                        .filter((clip) => clip.sequenceId === sequenceId && clip.id !== clipId)
-                        .map(({ sequenceId: _sequenceId, ...clip }) => clip);
-                    clips.push({
-                        id: clipId,
-                        kind: "camera.focus",
-                        kindVersion: 1,
-                        target: { type: "camera" },
-                        start,
-                        duration,
-                        layer: "screen",
-                        fill: "forwards",
-                        easing: options.easing,
-                        params,
-                        keyframes: [],
-                        assetRefs: [],
-                        seed: clipId,
-                        metadata: {},
-                    });
-                    return [boardSequenceUpsertOperation({
-                            sequence: { ...sequence, duration: Math.max(sequence.duration, start + duration) },
-                            clips,
-                        })];
-                },
+                build: () => [boardCompositionApplyOperation(composition)],
             }), options);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("delete <board> <sequence-id>").alias("rm").description("Delete a sequence and its clips"))
-        .action(async (target, sequenceId, options) => {
+    withJson(compositions.command("delete <board> <composition-id>").alias("rm").description("Delete a composition"))
+        .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardSequenceDeleteOperation(sequenceId)] }), options);
+            showUpdated(await board.mutate({
+                build: () => [boardCompositionDeleteOperation(compositionId)],
+            }), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards/appearance.js

@@ -67,20 +67,19 @@ Examples:
     });
     withJson(boards.command("playback-policy <board>")
         .description("Configure automatic Board playback")
-        .option("--sequence <id>", "Sequence to play")
+        .option("--composition <id>", "Composition to play")
         .option("--delay <ms>", "Delay before playback", "0")
-        .option("--loop", "Loop the sequence")
         .option("--clear", "Remove the playback policy"))
         .action(async (target, options) => {
         try {
-            if (options.clear === Boolean(options.sequence))
-                throw new Error("Use --sequence or --clear");
+            if (options.clear === Boolean(options.composition))
+                throw new Error("Use --composition or --clear");
             const delayMs = finite(options.delay, "delay");
             if (delayMs < 0)
                 throw new Error("delay must be non-negative");
             const policy = options.clear
                 ? null
-                : { sequenceId: options.sequence, delayMs, loop: Boolean(options.loop) };
+                : { compositionId: options.composition, delayMs };
             const board = await resolvedBoard(boards, target);
             showUpdated(await board.mutate({
                 build: (current) => [boardPlaybackPolicyOperation(current.board.metadata, policy)],

package/dist/commands/boards/items.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardItemCommands(boards: Command): void;

package/dist/commands/boards/items.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { BoardAuthoringItemSchema, BoardItemPatchSchema, } from "@neta-art/cohub";
+import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { handleHttp, json, jsonRequested, ok, table } from "../../output.js";
+import { resolvedBoard, withJson, } from "./context.js";
+const baseVersion = (value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new Error("base version must be a non-negative integer");
+    }
+    return parsed;
+};
+async function execute(boards, target, command, options) {
+    const board = await resolvedBoard(boards, target);
+    const snapshot = await board.authoring();
+    const mutation = {
+        mutationId: options.mutationId?.trim() || randomUUID(),
+        baseVersion: baseVersion(options.baseVersion, snapshot.board.version),
+        commands: [command],
+    };
+    if (options.dryRun) {
+        const result = {
+            mutationId: mutation.mutationId,
+            status: "prepared",
+            board: { id: snapshot.board.id, version: snapshot.board.version },
+            commands: mutation.commands,
+        };
+        if (jsonRequested(options))
+            return json(result);
+        ok(`Prepared against Board version ${snapshot.board.version}; no server validation or write performed`);
+        return;
+    }
+    const receipt = await board.mutateSemantic(mutation);
+    if (jsonRequested(options))
+        return json(receipt);
+    ok(`${receipt.replayed ? "Replayed" : "Applied"} mutation at Board version ${receipt.board.version}`);
+}
+function mutationOptions(command) {
+    return withJson(command)
+        .option("--base-version <version>", "Expected Board version; defaults to latest")
+        .option("--mutation-id <id>", "Stable id for safe retries")
+        .option("--dry-run", "Prepare locally without server validation or writing");
+}
+export function registerBoardItemCommands(boards) {
+    const items = boards.command("items").description("Author Board items with semantic JSON");
+    withJson(items.command("list <board>").alias("ls").description("List semantic Board items"))
+        .action(async (target, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const snapshot = await board.authoring();
+            if (jsonRequested(options))
+                return json(snapshot.items);
+            table(snapshot.items.map((item) => ({
+                id: item.id,
+                type: item.type,
+                x: item.frame.x,
+                y: item.frame.y,
+                width: item.frame.width,
+                height: item.frame.height,
+            })), [
+                { key: "id", label: "ID" },
+                { key: "type", label: "TYPE" },
+                { key: "x", label: "X" },
+                { key: "y", label: "Y" },
+                { key: "width", label: "WIDTH" },
+                { key: "height", label: "HEIGHT" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("create <board>")
+        .description("Create one item")
+        .requiredOption("-i, --input <file>", "Board Item JSON; use - for stdin")
+        .addHelpText("after", `
+Minimal text item:
+  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48,"rotation":0},"props":{"text":"Launch plan","fontSize":32},"style":{"color":"brand"}}`))
+        .action(async (target, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.create",
+                item: BoardAuthoringItemSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("patch <board> <item-id>")
+        .description("Recursively merge item fields")
+        .requiredOption("-i, --input <file>", "Board Item patch JSON; use - for stdin")
+        .addHelpText("after", `
+Objects merge recursively, arrays replace, and null clears optional fields.
+Move and rename a text item without replacing its size or font:
+  {"frame":{"x":160,"y":120},"props":{"text":"Updated"}}`))
+        .action(async (target, itemId, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.patch",
+                itemId,
+                patch: BoardItemPatchSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("replace <board> <item-id>")
+        .description("Replace one complete item")
+        .requiredOption("-i, --input <file>", "Complete Board Item JSON; use - for stdin"))
+        .action(async (target, itemId, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.replace",
+                itemId,
+                item: BoardAuthoringItemSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("delete <board> <item-id>").alias("rm")
+        .description("Delete one item")
+        .option("--cascade", "Atomically remove relations, effects, and animation references"))
+        .action(async (target, itemId, options) => {
+        try {
+            await execute(boards, target, {
+                type: "item.delete",
+                itemId,
+                cascade: Boolean(options.cascade),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards/nodes.d.ts

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
 export declare function registerBoardNodeCommands(boards: Command): void;

package/dist/commands/boards/nodes.js

@@ -1,68 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { boardNodeCreateOperation, boardNodeDeleteOperations, boardNodePatchOperation, createBoardConnection, createBoardNode, } from "@neta-art/cohub/board";
-import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { createBoardConnection } from "@neta-art/cohub/board";
 import { handleHttp } from "../../output.js";
 import { resolvedBoard, showUpdated, withJson, } from "./context.js";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
 export function registerBoardNodeCommands(boards) {
-    const nodes = boards.command("nodes").description("Create and update Board nodes");
-    withJson(nodes.command("add <board>")
-        .description("Add a node")
-        .requiredOption("-i, --input <file>", "BoardNodeSpec JSON; use - for stdin")
-        .addHelpText("after", `
-Frame x/y/width/height use Board world units. Draw points and arrow endpoints are also world input.
-Minimal text node:
-  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48},"text":"Launch plan"}`))
-        .action(async (target, options) => {
-        try {
-            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            const node = createBoardNode(input);
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardNodeCreateOperation(node)] }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(nodes.command("patch <board> <node-id>")
-        .description("Patch a node")
-        .requiredOption("-i, --input <file>", "BoardNodeInput field patch; use - for stdin")
-        .addHelpText("after", `
-x/y are absolute Board world coordinates.
-Move a node without changing its content:
-  {"x":160,"y":120}
-
-Nested view, style, and data fields replace their complete stored object.`))
-        .action(async (target, nodeId, options) => {
-        try {
-            const patch = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            if ("nodeId" in patch)
-                throw new Error("node patch must not contain nodeId");
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [boardNodePatchOperation(nodeId, patch)],
-            }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(nodes.command("remove <board> <node-id>")
-        .alias("rm")
-        .description("Remove a node and its connections"))
-        .action(async (target, nodeId, options) => {
-        try {
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                include: ["connections"],
-                build: (current) => boardNodeDeleteOperations(nodeId, current.connections),
-            }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
     withJson(boards.command("connect <board> <source> <target>")
-        .description("Connect two Board nodes")
+        .description("Connect two Board items")
         .option("--id <id>", "Connection id")
         .option("--relation <relation>", "Relation type")
         .option("--direction <direction>", "none, forward, backward, or both", "forward")

package/dist/commands/boards.d.ts

@@ -1,7 +1,7 @@
 import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
 import type { Command } from "commander";
 import { parseBoardJsonObject } from "../board-command-support.js";
-declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "sequences", "clips", "playback"];
+declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "compositions", "playback"];
 type InspectSection = (typeof INSPECT_SECTIONS)[number];
 export declare const parseJsonObject: typeof parseBoardJsonObject;
 export declare function readJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;

package/dist/commands/boards.js

@@ -5,7 +5,7 @@ import { registerBoardDomainCommands } from "./board-domain.js";
 import { createClient, createRealtimeClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
-const INSPECT_SECTIONS = ["nodes", "connections", "effects", "sequences", "clips", "playback"];
+const INSPECT_SECTIONS = ["nodes", "connections", "effects", "compositions", "playback"];
 export const parseJsonObject = parseBoardJsonObject;
 export async function readJsonObject(source, maxBytes = BOARD_TRANSACTION_INPUT_MAX_BYTES) {
     return readBoardJsonObject(source, maxBytes);
@@ -80,8 +80,7 @@ function showBoard(result) {
             nodes: result.nodes.length,
             connections: result.connections.length,
             effects: result.effects.length,
-            sequences: result.sequences.length,
-            clips: result.clips.length,
+            compositions: result.compositions.length,
         },
     ], [
         { key: "id", label: "ID" },
@@ -90,8 +89,7 @@ function showBoard(result) {
         { key: "nodes", label: "Nodes" },
         { key: "connections", label: "Connections" },
         { key: "effects", label: "Effects" },
-        { key: "sequences", label: "Sequences" },
-        { key: "clips", label: "Clips" },
+        { key: "compositions", label: "Compositions" },
     ]);
 }
 function showSummary(result) {
@@ -110,7 +108,7 @@ function showSummary(result) {
         { key: "nodes", label: "NODES" },
         { key: "connections", label: "CONNECTIONS" },
         { key: "effects", label: "EFFECTS" },
-        { key: "sequences", label: "SEQUENCES" },
+        { key: "compositions", label: "COMPOSITIONS" },
         { key: "background", label: "BACKGROUND" },
         { key: "updatedAt", label: "UPDATED" },
     ]);
@@ -135,7 +133,7 @@ function showValidation(result) {
 function showPlayback(result) {
     table([result], [
         { key: "playbackId", label: "Playback ID" },
-        { key: "sequenceId", label: "Sequence" },
+        { key: "compositionId", label: "Composition" },
         { key: "status", label: "Status" },
         { key: "position", label: "Position" },
         { key: "timeScale", label: "Time Scale" },
@@ -168,7 +166,7 @@ function registerTransactionCommand(boards, name) {
 Input example:
   {"baseVersion":12,"operations":[{"type":"board.patch","payload":{"patch":{"title":"Launch plan"}}}]}
 
-Prefer semantic commands such as boards background, nodes, effects, or sequences for common edits.`))
+Prefer semantic commands such as boards background, nodes, effects, or compositions for common edits.`))
         .action(async (target, options) => {
         try {
             const transaction = createTransactionInput(await readJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES), options);
@@ -181,8 +179,8 @@ Prefer semantic commands such as boards background, nodes, effects, or sequences
             if (name === "validate")
                 showValidation(result);
             else {
-                ok(`Board updated to version ${result.board.version}`);
-                showBoard(result);
+                const receipt = result;
+                ok(`Board updated to version ${receipt.board.version}`);
             }
         }
         catch (cause) {
@@ -317,7 +315,7 @@ export function registerBoards(program) {
         .option("--mutation-id <id>", "Stable id for safe retries")
         .option("-i, --input <file>", "BoardCreateInput fields; use - for stdin")
         .addHelpText("after", `
-For normal use, create an empty Board and add content with boards nodes, effects, and sequences.
+For normal use, create an empty Board and add content with boards nodes, effects, and compositions.
 --input is intended for bulk creation and accepts BoardCreateInput fields except path and title.`))
         .action(async (path, options) => {
         try {
@@ -347,7 +345,7 @@ For normal use, create an empty Board and add content with boards nodes, effects
     withJson(boards.command("inspect <board>")
         .alias("get")
         .description("Inspect a Board")
-        .option("--include <sections>", "Comma-separated nodes,connections,effects,sequences,clips,playback")
+        .option("--include <sections>", "Comma-separated nodes,connections,effects,compositions,playback")
         .option("--viewport <rect>", "Viewport as x,y,width,height"))
         .action(async (target, options) => {
         try {
@@ -416,20 +414,20 @@ For normal use, create an empty Board and add content with boards nodes, effects
     registerTransactionCommand(boards, "apply");
     registerBoardDomainCommands(boards);
     registerExportCommand(boards);
-    withJson(boards.command("play <board> <sequence-id>")
+    withJson(boards.command("play <board> <composition-id>")
         .description("Start shared playback")
         .option("--position <time>", "Initial position in milliseconds")
         .option("--time-scale <scale>", "Playback speed from 0 to 4")
         .option("--seed <seed>", "Deterministic playback seed")
         .option("--command-id <id>", "Idempotency command ID"))
-        .action(async (target, sequenceId, options) => {
+        .action(async (target, compositionId, options) => {
         try {
             const spaceId = resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).play({
                 commandId: commandId(options),
                 type: "play",
-                sequenceId,
+                compositionId,
                 shared: true,
                 ...(options.position === undefined ? {} : { position: parseNumber(options.position, "position", { min: 0 }) }),
                 ...(options.timeScale === undefined ? {} : { timeScale: parseNumber(options.timeScale, "timeScale", { min: Number.EPSILON, max: 4 }) }),
@@ -520,7 +518,7 @@ For normal use, create an empty Board and add content with boards nodes, effects
                         process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
                     }
                     else if (event.type === "board.playback.changed") {
-                        process.stdout.write(`${event.payload.status}  sequence ${event.payload.sequenceId}  position ${event.payload.position}\n`);
+                        process.stdout.write(`${event.payload.status}  composition ${event.payload.compositionId}  position ${event.payload.position}\n`);
                     }
                     else {
                         process.stdout.write(`awareness ${event.payload.actorName}  ${event.payload.update.type}\n`);

package/dist/commands/works.js

@@ -259,7 +259,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--meta <json>", "Work metadata as a JSON object")
         .option("--hide-cohub-bar", "Hide the Cohub footer bar on the public work page")
         .option("--show-cohub-bar", "Show the Cohub footer bar on the public work page")
@@ -338,7 +338,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--clear-work-scopes", "Clear work runtime scopes")
         .option("--clear-viewer-scopes", "Clear viewer-requestable scopes")
         .option("--meta <json>", "Work metadata as a JSON object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.12.0",
+  "version": "4.0.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.19.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "5.10.0"
+    "@neta-art/cohub": "6.0.0"
   },
   "publishConfig": {
     "access": "public"