@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/workspace/EditorShell.js

@@ -0,0 +1,67 @@
+import { el } from './dom.js';
+
+/**
+ * EditorShell — the workbench layout diagram editors share: a toolbar row, a
+ * side panel (model tree, palette), the main area (tabs + canvas) and an
+ * optional right-hand aside. Built with el() and inline styles, so it needs no
+ * stylesheet and never restyles the host page.
+ *
+ * Not a custom element, so the engine bundle can use it under node too.
+ */
+export class EditorShell {
+    /**
+     * @param {Object} [options]
+     * @param {Document} [options.document]
+     * @param {string} [options.sideWidth]
+     * @param {boolean} [options.aside] - Add a right-hand panel
+     * @param {string} [options.asideWidth]
+     * @param {Object<string, string>} [options.ids] - Element ids per region: toolbar, side, main, aside
+     * @param {boolean} [options.fullPage] - Fill the viewport (and drop the body margin)
+     */
+    constructor({ document: doc = document, sideWidth = '280px', aside = false, asideWidth = '300px', ids = {}, fullPage = false } = {}) {
+        this.doc = doc;
+        this.sideWidth = sideWidth;
+        this.aside = aside;
+        this.asideWidth = asideWidth;
+        this.ids = ids;
+        this.fullPage = fullPage;
+    }
+
+    /** @returns {{root: HTMLElement, toolbar: HTMLElement, side: HTMLElement, main: HTMLElement, aside?: HTMLElement}} */
+    build() {
+        const regions = {};
+        const region = (name, style) => ({
+            attrs: { id: this.ids[name] ?? null, 'data-shell-region': name },
+            style,
+            ref: (n) => { regions[name] = n; },
+        });
+        const panel = { background: '#fafafa', overflowY: 'auto', minHeight: '0', boxSizing: 'border-box' };
+        regions.root = el({
+            attrs: { 'data-editor-shell': '' },
+            style: {
+                display: 'flex', flexDirection: 'column', height: this.fullPage ? '100vh' : '100%', minHeight: '0',
+                fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif", color: '#333', background: '#f5f5f5',
+            },
+            children: [
+                region('toolbar', { flex: '0 0 auto' }),
+                {
+                    style: { display: 'flex', flex: '1 1 auto', minHeight: '0', overflow: 'hidden' },
+                    children: [
+                        region('side', { ...panel, flex: `0 0 ${this.sideWidth}`, borderRight: '1px solid #ddd' }),
+                        region('main', { flex: '1 1 auto', display: 'flex', flexDirection: 'column', minWidth: '0', minHeight: '0', background: '#fff', position: 'relative' }),
+                        this.aside && region('aside', { ...panel, flex: `0 0 ${this.asideWidth}`, borderLeft: '1px solid #ddd' }),
+                    ].filter(Boolean),
+                },
+            ],
+        }, this.doc);
+        return regions;
+    }
+
+    /** Replace the host's contents with the shell. */
+    mount(host) {
+        const regions = this.build();
+        host.replaceChildren(regions.root);
+        if (this.fullPage) this.doc.body.style.margin = '0';
+        return regions;
+    }
+}

package/src/workspace/Part.js

