@peter.prib/renderengine 0.2.6 → 0.2.10

package/src/workspace/workArea.js

@@ -1,413 +1,417 @@
-/**
- * WorkArea — the IDE-style editor area: several views open at once, in tab
- * groups that can sit side by side.
- *
- * The whole point is the separation the plain `tabs`/`split` layout does not
- * make on its own: a view being OPEN (it has a tab) is not the same as it being
- * VISIBLE (its tab is selected in a group that is on screen). A shell that
- * rebuilds a fixed layout per view can only ever show one; a work area lets you
- * put the data model next to the notebook that queries it.
- *
- * Structure lives in `workAreaModel.js` as pure functions over plain JSON, and
- * this class is the thin rendering shell over them:
- *
- *   model (JSON)  --createLayout-->  live layout tree  --serialize-->  model
- *
- * The live tree is authoritative for the things the user adjusts directly —
- * splitter positions, which tab is selected — so every structural change starts
- * by reading them back out of it (`_syncFromTree`). Rebuilding the subtree
- * afterwards is cheap and non-destructive: `PartNode.dispose()` only detaches a
- * part and `Part.mount()` re-parents it, so a part keeps its DOM, its state and
- * its bus subscriptions across the rebuild.
- *
- * Selecting a tab does NOT rebuild, though — the pane elements are what scroll,
- * and replacing them would throw away scroll position on every tab click.
- */
-import { createLayout } from './layout/index.js';
-import { el } from './dom.js';
-import {
-    emptyWorkArea, listGroups, listOpenParts, findPart,
-    openPart, closePart, focusPart,
-} from './workAreaModel.js';
-
-export class WorkArea {
-    /**
-     * @param {object}   [options]
-     * @param {object}   [options.area]           serialized area to restore
-     * @param {string}   [options.activeGroupId]  group new views open into
-     * @param {Function} [options.onChange]       ({ area, activeGroupId, reason }) — persist here
-     * @param {*}        [options.placeholder]    el() spec shown when nothing is open
-     * @param {Element}  [options.actionsHost]    filled with the focused view's `actions`
-     * @param {Element}  [options.outlineHost]    filled with the focused view's outline part
-     * @param {Function} [options.outlineFor]     (partId) => outline partId | null
-     * @param {*}        [options.outlinePlaceholder] el() spec when a view has no outline
-     * @param {Function} [options.beforeClose]    (partId) => false to keep a tab its close button was
-     *                                            pressed on (unsaved work, say); the handler may close it later
-     */
-    constructor({
-        area, activeGroupId, onChange, placeholder,
-        actionsHost, outlineHost, outlineFor, outlinePlaceholder, beforeClose,
-    } = {}) {
-        this.area = area ?? emptyWorkArea();
-        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
-        this.onChange = onChange ?? null;
-        this.beforeClose = beforeClose ?? null;
-        this.placeholder = placeholder ?? { cls: 'ws-workarea-empty', text: 'Nothing open' };
-        this.host = null;
-        this.ctx = null;
-        this._tree = null;
-        this._outerCtx = null;
-
-        // Frame slots. Both are filled from whichever view has FOCUS, which is
-        // the whole reason they live here: the work area is the only thing that
-        // knows what that is.
-        this.actionsHost = actionsHost ?? null;
-        this.outlineHost = outlineHost ?? null;
-        this.outlineFor = outlineFor ?? null;
-        this.outlinePlaceholder = outlinePlaceholder ?? null;
-        this._outlinePart = null;
-        this._slotPartId = null;
-    }
-
-    /* ── Queries ────────────────────────────────────────────────────────── */
-
-    /** Every open part id, in group order. */
-    openParts() { return listOpenParts(this.area); }
-
-    isOpen(partId) { return !!findPart(this.area, partId); }
-
-    /** The part id selected in each group — i.e. what is actually on screen. */
-    visibleParts() {
-        return listGroups(this.area)
-            .map(g => g.children?.[g.active ?? 0]?.partId)
-            .filter(Boolean);
-    }
-
-    /**
-     * The view with focus: the selected tab of the active group. This is what a
-     * shell keys its chrome off — window title, breadcrumb, which toolbar
-     * belongs to what — and it is not the same as "the last thing opened",
-     * because clicking into another group changes it.
-     */
-    activePart() {
-        const groups = listGroups(this.area);
-        const group = groups.find(g => g.id === this.activeGroupId) ?? groups[0];
-        return group?.children?.[group.active ?? 0]?.partId ?? null;
-    }
-
-    groupCount() { return listGroups(this.area).length; }
-
-    /** `{ area, activeGroupId }` — hand straight to a store, pass back to the ctor. */
-    serialize() {
-        this._syncFromTree();
-        return { area: this.area, activeGroupId: this.activeGroupId };
-    }
-
-    /* ── Rendering ──────────────────────────────────────────────────────── */
-
-    render(host, ctx = {}) {
-        this.host = host;
-        this._outerCtx = ctx;
-        this.ctx = {
-            ...ctx,
-            // Closing and group focus are decisions about the AREA, not about
-            // one tab strip, so they are intercepted here rather than left to
-            // TabsNode's own handling.
-            onTabClose: ({ partId }) => { if (partId && this.beforeClose?.(partId) !== false) this.close(partId); },
-            onGroupFocus: (id) => this._setActiveGroup(id),
-            onLayoutChange: () => this._changed('layout'),
-        };
-        this._build();
-        // Both slots explicitly: nothing has focus yet as far as they are
-        // concerned, so a restored area would otherwise come back with an empty
-        // action bar and an empty rail.
-        this._syncSlots({ actions: true, outline: true });
-        return this;
-    }
-
-    _build() {
-        if (!this.host) return;
-        this._tree?.dispose();
-        this._tree = null;
-        this.host.textContent = '';
-
-        if (!listOpenParts(this.area).length) {
-            if (this.placeholder) this.host.appendChild(el(this.placeholder));
-            return;
-        }
-
-        this._tree = createLayout(this.area);
-        this._tree.render(this.host, this.ctx);
-        this._tree.activate();
-        this._markActiveGroup();
-    }
-
-    /* ── Frame slots ────────────────────────────────────────────────────── */
-
-    /**
-     * Point the action bar and outline rail at whatever now has focus.
-     *
-     * A slot is re-read when focus MOVED, or when the caller asks for that slot
-     * specifically. The two are asked for separately because their costs
-     * differ: re-reading actions is a handful of buttons, whereas re-showing an
-     * outline re-parents an element, which resets its scroll position — so a
-     * `refreshActions()` must not quietly scroll a long tree back to the top.
-     */
-    _syncSlots({ actions = false, outline = false } = {}) {
-        const partId = this.activePart();
-        const moved = partId !== this._slotPartId;
-        if (!moved && !actions && !outline) return;
-        this._slotPartId = partId;
-        if (moved || actions) this._renderActions(partId);
-        if (moved || outline) this._showOutline(partId);
-    }
-
-    _renderActions(partId) {
-        if (!this.actionsHost) return;
-        this.actionsHost.textContent = '';
-        const actions = partId ? (this.ctx?.registry?.get(partId)?.actions ?? []) : [];
-        this.actionsHost.classList.toggle('ws-actionbar-empty', !actions.length);
-        for (const action of actions) {
-            if (!action) continue;
-            // An already-built element is passed straight through. This is the
-            // AdapterPart bargain again: a panel that already has a working
-            // toolbar — with selects, labels and its own rebuild logic — joins
-            // the frame's action bar by handing it over, not by being rewritten
-            // into a button array that could not express it anyway.
-            if (typeof action.nodeType === 'number' || typeof action.appendChild === 'function') {
-                this.actionsHost.appendChild(action);
-                continue;
-            }
-            if (action.separator) { this.actionsHost.appendChild(el({ cls: 'ws-action-sep' })); continue; }
-            this.actionsHost.appendChild(el({
-                tag: 'button',
-                cls: ['ws-action', action.cls],
-                text: action.label ?? '',
-                attrs: {
-                    type: 'button',
-                    title: action.title ?? action.label ?? null,
-                    disabled: action.disabled || null,
-                },
-                on: { click: (e) => action.onClick?.(e, this) },
-            }));
-        }
-    }
-
-    /**
-     * Show the focused view's outline.
-     *
-     * An outline is an ordinary Part, resolved through the registry — not a new
-     * kind of thing. That is what gets it pooling, mount-once-then-re-parent and
-     * lifecycle for free: a tree keeps its expanded nodes and scroll position
-     * while you work in another view and come back.
-     */
-    _showOutline(partId) {
-        if (!this.outlineHost) return;
-        const outlineId = partId && this.outlineFor ? this.outlineFor(partId) : null;
-        const next = outlineId ? this.ctx?.registry?.get(outlineId) : null;
-
-        // Detached by name rather than by clearing the host: the outgoing
-        // outline is a pooled part, and `detach()` is the call that says so.
-        this._outlinePart?.detach();
-        this._outlinePart = null;
-        this._placeholderEl?.remove();
-        this._placeholderEl = null;
-        this.outlineHost.classList.toggle('ws-outline-empty', !next);
-
-        if (!next) {
-            if (this.outlinePlaceholder) {
-                this._placeholderEl = this.outlineHost.appendChild(el(this.outlinePlaceholder));
-            }
-            return;
-        }
-        try {
-            next.mount(this.outlineHost, this.ctx);
-            this._outlinePart = next;
-        } catch (err) {
-            console.error(`WorkArea: outline part "${outlineId}" failed to mount`, err);
-            this.outlineHost.classList.add('ws-outline-empty');
-        }
-    }
-
-    /** Re-read the focused view's actions — call when a panel's state changes. */
-    refreshActions() {
-        this._syncSlots({ actions: true });
-        return this;
-    }
-
-    /**
-     * Re-read both slots. For the case a lazily-mounted view creates the very
-     * things the slots are meant to show *after* it took focus — the action bar
-     * and outline were resolved against a panel that did not exist yet.
-     */
-    refreshSlots() {
-        this._syncSlots({ actions: true, outline: true });
-        return this;
-    }
-
-    /** The outline part currently on show, if any. */
-    get outlinePart() { return this._outlinePart; }
-
-    /**
-     * Read the live tree back into the model. Splitter drags and tab selections
-     * only ever happened to the DOM nodes; skipping this would silently undo
-     * them the next time anything opens or closes.
-     */
-    _syncFromTree() {
-        if (this._tree) this.area = this._tree.serialize();
-        return this.area;
-    }
-
-    /** Show every tab's label as its part's title is now (a file name that changed, say). */
-    refreshLabels() {
-        const walk = (node) => {
-            if (node?.constructor?.type === 'tabs') node.refreshLabels?.();
-            for (const child of node?.children ?? []) walk(child);
-        };
-        if (this._tree) walk(this._tree);
-        return this;
-    }
-
-    /** Live TabsNode for a group id, or null when nothing is rendered. */
-    _liveGroup(groupId) {
-        const walk = (node) => {
-            if (node?.id === groupId && node.constructor?.type === 'tabs') return node;
-            for (const child of node?.children ?? []) {
-                const hit = walk(child);
-                if (hit) return hit;
-            }
-            return null;
-        };
-        return this._tree ? walk(this._tree) : null;
-    }
-
-    /**
-     * Tint the active group's tab strip, but only once there is more than one
-     * group — with a single group "where the next view opens" is not a question
-     * anyone is asking, and the accent would just be noise.
-     */
-    _markActiveGroup() {
-        const many = this.groupCount() > 1;
-        for (const group of listGroups(this.area)) {
-            const live = this._liveGroup(group.id);
-            live?.el?.classList.toggle('ws-group-active', many && group.id === this.activeGroupId);
-        }
-    }
-
-    _setActiveGroup(id) {
-        if (!id || id === this.activeGroupId) return;
-        this.activeGroupId = id;
-        this._markActiveGroup();
-        this._changed('focus-group');
-    }
-
-    _changed(reason) {
-        this._syncFromTree();
-        // Before onChange, so a consumer reacting to the change (updating its
-        // own chrome, persisting) sees a frame that already agrees with focus.
-        this._syncSlots();
-        this.onChange?.({ area: this.area, activeGroupId: this.activeGroupId, reason });
-        this._outerCtx?.onLayoutChange?.();
-    }
-
-    /* ── Commands ───────────────────────────────────────────────────────── */
-
-    /**
-     * Open a view.
-     *
-     * `where`: `'tab'` (default) adds it to the active group; `'right'`,
-     * `'left'`, `'below'` or `'above'` opens a new group beside it — which is
-     * what actually gets two views on screen together.
-     *
-     * Already open anywhere -> focused, not duplicated: a part instance owns one
-     * DOM element, so a second tab for it would necessarily be empty.
-     */
-    open(partId, { where = 'tab' } = {}) {
-        if (!partId) return this;
-        if (this.isOpen(partId)) return this.focus(partId);
-        this._syncFromTree();
-        const next = openPart(this.area, partId, { where, activeGroupId: this.activeGroupId });
-        this.area = next.area;
-        this.activeGroupId = next.activeGroupId;
-        this._build();
-        this._changed('open');
-        return this;
-    }
-
-    /** Open beside the active group — the "split editor" gesture. */
-    openToSide(partId, side = 'right') { return this.open(partId, { where: side }); }
-
-    /**
-     * Select an already-open view. Deliberately does not rebuild: it drives the
-     * live TabsNode, so pane scroll positions and the DOM survive a tab click.
-     */
-    focus(partId) {
-        const found = findPart(this._syncFromTree(), partId);
-        if (!found) return this;
-        const live = this._liveGroup(found.group.id);
-        if (live) {
-            live.select(found.index, true);
-            this.activeGroupId = found.group.id;
-            this._markActiveGroup();
-            this._changed('focus');
-            return this;
-        }
-        const next = focusPart(this.area, partId, { activeGroupId: this.activeGroupId });
-        this.area = next.area;
-        this.activeGroupId = next.activeGroupId;
-        this._build();
-        this._changed('focus');
-        return this;
-    }
-
-    /**
-     * Close a view. Its group disappears when it held the last tab, and a split
-     * left with one child collapses into it — so closing back down to one view
-     * leaves a plain tab strip rather than a split with an empty half.
-     */
-    close(partId) {
-        this._syncFromTree();
-        const next = closePart(this.area, partId, { activeGroupId: this.activeGroupId });
-        if (!next.closed) return this;
-        this.area = next.area;
-        this.activeGroupId = next.activeGroupId;
-        this._build();
-        this._changed('close');
-        return this;
-    }
-
-    /** Close everything, leaving one empty group. */
-    closeAll() {
-        for (const partId of this.openParts()) this.close(partId);
-        return this;
-    }
-
-    /**
-     * Replace the whole area — restoring a saved one, or switching perspective.
-     * Parts the new area does not reference are left in the registry pool, so
-     * switching back finds them as they were.
-     */
-    setArea(area, activeGroupId) {
-        this.area = area ?? emptyWorkArea();
-        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
-        this._build();
-        this._changed('set-area');
-        return this;
-    }
-
-    dispose() {
-        this._tree?.dispose();
-        this._tree = null;
-        // Detached, not disposed — the outline is a pooled part like any other,
-        // and destroying it here would take it out of the registry for good.
-        this._outlinePart?.detach();
-        this._outlinePart = null;
-        this._placeholderEl = null;
-        this._slotPartId = null;
-        if (this.host) this.host.textContent = '';
-        if (this.actionsHost) this.actionsHost.textContent = '';
-        if (this.outlineHost) this.outlineHost.textContent = '';
-        this.host = null;
-        this.ctx = null;
-    }
-}
+/**
+ * WorkArea — the IDE-style editor area: several views open at once, in tab
+ * groups that can sit side by side.
+ *
+ * The whole point is the separation the plain `tabs`/`split` layout does not
+ * make on its own: a view being OPEN (it has a tab) is not the same as it being
+ * VISIBLE (its tab is selected in a group that is on screen). A shell that
+ * rebuilds a fixed layout per view can only ever show one; a work area lets you
+ * put the data model next to the notebook that queries it.
+ *
+ * Structure lives in `workAreaModel.js` as pure functions over plain JSON, and
+ * this class is the thin rendering shell over them:
+ *
+ *   model (JSON)  --createLayout-->  live layout tree  --serialize-->  model
+ *
+ * The live tree is authoritative for the things the user adjusts directly —
+ * splitter positions, which tab is selected — so every structural change starts
+ * by reading them back out of it (`_syncFromTree`). Rebuilding the subtree
+ * afterwards is cheap and non-destructive: `PartNode.dispose()` only detaches a
+ * part and `Part.mount()` re-parents it, so a part keeps its DOM, its state and
+ * its bus subscriptions across the rebuild.
+ *
+ * Selecting a tab does NOT rebuild, though — the pane elements are what scroll,
+ * and replacing them would throw away scroll position on every tab click.
+ */
+import { createLayout } from './layout/index.js';
+import { el } from './dom.js';
+import {
+    emptyWorkArea, listGroups, listOpenParts, findPart,
+    openPart, closePart, focusPart,
+} from './workAreaModel.js';
+
+export class WorkArea {
+    /**
+     * @param {object}   [options]
+     * @param {object}   [options.area]           serialized area to restore
+     * @param {string}   [options.activeGroupId]  group new views open into
+     * @param {Function} [options.onChange]       ({ area, activeGroupId, reason }) — persist here
+     * @param {*}        [options.placeholder]    el() spec shown when nothing is open
+     * @param {Element}  [options.actionsHost]    filled with the focused view's `actions`
+     * @param {Element}  [options.outlineHost]    filled with the focused view's outline part
+     * @param {Function} [options.outlineFor]     (partId) => outline partId | null
+     * @param {*}        [options.outlinePlaceholder] el() spec when a view has no outline
+     * @param {Function} [options.beforeClose]    (partId) => false to keep a tab its close button was
+     *                                            pressed on (unsaved work, say); the handler may close it later
+     * @param {Function} [options.tabMenu]        (partId, event) => true when it showed a menu for that
+     *                                            part's tab (right-clicked); the browser's own shows otherwise
+     */
+    constructor({
+        area, activeGroupId, onChange, placeholder,
+        actionsHost, outlineHost, outlineFor, outlinePlaceholder, beforeClose, tabMenu,
+    } = {}) {
+        this.area = area ?? emptyWorkArea();
+        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
+        this.onChange = onChange ?? null;
+        this.beforeClose = beforeClose ?? null;
+        this.tabMenu = tabMenu ?? null;
+        this.placeholder = placeholder ?? { cls: 'ws-workarea-empty', text: 'Nothing open' };
+        this.host = null;
+        this.ctx = null;
+        this._tree = null;
+        this._outerCtx = null;
+
+        // Frame slots. Both are filled from whichever view has FOCUS, which is
+        // the whole reason they live here: the work area is the only thing that
+        // knows what that is.
+        this.actionsHost = actionsHost ?? null;
+        this.outlineHost = outlineHost ?? null;
+        this.outlineFor = outlineFor ?? null;
+        this.outlinePlaceholder = outlinePlaceholder ?? null;
+        this._outlinePart = null;
+        this._slotPartId = null;
+    }
+
+    /* ── Queries ────────────────────────────────────────────────────────── */
+
+    /** Every open part id, in group order. */
+    openParts() { return listOpenParts(this.area); }
+
+    isOpen(partId) { return !!findPart(this.area, partId); }
+
+    /** The part id selected in each group — i.e. what is actually on screen. */
+    visibleParts() {
+        return listGroups(this.area)
+            .map(g => g.children?.[g.active ?? 0]?.partId)
+            .filter(Boolean);
+    }
+
+    /**
+     * The view with focus: the selected tab of the active group. This is what a
+     * shell keys its chrome off — window title, breadcrumb, which toolbar
+     * belongs to what — and it is not the same as "the last thing opened",
+     * because clicking into another group changes it.
+     */
+    activePart() {
+        const groups = listGroups(this.area);
+        const group = groups.find(g => g.id === this.activeGroupId) ?? groups[0];
+        return group?.children?.[group.active ?? 0]?.partId ?? null;
+    }
+
+    groupCount() { return listGroups(this.area).length; }
+
+    /** `{ area, activeGroupId }` — hand straight to a store, pass back to the ctor. */
+    serialize() {
+        this._syncFromTree();
+        return { area: this.area, activeGroupId: this.activeGroupId };
+    }
+
+    /* ── Rendering ──────────────────────────────────────────────────────── */
+
+    render(host, ctx = {}) {
+        this.host = host;
+        this._outerCtx = ctx;
+        this.ctx = {
+            ...ctx,
+            // Closing and group focus are decisions about the AREA, not about
+            // one tab strip, so they are intercepted here rather than left to
+            // TabsNode's own handling.
+            onTabClose: ({ partId }) => { if (partId && this.beforeClose?.(partId) !== false) this.close(partId); },
+            onTabMenu: ({ partId, event }) => !!(partId && this.tabMenu?.(partId, event)),
+            onGroupFocus: (id) => this._setActiveGroup(id),
+            onLayoutChange: () => this._changed('layout'),
+        };
+        this._build();
+        // Both slots explicitly: nothing has focus yet as far as they are
+        // concerned, so a restored area would otherwise come back with an empty
+        // action bar and an empty rail.
+        this._syncSlots({ actions: true, outline: true });
+        return this;
+    }
+
+    _build() {
+        if (!this.host) return;
+        this._tree?.dispose();
+        this._tree = null;
+        this.host.textContent = '';
+
+        if (!listOpenParts(this.area).length) {
+            if (this.placeholder) this.host.appendChild(el(this.placeholder));
+            return;
+        }
+
+        this._tree = createLayout(this.area);
+        this._tree.render(this.host, this.ctx);
+        this._tree.activate();
+        this._markActiveGroup();
+    }
+
+    /* ── Frame slots ────────────────────────────────────────────────────── */
+
+    /**
+     * Point the action bar and outline rail at whatever now has focus.
+     *
+     * A slot is re-read when focus MOVED, or when the caller asks for that slot
+     * specifically. The two are asked for separately because their costs
+     * differ: re-reading actions is a handful of buttons, whereas re-showing an
+     * outline re-parents an element, which resets its scroll position — so a
+     * `refreshActions()` must not quietly scroll a long tree back to the top.
+     */
+    _syncSlots({ actions = false, outline = false } = {}) {
+        const partId = this.activePart();
+        const moved = partId !== this._slotPartId;
+        if (!moved && !actions && !outline) return;
+        this._slotPartId = partId;
+        if (moved || actions) this._renderActions(partId);
+        if (moved || outline) this._showOutline(partId);
+    }
+
+    _renderActions(partId) {
+        if (!this.actionsHost) return;
+        this.actionsHost.textContent = '';
+        const actions = partId ? (this.ctx?.registry?.get(partId)?.actions ?? []) : [];
+        this.actionsHost.classList.toggle('ws-actionbar-empty', !actions.length);
+        for (const action of actions) {
+            if (!action) continue;
+            // An already-built element is passed straight through. This is the
+            // AdapterPart bargain again: a panel that already has a working
+            // toolbar — with selects, labels and its own rebuild logic — joins
+            // the frame's action bar by handing it over, not by being rewritten
+            // into a button array that could not express it anyway.
+            if (typeof action.nodeType === 'number' || typeof action.appendChild === 'function') {
+                this.actionsHost.appendChild(action);
+                continue;
+            }
+            if (action.separator) { this.actionsHost.appendChild(el({ cls: 'ws-action-sep' })); continue; }
+            this.actionsHost.appendChild(el({
+                tag: 'button',
+                cls: ['ws-action', action.cls],
+                text: action.label ?? '',
+                attrs: {
+                    type: 'button',
+                    title: action.title ?? action.label ?? null,
+                    disabled: action.disabled || null,
+                },
+                on: { click: (e) => action.onClick?.(e, this) },
+            }));
+        }
+    }
+
+    /**
+     * Show the focused view's outline.
+     *
+     * An outline is an ordinary Part, resolved through the registry — not a new
+     * kind of thing. That is what gets it pooling, mount-once-then-re-parent and
+     * lifecycle for free: a tree keeps its expanded nodes and scroll position
+     * while you work in another view and come back.
+     */
+    _showOutline(partId) {
+        if (!this.outlineHost) return;
+        const outlineId = partId && this.outlineFor ? this.outlineFor(partId) : null;
+        const next = outlineId ? this.ctx?.registry?.get(outlineId) : null;
+
+        // Detached by name rather than by clearing the host: the outgoing
+        // outline is a pooled part, and `detach()` is the call that says so.
+        this._outlinePart?.detach();
+        this._outlinePart = null;
+        this._placeholderEl?.remove();
+        this._placeholderEl = null;
+        this.outlineHost.classList.toggle('ws-outline-empty', !next);
+
+        if (!next) {
+            if (this.outlinePlaceholder) {
+                this._placeholderEl = this.outlineHost.appendChild(el(this.outlinePlaceholder));
+            }
+            return;
+        }
+        try {
+            next.mount(this.outlineHost, this.ctx);
+            this._outlinePart = next;
+        } catch (err) {
+            console.error(`WorkArea: outline part "${outlineId}" failed to mount`, err);
+            this.outlineHost.classList.add('ws-outline-empty');
+        }
+    }
+
+    /** Re-read the focused view's actions — call when a panel's state changes. */
+    refreshActions() {
+        this._syncSlots({ actions: true });
+        return this;
+    }
+
+    /**
+     * Re-read both slots. For the case a lazily-mounted view creates the very
+     * things the slots are meant to show *after* it took focus — the action bar
+     * and outline were resolved against a panel that did not exist yet.
+     */
+    refreshSlots() {
+        this._syncSlots({ actions: true, outline: true });
+        return this;
+    }
+
+    /** The outline part currently on show, if any. */
+    get outlinePart() { return this._outlinePart; }
+
+    /**
+     * Read the live tree back into the model. Splitter drags and tab selections
+     * only ever happened to the DOM nodes; skipping this would silently undo
+     * them the next time anything opens or closes.
+     */
+    _syncFromTree() {
+        if (this._tree) this.area = this._tree.serialize();
+        return this.area;
+    }
+
+    /** Show every tab's label as its part's title is now (a file name that changed, say). */
+    refreshLabels() {
+        const walk = (node) => {
+            if (node?.constructor?.type === 'tabs') node.refreshLabels?.();
+            for (const child of node?.children ?? []) walk(child);
+        };
+        if (this._tree) walk(this._tree);
+        return this;
+    }
+
+    /** Live TabsNode for a group id, or null when nothing is rendered. */
+    _liveGroup(groupId) {
+        const walk = (node) => {
+            if (node?.id === groupId && node.constructor?.type === 'tabs') return node;
+            for (const child of node?.children ?? []) {
+                const hit = walk(child);
+                if (hit) return hit;
+            }
+            return null;
+        };
+        return this._tree ? walk(this._tree) : null;
+    }
+
+    /**
+     * Tint the active group's tab strip, but only once there is more than one
+     * group — with a single group "where the next view opens" is not a question
+     * anyone is asking, and the accent would just be noise.
+     */
+    _markActiveGroup() {
+        const many = this.groupCount() > 1;
+        for (const group of listGroups(this.area)) {
+            const live = this._liveGroup(group.id);
+            live?.el?.classList.toggle('ws-group-active', many && group.id === this.activeGroupId);
+        }
+    }
+
+    _setActiveGroup(id) {
+        if (!id || id === this.activeGroupId) return;
+        this.activeGroupId = id;
+        this._markActiveGroup();
+        this._changed('focus-group');
+    }
+
+    _changed(reason) {
+        this._syncFromTree();
+        // Before onChange, so a consumer reacting to the change (updating its
+        // own chrome, persisting) sees a frame that already agrees with focus.
+        this._syncSlots();
+        this.onChange?.({ area: this.area, activeGroupId: this.activeGroupId, reason });
+        this._outerCtx?.onLayoutChange?.();
+    }
+
+    /* ── Commands ───────────────────────────────────────────────────────── */
+
+    /**
+     * Open a view.
+     *
+     * `where`: `'tab'` (default) adds it to the active group; `'right'`,
+     * `'left'`, `'below'` or `'above'` opens a new group beside it — which is
+     * what actually gets two views on screen together.
+     *
+     * Already open anywhere -> focused, not duplicated: a part instance owns one
+     * DOM element, so a second tab for it would necessarily be empty.
+     */
+    open(partId, { where = 'tab' } = {}) {
+        if (!partId) return this;
+        if (this.isOpen(partId)) return this.focus(partId);
+        this._syncFromTree();
+        const next = openPart(this.area, partId, { where, activeGroupId: this.activeGroupId });
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('open');
+        return this;
+    }
+
+    /** Open beside the active group — the "split editor" gesture. */
+    openToSide(partId, side = 'right') { return this.open(partId, { where: side }); }
+
+    /**
+     * Select an already-open view. Deliberately does not rebuild: it drives the
+     * live TabsNode, so pane scroll positions and the DOM survive a tab click.
+     */
+    focus(partId) {
+        const found = findPart(this._syncFromTree(), partId);
+        if (!found) return this;
+        const live = this._liveGroup(found.group.id);
+        if (live) {
+            live.select(found.index, true);
+            this.activeGroupId = found.group.id;
+            this._markActiveGroup();
+            this._changed('focus');
+            return this;
+        }
+        const next = focusPart(this.area, partId, { activeGroupId: this.activeGroupId });
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('focus');
+        return this;
+    }
+
+    /**
+     * Close a view. Its group disappears when it held the last tab, and a split
+     * left with one child collapses into it — so closing back down to one view
+     * leaves a plain tab strip rather than a split with an empty half.
+     */
+    close(partId) {
+        this._syncFromTree();
+        const next = closePart(this.area, partId, { activeGroupId: this.activeGroupId });
+        if (!next.closed) return this;
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('close');
+        return this;
+    }
+
+    /** Close everything, leaving one empty group. */
+    closeAll() {
+        for (const partId of this.openParts()) this.close(partId);
+        return this;
+    }
+
+    /**
+     * Replace the whole area — restoring a saved one, or switching perspective.
+     * Parts the new area does not reference are left in the registry pool, so
+     * switching back finds them as they were.
+     */
+    setArea(area, activeGroupId) {
+        this.area = area ?? emptyWorkArea();
+        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
+        this._build();
+        this._changed('set-area');
+        return this;
+    }
+
+    dispose() {
+        this._tree?.dispose();
+        this._tree = null;
+        // Detached, not disposed — the outline is a pooled part like any other,
+        // and destroying it here would take it out of the registry for good.
+        this._outlinePart?.detach();
+        this._outlinePart = null;
+        this._placeholderEl = null;
+        this._slotPartId = null;
+        if (this.host) this.host.textContent = '';
+        if (this.actionsHost) this.actionsHost.textContent = '';
+        if (this.outlineHost) this.outlineHost.textContent = '';
+        this.host = null;
+        this.ctx = null;
+    }
+}