@dxos/plugin-illustrator 0.10.0

package/src/model/builder.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Renderer-neutral builder contract: each canvas variant (tldraw, excalidraw, …) implements
+// `SketchBuilder` to compile the scene DSL onto its concrete records and derive the scene back
+// from them. Implementations are contributed via `IllustratorCapabilities.VariantProvider`.
+//
+
+import { type Obj } from '@dxos/echo';
+
+import type * as Scene from './scene';
+
+/** A world object as derived from the canvas: placement is always resolved. */
+export type ReadWorldObject = Scene.WorldObject & { origin: Scene.Point; scale: number };
+
+export type ReadResult = {
+  scene: { objects: ReadWorldObject[] };
+  /** Shapes on the canvas not managed by the DSL (hand-drawn by users). */
+  unmanaged: number;
+};
+
+export type ApplyResult = {
+  /** Object ids created or modified. */
+  upserted: string[];
+  /** Shape records removed. */
+  removed: number;
+};
+
+/**
+ * Maps the scene DSL onto a renderer-specific canvas object.
+ * Geometry is derived from the live canvas records — not a stored copy — so the model stays
+ * coherent after users drag or resize shapes in the renderer's UI.
+ */
+export type SketchBuilder = {
+  /** Derive the neutral scene from the canvas. */
+  read: (canvas: Obj.Any) => ReadResult;
+  /** Apply a batch of edit commands atomically (implementations wrap their own `Obj.update`). */
+  apply: (canvas: Obj.Any, commands: readonly Scene.Command[]) => ApplyResult;
+};

