@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,567 @@
-# Temporary Holding Version
+# @miragon/modeler-shell
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared, framework-free chrome around Miragon diagram-js modelers: the menu button with its
+dropdown, the horizontal palette skin, the chrome tooltip, the zoom panel with its keys and fit, the
+problems pill, the status box, the empty-file hint, legend and inspector slots, the plumbing to a
+VS Code webview, and the web-app chrome (primary action, legal line, File and Appearance groups,
+problems list, toasts, empty-state card, drop zone, the web app's mode). One implementation for every modeler and every host (VS Code webview, web app,
+embedded in a foreign page), so the chrome looks and behaves the same everywhere.
+
+- **Look and behaviour** follow the Miragon design system, guide
+  [`modeler-design-system.md`][guide] §5, §6, §8, §9, §11, §12 and §13.3 to §13.5 (skill
+  `miragon-brand:modeler-tool-design`; the repository is private, the link opens for Miragon staff).
+- **Mechanics** (diagram-js services, VS Code quirks, why things are done the way they are) are in
+  the [implementation notes][notes].
+- **API**: every entry point, type and rule in [API.md][api].
+- **Plan**: Phase 4 of [Miragon/modeler-api#4](https://github.com/Miragon/modeler-api/issues/4); the
+  Event Storming modeler is the pilot.
+
+Zero runtime dependencies: diagram-js services are typed structurally, the `vscode` namespace and
+Playwright's `page` and `test` are passed in, nothing is imported at runtime. The stylesheet reads
+only the design system's `--cd-ui-*` roles and `--cd-shell-*` sizes. All texts are English by default
+and overridable through one messages table; numbers go through `Intl` in the UI language.
+
+## Install
+
+```sh
+npm i --save-exact @miragon/modeler-shell
+```
+
+The modeler brings what the shell styles against and draws into:
+
+- **diagram-js** 15.28 or later (directly or through its renderer);
+- **the design tokens**: `cd-tokens.generated.css` (and `cd-tokens.generated.json` where scripts
+  need values) of the design system, 1.12.0 or later (the release with the `shell` group). Copy
+  both unchanged from the skill's `assets/` or from
+  <https://corporate-identity.netlify.app/brand/cd-tokens.generated.css> and
+  <https://corporate-identity.netlify.app/brand/cd-tokens.generated.json>, mark them as generated,
+  and re-copy instead of editing. The shell ships no tokens and never forks a value;
+- **the fonts** Geist and Geist Mono, bundled locally, for example `@fontsource-variable/geist` and
+  `@fontsource-variable/geist-mono` (no CDN);
+- for `./vscode/extension`: **VS Code 1.90 or later**, whose extension host runs Node 20 (the global
+  `crypto` that `createNonce` uses; the types are tested against `@types/vscode` 1.96). Declare
+  `engines.vscode` accordingly and target `node20` in the extension-host bundle.
+
+Stylesheets, in this order. The tokens come first, unless the renderer's stylesheet already imports
+them (Event Storming's does), and are never loaded twice:
+
+```ts
+import "./theme/cd-tokens.generated.css"; // vendored, unchanged, first; left out when the renderer CSS brings it
+import "@fontsource-variable/geist/wght.css";
+import "@fontsource-variable/geist-mono/wght.css";
+import "diagram-js/assets/diagram-js.css"; // usually through the renderer's CSS
+import "@miragon/<notation>-renderer/…css";
+import "@miragon/modeler-shell/shell.css"; // last
+```
+
+The shell computes fit insets, breakpoints and layers from its own copy of the sizes (`SHELL`), while
+its stylesheet reads the vendored `--cd-shell-*` tokens. Pin the two together in a unit test (Vitest
+or `node:test`), not in the e2e suite, since the check is pure data:
+
+```ts
+// test/tokens.sync.test.ts
+import { SHELL, SHELL_TOKENS, shellSizesFromTokens } from "@miragon/modeler-shell/core";
+
+expect(SHELL).toEqual(shellSizesFromTokens(vendoredTokens.shell));
+expect(Object.keys(vendoredTokens.shell)).toEqual(expect.arrayContaining(Object.values(SHELL_TOKENS)));
+```
+
+| Entry                                        | For                                                         |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| `@miragon/modeler-shell`                     | `mountShell`, icons, and everything of `./core`             |
+| `@miragon/modeler-shell/core`                | DOM-free: fit math, keymap, zoom readout, appearance, sizes |
+| `@miragon/modeler-shell/diagram-js`          | `shellModule`, the viewport, `connectDiagramJs`             |
+| `@miragon/modeler-shell/vscode/extension`    | webview HTML with CSP and nonce, theme bridge               |
+| `@miragon/modeler-shell/vscode/webview`      | `mountVsCodeShell`, appearance handler, webview state       |
+| `@miragon/modeler-shell/testing`             | the Playwright-driven shell conformance kit                 |
+| `@miragon/modeler-shell/testing/vscode-stub` | a stand-in for VS Code around a webview test page           |
+| `@miragon/modeler-shell/shell.css`           | every style of the shell                                    |
+
+TypeScript: every entry resolves under `moduleResolution` `node16`, `bundler` and `node10`, and
+every optional input field accepts `undefined`, so a modeler compiling with
+`exactOptionalPropertyTypes` forwards optional values as they are.
+
+## Usage in a VS Code webview
+
+Extension host:
+
+```ts
+import * as vscode from "vscode";
+import {
+  connectThemeBridge,
+  currentAppearance,
+  renderWebviewHtml,
+} from "@miragon/modeler-shell/vscode/extension";
+
+const THEMES = ["light"] as const; // until the shared dark-mode release of the modelers
+
+// activate(): a hidden tab keeps document, view and selection
+vscode.window.registerCustomEditorProvider(viewType, provider, {
+  webviewOptions: { retainContextWhenHidden: true },
+});
+
+// resolveCustomTextEditor():
+const dist = vscode.Uri.joinPath(extensionUri, "dist");
+webview.options = { enableScripts: true, localResourceRoots: [dist] }; // script, CSS and font files
+const asset = (file: string) => webview.asWebviewUri(vscode.Uri.joinPath(dist, file)).toString();
+webview.html = renderWebviewHtml({
+  cspSource: webview.cspSource,
+  scriptUri: asset("webview.js"),
+  styleUris: [asset("webview.css")],
+  title: "Event Storming Board",
+  lang: "en",
+  appearance: currentAppearance(vscode, { themes: THEMES }), // on <html> before the first paint
+});
+connectThemeBridge(vscode, webviewPanel, { themes: THEMES }); // disposes itself with the panel
+```
+
+The bridge's disposable is only for ending it before the panel closes; never push it into
+`context.subscriptions`, which would keep one dead bridge per opened editor until the extension
+deactivates.
+
+Bundle the fonts as files next to the webview bundle, not as data URLs: with esbuild
+`loader: { ".woff2": "file", ".woff": "file" }` and `assetNames: "fonts/[name]-[hash]"` the browser
+fetches only the subsets a page's `unicode-range` needs (Geist Mono alone brings six; inlined they
+roughly double the webview CSS). The CSP of `renderWebviewHtml` allows fonts from `cspSource`, and
+`dist` is in `localResourceRoots`. A webview that bundles zod 4 runs `z.config({ jitless: true })` in
+a module it imports before any schema module: the CSP forbids eval, zod probes once for eval when it
+builds its first object schema, and the browser reports that caught `new Function` as a
+`securitypolicyviolation`; under `jitless` zod skips the probe.
+
+Webview:
+
+```ts
+import { INVALID_STATUS_DELAY_MS } from "@miragon/modeler-shell";
+import { connectDiagramJs, shellModule } from "@miragon/modeler-shell/diagram-js";
+import {
+  mountVsCodeShell,
+  persistView,
+  readShellState,
+  writeShellState,
+} from "@miragon/modeler-shell/vscode/webview";
+
+const vscode = acquireVsCodeApi();
+const stored = readShellState(vscode);
+
+// The diagram first: a modeler keyboard on document must run before the shell's key listener.
+// A renderer that builds its diagram lazily builds it now; width and height follow the shell's slot.
+// A renderer with its own Cmd/Ctrl+Z binding turns it off here, because VS Code's document history
+// owns undo (Event Storming: createCollaborativeModeler({ undoRedoKeys: false }), see API.md).
+const modeler = new Modeler({ width: "100%", height: "100%", additionalModules: [shellModule] });
+modeler.get("canvas");
+const shell = mountVsCodeShell(document.getElementById("app")!, {
+  themes: ["light"],
+  canvas: modeler.container,
+  menu: {
+    model: [/* Level; Type captions with keepEnabledWhenReadOnly, a view toggle */],
+    export: [/* Export as PNG, SVG */],
+    help: [/* Keyboard shortcuts… (the modeler's own dialog) */],
+  },
+  legend: {
+    render: renderLegend,
+    open: stored.legendOpen,
+    onToggle: (open) => writeShellState(vscode, { legendOpen: open }),
+  },
+  problems: { onActivate: () => vscode.postMessage({ type: "showProblems" }) },
+  emptyHint: { onInsertExample: () => vscode.postMessage({ type: "insertExample" }) },
+});
+const connection = connectDiagramJs(shell, modeler, {
+  // the tight bounds of the content, no padding: the shell's fit insets are the only margin
+  contentBounds: () => elementBounds(), // undefined while there is nothing to fit
+  isEmpty: () => elementCount() === 0, // cheap: no export, no validation
+});
+const { viewport } = connection;
+persistView(vscode, viewport); // writes the view once it rested, not on every frame
+
+async function importText(text: string, first: boolean): Promise<void> {
+  const keep = first ? undefined : viewport.getViewbox();
+  try {
+    await modeler.importDSL(text);
+    lockCanvas(false);
+    shell.setReadOnly(false);
+    shell.setStatus(null);
+    if (keep) viewport.restore(keep);
+    else if (first && stored.view) viewport.setState(stored.view);
+    viewport.afterImport(); // first content fits, an empty file shows 100 %, the hint follows by itself
+  } catch {
+    // locked at once, visible after 800ms without a valid import (no flicker while typing)
+    lockCanvas(true); // the modeler's own lock: context pad, move, resize, delete, paste, label editor
+    shell.setReadOnly(true, { delayMs: INVALID_STATUS_DELAY_MS });
+    shell.setStatus(
+      { severity: "danger", text: shell.messages.invalidFile("Event Storming board") },
+      { delayMs: INVALID_STATUS_DELAY_MS },
+    );
+  }
+}
+
+// Imports strictly one after another; `ready` resolves once the first one settled.
+let imports = Promise.resolve();
+let firstImportSettled = () => {};
+const ready = new Promise<void>((resolve) => (firstImportSettled = resolve));
+window.addEventListener("message", ({ data }) => {
+  if (data?.type === "init")
+    imports = imports.then(() => importText(data.text, true)).then(firstImportSettled);
+  if (data?.type === "update") imports = imports.then(() => importText(data.text, false));
+});
+vscode.postMessage({ type: "ready" });
+
+// For the e2e test page below; the bundle publishes nothing on window.
+export const webview = { shell, modeler, connection, ready };
+```
+
+`mountVsCodeShell` stops every key the webview handles on `document`, before VS Code's listener on
+`window` forwards it to the workbench, and keeps the webview in the mode the extension resolved: a
+modeler declaring `["light"]` stays light under any VS Code theme, high contrast passes, and VS
+Code's `workbench.reduceMotion` stops the chrome's animations. Undo and redo on the canvas go to VS
+Code (the shell keeps diagram-js's bindings off them), so a modeler's own keyboard binds no Cmd/Ctrl+Z
+in the webview either. Keys the canvas uses act only there: Cmd/Ctrl+A on the canvas selects every
+element (or is at least prevented), so VS Code's Select All never selects the chrome. The modeler's
+keyboard also ignores keys with `defaultPrevented` and keys from outside the canvas container, and
+puts no `tabindex` on it.
+
+`shell.setReadOnly(true)` locks the palette (all but Lasso and Hand) and the Model entries of the
+menu. View toggles stay usable: the shell's Legend checkbox and the legend's close button, and every
+entry with `keepEnabledWhenReadOnly` (guide §13.5 since design system 1.13.0). The canvas itself is the modeler's to lock: no context pad, move,
+resize, delete, paste or label editor. Content the modeler adds to `shell.root` (a "Keyboard
+shortcuts…" dialog) is the modeler's too: it removes it in its own teardown, for example on
+`diagram.destroy`, since `shell.destroy()` removes only what the shell added. The complete Event
+Storming example, including the export notification, is in [API.md][api]. Document sync, undo through
+the document and diagnostics stay in the modeler for now.
+
+## Usage in a web app
+
+The page's head writes the mode before the first paint. A light-only modeler keeps
+`<html lang="en" data-cd-theme="light">` static and lets the build put the metas and the contrast
+line in place of a marker in `index.html`:
+
+```ts
+// vite.config.ts
+import { webHeadMarkup } from "@miragon/modeler-shell/core";
+import tokens from "./src/theme/cd-tokens.generated.json" with { type: "json" };
+
+const themeColors = { light: tokens.fest["--cd-blau"], dark: tokens.dunkel["--cd-ui-grund"] };
+const modePlugin = {
+  name: "miragon-mode",
+  transformIndexHtml: (html: string) =>
+    html.replace("<!-- miragon-mode -->", webHeadMarkup({ themes: ["light"], themeColors })),
+};
+```
+
+```ts
+// src/main.ts
+import {
+  commandKeyLabel,
+  defaultMessages,
+  detectPlatform,
+  mountShell,
+  problemSummary,
+} from "@miragon/modeler-shell";
+import { connectDiagramJs, shellModule } from "@miragon/modeler-shell/diagram-js";
+
+// The diagram first: a modeler keyboard on document must run before the shell's key listener.
+const modeler = new Modeler({ width: "100%", height: "100%", additionalModules: [shellModule] });
+modeler.get("canvas");
+const platform = detectPlatform(navigator);
+const shell = mountShell(document.getElementById("app")!, {
+  host: "web",
+  canvas: modeler.container,
+  lang: "en",
+  themes: ["light"], // with "dark": also appearance: { themeColors }, and the menu gets Appearance
+  primary: { onSelect: share }, // "Share", top right; the label collapses before the palette moves
+  legal: { links: [{ label: "GitHub", href: "https://github.com/Miragon/…" }] },
+  file: {
+    newDiagram: { onSelect: newDiagram },
+    // ⌘O or Ctrl+O; also the start screen's "Open a file…" link
+    open: { onSelect: pickFile, shortcut: commandKeyLabel("O", platform, defaultMessages.keyNames) },
+    showExample: { onSelect: example },
+  },
+  menu: { model: [/* … */], export: [/* … */], help: [/* Keyboard shortcuts… */] },
+  problems: { onSelectItem: (item) => selectElement(item.elementId) },
+  legend: { render: renderLegend, open: storedLegendOpen(), onToggle: storeLegendOpen },
+  emptyState: {
+    title: "BPMN Modeler",
+    text: "Start a new diagram, or explore the example.",
+    komet: kometUrl, // the vendored, unchanged miragon-komet-blau.svg
+    onNewDiagram: newDiagram,
+    onShowExample: example,
+  },
+  dropZone: { accept: [".bpmn", "application/xml", "text/xml"], onDrop: ([file]) => openFile(file) },
+});
+const { viewport } = connectDiagramJs(shell, modeler, { contentBounds: () => elementBounds() });
+
+// Every new document opens like the first, and the start screen goes with it.
+async function openDocument(xml: string): Promise<void> {
+  viewport.newDocument();
+  const { warnings } = await modeler.importXML(xml);
+  viewport.afterImport();
+  shell.setEmptyState(false);
+  shell.setProblems(
+    problemSummary(warnings.map((warning) => ({ severity: "warning", message: warning.message }))),
+  );
+}
+
+// A fresh visit without a document in the link shows the start screen.
+if (!linkedDocument) shell.setEmptyState(true);
+shell.toast({ status: "success", text: "Link copied" }); // after a share
+```
+
+The `web` host renders the whole web column of guide §5.2: the primary action at the top right,
+the legal line at the bottom left with pill and legend above it, the File group first and, for a
+dark-capable modeler, the Appearance group in the menu, the problems list above the pill, toasts at
+the bottom centre (announced through two live regions), the start screen and a page-wide drop zone.
+It prevents the browser's page zoom for the chrome keys (outside text fields, modal dialogs and the
+start screen) and fits with the web insets. The web app's
+own menu, zoom, fit, toast, legal and empty-state markup goes away; what stays the modeler's is its
+content: the share link, file reading, examples, the Model and Export entries and the shortcuts
+dialog. See [API.md][api], "Web host (0.2)", and the complete Event Storming example there.
+
+## Usage in a foreign page
+
+`mountShell(container, { host: "embedded", themes: ["light"], canvas })` on an explicitly sized
+container: the root carries the tool's `lang` itself, keys act only while the focus is inside the
+modeler, and the page's `<html>` stays untouched. Until the `@miragon/modeler-api` contract gains
+its `appearance` surface (a later 1.x minor), an embedded modeler has no appearance channel, so the
+root carries its own `data-cd-theme` (the first of `themes`, light) and stays light inside a dark
+host page; it takes the page's `data-cd-kontrast="hoch"` over from the nearest mode carrier above
+it. The page's element styles (`button { text-transform: uppercase }`) do not reach the chrome.
+Toasts show at the bottom centre of the modeler, and the pill opens the problems list unless the
+modeler passes `problems.onActivate` (an embedding host with a list of its own).
+
+## The conformance kit
+
+Every modeler runs the kit in its own Playwright suite against its real webview or page. It checks
+the geometry of every island (±1px), ARIA and the keyboard models, that every chrome key acts exactly
+once and never reaches VS Code, that the canvas's own keys (Cmd/Ctrl+A) stay on the canvas, that
+nothing is ever half-dark (the painted canvas surround and the palette's colours included), that
+Enter on a creating palette entry adds one selected element, that an invalid file locks the canvas,
+and that `destroy()` leaves nothing behind. Five more cases cover the web column (`webChrome`,
+`emptyState`, `toasts`, `problemsList`, `dropZone`); in the IDE and embedded hosts they assert that
+none of it shows.
+
+For the `ide` host the suite serves a test page that puts a stand-in for VS Code around the
+modeler's webview code: VS Code's default webview styles, `<html>` as `renderWebviewHtml` writes it,
+the host page's theme classes, `acquireVsCodeApi()` and the real theme bridge. Serve
+`e2e/webview/` as the root of a Vite server, so the page is `/webview-test.html`:
+
+```ts
+// e2e/webview/webview-test.ts, the entry of e2e/webview/webview-test.html
+import { installVsCodeWebviewStub, stubOptionsFromSearch } from "@miragon/modeler-shell/testing/vscode-stub";
+
+// before the webview runs, which calls acquireVsCodeApi() and mounts the shell
+installVsCodeWebviewStub({ ...stubOptionsFromSearch(location.search), themes: ["light"] });
+const { webview } = await import("../../src/webview/main"); // exports { shell, modeler, connection, ready }
+
+// for the harness only: the shipped bundle publishes nothing on window
+window.shell = webview.shell;
+window.modeler = webview.modeler;
+window.connection = webview.connection;
+void webview.ready.then(() => (window.webviewReady = true)); // the first import settled
+
+// there is no extension host: post the document the way the extension would
+window.postMessage({ type: "init", text: EXAMPLE_BOARD }, "*");
+```
+
+`ready`, `webviewReady` and the window globals belong to the modeler's test page (declared in a
+`.d.ts` of the suite), not to the shell: the webview resolves `ready` once its first `init` import
+settled.
+
+```ts
+// e2e/shell-conformance.spec.ts
+import { test } from "@playwright/test";
+import { registerShellConformance, vsCodeStubSearch } from "@miragon/modeler-shell/testing";
+
+test.describe("shell conformance", () => {
+  test.describe.configure({ timeout: 60_000 }); // geometry measures three sizes
+  registerShellConformance(
+    {
+      host: "ide",
+      themes: ["light"],
+      absent: ["inspector"], // islands this modeler does not have: never visible, never skipped
+      async open(page, { size, requested }) {
+        await page.setViewportSize(size);
+        await page.goto(`/webview-test.html?${vsCodeStubSearch(requested)}`);
+        await page.waitForFunction(() => window.webviewReady === true); // set by the test page
+      },
+      async destroy(page) {
+        // the webview's own teardown path: connection, diagram (with the modeler's dialogs), shell
+        await page.evaluate(() => {
+          window.connection.destroy();
+          window.modeler.destroy();
+          window.shell.destroy();
+        });
+      },
+      show: {
+        async legend(page) {
+          await page.evaluate(() => window.shell.legend?.setOpen(true));
+        },
+        async problems(page) {
+          await page.evaluate(() => window.postMessage({ type: "problems", count: 2, errors: 1 }, "*"));
+        },
+        async status(page) {
+          await page.evaluate(() =>
+            window.shell.setStatus({ severity: "danger", text: window.shell.messages.invalidFile("board") }),
+          );
+        },
+        async invalid(page) {
+          // the way the host makes the file invalid: a document update the parser rejects
+          await page.evaluate((text) => window.postMessage({ type: "update", text }, "*"), INVALID_BOARD);
+        },
+      },
+    },
+    test,
+    {
+      onSkip(caseName, skips) {
+        // with `absent` listing what the modeler lacks, every remaining skip is a gap of this suite
+        throw new Error(`${caseName}: ${skips.map(({ hook, reason }) => `${hook}: ${reason}`).join("; ")}`);
+      },
+    },
+  );
+});
+```
+
+A web app's harness opens its page and adds the web column's hooks and the files to drop. The kit
+emulates the system's colour scheme and contrast (`page.emulateMedia`) before every `open`, so the
+page loads without a stored mode choice:
+
+```ts
+// e2e/shell-conformance.spec.ts of a web app
+registerShellConformance(
+  {
+    host: "web",
+    themes: ["light"],
+    absent: ["inspector", "invalid"],
+    async open(page, { size }) {
+      await page.setViewportSize(size);
+      await page.goto("/?example");
+      await page.waitForFunction(() => window.appReady === true);
+    },
+    async destroy(page) {
+      await page.evaluate(() => window.app.destroy());
+    },
+    show: {
+      async legend(page) {
+        /* … */
+      },
+      async problems(page) {
+        /* setProblems with items, so the list has rows */
+      },
+      async status(page) {
+        /* … */
+      },
+      async emptyState(page) {
+        /* the start screen of a fresh visit */
+      },
+      async toast(page, toast) {
+        await page.evaluate(
+          ({ status, text, actionLabel }) =>
+            window.app.shell.toast({
+              status,
+              text,
+              ...(actionLabel ? { action: { label: actionLabel, onSelect() {} } } : {}),
+            }),
+          toast,
+        );
+      },
+    },
+    drop: {
+      accepted: { name: "board.json", type: "application/json", text: EXAMPLE_JSON },
+      rejected: { name: "notes.md", type: "", text: "# Notes" },
+    },
+  },
+  test,
+  { onSkip: failOnSkips },
+);
+```
+
+The harness opens the modeler with the appearance the kit requests, the way its host would; for
+the `embedded` host the kit puts the foreign page itself in that mode. A skip names the harness
+field it misses (`{ hook: "legend", reason }`; `hook: "destroy"` without a `destroy`; `hook: "open"`
+when the opened document lacks what a case needs, such as a shape for `readOnly`); without `onSkip`
+the kit warns on the console. What each case asserts, and what the kit installs in the page, is
+listed in [API.md][api].
+
+`registerShellConformance` declares every test inside the kit, so a runner reports them at the kit's
+source (the package ships `src/` without its tests, so the location resolves). For test locations in
+the suite's own spec file, register the cases there:
+
+```ts
+import { shellConformanceCases } from "@miragon/modeler-shell/testing";
+
+for (const conformanceCase of shellConformanceCases()) {
+  test(`shell conformance: ${conformanceCase.name}`, async ({ page }) => {
+    const outcome = await conformanceCase.run(page, harness);
+    if (outcome?.skipped) failOnSkips(conformanceCase.name, outcome.skipped);
+  });
+}
+```
+
+The test page runs the webview from source without a CSP. Add one smoke test of the production bundle
+behind the HTML and CSP of `renderWebviewHtml` that fails on any `securitypolicyviolation` (the recipe
+is in [API.md][api], `./vscode/extension`).
+
+## Development
+
+Run from the repository root (`-w packages/shell` for this package only):
+
+```sh
+npm run build -w packages/shell       # tsup: ESM + CJS + d.ts, dist/shell.css
+npm run typecheck -w packages/shell   # src, core without the DOM library, demo
+npm test -w packages/shell            # Vitest: node (core, boundaries) and happy-dom projects
+npx playwright install chromium       # once
+npm run test:e2e -w packages/shell    # Playwright against demo/
+npm run demo -w packages/shell        # the demo page on http://localhost:5181
+```
+
+The demo page (`demo/`) is a small diagram-js modeler around the shell. Its query parameters choose
+the host (`host=ide|web|embedded`), the modes the modeler declares (`themes=light,dark`), what the
+host requests (`theme`, `kontrast=hoch`; embedded: the foreign page's own mode), the `ide` host's
+`colorTheme` setting and `reduceMotion`, and the state to start in (`legend=open`, `inspector`,
+`problems=2:1`, `status=danger`, `invalid`, `empty`, which opens at 100 %). In the `ide` host it runs
+inside the stub of `./testing/vscode-stub`, and keeps view and legend state through
+`acquireVsCodeApi()`.
+
+The web demo (`/web.html`) is the same modeler as a Miragon web app passes it to `mountShell`: the
+whole web column, the head markup of `webHeadMarkup` through the Vite config, and `window.__webDemo`
+for the harness. Its query parameters: `themes=light,dark`, `empty` (the start screen of a fresh
+visit), `legend` (`legend=open`), `inspector`, `problems` (the pill with its list) and `invalid`.
+
+The e2e suite runs the conformance kit for the `ide`, `web` and `embedded` hosts with a light-only
+and a dark-capable modeler, switches VS Code themes and the `colorTheme` setting at runtime, checks
+VS Code's reduce motion, the chrome's typography against VS Code's default styles and a hostile
+foreign page, the canvas slot's paint and focus ring, the web chrome's colours, radii and states
+(primary action, legal line, toasts, drop zone, empty state, high contrast and forced colours) and
+the web demo's own handlers, and proves with saboteurs that every case of the kit fails when its
+rule is broken.
+
+| Directory                               | Module                                                                                     |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `src/core`                              | DOM-free: fit math, keymap, zoom readout, appearance, sizes, texts                         |
+| `src/dom`                               | `mountShell`: menu, zoom panel, tooltip, pill, status, slots, keys                         |
+| `src/dom/web`, `src/core/web-chrome`    | web column: primary action, legal line, File and Appearance groups, empty state, drop zone |
+| `src/dom/feedback`, `src/core/feedback` | toasts, problems popover, the web app's mode                                               |
+| `src/diagram-js`                        | `shellModule`, viewport, `connectDiagramJs`, palette skin                                  |
+| `src/vscode`                            | extension side (HTML, theme bridge) and webview side                                       |
+| `src/testing`                           | the Playwright-driven conformance kit and the VS Code stub                                 |
+| `src/*.ts`, `src/shell.css`             | the entry points                                                                           |
+| `test/`                                 | package boundaries, token drift, the unit tests' helpers                                   |
+| `demo/`, `e2e/`                         | the demo modeler and the e2e suite                                                         |
+| `fixtures/tokens`                       | the token files, vendored unchanged for the tests and the demo                             |
+
+A module imports another one only through its `index.ts`; `src/core` imports nothing outside
+itself and compiles without the DOM library. `test/package-boundaries.test.ts` enforces this, the
+zero runtime dependencies, the exact devDependency pins, the token-only stylesheets and the published
+files (`dist`, `src` without its tests, `API.md` and the notices).
+
+## License
+
+MIT. The inlined Lucide icons are ISC (© Lucide Icons and Contributors), and `check`, `circle-x`,
+`maximize`, `minus`, `plus`, `triangle-alert` and `x` derive from Feather, MIT (© Cole Bemis), as
+Lucide's LICENSE lists them; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). `dist` keeps that
+notice as a legal comment in the chunk with the icons, but a bundler's `legalComments` setting may
+drop it: a VSIX or a web bundle that contains the shell carries the Lucide and Feather notices of
+THIRD_PARTY_NOTICES.md itself. Vite 8 (Rolldown with the Oxc minifier) drops legal comments by
+default; `build.rolldownOptions.output.comments.legal: true` keeps the notice in the bundle.
+
+[guide]: https://github.com/Miragon/corporate-identity/blob/main/plugins/miragon-brand/skills/modeler-tool-design/assets/modeler-design-system.md
+[notes]: https://github.com/Miragon/modeler-api/blob/main/docs/shell/implementation-notes.md
+[api]: https://github.com/Miragon/modeler-api/blob/main/packages/shell/API.md

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+`@miragon/modeler-shell` inlines icon geometry from [Lucide](https://lucide.dev)
+(`lucide-static` 1.59.0) in `src/dom/icons.ts` and its builds. That file opens with a legal comment
+(`/*! … @license … */`) naming both notices below, which esbuild and most minifiers keep in the
+output chunk that carries the geometry. A bundle built with legal comments dropped or moved to a
+separate file must ship these notices itself.
+
+## Lucide
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+Lucide's LICENSE (`lucide-static` 1.59.0) lists the icons derived from the
+Feather project, by their Feather names. Of those the shell inlines `check`,
+`circle-x` (Feather's `x-circle`), `maximize`, `minus`, `plus`,
+`triangle-alert` (Feather's `alert-triangle`) and `x`:
+
+The MIT License (MIT)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.