@dxos/plugin-tldraw 0.10.0

package/src/model/read.ts

@@ -0,0 +1,203 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Derives the neutral scene from tldraw records. Geometry is read from the live records —
+// not from a stored copy — so the agent's mental model stays coherent after users drag or
+// resize shapes in the UI. An object's `origin` is the top-left of its bounding box.
+//
+
+import { type ReadResult, type ReadWorldObject, type Scene } from '@dxos/plugin-illustrator/model';
+
+import { type ExternalBox } from './render';
+import { type CanvasContent } from './TldrawBuilder';
+
+type ShapeRecord = Record<string, any>;
+
+/** Read the derived scene from canvas content. */
+export const readScene = (content: CanvasContent): ReadResult => {
+  const groups = new Map<string, ShapeRecord[]>();
+  let unmanaged = 0;
+  for (const record of Object.values(content ?? {})) {
+    if (record?.typeName !== 'shape') {
+      continue;
+    }
+    const objectId = record.meta?.object;
+    if (typeof objectId !== 'string' || typeof record.meta?.element !== 'string') {
+      unmanaged++;
+      continue;
+    }
+    groups.set(objectId, [...(groups.get(objectId) ?? []), record]);
+  }
+
+  const objects = [...groups.entries()].map(([objectId, records]) => readObject(objectId, records, content));
+  return { scene: { objects }, unmanaged };
+};
+
+/** Canvas-px bounding boxes of all managed elements, keyed by `objectId/elementId`. */
+export const elementBoxes = (content: CanvasContent): Record<string, ExternalBox> => {
+  const boxes: Record<string, ExternalBox> = {};
+  for (const record of Object.values(content ?? {})) {
+    if (record?.typeName === 'shape' && record.meta?.object && record.meta?.element) {
+      boxes[`${record.meta.object}/${record.meta.element}`] = bounds(record);
+    }
+  }
+  return boxes;
+};
+
+const readObject = (objectId: string, records: ShapeRecord[], content: CanvasContent): ReadWorldObject => {
+  const scale = records.find((record) => typeof record.meta?.scale === 'number')?.meta.scale ?? 1;
+  const origin = {
+    x: Math.min(...records.map((record) => bounds(record).x)),
+    y: Math.min(...records.map((record) => bounds(record).y)),
+  };
+  const local = (abs: { x: number; y: number }): Scene.Point => ({
+    x: round((abs.x - origin.x) / scale),
+    y: round((abs.y - origin.y) / scale),
+  });
+  const length = (px: number) => round(px / scale);
+
+  const elements = records
+    .map((record) => readElement(record, { local, length, objectId, content }))
+    .filter((element): element is Scene.Element => element !== undefined);
+
+  return { id: objectId, origin, scale, elements };
+};
+
+type ReadContext = {
+  local: (abs: { x: number; y: number }) => Scene.Point;
+  length: (px: number) => number;
+  objectId: string;
+  content: CanvasContent;
+};
+
+const readElement = (record: ShapeRecord, ctx: ReadContext): Scene.Element | undefined => {
+  const id = record.meta.element;
+  const kind = record.meta.kind;
+  switch (record.type) {
+    case 'geo': {
+      const boxKind = kind === 'rect' || kind === 'diamond' || kind === 'triangle' ? kind : 'ellipse';
+      return {
+        kind: boxKind,
+        id,
+        ...ctx.local({ x: record.x, y: record.y }),
+        w: ctx.length(record.props.w),
+        h: ctx.length(record.props.h),
+        ...(record.rotation ? { rotation: round((record.rotation * 180) / Math.PI) } : {}),
+        ...(record.props.text ? { text: record.props.text } : {}),
+        ...readStyle(record),
+      };
+    }
+    case 'text': {
+      return {
+        kind: 'text',
+        id,
+        ...ctx.local({ x: record.x, y: record.y }),
+        ...(record.props.autoSize ? {} : { w: ctx.length(record.props.w) }),
+        text: record.props.text ?? '',
+        ...readStyle(record),
+      };
+    }
+    case 'line': {
+      const points = linePoints(record).map((point) => ctx.local({ x: record.x + point.x, y: record.y + point.y }));
+      if (kind === 'curve') {
+        return { kind: 'curve', id, points, ...readStyle(record) };
+      }
+      const closed =
+        points.length > 2 && points[0].x === points[points.length - 1].x && points[0].y === points[points.length - 1].y;
+      return {
+        kind: 'line',
+        id,
+        points: closed ? points.slice(0, -1) : points,
+        ...(closed ? { closed: true } : {}),
+        ...readStyle(record),
+      };
+    }
+    case 'arrow': {
+      const { from, to } = arrowRefs(record, ctx);
+      return {
+        kind: 'arrow',
+        id,
+        ...(from
+          ? { from }
+          : { start: ctx.local({ x: record.x + record.props.start.x, y: record.y + record.props.start.y }) }),
+        ...(to ? { to } : { end: ctx.local({ x: record.x + record.props.end.x, y: record.y + record.props.end.y }) }),
+        ...(record.props.text ? { text: record.props.text } : {}),
+        ...readStyle(record),
+      };
+    }
+    default:
+      return undefined;
+  }
+};
+
+/** Resolve arrow terminal bindings back to element refs (same-object refs are shortened). */
+const arrowRefs = (record: ShapeRecord, ctx: ReadContext): { from?: string; to?: string } => {
+  const refs: { from?: string; to?: string } = {};
+  for (const binding of Object.values(ctx.content ?? {})) {
+    if (binding?.typeName !== 'binding' || binding.fromId !== record.id) {
+      continue;
+    }
+    const target = ctx.content[binding.toId];
+    if (!target?.meta?.object || !target?.meta?.element) {
+      continue;
+    }
+    const ref =
+      target.meta.object === ctx.objectId ? target.meta.element : `${target.meta.object}/${target.meta.element}`;
+    if (binding.props?.terminal === 'start') {
+      refs.from = ref;
+    } else {
+      refs.to = ref;
+    }
+  }
+  return refs;
+};
+
+/** Report only non-default styles to keep the read output compact. */
+const readStyle = (record: ShapeRecord): Partial<Pick<Scene.Box, 'color' | 'fill' | 'stroke' | 'weight'>> => {
+  const { color, fill, dash, size } = record.props;
+  return {
+    ...(color && color !== 'black' ? { color } : {}),
+    ...(fill && fill !== 'none' ? { fill: fill === 'pattern' ? ('pattern' as const) : ('solid' as const) } : {}),
+    ...(dash && dash !== 'draw' ? { stroke: dash as Scene.Stroke } : {}),
+    ...(size && size !== 'm' ? { weight: size as Scene.Weight } : {}),
+  };
+};
+
+const linePoints = (record: ShapeRecord): { x: number; y: number }[] =>
+  Object.values(record.props.points ?? {})
+    // Indexes are `a<n>` fractional keys; numeric compare so `a10` sorts after `a2`.
+    .sort((a: any, b: any) => Number(String(a.index).slice(1)) - Number(String(b.index).slice(1)))
+    .map((point: any) => ({ x: point.x, y: point.y }));
+
+/** Bounding box of a shape record in canvas px. */
+const bounds = (record: ShapeRecord): ExternalBox => {
+  switch (record.type) {
+    case 'geo':
+      return { x: record.x, y: record.y, w: record.props.w, h: record.props.h };
+    case 'text':
+      return { x: record.x, y: record.y, w: record.props.w ?? 0, h: 0 };
+    case 'line': {
+      const points = linePoints(record);
+      const xs = points.map((point) => record.x + point.x);
+      const ys = points.map((point) => record.y + point.y);
+      return boxFrom(xs, ys);
+    }
+    case 'arrow': {
+      const xs = [record.x + record.props.start.x, record.x + record.props.end.x];
+      const ys = [record.y + record.props.start.y, record.y + record.props.end.y];
+      return boxFrom(xs, ys);
+    }
+    default:
+      return { x: record.x ?? 0, y: record.y ?? 0, w: record.props?.w ?? 0, h: record.props?.h ?? 0 };
+  }
+};
+
+const boxFrom = (xs: number[], ys: number[]): ExternalBox => {
+  const x = Math.min(...xs);
+  const y = Math.min(...ys);
+  return { x, y, w: Math.max(...xs) - x, h: Math.max(...ys) - y };
+};
+
+const round = (value: number) => Math.round(value * 100) / 100;