package/src/model/dialect.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Extension point for higher-level diagram languages (mermaid, d2, sequence, uml-class, …).
+// A dialect compiles its input into scene edit commands — owning any layout it needs — so its
+// output lands as ordinary world objects and stays editable by id. Mirrors the architecture
+// shared by Mermaid/D2/Kroki: dialect → intermediate positioned model → renderer.
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { invariant } from '@dxos/invariant';
+
+import * as Scene from './scene';
+
+export type Dialect<Input = any> = {
+  id: string;
+  description: string;
+  input: Schema.Schema<Input, any>;
+  compile: (input: Input) => Effect.Effect<readonly Scene.Command[]>;
+};
+
+/** The core dialect: input is already scene edit commands (identity compile). */
+export const sceneDialect: Dialect<readonly Scene.Command[]> = {
+  id: 'scene',
+  description: 'Positioned world objects and elements; the agent does the layout.',
+  input: Schema.Array(Scene.Command),
+  compile: Effect.succeed,
+};
+
+export class DialectRegistry {
+  readonly #dialects = new Map<string, Dialect>();
+
+  constructor(dialects: Dialect[] = [sceneDialect]) {
+    dialects.forEach((dialect) => this.register(dialect));
+  }
+
+  register(dialect: Dialect): void {
+    invariant(!this.#dialects.has(dialect.id), `duplicate dialect: ${dialect.id}`);
+    this.#dialects.set(dialect.id, dialect);
+  }
+
+  get(id: string): Dialect | undefined {
+    return this.#dialects.get(id);
+  }
+
+  list(): Dialect[] {
+    return [...this.#dialects.values()];
+  }
+}

package/src/model/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './builder';
+export * from './dialect';
+export * as Scene from './scene';

package/src/model/scene.ts

@@ -0,0 +1,208 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Backend-neutral scene DSL: a diagram is a set of named world objects ("face", "hat"),
+// each composed of graphical elements (rect, ellipse, line, curve, text, arrow) authored
+// in object-local units. A backend compiler (tldraw today) maps the scene onto the
+// concrete canvas; see `render.ts` / `read.ts`.
+//
+
+import * as Schema from 'effect/Schema';
+
+export const Color = Schema.Literal(
+  'black',
+  'grey',
+  'light-violet',
+  'violet',
+  'blue',
+  'light-blue',
+  'yellow',
+  'orange',
+  'green',
+  'light-green',
+  'light-red',
+  'red',
+  'white',
+);
+export type Color = Schema.Schema.Type<typeof Color>;
+
+export const Fill = Schema.Literal('none', 'solid', 'pattern');
+export type Fill = Schema.Schema.Type<typeof Fill>;
+
+export const Stroke = Schema.Literal('sketchy', 'solid', 'dashed', 'dotted');
+export type Stroke = Schema.Schema.Type<typeof Stroke>;
+
+export const Weight = Schema.Literal('s', 'm', 'l', 'xl');
+export type Weight = Schema.Schema.Type<typeof Weight>;
+
+export const Point = Schema.Struct({
+  x: Schema.Number,
+  y: Schema.Number,
+});
+export type Point = Schema.Schema.Type<typeof Point>;
+
+/** Style props shared by all elements; every field is optional with sensible defaults. */
+const styleFields = {
+  color: Schema.optional(Color).annotations({ description: 'Stroke/text color.' }),
+  fill: Schema.optional(Fill).annotations({ description: 'Interior fill of closed shapes.' }),
+  stroke: Schema.optional(Stroke).annotations({ description: 'Stroke rendering; sketchy is hand-drawn.' }),
+  weight: Schema.optional(Weight).annotations({ description: 'Stroke weight / text size.' }),
+};
+
+const id = Schema.String.annotations({
+  description: 'Stable element id, unique within the object (e.g. "left-eye"). Used to edit or delete the element.',
+});
+
+/** Closed shape drawn inside a local bounding box. */
+export const Box = Schema.Struct({
+  kind: Schema.Literal('rect', 'ellipse', 'diamond', 'triangle'),
+  id,
+  x: Schema.Number.annotations({ description: 'Left edge (object-local units).' }),
+  y: Schema.Number.annotations({ description: 'Top edge (object-local units).' }),
+  w: Schema.Number,
+  h: Schema.Number,
+  rotation: Schema.optional(Schema.Number).annotations({ description: 'Clockwise rotation in degrees.' }),
+  text: Schema.optional(Schema.String).annotations({ description: 'Centered label.' }),
+  ...styleFields,
+});
+export type Box = Schema.Schema.Type<typeof Box>;
+
+/** Circle sugar; reads back as an ellipse. */
+export const Circle = Schema.Struct({
+  kind: Schema.Literal('circle'),
+  id,
+  cx: Schema.Number.annotations({ description: 'Center x (object-local units).' }),
+  cy: Schema.Number.annotations({ description: 'Center y (object-local units).' }),
+  r: Schema.Number,
+  text: Schema.optional(Schema.String),
+  ...styleFields,
+});
+export type Circle = Schema.Schema.Type<typeof Circle>;
+
+/** Straight segment or open polyline through the given points. */
+export const Polyline = Schema.Struct({
+  kind: Schema.Literal('line'),
+  id,
+  points: Schema.Array(Point).annotations({ description: 'Two or more points (object-local units).' }),
+  closed: Schema.optional(Schema.Boolean).annotations({ description: 'Close the path back to the first point.' }),
+  ...styleFields,
+});
+export type Polyline = Schema.Schema.Type<typeof Polyline>;
+
+/** Smooth curve through the given points (spline). */
+export const Curve = Schema.Struct({
+  kind: Schema.Literal('curve'),
+  id,
+  points: Schema.Array(Point).annotations({ description: 'Control points the curve passes through.' }),
+  ...styleFields,
+});
+export type Curve = Schema.Schema.Type<typeof Curve>;
+
+/**
+ * Circular arc sugar; reads back as a curve. Angles are degrees, measured clockwise from
+ * the positive x-axis in screen coordinates (y grows downward): 0–180 is the lower half
+ * (a smile), 180–360 the upper half (a frown).
+ */
+export const Arc = Schema.Struct({
+  kind: Schema.Literal('arc'),
+  id,
+  cx: Schema.Number,
+  cy: Schema.Number,
+  r: Schema.Number,
+  startAngle: Schema.Number,
+  endAngle: Schema.Number,
+  ...styleFields,
+});
+export type Arc = Schema.Schema.Type<typeof Arc>;
+
+/** Free-standing text. */
+export const Text = Schema.Struct({
+  kind: Schema.Literal('text'),
+  id,
+  x: Schema.Number,
+  y: Schema.Number,
+  w: Schema.optional(Schema.Number).annotations({ description: 'Wrap width; omit for auto-size.' }),
+  text: Schema.String,
+  ...styleFields,
+});
+export type Text = Schema.Schema.Type<typeof Text>;
+
+/**
+ * Connector. Endpoints are element refs — `"<elementId>"` within the same object or
+ * `"<objectId>/<elementId>"` across objects — or explicit local points. Bound endpoints
+ * track their target when it moves.
+ */
+export const Arrow = Schema.Struct({
+  kind: Schema.Literal('arrow'),
+  id,
+  from: Schema.optional(Schema.String).annotations({ description: 'Source element ref.' }),
+  to: Schema.optional(Schema.String).annotations({ description: 'Target element ref.' }),
+  start: Schema.optional(Point).annotations({ description: 'Explicit start (used when `from` is omitted).' }),
+  end: Schema.optional(Point).annotations({ description: 'Explicit end (used when `to` is omitted).' }),
+  text: Schema.optional(Schema.String).annotations({ description: 'Label at the arrow midpoint.' }),
+  ...styleFields,
+});
+export type Arrow = Schema.Schema.Type<typeof Arrow>;
+
+export const Element = Schema.Union(Box, Circle, Polyline, Curve, Arc, Text, Arrow);
+export type Element = Schema.Schema.Type<typeof Element>;
+
+/**
+ * A semantic group of elements ("face", "hat") authored in its own local unit space.
+ * `origin` (canvas px) and `scale` (px per unit) place it on the canvas:
+ * `canvas = origin + local * scale`. On read, `origin` is derived as the top-left of the
+ * object's bounding box, so the model survives users dragging shapes around.
+ */
+export const WorldObject = Schema.Struct({
+  id: Schema.String.annotations({
+    description: 'Stable object id naming the thing depicted (e.g. "face", "hat").',
+  }),
+  origin: Schema.optional(Point).annotations({
+    description: 'Canvas position (px). Omit on upsert to keep the current position.',
+  }),
+  scale: Schema.optional(Schema.Number).annotations({ description: 'Canvas px per local unit (default 1).' }),
+  elements: Schema.Array(Element),
+});
+export type WorldObject = Schema.Schema.Type<typeof WorldObject>;
+
+export const Scene = Schema.Struct({
+  objects: Schema.Array(WorldObject),
+});
+export type Scene = Schema.Schema.Type<typeof Scene>;
+
+//
+// Edit commands.
+//
+
+export const UpsertObject = Schema.Struct({
+  op: Schema.Literal('upsert-object'),
+  object: WorldObject,
+}).annotations({ description: 'Create an object, or replace an existing one wholesale (same id).' });
+
+export const UpsertElements = Schema.Struct({
+  op: Schema.Literal('upsert-elements'),
+  objectId: Schema.String,
+  elements: Schema.Array(Element),
+}).annotations({ description: 'Add elements to an existing object, replacing any with matching ids.' });
+
+export const RemoveElements = Schema.Struct({
+  op: Schema.Literal('remove-elements'),
+  objectId: Schema.String,
+  elementIds: Schema.Array(Schema.String),
+});
+
+export const RemoveObject = Schema.Struct({
+  op: Schema.Literal('remove-object'),
+  objectId: Schema.String,
+});
+
+export const MoveObject = Schema.Struct({
+  op: Schema.Literal('move-object'),
+  objectId: Schema.String,
+  origin: Point.annotations({ description: 'New canvas position (px) for the object top-left.' }),
+});
+
+export const Command = Schema.Union(UpsertObject, UpsertElements, RemoveElements, RemoveObject, MoveObject);
+export type Command = Schema.Schema.Type<typeof Command>;

package/src/operations/create.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { IllustratorCapabilities, Sketch, SketchOperation } from '../types';
+import { UnknownSketchVariantError } from '../util/load-sketch';
+
+const handler: Operation.WithHandler<typeof SketchOperation.Create> = SketchOperation.Create.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ name, variant: variantId }) {
+      const variants = yield* Capability.getAll(IllustratorCapabilities.VariantProvider);
+      const variant = variantId ? variants.find((entry) => entry.id === variantId) : variants[0];
+      if (!variant) {
+        return yield* Effect.fail(new UnknownSketchVariantError(variantId ?? '(none registered)'));
+      }
+      const canvas = yield* variant.createCanvas();
+      return { object: Sketch.make({ name, canvas }) };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/edit.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+
+import { SketchOperation } from '../types';
+import { resolveVariant } from '../util/load-sketch';
+
+const handler: Operation.WithHandler<typeof SketchOperation.Edit> = SketchOperation.Edit.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ sketch, commands }) {
+      const { canvas, variant } = yield* resolveVariant(sketch);
+      const { upserted, removed } = variant.builder.apply(canvas, commands);
+      const { scene, unmanaged } = variant.builder.read(canvas);
+      return { scene, unmanaged, upserted, removed };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const IllustratorOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./create'),
+  () => import('./edit'),
+  () => import('./read'),
+);

