flexdesk 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.3.0",
+    "version": "0.4.1",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/tiling/shell.js

@@ -44,6 +44,7 @@ import { createContentRegistry } from './content_registry.js';
 import { createCommandPalette } from './command_palette.js';
 import { installKeymap } from './keymap.js';
 import { openTileTabSwitcher } from './tile_tab_menu.js';
+import { mountZoomControl } from './zoom.js';
 import { showContextMenu } from '../ui/components/context_menu.js';
 import { openForm } from '../ui/components/modal.js';
 
@@ -85,6 +86,11 @@ import { openForm } from '../ui/components/modal.js';
  *                                      window onto a tile puts it back in the
  *                                      tree. Default off — it changes what a
  *                                      drag to an edge does.
+ * @param {boolean}    [cfg.backToOpenList] C32. Whether Backspace on a record
+ *                                      tab closes it and returns to a list of
+ *                                      its section that is already open, rather
+ *                                      than rewriting it into a second copy of
+ *                                      that list. Default off.
  * @param {'top'|'bottom'} [cfg.tabLayout] C22. Where a multi-tab leaf draws its
  *                                      tabs. `'bottom'` is the framework's own
  *                                      spreadsheet strip under the tile body
@@ -97,7 +103,12 @@ import { openForm } from '../ui/components/modal.js';
  *                                      embedder whose settings pane holds only
  *                                      the root element can change it live.
  * @param {object}     [cfg.chrome]     { topNav?, paletteButton?, desktops?,
- *                                        panelToggles?: { left?, right?, bottom? } }
+ *                                        panelToggles?: { left?, right?, bottom? },
+ *                                        zoom? }
+ *                                      `zoom` is C31: the element the content
+ *                                      zoom control is painted into — see
+ *                                      zoom.js. Absent, there is no control and
+ *                                      nothing is ever scaled.
  * @returns {Promise<object>} the frozen shell
  */
 export async function createShell({
@@ -116,6 +127,7 @@ export async function createShell({
     panels = null,
     snapPromotion = false,
     promoteInPlace = false,
+    backToOpenList = false,
     tabLayout = null,
     chrome = {},
     // An embedder that moved its sections out of the top bar — into an icon
@@ -157,6 +169,7 @@ export async function createShell({
         panelDefaults: panels,
         snapPromotion,
         promoteInPlace,
+        backToOpenList,
         tabLayout,
         // `ctx` is the delivery vehicle for leaf-mounted chrome: tile_renderer
         // spreads it into every content factory, which is how the breadcrumb
@@ -185,6 +198,13 @@ export async function createShell({
     const paletteBtn = mountPaletteButton(chrome.paletteButton, palette);
     topNavEl = mountTopNav(chrome.topNav, taxonomy, wm);
     desktopsEl = mountDesktopBar(chrome.desktops, wm);
+    // C31. The content zoom. Painted with the rest of the chrome and, unlike the
+    // rest, AWAITED before the first mount: its saved value is applied to `root`
+    // as a CSS variable, and a shell that mounted first would paint every tile at
+    // 100% and then visibly jump to the user's zoom a moment later. A host with no
+    // saved zoom — or no `state` at all — resolves immediately to the default.
+    const zoom = mountZoomControl(chrome.zoom, { root, host });
+    if (zoom) await zoom.ready;
     // NOTE: bindPanelToggles CLONES the buttons (to strip whatever state the
     // embedder's own machinery left on them) and returns the FRESH nodes. The
     // originals are detached from here on — sync against the returned map, not
@@ -211,6 +231,9 @@ export async function createShell({
             topNavEl,
             desktopsEl,
             panelToggles: toggles,
+            // `get`/`set` so an embedder can drive the zoom from its own settings
+            // pane, or read it, without reaching into the control's DOM.
+            zoom,
         }),
         // A shell that can be built can be built TWICE — an embedder that
         // rebuilds on a context change (a different project, a different
@@ -229,6 +252,10 @@ export async function createShell({
             // captured before a rebuild, a promise that has not settled —
             // cannot repaint a dead tree into a root the live shell now owns.
             try { wm.renderer.destroy(); } catch (err) { log.warn?.('renderer teardown', err); }
+            // The zoom lives on `root` as a variable and a class. A rebuilt shell on
+            // the same root must not inherit the old one's scale with no control on
+            // screen to change it, so dispose puts the root back to 100%.
+            try { zoom?.dispose(); } catch { /* ignore */ }
         },
     });
 }

package/src/tiling/tile_tree.js

@@ -298,15 +298,27 @@ export class TileTree {
             }));
             n.activeTabIdx = Math.max(0,
                 Math.min(n.tabs.length - 1, saved.activeTabIdx || 0));
-            // The caller asked for a specific entity (props.id) OR for a
-            // page kind that ISN'T the nav category itself (e.g. `settings`
-            // lives under the `home` topNav). In both cases we must surface
-            // the requested target rather than silently showing whatever
-            // the restored page happened to hold. A bare top-nav click
-            // (target.kind === targetTopNav, no id) falls through and just
-            // restores the saved tabs as-is.
+            // The caller asked for a specific entity (props.id), for a page
+            // kind that ISN'T the nav category itself (e.g. `settings` lives
+            // under the `home` topNav), or for this page WITH PARTICULAR PROPS
+            // (a filter, an ad-hoc expression). In all three we must surface the
+            // requested target rather than silently showing whatever the
+            // restored page happened to hold.
+            //
+            // THE THIRD CASE WAS MISSING, and it is not a corner: "show me
+            // everything open on bo" is `kind: 'backlog'` with an `expr` and no
+            // id — no entity, and `backlog` IS its own nav category — so it fell
+            // through to the bare-restore branch and put back whatever the page
+            // last held. If that was a record you had been reading, the tile did
+            // not visibly change at all, and the click looked broken. (Found and
+            // fixed in BugDesk's fork first; this is that fix, upstream.)
+            //
+            // A BARE page switch still restores as-is, which is the whole point
+            // of archiving tabs: clicking a top-nav chip carries no props and
+            // must put back the tab you left open.
             const wantsTarget = target.props?.id != null
-                             || target.kind !== targetTopNav;
+                             || target.kind !== targetTopNav
+                             || Object.keys(target.props || {}).length > 0;
             if (wantsTarget) {
                 const wantId = target.props?.id != null;
                 const matchIdx = n.tabs.findIndex((t) =>
@@ -489,9 +501,19 @@ export class TileTree {
         };
         n.tabs = Array.isArray(n.tabs) ? n.tabs : [];
         n.tabs.push(tab);
-        n.activeTabIdx = n.tabs.length - 1;
-        _syncActiveTab(n);
-        return n.activeTabIdx;
+        // `background` appends WITHOUT switching to it — the caller asked for a
+        // tab to come back to, not for the page to change under them. Without
+        // this, "open in a background tab" was indistinguishable from an
+        // ordinary click: the tab arrived and took the screen with it.
+        //
+        // Returns the new tab's index either way, NOT `activeTabIdx`: for a
+        // background tab those differ, and a caller that wants to address the
+        // tab it just made needs the index of that tab.
+        if (!opts.background) {
+            n.activeTabIdx = n.tabs.length - 1;
+            _syncActiveTab(n);
+        }
+        return n.tabs.length - 1;
     }
 
     /** Switch the active tab on a leaf. No-op if `idx` is out of range. */

package/src/tiling/wm.js

@@ -34,7 +34,7 @@ const PANEL_TITLES = {
 export class WindowManager {
     constructor({ rootEl, api, ctx, onChange, eventBus, host, taxonomy, events, content,
                   panelDefaults = null, snapPromotion = false,
-                  promoteInPlace = false, tabLayout = null }) {
+                  promoteInPlace = false, tabLayout = null, backToOpenList = false }) {
         if (!taxonomy) throw new Error('WindowManager: a taxonomy is required');
         if (!content || typeof content.mount !== 'function') {
             throw new Error('WindowManager: a content registry is required '
@@ -83,6 +83,12 @@ export class WindowManager {
          *  changes where a promoted window can be dragged, and an existing
          *  embedder upgrading must not find its windows suddenly clipped. */
         this.promoteInPlace = !!promoteInPlace;
+        /** C32. Whether Backspace on an ENTITY tab closes it and returns to a list
+         *  that is already open, instead of turning the tab into a second copy of
+         *  that list. See `_backToOpenList`. Default off: it changes what the key
+         *  does, and an existing embedder upgrading must not find tabs closing
+         *  where they used to navigate. */
+        this.backToOpenList = !!backToOpenList;
         this._snapCtl = null;
         this.desktops = new DesktopManager({
             seed: this._rootLeaf, panelDefaults: this.panelDefaults });
@@ -285,7 +291,10 @@ export class WindowManager {
             this._notifyChange('navigate-back');
             return;
         }
-        // (2) Taxonomy fallback — the user's path is gone, so walk the
+        // (2) C32. An entity tab with nowhere left to go back to, beside a list
+        // of its own section that is already open: close it and land there.
+        if (this.backToOpenList && this._backToOpenList(id)) return;
+        // (3) Taxonomy fallback — the user's path is gone, so walk the
         // canonical parent instead. An ENTITY-level parent wins (the
         // instance one level up, e.g. the parent an id names); failing
         // that, the KIND-level parent (this page's section).
@@ -347,6 +356,68 @@ export class WindowManager {
     /** Navigate inside the current tab — preserves every other tab in
      *  the leaf. Used by Backspace + breadcrumb segments + anything
      *  else that should walk WITHIN the tile rather than reset it. */
+    /**
+     * C32. BACK FROM AN OPENED RECORD RETURNS TO THE LIST, IT DOES NOT MAKE ONE.
+     *
+     * The gesture this is for: a list tab, a record opened from it into a NEW
+     * tab, and Backspace in that record. With nothing left in the record tab's
+     * own history, step (3) of `navigateBack` walks the taxonomy up and REWRITES
+     * the record tab into its parent — so the tile ends up showing the list
+     * twice, once in the tab you started from and once in the tab you just left.
+     * The user's model is a browser's: you came from the list, the list is still
+     * open, so going back means closing this and being on the list again.
+     *
+     * So: when the active tab is an ENTITY — its props carry an `id`, the same
+     * test `swapToPage` uses for "the caller asked for a specific entity" — look
+     * for an open tab of the SAME section that is NOT one. That is the list or
+     * landing page the record belongs to. Close the record and activate it.
+     *
+     * NEAREST TO THE LEFT FIRST. New tabs are appended at the end, so the tab a
+     * record was opened from sits to its left; when several lists of the section
+     * are open, the nearest one on that side is the one it most plausibly came
+     * from. The right side is searched only after the left has nothing.
+     *
+     * DECLINES, and leaves step (3) to walk up in place, whenever there is no
+     * such tab: a record that is the tile's only tab, or one whose section has no
+     * list open. That keeps the one guarantee the whole rule exists for — Back
+     * never leaves two copies of a list — without ever closing a record into a
+     * tile that has nothing of its own to show.
+     *
+     * Matching is by SECTION (`topNavFor`) and not by kind, because the list a
+     * record was opened from is often not the record's taxonomy parent: a root
+     * landing page that renders the section, or a list that a flattened taxonomy
+     * files beside the record rather than above it.
+     *
+     * @returns {boolean} whether it closed a tab
+     */
+    _backToOpenList(leafId) {
+        const tree = this._tree();
+        const leaf = tree.get(leafId);
+        if (!leaf || leaf.kind !== 'leaf') return false;
+        const tabs = Array.isArray(leaf.tabs) ? leaf.tabs : [];
+        if (tabs.length < 2) return false;
+        const activeIdx = Math.max(0, Math.min(tabs.length - 1, leaf.activeTabIdx || 0));
+        const active = tabs[activeIdx];
+        if (!_isEntityTab(active)) return false;
+        const section = this.taxonomy.topNavFor(active.kind);
+        if (!section) return false;
+
+        const isList = (t) => t && !_isEntityTab(t) && this.taxonomy.topNavFor(t.kind) === section;
+        let target = -1;
+        for (let i = activeIdx - 1; i >= 0 && target < 0; i--) if (isList(tabs[i])) target = i;
+        for (let i = activeIdx + 1; i < tabs.length && target < 0; i++) if (isList(tabs[i])) target = i;
+        if (target < 0) return false;
+
+        tree.removeLeafTab(leafId, activeIdx);
+        // Removing the active tab shifts everything after it one to the left.
+        tree.setActiveLeafTab(leafId, target > activeIdx ? target - 1 : target);
+        tree.focus(leafId);
+        this.renderer.render();
+        this._persist();
+        this._notifyChange('navigate-back-close');
+        return true;
+    }
+
     navigateActiveTab(leafId, kind, props = {}) {
         const tree = this._tree();
         const leaf = tree.get(leafId);
@@ -3279,6 +3350,11 @@ export class WindowManager {
      *  `opts.transient` — the appended tab is not persisted/restored
      *                     (e.g. an add-row form). Only meaningful with
      *                     `newTab:true`.
+     *  `opts.background` — with `newTab`, append the tab WITHOUT switching to
+     *                     it or focusing its tile. "Open in a background tab"
+     *                     means the page you are reading stays in front;
+     *                     without it the tab arrives and takes the screen,
+     *                     which is what an ordinary click already does.
      *
      *  Back-compat: the legacy `opts.target` enum still works and maps
      *  onto the axes — 'auto'→origin, 'tab'→origin+newTab,
@@ -3289,6 +3365,8 @@ export class WindowManager {
      *  `openInWindow`) stay internal; callers prefer `wm.navigate(...)`. */
     navigate(kind, props = {}, opts = {}) {
         const { ctx = null, transient = false } = opts;
+        // Append the tab but stay where you are. Only meaningful with `newTab`.
+        const background = !!opts.background;
         // Resolve the two axes, honoring the legacy `target` alias.
         let { dest = 'main', newTab = false } = opts;
         if (opts.target != null) {
@@ -3314,12 +3392,12 @@ export class WindowManager {
         if (dest === 'window') return this._navigateWindow(kind, props);
         if (dest === 'main') {
             return newTab
-                ? this.openInTabInPrimary(kind, props, transient)
+                ? this.openInTabInPrimary(kind, props, transient, background)
                 : this.openInPrimary(kind, props);
         }
         // dest === 'origin'
         return newTab
-            ? this._navigateTab(ctx, kind, props, transient)
+            ? this._navigateTab(ctx, kind, props, transient, background)
             : this._navigateAuto(ctx, kind, props);
     }
 
@@ -3346,14 +3424,14 @@ export class WindowManager {
         this.openInPrimary(kind, props);
     }
 
-    _navigateTab(ctx, kind, props, transient = false) {
+    _navigateTab(ctx, kind, props, transient = false, background = false) {
         // Windows aren't tabbed — "open in tab" inside a window just
         // replaces the window's content.
         if (ctx?.windowId && this._windowToLeaf.has(ctx.windowId)) {
             this.openInWindow(ctx.windowId, kind, props);
             return;
         }
-        this.openInTabFromContext(ctx || {}, kind, props, transient);
+        this.openInTabFromContext(ctx || {}, kind, props, transient, background);
     }
 
     /** Spawn a fresh ManagedWindow with the requested content. No
@@ -3486,7 +3564,7 @@ export class WindowManager {
      *  Mirrors `openFromContext` (windowed / split-leaf / primary
      *  routing) but uses `appendLeafTab` so the existing content
      *  stays in place as a tab. */
-    openInTabFromContext(ctx, kind, props = {}, transient = false) {
+    openInTabFromContext(ctx, kind, props = {}, transient = false, background = false) {
         // Managed-window content: just open in the window — managed
         // windows aren't tabbed (one window = one content).
         if (ctx?.windowId && this._windowToLeaf.has(ctx.windowId)) {
@@ -3504,8 +3582,11 @@ export class WindowManager {
             this.openInPrimary(kind, props);
             return;
         }
-        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props), { transient });
-        tree.focus(leafId);
+        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props),
+            { transient, background });
+        // A BACKGROUND tab must not steal the tile's focus either — the point
+        // is that the user stays exactly where they were.
+        if (!background) tree.focus(leafId);
         this.renderer.render();
         this._persist();
         this._notifyChange('tab-open');
@@ -3518,7 +3599,7 @@ export class WindowManager {
      *  click from outside the tile system (e.g. the bottom-panel
      *  "Add row" button, which passes no ctx) reliably lands as a sibling
      *  tab in the main tile rather than swapping its content. */
-    openInTabInPrimary(kind, props = {}, transient = false) {
+    openInTabInPrimary(kind, props = {}, transient = false, background = false) {
         const tree = this._tree();
         const leafId = tree.primaryLeafId();
         // No content tile on this desktop (e.g. a panels-only layout) —
@@ -3526,8 +3607,11 @@ export class WindowManager {
         // caller asked for "a tab in the main tile"; with no main tile to
         // tab into, a floating window is the least-surprising fallback.
         if (!leafId) { this._navigateWindow(kind, props); return; }
-        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props), { transient });
-        tree.focus(leafId);
+        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props),
+            { transient, background });
+        // A BACKGROUND tab must not steal the tile's focus either — the point
+        // is that the user stays exactly where they were.
+        if (!background) tree.focus(leafId);
         this.renderer.render();
         this._persist();
         this._notifyChange('tab-open');
@@ -3628,3 +3712,8 @@ function _swapSiblings(tree, aId, bId) {
     return true;
 }
 
+/** A tab showing ONE record rather than a list: its props name an `id`. The same
+ *  test `swapToPage` applies to "the caller asked for a specific entity". */
+function _isEntityTab(tab) {
+    return !!tab && tab.props != null && tab.props.id != null && tab.props.id !== '';
+}

package/src/tiling/zoom.js

@@ -0,0 +1,248 @@
+/**
+ * zoom.js — the shell's content zoom: a − / track / + / readout control, and
+ * the one place that decides what "zoom the workspace" is allowed to touch.
+ *
+ * Opt-in, like every shell feature that changes what the user sees: an embedder
+ * that passes no `chrome.zoom` element gets no control and no scaling, so no
+ * existing consumer changes by upgrading. The control is Excel's — a continuous
+ * track with a detent-free middle, buttons either side that move in tens, and a
+ * readout that is itself the reset — because that is the shape people already
+ * know, and it is the one Tables shipped in its own status bar before this was
+ * lifted into the framework.
+ *
+ * ── WHAT IT SCALES, AND WHAT IT MUST NOT ───────────────────────────────────
+ *
+ * It scales CONTENT SURFACES and nothing a window is dragged across:
+ *
+ *     .twm-leaf__body          what a tile's content factory mounted into
+ *     .twm-window-content      what a promoted window's content mounted into
+ *
+ * and it does NOT scale the root, a leaf wrap, tile chrome, tab bars, or a
+ * window frame. That line is load-bearing rather than a matter of taste. CSS
+ * `zoom` establishes a scaled coordinate space, and FlexDesk's window drag,
+ * resize and snap all do arithmetic between the pointer (viewport pixels) and a
+ * window's `left`/`top` (the pixels of whatever contains it). A contained window
+ * (C21) lives in a LEAF WRAP and is re-parented to the ROOT for the length of a
+ * drag (R1); zoom either of those and every drag drifts by the zoom factor, and
+ * every C15 snap probe measures a tile in units the pointer is not in. Tile
+ * bodies and window content sit BELOW all of that geometry, so scaling them
+ * changes the text and none of the maths.
+ *
+ * ── HOW IT IS APPLIED ─────────────────────────────────────────────────────
+ *
+ * A CSS variable and a class, both on `root` — the element the embedder handed
+ * the shell. Never `document.body`, never a selector the framework did not
+ * author (the doctrine at the top of shell.js). Tiles and windows are created
+ * and destroyed long after any given change, so anything written element by
+ * element would have to be re-applied on every mount; a variable on the root is
+ * read by whatever exists at the time.
+ *
+ * The class is what keeps 100% free of any declaration. A rule that always said
+ * `zoom: var(--twm-zoom, 1)` would establish a scaled coordinate space even at
+ * 1, so at the default the class comes off and no `zoom` applies anywhere — an
+ * unzoomed shell lays out byte-for-byte as it did before this existed.
+ *
+ * A window an embedder mounts on `document.body` itself is outside the shell's
+ * root and therefore outside this: it is not the shell's to scale. Every window
+ * the WM promotes under `promoteInPlace` (C21) is inside the root, and so is
+ * every window for the duration of a drag.
+ *
+ * ── `zoom`, NOT `transform: scale()` ──────────────────────────────────────
+ *
+ * `zoom` reflows: text stays on the pixel grid, and a scroll container still
+ * measures the content it is scrolling. A transform would blur the text and
+ * leave the layout box at its old size, so a zoomed-in table would overflow a
+ * pane that did not know it had grown.
+ */
+
+/** The range. Below 50% a data row stops being readable; above 200% a typical
+ *  row no longer fits its own columns. */
+export const ZOOM_MIN = 50;
+export const ZOOM_MAX = 200;
+
+/** The track's granularity — fine, because a control you have to aim is one
+ *  people stop using. */
+export const ZOOM_STEP = 5;
+
+/** The BUTTONS' step: Excel's split, where the track is continuous and the − / +
+ *  cover ground. Commensurate with ZOOM_STEP by construction, so a button press
+ *  always lands on a notch and repeated presses cannot drift. */
+export const ZOOM_NUDGE = 10;
+
+/**
+ * Where the shell opens, and where a reset returns. Load-bearing: `applyZoom`
+ * removes the class at exactly this value, and that is what makes "unzoomed"
+ * mean "no declaration at all". Only true while the default IS 100.
+ */
+export const ZOOM_DEFAULT = 100;
+
+/** The logical key under the host's `state` capability. A per-person display
+ *  preference, persisted the same way the desktops are. */
+export const ZOOM_STATE_KEY = 'zoom';
+
+/**
+ * A number from anywhere — a slider, a stored preference, a caller — as a zoom
+ * the shell will accept.
+ *
+ * `null`, `undefined` and `''` are "no value" and read as the default. They are
+ * checked BEFORE the cast because `Number()` turns both `null` and `''` into 0 —
+ * a perfectly finite number that would then clamp to the floor, so a host with
+ * no saved zoom, or a read that failed, would silently open the shell at 50%.
+ *
+ * It QUANTISES, which is what makes 100% reachable: the track is stepped, so a
+ * stored 97 has to land on a notch rather than sit between two where neither the
+ * track nor the buttons can leave it.
+ */
+export function clampZoom(value) {
+    if (value == null || value === '') return ZOOM_DEFAULT;
+    const n = Number(value);
+    if (!Number.isFinite(n)) return ZOOM_DEFAULT;
+    const stepped = Math.round(n / ZOOM_STEP) * ZOOM_STEP;
+    return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, stepped));
+}
+
+/**
+ * Apply one zoom to a shell root. Idempotent. Takes the ELEMENT, never finds it.
+ *
+ * @param {Element} root     the shell's root
+ * @param {number}  percent  already clamped
+ */
+export function applyZoom(root, percent) {
+    if (!root?.style) return;
+    root.style.setProperty('--twm-zoom', String(percent / 100));
+    root.classList.toggle('twm-zoomed', percent !== ZOOM_DEFAULT);
+}
+
+/**
+ * Paint the control into the element the embedder handed over, restore the saved
+ * zoom, and keep the root in step.
+ *
+ * @param {Element|null} hostEl       where the control goes; absent → no control
+ * @param {object}       opts
+ * @param {Element}      opts.root    the shell root the zoom applies to
+ * @param {object}      [opts.host]   the host port; its `state` persists the zoom
+ * @param {string}      [opts.stateKey]
+ * @param {Function}    [opts.onChange] `(percent) => void`, after every change
+ * @returns {{el: Element, get: () => number, set: (percent: number) => void,
+ *            ready: Promise<number>, dispose: () => void} | null}
+ */
+export function mountZoomControl(hostEl, { root, host = null, stateKey = ZOOM_STATE_KEY, onChange } = {}) {
+    if (!hostEl || !root) return null;
+
+    const doc = hostEl.ownerDocument;
+    let current = ZOOM_DEFAULT;
+    let disposed = false;
+
+    const el = doc.createElement('div');
+    el.className = 'twm-zoom';
+
+    const stepButton = (label, title, delta) => {
+        const b = doc.createElement('button');
+        b.type = 'button';
+        b.className = 'twm-zoom__step';
+        b.textContent = label;
+        b.title = title;
+        b.setAttribute('aria-label', title);
+        b.addEventListener('click', () => commit(clampZoom(current + delta)));
+        return b;
+    };
+
+    const slider = doc.createElement('input');
+    slider.type = 'range';
+    slider.className = 'twm-zoom__slider';
+    slider.min = String(ZOOM_MIN);
+    slider.max = String(ZOOM_MAX);
+    slider.step = String(ZOOM_STEP);
+    slider.value = String(ZOOM_DEFAULT);
+    slider.title = `Zoom the workspace, ${ZOOM_MIN}–${ZOOM_MAX}% — double-click to reset.`;
+    slider.setAttribute('aria-label', 'Zoom the workspace');
+    // `input`, NOT `change`: the readout has to follow the thumb while it is
+    // being dragged, or the number under the mouse is the number you left.
+    slider.addEventListener('input', () => commit(clampZoom(slider.value)));
+    // A double-click on the track resets. It arrives after two mousedowns that
+    // each set the value and fire `input`, so the honest description is "one real
+    // write, then the reset", and a brief jump to wherever you clicked is visible
+    // before it snaps back. Excel's track does exactly that. It must not be
+    // "fixed" by swallowing `input` — that is the event the drag is made of.
+    slider.addEventListener('dblclick', () => commit(ZOOM_DEFAULT));
+
+    // The readout IS the reset, where Excel puts it and where a hand already is.
+    // A separate "100%" button would be a fourth control in a bar 20px tall, and a
+    // percentage nobody can click answers the question while refusing the obvious
+    // next request.
+    const readout = doc.createElement('button');
+    readout.type = 'button';
+    readout.className = 'twm-zoom__value';
+    readout.title = `Back to ${ZOOM_DEFAULT}%`;
+    readout.addEventListener('click', () => commit(ZOOM_DEFAULT));
+
+    el.append(
+        stepButton('−', `Zoom out ${ZOOM_NUDGE}%`, -ZOOM_NUDGE),
+        slider,
+        stepButton('+', `Zoom in ${ZOOM_NUDGE}%`, ZOOM_NUDGE),
+        readout,
+    );
+    hostEl.appendChild(el);
+
+    /** Paint the control and the root. No persistence — used by the restore,
+     *  where writing back what was just read would be a pointless round trip. */
+    const paint = (percent) => {
+        current = percent;
+        slider.value = String(percent);
+        readout.textContent = `${percent}%`;
+        applyZoom(root, percent);
+    };
+
+    // Debounced, because a drag fires `input` per pixel and each one would
+    // otherwise be a write through the host. A host without `state` is legal,
+    // exactly as it is for the desktops: the control still works, the zoom just
+    // does not survive a reload.
+    let saveTimer = 0;
+    const persist = (percent) => {
+        const state = host?.state;
+        if (!state) return;
+        clearTimeout(saveTimer);
+        saveTimer = setTimeout(() => {
+            Promise.resolve()
+                .then(() => state.write(stateKey, percent))
+                .catch((err) => console.warn('[zoom] save failed', err));
+        }, 400);
+    };
+
+    const commit = (percent) => {
+        if (disposed || percent === current) return;
+        paint(percent);
+        persist(percent);
+        try { onChange?.(percent); } catch (err) { console.warn('[zoom] onChange threw', err); }
+    };
+
+    paint(ZOOM_DEFAULT);
+
+    // Restored after the control is already on screen and usable: a zoom is not
+    // worth blocking a first paint on, and a failed read costs the default. The
+    // promise is returned so an embedder that DOES want to wait before mounting —
+    // to avoid content painting at 100% and then jumping — can.
+    const ready = Promise.resolve()
+        .then(() => host?.state?.read?.(stateKey))
+        .then((saved) => {
+            if (!disposed && saved != null) paint(clampZoom(saved));
+            return current;
+        })
+        .catch((err) => {
+            console.warn('[zoom] load failed', err);
+            return current;
+        });
+
+    return {
+        el,
+        get: () => current,
+        set: (percent) => commit(clampZoom(percent)),
+        ready,
+        dispose: () => {
+            disposed = true;
+            clearTimeout(saveTimer);
+            el.remove();
+            applyZoom(root, ZOOM_DEFAULT);
+        },
+    };
+}