@peter.prib/renderengine 0.2.11 → 0.5.0

package/src/workspace/Workspace.js

@@ -1,321 +1,329 @@
-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;
-}
+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() {
+        // Moved, not new (a host re-parents it: a tab dragged to another
+        // group): its layout was disposed when it left (disconnectedCallback),
+        // so it is drawn again — the parts are still in the registry, as they
+        // were. Without this a workspace moved in the page came back empty.
+        if (this._built) {
+            if (!this.tree && this.activePerspective) this._renderTree();
+            this._watchSystemTheme(this.theme === SYSTEM_THEME);
+            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;
+}