take4-console 0.25.0 → 0.31.0

package/dist/Screen/Window.mjs

@@ -1,6 +1,7 @@
 import { BUILTIN_TEXT, BUILTIN_TEXT_FOCUSED, BUILTIN_TEXT_DISABLED, BUILTIN_BORDER, BUILTIN_BORDER_FOCUSED, BUILTIN_BORDER_DISABLED } from './types.mjs';
 import { Region } from './Region.mjs';
 import { getRegistry } from './RegistryHolder.mjs';
+import { getErrorHandler } from './ErrorHolder.mjs';
 import { charWidth, stringWidth } from './textWidth.mjs';
 import { Size } from './Size.mjs';
 /** Glyph table for each visual border style. The 'none' style is handled
@@ -63,6 +64,24 @@ const resolvePadding = (spec) => {
         left: spec.left ?? 0,
     };
 };
+/** Normalises a MarginSpec to a full Margin record (missing sides → 0).
+ *  Shares the PaddingSpec shape so the two helpers are interchangeable. */
+const resolveMargin = (spec) => {
+    if (spec === undefined)
+        return { top: 0, right: 0, bottom: 0, left: 0 };
+    if (typeof spec === 'number')
+        return { top: spec, right: spec, bottom: spec, left: spec };
+    if (Array.isArray(spec)) {
+        const [v = 0, h = 0] = spec;
+        return { top: v, right: h, bottom: v, left: h };
+    }
+    return {
+        top: spec.top ?? 0,
+        right: spec.right ?? 0,
+        bottom: spec.bottom ?? 0,
+        left: spec.left ?? 0,
+    };
+};
 export class Window {
     x;
     y;
@@ -105,12 +124,44 @@ export class Window {
     /** Padding applied inside the border (in addition to the border inset).
      *  Influences `getInnerSize()` / `getInnerOffset()`. */
     padding;
+    /** Outer spacing reserved around this window inside its parent's layout.
+     *  Consumed by the parent's layout engine (absolute/flex/grid); does not
+     *  influence this window's inner area. */
+    margin;
     /** Number of columns for `layout: 'grid'`. */
     gridColumns;
     /** Cross-axis alignment for row/column layouts. */
     alignItems;
     /** Main-axis distribution of leftover space when no flex-grow child consumes it. */
     justifyContent;
+    /** Optional identifier — copied from WindowProperties.id. Used by
+     *  `WindowManager.focusById` and by diagnostic tooling. */
+    id;
+    /** Stacking order among siblings (higher z renders on top). Default: 0. */
+    zIndex;
+    /** Fires once when focused state flips from false to true. */
+    onFocusHandler;
+    /** Fires once when focused state flips from true to false. */
+    onBlurHandler;
+    /** Parent window (set by `addChild`, cleared by `removeChild`). Damage
+     *  tracking walks up this chain to notify the root `Screen` of geometry
+     *  or topology changes that need a full repaint. */
+    parent = null;
+    /** Accumulated dirty region in this window's local coordinates.
+     *  - `null`  — nothing changed since the last emit.
+     *  - `'all'` — the whole window area needs to be re-emitted.
+     *  - `DirtyRect` — bounding box of localised writes; `markDirty()` eagerly
+     *    unions new rects so we only ever carry one rect per window.
+     *  Windows start as `'all'` so the very first frame re-emits every cell. */
+    dirtyRect = 'all';
+    /** Depth of nested `Window.render()` calls currently executing. Increments
+     *  at the top of every `render()` and decrements in a `finally`, so
+     *  controls whose `render()` override re-writes content via `this.clear()`
+     *  / `this.writeText(...)` do not re-mark themselves dirty every frame —
+     *  render-time writes deterministically rebuild the display buffer from
+     *  existing state, so marking them as "user-driven dirty" would defeat the
+     *  "skip frame when nothing changed" optimisation. */
+    static renderingDepth = 0;
     /** Creates a window from the given properties.
      *  For percentage-based sizes, call addChild() before writing content to the window.
      *  Uses the global StyleRegistry set by the Screen constructor. */
@@ -134,9 +185,14 @@ export class Window {
         this.layoutMode = wp.layout ?? 'absolute';
         this.gap = wp.gap ?? 0;
         this.padding = resolvePadding(wp.padding);
+        this.margin = resolveMargin(wp.margin);
         this.gridColumns = Math.max(1, wp.gridColumns ?? 1);
         this.alignItems = wp.alignItems ?? 'stretch';
         this.justifyContent = wp.justifyContent ?? 'start';
+        this.id = wp.id;
+        this.zIndex = wp.zIndex ?? 0;
+        this.onFocusHandler = wp.onFocus;
+        this.onBlurHandler = wp.onBlur;
         const { w, h } = size.isAbsolute() ? size.resolve(0, 0) : { w: 1, h: 1 };
         this.region = new Region(w, h);
         this.content = new Region(w, h);
@@ -154,6 +210,96 @@ export class Window {
     getSize() {
         return this.region.getSize();
     }
+    // ── Damage tracking ─────────────────────────────────────────────────────
+    /** Marks this window (or a sub-rectangle in its local coordinates) as
+     *  dirty. Subsequent `Screen.render()` calls emit ANSI only for cells
+     *  inside the collected dirty rects, skipping untouched regions. When
+     *  `rect` is omitted, the entire window is flagged. Render-time writes
+     *  are ignored so controls' `render()` overrides do not re-mark
+     *  themselves every frame. Safe to call many times between renders —
+     *  new rects are unioned into the existing bounding box. */
+    markDirty(rect) {
+        if (Window.renderingDepth > 0)
+            return;
+        if (this.dirtyRect === 'all')
+            return;
+        if (rect === undefined) {
+            this.dirtyRect = 'all';
+            return;
+        }
+        if (rect.w <= 0 || rect.h <= 0)
+            return;
+        if (this.dirtyRect === null) {
+            this.dirtyRect = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
+            return;
+        }
+        const ax0 = this.dirtyRect.x;
+        const ay0 = this.dirtyRect.y;
+        const ax1 = ax0 + this.dirtyRect.w;
+        const ay1 = ay0 + this.dirtyRect.h;
+        const bx0 = rect.x;
+        const by0 = rect.y;
+        const bx1 = bx0 + rect.w;
+        const by1 = by0 + rect.h;
+        const nx0 = Math.min(ax0, bx0);
+        const ny0 = Math.min(ay0, by0);
+        const nx1 = Math.max(ax1, bx1);
+        const ny1 = Math.max(ay1, by1);
+        this.dirtyRect = { x: nx0, y: ny0, w: nx1 - nx0, h: ny1 - ny0 };
+    }
+    /** Convenience alias — flags the entire window as dirty. Equivalent to
+     *  calling `markDirty()` with no argument; kept as a named entry point
+     *  so custom controls can invalidate themselves without depending on
+     *  the default-argument behaviour. */
+    invalidate() {
+        this.markDirty();
+    }
+    /** Walks the parent chain up to the root window. Damage tracking uses
+     *  this to bubble a full-invalidation signal to the root `Screen` when
+     *  geometry or tree topology changes, because the cells previously
+     *  occupied by a now-moved / resized / hidden window need to be repainted
+     *  from the content underneath them. `Screen` overrides it to toggle its
+     *  internal full-repaint flag; plain `Window`s forward the call up. */
+    markFullInvalidation() {
+        this.parent?.markFullInvalidation();
+    }
+    /** Appends this window's dirty rect (translated into screen coordinates
+     *  via the running offset) and every descendant's dirty rects to `acc`.
+     *  Hidden subtrees are skipped — invisible windows don't contribute to
+     *  the emit phase, and any state change that flips visibility already
+     *  escalated to a full invalidation so the vacated area repaints. */
+    collectDirtyRects(offsetX, offsetY, acc) {
+        if (!this.visible)
+            return;
+        if (this.dirtyRect === 'all') {
+            const { width, height } = this.getSize();
+            acc.push({ x: offsetX, y: offsetY, w: width, h: height });
+        }
+        else if (this.dirtyRect !== null) {
+            acc.push({
+                x: offsetX + this.dirtyRect.x,
+                y: offsetY + this.dirtyRect.y,
+                w: this.dirtyRect.w,
+                h: this.dirtyRect.h,
+            });
+        }
+        for (const child of this.children) {
+            child.collectDirtyRects(offsetX + child.x, offsetY + child.y, acc);
+        }
+    }
+    /** Clears the dirty flag on this window and every descendant. Called by
+     *  `Screen.render()` after the emit phase so the next frame starts from
+     *  a clean slate. */
+    clearDirtyRecursive() {
+        this.dirtyRect = null;
+        for (const child of this.children)
+            child.clearDirtyRecursive();
+    }
+    /** Returns a snapshot of the resolved per-side margin (in cells). The parent's
+     *  layout engine reads this to reserve outer spacing around the child. */
+    getMargin() {
+        return { ...this.margin };
+    }
     /** Returns the number of cells consumed by decorations on each edge.
      *  The explicit 'none' border style is treated as no border (no insets). */
     borderInset() {
@@ -196,11 +342,67 @@ export class Window {
     }
     /** Sets the active state. Affects border and background appearance on next render(). */
     setActive(active) {
+        if (this.active === active)
+            return;
         this.active = active;
+        this.markDirty();
     }
-    /** Sets the focused state. Controls use this to change visual appearance on focus. */
+    /** Sets the focused state. Controls use this to change visual appearance on focus.
+     *  Fires `onFocus` / `onBlur` (configured via `WindowProperties`) when the state
+     *  actually changes; a no-op call with the current value does not re-fire them. */
     setFocused(focused) {
+        if (this.focused === focused)
+            return;
         this.focused = focused;
+        this.markDirty();
+        if (focused)
+            this.onFocusHandler?.();
+        else
+            this.onBlurHandler?.();
+    }
+    /** Registers (or replaces) the onFocus handler at runtime. Pass `undefined`
+     *  to detach. Fires in `setFocused` on every false → true transition. */
+    setOnFocus(handler) {
+        this.onFocusHandler = handler;
+    }
+    /** Registers (or replaces) the onBlur handler at runtime. Pass `undefined`
+     *  to detach. Fires in `setFocused` on every true → false transition. */
+    setOnBlur(handler) {
+        this.onBlurHandler = handler;
+    }
+    /** Returns the optional identifier set via WindowProperties.id. */
+    getId() {
+        return this.id;
+    }
+    /** Sets (or clears with `undefined`) the window identifier used by
+     *  `WindowManager.focusById` and diagnostic tooling. */
+    setId(id) {
+        this.id = id;
+    }
+    /** Returns the current stacking order. Higher values render on top of
+     *  lower ones among siblings. Default: 0. */
+    getZIndex() {
+        return this.zIndex;
+    }
+    /** Updates the stacking order. Siblings are re-sorted on the next render()
+     *  call; call `screen.render()` (or the surrounding window) to see the
+     *  change. Does not affect layout (flex/absolute coordinates are
+     *  independent of z). */
+    setZIndex(zIndex) {
+        if (this.zIndex === zIndex)
+            return;
+        this.zIndex = zIndex;
+        // Re-stacking can expose or occlude any cell inside the parent's
+        // bounds — escalate to a full repaint so the neighbour(s) underneath
+        // get re-emitted along with this window.
+        this.markFullInvalidation();
+        this.markDirty();
+    }
+    /** Returns the direct children of this window in insertion order (a
+     *  read-only view). WindowManager uses this to walk subtrees for
+     *  `trapFocus` and `focusById` without exposing the internal array. */
+    getChildren() {
+        return this.children;
     }
     /** Returns whether this window currently has keyboard focus. */
     isFocused() {
@@ -208,6 +410,8 @@ export class Window {
     }
     /** Sets the disabled state and deactivates the window when disabled. */
     setDisabled(disabled) {
+        if (this.disabled !== disabled)
+            this.markDirty();
         this.disabled = disabled;
         this.setActive(!disabled);
     }
@@ -221,7 +425,15 @@ export class Window {
      *  the content buffer — previously written cells reappear verbatim on the
      *  next render after the window is shown again. */
     setVisible(visible) {
+        if (this.visible === visible)
+            return;
         this.visible = visible;
+        // Showing / hiding a window changes what the root Screen emits in this
+        // window's old bounds (the parent below may need to repaint, or the
+        // new reveal needs its first emit). Full invalidation is the
+        // conservative, always-correct choice.
+        this.markFullInvalidation();
+        this.markDirty();
     }
     /** Returns whether this window is currently visible. Default: true. */
     isVisible() {
@@ -229,7 +441,10 @@ export class Window {
     }
     /** Sets the label text displayed by the control. */
     setLabel(label) {
+        if (this.label === label)
+            return;
         this.label = label;
+        this.markDirty();
     }
     /** Returns the current label text. */
     getLabel() {
@@ -239,6 +454,7 @@ export class Window {
      *  Intended for use by subclasses that need dynamic decoration (e.g. focus-state colour). */
     updateBorder(border) {
         this.border = resolveBorder(border);
+        this.markDirty();
     }
     /** Recomputes the border color from the current focused/disabled state.
      *  Called automatically at the start of render() so subclasses never need to do it manually.
@@ -260,7 +476,13 @@ export class Window {
      *  geometry consistent when more children join the stack. */
     addChild(child) {
         this.children.push(child);
+        child.parent = this;
         this.runLayout();
+        // Newly attached subtrees may overlap existing cells, and their own
+        // `dirtyRect` already defaults to `'all'` — but the parent region that
+        // may be exposed by later removal needs a correct baseline on the root
+        // Screen side, so we bubble a full invalidation for the first frame.
+        this.markFullInvalidation();
     }
     /** Returns a resolved Cell (char + CellAttributes) at (x, y) from the display buffer.
      *  Throws RangeError if out of bounds. Throws Error when the window is
@@ -279,11 +501,13 @@ export class Window {
     setChar(x, y, char) {
         this.content.setChar(x, y, char);
         this.region.setChar(x, y, char);
+        this.markDirty({ x, y, w: 1, h: 1 });
     }
     /** Sets the character and style ID at (x, y). Throws RangeError if out of bounds. */
     setCell(x, y, char, styleId = 0) {
         this.content.setCell(x, y, char, styleId);
         this.region.setCell(x, y, char, styleId);
+        this.markDirty({ x, y, w: 1, h: 1 });
     }
     /** Merges the given style ID onto the existing style at (x, y) without changing the character.
      *  Throws RangeError if out of bounds. */
@@ -292,16 +516,19 @@ export class Window {
         const mergedRegion = this.registry.merge(this.region.getStyleId(x, y), styleId);
         this.content.setStyleId(x, y, mergedContent);
         this.region.setStyleId(x, y, mergedRegion);
+        this.markDirty({ x, y, w: 1, h: 1 });
     }
     /** Resets every cell to a blank space with style ID 0. */
     clear() {
         this.content.clear();
         this.region.clear();
+        this.markDirty();
     }
     /** Fills every cell with the given character and style ID. */
     fill(char, styleId = 0) {
         this.content.fill(char, styleId);
         this.region.fill(char, styleId);
+        this.markDirty();
     }
     /** Writes text into the window's content area starting at (x, y) (default 0, 0).
      *  Coordinates are relative to the inner content area (i.e. decorations such as borders are excluded).
@@ -447,16 +674,69 @@ export class Window {
     render() {
         if (!this.visible)
             return;
-        this.syncBorderColor();
-        this.paintBackground();
-        this.blitContent();
-        this.paintBorder();
-        for (const child of this.children) {
-            if (!child.visible)
-                continue;
-            child.render();
+        Window.renderingDepth++;
+        try {
+            this.syncBorderColor();
+            this.paintBackground();
+            this.blitContent();
+            this.paintBorder();
+            for (const child of this.orderedByZ()) {
+                if (!child.visible)
+                    continue;
+                try {
+                    child.render();
+                    this.blitChild(child);
+                }
+                catch (err) {
+                    this.paintErrorPlaceholder(child, err);
+                    const handler = getErrorHandler();
+                    if (handler)
+                        handler(err, child);
+                    else
+                        throw err;
+                }
+            }
+        }
+        finally {
+            Window.renderingDepth--;
+        }
+    }
+    /** Returns direct children sorted for rendering — stable by (zIndex asc,
+     *  insertion order). Children with higher zIndex paint last, so they
+     *  appear on top of lower-z siblings. Layout is NOT affected: flex and
+     *  absolute positioning run off the insertion-ordered `children` list. */
+    orderedByZ() {
+        if (this.children.length < 2)
+            return this.children;
+        const stable = this.children.map((child, idx) => ({ child, idx }));
+        stable.sort((a, b) => (a.child.zIndex - b.child.zIndex) || (a.idx - b.idx));
+        return stable.map(e => e.child);
+    }
+    /** Renders a single-line "⚠ render error" marker over the child's
+     *  pre-allocated region so a broken subtree never blanks the rest of the
+     *  frame. The child is still blitted onto this window so its geometry
+     *  (borders, siblings) remains visible in the debug layout. */
+    paintErrorPlaceholder(child, err) {
+        const { width, height } = child.getSize();
+        if (width === 0 || height === 0)
+            return;
+        const styleId = this.registry.register({ foreground: 196, background: 52, bold: true });
+        try {
+            child.region = new Region(width, height);
+            child.region.fill(' ', styleId);
+            const message = err instanceof Error ? err.message : String(err);
+            const prefix = '⚠ render error: ';
+            const maxLen = Math.max(0, width - prefix.length);
+            const text = prefix + message.slice(0, maxLen);
+            const chars = [...text];
+            for (let i = 0; i < chars.length && i < width; i++) {
+                child.region.setCell(i, 0, chars[i], styleId);
+            }
             this.blitChild(child);
         }
+        catch {
+            // Swallow — the placeholder itself must not throw further.
+        }
     }
     /** Fills the display buffer with the background style. When inactive, adds dim to every cell.
      *  No-op when background is 0 (transparent). */
@@ -588,14 +868,25 @@ export class Window {
     /** Removes a previously added child window. No-op if the child is not found. */
     removeChild(child) {
         const idx = this.children.indexOf(child);
-        if (idx !== -1)
+        if (idx !== -1) {
             this.children.splice(idx, 1);
+            child.parent = null;
+            // The vacated rectangle has to be re-emitted from the content
+            // underneath — escalate so the root Screen repaints everything.
+            this.markFullInvalidation();
+        }
     }
     /** Replaces both internal regions with new ones of the given dimensions,
      *  then re-resolves sizes and positions of all direct children against the updated inner area. */
     resizeRegions(w, h) {
         this.region = new Region(w, h);
         this.content = new Region(w, h);
+        // A new region invalidates any per-cell dirty bookkeeping from the
+        // previous size — escalate to a full-window repaint and ask the
+        // Screen to emit from scratch because the old footprint on stdout
+        // may include cells that are no longer part of this window.
+        this.dirtyRect = 'all';
+        this.markFullInvalidation();
         this.reflowChildren();
     }
     /** Resizes this window to the given absolute dimensions and reflows every
@@ -633,7 +924,10 @@ export class Window {
         }
     }
     /** Absolute layout: each child independently resolves its Pos/Size against
-     *  the parent's inner area — the pre-flex behaviour. */
+     *  the parent's inner area — the pre-flex behaviour. A child's `margin`
+     *  shifts the resolved position by `(marginLeft, marginTop)` without
+     *  altering its size, so callers can push a window away from its declared
+     *  anchor without recomputing coordinates by hand. */
     layoutAbsolute(pw, ph, ox, oy) {
         for (const child of this.children) {
             if (!child.sizeSpec.isAbsolute()) {
@@ -642,8 +936,8 @@ export class Window {
             }
             const { width: cw, height: ch } = child.getSize();
             const { x, y } = child.posSpec.resolve(pw, ph, cw, ch);
-            child.x = x + ox;
-            child.y = y + oy;
+            child.x = x + ox + child.margin.left;
+            child.y = y + oy + child.margin.top;
         }
     }
     /** Row / column flex layout. The main axis (width for 'row', height for
@@ -656,7 +950,13 @@ export class Window {
      *  distribution only when no child consumes slack via flex-grow. Invisible
      *  children are skipped so `setVisible(false)` effectively removes them
      *  from the stack. Children are ordered by `Pos.flex(order)` first, then
-     *  by addChild insertion (stable). */
+     *  by addChild insertion (stable).
+     *
+     *  Each child's `margin` reserves extra cells around it: the main axis
+     *  loses `marginLeft+marginRight` (row) or `marginTop+marginBottom` (column)
+     *  per child before distribution, and the cross axis loses `margin*` per
+     *  child before alignment. Grow/shrink still apply to the inner size so the
+     *  declared margin stays constant even when the child is flex-resized. */
     layoutFlex(mode, pw, ph, ox, oy) {
         const ordered = this.orderedVisibleChildren();
         if (ordered.length === 0)
@@ -665,7 +965,13 @@ export class Window {
         const mainParent = isRow ? pw : ph;
         const crossParent = isRow ? ph : pw;
         const gap = this.gap;
-        // First pass: basis sizes per child.
+        // Per-child main/cross margin totals captured up-front so they stay
+        // constant across grow/shrink passes.
+        const mainMargin = (c) => isRow ? c.margin.left + c.margin.right : c.margin.top + c.margin.bottom;
+        const crossMargin = (c) => isRow ? c.margin.top + c.margin.bottom : c.margin.left + c.margin.right;
+        // First pass: basis sizes per child (inner, i.e. the child's own region
+        // without margin). Natural size is taken before margin so content-sized
+        // children keep their intrinsic footprint.
         const items = ordered.map((c) => {
             const mainSpec = isRow ? c.sizeSpec.getWidthSpec() : c.sizeSpec.getHeightSpec();
             const crossSpec = isRow ? c.sizeSpec.getHeightSpec() : c.sizeSpec.getWidthSpec();
@@ -677,10 +983,13 @@ export class Window {
                 crossSize: resolveFlexBasis(crossSpec, crossParent, isRow ? c.getSize().height : c.getSize().width),
             };
         });
-        // Distribute leftover main-axis space.
+        // Distribute leftover main-axis space. The parent sees each child's
+        // slot as `mainSize + mainMargin`, so margins are charged against the
+        // remaining space before grow/shrink.
         const totalGap = Math.max(0, items.length - 1) * gap;
+        const totalMargin = items.reduce((s, it) => s + mainMargin(it.child), 0);
         const totalMain = items.reduce((s, it) => s + it.mainSize, 0);
-        let remainder = mainParent - totalMain - totalGap;
+        let remainder = mainParent - totalMain - totalMargin - totalGap;
         const totalGrow = items.reduce((s, it) => s + (it.mainSpec.mode === 'flex' ? it.mainSpec.grow : 0), 0);
         if (remainder > 0 && totalGrow > 0) {
             let distributed = 0;
@@ -713,17 +1022,21 @@ export class Window {
                     it.mainSize = Math.max(0, it.mainSize - take);
                 }
                 const consumed = items.reduce((s, it) => s + it.mainSize, 0);
-                remainder = mainParent - consumed - totalGap;
+                remainder = mainParent - consumed - totalMargin - totalGap;
             }
         }
-        // Apply cross-axis stretch where allowed.
+        // Apply cross-axis stretch where allowed. Cross-axis margin is charged
+        // before stretch/clamp so a stretched child + its margin fits within
+        // crossParent.
         for (const it of items) {
+            const cm = crossMargin(it.child);
+            const available = Math.max(0, crossParent - cm);
             const mode = it.crossSpec.mode;
             if (this.alignItems === 'stretch' && mode !== 'abs' && mode !== 'pct') {
-                it.crossSize = crossParent;
+                it.crossSize = available;
             }
             else {
-                it.crossSize = Math.min(it.crossSize, crossParent);
+                it.crossSize = Math.min(it.crossSize, available);
             }
         }
         // justifyContent kicks in only when there is positive slack with no grow.
@@ -750,7 +1063,10 @@ export class Window {
                     break;
             }
         }
-        // Write final sizes and positions.
+        // Write final sizes and positions. The child's main-axis starting
+        // coordinate is `cursor + marginLeading`; cursor then advances by
+        // `mainSize + mainMargin + itemSpacing` so the next slot is offset by
+        // this child's full footprint.
         let cursor = mainStart;
         for (const it of items) {
             const mainSize = Math.max(0, it.mainSize);
@@ -760,30 +1076,36 @@ export class Window {
             if (newW !== it.child.getSize().width || newH !== it.child.getSize().height) {
                 it.child.resizeRegions(newW, newH);
             }
+            const m = it.child.margin;
+            const mainLead = isRow ? m.left : m.top;
+            const mainTrail = isRow ? m.right : m.bottom;
+            const crossLead = isRow ? m.top : m.left;
+            const cm = crossMargin(it.child);
             let crossPos = 0;
             if (this.alignItems !== 'stretch') {
-                const free = crossParent - crossSize;
+                const free = Math.max(0, crossParent - crossSize - cm);
                 if (this.alignItems === 'center')
                     crossPos = Math.floor(free / 2);
                 else if (this.alignItems === 'end')
                     crossPos = free;
             }
             if (isRow) {
-                it.child.x = ox + cursor;
-                it.child.y = oy + crossPos;
+                it.child.x = ox + cursor + mainLead;
+                it.child.y = oy + crossPos + crossLead;
             }
             else {
-                it.child.x = ox + crossPos;
-                it.child.y = oy + cursor;
+                it.child.x = ox + crossPos + crossLead;
+                it.child.y = oy + cursor + mainLead;
             }
-            cursor += mainSize + itemSpacing;
+            cursor += mainSize + mainLead + mainTrail + itemSpacing;
         }
     }
     /** Grid layout: children are placed row-major into equally sized cells.
      *  Each cell's width is `(innerWidth - gap * (cols - 1)) / cols` (floored);
      *  heights use the same formula with the derived row count. Children are
-     *  resized to the cell dimensions and positioned at the cell's top-left.
-     *  Invisible children are skipped. */
+     *  resized to the cell dimensions minus their own margin and positioned
+     *  at the cell's top-left offset by `(marginLeft, marginTop)`. Invisible
+     *  children are skipped. */
     layoutGrid(pw, ph, ox, oy) {
         const ordered = this.orderedVisibleChildren();
         if (ordered.length === 0)
@@ -797,11 +1119,14 @@ export class Window {
             const child = ordered[i];
             const c = i % cols;
             const r = Math.floor(i / cols);
-            if (cellW !== child.getSize().width || cellH !== child.getSize().height) {
-                child.resizeRegions(cellW, cellH);
+            const m = child.margin;
+            const innerW = Math.max(0, cellW - m.left - m.right);
+            const innerH = Math.max(0, cellH - m.top - m.bottom);
+            if (innerW !== child.getSize().width || innerH !== child.getSize().height) {
+                child.resizeRegions(innerW, innerH);
             }
-            child.x = ox + c * (cellW + gap);
-            child.y = oy + r * (cellH + gap);
+            child.x = ox + c * (cellW + gap) + m.left;
+            child.y = oy + r * (cellH + gap) + m.top;
         }
     }
     /** Returns visible children sorted by Pos.flex(order) ascending; children