@moloodev/editor-sdk 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@moloodev/editor-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/view.ts",
+    "./view": "./src/view.ts",
+    "./protocol": "./src/protocol-entry.ts",
+    "./render-result": "./src/render-result.ts",
+    "./origin-headers": "./src/origin-headers.ts",
+    "./layout": "./src/layout/index.ts",
+    "./layout/frame": "./src/layout/frame.ts",
+    "./commands": "./src/commands/index.ts",
+    "./commands/editor-document": "./src/commands/manifest/editor-document.ts",
+    "./commands/when": "./src/commands/when/validate.ts",
+    "./crdt": "./src/crdt/index.ts",
+    "./crdt/vite": "./src/crdt/vite-plugin.ts",
+    "./print": "./src/print/index.ts"
+  },
+  "dependencies": {
+    "@dnd-kit/react": "^0.5.0",
+    "@json-render/core": "^0.20.0",
+    "@json-render/react": "^0.20.0",
+    "@tabler/icons-react": "^3.46.0",
+    "@tanstack/react-hotkeys": "^0.10.0",
+    "lib0": "^0.2.117",
+    "y-indexeddb": "^9.0.12",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.32",
+    "zod": "^4.5.4",
+    "@moloodev/platform": "0.2.0",
+    "@moloodev/ui": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.56.1",
+    "@types/jsdom": "30.0.0",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "esbuild": "^0.28.2",
+    "jsdom": "30.1.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.origin-headers.json",
+    "test": "tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx' && pnpm test:browser",
+    "test:browser": "tsx --test 'browser/**/*.test.ts'"
+  }
 }

package/src/channel.ts

