@dxos/plugin-illustrator 0.10.0

package/dx.config.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.illustrator',
+    name: 'Illustrator',
+    author: 'DXOS',
+    description: trim`
+      Headless diagramming host plugin that provides shared infrastructure for local-first
+      drawing and diagramming inside DXOS Composer. The plugin owns the base \`Sketch\` ECHO
+      type — a named handle referencing a renderer-specific canvas object — together with the
+      renderer-neutral scene DSL, the diagram dialect registry, and the agent-facing sketch
+      skill and operations (create, read, edit).
+
+      Canvas renderers (tldraw, excalidraw, and others) are contributed by separate plugins
+      via the \`IllustratorCapabilities.VariantProvider\` capability. Each variant supplies its
+      own canvas schema, a builder that maps the scene DSL onto its records, and surface
+      components (Article and Card). Plugin-illustrator resolves the correct variant at
+      runtime and delegates rendering and DSL compilation, keeping the host layer fully
+      decoupled from renderer internals.
+
+      Canvas objects are stored as hidden ECHO objects alongside the top-level \`Sketch\`,
+      ensuring they replicate to all peers but do not appear as independent items in the
+      user's space graph.
+    `,
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-illustrator',
+    icon: { key: 'ph--compass-tool--regular', hue: 'indigo' },
+    spec: 'PLUGIN.mdl',
+  },
+});

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "@dxos/plugin-illustrator",
+  "version": "0.10.0",
+  "description": "Headless diagramming plugin for DXOS Composer (unifies canvas renderers like tldraw and excalidraw).",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/capabilities.mjs"
+    },
+    "#components": {
+      "source": "./src/components/index.ts",
+      "types": "./dist/types/src/components/index.d.ts",
+      "default": "./dist/lib/components.mjs"
+    },
+    "#containers": {
+      "source": "./src/containers/index.ts",
+      "types": "./dist/types/src/containers/index.d.ts",
+      "default": "./dist/lib/containers.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/meta.mjs"
+    },
+    "#model": {
+      "source": "./src/model/index.ts",
+      "types": "./dist/types/src/model/index.d.ts",
+      "default": "./dist/lib/model.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/operations.mjs"
+    },
+    "#plugin": {
+      "source": {
+        "workerd": "./src/IllustratorPlugin.workerd.tsx",
+        "node": "./src/IllustratorPlugin.node.tsx",
+        "default": "./src/IllustratorPlugin.tsx"
+      },
+      "types": "./dist/types/src/IllustratorPlugin.d.ts",
+      "workerd": "./dist/lib/IllustratorPlugin.workerd.mjs",
+      "node": "./dist/lib/IllustratorPlugin.node.mjs",
+      "default": "./dist/lib/IllustratorPlugin.mjs"
+    },
+    "#skills": {
+      "source": "./src/skills/index.ts",
+      "types": "./dist/types/src/skills/index.d.ts",
+      "default": "./dist/lib/skills.mjs"
+    },
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/translations.mjs"
+    },
+    "#types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/types.mjs"
+    },
+    "#util": "./src/util/index.ts"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
+    "./model": {
+      "source": "./src/model/index.ts",
+      "types": "./dist/types/src/model/index.d.ts",
+      "import": "./dist/lib/model.mjs"
+    },
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "import": "./dist/lib/plugin.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "import": "./dist/lib/translations.mjs"
+    },
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "import": "./dist/lib/types.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "dx.config.ts",
+    "src",
+    "PLUGIN.mdl"
+  ],
+  "dependencies": {
+    "effect": "3.21.4",
+    "@dxos/app-framework": "0.10.0",
+    "@dxos/app-toolkit": "0.10.0",
+    "@dxos/compute": "0.10.0",
+    "@dxos/echo": "0.10.0",
+    "@dxos/echo-react": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/log": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/plugin-space": "0.10.0",
+    "@dxos/react-ui": "0.10.0",
+    "@dxos/react-ui-search": "0.10.0",
+    "@dxos/util": "0.10.0",
+    "@dxos/schema": "0.10.0",
+    "@dxos/react-ui-form": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.17",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "vite": "^8.1.4",
+    "@dxos/ui-theme": "0.10.0",
+    "@dxos/plugin-testing": "0.10.0"
+  },
+  "peerDependencies": {
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "^0.10.0",
+    "@dxos/ui-theme": "^0.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/IllustratorPlugin.node.tsx

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+
+import { OperationHandler, SkillDefinition } from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { Sketch } from '#types';
+
+/**
+ * Headless variant of IllustratorPlugin (no React surfaces / CreateObject panel).
+ * Used in node contexts (CLI, agents, tests) where rendering is unavailable —
+ * the full variant lazy-loads `CreateSketchPanel` from `react-ui-search` which
+ * downstream bundlers don't resolve cleanly under nested pnpm symlinks.
+ */
+export const IllustratorPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({ schema: [Sketch.Sketch] }),
+  AppPlugin.addSkillDefinitionModule({ activate: SkillDefinition }),
+  AppPlugin.addTranslationsModule({ translations }),
+  Plugin.make,
+);
+
+export default IllustratorPlugin;

