@nebutra/atelier-canvas 1.0.0

package/dist/store/memory.d.ts

@@ -0,0 +1,22 @@
+import { a as CanvasStore, A as AtelierCanvas, d as CanvasScene } from '../types-Dw9o09h2.js';
+
+/**
+ * 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.
+ */
+
+declare class InMemoryCanvasStore implements CanvasStore {
+    private readonly base;
+    get(tenantId: string, canvasId: string): Promise<AtelierCanvas | null>;
+    create(tenantId: string, canvasId: string, name: string): Promise<AtelierCanvas>;
+    save(tenantId: string, canvasId: string, scene: CanvasScene, thumbnail?: string): Promise<AtelierCanvas>;
+    list(tenantId: string): Promise<readonly AtelierCanvas[]>;
+    /** Test helper. */
+    _clear(): void;
+}
+
+export { InMemoryCanvasStore };

package/dist/store/memory.js

@@ -0,0 +1,7 @@
+import {
+  InMemoryCanvasStore
+} from "../chunk-AVQEQBLX.js";
+export {
+  InMemoryCanvasStore
+};
+//# sourceMappingURL=memory.js.map

package/dist/store/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/store/prisma.d.ts

@@ -0,0 +1,69 @@
+import { a as CanvasStore, A as AtelierCanvas, d as CanvasScene } from '../types-Dw9o09h2.js';
+
+/**
+ * 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.
+ */
+
+/** 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. */
+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[]>;
+}
+interface TenantDbLike {
+    atelierCanvas: AtelierCanvasDelegate;
+}
+declare class PrismaCanvasStore implements CanvasStore {
+    private readonly getDb;
+    /**
+     * @param getDb returns an RLS-scoped tenant client. In the app:
+     *   `new PrismaCanvasStore((t) => getTenantDb(t) as unknown as TenantDbLike)`
+     */
+    constructor(getDb: (tenantId: string) => Promise<TenantDbLike> | TenantDbLike);
+    get(tenantId: string, canvasId: string): Promise<AtelierCanvas | null>;
+    create(tenantId: string, canvasId: string, name: string): Promise<AtelierCanvas>;
+    save(tenantId: string, canvasId: string, scene: CanvasScene, thumbnail?: string): Promise<AtelierCanvas>;
+    list(tenantId: string): Promise<readonly AtelierCanvas[]>;
+}
+
+export { type AtelierCanvasDelegate, PrismaCanvasStore, type TenantDbLike };

package/dist/store/prisma.js

@@ -0,0 +1,7 @@
+import {
+  PrismaCanvasStore
+} from "../chunk-X5VVODXM.js";
+export {
+  PrismaCanvasStore
+};
+//# sourceMappingURL=prisma.js.map