package/src/model/render.ts

@@ -0,0 +1,191 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// tldraw backend for the scene DSL: compiles a `WorldObject` into tldraw records.
+// Element identity is stamped into each record's `meta` (`{ object, element, kind, scale }`)
+// so `read.ts` can reconstruct the scene and edits can address records by id.
+//
+
+import { Scene } from '@dxos/plugin-illustrator/model';
+
+import {
+  type CanvasContent,
+  type ConnectorProps,
+  type Dash,
+  type Fill,
+  type PathProps,
+  type Point,
+  type ShapeProps,
+  TldrawBuilder,
+} from './TldrawBuilder';
+
+export const DEFAULT_SCALE = 1;
+
+/** Canvas-px bounding box of an existing element another object's arrow may bind to. */
+export type ExternalBox = { x: number; y: number; w: number; h: number };
+
+export type RenderOptions = {
+  origin: Scene.Point;
+  scale: number;
+  /** Fractional-index seed past the existing canvas content. */
+  indexStart: number;
+  /** Bounding boxes of existing elements, keyed by `objectId/elementId` (canvas px). */
+  external?: Record<string, ExternalBox>;
+  dialect?: string;
+};
+
+/** Stable record id for an element: `shape:<objectId>/<elementId>`. */
+export const shapeId = (objectId: string, elementId: string) => `shape:${objectId}/${elementId}`;
+
+const strokeToDash: Record<Scene.Stroke, Dash> = {
+  sketchy: 'draw',
+  solid: 'solid',
+  dashed: 'dashed',
+  dotted: 'dotted',
+};
+
+const fillToFill: Record<Scene.Fill, Fill> = {
+  none: 'none',
+  solid: 'solid',
+  pattern: 'pattern',
+};
+
+const boxKindToGeo = {
+  rect: 'rectangle',
+  ellipse: 'ellipse',
+  diamond: 'diamond',
+  triangle: 'triangle',
+} as const;
+
+const style = (element: Scene.Element): Pick<ShapeProps, 'color' | 'fill' | 'dash' | 'size'> => ({
+  color: element.color,
+  fill: 'fill' in element && element.fill ? fillToFill[element.fill] : undefined,
+  dash: element.stroke ? strokeToDash[element.stroke] : undefined,
+  size: element.weight,
+});
+
+/**
+ * Compile one world object into tldraw records (canvas-px coordinates).
+ * Local coordinates are mapped via `canvas = origin + local * scale`.
+ */
+export const renderObject = (object: Scene.WorldObject, options: RenderOptions): CanvasContent => {
+  const { origin, scale, indexStart, external = {}, dialect = 'scene' } = options;
+  const point = (local: Scene.Point | { x: number; y: number }): Point => ({
+    x: origin.x + local.x * scale,
+    y: origin.y + local.y * scale,
+  });
+  const length = (units: number) => units * scale;
+
+  const kinds = new Map<string, string>();
+  const builder = new TldrawBuilder({
+    indexStart,
+    metaFor: (handle) => {
+      const [objectId, elementId] = splitHandle(handle);
+      return { object: objectId, element: elementId, kind: kinds.get(handle), scale, dialect };
+    },
+  });
+
+  // Register existing canvas elements so arrows can bind across objects.
+  for (const [handle, box] of Object.entries(external)) {
+    builder.external(handle, box);
+  }
+
+  // Refs are element ids within this object, or `objectId/elementId` across objects.
+  const ref = (value: string) => (value.includes('/') ? value : `${object.id}/${value}`);
+
+  for (const element of object.elements) {
+    const handle = `${object.id}/${element.id}`;
+    kinds.set(handle, element.kind);
+    switch (element.kind) {
+      case 'rect':
+      case 'ellipse':
+      case 'diamond':
+      case 'triangle': {
+        builder.geo(boxKindToGeo[element.kind], {
+          id: handle,
+          ...point(element),
+          w: length(element.w),
+          h: length(element.h),
+          rotation: element.rotation !== undefined ? (element.rotation * Math.PI) / 180 : undefined,
+          text: element.text,
+          ...style(element),
+        });
+        break;
+      }
+      case 'circle': {
+        kinds.set(handle, 'ellipse');
+        builder.circle({
+          id: handle,
+          ...point({ x: element.cx - element.r, y: element.cy - element.r }),
+          w: length(element.r * 2),
+          text: element.text,
+          ...style(element),
+        });
+        break;
+      }
+      case 'line': {
+        const props: PathProps = {
+          id: handle,
+          points: element.points.map(point),
+          closed: element.closed,
+          ...style(element),
+        };
+        builder.path(props);
+        break;
+      }
+      case 'curve': {
+        builder.path({ id: handle, points: element.points.map(point), smooth: true, ...style(element) });
+        break;
+      }
+      case 'arc': {
+        kinds.set(handle, 'curve');
+        builder.path({ id: handle, points: sampleArc(element).map(point), smooth: true, ...style(element) });
+        break;
+      }
+      case 'text': {
+        builder.text({
+          id: handle,
+          ...point(element),
+          w: element.w !== undefined ? length(element.w) : undefined,
+          text: element.text,
+          color: element.color,
+          size: element.weight,
+        });
+        break;
+      }
+      case 'arrow': {
+        const props: ConnectorProps = {
+          id: handle,
+          from: element.from ? ref(element.from) : undefined,
+          to: element.to ? ref(element.to) : undefined,
+          start: element.start ? point(element.start) : undefined,
+          end: element.end ? point(element.end) : undefined,
+          text: element.text,
+          ...style(element),
+        };
+        builder.arrow(props);
+        break;
+      }
+    }
+  }
+
+  return builder.records();
+};
+
+/** `objectId/elementId` — element ids may themselves not contain `/`. */
+const splitHandle = (handle: string): [string, string] => {
+  const index = handle.indexOf('/');
+  return [handle.slice(0, index), handle.slice(index + 1)];
+};
+
+/** Sample an arc (degrees, clockwise from +x, y-down screen coords) into spline points. */
+const sampleArc = ({ cx, cy, r, startAngle, endAngle }: Scene.Arc): Scene.Point[] => {
+  const sweep = endAngle - startAngle;
+  const steps = Math.max(4, Math.ceil(Math.abs(sweep) / 22.5));
+  return Array.from({ length: steps + 1 }, (_, i) => {
+    const angle = ((startAngle + (sweep * i) / steps) * Math.PI) / 180;
+    return { x: cx + r * Math.cos(angle), y: cy + r * Math.sin(angle) };
+  });
+};

