@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/workspace/archimateServices.js

@@ -0,0 +1,33 @@
+import {
+    RenderEngine, ArchimateModel, ArchimateSpecializationSelector, DerivedRelationships, DiagramTabs, ModelTree,
+    SettingsManager, buildAnalysisPanel, buildModelTreePanel, fromArchimateView, parseArchiModel, toArchimateModel,
+    parseArchiFile, toArchiFile, toArchiExport, showGlobalSettingsDialog, showPropertiesDialog, showDiagramPropertiesDialog,
+} from '../index.js';
+
+/**
+ * What ArchimateDiagramEditor takes as its `workspace` option: the classes and
+ * dialogs it builds its model tree, tabs, settings and import/export from,
+ * collected by direct import. A part hands this in rather than reading a
+ * bundle's global, so it works the same however the library was loaded.
+ */
+export const ARCHIMATE_SERVICES = Object.freeze({
+    RenderEngine,
+    ArchimateModel,
+    ArchimateSpecializationRegistry: RenderEngine.ArchimateSpecializationRegistry,
+    ArchimateSpecializationSelector,
+    DerivedRelationships,
+    DiagramTabs,
+    ModelTree,
+    SettingsManager,
+    buildAnalysisPanel,
+    buildModelTreePanel,
+    fromArchimateView,
+    parseArchiModel,
+    parseArchiFile,
+    toArchiFile,
+    toArchiExport,
+    toArchimateModel,
+    showGlobalSettingsDialog,
+    showPropertiesDialog,
+    showDiagramPropertiesDialog,
+});

package/src/workspace/dom.js

