@dxos/plugin-illustrator 0.10.0

package/src/types/SketchOperation.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database, Ref, Type } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+
+import { meta } from '#meta';
+import { Scene } from '#model';
+
+import * as Sketch from './Sketch';
+
+const makeKey = (name: string) => DXN.make(`${meta.profile.key}.operation.${name}`);
+
+export const Create = Operation.make({
+  meta: { key: makeKey('create'), name: 'Create Sketch', icon: 'ph--pencil-simple--regular' },
+  input: Schema.Struct({
+    name: Schema.optional(Schema.String),
+    variant: Schema.optional(Schema.String).annotations({
+      description: 'Variant id (canvas typename); defaults to the first registered variant.',
+    }),
+  }),
+  output: Schema.Struct({
+    object: Type.getSchema(Sketch.Sketch),
+  }),
+  services: [Capability.Service, Database.Service],
+});
+
+/** The scene as derived from the live canvas. */
+const SceneOutput = {
+  scene: Scene.Scene.annotations({ description: 'The diagram as world objects with object-local coordinates.' }),
+  unmanaged: Schema.Number.annotations({
+    description: 'Number of shapes on the canvas not managed by the DSL (drawn by users).',
+  }),
+};
+
+export const Read = Operation.make({
+  meta: {
+    key: makeKey('read'),
+    name: 'Read Sketch',
+    description:
+      'Returns the current scene of a sketch: world objects (by id) with their elements in object-local units. Call before editing an existing sketch.',
+    icon: 'ph--eye--regular',
+  },
+  input: Schema.Struct({
+    sketch: Ref.Ref(Sketch.Sketch).annotations({ description: 'The sketch to read.' }),
+  }),
+  output: Schema.Struct(SceneOutput),
+  services: [Capability.Service, Database.Service],
+});
+
+export const Edit = Operation.make({
+  meta: {
+    key: makeKey('edit'),
+    name: 'Edit Sketch',
+    description:
+      'Applies scene commands to a sketch: upsert/move/remove world objects or individual elements by id. Returns the resulting scene.',
+    icon: 'ph--pencil-simple-line--regular',
+  },
+  input: Schema.Struct({
+    sketch: Ref.Ref(Sketch.Sketch).annotations({ description: 'The sketch to edit.' }),
+    commands: Schema.Array(Scene.Command).annotations({ description: 'Commands applied in order, atomically.' }),
+  }),
+  output: Schema.Struct({
+    ...SceneOutput,
+    upserted: Schema.Array(Schema.String).annotations({ description: 'Object ids created or modified.' }),
+    removed: Schema.Number.annotations({ description: 'Number of shapes removed.' }),
+  }),
+  services: [Capability.Service, Database.Service],
+});

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './types';
+
+export * as IllustratorCapabilities from './IllustratorCapabilities';
+export * as Sketch from './Sketch';
+export * as SketchOperation from './SketchOperation';

package/src/types/types.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+import type { ComponentType } from 'react';
+
+import type { Database, Obj, Type } from '@dxos/echo';
+
+import { type SketchBuilder } from '#model';
+
+import type * as Sketch from './Sketch';
+
+/**
+ * Contribution from a canvas renderer plugin (e.g. plugin-tldraw, plugin-excalidraw).
+ * Defines how a sketch variant is created, rendered, and how the scene DSL maps onto it.
+ */
+export type SketchVariant = {
+  /** Stable id, typically the canvas typename (e.g. 'org.dxos.type.canvas'). */
+  id: string;
+  /** Human-readable variant name (e.g. 'tldraw'). */
+  label: string;
+  /** Optional Phosphor icon name (e.g. 'ph--compass-tool--regular'). */
+  icon?: string;
+  /** ECHO Type entity of the canvas object referenced by `Sketch.canvas`. */
+  canvasType: Type.AnyObj;
+  /**
+   * Build an empty canvas object. May allocate ECHO objects, run effects, etc.
+   * Returned object is added to the database alongside the Sketch.
+   */
+  createCanvas: (input?: Record<string, any>) => Effect.Effect<Obj.Any, Error, Database.Service>;
+  /** Maps the scene DSL onto this variant's canvas records. */
+  builder: SketchBuilder;
+  /** Optional Card surface component for this variant. */
+  card?: ComponentType<SketchVariantSurfaceProps>;
+  /** Optional Article/Section/Slide surface component for this variant. */
+  article?: ComponentType<SketchVariantSurfaceProps>;
+};
+
+export type SketchVariantSurfaceProps = {
+  /** The base Sketch object (may be a snapshot from useObject/Surface). */
+  sketch: Obj.Snapshot<Sketch.Sketch> | Sketch.Sketch;
+  /** The resolved LIVE canvas object — variant store adapters need `Doc.createAccessor`. */
+  canvas: Obj.Unknown;
+  /** Surface role passed through from the host. */
+  role?: string;
+  /** Attendable id passed through from the host. */
+  attendableId?: string;
+  /** Card surfaces: whether the card is editable. */
+  editable?: boolean;
+  /** Section surfaces: whether the embed is extrinsically sized. */
+  extrinsic?: boolean;
+};

