take4-console 0.15.1 → 0.25.0

package/dist/Screen/Window.mjs

@@ -1,12 +1,23 @@
 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 { charWidth, stringWidth } from './textWidth.mjs';
 import { Size } from './Size.mjs';
-/** Characters used for each border style. */
+/** Glyph table for each visual border style. The 'none' style is handled
+ *  separately (paintBorder bails out early), so it does not appear here. */
 const BORDER_CHARS = {
-    single: { h: '─', v: '│', tl: '┌', tr: '┐', bl: '└', br: '┘' },
-    double: { h: '═', v: '║', tl: '╔', tr: '╗', bl: '╚', br: '╝' },
-    rounded: { h: '─', v: '│', tl: '╭', tr: '╮', bl: '╰', br: '╯' },
+    single: { horizontal: '─', vertical: '│', topLeft: '┌', topRight: '┐', bottomLeft: '└', bottomRight: '┘',
+        verticalLeft: '┤', verticalRight: '├', horizontalTop: '┴', horizontalBottom: '┬', cross: '┼' },
+    double: { horizontal: '═', vertical: '║', topLeft: '╔', topRight: '╗', bottomLeft: '╚', bottomRight: '╝',
+        verticalLeft: '╣', verticalRight: '╠', horizontalTop: '╩', horizontalBottom: '╦', cross: '╬' },
+    rounded: { horizontal: '─', vertical: '│', topLeft: '╭', topRight: '╮', bottomLeft: '╰', bottomRight: '╯',
+        verticalLeft: '┤', verticalRight: '├', horizontalTop: '┴', horizontalBottom: '┬', cross: '┼' },
+    thick: { horizontal: '━', vertical: '┃', topLeft: '┏', topRight: '┓', bottomLeft: '┗', bottomRight: '┛',
+        verticalLeft: '┫', verticalRight: '┣', horizontalTop: '┻', horizontalBottom: '┳', cross: '╋' },
+    dashed: { horizontal: '╌', vertical: '╎', topLeft: '┌', topRight: '┐', bottomLeft: '└', bottomRight: '┘',
+        verticalLeft: '┤', verticalRight: '├', horizontalTop: '┴', horizontalBottom: '┬', cross: '┼' },
+    ascii: { horizontal: '-', vertical: '|', topLeft: '+', topRight: '+', bottomLeft: '+', bottomRight: '+',
+        verticalLeft: '+', verticalRight: '+', horizontalTop: '+', horizontalBottom: '+', cross: '+' },
 };
 /** Resolves a border option (true / object / false) to a full WindowBorder or false. */
 const resolveBorder = (border) => {
@@ -16,6 +27,42 @@ const resolveBorder = (border) => {
         return { top: true, right: true, bottom: true, left: true };
     return border;
 };
+/** Resolves a flex-item's initial main- or cross-axis size from its DimSpec.
+ *  - 'abs'     → the literal pixel value.
+ *  - 'pct'     → the computed fraction of the parent's inner dimension.
+ *  - 'flex'    → the basis (abs or pct of parent) before grow/shrink distribution.
+ *  - 'content' → the child's natural size (its current Region dimension on the
+ *                requested axis), which defaults to 1 for an uninitialised child.
+ *  `naturalSize` must come from the child's current getSize() on the relevant
+ *  axis so content-sized children pick up the most up-to-date measurement. */
+function resolveFlexBasis(spec, parent, naturalSize) {
+    switch (spec.mode) {
+        case 'abs': return spec.value;
+        case 'pct': return Math.floor(parent * spec.value / 100);
+        case 'content': return naturalSize;
+        case 'flex':
+            return spec.basis.kind === 'pct'
+                ? Math.floor(parent * spec.basis.value / 100)
+                : spec.basis.value;
+    }
+}
+/** Normalises a PaddingSpec to a full Padding record (missing sides → 0). */
+const resolvePadding = (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;
@@ -45,6 +92,25 @@ export class Window {
     active;
     posSpec;
     sizeSpec;
+    /** Whether this window participates in rendering. When false, the window's own
+     *  render() is a no-op, its region is not blitted onto the parent, and
+     *  `getCell()` throws. Focus-cycle in WindowManager skips invisible focusable
+     *  controls. Default: true. */
+    visible = true;
+    /** Layout algorithm applied to direct children. 'absolute' keeps the pre-flex
+     *  behaviour; 'row' / 'column' / 'grid' activate the flex engine. */
+    layoutMode;
+    /** Spacing (in cells) between adjacent children for flex / grid layouts. */
+    gap;
+    /** Padding applied inside the border (in addition to the border inset).
+     *  Influences `getInnerSize()` / `getInnerOffset()`. */
+    padding;
+    /** 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;
     /** 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. */
@@ -65,6 +131,12 @@ export class Window {
         this.background = wp.background ?? 0;
         this.border = resolveBorder(wp.border ?? wp.defaultBorder);
         this.borderColorExplicit = this.border !== false && this.border.color !== undefined;
+        this.layoutMode = wp.layout ?? 'absolute';
+        this.gap = wp.gap ?? 0;
+        this.padding = resolvePadding(wp.padding);
+        this.gridColumns = Math.max(1, wp.gridColumns ?? 1);
+        this.alignItems = wp.alignItems ?? 'stretch';
+        this.justifyContent = wp.justifyContent ?? 'start';
         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);
@@ -82,10 +154,11 @@ export class Window {
     getSize() {
         return this.region.getSize();
     }
-    /** Returns the number of cells consumed by decorations on each edge. */
+    /** Returns the number of cells consumed by decorations on each edge.
+     *  The explicit 'none' border style is treated as no border (no insets). */
     borderInset() {
         const b = this.border;
-        if (!b)
+        if (!b || b.style === 'none')
             return { top: 0, right: 0, bottom: 0, left: 0 };
         return {
             top: (b.top ?? false) ? 1 : 0,
@@ -94,15 +167,28 @@ export class Window {
             left: (b.left ?? false) ? 1 : 0,
         };
     }
-    /** Returns the top-left offset of the content area, accounting for decorations such as borders. */
+    /** Returns the combined per-side inset (border + padding) that defines the
+     *  inner content area. Padding stacks on top of the border inset. */
+    innerInset() {
+        const b = this.borderInset();
+        return {
+            top: b.top + this.padding.top,
+            right: b.right + this.padding.right,
+            bottom: b.bottom + this.padding.bottom,
+            left: b.left + this.padding.left,
+        };
+    }
+    /** Returns the top-left offset of the content area, accounting for
+     *  decorations (border) and layout insets (padding). */
     getInnerOffset() {
-        const { left, top } = this.borderInset();
+        const { left, top } = this.innerInset();
         return { x: left, y: top };
     }
-    /** Returns the dimensions of the content area, accounting for decorations such as borders. */
+    /** Returns the dimensions of the content area, accounting for decorations
+     *  (border) and layout insets (padding). */
     getInnerSize() {
         const { width, height } = this.getSize();
-        const { top, right, bottom, left } = this.borderInset();
+        const { top, right, bottom, left } = this.innerInset();
         return {
             width: Math.max(0, width - left - right),
             height: Math.max(0, height - top - bottom),
@@ -129,6 +215,18 @@ export class Window {
     isDisabled() {
         return this.disabled;
     }
+    /** Shows or hides the window. A hidden window does not paint itself, is not
+     *  blitted onto its parent, and its focusable descendants are skipped by
+     *  `WindowManager.moveFocus / setFocus`. Toggling visibility does not mutate
+     *  the content buffer — previously written cells reappear verbatim on the
+     *  next render after the window is shown again. */
+    setVisible(visible) {
+        this.visible = visible;
+    }
+    /** Returns whether this window is currently visible. Default: true. */
+    isVisible() {
+        return this.visible;
+    }
     /** Sets the label text displayed by the control. */
     setLabel(label) {
         this.label = label;
@@ -154,25 +252,24 @@ export class Window {
                 ? this.registry.getNamedForeground(BUILTIN_BORDER_FOCUSED, 75)
                 : this.registry.getNamedForeground(BUILTIN_BORDER, 240);
     }
-    /** Adds a child window. If the child uses percentage-based sizes they are resolved immediately
-     *  against this window's inner dimensions (excluding decorations such as borders).
-     *  Position is resolved relative to the inner area and stored on child.x/y. */
+    /** Adds a child window. The final position and (for non-absolute sizes) the
+     *  final dimensions are computed by the parent's layout engine: in
+     *  'absolute' layout each child resolves its own Pos/Size; in 'row',
+     *  'column', or 'grid' layouts the engine distributes the inner area
+     *  across every visible child. Re-laying out on addChild keeps sibling
+     *  geometry consistent when more children join the stack. */
     addChild(child) {
-        const { width: pw, height: ph } = this.getInnerSize();
-        const { x: ox, y: oy } = this.getInnerOffset();
-        if (!child.sizeSpec.isAbsolute()) {
-            const { w, h } = child.sizeSpec.resolve(pw, ph);
-            child.resizeRegions(w, h);
-        }
-        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;
         this.children.push(child);
+        this.runLayout();
     }
     /** Returns a resolved Cell (char + CellAttributes) at (x, y) from the display buffer.
-     *  Throws RangeError if out of bounds. */
+     *  Throws RangeError if out of bounds. Throws Error when the window is
+     *  currently hidden (setVisible(false)) — callers should check isVisible()
+     *  first when the visibility state is uncertain. */
     getCell(x, y) {
+        if (!this.visible) {
+            throw new Error('Window.getCell called on a hidden window (setVisible(false))');
+        }
         const char = this.region.getChars()[this.flatIndex(x, y)];
         const styleId = this.region.getStyleId(x, y);
         const attributes = { ...this.registry.get(styleId) };
@@ -208,42 +305,155 @@ export class Window {
     }
     /** 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).
-     *  Newline characters move to the next row, resetting x to startX.
-     *  Characters outside the inner bounds are silently clipped.
-     *  When no style is provided, automatically picks disabledStyleId, focusedStyleId, or normalStyleId
-     *  based on the current disabled/focused state. */
-    writeText(text, options) {
+     *
+     *  Accepts either a plain string (one base style for the whole text) or an array of
+     *  `WriteTextSegment`s so inline rich text can be laid out without separate writeText()
+     *  calls — the cursor flows from one segment into the next on the same row. Each segment
+     *  may pin its own style either as a pre-registered `style: StyleId` or as inline
+     *  `attrs: CellAttributes` (registered on the fly). The segment style is merged on top
+     *  of the base style so global defaults (e.g. foreground) keep applying unless overridden.
+     *
+     *  Behaviour shared with the single-string form:
+     *  - Newline characters move to the next row, resetting x to startX.
+     *  - Characters outside the inner bounds are silently clipped.
+     *  - Wide characters (CJK, emoji, double-width NerdFonts) occupy two consecutive cells;
+     *    the second cell stores '' as a continuation sentinel so terminal cursor advancement
+     *    during render() stays aligned with the buffer indices. Wide chars whose right half
+     *    would overflow the inner area are skipped entirely.
+     *  - Zero-width codepoints (combining marks, format chars, control chars) are skipped.
+     *  - When no style is provided, the base style is auto-picked from disabled / focused /
+     *    normal state. Pass `options.style = 0` to suppress the state-based base style. */
+    writeText(input, options) {
         const { x: ox, y: oy } = this.getInnerOffset();
         const { width: iw, height: ih } = this.getInnerSize();
         const startX = (options?.x ?? 0) + ox;
         const startY = (options?.y ?? 0) + oy;
-        const styleId = options?.style ?? (this.disabled ? this.disabledStyleId :
+        const baseStyle = options?.style ?? (this.disabled ? this.disabledStyleId :
             this.focused ? this.focusedStyleId :
                 this.normalStyleId);
+        const segments = typeof input === 'string'
+            ? [{ text: input }]
+            : input;
         let cx = startX;
         let cy = startY;
-        for (const ch of text) {
-            if (ch === '\n') {
-                cx = startX;
-                cy++;
+        for (const seg of segments) {
+            let segId = baseStyle;
+            if (seg.style !== undefined) {
+                segId = this.registry.merge(baseStyle, seg.style);
+            }
+            else if (seg.attrs !== undefined) {
+                segId = this.registry.merge(baseStyle, this.registry.register(seg.attrs));
+            }
+            for (const ch of seg.text) {
+                if (ch === '\n') {
+                    cx = startX;
+                    cy++;
+                    continue;
+                }
+                const w = charWidth(ch.codePointAt(0));
+                if (w === 0)
+                    continue;
+                const inRow = cy >= oy && cy < oy + ih;
+                if (w === 2) {
+                    if (inRow && cx >= ox && cx + 1 < ox + iw) {
+                        this.setCell(cx, cy, ch, segId);
+                        this.setCell(cx + 1, cy, '', segId);
+                    }
+                }
+                else {
+                    if (inRow && cx >= ox && cx < ox + iw) {
+                        this.setCell(cx, cy, ch, segId);
+                    }
+                }
+                cx += w;
+            }
+        }
+    }
+    /** Writes a template that embeds named styles from the StyleRegistry.
+     *  Syntax is a mini-markup: `{name}…{/}` wraps an inline region in the style
+     *  registered under `name` (e.g. a built-in name like `builtin:text-focused` or a
+     *  user-registered custom name). Nested tags inherit attributes from their parent
+     *  — the inner style is merged on top of the outer one, so `{red}a{bold}b{/}c{/}`
+     *  renders `a` in red, `b` in red+bold, `c` in red. `{/}` closes the most recently
+     *  opened tag. Unknown names keep the surrounding style unchanged. `{{` and `}}`
+     *  escape literal braces. The template is compiled to an array of
+     *  `WriteTextSegment`s and written via writeText(), so line-wrap, width, and
+     *  clipping rules are inherited. */
+    writeMarkup(template, options) {
+        const segments = [];
+        const stack = [];
+        let buf = '';
+        const flush = () => {
+            if (buf.length === 0)
+                return;
+            const top = stack[stack.length - 1];
+            segments.push(top !== undefined ? { text: buf, style: top } : { text: buf });
+            buf = '';
+        };
+        let i = 0;
+        while (i < template.length) {
+            const ch = template[i];
+            if (ch === '{' && template[i + 1] === '{') {
+                buf += '{';
+                i += 2;
                 continue;
             }
-            if (cx >= ox && cx < ox + iw && cy >= oy && cy < oy + ih) {
-                this.setCell(cx, cy, ch, styleId);
+            if (ch === '}' && template[i + 1] === '}') {
+                buf += '}';
+                i += 2;
+                continue;
+            }
+            if (ch === '{') {
+                const close = template.indexOf('}', i + 1);
+                if (close === -1) {
+                    buf += ch;
+                    i++;
+                    continue;
+                }
+                const tag = template.slice(i + 1, close);
+                flush();
+                if (tag === '/') {
+                    stack.pop();
+                }
+                else {
+                    const id = this.registry.getNamed(tag);
+                    const top = stack[stack.length - 1] ?? 0;
+                    const composed = id !== undefined ? this.registry.merge(top, id) : top;
+                    stack.push(composed);
+                }
+                i = close + 1;
+                continue;
             }
-            cx++;
+            buf += ch;
+            i++;
         }
+        flush();
+        this.writeText(segments, options);
+    }
+    /** Returns the display width (in terminal cells) of a string,
+     *  honouring wide characters (CJK, emoji, double-width NerdFonts) and
+     *  ignoring zero-width codepoints. Useful for sizing labels or aligning
+     *  text in custom controls. */
+    getTextWidth(text) {
+        return stringWidth(text);
     }
     /**
      * Builds the display buffer: background → user content → border → children.
      * The result is stored in region and used by blitChild / Screen.render().
+     * A hidden window (setVisible(false)) returns immediately so neither its
+     * own paint stages nor its children contribute to the frame; hidden
+     * children are also skipped in the loop below.
      */
     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();
             this.blitChild(child);
         }
@@ -273,15 +483,21 @@ export class Window {
             }
         }
     }
-    /** Draws border characters on the display buffer edges. When inactive, adds dim to border cells. */
+    /** Draws border characters on the display buffer edges. When inactive, adds dim to border cells.
+     *  Uses the glyph table for `border.style`, with optional per-character overrides
+     *  via `border.chars`. The 'none' style is a no-op placeholder. */
     paintBorder() {
         if (!this.border)
             return;
         const b = this.border;
+        const style = b.style ?? 'single';
+        if (style === 'none')
+            return;
         const { width, height } = this.region.getSize();
         if (width < 2 && height < 2)
             return;
-        const chars = BORDER_CHARS[b.style ?? 'single'];
+        const baseChars = BORDER_CHARS[style];
+        const chars = b.chars ? { ...baseChars, ...b.chars } : baseChars;
         const bgColor = this.background !== 0
             ? this.registry.get(this.background).background
             : undefined;
@@ -304,11 +520,11 @@ export class Window {
                 const isRight = x === width - 1;
                 let ch;
                 if (isLeft && left)
-                    ch = chars.tl;
+                    ch = chars.topLeft;
                 else if (isRight && right)
-                    ch = chars.tr;
+                    ch = chars.topRight;
                 else
-                    ch = chars.h;
+                    ch = chars.horizontal;
                 this.region.setCell(x, 0, ch, baseId);
             }
         }
@@ -319,11 +535,11 @@ export class Window {
                 const isRight = x === width - 1;
                 let ch;
                 if (isLeft && left)
-                    ch = chars.bl;
+                    ch = chars.bottomLeft;
                 else if (isRight && right)
-                    ch = chars.br;
+                    ch = chars.bottomRight;
                 else
-                    ch = chars.h;
+                    ch = chars.horizontal;
                 this.region.setCell(x, height - 1, ch, baseId);
             }
         }
@@ -332,7 +548,7 @@ export class Window {
             const rowStart = top ? 1 : 0;
             const rowEnd = bottom ? height - 2 : height - 1;
             for (let y = rowStart; y <= rowEnd; y++) {
-                this.region.setCell(0, y, chars.v, baseId);
+                this.region.setCell(0, y, chars.vertical, baseId);
             }
         }
         // right column (skip corners already drawn)
@@ -340,22 +556,21 @@ export class Window {
             const rowStart = top ? 1 : 0;
             const rowEnd = bottom ? height - 2 : height - 1;
             for (let y = rowStart; y <= rowEnd; y++) {
-                this.region.setCell(width - 1, y, chars.v, baseId);
+                this.region.setCell(width - 1, y, chars.vertical, baseId);
             }
         }
     }
-    /** Copies a child's display buffer onto this window's display buffer, clipping to this window's bounds.
-     *  Styles are transferred from the child's registry into this window's registry.
-     *  Position is re-resolved from the child's Pos spec relative to the inner content area on every render. */
+    /** Copies a child's display buffer onto this window's display buffer,
+     *  clipping to this window's bounds. Styles are transferred from the child's
+     *  registry into this window's registry. The child's (x, y) was computed by
+     *  the layout engine on addChild / reflowChildren / setSize, so blit can
+     *  read it directly — this keeps absolute and flex paths on the same code. */
     blitChild(child) {
         const chars = child.region.getChars();
         const childStyleIds = child.region.getStyleIds();
         const { width: cw, height: ch } = child.getSize();
-        const { width: pw, height: ph } = this.getInnerSize();
-        const { x: ox, y: oy } = this.getInnerOffset();
-        const { x: cx, y: cy } = child.posSpec.resolve(pw, ph, cw, ch);
-        const ax = cx + ox;
-        const ay = cy + oy;
+        const ax = child.x;
+        const ay = child.y;
         const { width: totalW, height: totalH } = this.getSize();
         for (let childY = 0; childY < ch; childY++) {
             for (let childX = 0; childX < cw; childX++) {
@@ -383,11 +598,43 @@ export class Window {
         this.content = new Region(w, h);
         this.reflowChildren();
     }
-    /** Re-resolves sizes and absolute positions for every direct child against the current inner area.
-     *  Called after this window is resized so that percentage-based children get correct dimensions. */
+    /** Resizes this window to the given absolute dimensions and reflows every
+     *  descendant whose size or position is percentage-based against the new
+     *  inner area. Existing absolute children keep their declared geometry but
+     *  have their stored x/y refreshed by reflowChildren() so the parent's
+     *  border insets still apply. The previously written content is discarded
+     *  — callers that need to preserve it must redraw after setSize(). */
+    setSize(width, height) {
+        this.resizeRegions(width, height);
+    }
+    /** Re-resolves sizes and absolute positions for every direct child against
+     *  the current inner area. Delegates to the layout engine so percentage
+     *  children, flex children, and grid cells are all updated from the same
+     *  code path. Called after this window is resized or a new child is added. */
     reflowChildren() {
+        this.runLayout();
+    }
+    /** Runs the layout engine against the current inner area. Dispatches to
+     *  absolute / row / column / grid implementations based on `layoutMode`. */
+    runLayout() {
         const { width: pw, height: ph } = this.getInnerSize();
         const { x: ox, y: oy } = this.getInnerOffset();
+        switch (this.layoutMode) {
+            case 'absolute':
+                this.layoutAbsolute(pw, ph, ox, oy);
+                return;
+            case 'row':
+            case 'column':
+                this.layoutFlex(this.layoutMode, pw, ph, ox, oy);
+                return;
+            case 'grid':
+                this.layoutGrid(pw, ph, ox, oy);
+                return;
+        }
+    }
+    /** Absolute layout: each child independently resolves its Pos/Size against
+     *  the parent's inner area — the pre-flex behaviour. */
+    layoutAbsolute(pw, ph, ox, oy) {
         for (const child of this.children) {
             if (!child.sizeSpec.isAbsolute()) {
                 const { w, h } = child.sizeSpec.resolve(pw, ph);
@@ -399,6 +646,176 @@ export class Window {
             child.y = y + oy;
         }
     }
+    /** Row / column flex layout. The main axis (width for 'row', height for
+     *  'column') is distributed across children: each child starts with its
+     *  basis (abs → value, pct → fraction of parent, flex → flex basis,
+     *  content → measured natural size), then remaining slack is distributed
+     *  pro rata by `grow`, and negative slack by `shrink`. The cross axis is
+     *  aligned via `alignItems` — 'stretch' expands flex/content children to
+     *  the full inner cross dimension. `justifyContent` governs leftover
+     *  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). */
+    layoutFlex(mode, pw, ph, ox, oy) {
+        const ordered = this.orderedVisibleChildren();
+        if (ordered.length === 0)
+            return;
+        const isRow = mode === 'row';
+        const mainParent = isRow ? pw : ph;
+        const crossParent = isRow ? ph : pw;
+        const gap = this.gap;
+        // First pass: basis sizes per child.
+        const items = ordered.map((c) => {
+            const mainSpec = isRow ? c.sizeSpec.getWidthSpec() : c.sizeSpec.getHeightSpec();
+            const crossSpec = isRow ? c.sizeSpec.getHeightSpec() : c.sizeSpec.getWidthSpec();
+            return {
+                child: c,
+                mainSpec,
+                crossSpec,
+                mainSize: resolveFlexBasis(mainSpec, mainParent, isRow ? c.getSize().width : c.getSize().height),
+                crossSize: resolveFlexBasis(crossSpec, crossParent, isRow ? c.getSize().height : c.getSize().width),
+            };
+        });
+        // Distribute leftover main-axis space.
+        const totalGap = Math.max(0, items.length - 1) * gap;
+        const totalMain = items.reduce((s, it) => s + it.mainSize, 0);
+        let remainder = mainParent - totalMain - 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;
+            for (const it of items) {
+                if (it.mainSpec.mode !== 'flex')
+                    continue;
+                const share = Math.floor(remainder * (it.mainSpec.grow / totalGrow));
+                it.mainSize += share;
+                distributed += share;
+            }
+            // Hand the integer-truncation leftover to the last flex child.
+            const leftover = remainder - distributed;
+            if (leftover > 0) {
+                for (let i = items.length - 1; i >= 0; i--) {
+                    if (items[i].mainSpec.mode === 'flex') {
+                        items[i].mainSize += leftover;
+                        break;
+                    }
+                }
+            }
+            remainder = 0;
+        }
+        else if (remainder < 0) {
+            const totalShrink = items.reduce((s, it) => s + (it.mainSpec.mode === 'flex' ? it.mainSpec.shrink : 0), 0);
+            if (totalShrink > 0) {
+                for (const it of items) {
+                    if (it.mainSpec.mode !== 'flex')
+                        continue;
+                    const take = Math.ceil(Math.abs(remainder) * (it.mainSpec.shrink / totalShrink));
+                    it.mainSize = Math.max(0, it.mainSize - take);
+                }
+                const consumed = items.reduce((s, it) => s + it.mainSize, 0);
+                remainder = mainParent - consumed - totalGap;
+            }
+        }
+        // Apply cross-axis stretch where allowed.
+        for (const it of items) {
+            const mode = it.crossSpec.mode;
+            if (this.alignItems === 'stretch' && mode !== 'abs' && mode !== 'pct') {
+                it.crossSize = crossParent;
+            }
+            else {
+                it.crossSize = Math.min(it.crossSize, crossParent);
+            }
+        }
+        // justifyContent kicks in only when there is positive slack with no grow.
+        let mainStart = 0;
+        let itemSpacing = gap;
+        if (remainder > 0) {
+            switch (this.justifyContent) {
+                case 'center':
+                    mainStart = Math.floor(remainder / 2);
+                    break;
+                case 'end':
+                    mainStart = remainder;
+                    break;
+                case 'space-between':
+                    if (items.length > 1)
+                        itemSpacing = gap + Math.floor(remainder / (items.length - 1));
+                    break;
+                case 'space-around':
+                    if (items.length > 0) {
+                        const pad = Math.floor(remainder / (items.length * 2));
+                        mainStart = pad;
+                        itemSpacing = gap + pad * 2;
+                    }
+                    break;
+            }
+        }
+        // Write final sizes and positions.
+        let cursor = mainStart;
+        for (const it of items) {
+            const mainSize = Math.max(0, it.mainSize);
+            const crossSize = Math.max(0, it.crossSize);
+            const newW = isRow ? mainSize : crossSize;
+            const newH = isRow ? crossSize : mainSize;
+            if (newW !== it.child.getSize().width || newH !== it.child.getSize().height) {
+                it.child.resizeRegions(newW, newH);
+            }
+            let crossPos = 0;
+            if (this.alignItems !== 'stretch') {
+                const free = crossParent - crossSize;
+                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;
+            }
+            else {
+                it.child.x = ox + crossPos;
+                it.child.y = oy + cursor;
+            }
+            cursor += mainSize + 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. */
+    layoutGrid(pw, ph, ox, oy) {
+        const ordered = this.orderedVisibleChildren();
+        if (ordered.length === 0)
+            return;
+        const cols = this.gridColumns;
+        const rows = Math.max(1, Math.ceil(ordered.length / cols));
+        const gap = this.gap;
+        const cellW = Math.max(0, Math.floor((pw - gap * Math.max(0, cols - 1)) / cols));
+        const cellH = Math.max(0, Math.floor((ph - gap * Math.max(0, rows - 1)) / rows));
+        for (let i = 0; i < ordered.length; i++) {
+            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);
+            }
+            child.x = ox + c * (cellW + gap);
+            child.y = oy + r * (cellH + gap);
+        }
+    }
+    /** Returns visible children sorted by Pos.flex(order) ascending; children
+     *  without Pos.flex default to order 0. Stable w.r.t. addChild insertion. */
+    orderedVisibleChildren() {
+        const visible = this.children.filter(c => c.visible);
+        const withIndex = visible.map((child, idx) => ({
+            child,
+            order: child.posSpec.getFlexOrder() ?? 0,
+            idx,
+        }));
+        withIndex.sort((a, b) => (a.order - b.order) || (a.idx - b.idx));
+        return withIndex.map(e => e.child);
+    }
     /** Returns the flat index for (x, y) in the region buffer (used by getCell). */
     flatIndex(x, y) {
         return y * this.region.getSize().width + x;