@@ -0,0 +1,163 @@
+/**
+ * Part — base class for one unit of contributed UI.
+ *
+ * Subclasses live one-per-file under `parts/` and set `static type` (the
+ * registry key) plus, where meaningful, `static publishes` / `static subscribes`
+ * (the channel names they read and write). Those two are static metadata rather
+ * than ad-hoc `bus.subscribe()` calls buried inside `render()` precisely so a
+ * visual wiring UI can enumerate them without instantiating anything — that's
+ * the mashup authoring story.
+ *
+ * Lifecycle is `mount()` → `dispose()`. There is deliberately no "deactivate"
+ * hook: a part that is hidden but still in the layout tree stays mounted,
+ * because tearing down and rebuilding on every tab switch is what makes an IDE
+ * shell feel slow. A part that must stop work while hidden should subscribe to
+ * a visibility channel instead.
+ */
+import { el } from './dom.js';
+
+export class Part {
+    /** Registry key. Every concrete subclass must override this. */
+    static type = null;
+
+    /** Channel names this part writes / reads. Metadata only — see class doc. */
+    static publishes = [];
+    static subscribes = [];
+
+    constructor(spec = {}) {
+        if (new.target === Part) throw new TypeError('Part is abstract — subclass it');
+        this.id = spec.id;
+        this.title = spec.title ?? spec.id;
+        this.spec = spec;
+        /** The element this part owns. Created once, re-parented thereafter. */
+        this.root = null;
+        this.container = null;
+        this.ctx = null;
+        /** @type {Array<Function>} teardown callbacks run by dispose() */
+        this._disposers = [];
+        this._mounted = false;
+    }
+
+    get mounted() { return this._mounted; }
+
+    /**
+     * Attach to a host element. `ctx` carries the shell's services —
+     * `{ bus, engine, registry, theme, ...consumer extras }`.
+     *
+     * The part owns `this.root` and only builds it once. Calling `mount()`
+     * again — which happens when a perspective switch rebuilds the tree around
+     * a pooled part — re-parents that same element instead of re-rendering.
+     * That is what actually preserves scroll position, text selection and
+     * unsaved input across a perspective switch; re-running `render()` would
+     * throw all of it away.
+     */
+    mount(host, ctx) {
+        if (!this._mounted) {
+            this.root = el({
+                cls: 'ws-part',
+                dataset: { partId: this.id ?? '', partType: this.constructor.type ?? '' },
+            });
+            this.container = this.root;
+            this.ctx = ctx;
+            this._mounted = true;
+            host.appendChild(this.root);
+            this.render();
+            return;
+        }
+        host.appendChild(this.root); // moves it; no re-render
+    }
+
+    /**
+     * Whether the part is on screen now: mounted, in the page, and not in a
+     * hidden tab (a part in a tab that is not selected stays mounted). Keys a
+     * part listens for on the whole page should only act while it is.
+     */
+    isShown() {
+        const node = this.container;
+        if (!this.mounted || !node?.isConnected) return false;
+        return typeof node.getClientRects === 'function' ? node.getClientRects().length > 0 : true;
+    }
+
+    /** Remove from the DOM but keep the element and all state intact. */
+    detach() {
+        if (this.root?.parentNode) this.root.parentNode.removeChild(this.root);
+    }
+
+    /** Subclasses implement this. `this.container` / `this.ctx` are set. */
+    render() {
+        throw new Error(`${this.constructor.name} must implement render()`);
+    }
+
+    /* ── Leak-safe helpers ───────────────────────────────────────────────────
+       Anything registered through these is torn down by dispose(). Parts that
+       reach past them (raw setInterval, raw addEventListener on window) are on
+       their own — a leaked pane refresh timer keeps hitting the server forever
+       after the pane is gone, which is exactly the failure this guards. */
+
+    subscribe(channel, fn) {
+        const off = this.ctx.bus.subscribe(channel, fn);
+        this._disposers.push(off);
+        return off;
+    }
+
+    publish(channel, value) {
+        this.ctx.bus.publish(channel, value);
+    }
+
+    every(ms, fn) {
+        const id = setInterval(fn, ms);
+        this._disposers.push(() => clearInterval(id));
+        return id;
+    }
+
+    listen(target, event, fn, options) {
+        target.addEventListener(event, fn, options);
+        this._disposers.push(() => target.removeEventListener(event, fn, options));
+    }
+
+    /** Register an arbitrary teardown callback. */
+    onDispose(fn) {
+        this._disposers.push(fn);
+    }
+
+    /**
+     * Buttons this part contributes to its pane header or to a frame's action
+     * bar, as `[{label, title?, onClick, disabled?, separator?}]`. Rendered by
+     * GridNode into `.ws-pane-controls`, and by WorkArea into its action bar.
+     *
+     * On the Part rather than in the layout spec because they carry callbacks
+     * and the layout tree has to stay serializable JSON. Subclasses override, or
+     * a spec may supply a plain array for adapter-style parts.
+     *
+     * A spec may also supply a FUNCTION, called each time the actions are read.
+     * That is what lets a panel's buttons depend on its own state — "Export" is
+     * disabled until something is loaded — without the shell having to know
+     * anything about that state. An array stays an array, so nothing that
+     * already supplies one changes.
+     */
+    get actions() {
+        const a = this.spec.actions;
+        return (typeof a === 'function' ? a(this) : a) ?? [];
+    }
+
+    /** Optional hover text for the pane title (e.g. type and refresh interval). */
+    get paneTooltip() {
+        return this.spec.paneTooltip ?? null;
+    }
+
+    dispose() {
+        for (const fn of this._disposers.reverse()) {
+            try { fn(); } catch (err) { console.error(`${this.constructor.name}#${this.id}: disposer threw`, err); }
+        }
+        this._disposers = [];
+        if (this.root?.parentNode) this.root.parentNode.removeChild(this.root);
+        this.root = null;
+        this.container = null;
+        this.ctx = null;
+        this._mounted = false;
+    }
+
+    serialize() {
+        return { ...this.spec, type: this.constructor.type, id: this.id, title: this.title };
+    }
+}