package/dist/store/prisma.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-Dw9o09h2.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+type CanvasElementType = "image" | "embeddable" | "text";
+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>>;
+}
+interface CanvasFile {
+    readonly id: string;
+    readonly mimeType: string;
+    /** `data:` URI or remote URL. */
+    readonly dataURL: string;
+}
+interface CanvasScene {
+    readonly elements: readonly CanvasElement[];
+    readonly files: readonly CanvasFile[];
+}
+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. */
+interface ElementSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Resolved top-left position in scene coordinates. */
+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.
+ */
+interface ScenePatch {
+    readonly canvasId: string;
+    readonly tenantId: string;
+    readonly element: CanvasElement;
+    readonly file?: CanvasFile;
+    readonly thumbnail?: string;
+}
+/** Tenant-scoped persistence boundary (repository pattern). */
+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[]>;
+}
+
+export type { AtelierCanvas as A, CanvasElement as C, ElementSize as E, Placement as P, ScenePatch as S, CanvasStore as a, CanvasElementType as b, CanvasFile as c, CanvasScene as d };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nebutra/atelier-canvas",
+  "version": "1.0.0",
+  "description": "Server-authoritative creative-canvas engine: scene model, non-overlap placement, write-then-broadcast consistency, tenant-scoped locking",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "featureId": "atelier-canvas",
+    "category": "ai",
+    "summary": "Server-authoritative creative-canvas engine"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./store/memory": "./src/store/memory.ts",
+    "./store/prisma": "./src/store/prisma.ts",
+    "./agent": "./src/agent/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/logger": "0.1.0",
+    "@nebutra/tenant-store": "0.2.0"
+  },
+  "peerDependencies": {
+    "@nebutra/agents": "1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@nebutra/agents": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@nebutra/agents": "1.1.0"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/atelier-canvas#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/atelier-canvas"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/atelier-canvas.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Canvas engine: deterministic placement, tenant isolation, write-then-
+ * broadcast consistency, and per-canvas serialization.
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { _resetCanvasLocks } from "../lock";
+import { findNextPosition } from "../placement";
+import { type GeneratedAsset, placeGeneratedAsset } from "../service";
+import { InMemoryCanvasStore } from "../store/memory";
+import type { CanvasElement } from "../types";
+
+const img = (over: Partial<GeneratedAsset> = {}): GeneratedAsset => ({
+  modality: "image",
+  mimeType: "image/svg+xml",
+  url: "data:image/svg+xml;base64,AAAA",
+  width: 512,
+  height: 512,
+  ...over,
+});
+
+beforeEach(() => {
+  _resetCanvasLocks();
+});
+
+describe("findNextPosition", () => {
+  it("places the first element at the origin", () => {
+    expect(findNextPosition([], { width: 100, height: 100 })).toEqual({ x: 0, y: 0 });
+  });
+
+  it("never overlaps an existing element (respects gap)", () => {
+    const existing: CanvasElement[] = [
+      { id: "a", type: "image", x: 0, y: 0, width: 200, height: 200, ref: "f" },
+    ];
+    const p = findNextPosition(existing, { width: 200, height: 200 });
+    const clash = p.x < 200 + 40 && p.x + 200 + 40 > 0 && p.y < 200 + 40 && p.y + 200 + 40 > 0;
+    expect(clash).toBe(false);
+  });
+
+  it("is deterministic for identical input", () => {
+    const existing: CanvasElement[] = [
+      { id: "a", type: "image", x: 0, y: 0, width: 300, height: 100, ref: "f" },
+    ];
+    const a = findNextPosition(existing, { width: 100, height: 100 });
+    const b = findNextPosition(existing, { width: 100, height: 100 });
+    expect(a).toEqual(b);
+  });
+});
+
+describe("placeGeneratedAsset", () => {
+  it("persists before returning the patch (scene is durable)", async () => {
+    const store = new InMemoryCanvasStore();
+    const { patch } = await placeGeneratedAsset(store, "org_1", "c1", img());
+
+    const reloaded = await store.get("org_1", "c1");
+    expect(reloaded?.scene.elements).toHaveLength(1);
+    expect(reloaded?.scene.elements[0]?.id).toBe(patch.element.id);
+    expect(reloaded?.scene.files).toHaveLength(1);
+    expect(reloaded?.thumbnail).toBe(patch.thumbnail);
+  });
+
+  it("isolates canvases by tenant", async () => {
+    const store = new InMemoryCanvasStore();
+    await placeGeneratedAsset(store, "org_a", "shared-id", img());
+    await placeGeneratedAsset(store, "org_b", "shared-id", img());
+
+    expect((await store.get("org_a", "shared-id"))?.scene.elements).toHaveLength(1);
+    expect(await store.list("org_a")).toHaveLength(1);
+    expect(await store.list("org_b")).toHaveLength(1);
+  });
+
+  it("embeds video by URL (no file entry)", async () => {
+    const store = new InMemoryCanvasStore();
+    const { patch } = await placeGeneratedAsset(
+      store,
+      "org_1",
+      "c1",
+      img({ modality: "video", url: "https://x.test/v.mp4", mimeType: "video/mp4" }),
+    );
+    expect(patch.element.type).toBe("embeddable");
+    expect(patch.element.ref).toBe("https://x.test/v.mp4");
+    expect(patch.file).toBeUndefined();
+  });
+
+  it("serializes concurrent placements on the same canvas (no stacking)", async () => {
+    const store = new InMemoryCanvasStore();
+    await Promise.all(
+      Array.from({ length: 6 }, () => placeGeneratedAsset(store, "org_1", "c1", img())),
+    );
+    const scene = (await store.get("org_1", "c1"))?.scene;
+    expect(scene?.elements).toHaveLength(6);
+    // Every element occupies a distinct position.
+    const positions = new Set(scene?.elements.map((e) => `${e.x},${e.y}`));
+    expect(positions.size).toBe(6);
+  });
+});

package/src/agent/__tests__/agent.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The /agent subpath closes the loop end-to-end (mock provider): prompt →
+ * asset → server placement → durable scene → broadcast hook. Importing this
+ * module pulls @nebutra/agents (optional peer); the core export does not.
+ */
+
+import { createAgentContext } from "@nebutra/agents";
+import { describe, expect, it } from "vitest";
+import { InMemoryCanvasStore } from "../../store/memory";
+import type { ScenePatch } from "../../types";
+import { createAtelierAgent } from "../agent";
+import { ATELIER_SYSTEM_PROMPT } from "../prompts";
+import { createAtelierGenerationTool } from "../tools";
+
+const ctx = createAgentContext("org_1", "user_1", "conv_1");
+
+describe("atelier system prompt", () => {
+  it("encodes the absorbed creative invariants", () => {
+    expect(ATELIER_SYSTEM_PROMPT).toContain("Design Strategy");
+    expect(ATELIER_SYSTEM_PROMPT).toContain("QUANTITY IS A CONTRACT");
+    expect(ATELIER_SYSTEM_PROMPT).toContain("batches of at most 10");
+    expect(ATELIER_SYSTEM_PROMPT).toContain("input_images");
+  });
+});
+
+describe("createAtelierGenerationTool", () => {
+  it("generates, places, persists, then fires the broadcast hook", async () => {
+    const store = new InMemoryCanvasStore();
+    const broadcasts: ScenePatch[] = [];
+    const tool = createAtelierGenerationTool({
+      store,
+      onPlaced: (p) => {
+        broadcasts.push(p);
+      },
+    });
+
+    const out = (await tool.execute(
+      { canvasId: "c1", prompt: "a serene alpine lake at dawn" },
+      ctx,
+    )) as { ok: boolean; placed: { elementId: string; modality: string } };
+
+    expect(out.ok).toBe(true);
+    expect(out.placed.modality).toBe("image");
+
+    const canvas = await store.get("org_1", "c1");
+    expect(canvas?.scene.elements).toHaveLength(1);
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.element.id).toBe(out.placed.elementId);
+  });
+
+  it("rejects missing required input", async () => {
+    const tool = createAtelierGenerationTool({ store: new InMemoryCanvasStore() });
+    await expect(tool.execute({ canvasId: "c1" }, ctx)).rejects.toThrow("prompt");
+    await expect(tool.execute({ prompt: "x" }, ctx)).rejects.toThrow("canvasId");
+  });
+
+  it("places video as an embeddable (no file)", async () => {
+    const store = new InMemoryCanvasStore();
+    const tool = createAtelierGenerationTool({ store });
+    await tool.execute({ canvasId: "c1", prompt: "loop of falling snow", modality: "video" }, ctx);
+    const el = (await store.get("org_1", "c1"))?.scene.elements[0];
+    expect(el?.type).toBe("embeddable");
+  });
+});
+
+describe("createAtelierAgent", () => {
+  it("produces a single-tool AgentConfig carrying the strategy prompt", () => {
+    const agent = createAtelierAgent({ store: new InMemoryCanvasStore() });
+    expect(agent.id).toBe("atelier");
+    expect(agent.tools).toHaveLength(1);
+    expect(agent.tools?.[0]?.name).toBe("atelier_generate");
+    expect(agent.instructions).toBe(ATELIER_SYSTEM_PROMPT);
+  });
+});

