@nebutra/atelier-canvas 1.0.0

package/src/agent/tools.ts

@@ -0,0 +1,148 @@
+/**
+ * The single agent tool that closes the loop: text prompt → generated asset
+ * → server-placed on the tenant's canvas → patch handed back for broadcast.
+ *
+ * Generation reuses the env-key-gated modality in `@nebutra/agents` (mock when
+ * no provider key is present). Placement + persistence reuse this package's
+ * own engine (relative imports — same capability, no cross-package hop).
+ *
+ * `onPlaced` lets the app broadcast the patch (e.g. via pusher) WITHOUT this
+ * package taking a realtime dependency — broadcast is a WRAP at the app layer.
+ */
+
+import {
+  type AgentTool,
+  type GenerationContext,
+  generateImage,
+  generateVideo,
+} from "@nebutra/agents";
+import { placeGeneratedAsset } from "../service";
+import type { CanvasStore, ScenePatch } from "../types";
+
+export interface AtelierToolDeps {
+  /** Tenant-scoped persistence (InMemory for demo, Prisma in prod). */
+  readonly store: CanvasStore;
+  /** Broadcast hook — invoked after the patch is durably persisted. */
+  readonly onPlaced?: (patch: ScenePatch) => void | Promise<void>;
+}
+
+interface GenerateInput {
+  canvasId: string;
+  prompt: string;
+  modality?: "image" | "video";
+  width?: number;
+  height?: number;
+  inputImages?: string[];
+  durationSeconds?: number;
+}
+
+function parseInput(raw: unknown): GenerateInput {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  if (typeof o.canvasId !== "string" || o.canvasId.length === 0) {
+    throw new Error("atelier_generate: 'canvasId' is required");
+  }
+  if (typeof o.prompt !== "string" || o.prompt.trim().length === 0) {
+    throw new Error("atelier_generate: 'prompt' is required");
+  }
+  const modality = o.modality === "video" ? "video" : "image";
+  return {
+    canvasId: o.canvasId,
+    prompt: o.prompt,
+    modality,
+    ...(typeof o.width === "number" ? { width: o.width } : {}),
+    ...(typeof o.height === "number" ? { height: o.height } : {}),
+    ...(Array.isArray(o.inputImages)
+      ? { inputImages: o.inputImages.filter((x): x is string => typeof x === "string") }
+      : {}),
+    ...(typeof o.durationSeconds === "number" ? { durationSeconds: o.durationSeconds } : {}),
+  };
+}
+
+/**
+ * Build the `atelier_generate` tool. One call = one asset (the agent loops
+ * itself for batches, per the batching rule in the system prompt).
+ */
+export function createAtelierGenerationTool(deps: AtelierToolDeps): AgentTool {
+  return {
+    name: "atelier_generate",
+    description:
+      "Generate one image or video from a prompt and place it on the canvas. " +
+      "Returns the placed element's position so you can reason about layout. " +
+      "Call once per asset; for batches, call repeatedly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        canvasId: { type: "string", description: "Target canvas id" },
+        prompt: { type: "string", description: "Detailed generation prompt" },
+        modality: { type: "string", enum: ["image", "video"] },
+        width: { type: "number" },
+        height: { type: "number" },
+        durationSeconds: { type: "number", description: "Video length (s)" },
+        inputImages: {
+          type: "array",
+          items: { type: "string" },
+          description: "Reference file ids / URLs for edits & variations",
+        },
+      },
+      required: ["canvasId", "prompt"],
+    },
+    execute: async (rawInput, context) => {
+      const input = parseInput(rawInput);
+      const genCtx: GenerationContext = {
+        tenantId: context.tenantId,
+        userId: context.userId,
+        conversationId: context.conversationId,
+      };
+
+      const result =
+        input.modality === "video"
+          ? await generateVideo(
+              {
+                prompt: input.prompt,
+                ...(input.width ? { width: input.width } : {}),
+                ...(input.height ? { height: input.height } : {}),
+                ...(input.durationSeconds ? { durationSeconds: input.durationSeconds } : {}),
+                ...(input.inputImages?.[0] ? { inputImage: input.inputImages[0] } : {}),
+              },
+              genCtx,
+            )
+          : await generateImage(
+              {
+                prompt: input.prompt,
+                ...(input.width ? { width: input.width } : {}),
+                ...(input.height ? { height: input.height } : {}),
+                ...(input.inputImages ? { inputImages: input.inputImages } : {}),
+              },
+              genCtx,
+            );
+
+      const { patch } = await placeGeneratedAsset(deps.store, context.tenantId, input.canvasId, {
+        modality: result.modality,
+        mimeType: result.mimeType,
+        url: result.url,
+        width: result.width,
+        height: result.height,
+        meta: {
+          prompt: input.prompt,
+          model: result.model,
+          provider: result.providerName,
+        },
+      });
+
+      // Persisted — now safe to broadcast.
+      await deps.onPlaced?.(patch);
+
+      return {
+        ok: true,
+        placed: {
+          elementId: patch.element.id,
+          x: patch.element.x,
+          y: patch.element.y,
+          modality: result.modality,
+        },
+        provider: result.providerName,
+        model: result.model,
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @nebutra/atelier-canvas — server-authoritative creative-canvas engine.
+ *
+ * The browser owns the rich editing surface; this package owns the two
+ * properties that make an agent-driven canvas correct under concurrency and
+ * multi-tenancy: deterministic server-side placement, and persist-then-
+ * broadcast consistency. Tenant isolation is structural — every store method
+ * is scoped by `tenantId`.
+ */
+
+export { _resetCanvasLocks, withCanvasLock } from "./lock";
+export { findNextPosition } from "./placement";
+export {
+  type GeneratedAsset,
+  placeGeneratedAsset,
+} from "./service";
+export { InMemoryCanvasStore } from "./store/memory";
+export {
+  type AtelierCanvasDelegate,
+  PrismaCanvasStore,
+  type TenantDbLike,
+} from "./store/prisma";
+export type {
+  AtelierCanvas,
+  CanvasElement,
+  CanvasElementType,
+  CanvasFile,
+  CanvasScene,
+  CanvasStore,
+  ElementSize,
+  Placement,
+  ScenePatch,
+} from "./types";

package/src/lock.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-canvas serialization.
+ *
+ * The generic per-(tenant, resource) serializer now lives in the neutral
+ * lower layer `@nebutra/tenant-store` (so `@nebutra/reel` and future
+ * tenant-scoped features share it without depending on this package). This
+ * module keeps the original `withCanvasLock` / `_resetCanvasLocks` names as
+ * thin, back-compatible aliases so existing callers (e.g. apps/web) keep
+ * working unchanged.
+ *
+ * @deprecated Import `withTenantLock` / `_resetTenantLocks` from
+ * `@nebutra/tenant-store` directly in new code. These aliases are retained
+ * only for the existing public surface.
+ */
+
+import { _resetTenantLocks, withTenantLock } from "@nebutra/tenant-store";
+
+/**
+ * Run `fn` with exclusive access to a single (tenant, canvas). Calls for the
+ * same canvas run strictly in submission order; different canvases run freely.
+ *
+ * @deprecated Use `withTenantLock` from `@nebutra/tenant-store`.
+ */
+export function withCanvasLock<T>(
+  tenantId: string,
+  canvasId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withTenantLock(tenantId, canvasId, fn);
+}
+
+/**
+ * Test helper — clears all lock chains.
+ *
+ * @deprecated Use `_resetTenantLocks` from `@nebutra/tenant-store`.
+ */
+export function _resetCanvasLocks(): void {
+  _resetTenantLocks();
+}

package/src/placement.ts

@@ -0,0 +1,67 @@
+/**
+ * Server-authoritative non-overlap placement.
+ *
+ * Ported in spirit from the source product's `find_next_best_element_position`:
+ * the server — not the client — decides where a freshly generated asset lands,
+ * so concurrent generations never stack and every client converges on the same
+ * coordinates. Deterministic given (existing elements, size, gap): identical
+ * inputs always yield the identical position, which keeps placement tests and
+ * websocket-sync reproducible.
+ */
+
+import type { CanvasElement, ElementSize, Placement } from "./types";
+
+const DEFAULT_GAP = 40;
+/** Columns scanned before wrapping to the next row. Bounds worst-case work. */
+const MAX_COLS = 12;
+
+interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+function overlaps(a: Box, b: Box, gap: number): boolean {
+  return !(
+    a.x + a.width + gap <= b.x ||
+    b.x + b.width + gap <= a.x ||
+    a.y + a.height + gap <= b.y ||
+    b.y + b.height + gap <= a.y
+  );
+}
+
+/**
+ * Find the first free top-left position for an element of `size`, scanning
+ * left→right then top→down on a grid sized to the largest existing element.
+ * Returns `{0,0}` for an empty canvas.
+ */
+export function findNextPosition(
+  existing: readonly CanvasElement[],
+  size: ElementSize,
+  gap: number = DEFAULT_GAP,
+): Placement {
+  if (existing.length === 0) return { x: 0, y: 0 };
+
+  // Step = widest/tallest placed element (+gap) so the grid never collides
+  // with large neighbours; bounded below by the incoming element's own size.
+  const stepX = Math.max(size.width, ...existing.map((e) => e.width)) + gap;
+  const stepY = Math.max(size.height, ...existing.map((e) => e.height)) + gap;
+
+  const candidate: Box = { x: 0, y: 0, width: size.width, height: size.height };
+
+  for (let row = 0; row < existing.length + 1; row++) {
+    for (let col = 0; col < MAX_COLS; col++) {
+      candidate.x = col * stepX;
+      candidate.y = row * stepY;
+      const clash = existing.some((e) =>
+        overlaps(candidate, { x: e.x, y: e.y, width: e.width, height: e.height }, gap),
+      );
+      if (!clash) return { x: candidate.x, y: candidate.y };
+    }
+  }
+
+  // Pathological fallback: drop below everything.
+  const maxBottom = Math.max(...existing.map((e) => e.y + e.height));
+  return { x: 0, y: maxBottom + gap };
+}

package/src/service.ts

@@ -0,0 +1,115 @@
+/**
+ * The write-then-broadcast placement service — the core consistency
+ * invariant absorbed from the source product.
+ *
+ * For one (tenant, canvas), under the canvas lock:
+ *   1. load the authoritative scene,
+ *   2. compute a non-overlapping position server-side,
+ *   3. append the element/file and **persist** the new scene,
+ *   4. return a {@link ScenePatch}.
+ *
+ * The caller broadcasts the returned patch over the realtime channel *after*
+ * this resolves. Persisting before broadcasting is what makes the websocket
+ * a pure optimization: a client that never receives the event recovers the
+ * identical state on reload. Reversing the order reintroduces the
+ * lost-update bug.
+ */
+
+import { logger } from "@nebutra/logger";
+import { withCanvasLock } from "./lock";
+import { findNextPosition } from "./placement";
+import type {
+  AtelierCanvas,
+  CanvasElement,
+  CanvasFile,
+  CanvasScene,
+  CanvasStore,
+  ScenePatch,
+} from "./types";
+
+const log = logger.child({ module: "atelier-canvas/service" });
+
+/** A generated asset, shaped to match `@nebutra/agents` GenerationResult. */
+export interface GeneratedAsset {
+  readonly modality: "image" | "video";
+  readonly mimeType: string;
+  readonly url: string;
+  readonly width: number;
+  readonly height: number;
+  /** Carried into element.meta for provenance (prompt, model, provider). */
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+function newId(prefix: string): string {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+/**
+ * Place a generated asset on a canvas. Creates the canvas on first write.
+ * Concurrency-safe per (tenant, canvas) via {@link withCanvasLock}.
+ */
+export async function placeGeneratedAsset(
+  store: CanvasStore,
+  tenantId: string,
+  canvasId: string,
+  asset: GeneratedAsset,
+): Promise<{ patch: ScenePatch; canvas: AtelierCanvas }> {
+  return withCanvasLock(tenantId, canvasId, async () => {
+    const current =
+      (await store.get(tenantId, canvasId)) ?? (await store.create(tenantId, canvasId, canvasId));
+
+    const position = findNextPosition(current.scene.elements, {
+      width: asset.width,
+      height: asset.height,
+    });
+
+    // Images carry a file the client resolves by id; videos embed by URL.
+    let file: CanvasFile | undefined;
+    let ref: string;
+    if (asset.modality === "image") {
+      file = { id: newId("file"), mimeType: asset.mimeType, dataURL: asset.url };
+      ref = file.id;
+    } else {
+      ref = asset.url;
+    }
+
+    const element: CanvasElement = {
+      id: newId("el"),
+      type: asset.modality === "image" ? "image" : "embeddable",
+      x: position.x,
+      y: position.y,
+      width: asset.width,
+      height: asset.height,
+      ref,
+      ...(asset.meta ? { meta: asset.meta } : {}),
+    };
+
+    const nextScene: CanvasScene = {
+      elements: [...current.scene.elements, element],
+      files: file ? [...current.scene.files, file] : current.scene.files,
+    };
+
+    // Thumbnail = latest asset (matches source product's grid-preview rule).
+    const thumbnail = asset.url;
+
+    // (3) Persist BEFORE returning — broadcast happens in the caller, after.
+    const canvas = await store.save(tenantId, canvasId, nextScene, thumbnail);
+
+    log.debug("placed generated asset", {
+      tenantId,
+      canvasId,
+      modality: asset.modality,
+      x: position.x,
+      y: position.y,
+    });
+
+    const patch: ScenePatch = {
+      canvasId,
+      tenantId,
+      element,
+      ...(file ? { file } : {}),
+      thumbnail,
+    };
+    return { patch, canvas };
+  });
+}

package/src/store/memory.ts

@@ -0,0 +1,59 @@
+/**
+ * In-memory CanvasStore — the default for tests and the flag-gated demo.
+ *
+ * Storage mechanics (tenant-keyed map, never returning rows across tenants,
+ * tenant-filtered listing) are delegated to `InMemoryTenantStore` from
+ * `@nebutra/tenant-store`; this class only adds atelier's typed `create` /
+ * `save` domain shape, mirroring what RLS does in the Prisma store.
+ */
+
+import { InMemoryTenantStore } from "@nebutra/tenant-store";
+import type { AtelierCanvas, CanvasScene, CanvasStore } from "../types";
+
+const EMPTY_SCENE: CanvasScene = { elements: [], files: [] };
+
+export class InMemoryCanvasStore implements CanvasStore {
+  private readonly base = new InMemoryTenantStore<AtelierCanvas>();
+
+  async get(tenantId: string, canvasId: string): Promise<AtelierCanvas | null> {
+    return this.base.read(tenantId, canvasId);
+  }
+
+  async create(tenantId: string, canvasId: string, name: string): Promise<AtelierCanvas> {
+    const row: AtelierCanvas = {
+      id: canvasId,
+      tenantId,
+      name,
+      scene: EMPTY_SCENE,
+      updatedAt: new Date(),
+    };
+    return this.base.write(tenantId, canvasId, row);
+  }
+
+  async save(
+    tenantId: string,
+    canvasId: string,
+    scene: CanvasScene,
+    thumbnail?: string,
+  ): Promise<AtelierCanvas> {
+    const existing = await this.base.read(tenantId, canvasId);
+    const row: AtelierCanvas = {
+      id: canvasId,
+      tenantId,
+      name: existing?.name ?? canvasId,
+      scene,
+      ...(thumbnail !== undefined ? { thumbnail } : {}),
+      updatedAt: new Date(),
+    };
+    return this.base.write(tenantId, canvasId, row);
+  }
+
+  async list(tenantId: string): Promise<readonly AtelierCanvas[]> {
+    return this.base.listByTenant(tenantId);
+  }
+
+  /** Test helper. */
+  _clear(): void {
+    this.base.clear();
+  }
+}

package/src/store/prisma.ts

@@ -0,0 +1,119 @@
+/**
+ * Prisma-backed CanvasStore — the production persistence adapter.
+ *
+ * Decoupled from `@nebutra/db`'s generated client by a narrow structural
+ * interface, so this package typechecks and tests without running
+ * `prisma generate`. Wire it in the app by passing a `getDb` that returns
+ * `getTenantDb(tenantId)` (RLS-scoped) — that is what enforces tenant
+ * isolation at the database layer; this adapter never calls `getSystemDb()`.
+ *
+ * The `AtelierCanvas` Prisma model (see packages/platform/db/prisma/
+ * schema.prisma) stores the scene as a single JSON column — the same
+ * one-blob-per-canvas shape the source product used, but with an
+ * `organization_id` column + RLS instead of an implicit single user.
+ */
+
+import type { AtelierCanvas, CanvasScene, CanvasStore } from "../types";
+
+/** Row shape as persisted (scene/files as JSON). */
+interface AtelierCanvasRow {
+  id: string;
+  organizationId: string;
+  name: string;
+  scene: unknown;
+  thumbnail: string | null;
+  updatedAt: Date;
+}
+
+/** The subset of the generated delegate this adapter needs. */
+export interface AtelierCanvasDelegate {
+  findUnique(args: {
+    where: { organizationId_id: { organizationId: string; id: string } };
+  }): Promise<AtelierCanvasRow | null>;
+  upsert(args: {
+    where: { organizationId_id: { organizationId: string; id: string } };
+    create: Omit<AtelierCanvasRow, "updatedAt">;
+    update: Partial<Omit<AtelierCanvasRow, "id" | "organizationId">>;
+  }): Promise<AtelierCanvasRow>;
+  findMany(args: { where: { organizationId: string } }): Promise<AtelierCanvasRow[]>;
+}
+
+export interface TenantDbLike {
+  atelierCanvas: AtelierCanvasDelegate;
+}
+
+const EMPTY_SCENE: CanvasScene = { elements: [], files: [] };
+
+function toDomain(row: AtelierCanvasRow): AtelierCanvas {
+  const scene =
+    row.scene && typeof row.scene === "object" ? (row.scene as CanvasScene) : EMPTY_SCENE;
+  return {
+    id: row.id,
+    tenantId: row.organizationId,
+    name: row.name,
+    scene,
+    ...(row.thumbnail ? { thumbnail: row.thumbnail } : {}),
+    updatedAt: row.updatedAt,
+  };
+}
+
+export class PrismaCanvasStore implements CanvasStore {
+  /**
+   * @param getDb returns an RLS-scoped tenant client. In the app:
+   *   `new PrismaCanvasStore((t) => getTenantDb(t) as unknown as TenantDbLike)`
+   */
+  constructor(private readonly getDb: (tenantId: string) => Promise<TenantDbLike> | TenantDbLike) {}
+
+  async get(tenantId: string, canvasId: string): Promise<AtelierCanvas | null> {
+    const db = await this.getDb(tenantId);
+    const row = await db.atelierCanvas.findUnique({
+      where: { organizationId_id: { organizationId: tenantId, id: canvasId } },
+    });
+    return row ? toDomain(row) : null;
+  }
+
+  async create(tenantId: string, canvasId: string, name: string): Promise<AtelierCanvas> {
+    const db = await this.getDb(tenantId);
+    const row = await db.atelierCanvas.upsert({
+      where: { organizationId_id: { organizationId: tenantId, id: canvasId } },
+      create: {
+        id: canvasId,
+        organizationId: tenantId,
+        name,
+        scene: EMPTY_SCENE,
+        thumbnail: null,
+      },
+      update: {},
+    });
+    return toDomain(row);
+  }
+
+  async save(
+    tenantId: string,
+    canvasId: string,
+    scene: CanvasScene,
+    thumbnail?: string,
+  ): Promise<AtelierCanvas> {
+    const db = await this.getDb(tenantId);
+    const row = await db.atelierCanvas.upsert({
+      where: { organizationId_id: { organizationId: tenantId, id: canvasId } },
+      create: {
+        id: canvasId,
+        organizationId: tenantId,
+        name: canvasId,
+        scene,
+        thumbnail: thumbnail ?? null,
+      },
+      update: { scene, thumbnail: thumbnail ?? null },
+    });
+    return toDomain(row);
+  }
+
+  async list(tenantId: string): Promise<readonly AtelierCanvas[]> {
+    const db = await this.getDb(tenantId);
+    const rows = await db.atelierCanvas.findMany({
+      where: { organizationId: tenantId },
+    });
+    return rows.map(toDomain);
+  }
+}

package/src/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Scene model for the creative canvas.
+ *
+ * A narrow, transport-stable subset of the Excalidraw element shape — enough
+ * to place agent-generated media deterministically on the server without
+ * pulling Excalidraw as a server dependency. The browser holds the full
+ * Excalidraw scene; the server is authoritative only for *placement* and
+ * *persistence*, exactly the property that makes refresh == realtime.
+ */
+
+export type CanvasElementType = "image" | "embeddable" | "text";
+
+export interface CanvasElement {
+  readonly id: string;
+  readonly type: CanvasElementType;
+  /** Top-left x in scene coordinates. */
+  readonly x: number;
+  /** Top-left y in scene coordinates. */
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  /**
+   * For `image` — a file id resolvable in `scene.files`.
+   * For `embeddable` — the media URL (video).
+   * For `text` — the literal string.
+   */
+  readonly ref: string;
+  /** Free-form, provider/agent attribution (prompt, model, etc.). */
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+export interface CanvasFile {
+  readonly id: string;
+  readonly mimeType: string;
+  /** `data:` URI or remote URL. */
+  readonly dataURL: string;
+}
+
+export interface CanvasScene {
+  readonly elements: readonly CanvasElement[];
+  readonly files: readonly CanvasFile[];
+}
+
+export interface AtelierCanvas {
+  readonly id: string;
+  /** Owning organization — every read/write is scoped by this. */
+  readonly tenantId: string;
+  readonly name: string;
+  readonly scene: CanvasScene;
+  /** Latest generated asset, for list/grid previews. */
+  readonly thumbnail?: string;
+  readonly updatedAt: Date;
+}
+
+/** Size of an element to be placed. */
+export interface ElementSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Resolved top-left position in scene coordinates. */
+export interface Placement {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * The minimal patch produced by a server-side placement. Persisted *before*
+ * it is broadcast, so the websocket message is a pure UI optimization: a
+ * client that missed it recovers the identical state on reload.
+ */
+export interface ScenePatch {
+  readonly canvasId: string;
+  readonly tenantId: string;
+  readonly element: CanvasElement;
+  readonly file?: CanvasFile;
+  readonly thumbnail?: string;
+}
+
+/** Tenant-scoped persistence boundary (repository pattern). */
+export interface CanvasStore {
+  get(tenantId: string, canvasId: string): Promise<AtelierCanvas | null>;
+  create(tenantId: string, canvasId: string, name: string): Promise<AtelierCanvas>;
+  /** Replace the persisted scene + thumbnail for a canvas. */
+  save(
+    tenantId: string,
+    canvasId: string,
+    scene: CanvasScene,
+    thumbnail?: string,
+  ): Promise<AtelierCanvas>;
+  list(tenantId: string): Promise<readonly AtelierCanvas[]>;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "types": ["node"],
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}