package/src/workspace/PartFactory.js

@@ -0,0 +1,49 @@
+import { Part } from './Part.js';
+
+/**
+ * PartFactory — instantiates Part subclasses from specs.
+ *
+ * Separates object creation from the pooling lifecycle in PartRegistry so each
+ * class has a single responsibility.
+ */
+export class PartFactory {
+    constructor() {
+        /** @type {Map<string, typeof Part>} */
+        this._types = new Map();
+    }
+
+    /** Register a Part subclass, keyed on its static `type`. */
+    register(PartClass) {
+        const type = PartClass?.type;
+        if (!type) throw new Error(`Part class ${PartClass?.name ?? PartClass} has no static type`);
+        if (!(PartClass.prototype instanceof Part)) {
+            throw new Error(`${PartClass.name} must extend Part`);
+        }
+        this._types.set(type, PartClass);
+        return this;
+    }
+
+    registerAll(classes) {
+        for (const c of classes) this.register(c);
+        return this;
+    }
+
+    hasType(type) { return this._types.has(type); }
+    registeredTypes() { return [...this._types.keys()]; }
+
+    /** Registered types with their declared channels — feeds a wiring UI. */
+    describeTypes() {
+        return [...this._types.values()].map(Cls => ({
+            type: Cls.type,
+            publishes: Cls.publishes ?? [],
+            subscribes: Cls.subscribes ?? [],
+        }));
+    }
+
+    /** Instantiate from a spec. */
+    create(spec) {
+        const PartClass = this._types.get(spec?.type);
+        if (!PartClass) throw new Error(`Unknown part type "${spec?.type}" (registered: ${this.registeredTypes().join(', ') || 'none'})`);
+        return new PartClass(spec);
+    }
+}

package/src/workspace/PartRegistry.js

