@neta-art/cohub 5.10.0 → 7.0.0

package/README.md

@@ -80,20 +80,16 @@ Use `space.boards` for collection operations and bind an ID with
 `space.board(boardId)` for entity operations:
 
 ```ts
-import { createBoardNode } from "@neta-art/cohub";
-
 const created = await space.boards.create({
   path: "boards/plan.board",
   title: "Plan",
-  nodes: [
-    createBoardNode({
-      id: "goal",
-      type: "geo",
-      frame: { x: 80, y: 80, width: 240, height: 120 },
-      text: "Ship",
-      color: "green",
-    }),
-  ],
+  items: [{
+    id: "goal",
+    type: "geo",
+    frame: { x: 80, y: 80, width: 240, height: 120, rotation: 0 },
+    props: { shape: "rounded", text: "Ship" },
+    style: { color: "green" },
+  }],
 });
 
 const board = space.board(created.board.id);
@@ -102,32 +98,32 @@ const board = space.board(created.board.id);
 // Machine-readable types, enums and coordinate spaces for dynamic clients.
 const capabilities = await board.capabilities();
 
-const snapshot = await board.inspect({
-  include: ["nodes", "effects", "sequences", "clips", "playback"],
-});
+const snapshot = await board.authoring({ include: ["items"] });
 
-await board.apply({
-  txId: crypto.randomUUID(),
+await board.mutateSemantic({
   baseVersion: snapshot.board.version,
-  operations: [
-    { type: "board.patch", payload: { patch: { title: "Updated plan" } } },
-  ],
+  commands: [{
+    type: "item.patch",
+    itemId: "goal",
+    patch: { props: { text: "Updated plan" } },
+  }],
 });
 
 await board.play({
   commandId: crypto.randomUUID(),
   type: "play",
-  sequenceId: "ambient",
+  compositionId: "ambient",
 });
 ```
 
-A bound `BoardClient` injects its `boardId` into validation and transaction
-requests. Realtime subscriptions are also scoped to that Board:
+A bound `BoardClient` injects its `boardId` into semantic mutation requests.
+Realtime subscriptions use the same semantic resource projection:
 
 ```ts
 const stop = board.subscribe({
-  transaction(event) {
+  changed(event) {
     console.log("version", event.payload.version);
+    console.log("items", event.payload.changed.items);
   },
   playback(event) {
     console.log("playback", event.payload.status);
@@ -137,7 +133,7 @@ const stop = board.subscribe({
 stop();
 ```
 
-Task nodes keep a small, replaceable display snapshot beside their stable `taskRunId`. The SDK can build that projection from an authoritative TaskRun without copying the full payload, result or inline media into a Board:
+Task Items keep a small, replaceable display snapshot beside their stable `taskRunId`. The SDK can build that projection from an authoritative TaskRun without copying the full payload, result or inline media into a Board:
 
 ```ts
 import { taskRunToBoardTaskSnapshot } from "@neta-art/cohub/board";
@@ -156,40 +152,36 @@ graphics stack:
 ```ts
 import {
   BoardDocumentSchema,
-  clip,
-  compileSequence,
+  compileComposition,
   createBoardExtensionRegistry,
   itemBounds,
   planBoardExport,
-  timeline,
 } from "@neta-art/cohub/board";
 
