@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/testing-vscode-stub.ts

@@ -0,0 +1,2 @@
+// "@miragon/modeler-shell/testing/vscode-stub": a stand-in for VS Code around a webview test page.
+export * from "./testing/vscode-stub.js";

package/src/testing.ts

@@ -0,0 +1,2 @@
+// "@miragon/modeler-shell/testing": the Playwright-driven shell conformance kit (Playwright injected).
+export * from "./testing/index.js";

package/src/vscode/extension/html.ts

@@ -0,0 +1,107 @@
+import { appearanceAttributes, type Appearance } from "../../core/index.js";
+
+export interface WebviewHtmlOptions {
+  /** `webview.cspSource` */
+  cspSource: string;
+  /** The bundle, `webview.asWebviewUri(…).toString()`. */
+  scriptUri: string;
+  /** Stylesheets in load order (token CSS first, see API.md). */
+  styleUris?: readonly string[] | undefined;
+  /** `<title>` */
+  title: string;
+  /** The tool's UI language for `<html lang>`; English modelers pass `"en"`. */
+  lang: string;
+  /** Resolved appearance (`currentAppearance`), written before the first paint. */
+  appearance: Appearance;
+  /** Markup inside `<body>` before the script; default `<div id="app"></div>`. */
+  body?: string | undefined;
+  /** Script nonce; default `createNonce()`. */
+  nonce?: string | undefined;
+  /**
+   * Allow inline styles (`style-src … 'unsafe-inline'`), default `true`: renderers write `style`
+   * attributes into markup (palette entries, SVG strings). The shell and diagram-js themselves
+   * only style through the CSSOM and run without it; pass `false` once the renderer does too.
+   */
+  inlineStyles?: boolean | undefined;
+}
+
+const NONCE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const NONCE_LENGTH = 32;
+/** Bytes at or above this limit are rejected, so every character is equally likely. */
+const UNBIASED_BYTE_LIMIT = 256 - (256 % NONCE_ALPHABET.length);
+/** The `base64-value` of a CSP `nonce-source`. */
+const CSP_NONCE = /^[A-Za-z0-9+/_-]+={0,2}$/;
+
+const DEFAULT_BODY = '<div id="app"></div>';
+
+/** 32 characters `[A-Za-z0-9]` from `crypto.getRandomValues`. */
+export function createNonce(): string {
+  let nonce = "";
+  while (nonce.length < NONCE_LENGTH) {
+    for (const byte of crypto.getRandomValues(new Uint8Array(NONCE_LENGTH))) {
+      if (byte < UNBIASED_BYTE_LIMIT && nonce.length < NONCE_LENGTH) {
+        nonce += NONCE_ALPHABET.charAt(byte % NONCE_ALPHABET.length);
+      }
+    }
+  }
+  return nonce;
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function attribute(name: string, value: string): string {
+  return `${name}="${escapeHtml(value)}"`;
+}
+
+function contentSecurityPolicy(cspSource: string, nonce: string, inlineStyles: boolean): string {
+  return [
+    "default-src 'none'",
+    `img-src ${cspSource} data: blob:`,
+    inlineStyles ? `style-src ${cspSource} 'unsafe-inline'` : `style-src ${cspSource}`,
+    `font-src ${cspSource} data:`,
+    `script-src 'nonce-${nonce}'`,
+  ].join("; ");
+}
+
+/**
+ * The webview document: `<html lang class="cd-shell-document" data-cd-theme [data-cd-kontrast]>`,
+ * the CSP (`default-src 'none'`, `img-src <cspSource> data: blob:`, `style-src <cspSource>` plus
+ * `'unsafe-inline'` unless `inlineStyles: false`, `font-src <cspSource> data:`,
+ * `script-src 'nonce-…'`), the stylesheets, `body` and the nonce'd script. Attribute values and the
+ * title are escaped; `body` is markup and is not. Throws for a `nonce` that is not a CSP base64
+ * value.
+ */
+export function renderWebviewHtml(options: WebviewHtmlOptions): string {
+  const nonce = options.nonce ?? createNonce();
+  if (!CSP_NONCE.test(nonce)) {
+    throw new Error(`@miragon/modeler-shell: renderWebviewHtml got an invalid nonce "${nonce}"`);
+  }
+  const appearance = appearanceAttributes(options.appearance);
+  const kontrast = appearance["data-cd-kontrast"];
+  const htmlAttributes = [
+    attribute("lang", options.lang),
+    attribute("class", "cd-shell-document"),
+    attribute("data-cd-theme", appearance["data-cd-theme"]),
+    ...(kontrast ? [attribute("data-cd-kontrast", kontrast)] : []),
+  ].join(" ");
+  const stylesheets = (options.styleUris ?? []).map(
+    (uri) => `\n    <link ${attribute("rel", "stylesheet")} ${attribute("href", uri)} />`,
+  );
+
+  return `<!doctype html>
+<html ${htmlAttributes}>
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy" ${attribute("content", contentSecurityPolicy(options.cspSource, nonce, options.inlineStyles !== false))} />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />${stylesheets.join("")}
+    <title>${escapeHtml(options.title)}</title>
+  </head>
+  <body>
+    ${options.body ?? DEFAULT_BODY}
+    <script ${attribute("nonce", nonce)} ${attribute("src", options.scriptUri)}></script>
+  </body>
+</html>
+`;
+}

package/src/vscode/extension/index.ts

@@ -0,0 +1,8 @@
+export type { ColorThemeLike, DisposableLike, VsCodeLike, WebviewPanelLike } from "./types.js";
+export type { WebviewHtmlOptions } from "./html.js";
+export { createNonce, renderWebviewHtml } from "./html.js";
+export type { ThemeBridgeOptions } from "./theme-bridge.js";
+export { connectThemeBridge, currentAppearance } from "./theme-bridge.js";
+export { revealFileLabel } from "./reveal.js";
+export type { AppearanceMessage } from "../protocol.js";
+export { APPEARANCE_MESSAGE_TYPE, appearanceMessage, isAppearanceMessage } from "../protocol.js";

package/src/vscode/extension/reveal.ts

@@ -0,0 +1,9 @@
+/**
+ * The label VS Code itself uses for revealing a file, for the action on the export notification:
+ * `darwin` "Reveal in Finder", `win32` "Reveal in File Explorer", otherwise "Open Containing Folder".
+ */
+export function revealFileLabel(platform: string): string {
+  if (platform === "darwin") return "Reveal in Finder";
+  if (platform === "win32") return "Reveal in File Explorer";
+  return "Open Containing Folder";
+}

package/src/vscode/extension/theme-bridge.ts

@@ -0,0 +1,85 @@
+import {
+  requestedAppearance,
+  resolveAppearance,
+  type Appearance,
+  type ColorThemeSetting,
+  type Theme,
+} from "../../core/index.js";
+import { appearanceMessage } from "../protocol.js";
+import type { DisposableLike, VsCodeLike, WebviewPanelLike } from "./types.js";
+
+export interface ThemeBridgeOptions {
+  /** The modes the modeler can show, a static value of the modeler package (`["light"]` today). */
+  themes: readonly Theme[];
+  /** Full key of `miragon.<modeler>.colorTheme`; omit until the modeler can show dark. */
+  settingKey?: string | undefined;
+}
+
+function isColorThemeSetting(value: unknown): value is ColorThemeSetting {
+  return value === "automatic" || value === "light" || value === "dark";
+}
+
+function readColorThemeSetting(vscode: VsCodeLike, settingKey: string): ColorThemeSetting | undefined {
+  const separator = settingKey.lastIndexOf(".");
+  const value =
+    separator < 0
+      ? vscode.workspace.getConfiguration().get<unknown>(settingKey)
+      : vscode.workspace
+          .getConfiguration(settingKey.slice(0, separator))
+          .get<unknown>(settingKey.slice(separator + 1));
+  return isColorThemeSetting(value) ? value : undefined;
+}
+
+/**
+ * The resolved appearance right now: color theme kind (and setting) through `resolveAppearance`.
+ * A setting value outside `automatic | light | dark` counts as `automatic`.
+ */
+export function currentAppearance(vscode: VsCodeLike, options: ThemeBridgeOptions): Appearance {
+  const setting = options.settingKey ? readColorThemeSetting(vscode, options.settingKey) : undefined;
+  return resolveAppearance(requestedAppearance(vscode.window.activeColorTheme.kind, setting), options.themes);
+}
+
+/**
+ * Posts an `AppearanceMessage` to the panel's webview on `onDidChangeActiveColorTheme`, on a change
+ * of `settingKey` and whenever the panel becomes visible again (hidden retained webviews may miss
+ * messages). Disposes itself with the panel. Throws when `themes` is empty.
+ */
+export function connectThemeBridge(
+  vscode: VsCodeLike,
+  panel: WebviewPanelLike,
+  options: ThemeBridgeOptions,
+): DisposableLike {
+  if (options.themes.length === 0) {
+    throw new Error("@miragon/modeler-shell: connectThemeBridge needs at least one theme");
+  }
+  const { settingKey } = options;
+  const post = (): void => {
+    void panel.webview.postMessage(appearanceMessage(currentAppearance(vscode, options)));
+  };
+
+  let wasVisible = panel.visible;
+  const subscriptions: DisposableLike[] = [
+    vscode.window.onDidChangeActiveColorTheme(post),
+    panel.onDidChangeViewState(({ webviewPanel }) => {
+      const becameVisible = webviewPanel.visible && !wasVisible;
+      wasVisible = webviewPanel.visible;
+      if (becameVisible) post();
+    }),
+  ];
+  if (settingKey) {
+    subscriptions.push(
+      vscode.workspace.onDidChangeConfiguration((event) => {
+        if (event.affectsConfiguration(settingKey)) post();
+      }),
+    );
+  }
+
+  let disposed = false;
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    for (const subscription of subscriptions.splice(0)) subscription.dispose();
+  };
+  subscriptions.push(panel.onDidDispose(dispose));
+  return { dispose };
+}