package/src/IllustratorPlugin.tsx

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+
+import { CommentConfig, CreateObject, OperationHandler, ReactSurface, SkillDefinition } from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { Sketch } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
+
+export const IllustratorPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addCommentConfigModule({ activate: CommentConfig }),
+  AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({ schema: [Sketch.Sketch] }),
+  AppPlugin.addSkillDefinitionModule({ activate: SkillDefinition }),
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations }),
+  AppPlugin.addPluginAssetModule({
+    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+  }),
+  Plugin.make,
+);
+
+export default IllustratorPlugin;

package/src/IllustratorPlugin.workerd.tsx

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+import { Sketch } from '#types';
+
+export const IllustratorPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addSchemaModule({ schema: [Sketch.Sketch] }),
+  Plugin.make,
+);
+
+export default IllustratorPlugin;

package/src/capabilities/comment-config.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Type } from '@dxos/echo';
+
+import { Sketch } from '#types';
+
+const activate = Effect.fnUntraced(function* () {
+  return Capability.contributes(AppCapabilities.CommentConfig, {
+    id: Type.getTypename(Sketch.Sketch),
+    comments: 'unanchored',
+  });
+});
+
+export default activate;

package/src/capabilities/create-object.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database, Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { SpaceCapabilities, SpaceOperation } from '@dxos/plugin-space';
+
+import { CreateSketchPanel } from '#components';
+
+import { IllustratorCapabilities, Sketch } from '../types';
+
+type CreateOptions = Parameters<SpaceCapabilities.CreateObjectEntry['createObject']>[1];
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(SpaceCapabilities.CreateObjectEntry, {
+      id: Type.getTypename(Sketch.Sketch),
+      customPanel: CreateSketchPanel,
+      createObject: (
+        { variantId, input }: { variantId: string; input?: Record<string, any> },
+        options: CreateOptions,
+      ) =>
+        Effect.gen(function* () {
+          const variants = yield* Capability.getAll(IllustratorCapabilities.VariantProvider);
+          const variant = variants.find((entry) => entry.id === variantId);
+          invariant(variant, `Unknown sketch variant: ${variantId}`);
+
+          // Build the canvas object via the variant's factory.
+          const canvas = yield* variant
+            .createCanvas(input ?? {})
+            .pipe(Effect.provideService(Database.Service, Database.makeService(options.db)));
+
+          // Add the canvas to the database. Stays hidden — it's referenced by the Sketch and
+          // shouldn't appear as a top-level item in the user's space.
+          yield* Operation.invoke(SpaceOperation.AddObject, {
+            object: canvas,
+            target: options.target,
+            targetNodeId: options.targetNodeId,
+          });
+
+          const sketch = Sketch.make({
+            name: typeof input?.name === 'string' ? input.name : undefined,
+            canvas,
+          });
+
+          // Add the user-facing Sketch wrapper. Not hidden — this is the object the user sees
+          // and navigates to. If this second write fails, roll back the canvas so we don't
+          // leak an orphaned object into the space.
+          return yield* Operation.invoke(SpaceOperation.AddObject, {
+            object: sketch,
+            target: options.target,
+            targetNodeId: options.targetNodeId,
+          }).pipe(
+            Effect.tapError(() =>
+              Operation.invoke(SpaceOperation.RemoveObjects, { objects: [canvas] }).pipe(Effect.ignore),
+            ),
+          );
+        }),
+    });
+  }),
+);