@@ -0,0 +1,86 @@
+import { PartFactory } from './PartFactory.js';
+
+/**
+ * PartRegistry — live instance pool for Part subclasses.
+ *
+ * The pool is what makes perspective switching cheap and non-destructive:
+ * instances are keyed by part id, so if the incoming perspective also
+ * references `notebook`, the same instance is reused and keeps its scroll
+ * position, unsaved buffer and subscriptions.
+ *
+ * Pooled parts are NOT disposed when a perspective stops referencing them —
+ * they are only detached, so switching back finds them intact. Disposal is
+ * explicit: `remove`, `disposeExcept`, `disposeAll`.
+ *
+ * Type registration and instantiation live in PartFactory; this class owns
+ * only the instance pool lifecycle.
+ */
+export class PartRegistry {
+    constructor(factory = new PartFactory()) {
+        /** @type {PartFactory} */
+        this._factory = factory;
+        /** @type {Map<string, Part>} */
+        this._instances = new Map();
+    }
+
+    /** Register a Part subclass with the underlying factory. */
+    register(PartClass) {
+        this._factory.register(PartClass);
+        return this;
+    }
+
+    registerAll(classes) {
+        this._factory.registerAll(classes);
+        return this;
+    }
+
+    hasType(type) { return this._factory.hasType(type); }
+
+    /** Instantiate from a spec without pooling it. */
+    create(spec) {
+        return this._factory.create(spec);
+    }
+
+    /**
+     * Add a part to the pool from its spec. Ids must be unique — a duplicate id
+     * silently replacing a live part would orphan its subscriptions.
+     */
+    add(spec) {
+        if (!spec?.id) throw new Error('Part spec requires an id');
+        if (this._instances.has(spec.id)) throw new Error(`Part id "${spec.id}" already exists`);
+        const part = this.create(spec);
+        this._instances.set(spec.id, part);
+        return part;
+    }
+
+    get(id) { return this._instances.get(id); }
+    has(id) { return this._instances.has(id); }
+    ids() { return [...this._instances.keys()]; }
+
+    remove(id) {
+        const part = this._instances.get(id);
+        if (!part) return false;
+        part.dispose();
+        this._instances.delete(id);
+        return true;
+    }
+
+    /** Dispose every pooled part whose id is not in `keepIds`. */
+    disposeExcept(keepIds) {
+        const keep = new Set(keepIds);
+        for (const id of [...this._instances.keys()]) {
+            if (!keep.has(id)) this.remove(id);
+        }
+    }
+
+    disposeAll() { this.disposeExcept([]); }
+
+    /** Registered types with their declared channels — feeds a wiring UI. */
+    describeTypes() {
+        return this._factory.describeTypes();
+    }
+
+    serialize() {
+        return [...this._instances.values()].map(p => p.serialize());
+    }
+}

package/src/workspace/Workspace.js