package/src/operations/read.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+
+import { SketchOperation } from '../types';
+import { resolveVariant } from '../util/load-sketch';
+
+const handler: Operation.WithHandler<typeof SketchOperation.Read> = SketchOperation.Read.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ sketch }) {
+      const { canvas, variant } = yield* resolveVariant(sketch);
+      return variant.builder.read(canvas);
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const IllustratorPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { IllustratorOperationHandlerSet } from './operations';

package/src/skills/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as SketchSkill } from './sketch-skill';

package/src/skills/sketch-skill.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill, Template } from '@dxos/compute';
+import { trim } from '@dxos/util';
+
+import { SketchOperation } from '#types';
+
+const SKILL_KEY = 'org.dxos.skill.sketch';
+
+const operations = [SketchOperation.Create, SketchOperation.Read, SketchOperation.Edit];
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'Sketch',
+    tools: Skill.toolDefinitions({ operations }),
+    instructions: Template.make({
+      source: trim`
+        {{! Sketch }}
+
+        You can draw and edit diagrams on a shared canvas using a scene DSL.
+
+        ## Model
+
+        A drawing is a set of WORLD OBJECTS — semantic things like "face", "hat", "server" —
+        each composed of graphical ELEMENTS (rect, ellipse, circle, diamond, triangle, line,
+        curve, arc, text, arrow). You do the layout; there is no auto-layout.
+
+        - Give objects and elements short, semantic ids ("face", "left-eye"). Ids are how you
+          edit or delete things later — choose them as carefully as variable names.
+        - Element coordinates are OBJECT-LOCAL units. Design each object in roughly a 100-unit
+          box. The object's "origin" (canvas px) and "scale" (px per unit) place it on the
+          canvas: canvas = origin + local * scale. Prefer scale 2-3 for a primary subject.
+        - Screen coordinates: x grows right, y grows DOWN. Arc angles are degrees clockwise
+          from the +x axis: startAngle 30, endAngle 150 bulges downward (a smile);
+          210 to 330 bulges upward (a frown).
+        - Circle is sugar for ellipse (reads back as ellipse); arc is sugar for curve.
+        - Arrows can bind to elements: from/to is an element id in the same object, or
+          "objectId/elementId" across objects. Bound arrows track their targets.
+        - Styles: color (named palette), fill (none | solid | pattern),
+          stroke (sketchy | solid | dashed | dotted), weight (s | m | l | xl).
+
+        ## Workflow
+
+        1. If no sketch exists in context, create one first.
+        2. ALWAYS call read before editing an existing sketch — it returns the scene as you
+           (or the user) last left it, with origins derived from the live canvas, so it stays
+           correct even after the user drags shapes around. Note "unmanaged" counts shapes the
+           user drew by hand that are not part of the scene.
+        3. Edit with commands, in one batch where possible:
+           - upsert-object: create a new object, or redraw one wholesale.
+           - upsert-elements: add or replace specific elements of an object — prefer this for
+             incremental changes ("make the smile bigger" replaces only "smile").
+           - remove-elements / remove-object: delete by id.
+           - move-object: reposition an object (canvas px) without resending its elements.
+        4. Compose scenes from multiple objects: "add a hat" means a NEW "hat" object placed
+           relative to the existing object's origin and size (from read) — do not redraw the
+           existing object.
+      `,
+    }),
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/translations.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Type } from '@dxos/echo';
+import { type Resource } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+import { Sketch } from '#types';
+
+export const translations = [
+  {
+    'en-US': {
+      [Type.getTypename(Sketch.Sketch)]: {
+        'typename.label': 'Sketch',
+        'typename.label_zero': 'Sketches',
+        'typename.label_one': 'Sketch',
+        'typename.label_other': 'Sketches',
+        'object-name.placeholder': 'New sketch',
+        'add-object.label': 'Add sketch',
+        'rename-object.label': 'Rename sketch',
+        'delete-object.label': 'Delete sketch',
+        'object-deleted.label': 'Sketch deleted',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'Illustrator',
+        'create-panel.variant.label': 'Select renderer',
+        'create-panel.variant.placeholder': 'Search renderers...',
+        'unsupported-variant.label': 'Unsupported sketch variant',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/IllustratorCapabilities.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+import type { SketchVariant } from './types';
+
+/**
+ * A sketch variant contribution. Each renderer plugin (tldraw, excalidraw, ...)
+ * contributes one of these via `Capability.contributes(IllustratorCapabilities.VariantProvider, variant)`.
+ * Consumers iterate via `Capability.getAll(IllustratorCapabilities.VariantProvider)` (Effect) or
+ * `useCapabilities(IllustratorCapabilities.VariantProvider)` (React).
+ */
+export const VariantProvider = Capability.make<SketchVariant>(`${meta.profile.key}.capability.variant`);

package/src/types/Sketch.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+import { CardAnnotation, CollectionItemAnnotation } from '@dxos/schema';
+
+/**
+ * Base Sketch object. Renderer-specific canvas data lives in a separate referenced object.
+ * Unifies all canvas renderers (tldraw, excalidraw, ...) under one typename so they share
+ * graph node, create flow, and shared surface scaffolding.
+ */
+export class Sketch extends Type.makeObject<Sketch>(DXN.make('org.dxos.type.sketch', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    canvas: Ref.Ref(Obj.Unknown)
+      .annotations({ description: 'Reference to the renderer-specific canvas object.' })
+      .pipe(FormInputAnnotation.set(false)),
+  }).pipe(
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--compass-tool--regular', hue: 'indigo' }),
+    CardAnnotation.set(true),
+    CollectionItemAnnotation.set(true),
+  ),
+) {}
+
+/**
+ * Variant-narrowed reference to a Sketch.
+ *
+ * Encodes — at the type level — that the canvas ref points to a specific canvas type.
+ * Runtime narrowing is performed by `loadSketch(ref, canvasType)` which validates and
+ * returns the resolved Sketch together with its typed canvas.
+ *
+ * @example
+ * ```ts
+ * input: Schema.Struct({
+ *   sketch: SketchRef(Tldraw.Canvas),
+ * }),
+ * // handler:
+ * const { sketch, canvas } = yield* loadSketch(input.sketch, Tldraw.Canvas);
+ * // `canvas` is typed as Tldraw.Canvas.
+ * ```
+ */
+export type SketchRef<_V> = Ref.Ref<Sketch>;
+
+export const SketchRef = <S extends Type.AnyObj>(_canvasType: S) =>
+  Ref.Ref(Sketch) as Schema.Schema<SketchRef<Type.InstanceType<S>>, any, never>;
+
+/**
+ * Build a base `Sketch` object referencing the given canvas ECHO object.
+ *
+ * The canvas is stored as a `Ref` so the renderer-specific data (e.g. `Tldraw.Canvas`,
+ * `Excalidraw.Canvas`) lives as its own ECHO object alongside the Sketch.
+ *
+ * @param name Optional display name shown in the graph node and Properties form.
+ * @param canvas Renderer-specific canvas object.
+ * @returns A new `Sketch` object with `canvas` stored as a Ref.
+ */
+export const make = ({ name, canvas }: { name?: string; canvas: Obj.Unknown }): Sketch => {
+  return Obj.make(Sketch, { name, canvas: Ref.make(canvas) });
+};
+
+/** Type guard for {@link Sketch} objects. */
+export const isSketch = (object: unknown): object is Sketch => Obj.instanceOf(Sketch, object);