@@ -0,0 +1,287 @@
+import type {
+  EditorEvent,
+  EditorFailure,
+  EditorOperation,
+  EditorRequest,
+  EditorRequestType,
+  EditorResponse,
+  EditorSuccess,
+} from "./index";
+import {
+  parseEditorEvent,
+  parseEditorRequest,
+  parseEditorResponseFor,
+  parseHandshakeReply,
+  parseSessionOpen,
+} from "./protocol";
+
+/** One deadline for every paired request and for the view handshake. host.pick shares it. */
+export const EDITOR_REQUEST_TIMEOUT_MS = 30_000;
+
+export type EditorPort = {
+  postMessage(data: unknown): void;
+  start(): void;
+  close(): void;
+  addEventListener(
+    type: "message",
+    listener: (event: { readonly data: unknown }) => void,
+  ): void;
+  removeEventListener(
+    type: "message",
+    listener: (event: { readonly data: unknown }) => void,
+  ): void;
+};
+
+export type HandshakeResult =
+  | { ok: true }
+  | { ok: false; code: "version" | "schema" | "rejected" | "timeout" };
+
+export type EditorRequestHandler = (
+  request: EditorRequest,
+) => Promise<
+  | { ok: true; body: EditorSuccess["body"] }
+  | { ok: false; code: string }
+>;
+
+export type EditorChannel = {
+  readonly handshake: Promise<HandshakeResult>;
+  request<Type extends EditorRequestType>(
+    type: Type,
+    body: EditorOperation[Type]["body"],
+  ): Promise<EditorResponse<Type>>;
+  emit(event: EditorEvent): boolean;
+  close(): void;
+};
+
+type Role = "host" | "view";
+type Phase = "wait" | "open" | "closed";
+type CloseCode = "version" | "schema" | "rejected" | "timeout" | "closed";
+
+type Pending = {
+  timer: ReturnType<typeof setTimeout>;
+  accept(value: unknown): void;
+  cancel(): void;
+};
+
+function failure(id: string, code: string): EditorFailure {
+  return { v: 1, id, ok: false, code };
+}
+
+function handlerFailure(code: string): { ok: false; code: string } {
+  return { ok: false, code };
+}
+
+function field(value: unknown, key: string): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  if (!Object.hasOwn(value, key)) return undefined;
+  return Reflect.get(value, key);
+}
+
+export function createEditorChannel(options: {
+  role: Role;
+  editorId: string;
+  port: EditorPort;
+  onRequest?: EditorRequestHandler;
+  onEvent?: (event: EditorEvent) => void;
+}): EditorChannel {
+  const { role, editorId, port, onRequest, onEvent } = options;
+  let phase: Phase = "wait";
+  let nextId = 0;
+  const pending = new Map<string, Pending>();
+  let handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+  let handshakeSettled = false;
+  let settleHandshake: (result: HandshakeResult) => void = () => {};
+  const handshake = new Promise<HandshakeResult>((resolve) => {
+    settleHandshake = (result) => {
+      if (handshakeSettled) return;
+      handshakeSettled = true;
+      resolve(result);
+    };
+  });
+
+  function post(data: unknown) {
+    if (phase === "closed") return;
+    port.postMessage(data);
+  }
+
+  function disarmHandshakeTimer() {
+    if (handshakeTimer === undefined) return;
+    clearTimeout(handshakeTimer);
+    handshakeTimer = undefined;
+  }
+
+  function closeWith(code: CloseCode) {
+    if (phase === "closed") return;
+    phase = "closed";
+    disarmHandshakeTimer();
+    port.removeEventListener("message", onMessage);
+    port.close();
+    const waiting = [...pending.values()];
+    for (const entry of waiting) clearTimeout(entry.timer);
+    pending.clear();
+    for (const entry of waiting) entry.cancel();
+    if (code === "closed") {
+      settleHandshake({ ok: false, code: "rejected" });
+      return;
+    }
+    settleHandshake({ ok: false, code });
+  }
+
+  function rejectOpen(code: "version" | "schema" | "rejected") {
+    post({ v: 1, ok: false, code });
+    closeWith(code);
+  }
+
+  function take(id: string): Pending | undefined {
+    const entry = pending.get(id);
+    if (!entry) return undefined;
+    pending.delete(id);
+    clearTimeout(entry.timer);
+    return entry;
+  }
+
+  async function replyTo(request: EditorRequest) {
+    let result: Awaited<ReturnType<EditorRequestHandler>>;
+    try {
+      result = onRequest ? await onRequest(request) : handlerFailure("schema");
+    } catch {
+      result = handlerFailure("schema");
+    }
+    if (phase === "closed") return;
+    const wire = result.ok
+      ? { v: 1, id: request.id, ok: true, body: result.body }
+      : failure(request.id, result.code);
+    const parsed = parseEditorResponseFor(request.type, wire);
+    if (!parsed.ok) {
+      post(failure(request.id, parsed.code));
+      return;
+    }
+    post(parsed.message);
+  }
+
+  function takeReply(value: unknown) {
+    const reply = parseHandshakeReply(value);
+    if (!reply.ok) {
+      closeWith(reply.code);
+      return;
+    }
+    if (!reply.message.ok) {
+      closeWith(reply.message.code);
+      return;
+    }
+    disarmHandshakeTimer();
+    phase = "open";
+    settleHandshake({ ok: true });
+  }
+
+  function onMessage(event: { readonly data: unknown }) {
+    if (phase === "closed") return;
+    const value = event.data;
+    if (role === "view" && phase === "wait") {
+      takeReply(value);
+      return;
+    }
+    if (field(value, "type") === "session.open") {
+      if (phase === "open") {
+        rejectOpen("rejected");
+        return;
+      }
+      const opened = parseSessionOpen(value);
+      if (!opened.ok) {
+        rejectOpen(opened.code);
+        return;
+      }
+      if (opened.message.body.editorId !== editorId) {
+        rejectOpen("rejected");
+        return;
+      }
+      post({ v: 1, ok: true });
+      phase = "open";
+      settleHandshake({ ok: true });
+      return;
+    }
+    if (phase === "wait") return;
+    const id = field(value, "id");
+    if (typeof id === "string") {
+      const entry = take(id);
+      if (entry) {
+        entry.accept(value);
+        return;
+      }
+    }
+    if (typeof field(value, "ok") === "boolean") return;
+    const request = parseEditorRequest(value);
+    if (request.ok) {
+      void replyTo(request.message);
+      return;
+    }
+    if (request.code === "version" && typeof id === "string") {
+      post(failure(id, "version"));
+      return;
+    }
+    const incoming = parseEditorEvent(value);
+    if (incoming.ok) {
+      onEvent?.(incoming.message);
+      return;
+    }
+    if (typeof id === "string") post(failure(id, incoming.code));
+  }
+
+  function request<Type extends EditorRequestType>(
+    type: Type,
+    body: EditorOperation[Type]["body"],
+  ): Promise<EditorResponse<Type>> {
+    nextId += 1;
+    const id = `${role}:${nextId}`;
+    if (phase !== "open") return Promise.resolve(failure(id, "closed"));
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        if (!pending.delete(id)) return;
+        resolve(failure(id, "timeout"));
+      }, EDITOR_REQUEST_TIMEOUT_MS);
+      pending.set(id, {
+        timer,
+        accept(value: unknown) {
+          const parsed = parseEditorResponseFor(type, value);
+          if (!parsed.ok) {
+            resolve(failure(id, parsed.code));
+            return;
+          }
+          resolve(parsed.message);
+        },
+        cancel() {
+          resolve(failure(id, "closed"));
+        },
+      });
+      post({ v: 1, id, type, body });
+    });
+  }
+
+  function emit(event: EditorEvent): boolean {
+    if (phase !== "open") return false;
+    const parsed = parseEditorEvent(event);
+    if (!parsed.ok) return false;
+    post(parsed.message);
+    return true;
+  }
+
+  port.addEventListener("message", onMessage);
+  if (role === "view") {
+    handshakeTimer = setTimeout(() => {
+      closeWith("timeout");
+    }, EDITOR_REQUEST_TIMEOUT_MS);
+    post({ v: 1, type: "session.open", body: { editorId } });
+  }
+  port.start();
+
+  return {
+    handshake,
+    request,
+    emit,
+    close() {
+      closeWith("closed");
+    },
+  };
+}