package/src/agent/agent.ts

@@ -0,0 +1,34 @@
+/**
+ * The creative-canvas agent, as a single Sailor `AgentConfig`.
+ *
+ * The source product ran a two-node LangGraph swarm (planner ⇄ creator). Both
+ * roles are expressed here as one prompt with two phases plus one tool — the
+ * planner/creator split was orchestration overhead, not product value, and
+ * Sailor's `BaseAgent` tool-loop already provides the step iteration the swarm
+ * was emulating. `maxSteps` is the `@nebutra/agents` AgentConfig field (the
+ * provider maps it to `stopWhen: stepCountIs(...)` internally) — not an AI SDK
+ * option.
+ */
+
+import type { AgentConfig } from "@nebutra/agents";
+import { ATELIER_SYSTEM_PROMPT } from "./prompts";
+import { type AtelierToolDeps, createAtelierGenerationTool } from "./tools";
+
+export interface CreateAtelierAgentOptions extends AtelierToolDeps {
+  /** Model id / preset. Defaults to the "flagship" preset. */
+  readonly model?: string;
+  /** Max tool-loop iterations (batch generation needs headroom). */
+  readonly maxSteps?: number;
+}
+
+export function createAtelierAgent(opts: CreateAtelierAgentOptions): AgentConfig {
+  return {
+    id: "atelier",
+    name: "Atelier",
+    description: "Plans and generates images/videos onto a creative canvas from a brief.",
+    model: opts.model ?? "flagship",
+    instructions: ATELIER_SYSTEM_PROMPT,
+    tools: [createAtelierGenerationTool(opts)],
+    maxSteps: opts.maxSteps ?? 30,
+  };
+}

