@flyingrobots/bijou 2.1.0 → 3.1.0

package/dist/core/components/alert-v3.js

@@ -0,0 +1,37 @@
+import { createSurface } from '../../ports/surface.js';
+import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
+import { boxSurface } from './box-v3.js';
+import { createTextSurface, tokenToCellStyle } from './surface-text.js';
+const ICONS = {
+    success: '\u2713',
+    error: '\u2717',
+    warning: '\u26A0',
+    info: '\u2139',
+};
+const BORDER_TOKENS = {
+    success: 'success',
+    error: 'error',
+    warning: 'warning',
+    info: 'primary',
+};
+/**
+ * Render an alert box as a Surface for V3-native composition.
+ */
+export function alertSurface(message, options = {}) {
+    const ctx = resolveCtx(options.ctx);
+    const variant = options.variant ?? 'info';
+    const iconSurface = createTextSurface(ICONS[variant], tokenToCellStyle(ctx?.semantic(variant)));
+    const messageSurface = typeof message === 'string' ? createTextSurface(message) : message;
+    const width = iconSurface.width + 1 + messageSurface.width;
+    const height = Math.max(iconSurface.height, messageSurface.height, 1);
+    const content = createSurface(width, height, { char: ' ', empty: false });
+    content.blit(iconSurface, 0, 0);
+    content.set(iconSurface.width, 0, { char: ' ', empty: false });
+    content.blit(messageSurface, iconSurface.width + 1, 0);
+    return boxSurface(content, {
+        ...options,
+        borderToken: options.borderToken ?? ctx?.border(BORDER_TOKENS[variant]),
+        bgToken: options.bgToken ?? ctx?.surface('elevated'),
+    });
+}
+//# sourceMappingURL=alert-v3.js.map

package/dist/core/components/alert-v3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-v3.js","sourceRoot":"","sources":["../../../src/core/components/alert-v3.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExE,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,aAAa,GAAsE;IACvF,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAyB,EAAE,UAAwB,EAAE;IAChF,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,cAAc,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1F,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,GAAG,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAE1E,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEvD,OAAO,UAAU,CAAC,OAAO,EAAE;QACzB,GAAG,OAAO;QACV,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,GAAG,EAAE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACvE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC;KACrD,CAAC,CAAC;AACL,CAAC"}

package/dist/core/components/alert.d.ts

@@ -1,15 +1,15 @@
-import type { BijouContext } from '../../ports/context.js';
 import type { TokenValue } from '../theme/tokens.js';
+import type { BijouNodeOptions } from './types.js';
 /** Alert severity level. */
 export type AlertVariant = 'success' | 'error' | 'warning' | 'info';
 /** Configuration for rendering an alert box. */
