@moloodev/editor-sdk 0.0.0-stage → 0.2.0

package/src/protocol.ts

@@ -0,0 +1,471 @@
+import {
+  bundleConfirmSchema,
+  compositionSchema,
+  publicationSchema,
+} from "@moloodev/platform";
+import { documentSchema } from "./print";
+import { z } from "zod";
+import {
+  chromeManifestSchema,
+  type ChromeManifest,
+} from "./chrome-manifest";
+import type {
+  EditorEvent,
+  EditorOperation,
+  EditorRequest,
+  EditorRequestType,
+  EditorResponse,
+  EditorSuccess,
+} from "./index";
+import { jsonSchema } from "./json-schema";
+
+export const EDITOR_LAYOUT_BYTES_MAX = 8_192;
+export const EDITOR_LAYOUT_PANELS_MAX = 32;
+export const EDITOR_LAYOUT_SECTIONS_MAX = 64;
+export const EDITOR_CLIPBOARD_TEXT_MAX = 1_000_000;
+export const EDITOR_DOWNLOAD_BYTES_MAX = 52_428_800;
+export const EDITOR_IMPORT_BYTES_MAX = 4 * 1024 * 1024;
+export const EDITOR_FILENAME_MAX = 255;
+export const EDITOR_ASSET_FILE_BYTES_MAX = 8 * 1024 * 1024;
+
+const layoutRecordKey = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/);
+
+export const layoutValuesSchema = z.strictObject({
+  panels: z.record(
+    layoutRecordKey,
+    z.strictObject({
+      visible: z.boolean(),
+      size: z.union([
+        z.number().int().min(0).max(100_000),
+        z.templateLiteral([z.number(), "%"])
+          .refine((size) => /^\d{1,3}(\.\d{1,4})?%$/.test(size) && Number.parseFloat(size) <= 100),
+      ]).exactOptional(),
+    }),
+  ).refine((panels) => Object.keys(panels).length <= EDITOR_LAYOUT_PANELS_MAX),
+  collapsed: z.record(layoutRecordKey, z.boolean())
+    .refine((collapsed) => Object.keys(collapsed).length <= EDITOR_LAYOUT_SECTIONS_MAX)
+    .exactOptional(),
+}).refine((layout) => JSON.stringify(layout).length <= EDITOR_LAYOUT_BYTES_MAX);
+
+const base64Schema = z.string()
+  .max(4 * Math.ceil(EDITOR_DOWNLOAD_BYTES_MAX / 3))
+  .refine((data) => {
+    if (data.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(data)) return false;
+    const padding = data.indexOf("=");
+    return padding === -1 ||
+      (padding === data.length - 1 && data.endsWith("=")) ||
+      (padding === data.length - 2 && data.endsWith("=="));
+  });
+
+export const importBase64Schema = base64Schema.max(4 * Math.ceil(EDITOR_IMPORT_BYTES_MAX / 3));
+
+const mimeName = "[A-Za-z0-9][A-Za-z0-9!#$&^_.+\\-]{0,126}";
+const mimeToken = "[A-Za-z0-9!#$%&'*+.^_`|~\\-]+";
+const mimeValue = String.raw`(?:${mimeToken}|"(?:[^"\\\r\n]|\\[^\r\n])*")`;
+const mimePattern = new RegExp(`^${mimeName}/${mimeName}(?:;[ \t]*${mimeToken}=${mimeValue})*$`);
+const mimeTypeSchema = z.string().refine((value) => !/[\r\n]/.test(value) && mimePattern.test(value));
+
+const httpsUrlSchema = z.string().refine((value) => {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+});
+
+const storageModeSchema = z.enum(["json", "text", "blob"]);
+
+const assetSchema = z.strictObject({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  storageMode: storageModeSchema.exactOptional(),
+  contentType: z.string().nullable().exactOptional(),
+  schema: z.string().nullable().exactOptional(),
+  path: z.string(),
+  epoch: z.number(),
+  headRevision: z.number(),
+  updatedAt: z.string(),
+  contentBytes: z.number(),
+  locked: z.boolean(),
+  lockHeld: z.boolean(),
+  trashed: z.boolean(),
+});
+
+const revisionSchema = z.strictObject({
+  id: z.string(),
+  assetId: z.string(),
+  revision: z.number(),
+  message: z.string(),
+  contentBytes: z.number(),
+  createdAt: z.string(),
+});
+
+const emptySchema = z.record(z.string(), z.never());
+
+const sessionSchema = z.strictObject({
+  asset: z.strictObject({
+    id: z.string(),
+    type: z.string(),
+    name: z.string(),
+    storageMode: storageModeSchema.exactOptional(),
+    contentType: z.string().nullable().exactOptional(),
+    schema: z.string().nullable().exactOptional(),
+  }).nullable(),
+  mode: z.enum(["idle", "loading", "read", "edit"]),
+  data: z.record(z.string(), jsonSchema).nullable(),
+  syncStatus: z.enum(["live", "pending", "offline", "error"]),
+});
+
+const accessSchema = z.strictObject({
+  canManage: z.boolean(),
+});
+
+const themeSchema = z.strictObject({
+  theme: z.enum(["dark", "light"]),
+});
+
+const commandIdSchema = z.string().min(1);
+
+const commandInvokeBodySchema = z.strictObject({
+  commandId: commandIdSchema,
+});
+
+const commandStateBodySchema = z.strictObject({
+  id: commandIdSchema,
+  visible: z.boolean(),
+  disabled: z.boolean(),
+  pressed: z.boolean(),
+  label: z.string().max(200),
+});
+
+const pickBodySchema = z.strictObject({
+  acceptedTypes: z.array(z.string()).exactOptional(),
+  excludeTypes: z.array(z.string()).exactOptional(),
+  excludeIds: z.array(z.string()).exactOptional(),
+});
+
+const openBrowserBodySchema = z.strictObject({
+  excludeIds: z.array(z.string()).readonly().exactOptional(),
+});
+
+const pickSuccessSchema = z.union([
+  z.strictObject({
+    cancelled: z.literal(false),
+    assets: z.array(assetSchema),
+  }),
+  z.strictObject({
+    cancelled: z.literal(true),
+  }),
+]);
+
+function requestOf<Type extends EditorRequestType>(
+  type: Type,
+  body: z.ZodType<EditorOperation[Type]["body"]>,
+) {
+  return z.strictObject({
+    v: z.literal(1),
+    id: z.string(),
+    type: z.literal(type),
+    body,
+  });
+}
+
+function successOf<Body>(body: z.ZodType<Body>) {
+  return z.strictObject({
+    v: z.literal(1),
+    id: z.string(),
+    ok: z.literal(true),
+    body,
+  });
+}
+
+export const editorRequestSchema = z.discriminatedUnion("type", [
+  requestOf("asset.rename", z.strictObject({ name: z.string().min(1).max(EDITOR_FILENAME_MAX) })),
+  requestOf("asset.read", z.strictObject({ id: z.string().min(1) })),
+  requestOf("asset.list", z.strictObject({ type: z.string().exactOptional() })),
+  requestOf("asset.listRevisions", z.strictObject({ id: z.string() })),
+  requestOf("asset.getComposition", z.strictObject({ id: z.string() })),
+  requestOf("asset.getPublication", z.strictObject({ id: z.string() })),
+  requestOf(
+    "asset.confirmBundle",
+    z.strictObject({
+      id: z.string(),
+      message: z.string(),
+      reviewed: z.string(),
+    }),
+  ),
+  requestOf(
+    "asset.putPublication",
+    z.strictObject({
+      id: z.string(),
+      publication: publicationSchema,
+    }),
+  ),
+  requestOf("host.pick", pickBodySchema),
+  requestOf(
+    "host.openAsset",
+    z.strictObject({ id: z.string(), type: z.string() }),
+  ),
+  requestOf("host.openInfo", z.strictObject({ id: z.string() })),
+  requestOf("host.start", emptySchema),
+  requestOf("host.openBrowser", openBrowserBodySchema),
+  requestOf("host.clipboardWrite", z.strictObject({
+    text: z.string().max(EDITOR_CLIPBOARD_TEXT_MAX),
+  })),
+  requestOf("host.download", z.union([
+    z.strictObject({
+      filename: z.string().min(1).max(EDITOR_FILENAME_MAX),
+      mimeType: mimeTypeSchema,
+      content: z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("text"), text: z.string().max(EDITOR_DOWNLOAD_BYTES_MAX) }),
+        z.strictObject({ kind: z.literal("base64"), data: base64Schema }),
+      ]),
+    }),
+    z.strictObject({ url: httpsUrlSchema }),
+  ])),
+  requestOf("host.openPopup", z.strictObject({ url: httpsUrlSchema })),
+  requestOf("host.render", z.strictObject({
+    format: z.literal("pdf"),
+    document: documentSchema,
+    name: z.string().max(EDITOR_FILENAME_MAX),
+  })),
+  requestOf("doc.append", z.strictObject({ assetId: z.string(), update: z.string() })),
+  requestOf("chrome.submit", chromeManifestSchema),
+  requestOf("layout.load", emptySchema),
+  requestOf("layout.save", z.strictObject({ layout: layoutValuesSchema })),
+]);
+
+const failureSchema = z.strictObject({
+  v: z.literal(1),
+  id: z.string(),
+  ok: z.literal(false),
+  code: z.string(),
+});
+
+const publicationSuccess = successOf(publicationSchema);
+const emptySuccess = successOf(emptySchema);
+
+const successByType: {
+  [Type in EditorRequestType]: z.ZodType<EditorSuccess<Type>>;
+} = {
+  "asset.rename": successOf(z.strictObject({ name: z.string() })),
+  "asset.read": successOf(z.strictObject({
+    asset: assetSchema,
+    payload: z.record(z.string(), z.json()),
+    fileUrl: z.string()
+      .max(4 * Math.ceil(EDITOR_ASSET_FILE_BYTES_MAX / 3) + 256)
+      .regex(/^data:[a-z0-9.+-]+\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/]*={0,2}$/i)
+      .nullable(),
+  })),
+  "asset.list": successOf(z.array(assetSchema)),
+  "asset.listRevisions": successOf(z.array(revisionSchema)),
+  "asset.getComposition": successOf(compositionSchema),
+  "asset.getPublication": publicationSuccess,
+  "asset.confirmBundle": successOf(bundleConfirmSchema),
+  "asset.putPublication": publicationSuccess,
+  "host.pick": successOf(pickSuccessSchema),
+  "host.openAsset": emptySuccess,
+  "host.openInfo": emptySuccess,
+  "host.start": emptySuccess,
+  "host.openBrowser": emptySuccess,
+  "host.clipboardWrite": emptySuccess,
+  "host.download": emptySuccess,
+  "host.openPopup": emptySuccess,
+  "host.render": successOf(z.strictObject({ url: httpsUrlSchema })),
+  "doc.append": emptySuccess,
+  "chrome.submit": emptySuccess,
+  "layout.load": successOf(z.strictObject({ layout: layoutValuesSchema.nullable() })),
+  "layout.save": emptySuccess,
+};
+
+export const editorResponseSchema = z.union([
+  successByType["asset.rename"],
+  successByType["asset.read"],
+  successByType["asset.list"],
+  successByType["asset.listRevisions"],
+  successByType["asset.getComposition"],
+  successByType["asset.getPublication"],
+  successByType["asset.confirmBundle"],
+  successByType["host.pick"],
+  successByType["host.start"],
+  successByType["host.render"],
+  successByType["layout.load"],
+  failureSchema,
+]);
+
+const sessionOpenSchema = z.strictObject({
+  v: z.literal(1),
+  type: z.literal("session.open"),
+  body: z.strictObject({
+    editorId: z.string(),
+  }),
+});
+
+export type SessionOpen = z.infer<typeof sessionOpenSchema>;
+
+const handshakeReplySchema = z.discriminatedUnion("ok", [
+  z.strictObject({
+    v: z.literal(1),
+    ok: z.literal(true),
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    ok: z.literal(false),
+    code: z.enum(["version", "schema", "rejected"]),
+  }),
+]);
+
+export type HandshakeReply = z.infer<typeof handshakeReplySchema>;
+
+export const editorEventSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("file.import"),
+    body: z.strictObject({
+      name: z.string().min(1).max(EDITOR_FILENAME_MAX),
+      data: importBase64Schema,
+    }),
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("session"),
+    body: sessionSchema,
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("access"),
+    body: accessSchema,
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("theme"),
+    body: themeSchema,
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("doc.update"),
+    body: z.strictObject({ assetId: z.string(), update: z.string() }),
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("host.createRequested"),
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("command.invoke"),
+    body: commandInvokeBodySchema,
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("command.shortcut"),
+    body: z.strictObject({ key: z.string().min(1), commandId: commandIdSchema }),
+  }),
+  z.strictObject({
+    v: z.literal(1),
+    type: z.literal("command.state"),
+    body: commandStateBodySchema,
+  }),
+]);
+
+export type ProtocolCode = "version" | "schema";
+
+export type ProtocolResult<T> =
+  | { ok: true; message: T }
+  | { ok: false; code: ProtocolCode };
+
+function wrongVersion(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  if (!Object.hasOwn(value, "v")) return false;
+  return Reflect.get(value, "v") !== 1;
+}
+
+// Bundle schemas strip unknown keys. A stripped tree is not the wire value.
+export function sameTree(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (typeof left !== "object" || typeof right !== "object") return false;
+  if (left === null || right === null) return false;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) return false;
+    if (left.length !== right.length) return false;
+    return left.every((item, index) => sameTree(item, right[index]));
+  }
+  const leftKeys = Object.keys(left);
+  if (leftKeys.length !== Object.keys(right).length) return false;
+  return leftKeys.every(
+    (key) =>
+      Object.hasOwn(right, key) &&
+      sameTree(Reflect.get(left, key), Reflect.get(right, key)),
+  );
+}
+
+function parseWith<T>(
+  schema: z.ZodType<T>,
+  value: unknown,
+): ProtocolResult<T> {
+  if (wrongVersion(value)) return { ok: false, code: "version" };
+  const parsed = schema.safeParse(value);
+  if (!parsed.success || !sameTree(parsed.data, value)) {
+    return { ok: false, code: "schema" };
+  }
+  return { ok: true, message: parsed.data };
+}
+
+export function parseEditorRequest(value: unknown): ProtocolResult<EditorRequest> {
+  return parseWith(editorRequestSchema, value);
+}
+
+export function parseEditorResponse(
+  value: unknown,
+): ProtocolResult<EditorResponse> {
+  return parseWith(editorResponseSchema, value);
+}
+
+export function parseEditorResponseFor<Type extends EditorRequestType>(
+  type: Type,
+  value: unknown,
+): ProtocolResult<EditorResponse<Type>> {
+  if (wrongVersion(value)) return { ok: false, code: "version" };
+  const failed = failureSchema.safeParse(value);
+  if (failed.success && sameTree(failed.data, value)) {
+    return { ok: true, message: failed.data };
+  }
+  return parseWith(successByType[type], value);
+}
+
+export function parseSessionOpen(value: unknown): ProtocolResult<SessionOpen> {
+  return parseWith(sessionOpenSchema, value);
+}
+
+export function parseHandshakeReply(
+  value: unknown,
+): ProtocolResult<HandshakeReply> {
+  return parseWith(handshakeReplySchema, value);
+}
+
+export function parseEditorEvent(value: unknown): ProtocolResult<EditorEvent> {
+  return parseWith(editorEventSchema, value);
+}
+
+export { chromeManifestSchema };
+export type { ChromeManifest };
+
+export function parseChromeManifest(
+  value: unknown,
+): { ok: true; message: ChromeManifest } | { ok: false; code: "schema" } {
+  const parsed = chromeManifestSchema.safeParse(value);
+  if (!parsed.success || !sameTree(parsed.data, value)) {
+    return { ok: false, code: "schema" };
+  }
+  return { ok: true, message: parsed.data };
+}
+
+export {
+  isEditorLabel,
+  isPublisherName,
+  parseEditorId,
+  reservedPublishers,
+} from "./editor-id";
+export type { EditorId } from "./editor-id";