@@ -0,0 +1,321 @@
+import { ContextBus } from './ContextBus.js';
+import { PartRegistry } from './PartRegistry.js';
+import { createLayout } from './layout/index.js';
+import { ensureStyles } from './styles.js';
+import { BUILTIN_THEMES, SYSTEM_THEME } from './themes.js';
+import { render } from './dom.js';
+
+/** Bump when the serialized shape changes; `deserialize` migrates on the way in. */
+export const WORKSPACE_SCHEMA_VERSION = 1;
+
+/**
+ * Workspace — the `<ws-workspace>` custom element and the shell's public API.
+ *
+ * Renders into **light DOM**: parts routinely carry their own stylesheets, and a
+ * consumer stylesheet cannot cross a shadow boundary. All shell markup is
+ * `ws-`-prefixed and themed through CSS custom properties instead.
+ *
+ * Typical wiring:
+ *
+ *   const ws = document.querySelector('ws-workspace');
+ *   ws.registerParts([ListPart, DetailPart, ChartPart]);
+ *   ws.addPart({ id: 'nav', type: 'list', title: 'Tables', items: [...] });
+ *   ws.registerPerspective('default', { type: 'split', dir: 'row', children: [...] });
+ *   ws.activatePerspective('default');
+ */
+export class Workspace extends HTMLElement {
+    constructor() {
+        super();
+        this.bus = new ContextBus();
+        this.registry = new PartRegistry();
+        /** @type {Map<string, object>} name → layout JSON */
+        this.perspectives = new Map();
+        this.activePerspective = null;
+        /** @type {import('./layout/LayoutNode.js').LayoutNode|null} */
+        this.tree = null;
+        /** @type {Map<string, object>} theme name → CSS custom-property map */
+        this.themes = new Map(Object.entries(BUILTIN_THEMES));
+        /** The *selection* — may be `system`, which resolves at apply time. */
+        this.theme = 'light';
+        /** Custom properties currently written onto the host, so they can be
+         *  cleared before a different theme is applied. */
+        this._appliedVars = [];
+        this._built = false;
+    }
+
+    /* ── Element lifecycle ──────────────────────────────────────────────── */
+
+    connectedCallback() {
+        if (this._built) return;
+        this._built = true;
+        ensureStyles(this.ownerDocument ?? document);
+        this.classList.add('ws-workspace');
+
+        // Chrome is built from element specs rather than an HTML string, and
+        // `ref` captures the nodes directly — no querySelector round-trip.
+        // `label`, not `title` — `title` is a global HTML attribute and would
+        // also render a browser tooltip over the whole workspace.
+        render(this, [
+            { cls: 'ws-toolbar', children: [
+                { tag: 'span', cls: 'ws-toolbar-title', text: this.getAttribute('label') ?? '' },
+                { tag: 'span', cls: 'ws-toolbar-spacer' },
+                { tag: 'span', cls: 'ws-theme-picker', ref: n => { this._themePickerEl = n; } },
+                { tag: 'span', cls: 'ws-perspectives', ref: n => { this._perspectivesEl = n; } },
+            ]},
+            { cls: 'ws-root', ref: n => { this._rootEl = n; } },
+        ]);
+
+        this.applyTheme(this.getAttribute('theme') ?? 'light');
+        this._renderThemePicker();
+
+        // A perspective registered before the element was connected renders now.
+        if (this.activePerspective) this._renderTree();
+        else if (this.perspectives.size) this.activatePerspective([...this.perspectives.keys()][0]);
+    }
+
+    disconnectedCallback() {
+        this.tree?.dispose();
+        this.tree = null;
+        this._watchSystemTheme(false); // a live matchMedia listener would outlive the element
+    }
+
+    /* ── Parts ──────────────────────────────────────────────────────────── */
+
+    registerPart(PartClass) { this.registry.register(PartClass); return this; }
+    registerParts(classes) { this.registry.registerAll(classes); return this; }
+
+    /** Create a pooled part instance from a spec. */
+    addPart(spec) { return this.registry.add(spec); }
+    addParts(specs) { return specs.map(s => this.addPart(s)); }
+    getPart(id) { return this.registry.get(id); }
+    removePart(id) { return this.registry.remove(id); }
+
+    /* ── Perspectives ───────────────────────────────────────────────────── */
+
+    registerPerspective(name, layoutJson) {
+        this.perspectives.set(name, layoutJson);
+        this._renderPerspectiveButtons();
+        return this;
+    }
+
+    /**
+     * Switch to a named perspective.
+     *
+     * Parts are pooled by id and live for the workspace's lifetime, so a part
+     * the incoming perspective also references is re-parented rather than
+     * rebuilt — it keeps its scroll position, unsaved input and subscriptions.
+     * Parts the incoming perspective doesn't reference are detached, not
+     * destroyed, so switching back restores them intact.
+     *
+     * There is deliberately no legal-transition table: a framework cannot know
+     * a consumer's perspectives. Pass `guard` to veto a switch if you need one.
+     */
+    activatePerspective(name) {
+        const layout = this.perspectives.get(name);
+        if (!layout) throw new Error(`Unknown perspective "${name}"`);
+        const from = this.activePerspective;
+        if (from === name) return true;
+        if (this.guard && this.guard(from, name) === false) return false;
+
+        this.tree?.dispose();
+        this.activePerspective = name;
+        this._renderTree();
+
+        this.dispatchEvent(new CustomEvent('ws-perspective-change', {
+            detail: { from, to: name }, bubbles: true,
+        }));
+        return true;
+    }
+
+    _renderTree() {
+        if (!this._rootEl) return;
+        const layout = this.perspectives.get(this.activePerspective);
+        this._rootEl.textContent = '';
+        this.tree = createLayout(layout);
+        this.tree.render(this._rootEl, this._ctx());
+        this.tree.activate?.();
+        // Parts the new tree doesn't reference are deliberately NOT disposed —
+        // they are merely detached (PartNode.dispose), keeping their DOM and
+        // state. Disposing them would delete them from the pool, so switching
+        // back to the perspective that used them would find them gone. Part
+        // lifetime ends only at removePart()/deserialize().
+        this._renderPerspectiveButtons();
+    }
+
+    _ctx() {
+        return {
+            bus: this.bus,
+            registry: this.registry,
+            workspace: this,
+            onLayoutChange: () => this._onLayoutChange(),
+            ...(this.services ?? {}),
+        };
+    }
+
+    _onLayoutChange() {
+        if (this.activePerspective) {
+            this.perspectives.set(this.activePerspective, this.tree.serialize());
+        }
+        this.dispatchEvent(new CustomEvent('ws-layout-change', {
+            detail: { perspective: this.activePerspective }, bubbles: true,
+        }));
+    }
+
+    _renderPerspectiveButtons() {
+        if (!this._perspectivesEl) return;
+        render(this._perspectivesEl, [...this.perspectives.keys()].map(name => ({
+            tag: 'button',
+            cls: ['ws-perspective-btn', name === this.activePerspective && 'ws-active'],
+            text: name,
+            attrs: { type: 'button' },
+            on: { click: () => this.activatePerspective(name) },
+        })));
+    }
+
+    /* ── Theming ────────────────────────────────────────────────────────── */
+
+    /**
+     * Register a custom-property set under a name. It appears in the toolbar's
+     * theme picker immediately — the picker is built from the registry, so a
+     * consumer theme needs no CSS and no picker change.
+     */
+    registerTheme(name, vars) {
+        this.themes.set(name, vars);
+        this._renderThemePicker();
+        return this;
+    }
+
+    /** Registered theme names, plus the reserved `system` option. */
+    themeNames() { return [SYSTEM_THEME, ...this.themes.keys()]; }
+
+    /**
+     * Apply a theme by name, or `system` to follow the OS setting.
+     *
+     * The previous theme's properties are removed before the new ones are set:
+     * a custom theme may define only some of the vars, and leftovers from the
+     * outgoing theme would otherwise show through as a mismatched palette.
+     */
+    applyTheme(name) {
+        const resolved = name === SYSTEM_THEME ? this._systemTheme() : name;
+        const vars = this.themes.get(resolved);
+        if (!vars && name !== SYSTEM_THEME) return this;
+
+        for (const key of this._appliedVars) this.style.removeProperty(key);
+        this._appliedVars = [];
+        for (const [k, v] of Object.entries(vars ?? {})) {
+            this.style.setProperty(k, v);
+            this._appliedVars.push(k);
+        }
+
+        const previous = this.theme;
+        this.theme = name;                          // the selection ('system' stays 'system')
+        this.setAttribute('data-theme', resolved);  // the resolved name, for consumer CSS hooks
+        this._watchSystemTheme(name === SYSTEM_THEME);
+        if (this._themeSelect) this._themeSelect.value = name;
+
+        if (previous !== name) {
+            this.dispatchEvent(new CustomEvent('ws-theme-change', {
+                detail: { theme: name, resolved }, bubbles: true,
+            }));
+        }
+        return this;
+    }
+
+    _systemTheme() {
+        return globalThis.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+
+    /** Keep `system` live: re-apply when the OS flips between light and dark. */
+    _watchSystemTheme(enabled) {
+        if (enabled && !this._systemThemeQuery) {
+            this._systemThemeQuery = globalThis.matchMedia?.('(prefers-color-scheme: dark)');
+            this._onSystemThemeChange = () => { if (this.theme === SYSTEM_THEME) this.applyTheme(SYSTEM_THEME); };
+            this._systemThemeQuery?.addEventListener('change', this._onSystemThemeChange);
+        } else if (!enabled && this._systemThemeQuery) {
+            this._systemThemeQuery.removeEventListener('change', this._onSystemThemeChange);
+            this._systemThemeQuery = null;
+        }
+    }
+
+    _renderThemePicker() {
+        if (!this._themePickerEl) return;
+        if (this.getAttribute('theme-picker') === 'hidden') {
+            this._themePickerEl.textContent = '';
+            return;
+        }
+        render(this._themePickerEl, [
+            { tag: 'label', text: 'Theme', attrs: { for: 'ws-theme-select' } },
+            {
+                tag: 'select',
+                cls: 'ws-theme-select',
+                attrs: { id: 'ws-theme-select', title: 'Colour theme' },
+                on: { change: e => this.applyTheme(e.target.value) },
+                ref: n => { this._themeSelect = n; n.value = this.theme; },
+                children: this.themeNames().map(name => ({
+                    tag: 'option',
+                    text: name === SYSTEM_THEME ? 'System' : name[0].toUpperCase() + name.slice(1),
+                    attrs: { value: name, selected: name === this.theme },
+                })),
+            },
+        ]);
+    }
+
+    /* ── Persistence ────────────────────────────────────────────────────── */
+
+    serialize() {
+        if (this.tree && this.activePerspective) {
+            this.perspectives.set(this.activePerspective, this.tree.serialize());
+        }
+        return {
+            version: WORKSPACE_SCHEMA_VERSION,
+            theme: this.theme,
+            activePerspective: this.activePerspective,
+            perspectives: Object.fromEntries(this.perspectives),
+            parts: this.registry.serialize(),
+        };
+    }
+
+    /**
+     * Restore a serialized workspace. Part *types* must already be registered —
+     * a saved document carries specs, not code.
+     *
+     * `version` is honoured from day one on purpose: layout schemas change, and
+     * sqlengine's dashboard already had to retrofit exactly this migration once.
+     */
+    deserialize(json, { migrate } = {}) {
+        const doc = migrate ? migrate(json) : json;
+        if (doc.version > WORKSPACE_SCHEMA_VERSION) {
+            throw new Error(`Workspace document version ${doc.version} is newer than this build (${WORKSPACE_SCHEMA_VERSION})`);
+        }
+        this.registry.disposeAll();
+        for (const spec of doc.parts ?? []) {
+            if (spec.adapter) continue; // AdapterPart's mount fn cannot round-trip — re-add it in code
+            this.addPart(spec);
+        }
+        // Only a theme this build actually knows — a document naming one the
+        // consumer no longer registers must not leave the shell unstyled.
+        if (doc.theme && (doc.theme === SYSTEM_THEME || this.themes.has(doc.theme))) {
+            this.applyTheme(doc.theme);
+        }
+        this.perspectives = new Map(Object.entries(doc.perspectives ?? {}));
+        this.activePerspective = null;
+        if (doc.activePerspective && this.perspectives.has(doc.activePerspective)) {
+            this.activatePerspective(doc.activePerspective);
+        }
+        return this;
+    }
+}
+
+export const WORKSPACE_TAG = 'ws-workspace';
+
+/**
+ * Register the element. Custom element names must contain a hyphen, so
+ * `workspace` is not a legal name — `define()` throws SyntaxError on it.
+ * Guarded so importing this module twice does not throw on re-definition.
+ */
+export function defineWorkspace(tag = WORKSPACE_TAG) {
+    if (typeof customElements === 'undefined') return false;
+    if (customElements.get(tag)) return false;
+    customElements.define(tag, Workspace);
+    return true;
+}