@dineug/erd-editor 3.10.0 → 4.1.0

package/README.md

@@ -2,32 +2,34 @@
 
 > Entity-Relationship Diagram Editor as a custom element
 
-![erd-editor](https://github.com/dineug/erd-editor/blob/main/img/erd-editor-vscode.png?raw=true)
+![ERD Editor](https://github.com/dineug/erd-editor/blob/main/img/erd-editor-vscode.png?raw=true)
 
-`<erd-editor>` is a full database-schema editor in a single custom element. It has no
-framework dependency and renders into a closed shadow root, so it drops into any page —
-React, Vue, Svelte, or plain HTML — without leaking styles either way.
-
-This is the same editor that powers [erd-editor.io](https://erd-editor.io), the
-[Google Drive app](https://workspace.google.com/marketplace/app/erd_editor/428467403360), the
-[VS Code extension](https://marketplace.visualstudio.com/items?itemName=dineug.vuerd-vscode),
-the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/23594-erd-editor) and the
+`<erd-editor>` is a database-schema editor in one custom element. It has no framework dependency
+and renders into a closed shadow root, so it drops into React, Vue, Svelte or plain HTML without
+leaking styles either way. It is the same editor as [erd-editor.io](https://erd-editor.io), the
+[VS Code extension](https://marketplace.visualstudio.com/items?itemName=dineug.vuerd-vscode), the
+[JetBrains plugin](https://plugins.jetbrains.com/plugin/23594-erd-editor) and the
 [Obsidian plugin](https://community.obsidian.md/plugins/erd-editor).
 
 ## Features
 
-- Visual schema design — tables, columns, memos, and four relationship cardinalities
-  (zero-one, zero-N, one-only, one-N)
-- Import — a `.sql` dump, a GraphQL SDL schema from any tool that emits one, a `.dbml` file, or
-  an `.aml` file
-- SQL DDL export — Databricks, MariaDB, MSSQL, MySQL, Oracle, PostgreSQL, Snowflake and SQLite
-- Code generation — TypeScript, GraphQL, C#, Java, JPA, Kotlin, Scala, Go,
-  SQLAlchemy, TypeORM, Sequelize, Drizzle, DBML, AML
-- Export — `.erd.json`, `.sql`, `.png`
-- Force-directed visualization of table relationships
-- Quick search over commands, and over tables, columns, comments and memos after `#`, `@` or `:`,
-  find and replace, undo / redo, remappable keyboard shortcuts, and a built-in theme builder
-- Collaboration hooks — the editor emits and applies actions; you supply the transport
+- **Design** — tables, columns, memos and table groups, four relationship cardinalities, ON DELETE
+  and ON UPDATE, alternate keys, Auto Layout
+- **Import** — SQL DDL, GraphQL SDL, DBML and AML from the menu or [`setSchema*`](#importing-a-schema),
+  replacing the diagram or adding to it
+- **Export** — DDL for eight databases, also from `getSchemaSQL()`, code in 22 languages and ORMs,
+  PNG and SVG
+- **Navigate** — command palette (`Ctrl`/`Cmd`+`K`), an Explorer tree with find and replace, Graph
+  and Flow views
+- **History** — undo and redo, time travel through the session, a diff viewer (`setDiffValue()`)
+- **25 languages** and a System, Light or Dark theme, their pickers opt-in with an attribute
+- **Collaboration** — [`getSharedStore()`](#collaboration) relays edits over your own transport,
+  and the [headless entries](#headless-replica) run the same document with no DOM
+
+**Databases:** Databricks, MariaDB, MSSQL, MySQL, Oracle, PostgreSQL, Snowflake, SQLite
+
+**Code:** TypeScript, GraphQL, C#, Java, JPA, Kotlin, Scala, Go, SQLAlchemy, TypeORM, Sequelize,
+Drizzle, DBML, AML, Mermaid, PHP, Doctrine, Rust, SeaORM, Swift, Zod, JSON Schema
 
 ## Install
 
@@ -35,13 +37,9 @@ the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/23594-erd-editor) and
 npm install @dineug/erd-editor
 ```
 
-The package ships ES modules with its dependencies left as bare imports, so any bundler
-(Vite, webpack, Rspack, esbuild, …) resolves, dedupes and tree-shakes them like the rest of
-your app. Four features run in shared workers — schema garbage collection, the PNG export, the
-automatic table placement and the syntax highlighting — constructed as
-`new SharedWorker(new URL('./workers/…', import.meta.url))`, which those bundlers emit as worker
-files beside your chunks; a strict CSP needs `worker-src 'self'`. Without a bundler, use the UMD
-file described under [Script tag](#script-tag) instead.
+The PNG and SVG export, the Flow and tree layouts and the syntax highlighting run in shared
+workers, which Vite, webpack and Rspack emit beside your chunks and esbuild does not. A strict CSP
+needs `worker-src 'self'`. Without a bundler, use the [script tag](#script-tag) build.
 
 ## Usage
 
@@ -49,26 +47,20 @@ file described under [Script tag](#script-tag) instead.
 import '@dineug/erd-editor';
 
 const editor = document.createElement('erd-editor');
-// the editor fills its container, and a custom element is inline by default
+// a custom element is inline, and the editor fills its box
 Object.assign(editor.style, { display: 'block', width: '100%', height: '100vh' });
 document.body.appendChild(editor);
 
-// load a document without adding an undo entry, then keep it in sync
 editor.setInitialValue(localStorage.getItem('my-diagram') ?? '');
 editor.addEventListener('change', () => {
   localStorage.setItem('my-diagram', editor.value);
 });
 ```
 
-`setInitialValue('')` starts a new document, as an element given no value shows: it saves neither
-the scroll nor the zoom (Save Scroll Information and Save Zoom Information off), so looking around
-leaves `value` as it was. A document loaded from text keeps the switches it names, and one that
-names none saves both.
-
 ### Server-side rendering
 
-Importing the package registers the custom element at module scope, so it needs a DOM and
-throws in Node. In Next.js, Nuxt, SvelteKit or Astro, reach it from a client-only path:
+Importing the package registers the element, which needs a DOM, so in Next.js, Nuxt, SvelteKit or
+Astro import it on the client:
 
 ```js
 useEffect(() => {
@@ -78,215 +70,205 @@ useEffect(() => {
 
 ### Vite
 
-In development Vite pre-bundles dependencies into its cache directory, and the worker files
-would then be looked up there rather than beside the package. Exclude the editor packages from
-that step; a production build needs nothing.
+In development, keep the editor out of Vite's pre-bundling and include the ELK bundle its layout
+worker imports, or the Flow and tree layouts fail. A production build needs nothing.
 
 ```js
 // vite.config.js
 export default {
   optimizeDeps: {
     exclude: ['@dineug/erd-editor'],
+    include: ['@dineug/erd-editor > elkjs/lib/elk.bundled.js'],
   },
 };
 ```
 
 ### Script tag
 
-`dist/erd-editor.umd.js` is a self-contained build for a plain `<script>` tag: every
-dependency and all four workers are inside it, and it registers `<erd-editor>` and exposes the
-two file callbacks as `window.ErdEditor`. It is what `unpkg` and `jsdelivr` serve.
+`dist/erd-editor.umd.js` bundles every dependency and worker, registers `<erd-editor>` and puts
+`setExportFileCallback`, `setImportFileCallback` and `createKeyBindingMap` on `window.ErdEditor`.
+Its workers are `data:` URLs, so a strict CSP needs `worker-src data:`. Pin a version beyond a demo.
 
 ```html
 <erd-editor style="display: block; width: 100%; height: 100vh"></erd-editor>
 <script src="https://cdn.jsdelivr.net/npm/@dineug/erd-editor/dist/erd-editor.umd.js"></script>
 ```
 
-The workers travel inside the file as `data:` URLs, so a strict CSP needs `worker-src data:`
-for this build. Pin a version in the URL for anything beyond a demo.
-
-### HTML
-
-```html
-<erd-editor system-dark-mode enable-theme-builder></erd-editor>
-<script type="module">
-  import '@dineug/erd-editor';
-
-  const editor = document.querySelector('erd-editor');
-</script>
-```
-
-```css
-erd-editor {
-  display: block;
-  width: 100%;
-  height: 100vh;
-}
-```
-
 ## API
 
+The element's type is exported as `ErdEditorElement`. The
+[Element API docs](https://docs.erd-editor.io/docs/api/erd-editor-element) cover each member in
+full.
+
 ### Attributes
 
 | Attribute | Property | Description |
 | --- | --- | --- |
-| `readonly` | `readonly` | Blocks editing and suppresses the `change` event. Assigning `value`, `setSchemaSQL()`, `setSchemaGraphQL()`, `setSchemaDBML()`, `setSchemaAML()` and `clear()` are ignored while it is set — load with `setInitialValue()` instead. Viewport actions and the SQL/code output settings still apply. |
-| `system-dark-mode` | `systemDarkMode` | Follows the OS color scheme |
-| `enable-theme-builder` | `enableThemeBuilder` | Shows the built-in theme builder |
+| `readonly` | `readonly` | Blocks editing and `change`; only `setInitialValue()` still loads. |
+| `system-dark-mode` | `systemDarkMode` | Sets the appearance to `system`. |
+| `enable-theme-builder` | `enableThemeBuilder` | Shows the theme builder and the palette's Theme. |
+| `enable-locale-picker` | `enableLocalePicker` | Shows the language button and the palette's Display Language, System by default. |
+| `enable-welcome-screen` | `enableWelcomeScreen` | Shows the welcome screen over an empty, editable diagram. |
+
+An attribute is on when present with no value or `"true"`.
 
 ### Properties
 
 | Property | Description |
 | --- | --- |
-| `value: string` | The document as JSON — an `.erd.json` document ([schema](https://github.com/dineug/erd-editor/blob/main/json-schema/schema.json)). Assigning it loads the document as an edit, so it lands in the undo history; use `setInitialValue` to load without one. Assigning an empty string loads a new document, as `setInitialValue('')` does. |
+| `value: string` | The document as a file saves it ([schema](https://github.com/dineug/erd-editor/blob/main/json-schema/schema.json)). Assigning one, or `''` for a new one, is an undoable load. |
+| `runtimeValue: string` | Read only. The document as this editor holds it, to seed a collaborator. |
 
 ### Methods
 
 | Method | Description |
 | --- | --- |
-| `setInitialValue(value: string)` | Load the initial document. Does not create a history entry, and clears the undo history, so nothing done before the load can be undone or redone onto it. |
-| `getSchemaSQL(vendor?)` | Export DDL. `vendor` is one of `Databricks`, `MariaDB`, `MSSQL`, `MySQL`, `Oracle`, `PostgreSQL`, `Snowflake`, `SQLite`; omit it to use the document's own setting. |
-| `setSchemaSQL(value: string)` | Parse a DDL string and **replace** the current document with it. Lands in the undo history; an empty string is ignored. |
-| `setSchemaGraphQL(value: string)` | Parse a GraphQL SDL string and **replace** the current document with it. Object types become tables, scalars map to the document's own dialect, and relationships are read from the fields that point at another type. Lands in the undo history; an empty string is ignored. |
-| `setSchemaDBML(value: string)` | Parse a DBML string and **replace** the current document with it. Tables, columns, indexes and every `Ref` spelling are read; a `Project`, `TableGroup` or sticky `Note` is skipped, and text it cannot read loads an empty document rather than being refused. Lands in the undo history; an empty string is ignored. |
-| `setSchemaAML(value: string)` | Parse an [AML](https://azimutt.app) string and **replace** the current document with it. Entities, attributes, indexes and every relation arrow are read, in the v2 and the legacy v1 spelling; a check, a struct type and a view are skipped, and text it cannot read loads an empty document rather than being refused. Lands in the undo history; an empty string is ignored. |
-| `setDiffValue(value: string)` | Open the diff viewer against another document. |
-| `setPresetTheme(options)` | Set `appearance`, `grayColor` and `accentColor`. |
-| `setTheme(theme)` | Override individual theme tokens. |
-| `setKeyBindingMap(map)` | Remap shortcuts, `search` and `findReplace` among them. `edit`, `stop`, `undo`, `redo`, `zoomIn`, `zoomOut` and `zoomReset` are reserved. |
-| `getSharedStore(config?)` | Returns `{ subscribe, dispatch, dispatchSync, connection, disconnect, destroy }`. `subscribe` gives you this editor's actions to relay; `dispatch` applies a peer's. You supply the transport. `config` is `{ getNickname?, mouseTracker?, focusTracker? }`; both trackers default to `true` and broadcast this editor's cursor and table focus to peers. |
-| `focus()` / `blur()` | Move focus in and out of the editor. |
-| `clear()` | Empty the document. Its settings stay, the save switches included, so a cleared file keeps saving what it saved. |
-| `destroy()` | Tear the editor down and release its listeners, subscriptions and shared stores. |
+| `setInitialValue(value)` | Load a document with no undo entry; `''` starts a new one. |
+| `getSchemaSQL(vendor?, options?)` | DDL for one of the eight databases, by default the document's. `options`: `statements` (`create`, `ifNotExists`, `recreate`), `header` (`none`, `use`, `createAndUse`). |
+| `setSchemaSQL(value, options?)`, `setSchemaGraphQL`, `setSchemaDBML`, `setSchemaAML` | Replace the document with parsed DDL, GraphQL SDL, DBML or AML, or append it ([Importing a schema](#importing-a-schema)). |
+| `setSchemaJSON(value, options?)` | Load an `.erd.json` document as `value` does, or append it. |
+| `setDiffValue(value)` | Diff another document over the ERD tab. |
+| `setPresetTheme(options)` | Set `appearance` (`light`, `dark`, `system`), `grayColor` and `accentColor`. |
+| `setSystemAppearance(appearance)` | Name the light or dark `system` shows; `null` follows the OS. |
+| `setLocale(locale)` | Set the display language, `'system'` or a [code](#display-language). |
+| `setSystemLocale(tag)` | Name the BCP 47 language `system` shows; `null` reads `navigator.languages`. |
+| `setTheme(theme)` | Override theme tokens; each call replaces the earlier overrides. |
+| `setKeyBindingMap(map)` | Remap [shortcuts](#key-bindings) but `edit`, `stop`, `undo`, `redo` and the zoom keys. |
+| `getSharedStore(config?)` | A [shared store](#collaboration) for collaboration. |
+| `focus()` / `blur()` | Move focus in or out. |
+| `clear()` | Empty the document and keep its settings, in one undo step. |
+| `destroy()` | Release the editor's listeners, subscriptions and shared stores. |
 
 ### Events
 
 | Event | Description |
 | --- | --- |
-| `change` | The document changed. Debounced, and never fired while `readonly`. Read `editor.value`. A scroll or a zoom fires it too. A scroll leaves `value` as it was with Save Scroll Information off; a zoom moves the scroll position too, so it leaves `value` as it was only with Save Zoom Information and Save Scroll Information both off. `value` differs from a file another release or machine wrote from the load on, so a host that writes files tells an edit from such a change by a [headless replica](#headless-replica)'s `changed`, not by comparing bytes with the file. |
-| `changePresetTheme` | The theme was changed from inside the editor. `event.detail` carries the new options. |
+| `change` | The document changed; read `editor.value`. |
+| `changePresetTheme` | The theme changed in the editor; `event.detail` holds the options. |
+| `changeLocale` | A language was picked in the editor; `event.detail.locale` holds it. |
 
-## Key bindings
+### Loading and saving
 
-`createKeyBindingMap()` returns the shortcuts an editor listens for until `setKeyBindingMap`
-changes them, as a new map on every call. Each is a [tinykeys](https://github.com/jamiebuilds/tinykeys)
-chord that names its key by `KeyboardEvent.code`, where `$mod` is Cmd on macOS and Ctrl elsewhere.
+- Save `value`. `runtimeValue` also keeps removed entities and only seeds a
+  [collaborator](#collaboration).
+- `change` fires 200 ms after the last change, never under `readonly`, and never for scroll, zoom,
+  the open tab or the code settings while the document locks them, which a new document does.
+- A file written by hand or by another release can differ from `value` once loaded, so detect edits
+  with a [replica](#headless-replica)'s `changed`, not by comparing bytes.
+
+### Importing a schema
+
+- The four text `setSchema*` methods take `{ placement?: 'auto' | 'grid', mode?: 'replace' | 'append' }`,
+  and `setSchemaJSON` only `mode`. Each lands in one undo step and ignores `''`.
+- `'grid'`, the default, lands at once in rows. `'auto'` lays the tables out as the Import menu does
+  and returns a `Promise` that resolves when they land; a later load supersedes it.
+- `mode: 'append'` adds the tables below the diagram, as Import and Add does.
+
+### Theme and language
+
+The element starts dark and English and stores neither choice: `setPresetTheme` and `setLocale`
+set them, and your host keeps what `changePresetTheme` and `changeLocale` report.
+
+## Collaboration
+
+A joiner starts from the first editor's `runtimeValue`, then each relays its actions:
 
 ```js
-import { createKeyBindingMap } from '@dineug/erd-editor';
+joiner.setInitialValue(editor.runtimeValue);
 
-const shortcuts = Object.values(createKeyBindingMap())
-  .flat()
-  .map(({ shortcut }) => shortcut); // '$mod+KeyK', 'Alt+Enter', ...
+const local = editor.getSharedStore();
+const remote = joiner.getSharedStore();
+local.subscribe(actions => remote.dispatch(actions));
+remote.subscribe(actions => local.dispatch(actions));
 ```
 
-The editor listens on its own element, so a host that takes keys before the page does, with
-global hotkeys or a capture-phase `keydown` listener, has to let these through while the editor
-is focused. The `KeyBindingMap`, `KeyBindingName` and `ShortcutOption` types come with it.
+An editor never forwards what it received, so with three or more, send each one's batches to every
+other. Call `flushStreamBuffers()` before destroying a store, or the last drags and resizes never
+reach the peers. `getSharedStore({ getNickname, mouseTracker, focusTracker })` also shares cursors
+and focus.
 
-The page's own find is among them: while the editor is focused, on any of its tabs, `$mod+KeyF`
-opens its Find and Replace, bringing the ERD tab up, and is prevented, so the browser opens no find
-bar; while the diff viewer, time travel or the automatic placement preview covers the ERD tab, the
-press goes on to the page. `setKeyBindingMap({ findReplace: [] })` leaves it to the page on every
-tab, and the toolbar button, the quick search and the context menu still open Find and Replace.
+## Key bindings
 
-## Syntax highlighting
+`createKeyBindingMap()` returns the default shortcuts, and `setKeyBindingMap` replaces each list it
+names. A chord is modifiers (`Shift`, `Alt`, `Control`, `Meta`, or `$mod` for Cmd on macOS and Ctrl
+elsewhere) joined by `+` with a `KeyboardEvent.code` or `key`; a space separates the chords of a
+sequence, such as `KeyT KeyG`. Several defaults, search and find and replace among them, stop the
+keydown, so to leave `$mod+KeyF` to the page, call `setKeyBindingMap({ findReplace: [] })`.
 
-The SQL and code-generation panels are highlighted by [Shiki](https://shiki.style), in a shared
-worker of its own. There is nothing to install or register: the worker is built the first time a
-code panel renders, so a page that opens none never fetches the grammars.
+## Display language
 
-| | |
-| --- | --- |
-| Languages | SQL, TypeScript, GraphQL, C#, Java, Kotlin, Scala, Go, Python |
-| Themes | `github-dark`, `github-light`, picked from the editor's light / dark appearance |
+`en`, `ar-SA`, `de-DE`, `es-ES`, `eu-ES`, `fa-IR`, `fr-FR`, `he-IL`, `id-ID`, `it-IT`, `ja-JP`,
+`ko-KR`, `nl-NL`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sl-SI`, `sv-SE`, `tr-TR`,
+`uk-UA`, `zh-CN` and `zh-TW`. Arabic, Hebrew and Persian lay the editor out right to left. The
+`LocaleCode` and `LocaleOption` types are exported.
 
-Those are exactly the languages the panels emit — the JPA generator emits Java, the SQLAlchemy
-generator emits Python, the TypeORM, Sequelize and Drizzle generators emit TypeScript, and the
-DBML and AML generators are highlighted as SQL, the closest grammar shiki ships.
+## Workers
 
-Where `SharedWorker` is missing — Chrome on Android, Safari before 16.4 — the underlying error is
-logged and the panels render as plain text; nothing else is affected. The regex engine is plain
-JavaScript, so no host CSP needs `wasm-unsafe-eval`.
+[Shiki](https://shiki.style) highlights the code panels with a JavaScript regex engine, so a CSP
+needs no `wasm-unsafe-eval`. Without `SharedWorker`, as in Chrome on Android before Chrome 148, the
+code panels show plain text, the Flow view and the Flow and tree layouts place nothing, an `'auto'`
+import lands in rows, and PNG and SVG exports draw on the main thread.
 
 ## File dialogs
 
-Import and export go through injectable callbacks, so a host without a browser file dialog —
-an IDE webview, for example — can supply its own. The two are not symmetric: export hands you
-the finished file, while import only asks for one, and you push the content back in yourself.
+Import and export go through page-wide callbacks, so a host without a browser file dialog, such as
+an IDE webview, supplies its own:
 
 ```js
 import { setExportFileCallback, setImportFileCallback } from '@dineug/erd-editor';
 
 setExportFileCallback((blob, { fileName }) => host.writeFile(fileName, blob));
 
-setImportFileCallback(async ({ type, op, accept }) => {
+setImportFileCallback(async ({ type, op, accept, mode }) => {
   const text = await host.pickFile(accept);
-
-  if (op === 'diff') {
-    editor.setDiffValue(text);
-  } else if (type === 'json') {
-    editor.value = text;
-  } else if (type === 'sql') {
-    editor.setSchemaSQL(text);
-  } else if (type === 'graphql') {
-    editor.setSchemaGraphQL(text);
-  } else if (type === 'dbml') {
-    editor.setSchemaDBML(text);
-  } else if (type === 'aml') {
-    editor.setSchemaAML(text);
-  }
+  if (op === 'diff') return editor.setDiffValue(text);
+  if (type === 'json') return editor.setSchemaJSON(text, { mode });
+  const format = { sql: 'SQL', graphql: 'GraphQL', dbml: 'DBML', aml: 'AML' }[type];
+  if (format) editor[`setSchema${format}`](text, { placement: 'auto', mode });
 });
 ```
 
-Dispatch on every `type` you handle and ignore the rest. Assigning `value` clears the
-document before it parses, so routing a payload there that is not an `.erd.json` document —
-through a catch-all `else`, or because a `type` added later fell through — empties the
-diagram instead of importing anything. `accept` carries the extensions for that type
-(`.json`, `.sql`, or `.graphql,.gql,.graphqls`), ready to hand to a host file dialog.
-
-Left unset, the editor uses the browser's own download and file-picker behavior.
+Skip a `type` you do not handle: a replacing `setSchemaJSON()` empties the document on any other
+payload. Unset or `null`, the browser's download and file picker work.
 
 ## Headless replica
 
-A second entry point runs the document store with no DOM, for hosts that need to apply an
-action stream and serialize the result off the main thread:
+`engine.js` applies the same actions with no DOM, so a worker can keep and serialize the document:
 
 ```js
 import { createReplicationStore } from '@dineug/erd-editor/engine.js';
 
-// `toWidth` measures text for layout — a worker has no DOM, so you supply it
-const store = createReplicationStore({ toWidth });
-
+const store = createReplicationStore({ toWidth }); // a worker has no DOM to measure text
 store.setInitialValue(savedJson);
 store.on({ change: ({ value, changed }) => changed && persist(value) });
-store.dispatch(actions); // actions relayed from a live editor's shared store
+store.dispatch(actions);
 ```
 
-`change` comes 200 ms after the last action that can change the document. `changed` is false
-when those actions left `value` as it was, such as a scroll with Save Scroll Information off, or a
-zoom with Save Zoom Information and Save Scroll Information both off: a zoom moves the scroll
-position too, so with only the scroll saved it changes `value`. It compares with the value the
-store last reported, or loaded, never with your file: a file another release or machine wrote
-serializes differently from the start.
+`changed` is false when `value` matches what the store last reported or loaded.
 
-## Development
+`peer.js` runs a collaboration peer with no DOM: `createPeerStore({ nickname })` dispatches actions,
+receives a peer's batches and undoes its own. The
+[ERD Editor MCP server](https://github.com/dineug/erd-editor/tree/main/packages/mcp-server#readme)
+is built on it.
 
-This package is the editor core of the [erd-editor monorepo](https://github.com/dineug/erd-editor);
-work on it from a workspace checkout.
+## Development
 
 ```sh
-pnpm --filter @dineug/erd-editor dev            # builds workspace deps, then a dev server
+pnpm --filter @dineug/erd-editor dev            # dev server, workspace deps built first
 pnpm --filter @dineug/erd-editor dev:storybook  # component playground
 pnpm exec vp run --filter @dineug/erd-editor --fail-if-no-match test
 pnpm --filter @dineug/erd-editor e2e            # Playwright
 ```
 
+What a change runs and carries is in
+[AGENTS.md](https://github.com/dineug/erd-editor/blob/main/packages/erd-editor/AGENTS.md).
+
 ## Documentation
 
+- [Editing Guide](https://docs.erd-editor.io/docs/category/guides) — every editor feature
+- [Element API](https://docs.erd-editor.io/docs/api/erd-editor-element) — the `<erd-editor>`
+  element in full
 - [Documentation](https://docs.erd-editor.io)
-- [Editing Guide](https://docs.erd-editor.io/docs/category/guides)
-- [Element API](https://docs.erd-editor.io/docs/api/erd-editor-element)
 
 ## Issues
 

package/dist/components/appContext.d.ts

@@ -15,6 +15,10 @@ export type AppContext = EngineContext & {
     }>;
     keydown$: Subject<KeyboardEvent>;
     emitter: Emitter;
+    /** Set once appDestroy has run, so a render it sets off knows nothing is left to read. */
+    lifecycle: {
+        destroyed: boolean;
+    };
 };
 export type InjectAppContext = InjectEngineContext;
 export type AppContextOptions = RxStoreOptions & {

package/dist/components/erd/Erd.d.ts

@@ -3,6 +3,9 @@ export type ErdProps = {
     isDarkMode: boolean;
     mouseTracking: boolean;
     readonly: boolean;
+    enableWelcomeScreen?: boolean;
+    enableThemeBuilder?: boolean;
+    enableLocalePicker?: boolean;
 };
 declare const Erd: FC<ErdProps>;
 export default Erd;

package/dist/components/erd/automatic-table-placement/AutomaticTablePlacement.d.ts

@@ -1,5 +1,6 @@
 import { FC, Ref } from '@dineug/r-html';
 import { AppContext } from '../../appContext';
+import { I18n } from '../../../i18n/translate';
 export type AutomaticTablePlacementProps = {
     app: Ref<AppContext>;
     onChange: (tables: TablePoint[]) => void;
@@ -13,7 +14,7 @@ export type TablePoint = {
 export type PlacementToastState = {
     progress: number;
 };
-export declare function placementDescription({ progress, }: PlacementToastState): string;
+export declare function placementDescription({ progress }: PlacementToastState, i18n?: I18n): string;
 declare const AutomaticTablePlacement: FC<AutomaticTablePlacementProps>;
 export default AutomaticTablePlacement;
 //# sourceMappingURL=AutomaticTablePlacement.d.ts.map

package/dist/components/erd/automatic-table-placement/createAutomaticTablePlacement.d.ts

@@ -1,12 +1,43 @@
 import { RootState } from '../../../engine/state';
-import { Table } from '../../../internal-types';
-type Node = {
+import { Table, TableGroup } from '../../../internal-types';
+/** A table in no group, put at the node less its radius, as it always was. */
+type TableNode = {
     id: string;
     r: number;
     x: number;
     y: number;
+    vx: number;
+    vy: number;
     ref: Table;
+    width: number;
+    height: number;
 };
+/** A member, and where it stands from the corner of its group's box. */
+type Member = {
+    ref: Table;
+    dx: number;
+    dy: number;
+};
+/**
+ * A group with members, moved as one box centred on the node: the members keep
+ * where they stand inside it, and the box, their bounds and the padding, is
+ * the rect the group is drawn at, so a preview shows the group where it goes.
+ */
+type GroupNode = {
+    id: string;
+    r: number;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    group: TableGroup;
+    width: number;
+    height: number;
+    members: Member[];
+};
+type Node = TableNode | GroupNode;
+/** The least room a group's box keeps from another group's box or a table. */
+export declare const GROUP_BOX_GAP = 100;
 /** The two readings of a simulation's heat that its progress is taken from. */
 type Cooling = {
     alpha(): number;
@@ -23,6 +54,11 @@ type Cooling = {
  * });
  */
 export declare function placementProgress(simulation: Cooling): number;
+/**
+ * The force simulation that places the tables, around the middle of what the
+ * document draws. A group with members is one box in it, its members kept
+ * inside and the box kept clear of the others, so it is drawn where it goes.
+ */
 export declare function createAutomaticTablePlacement(state: RootState): import('d3-force').Simulation<Node, undefined>;
 export {};
 //# sourceMappingURL=createAutomaticTablePlacement.d.ts.map

package/dist/components/erd/automatic-table-placement/elkPlacement.d.ts

@@ -0,0 +1,42 @@
+import { FC } from '@dineug/r-html';
+import { AppContext } from '../../appContext';
+import { ElkLayoutPoint, ElkLayoutRequest } from '../../../services/elk-layout';
+type PlacingToastProps = {
+    onCancel: () => void;
+};
+/**
+ * The message up while ELK works, and the whole of what a one-shot placement
+ * shows. There is no progress to follow and nothing to read off a layout that
+ * does not exist yet, so Cancel is the only thing on it. A view placement shows it too.
+ */
+export declare const PlacingToast: FC<PlacingToastProps>;
+/** How a layout ended: placed, given up on by whoever waited, or never answered. */
+export type ElkLayoutAnswer = {
+    status: 'placed';
+    points: ElkLayoutPoint[];
+} | {
+    status: 'cancelled';
+} | {
+    status: 'failed';
+    error: unknown;
+};
+export type LayoutByElkOptions = {
+    /**
+     * Whether the toast waits until the layout has run long enough to say so,
+     * for a placement nobody asked to watch, rather than going up at once.
+     */
+    whenSlow?: boolean;
+    /** Ends the wait from outside, as Cancel does, and takes the toast down. */
+    signal?: AbortSignal;
+};
+/**
+ * One ELK layout behind the Placing toast, reading nothing but the request and
+ * the app context, so the document and a document not loaded yet are placed
+ * alike. Cancel and the stop key end the wait at once, the toast with it.
+ *
+ * @example
+ * const answer = await layoutByElk(app, request, { whenSlow: true });
+ */
+export declare function layoutByElk({ emitter, shortcut$ }: AppContext, request: ElkLayoutRequest, { whenSlow, signal }?: LayoutByElkOptions): Promise<ElkLayoutAnswer>;
+export {};
+//# sourceMappingURL=elkPlacement.d.ts.map

package/dist/components/erd/automatic-table-placement/flowPlacement.d.ts

@@ -0,0 +1,21 @@
+import { AppContext } from '../../appContext';
+import { ElkLayoutPoint, ElkLayoutRequest } from '../../../services/elk-layout';
+/**
+ * What a Flow placement of a document asks ELK, measured on a plain store of
+ * its own with the editor's text measure, so nothing reaches the editor's
+ * store. Null under two tables or with no relationship, the grid's cases.
+ *
+ * @example
+ * const request = createFlowRequest(app, json);
+ */
+export declare function createFlowRequest({ toWidth }: AppContext, json: string): ElkLayoutRequest | null;
+/**
+ * Where each table of a document not loaded yet goes by Flow, measured from
+ * the corner of the block the tables make, so the caller decides where that
+ * block stands. Null leaves the tables to the grid, and says nothing of why.
+ *
+ * @example
+ * const points = await placeByFlow(app, json, controller.signal);
+ */
+export declare function placeByFlow(app: AppContext, json: string, signal?: AbortSignal): Promise<ElkLayoutPoint[] | null>;
+//# sourceMappingURL=flowPlacement.d.ts.map

package/dist/components/erd/automatic-table-placement/placementActions.d.ts

@@ -0,0 +1,14 @@
+import { AnyAction } from '@dineug/r-html';
+import { RootState } from '../../../engine/state';
+import { TableMove } from '../../../konva/scene/contentBounds';
+import { GeometrySource } from '../../../utils/draw-relationship/geometrySource';
+/**
+ * What a placement lands as: each table at its point, each group with members
+ * at the rect round where they land, and the view centred on the box all of it
+ * fills, read before the move. Dispatched together, they are one undo entry.
+ *
+ * @example
+ * store.dispatch(toPlacementActions(store.state, points));
+ */
+export declare function toPlacementActions(state: RootState, tables: ReadonlyArray<TableMove>, source?: GeometrySource): AnyAction[];
+//# sourceMappingURL=placementActions.d.ts.map