package/src/vscode/extension/types.ts

@@ -0,0 +1,36 @@
+/**
+ * The parts of the `vscode` namespace the extension helpers use, typed structurally: the shell
+ * never imports `vscode`; the extension passes its own `import * as vscode from "vscode"`.
+ */
+
+export interface DisposableLike {
+  dispose(): unknown;
+}
+
+export interface ColorThemeLike {
+  /** `vscode.ColorThemeKind`: 1 Light, 2 Dark, 3 HighContrast, 4 HighContrastLight. */
+  readonly kind: number;
+}
+
+export interface VsCodeLike {
+  readonly window: {
+    readonly activeColorTheme: ColorThemeLike;
+    onDidChangeActiveColorTheme(listener: (theme: ColorThemeLike) => unknown): DisposableLike;
+  };
+  readonly workspace: {
+    getConfiguration(section?: string): { get<T>(key: string): T | undefined };
+    onDidChangeConfiguration(
+      listener: (event: { affectsConfiguration(section: string): boolean }) => unknown,
+    ): DisposableLike;
+  };
+}
+
+/** `vscode.WebviewPanel` as far as the theme bridge needs it. */
+export interface WebviewPanelLike {
+  readonly webview: { postMessage(message: unknown): unknown };
+  readonly visible: boolean;
+  onDidChangeViewState(
+    listener: (event: { readonly webviewPanel: { readonly visible: boolean } }) => unknown,
+  ): DisposableLike;
+  onDidDispose(listener: () => unknown): DisposableLike;
+}