package/src/capabilities/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const CommentConfig = Capability.lazy('CommentConfig', () => import('./comment-config'));
+export const CreateObject = Capability.lazy('CreateObject', () => import('./create-object'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const SkillDefinition = Capability.lazy('SkillDefinition', () => import('./skill-definition'));

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { IllustratorOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, IllustratorOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+
+import { SketchArticle, SketchCard } from '#containers';
+
+import { Sketch } from '../types';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'sketch',
+        filter: AppSurface.oneOf(
+          AppSurface.object(AppSurface.Article, Sketch.Sketch),
+          AppSurface.object(AppSurface.Section, Sketch.Sketch),
+          AppSurface.object(AppSurface.Slide, Sketch.Sketch),
+        ),
+        component: ({ data: { subject, attendableId, extrinsic }, role }) => (
+          <SketchArticle role={role} subject={subject} attendableId={attendableId} extrinsic={extrinsic} />
+        ),
+      }),
+      Surface.create({
+        id: 'sketchCard',
+        filter: AppSurface.object(AppSurface.CardContent, Sketch.Sketch),
+        component: ({ data, role }) => <SketchCard role={role} subject={data.subject} editable={data.editable} />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/skill-definition.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+
+import { SketchSkill } from '#skills';
+
+const skillDefinition = () => Effect.succeed([Capability.contributes(AppCapabilities.SkillDefinition, SketchSkill)]);
+
+export default skillDefinition;

package/src/components/CreateSketchPanel.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type SpaceCapabilities } from '@dxos/plugin-space';
+import { useTranslation } from '@dxos/react-ui';
+import { SearchList, useSearchListResults } from '@dxos/react-ui-search';
+
+import { meta } from '#meta';
+import { IllustratorCapabilities, type SketchVariant } from '#types';
+
+export type CreateSketchPanelProps = SpaceCapabilities.CreateObjectCustomPanelProps & {
+  /** Optional override (primarily for stories/tests). Defaults to IllustratorCapabilities.VariantProvider. */
+  variants?: SketchVariant[];
+};
+
+/**
+ * Variant picker for sketches (SearchList over contributed `SketchVariant[]`).
+ * On select, calls `onCreateObject({ variantId })`; plugin-illustrator's
+ * CreateObjectEntry.createObject resolves the variantId, builds the canvas via
+ * variant.createCanvas, then wraps it in a Sketch.
+ */
+export const CreateSketchPanel = ({ onCreateObject, variants: variantsProp }: CreateSketchPanelProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const capabilityVariants = useCapabilities(IllustratorCapabilities.VariantProvider);
+  const variants = variantsProp ?? capabilityVariants;
+  const sorted = useMemo(() => [...variants].sort((a, b) => a.label.localeCompare(b.label)), [variants]);
+  const { results, handleSearch } = useSearchListResults({
+    items: sorted,
+    extract: (variant) => variant.label,
+  });
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      const variant = variants.find((entry) => entry.id === id);
+      if (!variant) {
+        return;
+      }
+      void onCreateObject({ variantId: id });
+    },
+    [variants, onCreateObject],
+  );
+
+  return (
+    <SearchList.Root onSearch={handleSearch}>
+      <SearchList.Input
+        classNames='mb-form-gap'
+        autoFocus
+        data-testid='create-sketch-panel.variant-input'
+        placeholder={t('create-panel.variant.placeholder')}
+      />
+      <SearchList.Viewport>
+        {results.map((variant) => (
+          <SearchList.Item
+            key={variant.id}
+            value={variant.id}
+            label={variant.label}
+            icon={variant.icon ?? 'ph--compass-tool--regular'}
+            onSelect={() => handleSelect(variant.id)}
+          />
+        ))}
+      </SearchList.Viewport>
+    </SearchList.Root>
+  );
+};