@@ -0,0 +1,120 @@
+/**
+ * el() — build DOM from a plain-JSON element spec.
+ *
+ * The shell's structural guardrail: markup is generated from JavaScript and
+ * JSON objects, not written as HTML strings. Structure stays *data* — it can be
+ * inspected, composed, serialized and diffed the same way the layout tree is,
+ * and it never goes through an HTML parser, so text content cannot inject
+ * markup. Raw HTML injection is the deliberate escape hatch (`HtmlPart`), not
+ * the default (`ContentPart`).
+ *
+ * Spec shape — every field optional:
+ *
+ *   {
+ *     tag:      'div',                    // default 'div'
+ *     cls:      'ws-toolbar' | ['a','b'], // class names
+ *     text:     'label',                  // textContent (escaped by construction)
+ *     attrs:    { role: 'tablist' },      // setAttribute; null/false/undefined skipped
+ *     dataset:  { partId: 'nav' },        // data-* attributes
+ *     style:    { flex: '1 1 auto' },     // inline style properties
+ *     on:       { click: fn },            // addEventListener
+ *     children: [spec | Node | string],   // strings become text nodes
+ *     ref:      (element) => {},          // capture the node without querySelector
+ *   }
+ *
+ * A bare string spec produces a text node, so `children: ['plain text']` works.
+ */
+export function el(spec, doc = document) {
+    if (spec == null) return doc.createTextNode('');
+    if (typeof spec === 'string' || typeof spec === 'number') return doc.createTextNode(String(spec));
+    // Duck-typed rather than `instanceof Node`: `Node` is a browser global, so
+    // that test throws a ReferenceError anywhere else — including under a
+    // substituted document. A spec object never carries either of these.
+    if (typeof spec.nodeType === 'number' || typeof spec.appendChild === 'function') return spec;
+
+    const node = doc.createElement(spec.tag ?? 'div');
+
+    if (spec.cls) {
+        const classes = Array.isArray(spec.cls) ? spec.cls : [spec.cls];
+        node.className = classes.filter(Boolean).join(' ');
+    }
+    if (spec.text != null) node.textContent = String(spec.text);
+
+    for (const [k, v] of Object.entries(spec.attrs ?? {})) {
+        if (v == null || v === false) continue;
+        node.setAttribute(k, v === true ? '' : String(v));
+    }
+    for (const [k, v] of Object.entries(spec.dataset ?? {})) {
+        if (v == null) continue;
+        node.dataset[k] = String(v);
+    }
+    for (const [k, v] of Object.entries(spec.style ?? {})) {
+        if (v == null) continue;
+        node.style.setProperty(cssProp(k), String(v));
+    }
+    for (const [event, handler] of Object.entries(spec.on ?? {})) {
+        if (typeof handler === 'function') node.addEventListener(event, handler);
+    }
+    for (const child of spec.children ?? []) {
+        node.appendChild(el(child, doc));
+    }
+
+    spec.ref?.(node);
+    return node;
+}
+
+/** Build several specs into a DocumentFragment. */
+export function frag(specs, doc = document) {
+    const f = doc.createDocumentFragment();
+    for (const spec of specs ?? []) f.appendChild(el(spec, doc));
+    return f;
+}
+
+/** Replace an element's contents with freshly built specs. */
+export function render(host, specs, doc = document) {
+    host.textContent = '';
+    host.appendChild(frag(Array.isArray(specs) ? specs : [specs], doc));
+    return host;
+}
+
+/** camelCase → kebab-case, so style keys can be written either way. */
+function cssProp(key) {
+    return key.startsWith('--') ? key : key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`);
+}
+
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+/**
+ * The same spec as el(), written out as HTML text: for a page that is saved
+ * rather than shown (a report). Text and attribute values are escaped; `on`
+ * and `ref` have no meaning in text and are left out. `script` is the one
+ * extra field: the trusted contents of a <script> or <style> (not escaped,
+ * but `</` is, so it cannot close its element early).
+ */
+export function toHtml(spec) {
+    if (spec == null) return '';
+    if (typeof spec === 'string' || typeof spec === 'number') return escapeHtml(spec);
+    if (Array.isArray(spec)) return spec.map(toHtml).join('');
+    const tag = spec.tag ?? 'div';
+    const attrs = [];
+    if (spec.cls) {
+        const classes = (Array.isArray(spec.cls) ? spec.cls : [spec.cls]).filter(Boolean);
+        if (classes.length) attrs.push(['class', classes.join(' ')]);
+    }
+    for (const [k, v] of Object.entries(spec.attrs ?? {})) {
+        if (v == null || v === false) continue;
+        attrs.push([k, v === true ? '' : String(v)]);
+    }
+    for (const [k, v] of Object.entries(spec.dataset ?? {})) {
+        if (v != null) attrs.push([`data-${cssProp(k)}`, String(v)]);
+    }
+    const style = Object.entries(spec.style ?? {}).filter(([, v]) => v != null).map(([k, v]) => `${cssProp(k)}: ${v}`).join('; ');
+    if (style) attrs.push(['style', style]);
+    const open = `<${tag}${attrs.map(([k, v]) => ` ${k}="${escapeHtml(v)}"`).join('')}>`;
+    if (VOID_TAGS.has(tag)) return open;
+    const inner = spec.script != null
+        ? String(spec.script).replace(/<\//g, '<\\/')
+        : (spec.text != null ? escapeHtml(spec.text) : '') + (spec.children ?? []).map(toHtml).join('');
+    return `${open}${inner}</${tag}>`;
+}

package/src/workspace/index.js

@@ -0,0 +1,75 @@
+/**
+ * Workspace — browser-only entry point for the application shell.
+ *
+ * Deliberately NOT re-exported from `src/index.js`: `Workspace` subclasses
+ * HTMLElement at module scope, so merely importing it throws under node — and
+ * `src/index.js` is the node entry the test suite loads. Import this module
+ * directly from a browser instead.
+ *
+ * Importing it registers the `<ws-workspace>` element. Built-in part types are
+ * NOT auto-registered: which parts exist is the consumer's decision, and
+ * pulling ChartPart in unconditionally would drag the whole RenderEngine into
+ * a shell that may only ever host adapted panels. Call
+ * `registerBuiltinParts(ws)` for the standard set, or register individually.
+ *
+ * See WORKSPACE_ARCHITECTURE.md for the design.
+ */
+import { Workspace, WORKSPACE_TAG, WORKSPACE_SCHEMA_VERSION, defineWorkspace } from './Workspace.js';
+import { ContextBus } from './ContextBus.js';
+import { Part } from './Part.js';
+import { PartRegistry } from './PartRegistry.js';
+import { PartFactory } from './PartFactory.js';
+import { ContentPart } from './parts/ContentPart.js';
+import { HtmlPart } from './parts/HtmlPart.js';
+import { ListPart } from './parts/ListPart.js';
+import { DetailPart } from './parts/DetailPart.js';
+import { AdapterPart } from './parts/AdapterPart.js';
+import { ModelsPart } from './parts/ModelsPart.js';
+
+defineWorkspace();
+
+/** The dependency-free part types — everything except ChartPart. */
+export const BUILTIN_PARTS = [ContentPart, HtmlPart, ListPart, DetailPart, AdapterPart, ModelsPart];
+
+/** Convenience: register the standard part types on a workspace element. */
+export function registerBuiltinParts(ws) {
+    ws.registerParts(BUILTIN_PARTS);
+    return ws;
+}
+
+export {
+    Workspace, WORKSPACE_TAG, WORKSPACE_SCHEMA_VERSION, defineWorkspace,
+    ContextBus, Part, PartRegistry, PartFactory,
+    ContentPart, HtmlPart, ListPart, DetailPart, AdapterPart, ModelsPart,
+};
+export { el, frag, render } from './dom.js';
+
+// The engine's whole public API, re-exported so the workspace UMD bundle is a
+// superset of the main one: a page that loads renderengine-workspace.umd.js
+// gets both the shell and RenderEngine from a single script tag, instead of
+// having to load two bundles in the right order. A star export rather than a
+// list, so nothing the engine adds can go missing here; this module's own
+// exports take precedence over any of the same name.
+export * from '../index.js';
+export {
+    BUILTIN_THEMES, SYSTEM_THEME, THEME_VARS,
+    LIGHT_THEME, DARK_THEME, MIDNIGHT_THEME, SEPIA_THEME,
+} from './themes.js';
+export { ChartPart } from './parts/ChartPart.js';
+export { EditorPart } from './parts/EditorPart.js';
+export { DiagramEditorPart } from './parts/DiagramEditorPart.js';
+export { ArchimateEditorPart } from './parts/ArchimateEditorPart.js';
+export { ArchimateCanvasPart } from './parts/ArchimateCanvasPart.js';
+export { ARCHIMATE_SERVICES } from './archimateServices.js';
+export { EditorShell } from './EditorShell.js';
+export {
+    createLayout, LayoutNode, PartNode, SplitNode, TabsNode, GridNode,
+    GRID_COLS, ROW_UNIT_PX, GRID_GAP_PX,
+    MIN_COL_SPAN, MIN_ROW_SPAN, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN,
+} from './layout/index.js';
+export { WORKSPACE_CSS, ensureStyles } from './styles.js';
+export { WorkArea } from './workArea.js';
+export {
+    emptyWorkArea, listGroups, listOpenParts, findPart, resolveGroup,
+    openPart, closePart, focusPart,
+} from './workAreaModel.js';

package/src/workspace/layout/GridNode.js

@@ -0,0 +1,280 @@
+import { LayoutNode } from './LayoutNode.js';
+import { el, render } from '../dom.js';
+
+/**
+ * GridNode — a 12-column grid of draggable, resizable panes.
+ *
+ * The geometry, snapping, collision-swap and "crystallize" behaviour here are
+ * lifted from sqlengine workbench's `dashboard.js`, which is where this model
+ * was proven in production. Keeping the numbers and the semantics identical is
+ * deliberate: it is what lets an existing dashboard document load into this
+ * shell unchanged, via `GridNode.migrateChildren()`.
+ *
+ * A child's placement lives in `child.spec.layout = {col, row, colSpan, rowSpan}`.
+ * `col`/`row` are 1-based and stay undefined until a pane is actually dragged,
+ * so an untouched grid flows left-to-right via native CSS grid auto-placement.
+ * The first drag or resize on ANY pane crystallizes the whole grid — every
+ * pane's currently rendered position is captured into explicit col/row — so
+ * pinned and auto-flowing panes are never mixed after that point.
+ */
+
+export const GRID_COLS = 12;
+export const ROW_UNIT_PX = 20;   // must match .ws-grid's grid-auto-rows
+export const GRID_GAP_PX = 14;   // must match .ws-grid's gap
+export const MIN_COL_SPAN = 2;
+export const MIN_ROW_SPAN = 4;
+export const DEFAULT_COL_SPAN = 6;
+export const DEFAULT_ROW_SPAN = 9;
+
+/** Old dashboard shape `{span: 1-4, height: 'sm'|'md'|'lg'}` → `{colSpan,rowSpan}`. */
+const OLD_HEIGHT_TO_ROWS = { sm: 6, md: 9, lg: 13 };
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+
+function rectsOverlap(a, b) {
+    if (a.col == null || b.col == null) return false;
+    return a.col < b.col + b.colSpan && a.col + a.colSpan > b.col &&
+           a.row < b.row + b.rowSpan && a.row + a.rowSpan > b.row;
+}
+
+export class GridNode extends LayoutNode {
+    static type = 'grid';
+
+    /**
+     * Convert legacy `{span, height}` child layouts in place. Returns true if
+     * anything was converted, so the caller knows to persist the migration
+     * rather than re-derive it on every load.
+     */
+    static migrateChildren(children) {
+        let migrated = false;
+        for (const child of children ?? []) {
+            const old = child.layout ?? {};
+            if (old.colSpan != null) continue;
+            child.layout = {
+                colSpan: clamp((old.span ?? 2) * 3, MIN_COL_SPAN, GRID_COLS),
+                rowSpan: OLD_HEIGHT_TO_ROWS[old.height ?? 'md'] ?? DEFAULT_ROW_SPAN,
+            };
+            migrated = true;
+        }
+        return migrated;
+    }
+
+    constructor(spec = {}) {
+        super(spec);
+        this.cols = spec.cols ?? GRID_COLS;
+        this.movable = spec.movable !== false;
+        this.resizable = spec.resizable !== false;
+        for (const child of this.children) {
+            const l = child.spec.layout ?? (child.spec.layout = {});
+            l.colSpan ??= DEFAULT_COL_SPAN;
+            l.rowSpan ??= DEFAULT_ROW_SPAN;
+        }
+        this._panes = [];
+    }
+
+    build(ctx) {
+        this.el.classList.add('ws-grid');
+        this.el.style.gridTemplateColumns = `repeat(${this.cols}, minmax(0, 1fr))`;
+        this._panes = [];
+
+        this.children.forEach((child) => {
+            let header, body;
+            const paneEl = this.el.appendChild(el({
+                cls: 'ws-pane',
+                children: [
+                    { cls: 'ws-pane-header', attrs: { title: this.movable ? 'Drag to move' : null },
+                      ref: n => { header = n; } },
+                    { cls: 'ws-pane-body', ref: n => { body = n; } },
+                ],
+            }));
+            this._panes.push(paneEl);
+            this._applyPlacement(paneEl, child.spec.layout);
+
+            child.render(body, ctx);
+            child.activate?.();
+            // After render(): a PartNode only resolves its part — and therefore
+            // its title and actions — during render(), so building the header
+            // earlier would show the raw part id and no buttons.
+            this._buildPaneHeader(header, child);
+
+            if (this.movable) this._attachDragMove(paneEl, header, child);
+            if (this.resizable) this._attachResize(paneEl, child);
+        });
+    }
+
+    activate() {
+        for (const child of this.children) child.activate?.();
+    }
+
+    /**
+     * Title plus the part's own pane actions (rename, refresh, close, …).
+     *
+     * Actions come from the mounted Part, not from the layout spec: they carry
+     * callbacks, and the layout tree has to stay serializable JSON. `_attachDragMove`
+     * already ignores pointerdowns inside `.ws-pane-controls`, so a button click
+     * never starts a pane drag.
+     */
+    _buildPaneHeader(header, child) {
+        const actions = child.paneActions?.() ?? [];
+        render(header, [
+            { tag: 'span', cls: 'ws-pane-title', text: child.label?.() ?? child.spec?.title ?? '',
+              attrs: { title: child.paneTooltip?.() ?? null } },
+            ...(actions.length ? [{
+                tag: 'span', cls: 'ws-pane-controls',
+                children: actions.map(a => ({
+                    tag: 'button',
+                    cls: 'ws-pane-btn',
+                    text: a.label,
+                    attrs: { type: 'button', title: a.title ?? a.label },
+                    on: { click: (e) => { e.stopPropagation(); a.onClick?.(e); } },
+                })),
+            }] : []),
+        ]);
+    }
+
+    _applyPlacement(paneEl, l) {
+        paneEl.style.gridColumn = l.col != null ? `${l.col} / span ${l.colSpan}` : `span ${l.colSpan}`;
+        paneEl.style.gridRow = l.row != null ? `${l.row} / span ${l.rowSpan}` : `span ${l.rowSpan}`;
+    }
+
+    /** Re-apply every pane's placement after a move/resize commits. */
+    _restyleAll() {
+        this.children.forEach((child, i) => {
+            const paneEl = this._panes[i];
+            if (paneEl) this._applyPlacement(paneEl, child.spec.layout);
+        });
+    }
+
+    _metrics() {
+        const rect = this.el.getBoundingClientRect();
+        const colWidth = (rect.width - GRID_GAP_PX * (this.cols - 1)) / this.cols;
+        return { rect, colWidth, rowHeight: ROW_UNIT_PX, gap: GRID_GAP_PX };
+    }
+
+    /**
+     * Capture every pane's currently rendered position into explicit col/row if
+     * any pane lacks one. Visually a no-op — see the class doc for why the
+     * whole grid is pinned at once rather than per pane.
+     */
+    _crystallizeIfNeeded() {
+        if (!this.children.some(c => c.spec.layout.col == null || c.spec.layout.row == null)) return;
+        const { rect, colWidth, rowHeight, gap } = this._metrics();
+        this.children.forEach((child, i) => {
+            const l = child.spec.layout;
+            if (l.col != null && l.row != null) return;
+            const paneEl = this._panes[i];
+            if (!paneEl) return;
+            const r = paneEl.getBoundingClientRect();
+            l.col = Math.max(1, Math.round((r.left - rect.left) / (colWidth + gap)) + 1);
+            l.row = Math.max(1, Math.round((r.top - rect.top) / (rowHeight + gap)) + 1);
+        });
+    }
+
+    _attachDragMove(paneEl, header, child) {
+        header.addEventListener('pointerdown', (e) => {
+            if (e.button !== 0 || e.target.closest('.ws-pane-controls')) return;
+            this._crystallizeIfNeeded();
+            const l = child.spec.layout;
+            const { colWidth, rowHeight, gap } = this._metrics();
+            const startX = e.clientX, startY = e.clientY;
+            const startCol = l.col, startRow = l.row;
+            header.setPointerCapture(e.pointerId);
+            paneEl.classList.add('ws-pane-dragging');
+
+            const onMove = (ev) => {
+                paneEl.style.transform = `translate(${ev.clientX - startX}px, ${ev.clientY - startY}px)`;
+            };
+            const onUp = (ev) => {
+                header.releasePointerCapture(e.pointerId);
+                header.removeEventListener('pointermove', onMove);
+                header.removeEventListener('pointerup', onUp);
+                header.removeEventListener('pointercancel', onUp);
+                paneEl.style.transform = '';
+                paneEl.classList.remove('ws-pane-dragging');
+
+                const colDelta = Math.round((ev.clientX - startX) / (colWidth + gap));
+                const rowDelta = Math.round((ev.clientY - startY) / (rowHeight + gap));
+                if (colDelta === 0 && rowDelta === 0) return; // a click, not a drag
+
+                const targetCol = clamp(startCol + colDelta, 1, this.cols - l.colSpan + 1);
+                const targetRow = Math.max(1, startRow + rowDelta);
+                const target = { col: targetCol, row: targetRow, colSpan: l.colSpan, rowSpan: l.rowSpan };
+
+                // Simple and predictable rather than a real bin-packer: landing
+                // on exactly one occupied pane swaps the two.
+                const occupant = this.children.find(c => c !== child && rectsOverlap(target, c.spec.layout));
+                if (occupant) {
+                    const swapCol = occupant.spec.layout.col, swapRow = occupant.spec.layout.row;
+                    occupant.spec.layout.col = l.col;
+                    occupant.spec.layout.row = l.row;
+                    l.col = swapCol;
+                    l.row = swapRow;
+                } else {
+                    l.col = targetCol;
+                    l.row = targetRow;
+                }
+                this._restyleAll();
+                this._emitChange();
+            };
+            header.addEventListener('pointermove', onMove);
+            header.addEventListener('pointerup', onUp);
+            header.addEventListener('pointercancel', onUp);
+        });
+    }
+
+    _attachResize(paneEl, child) {
+        const handle = paneEl.appendChild(el({
+            cls: 'ws-resize-handle',
+            text: '⤡',
+            attrs: { title: 'Drag to resize' },
+        }));
+
+        handle.addEventListener('pointerdown', (e) => {
+            if (e.button !== 0) return;
+            e.stopPropagation();
+            this._crystallizeIfNeeded();
+            const l = child.spec.layout;
+            const { colWidth, rowHeight, gap } = this._metrics();
+            const startX = e.clientX, startY = e.clientY;
+            const startColSpan = l.colSpan, startRowSpan = l.rowSpan;
+            const maxColSpan = this.cols - l.col + 1;
+            handle.setPointerCapture(e.pointerId);
+            paneEl.classList.add('ws-pane-dragging');
+
+            const computeSpans = (ev) => ({
+                colSpan: clamp(startColSpan + Math.round((ev.clientX - startX) / (colWidth + gap)), MIN_COL_SPAN, maxColSpan),
+                rowSpan: Math.max(MIN_ROW_SPAN, startRowSpan + Math.round((ev.clientY - startY) / (rowHeight + gap))),
+            });
+            const onMove = (ev) => {
+                const { colSpan, rowSpan } = computeSpans(ev);
+                paneEl.style.gridColumn = `${l.col} / span ${colSpan}`;
+                paneEl.style.gridRow = `${l.row} / span ${rowSpan}`;
+            };
+            const onUp = (ev) => {
+                handle.releasePointerCapture(e.pointerId);
+                handle.removeEventListener('pointermove', onMove);
+                handle.removeEventListener('pointerup', onUp);
+                handle.removeEventListener('pointercancel', onUp);
+                paneEl.classList.remove('ws-pane-dragging');
+                const { colSpan, rowSpan } = computeSpans(ev);
+                l.colSpan = colSpan;
+                l.rowSpan = rowSpan;
+                this._restyleAll();
+                this._emitChange();
+            };
+            handle.addEventListener('pointermove', onMove);
+            handle.addEventListener('pointerup', onUp);
+            handle.addEventListener('pointercancel', onUp);
+        });
+    }
+
+    serialize() {
+        return {
+            type: GridNode.type,
+            cols: this.cols,
+            ...(this.movable ? {} : { movable: false }),
+            ...(this.resizable ? {} : { resizable: false }),
+            children: this.children.map(c => c.serialize()),
+        };
+    }
+}

package/src/workspace/layout/LayoutNode.js

@@ -0,0 +1,89 @@
+/**
+ * LayoutNode — base class for the layout tree.
+ *
+ * One subclass per node kind, one file each: SplitNode, TabsNode, GridNode,
+ * PartNode. The serialized form carries a `type` discriminator because JSON has
+ * no classes; `LayoutNode.create()` maps it back. Subclasses import only this
+ * base and call `LayoutNode.create()` for their children, so there is no import
+ * cycle with `layout/index.js` (which is what populates the type table).
+ */
+import { el } from '../dom.js';
+
+export class LayoutNode {
+    /** Discriminator used in serialized form. Every subclass overrides this. */
+    static type = null;
+
+    /** @type {Map<string, typeof LayoutNode>} populated by layout/index.js */
+    static _types = new Map();
+
+    static registerType(NodeClass) {
+        if (!NodeClass?.type) throw new Error(`Layout node ${NodeClass?.name} has no static type`);
+        LayoutNode._types.set(NodeClass.type, NodeClass);
+    }
+
+    /** Build a node (and its subtree) from a plain-JSON descriptor. */
+    static create(json) {
+        if (json instanceof LayoutNode) return json;
+        const NodeClass = LayoutNode._types.get(json?.type);
+        if (!NodeClass) {
+            throw new Error(`Unknown layout node type "${json?.type}" (known: ${[...LayoutNode._types.keys()].join(', ') || 'none'})`);
+        }
+        return new NodeClass(json);
+    }
+
+    constructor(spec = {}) {
+        if (new.target === LayoutNode) throw new TypeError('LayoutNode is abstract — subclass it');
+        this.spec = spec;
+        /** @type {LayoutNode[]} */
+        this.children = (spec.children ?? []).map(c => LayoutNode.create(c));
+        /** @type {HTMLElement|null} this node's own root element */
+        this.el = null;
+        this.ctx = null;
+    }
+
+    /**
+     * Build DOM into `host`. Subclasses override `build()`, not this — this
+     * handles the common element/ctx bookkeeping.
+     */
+    render(host, ctx) {
+        this.ctx = ctx;
+        // `ws-node-<type>`, not `ws-<type>` — the latter would give a PartNode
+        // the class `ws-part`, which is what a mounted Part names its own root.
+        this.el = host.appendChild(el({ cls: ['ws-node', `ws-node-${this.constructor.type}`] }));
+        this.build(ctx);
+        return this.el;
+    }
+
+    /** Subclasses implement. `this.el` is attached and empty. */
+    build() {
+        throw new Error(`${this.constructor.name} must implement build()`);
+    }
+
+    /**
+     * Detach this node's DOM. Does NOT dispose parts — part lifetime belongs to
+     * the PartRegistry pool so instances survive a perspective switch (see
+     * PartRegistry.disposeExcept).
+     */
+    dispose() {
+        for (const child of this.children) child.dispose();
+        if (this.el?.parentNode) this.el.parentNode.removeChild(this.el);
+        this.el = null;
+        this.ctx = null;
+    }
+
+    /** Every part id referenced in this subtree. */
+    partIds() {
+        return this.children.flatMap(c => c.partIds());
+    }
+
+    serialize() {
+        const out = { ...this.spec, type: this.constructor.type };
+        if (this.children.length) out.children = this.children.map(c => c.serialize());
+        return out;
+    }
+
+    /** Notify the shell that geometry changed and should be persisted. */
+    _emitChange() {
+        this.ctx?.onLayoutChange?.();
+    }
+}

package/src/workspace/layout/PartNode.js

@@ -0,0 +1,77 @@
+import { LayoutNode } from './LayoutNode.js';
+import { render } from '../dom.js';
+
+/**
+ * PartNode — leaf of the layout tree. Resolves `partId` against the shell's
+ * PartRegistry pool and mounts that part into its own container.
+ *
+ * Mounting is lazy: `build()` only creates the container. `activate()` does the
+ * actual `part.mount()`, and TabsNode calls it when a tab is first shown. Once
+ * mounted the part stays mounted (see Part's class doc) — lazy-then-permanent,
+ * not mount/unmount per switch. Nodes outside a TabsNode are activated
+ * immediately by their parent.
+ */
+export class PartNode extends LayoutNode {
+    static type = 'part';
+
+    constructor(spec = {}) {
+        super(spec);
+        this.partId = spec.partId ?? spec.id;
+        if (!this.partId) throw new Error('PartNode requires a partId');
+        this.part = null;
+    }
+
+    build(ctx) {
+        this.el.classList.add('ws-part-host');
+        this.el.dataset.partId = this.partId;
+        this.part = ctx.registry.get(this.partId);
+        if (!this.part) {
+            render(this.el, { cls: 'ws-part-missing', text: `Unknown part: ${this.partId}` });
+        }
+    }
+
+    /**
+     * Mount the part, or re-parent it if it is already live (pooled across a
+     * perspective switch). Idempotent.
+     */
+    activate() {
+        if (!this.part) return;
+        try {
+            this.part.mount(this.el, this.ctx);
+        } catch (err) {
+            console.error(`PartNode: part "${this.partId}" failed to mount`, err);
+            render(this.el, { cls: 'ws-part-missing', text: `Part "${this.partId}" failed to mount — see console.` });
+        }
+    }
+
+    /** Title for a tab strip / pane header. */
+    label() {
+        return this.part?.title ?? this.spec.title ?? this.partId;
+    }
+
+    /** Pane-header buttons contributed by the mounted part. */
+    paneActions() {
+        return this.part?.actions ?? [];
+    }
+
+    /** Hover text for the pane title. */
+    paneTooltip() {
+        return this.part?.paneTooltip ?? null;
+    }
+
+    dispose() {
+        // Detach the part's element without disposing the instance — the pool
+        // decides whether it survives the perspective switch, and detach()
+        // keeps its DOM (and therefore its state) intact either way.
+        this.part?.detach();
+        super.dispose();
+    }
+
+    partIds() {
+        return [this.partId];
+    }
+
+    serialize() {
+        return { type: PartNode.type, partId: this.partId, ...(this.spec.layout ? { layout: { ...this.spec.layout } } : {}) };
+    }
+}