package/src/util/index.ts

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

package/src/util/load-sketch.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Database, Obj, type Ref, Type } from '@dxos/echo';
+
+import * as IllustratorCapabilities from '../types/IllustratorCapabilities';
+import * as Sketch from '../types/Sketch';
+import { type SketchVariant } from '../types/types';
+
+export class SketchVariantMismatchError extends Error {
+  readonly _tag = 'SketchVariantMismatchError';
+  constructor(
+    readonly sketchId: string,
+    readonly expectedTypename: string,
+    readonly actualTypename: string,
+  ) {
+    super(`Sketch ${sketchId} canvas typename mismatch: expected ${expectedTypename}, got ${actualTypename}.`);
+  }
+}
+
+export class UnknownSketchVariantError extends Error {
+  readonly _tag = 'UnknownSketchVariantError';
+  constructor(readonly typename: string) {
+    super(`No sketch variant registered for canvas type: ${typename}.`);
+  }
+}
+
+/**
+ * Loads a Sketch from a Ref and resolves its canvas, asserting the canvas matches
+ * the expected type. Returns the typed pair.
+ *
+ * Use in operation handlers that declare `input.sketch: SketchRef<MyCanvas>`.
+ */
+export const loadSketch = <S extends Type.AnyObj>(
+  ref: Ref.Ref<Sketch.Sketch>,
+  canvasType: S,
+): Effect.Effect<{ sketch: Sketch.Sketch; canvas: Type.InstanceType<S> }, Error, Database.Service> =>
+  Effect.gen(function* () {
+    const sketch = yield* Database.load(ref);
+    const canvas = yield* Database.load(sketch.canvas);
+    if (!Obj.instanceOf(canvasType, canvas)) {
+      const expected = Type.getTypename(canvasType) ?? 'unknown';
+      const actual = Obj.getTypename(canvas as Obj.Any) ?? 'unknown';
+      return yield* Effect.fail(new SketchVariantMismatchError(sketch.id, expected, actual));
+    }
+    return { sketch, canvas: canvas as Type.InstanceType<S> };
+  });
+
+/**
+ * Loads a Sketch and resolves the variant provider matching its canvas typename.
+ * Used by the renderer-agnostic read/edit operations.
+ */
+export const resolveVariant = (
+  ref: Ref.Ref<Sketch.Sketch>,
+): Effect.Effect<
+  { sketch: Sketch.Sketch; canvas: Obj.Any; variant: SketchVariant },
+  Error,
+  Database.Service | Capability.Service
+> =>
+  Effect.gen(function* () {
+    const sketch = yield* Database.load(ref);
+    const canvas = (yield* Database.load(sketch.canvas)) as Obj.Any;
+    const typename = Obj.getTypename(canvas) ?? 'unknown';
+    const variants = yield* Capability.getAll(IllustratorCapabilities.VariantProvider);
+    const variant = variants.find((entry) => entry.id === typename);
+    if (!variant) {
+      return yield* Effect.fail(new UnknownSketchVariantError(typename));
+    }
+    return { sketch, canvas, variant };
+  });

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}