package/src/components/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CreateSketchPanel';

package/src/containers/SketchArticle/SketchArticle.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj, type Ref } from '@dxos/echo';
+import { useObject } from '@dxos/echo-react';
+import { useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+import { IllustratorCapabilities, type Sketch } from '#types';
+
+export type SketchArticleProps = AppSurface.ObjectArticleProps<Sketch.Sketch> & {
+  extrinsic?: boolean;
+};
+
+/** Resolves the sketch's canvas and delegates rendering to the matching variant's article. */
+export const SketchArticle = ({ role, attendableId, subject: sketch, extrinsic }: SketchArticleProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const variants = useCapabilities(IllustratorCapabilities.VariantProvider);
+  const ref = sketch.canvas as Ref.Ref<Obj.Unknown>;
+  // Subscribe via the snapshot for load/re-render, but hand variants the LIVE object —
+  // their store adapters need `Doc.createAccessor`, which rejects snapshots.
+  const [snapshot] = useObject(ref);
+  const canvas = snapshot ? ref.target : undefined;
+
+  if (!canvas) {
+    return null;
+  }
+
+  const typename = Obj.getTypename(canvas);
+  const match = variants.find((variant) => variant.id === typename);
+  if (!match?.article) {
+    return (
+      <div className='p-4 text-sm'>
+        {t('unsupported-variant.label', { defaultValue: 'Unsupported sketch variant' })}
+      </div>
+    );
+  }
+
+  const Component = match.article;
+  return <Component sketch={sketch} canvas={canvas} role={role} attendableId={attendableId} extrinsic={extrinsic} />;
+};
+
+SketchArticle.displayName = 'SketchArticle';

package/src/containers/SketchArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './SketchArticle';

package/src/containers/SketchCard/SketchCard.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj, type Ref } from '@dxos/echo';
+import { useObject } from '@dxos/echo-react';
+
+import { IllustratorCapabilities, type Sketch } from '#types';
+
+export type SketchCardProps = AppSurface.ObjectCardProps<Sketch.Sketch>;
+
+/** Resolves the sketch's canvas and delegates rendering to the matching variant's card. */
+export const SketchCard = ({ role, subject: sketch, editable }: SketchCardProps) => {
+  const variants = useCapabilities(IllustratorCapabilities.VariantProvider);
+  const ref = sketch.canvas as Ref.Ref<Obj.Unknown>;
+  // Subscribe via the snapshot for load/re-render, but hand variants the LIVE object —
+  // their store adapters need `Doc.createAccessor`, which rejects snapshots.
+  const [snapshot] = useObject(ref);
+  const canvas = snapshot ? ref.target : undefined;
+
+  if (!canvas) {
+    return null;
+  }
+
+  const typename = Obj.getTypename(canvas);
+  const match = variants.find((variant) => variant.id === typename);
+  if (!match?.card) {
+    return null;
+  }
+
+  const Component = match.card;
+  return <Component sketch={sketch} canvas={canvas} role={role} editable={editable} />;
+};
+
+SketchCard.displayName = 'SketchCard';
+
+export default SketchCard;

package/src/containers/SketchCard/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './SketchCard';

package/src/containers/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './SketchArticle';
+export * from './SketchCard';

package/src/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './meta';
+export * as IllustratorModel from './model';
+export * from './operations';
+export * from './skills';
+export * from './types';
+export * from './util';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);