@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/layout.js

@@ -0,0 +1,856 @@
+/**
+ * Layout regions (D-041 Phase 2): a `LayoutSpec` names regions per form factor, the engine lays
+ * them out with one CSS grid inside the safe area of a CSS-px overlay, and widgets register once
+ * with a region per form factor. The layout moves them when the form factor changes (a phone
+ * turned upright) and reports `freeRect`, the space the UI leaves, for the scene's camera.
+ *
+ * Everything is in CSS px relative to the overlay root. The geometry is pure (`resolveLayout`)
+ * and the DOM grid uses the same resolved track sizes, so the rects the layout reports are the
+ * rects the browser draws.
+ */
+import { h } from './dom.js';
+export const FORM_FACTORS = [
+    'phone-landscape',
+    'phone-portrait',
+    'tablet',
+    'desktop',
+];
+export const REGIONS = [
+    'top',
+    'left',
+    'right',
+    'bottom',
+    'cardLane',
+    'captionLane',
+    'modal',
+    'fill',
+];
+export const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+/** `size` in `ff`: the number itself, else the form's entry, `phone` on a phone, `default`. Pure. */
+export function formSize(size, ff) {
+    if (typeof size === 'number')
+        return size;
+    const own = size[ff];
+    if (own !== undefined)
+        return own;
+    if (ff.startsWith('phone') && size.phone !== undefined)
+        return size.phone;
+    return size.default;
+}
+/** Largest short side (CSS px) a phone has; tablets start around 744. */
+export const PHONE_MAX_SHORT_SIDE = 600;
+/** A window whose short side is under this is phone-sized, whatever the pointer. */
+export const PHONE_MAX_VIEW_SHORT = 480;
+/**
+ * Default form-factor choice. A phone is a coarse-pointer screen whose short side is at most
+ * `PHONE_MAX_SHORT_SIDE` (the `deviceTraits().handheld` rule), or any window whose short side is
+ * under `PHONE_MAX_VIEW_SHORT` (a tiny desktop window gets phone chrome rather than clipped
+ * desktop chrome). Phones split by orientation. Other coarse pointers are tablets; the rest are
+ * desktops.
+ */
+export function classifyFormFactor(i) {
+    const viewShort = Math.min(i.width, i.height);
+    const handheld = i.coarsePointer && i.shortSide > 0 && i.shortSide <= PHONE_MAX_SHORT_SIDE;
+    if (handheld || (viewShort > 0 && viewShort < PHONE_MAX_VIEW_SHORT)) {
+        return i.height > i.width ? 'phone-portrait' : 'phone-landscape';
+    }
+    return i.coarsePointer ? 'tablet' : 'desktop';
+}
+const WIDE_AREAS = [
+    'top    top         top      top',
+    'left   fill        cardLane right',
+    'left   captionLane cardLane right',
+    'bottom bottom      bottom   bottom',
+];
+/**
+ * The default regions. They are deliberately sparse: empty tracks collapse, so a phone shows
+ * only the chrome a scene registers, and the world gets the rest.
+ *
+ * - **desktop / tablet**: full-width top and bottom bars; left and right rails; a card lane
+ *   beside the world on the right; the caption lane under the world.
+ * - **phone-landscape**: height is the scarce axis, so left and right are full-height rails
+ *   (56 px: a 44 px tap target plus padding) and top/bottom sit between them; the card lane is
+ *   beside the world; the caption lane is a short strip under it.
+ * - **phone-portrait**: width is scarce, so the rails are slim and the card lane and caption lane
+ *   are full-width strips stacked under the world, above the bottom bar.
+ */
+export const defaultForms = {
+    desktop: {
+        columns: [
+            { frac: 0.16, min: 180, max: 300 },
+            'fill',
+            { frac: 0.18, min: 200, max: 320 },
+            { frac: 0.16, min: 180, max: 300 },
+        ],
+        rows: [64, 'fill', { frac: 0.16, min: 96, max: 168 }, 72],
+        areas: WIDE_AREAS,
+        tapMin: 32,
+        textMin: 0,
+        pad: 12,
+        modalMargin: 24,
+        units: 'frame',
+    },
+    tablet: {
+        columns: [
+            { frac: 0.16, min: 160, max: 280 },
+            'fill',
+            { frac: 0.2, min: 200, max: 300 },
+            { frac: 0.16, min: 160, max: 280 },
+        ],
+        rows: [68, 'fill', { frac: 0.16, min: 104, max: 168 }, 76],
+        areas: WIDE_AREAS,
+        tapMin: 44,
+        textMin: 0,
+        pad: 12,
+        modalMargin: 20,
+        units: 'frame',
+    },
+    'phone-landscape': {
+        columns: [56, 'fill', { frac: 0.24, min: 140, max: 200 }, 56],
+        rows: [52, 'fill', { frac: 0.24, min: 64, max: 96 }, 52],
+        areas: [
+            'left top         top      right',
+            'left fill        cardLane right',
+            'left captionLane cardLane right',
+            'left bottom      bottom   right',
+        ],
+        tapMin: 44,
+        textMin: 12,
+        pad: 4,
+        modalMargin: 8,
+        units: 'css',
+    },
+    'phone-portrait': {
+        columns: [56, 'fill', 56],
+        rows: [56, 'fill', { frac: 0.16, min: 96, max: 140 }, { frac: 0.14, min: 80, max: 120 }, 60],
+        areas: [
+            'top         top         top',
+            'left        fill        right',
+            'cardLane    cardLane    cardLane',
+            'captionLane captionLane captionLane',
+            'bottom      bottom      bottom',
+        ],
+        tapMin: 44,
+        textMin: 12,
+        pad: 4,
+        modalMargin: 8,
+        units: 'css',
+    },
+};
+/** The spec for `ff` with `spec.forms[ff]` merged over the default. */
+export function formSpec(ff, spec = {}) {
+    const form = { ...defaultForms[ff], ...spec.forms?.[ff] };
+    if (spec.bars)
+        form.bars = { ...spec.bars, ...form.bars };
+    return form;
+}
+/** Parses `areas` into a cell grid; throws on ragged rows, unknown names or non-rectangles. */
+export function parseAreas(areas) {
+    const cells = areas.map((r) => r.trim().split(/\s+/));
+    const w = cells[0]?.length ?? 0;
+    if (!w || cells.some((r) => r.length !== w))
+        throw new Error('layout: ragged areas');
+    const boxes = new Map();
+    cells.forEach((row, r) => {
+        row.forEach((name, c) => {
+            if (name === '.')
+                return;
+            if (!REGIONS.includes(name) || name === 'modal') {
+                throw new Error(`layout: unknown grid area "${name}"`);
+            }
+            const b = boxes.get(name);
+            if (!b)
+                boxes.set(name, { r0: r, r1: r, c0: c, c1: c, n: 1 });
+            else {
+                b.r0 = Math.min(b.r0, r);
+                b.r1 = Math.max(b.r1, r);
+                b.c0 = Math.min(b.c0, c);
+                b.c1 = Math.max(b.c1, c);
+                b.n++;
+            }
+        });
+    });
+    for (const [name, b] of boxes) {
+        if ((b.r1 - b.r0 + 1) * (b.c1 - b.c0 + 1) !== b.n) {
+            throw new Error(`layout: area "${name}" is not a rectangle`);
+        }
+    }
+    return cells;
+}
+/**
+ * Resolves track sizes on one axis. `collapsed[i]` forces track i to 0. Fixed and fractional
+ * tracks take their size; when they overflow, fractional tracks shrink toward `min`, then the
+ * fill tracks get what is left (at least 0), shared equally.
+ */
+export function resolveTracks(tracks, length, collapsed = []) {
+    const size = tracks.map((t, i) => {
+        if (collapsed[i] || t === 'fill')
+            return 0;
+        if (typeof t === 'number')
+            return Math.max(0, t);
+        const v = t.frac * length;
+        return Math.max(t.min ?? 0, Math.min(t.max ?? Number.POSITIVE_INFINITY, v));
+    });
+    let over = size.reduce((a, b) => a + b, 0) - length;
+    if (over > 0) {
+        const slack = tracks.map((t, i) => typeof t === 'object' && !collapsed[i] ? Math.max(0, size[i] - (t.min ?? 0)) : 0);
+        const total = slack.reduce((a, b) => a + b, 0);
+        if (total > 0) {
+            const k = Math.min(1, over / total);
+            for (let i = 0; i < size.length; i++)
+                size[i] = size[i] - slack[i] * k;
+            over -= Math.min(over, total);
+        }
+    }
+    const fills = tracks.map((t, i) => t === 'fill' && !collapsed[i]);
+    const nFill = fills.filter(Boolean).length;
+    const left = Math.max(0, length - size.reduce((a, b) => a + b, 0));
+    return size.map((s, i) => Math.round((fills[i] ? left / nFill : s) * 100) / 100);
+}
+/** The insets a rect at `rect` inside a `viewport` of the given size actually touches. */
+export function effectiveInsets(rect, viewport, insets) {
+    return {
+        top: Math.max(0, insets.top - rect.y),
+        left: Math.max(0, insets.left - rect.x),
+        bottom: Math.max(0, insets.bottom - (viewport.height - (rect.y + rect.height))),
+        right: Math.max(0, insets.right - (viewport.width - (rect.x + rect.width))),
+    };
+}
+const ROW_BARS = ['top', 'bottom'];
+const COL_BARS = ['left', 'right'];
+const BAR_NAMES = ['top', 'bottom', 'left', 'right'];
+/**
+ * The outer track of `bar` in `cells`: the first row for `top`, the last for `bottom`, the first
+ * column for `left`, the last for `right`; -1 when the bar is not in the grid.
+ */
+function outerTrack(cells, bar) {
+    const rows = bar === 'top' || bar === 'bottom';
+    const n = rows ? cells.length : (cells[0]?.length ?? 0);
+    let t = -1;
+    for (let i = 0; i < n; i++) {
+        const has = rows ? cells[i].includes(bar) : cells.some((row) => row[i] === bar);
+        if (has && (t < 0 || bar === 'bottom' || bar === 'right'))
+            t = i;
+    }
+    return t;
+}
+/** The track a `content` bar or rail wants (its content plus `pad` each side, clamped by `max`), or 0. */
+function contentWant(form, content, bar) {
+    const b = form.bars?.[bar];
+    const v = content?.[bar];
+    if (b?.size !== 'content' || v === undefined || !(v > 0))
+        return 0;
+    return Math.min(v + 2 * form.pad, b.max ?? Number.POSITIVE_INFINITY);
+}
+/**
+ * `cells` with the corner rule applied (ws/ui-9, `BarSize`): where a content bar and a content
+ * rail meet, the corner cell goes to the one that wants the larger track. A tie, or a swap that
+ * would leave a region not a rectangle, keeps the cell. Pure; returns `cells` itself when nothing
+ * moves.
+ */
+function cornerCells(form, cells, content) {
+    if (!content || !form.bars)
+        return cells;
+    let out = cells;
+    for (const bar of ROW_BARS) {
+        const wb = contentWant(form, content, bar);
+        if (!wb)
+            continue;
+        for (const rail of COL_BARS) {
+            const wr = contentWant(form, content, rail);
+            if (!wr || wr === wb)
+                continue;
+            const r = outerTrack(out, bar);
+            const c = outerTrack(out, rail);
+            if (r < 0 || c < 0)
+                continue;
+            const owner = out[r][c];
+            const winner = wb > wr ? bar : rail;
+            if ((owner !== bar && owner !== rail) || owner === winner)
+                continue;
+            const next = out.map((row) => [...row]);
+            next[r][c] = winner;
+            if (!next.some((row) => row.includes(owner)))
+                continue;
+            try {
+                parseAreas(next.map((row) => row.join(' ')));
+            }
+            catch {
+                continue; // not a rectangle any more: keep the form's cell
+            }
+            out = next;
+        }
+    }
+    return out;
+}
+/**
+ * The tracks on one axis of `form` with each `content` bar's (rows: `top`, `bottom`; ws/ui-8) or
+ * rail's (columns: `left`, `right`; ws/ui-9) outer track grown to `contentWant`, never below the
+ * track's own size. Pure; returns the form's own tracks when nothing grows.
+ */
+function contentTracks(form, cells, content, axis) {
+    const base = form[axis];
+    if (!content || !form.bars)
+        return base;
+    let tracks = base;
+    for (const bar of axis === 'rows' ? ROW_BARS : COL_BARS) {
+        const want = contentWant(form, content, bar);
+        if (!want)
+            continue;
+        const i = outerTrack(cells, bar);
+        const t = tracks[i];
+        if (t === undefined || t === 'fill')
+            continue;
+        let next;
+        if (typeof t === 'number') {
+            if (want <= t)
+                continue;
+            next = want;
+        }
+        else {
+            if (want <= (t.min ?? 0))
+                continue;
+            next = { ...t, min: want, max: Math.max(t.max ?? Number.POSITIVE_INFINITY, want) };
+        }
+        if (tracks === base)
+            tracks = [...base];
+        tracks[i] = next;
+    }
+    return tracks;
+}
+/** The `grid-template-areas` rows `resolveLayout` lays out for `content` (the corner rule applied). */
+function resolvedAreas(form, content) {
+    const cells = parseAreas(form.areas);
+    const out = cornerCells(form, cells, content);
+    return out === cells ? form.areas : out.map((row) => row.join(' '));
+}
+/**
+ * Lays out one form at one size. `occupied` names the grid regions that hold widgets; with
+ * `collapseEmpty`, a track collapses when every region in it is empty or also spans another
+ * track on that axis (so a full-width bar never holds a side rail open). `fill` is never empty.
+ * `content` is the tallest widget per bar (`top`, `bottom`) and the widest per rail (`left`,
+ * `right`), CSS px, for the form's `content` bars and rails (`BarSize`, with its corner rule).
+ * Pure.
+ */
+export function resolveLayout(formFactor, form, width, height, safeArea = NO_INSETS, occupied = null, content = null) {
+    const cells = cornerCells(form, parseAreas(form.areas), content);
+    if (cells.length !== form.rows.length || cells[0].length !== form.columns.length) {
+        throw new Error('layout: rows/columns do not match areas');
+    }
+    const innerW = Math.max(0, width - safeArea.left - safeArea.right);
+    const innerH = Math.max(0, height - safeArea.top - safeArea.bottom);
+    const spans = new Map();
+    cells.forEach((row, r) => {
+        row.forEach((n, c) => {
+            if (n === '.')
+                return;
+            const b = spans.get(n);
+            if (!b)
+                spans.set(n, { r0: r, r1: r, c0: c, c1: c });
+            else {
+                b.r1 = Math.max(b.r1, r);
+                b.c1 = Math.max(b.c1, c);
+            }
+        });
+    });
+    const empty = (n) => n !== 'fill' && occupied !== null && !occupied.has(n);
+    const collapseAxis = (count, axis) => Array.from({ length: count }, (_, i) => {
+        if (occupied === null)
+            return false;
+        const names = new Set(axis === 'r' ? cells[i] : cells.map((row) => row[i]));
+        for (const n of names) {
+            if (n === '.')
+                continue;
+            const s = spans.get(n);
+            const wide = axis === 'r' ? s.r1 > s.r0 : s.c1 > s.c0;
+            if (n === 'fill' || (!empty(n) && !wide))
+                return false;
+        }
+        return true;
+    });
+    const colCollapsed = collapseAxis(form.columns.length, 'c');
+    const rowCollapsed = collapseAxis(form.rows.length, 'r');
+    // An occupied region never ends up with every track collapsed: reopen its first one.
+    for (const [n, s] of spans) {
+        if (empty(n))
+            continue;
+        if (colCollapsed.slice(s.c0, s.c1 + 1).every(Boolean))
+            colCollapsed[s.c0] = false;
+        if (rowCollapsed.slice(s.r0, s.r1 + 1).every(Boolean))
+            rowCollapsed[s.r0] = false;
+    }
+    const columns = resolveTracks(contentTracks(form, cells, content, 'columns'), innerW, colCollapsed);
+    const rows = resolveTracks(contentTracks(form, cells, content, 'rows'), innerH, rowCollapsed);
+    const offs = (t, i) => t.slice(0, i).reduce((a, b) => a + b, 0);
+    const regions = Object.fromEntries(REGIONS.map((n) => [n, null]));
+    for (const [n, s] of spans) {
+        const x = safeArea.left + offs(columns, s.c0);
+        const y = safeArea.top + offs(rows, s.r0);
+        regions[n] = {
+            x,
+            y,
+            width: offs(columns, s.c1 + 1) - offs(columns, s.c0),
+            height: offs(rows, s.r1 + 1) - offs(rows, s.r0),
+        };
+    }
+    const m = form.modalMargin;
+    regions.modal = {
+        x: safeArea.left + m,
+        y: safeArea.top + m,
+        width: Math.max(0, innerW - 2 * m),
+        height: Math.max(0, innerH - 2 * m),
+    };
+    const freeRect = regions.fill ?? {
+        x: safeArea.left,
+        y: safeArea.top,
+        width: innerW,
+        height: innerH,
+    };
+    return {
+        formFactor,
+        units: form.units,
+        width,
+        height,
+        safeArea,
+        columns,
+        rows,
+        regions,
+        freeRect: { ...freeRect },
+    };
+}
+/** Where `place` puts a widget in `ff`. Pure. */
+export function placementFor(place, ff) {
+    return place[ff] ?? place.default ?? 'hidden';
+}
+/**
+ * Pads the layout's regions by a host's safe-area insets (ws/host-mobile): sets
+ * `layout.setSafeArea(source.insets())` now and again whenever `source` reports a change, so the
+ * `top` region starts below the notch and the `bottom` region ends above the home indicator.
+ * `createGame` calls it with `host.safeArea` when the host has one; without it the layout reads
+ * `env(safe-area-inset-*)` itself. Returns unsubscribe, which also hands the page's own insets
+ * back to the layout.
+ */
+export function followSafeArea(layout, source) {
+    const apply = (i) => layout.setSafeArea({ top: i.top, right: i.right, bottom: i.bottom, left: i.left });
+    apply(source.insets());
+    const off = source.watch(apply);
+    return () => {
+        off();
+        layout.setSafeArea(null);
+    };
+}
+/** CSS px safe-area insets of `doc`'s viewport (`env(safe-area-inset-*)`, or the `--tc-safe-*` overrides). */
+export function readSafeArea(doc = document) {
+    const probe = doc.createElement('div');
+    probe.style.cssText =
+        'position:fixed;left:0;top:0;width:0;height:0;visibility:hidden;pointer-events:none;' +
+            'padding:var(--tc-safe-top,env(safe-area-inset-top,0px)) var(--tc-safe-right,env(safe-area-inset-right,0px)) ' +
+            'var(--tc-safe-bottom,env(safe-area-inset-bottom,0px)) var(--tc-safe-left,env(safe-area-inset-left,0px));';
+    doc.body.append(probe);
+    const cs = doc.defaultView?.getComputedStyle(probe);
+    const px = (v) => Number.parseFloat(v ?? '') || 0;
+    const out = {
+        top: px(cs?.paddingTop),
+        right: px(cs?.paddingRight),
+        bottom: px(cs?.paddingBottom),
+        left: px(cs?.paddingLeft),
+    };
+    probe.remove();
+    return out;
+}
+/** Slack before a measured box counts as larger than its region, CSS px (sub-pixel rounding). */
+const OVERFLOW_SLACK = 0.5;
+const r2 = (v) => Math.round(v * 100) / 100;
+const HIDDEN_ATTR = 'data-tc-layout-hidden';
+/**
+ * Lays out regions over the overlay (`createOverlay` calls it; read it as `overlay.layout`).
+ *
+ * The density tokens `--tc-tap-min` and `--tc-text-min` (from the form spec), `data-form-factor`
+ * and the form's `units` go on the overlay root, so the base widgets in the panels layer follow
+ * them too.
+ */
+export function createLayout(overlay, spec = {}) {
+    const root = overlay.root;
+    const doc = root.ownerDocument;
+    const win = doc.defaultView;
+    const classify = spec.classify ?? classifyFormFactor;
+    const collapseEmpty = spec.collapseEmpty !== false;
+    let insetOverride = spec.safeArea ?? null;
+    let formOverride = null;
+    const regionEls = Object.fromEntries(REGIONS.map((n) => [
+        n,
+        h('div', {
+            class: 'tc-region',
+            dataset: { region: n },
+            style: n === 'modal' ? {} : { gridArea: n },
+        }),
+    ]));
+    const free = h('div', { class: 'tc-layout-free' });
+    const element = h('div', { class: 'tc-layout' }, ...REGIONS.filter((n) => n !== 'modal').map((n) => regionEls[n]));
+    overlay.layers.layout.append(element, regionEls.modal, free);
+    const entries = [];
+    const subs = new Set();
+    let seq = 0;
+    let state;
+    let freeUses = [];
+    let overflows = [];
+    const measureInsets = () => {
+        const vp = {
+            width: win?.innerWidth ?? overlay.rect.width,
+            height: win?.innerHeight ?? overlay.rect.height,
+        };
+        const raw = insetOverride ?? readSafeArea(doc);
+        // The overlay's rect is relative to its parent; place it in the viewport.
+        const pb = root.parentElement?.getBoundingClientRect();
+        const r = overlay.rect;
+        const inView = {
+            x: (pb?.left ?? 0) + r.x,
+            y: (pb?.top ?? 0) + r.y,
+            width: r.width,
+            height: r.height,
+        };
+        return effectiveInsets(inView, vp, raw);
+    };
+    const classifyNow = () => {
+        const mq = (q) => typeof win?.matchMedia === 'function' && win.matchMedia(q).matches;
+        const s = win?.screen;
+        return classify({
+            width: overlay.rect.width,
+            height: overlay.rect.height,
+            coarsePointer: mq('(pointer: coarse)'),
+            shortSide: s ? Math.min(s.width, s.height) : 0,
+        });
+    };
+    const apply = () => {
+        const ff = classifyNow();
+        const form = { ...formSpec(ff, spec), ...formOverride?.[ff] };
+        // Which grid regions hold a widget in this form factor.
+        const occupied = new Set();
+        for (const e of entries) {
+            const p = placementFor(e.place, ff);
+            if (typeof p === 'string' && p !== 'hidden')
+                occupied.add(p);
+        }
+        const insets = measureInsets();
+        const resolve = (content) => resolveLayout(ff, form, overlay.rect.width, overlay.rect.height, insets, collapseEmpty ? occupied : null, content);
+        state = resolve(null);
+        writeGrid(ff, form, insets, occupied);
+        for (const e of entries)
+            e.onForm?.(ff);
+        // Widgets. A widget already in its region after the one placed before it stays put
+        // (ws/ui-11): re-inserting a node cancels its CSS transitions and drops its focus, so a
+        // re-layout moves only the elements whose region or order changed, and tells them (`onMove`).
+        freeUses = [];
+        const sorted = [...entries].sort((a, b) => a.order - b.order || a.seq - b.seq);
+        const freed = [];
+        const moved = [];
+        const lastIn = new Map();
+        for (const e of sorted) {
+            const was = e.current;
+            let p = placementFor(e.place, ff);
+            if (typeof p === 'string' && p !== 'hidden' && !state.regions[p]) {
+                console.warn(`[layout] ${e.id}: no "${p}" region in ${ff}; hidden`);
+                p = 'hidden';
+            }
+            e.el.toggleAttribute(HIDDEN_ATTR, p === 'hidden');
+            e.el.style.order = e.order ? String(e.order) : '';
+            if (typeof p === 'object') {
+                if (!e.loggedFree) {
+                    console.info(`[layout] free placement: ${e.id} (${p.reason})`);
+                    e.loggedFree = true;
+                }
+                freeUses.push({ id: e.id, reason: p.reason });
+                if (e.caption)
+                    e.caption.dock(null);
+                if (e.el.parentNode !== free)
+                    free.append(e.el);
+                freed.push([e, p]);
+                e.current = 'free';
+                if (was !== 'free')
+                    moved.push(e);
+                continue;
+            }
+            if (e.current === 'free') {
+                for (const k of ['position', 'left', 'top', 'width', 'height'])
+                    e.el.style[k] = '';
+            }
+            if (p === 'hidden') {
+                if (e.caption)
+                    e.caption.dock(null);
+                e.current = 'hidden';
+                if (was !== 'hidden')
+                    moved.push(e);
+                continue;
+            }
+            const r = regionEls[p];
+            const prev = lastIn.get(r);
+            let move = was !== p;
+            if (e.caption)
+                e.caption.dock(r);
+            else if (e.el.parentNode !== r ||
+                (prev && !(prev.compareDocumentPosition(e.el) & Node.DOCUMENT_POSITION_FOLLOWING))) {
+                if (prev)
+                    prev.after(e.el);
+                else
+                    r.prepend(e.el);
+                move = true;
+            }
+            lastIn.set(r, e.caption ? e.caption.element : e.el);
+            e.current = p;
+            if (move)
+                moved.push(e);
+        }
+        // Content bars and rails (ws/ui-8, ws/ui-9): one read of the bar widgets' heights and the
+        // rail widgets' widths, then the grid re-flows once if a track or a corner moved. A content
+        // rail is measured at `max-content` (ws/ui-10): for the read it is as wide as its widest
+        // widget wants and does not stretch them, so a widget reports its intrinsic width rather than
+        // the rail's current one, and the rail follows its content both ways.
+        const bars = form.bars;
+        if (bars && BAR_NAMES.some((b) => bars[b]?.size === 'content')) {
+            const content = {};
+            const left = bars.left?.size === 'content' ? intrinsic(regionEls.left) : null;
+            const right = bars.right?.size === 'content' ? intrinsic(regionEls.right) : null;
+            for (const e of sorted) {
+                const p = e.current;
+                if (p !== 'top' && p !== 'bottom' && p !== 'left' && p !== 'right')
+                    continue;
+                if (bars[p]?.size !== 'content')
+                    continue;
+                const box = e.el.getBoundingClientRect?.();
+                const v = (p === 'left' || p === 'right' ? box?.width : box?.height) ?? 0;
+                content[p] = Math.max(content[p] ?? 0, v);
+            }
+            left?.();
+            right?.();
+            const next = resolve(content);
+            const areas = resolvedAreas(form, content);
+            if (areas !== form.areas ||
+                next.rows.some((r, i) => r !== state.rows[i]) ||
+                next.columns.some((c, i) => c !== state.columns[i])) {
+                state = next;
+                writeGrid(ff, form, insets, occupied, areas);
+            }
+        }
+        for (const [e, p] of freed) {
+            const r = typeof p.rect === 'function' ? p.rect(state) : p.rect;
+            Object.assign(e.el.style, {
+                position: 'absolute',
+                left: `${r.x}px`,
+                top: `${r.y}px`,
+                width: `${r.width}px`,
+                height: `${r.height}px`,
+            });
+        }
+        // Overflow: one read pass after the writes above (one reflow per re-layout, none per frame).
+        overflows = [];
+        for (const e of sorted) {
+            const p = e.current;
+            if (p === 'free' || p === 'hidden')
+                continue;
+            const r = state.regions[p];
+            const box = e.el.getBoundingClientRect?.();
+            if (!r || !box)
+                continue;
+            const rw = r2(Math.max(0, r.width - 2 * form.pad));
+            const rh = r2(Math.max(0, r.height - 2 * form.pad));
+            const w = r2(box.width);
+            const bh = r2(box.height);
+            if (w <= rw + OVERFLOW_SLACK && bh <= rh + OVERFLOW_SLACK)
+                continue;
+            overflows.push({ id: e.id, region: p, w, h: bh, rw, rh });
+            if (!e.warnedOverflow) {
+                e.warnedOverflow = true;
+                console.warn(`[layout] ${e.id} overflows its "${p}" region in ${ff}: ${w}x${bh} px in ${rw}x${rh} px`);
+            }
+        }
+        for (const e of moved)
+            e.onMove?.(e.current);
+        for (const f of subs)
+            f(state);
+    };
+    /**
+     * Lay a rail out at `max-content` for a measure (ws/ui-10): the region as wide as its widest
+     * widget wants, its widgets at their own width (`align-items: flex-start` instead of the rail's
+     * stretch). Returns the restore. Inline values a game set on the region come back.
+     */
+    const intrinsic = (el) => {
+        const s = el.style;
+        const width = s.width;
+        const align = s.alignItems;
+        s.width = 'max-content';
+        s.alignItems = 'flex-start';
+        return () => {
+            s.width = width;
+            s.alignItems = align;
+        };
+    };
+    /** Tokens, grid tracks and region visibility for the current `state`. */
+    const writeGrid = (ff, form, insets, occupied, 
+    /** The grid areas `state` was laid out with (the corner rule may move a cell; ws/ui-9). */
+    areas = form.areas) => {
+        root.dataset.formFactor = ff;
+        root.style.setProperty('--tc-tap-min', `${form.tapMin}px`);
+        root.style.setProperty('--tc-text-min', `${form.textMin}px`);
+        root.style.setProperty('--tc-region-pad', `${form.pad}px`);
+        for (const side of ['top', 'right', 'bottom', 'left']) {
+            root.style.setProperty(`--tc-safe-${side}-px`, `${insets[side]}px`);
+        }
+        const m = state.regions.modal;
+        root.style.setProperty('--tc-modal-top', `${m.y}px`);
+        root.style.setProperty('--tc-modal-left', `${m.x}px`);
+        root.style.setProperty('--tc-modal-right', `${state.width - m.x - m.width}px`);
+        root.style.setProperty('--tc-modal-bottom', `${state.height - m.y - m.height}px`);
+        Object.assign(element.style, {
+            padding: `${insets.top}px ${insets.right}px ${insets.bottom}px ${insets.left}px`,
+            gridTemplateColumns: state.columns.map((c) => `${c}px`).join(' '),
+            gridTemplateRows: state.rows.map((r) => `${r}px`).join(' '),
+            gridTemplateAreas: areas.map((a) => `"${a.trim().split(/\s+/).join(' ')}"`).join(' '),
+        });
+        for (const n of REGIONS) {
+            const r = state.regions[n];
+            const el = regionEls[n];
+            const absent = !r || r.width <= 0 || r.height <= 0;
+            el.toggleAttribute('data-empty', absent || (n !== 'fill' && !occupied.has(n)));
+            // A content bar or rail (ws/ui-11): widgets that otherwise shrink to fit their region
+            // (the minimap) hold their own size here, and the track grows to them instead.
+            el.toggleAttribute('data-content', form.bars?.[n]?.size === 'content');
+            el.hidden = absent;
+            if (n === 'modal' && r) {
+                Object.assign(el.style, {
+                    left: `${r.x}px`,
+                    top: `${r.y}px`,
+                    width: `${r.width}px`,
+                    height: `${r.height}px`,
+                });
+            }
+        }
+    };
+    const unwatch = overlay.onResize(() => apply());
+    const layout = {
+        element,
+        get formFactor() {
+            return state.formFactor;
+        },
+        get state() {
+            return state;
+        },
+        get freeRect() {
+            return state.freeRect;
+        },
+        get safeArea() {
+            return state.safeArea;
+        },
+        get freeUses() {
+            return freeUses;
+        },
+        region(name) {
+            return regionEls[name];
+        },
+        overflows: () => overflows,
+        add(el, opts) {
+            const e = {
+                id: opts.id ?? (el.id || `widget-${seq + 1}`),
+                el,
+                place: { ...opts.place },
+                order: opts.order ?? 0,
+                seq: seq++,
+                current: 'hidden',
+                home: el.parentNode ? { parent: el.parentNode, next: el.nextSibling } : undefined,
+                loggedFree: false,
+                warnedOverflow: false,
+                onForm: opts.onForm,
+                onMove: opts.onMove,
+            };
+            entries.push(e);
+            apply();
+            return handle(e);
+        },
+        dockCaption(caption = overlay.caption, place = { default: 'captionLane' }) {
+            const e = {
+                id: 'caption',
+                el: caption.element,
+                place: { ...place },
+                order: 0,
+                seq: seq++,
+                current: 'hidden',
+                caption,
+                loggedFree: false,
+                warnedOverflow: false,
+            };
+            entries.push(e);
+            apply();
+            return handle(e);
+        },
+        setSafeArea(insets) {
+            insetOverride = insets ? { ...insets } : null;
+            apply();
+        },
+        setForms(forms) {
+            formOverride = forms ? { ...forms } : null;
+            apply();
+        },
+        refresh: () => apply(),
+        onChange(fn) {
+            subs.add(fn);
+            return () => subs.delete(fn);
+        },
+        destroy() {
+            unwatch();
+            subs.clear();
+            for (const e of entries.splice(0)) {
+                if (e.caption)
+                    e.caption.dock(null);
+                else if (e.home)
+                    goHome(e);
+                e.el.removeAttribute(HIDDEN_ATTR);
+            }
+            element.remove();
+            regionEls.modal.remove();
+            free.remove();
+            delete root.dataset.formFactor;
+        },
+    };
+    /** Back where it was before `add`, or out of the document if it had no parent then. */
+    function goHome(e) {
+        const home = e.home;
+        if (!home?.parent) {
+            e.el.remove();
+            return;
+        }
+        const next = home.next && home.next.parentNode === home.parent ? home.next : null;
+        home.parent.insertBefore(e.el, next);
+    }
+    function handle(e) {
+        return {
+            element: e.el,
+            get region() {
+                return e.current;
+            },
+            setPlace(place) {
+                e.place = { ...place };
+                e.loggedFree = false;
+                e.warnedOverflow = false;
+                apply();
+            },
+            remove() {
+                const i = entries.indexOf(e);
+                if (i < 0)
+                    return;
+                entries.splice(i, 1);
+                if (e.caption)
+                    e.caption.dock(null);
+                else
+                    goHome(e);
+                e.el.removeAttribute(HIDDEN_ATTR);
+                e.el.style.order = '';
+                if (e.current === 'free') {
+                    for (const k of ['position', 'left', 'top', 'width', 'height'])
+                        e.el.style[k] = '';
+                }
+                apply();
+            },
+        };
+    }
+    apply();
+    return layout;
+}