-export interface AlertOptions {
+export interface AlertOptions extends BijouNodeOptions {
     /** Severity variant (defaults to `'info'`). */
     variant?: AlertVariant;
+    /** Theme token applied to alert borders. Defaults to a variant-specific border token. */
+    borderToken?: TokenValue;
     /** Background fill token for the alert box interior. Defaults to `surface.elevated`. */
     bgToken?: TokenValue;
-    /** Bijou context for I/O, styling, and mode detection. */
-    ctx?: BijouContext;
 }
 /**
  * Render an alert box with an icon and message.

package/dist/core/components/alert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAS,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAK5D,4BAA4B;AAC5B,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,wFAAwF;IACxF,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAsBzE"}
+{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,4BAA4B;AAC5B,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE,gDAAgD;AAChD,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,+CAA+C;IAC/C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,wFAAwF;IACxF,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAsBzE"}

package/dist/core/components/alert.js

@@ -51,7 +51,7 @@ export function alert(message, options = {}) {
         interactive: () => {
             const icon = ICONS[variant];
             const semanticToken = ctx.semantic(variant);
-            const borderToken = ctx.border(BORDER_TOKENS[variant]);
+            const borderToken = options.borderToken ?? ctx.border(BORDER_TOKENS[variant]);
             const coloredIcon = ctx.style.styled(semanticToken, icon);
             return box(coloredIcon + ' ' + safeMessage, {
                 borderToken,

package/dist/core/components/alert.js.map

@@ -1 +1 @@
-{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAejD,sDAAsD;AACtD,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,GAAiC;IAChD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,yDAAyD;AACzD,MAAM,iBAAiB,GAAiC;IACtD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,8EAA8E;AAC9E,MAAM,aAAa,GAAgD;IACjE,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAAwB,EAAE;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,WAAW,GAAG,OAAO,IAAI,EAAE,CAAC;IAElC,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;QAC5B,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,WAAW,EAAE;QACtD,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,WAAW,EAAE;QACjE,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,aAAa,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YACvD,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAE1D,OAAO,GAAG,CAAC,WAAW,GAAG,GAAG,GAAG,WAAW,EAAE;gBAC1C,WAAW;gBACX,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC;gBACnD,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;gBAC9B,GAAG;aACJ,CAAC,CAAC;QACL,CAAC;KACF,EAAE,OAAO,CAAC,CAAC;AACd,CAAC"}
+{"version":3,"file":"alert.js","sourceRoot":"","sources":["../../../src/core/components/alert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAgBjD,sDAAsD;AACtD,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ;IACjB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,GAAiC;IAChD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,yDAAyD;AACzD,MAAM,iBAAiB,GAAiC;IACtD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,8EAA8E;AAC9E,MAAM,aAAa,GAAgD;IACjE,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAAwB,EAAE;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,WAAW,GAAG,OAAO,IAAI,EAAE,CAAC;IAElC,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;QAC5B,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,WAAW,EAAE;QACtD,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,WAAW,EAAE;QACjE,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,aAAa,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YAC9E,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAE1D,OAAO,GAAG,CAAC,WAAW,GAAG,GAAG,GAAG,WAAW,EAAE;gBAC1C,WAAW;gBACX,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC;gBACnD,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;gBAC9B,GAAG;aACJ,CAAC,CAAC;QACL,CAAC;KACF,EAAE,OAAO,CAAC,CAAC;AACd,CAAC"}

package/dist/core/components/badge.d.ts

@@ -1,27 +1,21 @@
-import type { BijouContext } from '../../ports/context.js';
+import { type Surface } from '../../ports/surface.js';
 import type { BaseStatusKey } from '../theme/tokens.js';
+import type { BijouNodeOptions } from './types.js';
 /** Badge color variant — any status key, plus `'accent'` and `'primary'`. */
 export type BadgeVariant = BaseStatusKey | 'accent' | 'primary';
 /** Configuration for rendering a badge. */
-export interface BadgeOptions {
+export interface BadgeOptions extends BijouNodeOptions {
     /** Color variant (defaults to `'info'`). */
     variant?: BadgeVariant;
-    /** Bijou context for I/O, styling, and mode detection. */
-    ctx?: BijouContext;
 }
 /**
  * Render an inline badge (pill-shaped label) for the given text.
  *
- * Output adapts to the current output mode:
- * - `interactive` / `static` — inverse-colored pill using the variant token.
- * - `pipe` — bracketed text like `[OK]`.
- * - `accessible` — plain text.
- *
- * Falls back to a plain space-padded string when no context or theme is available.
+ * Returns a Surface containing the styled badge.
  *
  * @param text - Label to display inside the badge.
  * @param options - Badge configuration.
- * @returns The rendered badge string.
+ * @returns The rendered badge Surface.
  */
-export declare function badge(text: string, options?: BadgeOptions): string;
+export declare function badge(text: string, options?: BadgeOptions): Surface;
 //# sourceMappingURL=badge.d.ts.map

package/dist/core/components/badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIpE,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAsBtE"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,OAAO,EAAa,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,2CAA2C;AAC3C,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,4CAA4C;IAC5C,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CA2CvE"}

package/dist/core/components/badge.js

@@ -1,37 +1,52 @@
+import { createSurface } from '../../ports/surface.js';
 import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
-import { renderByMode } from '../mode-render.js';
+import { segmentGraphemes } from '../text/grapheme.js';
+import { applyBCSSCellTextStyles } from './bcss-style.js';
 /**
  * Render an inline badge (pill-shaped label) for the given text.
  *
- * Output adapts to the current output mode:
- * - `interactive` / `static` — inverse-colored pill using the variant token.
- * - `pipe` — bracketed text like `[OK]`.
- * - `accessible` — plain text.
- *
- * Falls back to a plain space-padded string when no context or theme is available.
+ * Returns a Surface containing the styled badge.
  *
  * @param text - Label to display inside the badge.
  * @param options - Badge configuration.
- * @returns The rendered badge string.
+ * @returns The rendered badge Surface.
  */
 export function badge(text, options = {}) {
     const ctx = resolveCtx(options.ctx);
-    if (!ctx)
-        return ` ${text} `;
     const variant = options.variant ?? 'info';
-    return renderByMode(ctx.mode, {
-        pipe: () => `[${text}]`,
-        accessible: () => text,
-        interactive: () => {
-            const baseToken = (variant === 'accent' || variant === 'primary')
-                ? ctx.semantic(variant)
-                : ctx.status(variant);
-            const inverseToken = {
-                hex: baseToken.hex,
-                modifiers: [...(baseToken.modifiers ?? []), 'inverse'],
-            };
-            return ctx.style.styled(inverseToken, ` ${text} `);
-        },
-    }, options);
+    const paddedText = ` ${text} `;
+    const graphemes = segmentGraphemes(paddedText);
+    const width = graphemes.length;
+    const surface = createSurface(width, 1);
+    if (!ctx || ctx.mode === 'pipe' || ctx.mode === 'accessible') {
+        // Basic text output for non-rich modes
+        const char = ctx?.mode === 'pipe' ? `[${text}]` : paddedText;
+        return stringToSurface(char, char.length, 1);
+    }
+    // Resolve global CSS styles
+    const bcss = ctx.resolveBCSS({ type: 'Badge', id: options.id, classes: options.class?.split(' ') });
+    const baseToken = (variant === 'accent' || variant === 'primary')
+        ? ctx.semantic(variant)
+        : ctx.status(variant);
+    const cell = {
+        char: ' ',
+        ...applyBCSSCellTextStyles({
+            fg: baseToken.hex,
+            bg: undefined,
+            modifiers: [...(baseToken.modifiers ?? []), 'inverse'],
+        }, bcss),
+        empty: false
+    };
+    // If CSS background is set, we might want to disable 'inverse' modifier 
+    // since the user is being explicit about the BG color.
+    if (bcss['background']) {
+        cell.modifiers = cell.modifiers?.filter(m => m !== 'inverse');
+    }
+    for (let i = 0; i < width; i++) {
+        surface.set(i, 0, { ...cell, char: graphemes[i] });
+    }
+    return surface;
 }
+// Helper needed for the fallback
+import { stringToSurface } from '../render/differ.js';
 //# sourceMappingURL=badge.js.map

package/dist/core/components/badge.js.map

@@ -1 +1 @@
-{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAajD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,UAAwB,EAAE;IAC5D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,IAAI,GAAG,CAAC;IAE7B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAE1C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;QAC5B,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,GAAG;QACvB,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI;QACtB,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,SAAS,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,SAAS,CAAC;gBAC/D,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACvB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAExB,MAAM,YAAY,GAAe;gBAC/B,GAAG,EAAE,SAAS,CAAC,GAAG;gBAClB,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC;aACvD,CAAC;YAEF,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;QACrD,CAAC;KACF,EAAE,OAAO,CAAC,CAAC;AACd,CAAC"}
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA2B,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAW1D;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,UAAwB,EAAE;IAC5D,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAE1C,MAAM,UAAU,GAAG,IAAI,IAAI,GAAG,CAAC;IAC/B,MAAM,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;IAC/B,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAExC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC7D,uCAAuC;QACvC,MAAM,IAAI,GAAG,GAAG,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7D,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,4BAA4B;IAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEpG,MAAM,SAAS,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,SAAS,CAAC;QAC/D,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;QACvB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAExB,MAAM,IAAI,GAAS;QACjB,IAAI,EAAE,GAAG;QACT,GAAG,uBAAuB,CAAC;YACzB,EAAE,EAAE,SAAS,CAAC,GAAG;YACjB,EAAE,EAAE,SAAS;YACb,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC;SACvD,EAAE,IAAI,CAAC;QACR,KAAK,EAAE,KAAK;KACb,CAAC;IAEF,yEAAyE;IACzE,uDAAuD;IACvD,IAAI,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iCAAiC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/core/components/bcss-style.d.ts

@@ -0,0 +1,6 @@
+import type { Cell } from '../../ports/surface.js';
+type BCSSStyles = Record<string, string>;
+export declare function mergeBCSSModifiers(base: readonly string[] | undefined, styles: BCSSStyles): string[] | undefined;
+export declare function applyBCSSCellTextStyles(base: Pick<Cell, 'fg' | 'bg' | 'modifiers'>, styles: BCSSStyles): Pick<Cell, 'fg' | 'bg' | 'modifiers'>;
+export {};
+//# sourceMappingURL=bcss-style.d.ts.map

package/dist/core/components/bcss-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bcss-style.d.ts","sourceRoot":"","sources":["../../../src/core/components/bcss-style.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzC,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACnC,MAAM,EAAE,UAAU,GACjB,MAAM,EAAE,GAAG,SAAS,CAoCtB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,EAC3C,MAAM,EAAE,UAAU,GACjB,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,CAMvC"}

package/dist/core/components/bcss-style.js

@@ -0,0 +1,44 @@
+export function mergeBCSSModifiers(base, styles) {
+    const modifiers = new Set(base ?? []);
+    const fontWeight = styles['font-weight']?.trim().toLowerCase();
+    if (fontWeight === 'bold' || fontWeight === '700' || fontWeight === '800' || fontWeight === '900') {
+        modifiers.add('bold');
+    }
+    else if (fontWeight === 'normal' || fontWeight === '400') {
+        modifiers.delete('bold');
+    }
+    const fontStyle = styles['font-style']?.trim().toLowerCase();
+    if (fontStyle === 'italic') {
+        modifiers.add('italic');
+    }
+    else if (fontStyle === 'normal') {
+        modifiers.delete('italic');
+    }
+    const decoration = styles['text-decoration']?.trim().toLowerCase();
+    if (decoration === 'none') {
+        modifiers.delete('underline');
+        modifiers.delete('curly-underline');
+        modifiers.delete('dotted-underline');
+        modifiers.delete('dashed-underline');
+        modifiers.delete('strikethrough');
+        modifiers.delete('strike');
+    }
+    else if (decoration) {
+        if (decoration.includes('underline')) {
+            modifiers.add('underline');
+        }
+        if (decoration.includes('line-through')) {
+            modifiers.add('strikethrough');
+            modifiers.delete('strike');
+        }
+    }
+    return modifiers.size > 0 ? Array.from(modifiers) : undefined;
+}
+export function applyBCSSCellTextStyles(base, styles) {
+    return {
+        fg: styles['color'] ?? base.fg,
+        bg: styles['background'] ?? base.bg,
+        modifiers: mergeBCSSModifiers(base.modifiers, styles),
+    };
+}
+//# sourceMappingURL=bcss-style.js.map

package/dist/core/components/bcss-style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bcss-style.js","sourceRoot":"","sources":["../../../src/core/components/bcss-style.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,kBAAkB,CAChC,IAAmC,EACnC,MAAkB;IAElB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAEtC,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/D,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QAClG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;SAAM,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QAC3D,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7D,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;SAAM,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnE,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC9B,SAAS,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACpC,SAAS,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACrC,SAAS,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACrC,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAClC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YACrC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACxC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YAC/B,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,IAA2C,EAC3C,MAAkB;IAElB,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE;QAC9B,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,EAAE;QACnC,SAAS,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/dist/core/components/box-v3.d.ts

@@ -0,0 +1,17 @@
+import { type Surface } from '../../ports/surface.js';
+import { type BoxOptions, type HeaderBoxOptions } from './box.js';
+/**
+ * Render a bordered box around a Surface.
+ *
+ * Returns a new Surface containing the box and the nested content.
+ */
+export declare function boxSurface(content: Surface | string, options?: BoxOptions): Surface;
+export declare const boxV3: typeof boxSurface;
+/**
+ * Render a header box as a Surface for V3-native composition.
+ *
+ * Unlike {@link headerBox}, this always returns a Surface and is intended
+ * for use inside framed apps or other surface-first render paths.
+ */
+export declare function headerBoxSurface(label: string, options?: HeaderBoxOptions): Surface;
+//# sourceMappingURL=box-v3.d.ts.map

package/dist/core/components/box-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box-v3.d.ts","sourceRoot":"","sources":["../../../src/core/components/box-v3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,OAAO,EAAa,MAAM,wBAAwB,CAAC;AAIhF,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA4BnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAwGvF;AAED,eAAO,MAAM,KAAK,mBAAa,CAAC;AAEhC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAmBvF"}

package/dist/core/components/box-v3.js

@@ -0,0 +1,149 @@
+import { createSurface } from '../../ports/surface.js';
+import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
+import { clipToWidth } from '../text/clip.js';
+import { wrapToWidth } from '../text/wrap.js';
+import { resolveFillChar } from './box.js';
+import { applyBCSSCellTextStyles } from './bcss-style.js';
+import { createSegmentSurface, createTextSurface, segmentSurfaceText, tokenToCellStyle, wrapSurfaceToWidth } from './surface-text.js';
+import { resolveOverflowBehavior } from './overflow.js';
+const BORDER = { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' };
+function normalizeFixedWidth(width) {
+    if (width == null)
+        return undefined;
+    if (!Number.isFinite(width))
+        return undefined;
+    return Math.max(2, Math.floor(width));
+}
+function withInheritedBackground(surface, background) {
+    if (background == null)
+        return surface;
+    const next = surface.clone();
+    for (let y = 0; y < next.height; y++) {
+        for (let x = 0; x < next.width; x++) {
+            const cell = next.get(x, y);
+            if (cell.empty || cell.bg != null)
+                continue;
+            next.set(x, y, { ...cell, bg: background });
+        }
+    }
+    return next;
+}
+/**
+ * Render a bordered box around a Surface.
+ *
+ * Returns a new Surface containing the box and the nested content.
+ */
+export function boxSurface(content, options = {}) {
+    const ctx = resolveCtx(options.ctx);
+    const { title, width: fixedWidth, padding = {} } = options;
+    const bcss = ctx?.resolveBCSS({ type: 'Box', id: options.id, classes: options.class?.split(' ') }) ?? {};
+    const overflow = resolveOverflowBehavior(options.overflow, bcss);
+    const normalizedFixedWidth = normalizeFixedWidth(fixedWidth);
+    const pt = padding.top ?? 0;
+    const pb = padding.bottom ?? 0;
+    const pl = padding.left ?? 0;
+    const pr = padding.right ?? 0;
+    let contentSurf;
+    if (typeof content === 'string') {
+        const wrapped = normalizedFixedWidth !== undefined && overflow === 'wrap'
+            ? wrapToWidth(content, Math.max(0, normalizedFixedWidth - 2 - pl - pr)).join('\n')
+            : content;
+        contentSurf = createTextSurface(wrapped);
+    }
+    else {
+        contentSurf = normalizedFixedWidth !== undefined && overflow === 'wrap'
+            ? wrapSurfaceToWidth(content, Math.max(0, normalizedFixedWidth - 2 - pl - pr))
+            : content;
+    }
+    const autoTitleWidth = normalizedFixedWidth === undefined && title
+        ? segmentSurfaceText(` ${title} `, 'boxSurface title').length
+        : 0;
+    const innerW = normalizedFixedWidth === undefined
+        ? Math.max(contentSurf.width + pl + pr, autoTitleWidth)
+        : contentSurf.width + pl + pr;
+    const innerH = contentSurf.height + pt + pb;
+    const outerW = normalizedFixedWidth ?? (innerW + 2);
+    const outerH = innerH + 2;
+    const boundedInnerW = Math.max(0, outerW - 2);
+    const effectiveLeft = normalizedFixedWidth !== undefined ? Math.min(pl, boundedInnerW) : pl;
+    const effectiveRight = normalizedFixedWidth !== undefined ? Math.min(pr, Math.max(0, boundedInnerW - effectiveLeft)) : pr;
+    const contentBoxWidth = Math.max(0, boundedInnerW - effectiveLeft - effectiveRight);
+    const surface = createSurface(outerW, outerH);
+    const resolvedFillChar = resolveFillChar(options.fillChar);
+    const fillStyle = applyBCSSCellTextStyles({
+        fg: undefined,
+        bg: options.bgToken?.bg,
+        modifiers: undefined,
+    }, bcss);
+    surface.fill({
+        char: resolvedFillChar,
+        bg: fillStyle.bg,
+        fg: fillStyle.fg,
+        modifiers: fillStyle.modifiers,
+        empty: false,
+    });
+    const borderToken = options.borderToken || ctx?.border('primary');
+    const borderStyle = applyBCSSCellTextStyles({
+        fg: borderToken?.hex ?? '#ffffff',
+        bg: borderToken?.bg,
+        modifiers: borderToken?.modifiers,
+    }, bcss);
+    const borderCell = {
+        char: ' ',
+        fg: borderStyle.fg,
+        bg: borderStyle.bg,
+        modifiers: borderStyle.modifiers,
+    };
+    // Draw borders
+    for (let x = 0; x < outerW; x++) {
+        surface.set(x, 0, { ...borderCell, char: BORDER.h });
+        surface.set(x, outerH - 1, { ...borderCell, char: BORDER.h });
+    }
+    for (let y = 0; y < outerH; y++) {
+        surface.set(0, y, { ...borderCell, char: BORDER.v });
+        surface.set(outerW - 1, y, { ...borderCell, char: BORDER.v });
+    }
+    surface.set(0, 0, { ...borderCell, char: BORDER.tl });
+    surface.set(outerW - 1, 0, { ...borderCell, char: BORDER.tr });
+    surface.set(0, outerH - 1, { ...borderCell, char: BORDER.bl });
+    surface.set(outerW - 1, outerH - 1, { ...borderCell, char: BORDER.br });
+    // Draw title
+    if (title && outerW >= 4) {
+        const available = Math.max(0, outerW - 4);
+        const titleText = clipToWidth(` ${title} `, available);
+        const titleGs = segmentSurfaceText(titleText, 'boxSurface title');
+        const titleLen = Math.min(titleGs.length, available);
+        for (let i = 0; i < titleLen; i++) {
+            surface.set(i + 2, 0, { ...borderCell, char: titleGs[i] });
+        }
+    }
+    // Blit content
+    surface.blit(withInheritedBackground(contentSurf, fillStyle.bg), effectiveLeft + 1, pt + 1, 0, 0, contentBoxWidth, contentSurf.height);
+    return surface;
+}
+export const boxV3 = boxSurface;
+/**
+ * Render a header box as a Surface for V3-native composition.
+ *
+ * Unlike {@link headerBox}, this always returns a Surface and is intended
+ * for use inside framed apps or other surface-first render paths.
+ */
+export function headerBoxSurface(label, options = {}) {
+    const ctx = resolveCtx(options.ctx);
+    const safeLabel = label ?? '';
+    const detail = options.detail ?? '';
+    const labelToken = options.labelToken ?? ctx?.semantic('primary');
+    const mutedToken = ctx?.semantic('muted');
+    const segments = [];
+    if (safeLabel.length > 0) {
+        segments.push({ text: safeLabel, style: tokenToCellStyle(labelToken) });
+    }
+    if (detail.length > 0) {
+        segments.push({
+            text: safeLabel.length > 0 ? `  ${detail}` : detail,
+            style: tokenToCellStyle(mutedToken),
+        });
+    }
+    return boxSurface(createSegmentSurface(segments), options);
+}
+//# sourceMappingURL=box-v3.js.map

package/dist/core/components/box-v3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"box-v3.js","sourceRoot":"","sources":["../../../src/core/components/box-v3.ts"],"names":[],"mappings":"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"}

package/dist/core/components/box.d.ts

@@ -1,7 +1,9 @@
-import type { BijouContext } from '../../ports/context.js';
 import type { TokenValue } from '../theme/tokens.js';
+import type { BijouNodeOptions } from './types.js';
 /** Configuration for rendering a bordered box. */
-export interface BoxOptions {
+export interface BoxOptions extends BijouNodeOptions {
+    /** Optional title displayed in the top border. */
+    title?: string;
     /** Theme token applied to border characters. */
     borderToken?: TokenValue;
     /** Background fill token. Interior spaces are styled with this token's bg color. */
@@ -21,8 +23,6 @@ export interface BoxOptions {
      * are rejected and fall back to space.
      */
     fillChar?: string;
-    /** Bijou context for I/O, styling, and mode detection. */
-    ctx?: BijouContext;
 }
 /**
  * Render content inside a bordered box.
@@ -55,4 +55,11 @@ export interface HeaderBoxOptions extends BoxOptions {
  * @returns The rendered header box string.
  */
 export declare function headerBox(label: string, options?: HeaderBoxOptions): string;
+/**
+ * Validate and resolve a fill character option.
+ *
+ * Returns the character if it is a single-width grapheme cluster,
+ * otherwise falls back to a space.
+ */
+export declare function resolveFillChar(fillChar: string | undefined): string;
 //# sourceMappingURL=box.d.ts.map

package/dist/core/components/box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../../src/core/components/box.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,oFAAoF;IACpF,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AA4ED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAuBrE;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAqB/E"}
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../../src/core/components/box.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,kDAAkD;AAClD,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,oFAAoF;IACpF,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAwGD;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CA2BrE;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAqB/E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIpE"}

package/dist/core/components/box.js

@@ -2,15 +2,17 @@ import { resolveCtx } from '../resolve-ctx.js';
 import { makeBgFill } from '../bg-fill.js';
 import { graphemeWidth } from '../text/grapheme.js';
 import { clipToWidth } from '../text/clip.js';
+import { wrapToWidth } from '../text/wrap.js';
 import { renderByMode } from '../mode-render.js';
+import { resolveOverflowBehavior } from './overflow.js';
 /** Unicode box-drawing characters for single-line borders. */
 const BORDER = { tl: '\u250c', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2500', v: '\u2502' };
 /**
  * Draw a unicode box around the given content string.
  *
  * Supports both auto-width (measured from content) and fixed-width modes.
- * Content lines wider than the available space are hard-truncated via
- * `clipToWidth` (no ellipsis is appended).
+ * Content lines wider than the available space wrap by default. Set
+ * `overflow: 'truncate'` to preserve the previous hard-clipping behavior.
  *
  * @param content - Multiline string to place inside the box.
  * @param borderColor - Function that wraps border characters with color styling.
@@ -18,10 +20,11 @@ const BORDER = { tl: '\u250c', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2
  * @param fixedWidth - If provided, lock the outer width and clip/pad content to fit.
  * @param bgFill - Optional function to wrap interior content with background color styling.
  * @param fillChar - Single-width character for padding areas (defaults to space).
+ * @param title - Optional title displayed in the top border.
  * @returns The rendered box as a multiline string.
  */
-function drawBox(content, borderColor, padding, fixedWidth, bgFill, fillChar = ' ') {
-    const contentLines = content.split('\n');
+function drawBox(content, borderColor, padding, fixedWidth, bgFill, fillChar = ' ', title, overflow = 'wrap') {
+    const rawContentLines = content.split('\n');
     let innerWidth;
     let contentWidth;
     if (fixedWidth !== undefined) {
@@ -31,13 +34,17 @@ function drawBox(content, borderColor, padding, fixedWidth, bgFill, fillChar = '
     }
     else {
         // Auto width: measure content
-        const maxWidth = contentLines.reduce((max, line) => Math.max(max, graphemeWidth(line)), 0);
+        const titleWidth = title ? graphemeWidth(title) + 2 : 0;
+        const maxWidth = rawContentLines.reduce((max, line) => Math.max(max, graphemeWidth(line)), 0);
         contentWidth = maxWidth;
-        innerWidth = maxWidth + padding.left + padding.right;
+        innerWidth = Math.max(titleWidth, maxWidth + padding.left + padding.right);
     }
     // When fixed width, padding may exceed innerWidth — clamp to fit
     const effectiveLeft = fixedWidth !== undefined ? Math.min(padding.left, innerWidth) : padding.left;
     const effectiveRight = fixedWidth !== undefined ? Math.min(padding.right, Math.max(0, innerWidth - effectiveLeft)) : padding.right;
+    const contentLines = fixedWidth !== undefined && overflow === 'wrap'
+        ? rawContentLines.flatMap((line) => wrapToWidth(line, contentWidth))
+        : rawContentLines;
     const pad = (line) => {
         const visible = graphemeWidth(line);
         let processed = line;
@@ -50,7 +57,27 @@ function drawBox(content, borderColor, padding, fixedWidth, bgFill, fillChar = '
         return leftPad + processed + rightPad;
     };
     const fill = bgFill ?? ((s) => s);
-    const top = borderColor(BORDER.tl + BORDER.h.repeat(innerWidth) + BORDER.tr);
+    // Render top border with optional title
+    let topBorder = BORDER.h.repeat(innerWidth);
+    if (title && innerWidth >= 4) {
+        const label = ` ${title} `;
+        const labelWidth = graphemeWidth(label);
+        if (labelWidth <= innerWidth - 2) {
+            const start = 1;
+            const before = BORDER.h.repeat(start);
+            const after = BORDER.h.repeat(innerWidth - start - labelWidth);
+            topBorder = before + label + after;
+        }
+        else {
+            // Title too long, clip it
+            const clippedLabel = clipToWidth(label, innerWidth - 2);
+            const start = 1;
+            const before = BORDER.h.repeat(start);
+            const after = BORDER.h.repeat(innerWidth - start - graphemeWidth(clippedLabel));
+            topBorder = before + clippedLabel + after;
+        }
+    }
+    const top = borderColor(BORDER.tl + topBorder + BORDER.tr);
     const bottom = borderColor(BORDER.bl + BORDER.h.repeat(innerWidth) + BORDER.br);
     const emptyLine = borderColor(BORDER.v) + fill(fillChar.repeat(innerWidth)) + borderColor(BORDER.v);
     const lines = [top];
@@ -92,7 +119,8 @@ export function box(content, options = {}) {
             const colorize = (s) => ctx.style.styled(borderToken, s);
             const bgFill = makeBgFill(options.bgToken, ctx);
             const resolvedFill = resolveFillChar(options.fillChar);
-            return drawBox(safeContent, colorize, padding, options.width, bgFill, resolvedFill);
+            const overflow = resolveOverflowBehavior(options.overflow, ctx.resolveBCSS({ type: 'Box', id: options.id, classes: options.class?.split(' ') }));
+            return drawBox(safeContent, colorize, padding, options.width, bgFill, resolvedFill, options.title, overflow);
         },
     }, options);
 }
@@ -133,7 +161,7 @@ export function headerBox(label, options = {}) {
  * Returns the character if it is a single-width grapheme cluster,
  * otherwise falls back to a space.
  */
-function resolveFillChar(fillChar) {
+export function resolveFillChar(fillChar) {
     if (fillChar == null || fillChar.length === 0)
         return ' ';
     if (graphemeWidth(fillChar) !== 1)