package/src/model/scene.test.ts

@@ -0,0 +1,222 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createTLSchema } from '@tldraw/tlschema';
+import { describe, test } from 'vitest';
+
+import { type Scene } from '@dxos/plugin-illustrator/model';
+
+import { applyCommands } from './apply';
+import { readScene } from './read';
+
+/** A face made of every element category: boxes, circles, arc sugar, polyline, text. */
+const face: Scene.WorldObject = {
+  id: 'face',
+  origin: { x: 100, y: 100 },
+  scale: 2,
+  elements: [
+    { kind: 'circle', id: 'head', cx: 50, cy: 50, r: 50, color: 'yellow', fill: 'solid' },
+    { kind: 'circle', id: 'left-eye', cx: 30, cy: 35, r: 6, fill: 'solid' },
+    { kind: 'circle', id: 'right-eye', cx: 70, cy: 35, r: 6, fill: 'solid' },
+    {
+      kind: 'line',
+      id: 'nose',
+      points: [
+        { x: 50, y: 45 },
+        { x: 50, y: 60 },
+      ],
+    },
+    { kind: 'arc', id: 'smile', cx: 50, cy: 55, r: 25, startAngle: 30, endAngle: 150, color: 'red' },
+  ],
+};
+
+const hat: Scene.WorldObject = {
+  id: 'hat',
+  origin: { x: 120, y: 40 },
+  scale: 2,
+  elements: [
+    { kind: 'rect', id: 'brim', x: 0, y: 25, w: 80, h: 6, color: 'blue', fill: 'solid' },
+    { kind: 'rect', id: 'crown', x: 20, y: 0, w: 40, h: 25, color: 'blue', fill: 'solid' },
+  ],
+};
+
+const upsert = (object: Scene.WorldObject): Scene.Command => ({ op: 'upsert-object', object });
+
+describe('scene DSL', () => {
+  test('renders objects and reads back a coherent scene', ({ expect }) => {
+    const content = {};
+    const result = applyCommands(content, [upsert(face)]);
+    expect(result.upserted).to.deep.eq(['face']);
+
+    const { scene, unmanaged } = readScene(content);
+    expect(unmanaged).to.eq(0);
+    expect(scene.objects).to.have.length(1);
+
+    const read = scene.objects[0];
+    expect(read.id).to.eq('face');
+    // Origin is derived from the bounding box: head top-left = origin + (0,0) * scale.
+    expect(read.origin).to.deep.eq({ x: 100, y: 100 });
+    expect(read.scale).to.eq(2);
+    expect(read.elements.map((element) => element.id)).to.deep.eq(['head', 'left-eye', 'right-eye', 'nose', 'smile']);
+
+    // Circle sugar reads back as an ellipse in local units.
+    const head = read.elements.find((element) => element.id === 'head');
+    expect(head).to.include({ kind: 'ellipse', x: 0, y: 0, w: 100, h: 100 });
+    // Arc sugar reads back as a curve.
+    const smile = read.elements.find((element) => element.id === 'smile');
+    expect(smile?.kind).to.eq('curve');
+  });
+
+  test('rendered records pass tldraw schema validation', ({ expect }) => {
+    const content = {};
+    applyCommands(content, [
+      upsert(face),
+      upsert(hat),
+      upsert({
+        id: 'labels',
+        origin: { x: 0, y: 400 },
+        elements: [
+          { kind: 'text', id: 'caption', x: 0, y: 0, text: 'portrait' },
+          { kind: 'arrow', id: 'points-at', from: 'caption', to: 'face/head', text: 'head' },
+          {
+            kind: 'line',
+            id: 'zigzag',
+            points: [
+              { x: 0, y: 20 },
+              { x: 10, y: 30 },
+              { x: 20, y: 20 },
+            ],
+            closed: true,
+          },
+          { kind: 'diamond', id: 'gem', x: 40, y: 20, w: 20, h: 20, rotation: 45, stroke: 'dashed', weight: 'l' },
+        ],
+      }),
+    ]);
+
+    const schema = createTLSchema();
+    // tldraw types its record map as a fixed-key object without an index signature;
+    // validating an arbitrary record requires a string-keyed view.
+    const validators = schema.types as Record<string, { validate: (record: unknown) => unknown }>;
+    for (const record of Object.values(content) as any[]) {
+      expect(() => validators[record.typeName].validate(record), record.id).to.not.throw();
+    }
+  });
+
+  test('cross-object arrows bind to their targets', ({ expect }) => {
+    const content: Record<string, any> = {};
+    applyCommands(content, [
+      upsert(face),
+      upsert({
+        id: 'hat',
+        origin: { x: 120, y: 40 },
+        elements: [...hat.elements, { kind: 'arrow', id: 'sits-on', from: 'brim', to: 'face/head' }],
+      }),
+    ]);
+
+    const bindings = Object.values(content).filter((record) => record.typeName === 'binding');
+    expect(bindings.map((binding) => binding.toId).sort()).to.deep.eq(['shape:face/head', 'shape:hat/brim']);
+
+    const { scene } = readScene(content);
+    const arrow = scene.objects
+      .find((object) => object.id === 'hat')
+      ?.elements.find((element) => element.id === 'sits-on');
+    expect(arrow).to.include({ kind: 'arrow', from: 'brim', to: 'face/head' });
+  });
+
+  test('upsert-elements replaces by id and keeps the rest', ({ expect }) => {
+    const content = {};
+    applyCommands(content, [upsert(face)]);
+    const before = readScene(content).scene.objects[0];
+
+    // Make the smile a frown (upper arc), leave everything else untouched.
+    applyCommands(content, [
+      {
+        op: 'upsert-elements',
+        objectId: 'face',
+        elements: [{ kind: 'arc', id: 'smile', cx: 50, cy: 70, r: 20, startAngle: 210, endAngle: 330 }],
+      },
+    ]);
+
+    const after = readScene(content).scene.objects[0];
+    expect(after.elements).to.have.length(before.elements.length);
+    expect(after.elements.find((element) => element.id === 'head')).to.deep.eq(
+      before.elements.find((element) => element.id === 'head'),
+    );
+    expect(after.elements.find((element) => element.id === 'smile')).to.not.deep.eq(
+      before.elements.find((element) => element.id === 'smile'),
+    );
+  });
+
+  test('remove and move commands', ({ expect }) => {
+    const content: Record<string, any> = {};
+    applyCommands(content, [upsert(face), upsert(hat)]);
+
+    const moved = applyCommands(content, [{ op: 'move-object', objectId: 'hat', origin: { x: 220, y: 140 } }]);
+    expect(moved.upserted).to.deep.eq(['hat']);
+    const hatRead = readScene(content).scene.objects.find((object) => object.id === 'hat');
+    expect(hatRead?.origin).to.deep.eq({ x: 220, y: 140 });
+    // Local geometry is unchanged by a move.
+    expect(hatRead?.elements.find((element) => element.id === 'brim')).to.include({ x: 0, y: 25, w: 80, h: 6 });
+
+    const removedElements = applyCommands(content, [
+      { op: 'remove-elements', objectId: 'face', elementIds: ['left-eye', 'right-eye'] },
+    ]);
+    expect(removedElements.removed).to.eq(2);
+
+    const removedObject = applyCommands(content, [{ op: 'remove-object', objectId: 'hat' }]);
+    expect(removedObject.removed).to.eq(2);
+    expect(readScene(content).scene.objects.map((object) => object.id)).to.deep.eq(['face']);
+  });
+
+  test('removing an arrow target also drops its bindings', ({ expect }) => {
+    const content: Record<string, any> = {};
+    applyCommands(content, [
+      upsert({
+        id: 'graph',
+        origin: { x: 0, y: 0 },
+        elements: [
+          { kind: 'rect', id: 'a', x: 0, y: 0, w: 40, h: 20 },
+          { kind: 'rect', id: 'b', x: 100, y: 0, w: 40, h: 20 },
+          { kind: 'arrow', id: 'a-to-b', from: 'a', to: 'b' },
+        ],
+      }),
+    ]);
+    expect(Object.values(content).filter((record) => record.typeName === 'binding')).to.have.length(2);
+
+    applyCommands(content, [{ op: 'remove-elements', objectId: 'graph', elementIds: ['b'] }]);
+    const bindings = Object.values(content).filter((record) => record.typeName === 'binding');
+    // Only the binding to the surviving shape remains; nothing dangles.
+    expect(bindings).to.have.length(1);
+    expect(bindings[0].toId).to.eq('shape:graph/a');
+  });
+
+  test('unmanaged shapes are counted but not read as scene objects', ({ expect }) => {
+    const content: Record<string, any> = {};
+    applyCommands(content, [upsert(hat)]);
+    content['shape:user'] = {
+      id: 'shape:user',
+      typeName: 'shape',
+      type: 'geo',
+      x: 0,
+      y: 0,
+      rotation: 0,
+      index: 'a99',
+      parentId: 'page:page',
+      isLocked: false,
+      opacity: 1,
+      meta: {},
+      props: { geo: 'rectangle', w: 10, h: 10 },
+    };
+
+    const { scene, unmanaged } = readScene(content);
+    expect(unmanaged).to.eq(1);
+    expect(scene.objects.map((object) => object.id)).to.deep.eq(['hat']);
+  });
+
+  test('upsert-elements on an unknown object fails with guidance', ({ expect }) => {
+    expect(() => applyCommands({}, [{ op: 'upsert-elements', objectId: 'ghost', elements: [] }])).to.throw(
+      /unknown object/,
+    );
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const TldrawPlugin = Plugin.lazy(meta, () => import('#plugin'));