package/src/agent/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @nebutra/atelier-canvas/agent — the canvas capability's agent face.
+ *
+ * Opt-in subpath: importing it pulls `@nebutra/agents` (an optional peer);
+ * the package's core export (placement / store / consistency) stays free of
+ * any agents dependency. This is a *consumer* of the agents runtime — it
+ * yields an `AgentConfig` — never a runtime parallel to it.
+ */
+
+export { type CreateAtelierAgentOptions, createAtelierAgent } from "./agent";
+export {
+  ATELIER_CREATOR_RULES,
+  ATELIER_PLANNER_RULES,
+  ATELIER_SYSTEM_PROMPT,
+} from "./prompts";
+export { type AtelierToolDeps, createAtelierGenerationTool } from "./tools";

package/src/agent/prompts.ts

@@ -0,0 +1,64 @@
+/**
+ * The creative-direction prompt strategy.
+ *
+ * This is the differentiated IP absorbed from the source product, re-expressed
+ * in Sailor's voice: a two-phase loop (plan → create), a structured "Design
+ * Strategy" the model must author before generating, and the operational
+ * invariants that make multi-asset generation reliable — exact-quantity
+ * preservation, bounded batches, reference-image parsing, and act-without-
+ * asking. These rules, not the model choice, are what make output consistent.
+ *
+ * Lives under the `/agent` subpath, not a package parallel to
+ * `@nebutra/agents`: it produces an `AgentConfig` *consumed by* the agents
+ * runtime, it is not a second runtime.
+ */
+
+/** Phase 1 — decompose intent into an ordered plan. */
+export const ATELIER_PLANNER_RULES = `\
+You are a creative-canvas director. Reply in the SAME LANGUAGE as the user.
+
+PLAN FIRST:
+- For any multi-step request, write a short ordered plan (high-level steps)
+  before generating anything. For a single image with no extra steps, a plan
+  is optional.
+- Then proceed to generate immediately. Do NOT ask the user to approve the
+  plan — acting is expected.
+
+QUANTITY IS A CONTRACT:
+- If the user states a count ("20 images", "make 15 frames"), carry that
+  EXACT number through the plan and the generation calls. Never silently
+  change or drop it. If no count is given, assume 1.`;
+
+/** Phase 2 — author a design strategy, then generate. */
+export const ATELIER_CREATOR_RULES = `\
+BEFORE GENERATING AN IMAGE, author a brief Design Strategy in the user's
+language covering, as bullets:
+  • Recommended resolution (and why it fits the use case)
+  • Style & mood
+  • Key visual element(s)
+  • Composition & layout
+  • Colour palette (concrete values)
+  • Typography (only if the piece carries text)
+
+Then call the generation tool with ONE detailed, professional prompt derived
+from that strategy. The strategy is scaffolding for the prompt — keep it tight,
+not an essay.
+
+REFERENCE IMAGES:
+- The user message may carry references as XML:
+  <input_images><image file_id="..."/></input_images>
+- When present, extract every file_id and pass them to the tool's
+  \`inputImages\` argument so edits/variations are grounded in the source.
+
+BATCHING:
+- Need more than 10 assets? Generate in batches of at most 10, finishing and
+  acknowledging each batch ("Batch 1 of 3 done") before starting the next.
+
+VIDEO:
+- For video, you may first generate the key still(s) and animate from them, or
+  generate directly from a text prompt — choose what the brief implies.`;
+
+/** Composed system prompt for a single-agent creative-canvas operator. */
+export const ATELIER_SYSTEM_PROMPT = `${ATELIER_PLANNER_RULES}
+
+${ATELIER_CREATOR_RULES}`;