package/src/chrome-manifest.ts

@@ -0,0 +1,111 @@
+import { validateWhenClause } from "./commands/when/validate";
+import { z } from "zod";
+import type { Json } from "./index";
+import { jsonSchema } from "./json-schema";
+
+/** One path segment. KindIcon imports `@tabler/icons-react/dist/esm/icons/${name}.mjs`. */
+const iconNameSchema = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+
+const HOST_COMMANDS = new Set([
+  "editor.new",
+  "editor.open",
+  "editor.preferences",
+]);
+
+const whenClause = z
+  .string()
+  .min(1)
+  .refine((clause) => validateWhenClause(clause).length === 0);
+
+const commandSchema = z.strictObject({
+  id: z.string().min(1),
+  title: z.string(),
+  group: z.string().exactOptional(),
+  when: whenClause.exactOptional(),
+});
+
+const menuSchema = z.strictObject({
+  path: z.array(z.string()).min(1),
+  commandId: z.string().min(1),
+  order: z.number().exactOptional(),
+  group: z.string().exactOptional(),
+  label: z.string().exactOptional(),
+  shortcut: z.string().exactOptional(),
+  when: whenClause.exactOptional(),
+});
+
+const keybindingSchema = z.strictObject({
+  commandId: z.string().min(1),
+  key: z.string().min(1),
+});
+
+function jsonRecord(value: Json): { [key: string]: Json } | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return undefined;
+}
+
+export const chromeManifestSchema = z
+  .strictObject({
+    contributes: z
+      .strictObject({
+        commands: z.array(commandSchema).exactOptional(),
+        menus: z.array(menuSchema).exactOptional(),
+        keybindings: z.array(keybindingSchema).exactOptional(),
+      })
+      .exactOptional(),
+    layout: z.strictObject({
+      root: z.string(),
+      elements: z.record(z.string(), jsonSchema),
+    }),
+    titles: z.record(z.string(), z.string()),
+    panelHeaders: z
+      .record(
+        z.string().min(1),
+        z.strictObject({
+          commandId: z.string().min(1),
+          icon: iconNameSchema,
+        }),
+      )
+      .exactOptional(),
+  })
+  .superRefine((manifest, ctx) => {
+    const declared = new Set(
+      manifest.contributes?.commands?.map((command) => command.id) ?? [],
+    );
+    const used = [
+      ...(manifest.contributes?.menus?.map((menu) => menu.commandId) ?? []),
+      ...(manifest.contributes?.keybindings?.map(
+        (binding) => binding.commandId,
+      ) ?? []),
+    ];
+    for (const [contentId, header] of Object.entries(manifest.panelHeaders ?? {})) {
+      used.push(header.commandId);
+      if (HOST_COMMANDS.has(header.commandId)) {
+        ctx.addIssue({
+          code: "custom",
+          message: "host command",
+          path: ["panelHeaders", contentId, "commandId"],
+        });
+      }
+    }
+    for (const element of Object.values(manifest.layout.elements)) {
+      const row = jsonRecord(element);
+      if (row?.type !== "ToolbarButton") continue;
+      const props = row.props === undefined ? undefined : jsonRecord(row.props);
+      if (props == null) continue;
+      const icon = props.icon;
+      if (icon != null && !iconNameSchema.safeParse(icon).success) {
+        ctx.addIssue({ code: "custom", message: "icon" });
+      }
+      if (typeof props.commandId === "string") used.push(props.commandId);
+    }
+    for (const id of used) {
+      if (!declared.has(id)) {
+        ctx.addIssue({ code: "custom", message: "command" });
+      }
+    }
+  });
+
+export type ChromeManifest = z.infer<typeof chromeManifestSchema>;

package/src/commands/clipboard/router.ts