package/src/vscode/protocol.ts

@@ -0,0 +1,31 @@
+import type { Appearance } from "../core/index.js";
+
+/** The one message the theme bridge posts to the webview. */
+export const APPEARANCE_MESSAGE_TYPE = "modelerShell.appearance";
+
+export interface AppearanceMessage {
+  type: typeof APPEARANCE_MESSAGE_TYPE;
+  /** Already resolved against the modeler's themes. */
+  appearance: Appearance;
+}
+
+/** A plain, JSON-safe message (no `kontrast: undefined` key). */
+export function appearanceMessage(appearance: Appearance): AppearanceMessage {
+  return {
+    type: APPEARANCE_MESSAGE_TYPE,
+    appearance: appearance.kontrast
+      ? { theme: appearance.theme, kontrast: appearance.kontrast }
+      : { theme: appearance.theme },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Type guard for `MessageEvent.data` in the webview. */
+export function isAppearanceMessage(value: unknown): value is AppearanceMessage {
+  if (!isRecord(value) || value.type !== APPEARANCE_MESSAGE_TYPE || !isRecord(value.appearance)) return false;
+  const { theme, kontrast } = value.appearance;
+  return (theme === "light" || theme === "dark") && (kontrast === undefined || kontrast === "hoch");
+}

package/src/vscode/webview/appearance.ts

@@ -0,0 +1,141 @@
+import {
+  REDUCED_MOTION_CLASS,
+  appearanceAttributes,
+  appearanceFromBodyClasses,
+  reducedMotionFromBodyClasses,
+  resolveAppearance,
+  type Appearance,
+  type Theme,
+} from "../../core/index.js";
+import { isAppearanceMessage } from "../protocol.js";
+
+const NO_TRANSITION_CLASS = "cd-shell-no-transition";
+
+/** The latest mode switch per `<html>`: only its second frame may lift the transition stop. */
+const latestSwitch = new WeakMap<Element, number>();
+
+function showsAppearance(element: Element, appearance: Appearance): boolean {
+  const attributes = appearanceAttributes(appearance);
+  return (
+    element.getAttribute("data-cd-theme") === attributes["data-cd-theme"] &&
+    element.getAttribute("data-cd-kontrast") === (attributes["data-cd-kontrast"] ?? null)
+  );
+}
+
+/**
+ * Writes `data-cd-theme` and `data-cd-kontrast` on `element` (default `<html>`) in one task, with
+ * transitions suppressed for one frame: adds `cd-shell-no-transition` to `<html>`, sets both
+ * attributes and removes the class in a nested `requestAnimationFrame` (after the last of several
+ * quick switches).
+ */
+export function applyAppearance(appearance: Appearance, element?: HTMLElement): void {
+  const target = element ?? document.documentElement;
+  const html = target.ownerDocument.documentElement;
+  const attributes = appearanceAttributes(appearance);
+  const kontrast = attributes["data-cd-kontrast"];
+
+  const switchId = (latestSwitch.get(html) ?? 0) + 1;
+  latestSwitch.set(html, switchId);
+  html.classList.add(NO_TRANSITION_CLASS);
+  target.setAttribute("data-cd-theme", attributes["data-cd-theme"]);
+  if (kontrast) target.setAttribute("data-cd-kontrast", kontrast);
+  else target.removeAttribute("data-cd-kontrast");
+
+  requestAnimationFrame(() =>
+    requestAnimationFrame(() => {
+      if (latestSwitch.get(html) !== switchId) return;
+      latestSwitch.delete(html);
+      html.classList.remove(NO_TRANSITION_CLASS);
+    }),
+  );
+}
+
+export interface AppearanceListenerOptions {
+  /** The modes the modeler can show; the body-class fallback resolves against them. */
+  themes: readonly Theme[];
+}
+
+/**
+ * Listens for `AppearanceMessage`s on `window` and applies them to `<html>`, resolved against
+ * `themes` once more so a webview never shows a mode its bundle cannot. A page whose `<html>` has
+ * no `data-cd-theme` at connect (no `renderWebviewHtml`) falls back to the VS Code body classes,
+ * through a `MutationObserver` on `<body>` until the first message (resolved against `themes`).
+ * With the attributes of `renderWebviewHtml` there is no fallback: the extension's bridge knows the
+ * `colorTheme` setting, the body classes do not, and VS Code changes them before the bridge's
+ * message arrives, which would flash the mode without the setting. Returns the disconnect
+ * function. Throws when `themes` is empty.
+ */
+export function connectAppearance(options: AppearanceListenerOptions): () => void {
+  const { themes } = options;
+  if (themes.length === 0) {
+    throw new Error("@miragon/modeler-shell: connectAppearance needs at least one theme");
+  }
+  const html = document.documentElement;
+  const show = (requested: Appearance): void => {
+    const resolved = resolveAppearance(requested, themes);
+    if (!showsAppearance(html, resolved)) applyAppearance(resolved, html);
+  };
+
+  let fallbackActive = !html.hasAttribute("data-cd-theme");
+  const applyBodyClasses = (): void => {
+    if (!fallbackActive || !document.body) return;
+    const requested = appearanceFromBodyClasses(document.body.classList);
+    if (requested) show(requested);
+  };
+  const observer = new MutationObserver(applyBodyClasses);
+  const startFallback = (): void => {
+    if (!fallbackActive || !document.body) return;
+    observer.observe(document.body, { attributes: true, attributeFilter: ["class"] });
+    applyBodyClasses();
+  };
+  const stopFallback = (): void => {
+    if (!fallbackActive) return;
+    fallbackActive = false;
+    observer.disconnect();
+    document.removeEventListener("DOMContentLoaded", startFallback);
+  };
+
+  const onMessage = (event: MessageEvent): void => {
+    if (!isAppearanceMessage(event.data)) return;
+    stopFallback();
+    show(event.data.appearance);
+  };
+
+  window.addEventListener("message", onMessage);
+  if (document.body) startFallback();
+  else if (fallbackActive) document.addEventListener("DOMContentLoaded", startFallback, { once: true });
+
+  return () => {
+    window.removeEventListener("message", onMessage);
+    fallbackActive = false;
+    observer.disconnect();
+    document.removeEventListener("DOMContentLoaded", startFallback);
+  };
+}
+
+/**
+ * Mirrors VS Code's `workbench.reduceMotion` (the body class `vscode-reduce-motion`, which VS Code
+ * keeps up to date) as `REDUCED_MOTION_CLASS` on `<html>` for the whole session: the shell's
+ * animations stop and an explicit fit jumps, as under `prefers-reduced-motion` (guide §5.14, §7).
+ * Returns the disconnect function, which removes the class again.
+ */
+export function connectReducedMotion(): () => void {
+  const html = document.documentElement;
+  const apply = (): void => {
+    if (document.body)
+      html.classList.toggle(REDUCED_MOTION_CLASS, reducedMotionFromBodyClasses(document.body.classList));
+  };
+  const observer = new MutationObserver(apply);
+  const start = (): void => {
+    if (!document.body) return;
+    observer.observe(document.body, { attributes: true, attributeFilter: ["class"] });
+    apply();
+  };
+  if (document.body) start();
+  else document.addEventListener("DOMContentLoaded", start, { once: true });
+  return () => {
+    observer.disconnect();
+    document.removeEventListener("DOMContentLoaded", start);
+    html.classList.remove(REDUCED_MOTION_CLASS);
+  };
+}

package/src/vscode/webview/index.ts

@@ -0,0 +1,8 @@
+export type { AppearanceListenerOptions } from "./appearance.js";
+export { applyAppearance, connectAppearance, connectReducedMotion } from "./appearance.js";
+export type { VsCodeShellOptions } from "./mount.js";
+export { mountVsCodeShell } from "./mount.js";
+export type { PersistViewOptions, PersistableView, ShellWebviewState, WebviewStateApi } from "./state.js";
+export { SHELL_STATE_KEY, persistView, readShellState, writeShellState } from "./state.js";
+export type { AppearanceMessage } from "../protocol.js";
+export { APPEARANCE_MESSAGE_TYPE, appearanceMessage, isAppearanceMessage } from "../protocol.js";

package/src/vscode/webview/mount.ts

@@ -0,0 +1,88 @@
+import { mountShell, type ShellHandle, type ShellOptions } from "../../dom/index.js";
+import { connectAppearance, connectReducedMotion, type AppearanceListenerOptions } from "./appearance.js";
+
+/** The web column's options (0.2): a VS Code webview has none of them (guide §5.2, §13.5). */
+type WebHostOptionKey = "primary" | "legal" | "file" | "appearance" | "emptyState" | "dropZone";
+
+export interface VsCodeShellOptions
+  extends Omit<ShellOptions, "host" | "keyScope" | "themes" | WebHostOptionKey>, AppearanceListenerOptions {}
+
+/** The shell's handle with a `destroy` that runs `beforeDestroy` first; every other member delegates. */
+function withDestroyHook(shell: ShellHandle, beforeDestroy: () => void): ShellHandle {
+  return {
+    get root() {
+      return shell.root;
+    },
+    get canvas() {
+      return shell.canvas;
+    },
+    get host() {
+      return shell.host;
+    },
+    get lang() {
+      return shell.lang;
+    },
+    get platform() {
+      return shell.platform;
+    },
+    get messages() {
+      return shell.messages;
+    },
+    get menu() {
+      return shell.menu;
+    },
+    get tooltip() {
+      return shell.tooltip;
+    },
+    get legend() {
+      return shell.legend;
+    },
+    get inspector() {
+      return shell.inspector;
+    },
+    get primary() {
+      return shell.primary;
+    },
+    get appearance() {
+      return shell.appearance;
+    },
+    setZoomTarget: (target) => shell.setZoomTarget(target),
+    fitInsets: () => shell.fitInsets(),
+    registerPalette: (palette) => shell.registerPalette(palette),
+    setProblems: (summary) => shell.setProblems(summary),
+    setStatus: (status, options) => shell.setStatus(status, options),
+    setEmptyHint: (visible) => shell.setEmptyHint(visible),
+    setReadOnly: (readOnly, options) => shell.setReadOnly(readOnly, options),
+    isReadOnly: () => shell.isReadOnly(),
+    setEmptyState: (shown) => shell.setEmptyState(shown),
+    isEmptyStateShown: () => shell.isEmptyStateShown(),
+    toast: (request) => shell.toast(request),
+    destroy() {
+      beforeDestroy();
+      shell.destroy();
+    },
+  };
+}
+
+/**
+ * `mountShell` for a VS Code webview: `host: "ide"`, the key listener on `document` (VS Code's own
+ * listener sits on `window`, so handled keys are stopped before it), `cd-shell-document` on
+ * `<html>`, plus `connectAppearance` and `connectReducedMotion`. `destroy()` also disconnects both.
+ */
+export function mountVsCodeShell(root: HTMLElement, options: VsCodeShellOptions): ShellHandle {
+  const { themes } = options;
+  const disconnectAppearance = connectAppearance({ themes });
+  const disconnectReducedMotion = connectReducedMotion();
+  const disconnect = (): void => {
+    disconnectAppearance();
+    disconnectReducedMotion();
+  };
+  let shell: ShellHandle;
+  try {
+    shell = mountShell(root, { ...options, host: "ide", keyScope: "document" });
+  } catch (error) {
+    disconnect();
+    throw error;
+  }
+  return withDestroyHook(shell, disconnect);
+}

package/src/vscode/webview/state.ts

@@ -0,0 +1,116 @@
+import type { Bounds, ViewportState } from "../../core/index.js";
+
+/** `acquireVsCodeApi()` as far as the state helpers need it. */
+export interface WebviewStateApi {
+  getState(): unknown;
+  setState(state: unknown): void;
+}
+
+/** What the shell keeps across a webview rebuild (guide §13.5: legend state and view). */
+export interface ShellWebviewState {
+  legendOpen?: boolean | undefined;
+  view?: ViewportState | undefined;
+}
+
+/** The key under which the shell's part lives in the webview state; other keys stay untouched. */
+export const SHELL_STATE_KEY = "modelerShell";
+
+type StateRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is StateRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function storedState(api: WebviewStateApi): StateRecord {
+  const state = api.getState();
+  return isRecord(state) ? state : {};
+}
+
+function viewboxFrom(value: unknown): Bounds | undefined {
+  if (!isRecord(value)) return undefined;
+  const { x, y, width, height } = value;
+  if (typeof x !== "number" || typeof y !== "number") return undefined;
+  if (typeof width !== "number" || typeof height !== "number") return undefined;
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || !Number.isFinite(height)) {
+    return undefined;
+  }
+  return width > 0 && height > 0 ? { x, y, width, height } : undefined;
+}
+
+function viewFrom(value: unknown): ViewportState | undefined {
+  if (!isRecord(value) || typeof value.userMoved !== "boolean") return undefined;
+  const viewbox = viewboxFrom(value.viewbox);
+  return viewbox ? { viewbox, userMoved: value.userMoved } : undefined;
+}
+
+/** The shell's part of `api.getState()`; `{}` when there is none or it is malformed. */
+export function readShellState(api: WebviewStateApi): ShellWebviewState {
+  const part = storedState(api)[SHELL_STATE_KEY];
+  if (!isRecord(part)) return {};
+  const state: ShellWebviewState = {};
+  if (typeof part.legendOpen === "boolean") state.legendOpen = part.legendOpen;
+  const view = viewFrom(part.view);
+  if (view) state.view = view;
+  return state;
+}
+
+/**
+ * Merges `patch` into the shell's part and writes the whole state back, keeping every other key.
+ * A value that is `undefined` (for example `viewport.getState()` before the first import) or
+ * malformed leaves the stored value alone; nothing is written when nothing changed.
+ */
+export function writeShellState(api: WebviewStateApi, patch: ShellWebviewState): void {
+  const state = storedState(api);
+  const part = isRecord(state[SHELL_STATE_KEY]) ? (state[SHELL_STATE_KEY] as StateRecord) : {};
+  const next: StateRecord = { ...part };
+  if (typeof patch.legendOpen === "boolean") next.legendOpen = patch.legendOpen;
+  const view = viewFrom(patch.view);
+  if (view) next.view = view;
+  if (JSON.stringify(next) === JSON.stringify(state[SHELL_STATE_KEY])) return;
+  api.setState({ ...state, [SHELL_STATE_KEY]: next });
+}
+
+/** What `persistView` reads of a viewport (`connectDiagramJs(…).viewport`). */
+export interface PersistableView {
+  onChange(listener: () => void): () => void;
+  getState(): ViewportState | undefined;
+}
+
+export interface PersistViewOptions {
+  /** Quiet time before the write, default 250ms. */
+  delayMs?: number | undefined;
+}
+
+/** A pan, a wheel zoom or a fit animation changes the view on every frame. */
+const PERSIST_VIEW_DELAY_MS = 250;
+
+/**
+ * Keeps the stored view (`writeShellState(api, { view })`) up to date once the view has rested for
+ * `delayMs`, instead of one `vscode.setState` IPC message per animation frame. Returns the stop
+ * function; it writes a pending change at once.
+ */
+export function persistView(
+  api: WebviewStateApi,
+  viewport: PersistableView,
+  options: PersistViewOptions = {},
+): () => void {
+  const delayMs = options.delayMs ?? PERSIST_VIEW_DELAY_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const write = (): void => {
+    timer = undefined;
+    writeShellState(api, { view: viewport.getState() });
+  };
+  const unsubscribe = viewport.onChange(() => {
+    clearTimeout(timer);
+    timer = setTimeout(write, delayMs);
+  });
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    unsubscribe();
+    if (timer === undefined) return;
+    clearTimeout(timer);
+    write();
+  };
+}

package/src/vscode-extension.ts

@@ -0,0 +1,2 @@
+// "@miragon/modeler-shell/vscode/extension": the extension-host side (the vscode namespace is injected).
+export * from "./vscode/extension/index.js";

package/src/vscode-webview.ts

@@ -0,0 +1,2 @@
+// "@miragon/modeler-shell/vscode/webview": the webview side.
+export * from "./vscode/webview/index.js";