package/src/render-result.ts

@@ -0,0 +1,25 @@
+const renderCodes = ["forbidden", "invalid", "unsupported", "too-large"] as const;
+
+export type RenderCode = (typeof renderCodes)[number];
+
+export function renderCode(value: string): RenderCode | undefined {
+  for (const code of renderCodes) {
+    if (value === code) return code;
+  }
+  return undefined;
+}
+
+export class RenderFailure extends Error {
+  readonly code: RenderCode;
+
+  constructor(code: RenderCode) {
+    super(code);
+    this.name = "RenderFailure";
+    this.code = code;
+  }
+}
+
+export function renderFailureCode(error: unknown): RenderCode | undefined {
+  if (!(error instanceof RenderFailure)) return undefined;
+  return error.code;
+}

package/src/view/editor-chrome.ts

@@ -0,0 +1,28 @@
+import type { ContributionManifest, EditorManifest } from "../commands";
+import { chromeManifestSchema, type ChromeManifest } from "../protocol";
+import { EDITOR_COMMON_CONTRIBUTES } from "../editor-common";
+
+type ChromeLayout = Pick<ChromeManifest, "layout" | "titles" | "panelHeaders">;
+
+export function createEditorChrome(manifest: EditorManifest, binding: {
+  spec: { readonly root: string; readonly elements: object };
+  titles: ChromeLayout["titles"];
+  panelHeaders?: ChromeLayout["panelHeaders"];
+}) {
+  const chromeManifest: ChromeManifest = chromeManifestSchema.parse({
+    contributes: {
+      commands: [...EDITOR_COMMON_CONTRIBUTES.commands, ...(manifest.contributes?.commands ?? [])],
+      menus: [...EDITOR_COMMON_CONTRIBUTES.menus, ...(manifest.contributes?.menus ?? [])],
+      keybindings: [...EDITOR_COMMON_CONTRIBUTES.keybindings, ...(manifest.contributes?.keybindings ?? [])],
+    },
+    layout: binding.spec,
+    titles: binding.titles,
+    ...(binding.panelHeaders && Object.keys(binding.panelHeaders).length > 0 ? { panelHeaders: binding.panelHeaders } : {}),
+  });
+  const contribution: ContributionManifest = {
+    id: manifest.id,
+    activation: "exact",
+    ...chromeManifest.contributes,
+  };
+  return { chromeManifest, contribution };
+}