@@ -0,0 +1,99 @@
+import type { ClipboardAdapter, ClipboardPayload } from "./types";
+
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!target || typeof target !== "object") return false;
+  const el = target as {
+    isContentEditable?: boolean;
+    tagName?: string;
+  };
+  if (el.isContentEditable) return true;
+  const tag = el.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}
+
+/**
+ * Route native copy/cut/paste:
+ * - text / editable targets → let the browser handle
+ * - object selection → custom MIME via clipboardData
+ */
+export function createClipboardRouter(getAdapter: () => ClipboardAdapter | null) {
+  function onCopy(event: ClipboardEvent): void {
+    if (isEditableTarget(event.target)) return;
+    const adapter = getAdapter();
+    if (!adapter) return;
+    const selection = adapter.getSelection();
+    if (selection.kind !== "object") return;
+    event.preventDefault();
+    writePayload(event, selection.payload);
+  }
+
+  function onCut(event: ClipboardEvent): void {
+    if (isEditableTarget(event.target)) return;
+    const adapter = getAdapter();
+    if (!adapter) return;
+    const selection = adapter.getSelection();
+    if (selection.kind !== "object") return;
+    event.preventDefault();
+    writePayload(event, selection.payload);
+    void adapter.deleteSelection?.();
+  }
+
+  function onPaste(event: ClipboardEvent): void {
+    if (isEditableTarget(event.target)) return;
+    const adapter = getAdapter();
+    if (!adapter?.pasteObject) return;
+    const payload = readObjectPayload(event, adapter);
+    if (!payload) return;
+    event.preventDefault();
+    void adapter.pasteObject(payload);
+  }
+
+  function attach(target: GlobalEventHandlers = document): () => void {
+    target.addEventListener("copy", onCopy as EventListener);
+    target.addEventListener("cut", onCut as EventListener);
+    target.addEventListener("paste", onPaste as EventListener);
+    return () => {
+      target.removeEventListener("copy", onCopy as EventListener);
+      target.removeEventListener("cut", onCut as EventListener);
+      target.removeEventListener("paste", onPaste as EventListener);
+    };
+  }
+
+  return { onCopy, onCut, onPaste, attach };
+}
+
+function writePayload(event: ClipboardEvent, payload: ClipboardPayload): void {
+  const { clipboardData } = event;
+  if (!clipboardData) return;
+  clipboardData.setData(payload.mimeType, payload.data);
+  if (payload.text != null) {
+    clipboardData.setData("text/plain", payload.text);
+  }
+}
+
+function readObjectPayload(
+  event: ClipboardEvent,
+  adapter: ClipboardAdapter,
+): ClipboardPayload | null {
+  const { clipboardData } = event;
+  if (!clipboardData) return null;
+
+  // Prefer a MIME the adapter just exposed via current selection type,
+  // otherwise scan application/x-moloo-* types.
+  const types = [...clipboardData.types];
+  const molooType = types.find((type) => type.startsWith("application/x-moloo-"));
+  if (!molooType) return null;
+
+  const data = clipboardData.getData(molooType);
+  if (!data) return null;
+
+  // Ensure adapter still wants object paste (has pasteObject).
+  void adapter;
+  return {
+    mimeType: molooType,
+    data,
+    text: clipboardData.getData("text/plain") || undefined,
+  };
+}
+
+export type ClipboardRouter = ReturnType<typeof createClipboardRouter>;

package/src/commands/clipboard/types.ts

@@ -0,0 +1,20 @@
+export type ClipboardPayload = {
+  /** Custom MIME type, e.g. `application/x-moloo-canvas`. */
+  mimeType: string;
+  data: string;
+  /** Optional plain-text fallback for foreign paste targets. */
+  text?: string;
+};
+
+export type ClipboardSelection =
+  | { kind: "text" }
+  | { kind: "object"; payload: ClipboardPayload }
+  | { kind: "none" };
+
+export type ClipboardAdapter = {
+  getSelection(): ClipboardSelection;
+  /** Apply an object payload (and optional text) from a paste event. */
+  pasteObject?(payload: ClipboardPayload): void | Promise<void>;
+  /** Delete current object selection (used by cut). */
+  deleteSelection?(): void | Promise<void>;
+};

package/src/commands/history/stack.ts

@@ -0,0 +1,53 @@
+export type UndoCommand = {
+  id?: string;
+  undo: () => void | Promise<void>;
+  redo: () => void | Promise<void>;
+};
+
+export type UndoStack = {
+  push(command: UndoCommand): void;
+  undo(): Promise<boolean>;
+  redo(): Promise<boolean>;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  clear(): void;
+};
+
+export function createUndoStack(limit = 100): UndoStack {
+  const past: UndoCommand[] = [];
+  const future: UndoCommand[] = [];
+
+  return {
+    push(command) {
+      past.push(command);
+      if (past.length > limit) {
+        past.shift();
+      }
+      future.length = 0;
+    },
+    async undo() {
+      const command = past.pop();
+      if (!command) return false;
+      await command.undo();
+      future.push(command);
+      return true;
+    },
+    async redo() {
+      const command = future.pop();
+      if (!command) return false;
+      await command.redo();
+      past.push(command);
+      return true;
+    },
+    canUndo() {
+      return past.length > 0;
+    },
+    canRedo() {
+      return future.length > 0;
+    },
+    clear() {
+      past.length = 0;
+      future.length = 0;
+    },
+  };
+}