-const sequence = compileSequence({
+const composition = compileComposition({
   id: "ambient",
   name: "Ambient",
-  seed: "ambient-v1",
-  timeline: clip({
-    kind: "motion.keyframes",
-    target: { type: "node", nodeId: "image" },
-    duration: 1_000,
+  duration: 1_000,
+  tracks: [{
+    id: "image-translation",
+    target: { type: "item", itemId: "image" },
+    channel: "transform.translation",
+    fill: "both",
     keyframes: [
-      { at: 0, value: { y: 0 } },
-      { at: 500, value: { y: -8 } },
-      { at: 1_000, value: { y: 0 } },
+      { time: 0, value: { x: 0, y: 0 } },
+      { time: 500, value: { x: 0, y: -8 } },
+      { time: 1_000, value: { x: 0, y: 0 } },
     ],
-  }),
+  }],
+  playback: { loop: true, endBehavior: "hold", reducedMotion: { mode: "base" } },
 });
 
 await space.boards.create({
   path: "boards/ambient.board",
   metadata: {
-    playback: {
-      sequenceId: sequence.sequence.id,
-      delayMs: 500,
-      loop: true,
-    },
+    playback: { compositionId: composition.id, delayMs: 500 },
   },
-  sequences: [sequence],
+  compositions: [composition],
 });
 ```
 
@@ -241,8 +233,9 @@ access tokens — no API keys required.
 
 Four runtime-only APIs are available **exclusively inside a published Work**:
 
-- `client.context()` — returns Work identity, Space identity, and current
-  permission scopes. Returns `null` outside a Work runtime.
+- `client.context()` — returns Work identity, Space identity, the current
+  viewer, permission scopes, and optional UI Preview invocation identifiers.
+  Returns `null` outside a Work runtime.
 - `client.auth.request({ scopes, reason })` — shows the viewer a consent dialog
   and caches a token with the approved scopes.
 - `client.work.commerce.*` — entitlement checks, credit consumption,
@@ -259,6 +252,7 @@ const client = createCohubClient({ env: "prod" });
 const ctx = await client.context();
 if (!ctx?.space?.id) throw new Error("Not inside a published Work.");
 
+const sourceSessionId = ctx.invocation?.sessionId ?? null;
 const space = client.space(ctx.space.id);
 
 // Request viewer scopes from a user gesture (button click)
@@ -274,11 +268,14 @@ Work permissions come in **two disjoint sets**:
 
 - **Work scopes** (read, no consent): `space.view`, `session.view`,
   `file.view`, `taskrun.view` — granted at publish time.
-- **Viewer scopes** (action, consent-required): `session.prompt.fullaccess`,
-  `generation.create`, `user.space.list`, `user.session.list`,
-  `user.usage.read` — approved per-viewer via `auth.request()`.
-
-> **Read operations need work scopes. Action operations need viewer scopes.
+- **Viewer scopes** (consent-required): `taskrun.view`,
+  `session.prompt.fullaccess`, `generation.create`, `user.space.list`,
+  `user.session.list`, `user.usage.read` — approved per-viewer via
+  `auth.request()`.
+
+Viewer-granted `taskrun.view` is checked against the viewer's own access to the
+requested Space or Session. Other read operations need work scopes; action
+operations need viewer scopes.
 They never substitute for each other.** For example, `session.prompt.fullaccess`
 lets you send a prompt but does NOT let you read the reply — that needs
 `session.view` (a work scope). Similarly, `generation.create` lets you create

package/dist/board/animation.d.ts

@@ -1,38 +1,47 @@
 import { BoardCapability, BoardRenderCost } from "../protocol/dist/board-constants.js";
-import { BoardAssetRef, BoardClip, BoardDiagnostic, BoardEffect, BoardSequence, BoardTarget, BoardValidationResult } from "../protocol/dist/board.js";
+import { BoardAnimationTarget, BoardComposition, BoardEasing, BoardProceduralClip, BoardTimelineMarker, BoardTrack, BoardTrackInterpolation } from "../protocol/dist/board-composition.js";
+import { BoardAssetRef, BoardEffect } from "../protocol/dist/board-effect.js";
+import { BoardDiagnostic, BoardValidationResult } from "../protocol/dist/board.js";
 import "../protocol/dist/index.js";
 //#region src/board/animation.d.ts
-type TimelineClipInput = Omit<BoardClip, "id" | "sequenceId" | "start" | "seed"> & {
-  id?: string;
-  seed?: string;
+type CompositionInput = Omit<BoardComposition, "revision"> & {
+  revision?: number;
 };
-type TimelineInput = {
-  type: "clip";
-  clip: TimelineClipInput;
-} | {
-  type: "parallel";
-  children: TimelineInput[];
-} | {
-  type: "sequence";
-  children: TimelineInput[];
-} | {
-  type: "stagger";
-  each: number;
-  children: TimelineInput[];
-} | {
-  type: "delay";
-  duration: number;
-  child: TimelineInput;
-} | {
-  type: "repeat";
-  count: number;
-  child: TimelineInput;
+type TrackInput = Omit<BoardTrack, "channelVersion" | "metadata"> & {
+  channelVersion?: number;
+  metadata?: Record<string, unknown>;
 };
-type CompiledSequence = {
-  sequence: Omit<BoardSequence, "boardId" | "revision">;
-  clips: Array<Omit<BoardClip, "sequenceId">>;
-  assetRefs: BoardAssetRef[];
+type ProceduralClipInput = Omit<BoardProceduralClip, "kindVersion" | "layer" | "fill" | "easing" | "params" | "assetRefs" | "metadata"> & {
+  kindVersion?: number;
+  layer?: BoardProceduralClip["layer"];
+  fill?: BoardProceduralClip["fill"];
+  easing?: BoardEasing;
+  params?: Record<string, unknown>;
+  assetRefs?: BoardAssetRef[];
+  metadata?: Record<string, unknown>;
+};
+declare function track(input: TrackInput): BoardTrack;
+declare function proceduralClip(input: ProceduralClipInput): BoardProceduralClip;
+declare function composition(input: CompositionInput): BoardComposition;
+declare function compileComposition(input: {
+  id: string;
+  name: string;
+  duration: number;
+  tracks?: TrackInput[];
+  clips?: ProceduralClipInput[];
+  markers?: BoardTimelineMarker[];
+  playback?: BoardComposition["playback"];
+  metadata?: Record<string, unknown>;
+}): BoardComposition;
+type SampledTrack = {
+  target: BoardAnimationTarget;
+  channel: string;
+  value: unknown;
 };
+declare function sampleEasing(easing: BoardEasing, value: number): number;
+/** Deterministically sample one validated Track without touching scene state. */
+declare function sampleTrack(trackValue: BoardTrack, time: number): SampledTrack | null;
+declare function sampleCompositionTracks(value: BoardComposition, time: number): SampledTrack[];
 type RenderBounds = {
   x: number;
   y: number;
@@ -48,54 +57,135 @@ type BoardExtensionDefinition = BoardCapability & {
 };
 type BoardPresetDefinition = BoardCapability & {
   kind: "preset";
-  compile: (params: Record<string, unknown>) => TimelineInput;
+  compile: (params: Record<string, unknown>) => BoardComposition;
 };
 declare const DEFAULT_BOARD_LIMITS: BoardRenderCost;
-declare const timeline: {
-  clip(clip: TimelineClipInput): TimelineInput;
-  parallel(...children: TimelineInput[]): TimelineInput;
-  sequence(...children: TimelineInput[]): TimelineInput;
-  stagger(each: number, ...children: TimelineInput[]): TimelineInput;
-  delay(duration: number, child: TimelineInput): TimelineInput;
-  repeat(count: number, child: TimelineInput): TimelineInput;
-};
-declare function clip(input: {
-  kind: string;
-  target: BoardTarget;
-  duration: number;
-  params?: Record<string, unknown>;
-  keyframes?: BoardClip["keyframes"];
-  assetRefs?: BoardAssetRef[];
-  easing?: string;
-  fill?: BoardClip["fill"];
-  layer?: BoardClip["layer"];
-  kindVersion?: number;
-  id?: string;
-  seed?: string;
-  metadata?: Record<string, unknown>;
-}): TimelineInput;
-declare function compileSequence(input: {
-  id: string;
-  name: string;
-  seed: string;
-  timeline: TimelineInput;
-  restPose?: Record<string, unknown>;
-  metadata?: Record<string, unknown>;
-}): CompiledSequence;
 declare class BoardExtensionRegistry {
   #private;
+  constructor();
   register(definition: BoardExtensionDefinition | BoardPresetDefinition): this;
   capabilities(): BoardCapability[];
-  compilePreset(id: string, version: number, params: Record<string, unknown>): TimelineInput;
+  compilePreset(id: string, version: number, params: Record<string, unknown>): {
+    id: string;
+    name: string;
+    timeline: {
+      duration: number;
+      tracks: {
+        id: string;
+        target: {
+          type: "item";
+          itemId: string;
+        } | {
+          type: "effect";
+          effectId: string;
+        } | {
+          type: "camera";
+        } | {
+          type: "board";
+        };
+        channel: string;
+        channelVersion: number;
+        interpolation: "linear" | "step";
+        fill: "backwards" | "both" | "forwards" | "none";
+        keyframes: {
+          time: number;
+          value: unknown;
+          easing?: "ease-in-cubic" | "ease-in-out-cubic" | "ease-in-out-quad" | "ease-in-quad" | "ease-out-cubic" | "ease-out-expo" | "ease-out-quad" | "ease-out-quart" | "linear" | undefined;
+        }[];
+        metadata: Record<string, unknown>;
+      }[];
+      clips: {
+        id: string;
+        kind: string;
+        kindVersion: number;
+        target: {
+          type: "item";
+          itemId: string;
+        } | {
+          type: "effect";
+          effectId: string;
+        } | {
+          type: "camera";
+        } | {
+          type: "board";
+        };
+        start: number;
+        duration: number;
+        layer: "behind" | "content" | "front" | "screen";
+        fill: "backwards" | "both" | "forwards" | "none";
+        easing: "ease-in-cubic" | "ease-in-out-cubic" | "ease-in-out-quad" | "ease-in-quad" | "ease-out-cubic" | "ease-out-expo" | "ease-out-quad" | "ease-out-quart" | "linear";
+        params: Record<string, unknown>;
+        assetRefs: {
+          type: "extension" | "space-file";
+          ref: string;
+          digest?: string | undefined;
+        }[];
+        seed: string;
+        metadata: Record<string, unknown>;
+      }[];
+      markers: {
+        id: string;
+        time: number;
+        duration?: number | undefined;
+        metadata: Record<string, unknown>;
+      }[];
+    };
+    playback: {
+      loop: boolean;
+      endBehavior: "hold" | "reset";
+      reducedMotion: {
+        mode: "base";
+      } | {
+        mode: "time";
+        time: number;
+      } | {
+        mode: "marker";
+        markerId: string;
+      };
+    };
+    metadata: Record<string, unknown>;
+    revision: number;
+  };
   validate(input: {
-    clips: Array<Omit<BoardClip, "sequenceId">>;
+    composition: BoardComposition;
     effects?: Array<Omit<BoardEffect, "boardId" | "revision">>;
     profile?: QualityProfile;
     limits?: BoardRenderCost;
   }): BoardValidationResult;
 }
-declare function createBoardExtensionRegistry(input?: {
-  builtins?: boolean;
-}): BoardExtensionRegistry;
+declare function createBoardExtensionRegistry(): BoardExtensionRegistry;
+declare const BOARD_CHANNELS: {
+  readonly "transform.translation": {
+    readonly targets: readonly ["item"];
+    readonly value: import("zod").ZodObject<{
+      x: import("zod").ZodNumber;
+      y: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>;
+    readonly interpolations: readonly ["linear", "step"];
+    readonly coordinateSpace: "world-offset";
+    readonly unit: "board";
+  };
+  readonly "transform.rotation": {
+    readonly targets: readonly ["item"];
+    readonly value: import("zod").ZodNumber;
+    readonly interpolations: readonly ["linear", "step"];
+    readonly unit: "radian";
+  };
+  readonly "transform.scale": {
+    readonly targets: readonly ["item"];
+    readonly value: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodObject<{
+      x: import("zod").ZodNumber;
+      y: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>]>;
+    readonly interpolations: readonly ["linear", "step"];
+    readonly unit: "ratio";
+  };
+  readonly "style.opacity": {
+    readonly targets: readonly ["item"];
+    readonly value: import("zod").ZodNumber;
+    readonly interpolations: readonly ["linear", "step"];
+    readonly unit: "ratio";
+  };
+};
 //#endregion
-export { BoardExtensionDefinition, BoardExtensionRegistry, BoardPresetDefinition, CompiledSequence, DEFAULT_BOARD_LIMITS, QualityProfile, RenderBounds, TimelineClipInput, TimelineInput, clip, compileSequence, createBoardExtensionRegistry, timeline };
+export { BOARD_CHANNELS, BoardExtensionDefinition, BoardExtensionRegistry, BoardPresetDefinition, type BoardTrackInterpolation, CompositionInput, DEFAULT_BOARD_LIMITS, ProceduralClipInput, QualityProfile, RenderBounds, SampledTrack, TrackInput, compileComposition, composition, createBoardExtensionRegistry, proceduralClip, sampleCompositionTracks, sampleEasing, sampleTrack, track };