@flyingrobots/bijou 4.4.1 → 5.0.0

package/README.md

@@ -45,10 +45,18 @@ const panel = boxSurface(
 
 Select the family based on the interaction semantic, not just the visual shape.
 
+Render-path naming follows one house rule: the base family name is the public
+component, and a `*Surface()` companion means “the same family on the composable
+surface path.” If there is no `*Surface()` companion, the family is either
+already surface-native, intentionally string-first, or both paths would be
+fake duplication rather than a real second API.
+
 ### Status and Feedback
 - **`badge()`**: Compact, inline status.
 - **`note()`**: Non-urgent explanation.
 - **`alert()`**: Persistent, in-flow message.
+- **`guidedFlow()`**: Calm multi-step assistance with one explicit next action.
+- **`explainability()`**: AI- or machine-mediated recommendation with visible provenance and evidence.
 - *Use `@flyingrobots/bijou-tui` notifications for stacking, history, or active routing.*
 
 ### Selection and Prompts
@@ -72,7 +80,7 @@ Select the family based on the interaction semantic, not just the visual shape.
 
 - **[GUIDE.md](./GUIDE.md)**: Productive-fast path.
 - **[ADVANCED_GUIDE.md](./ADVANCED_GUIDE.md)**: Rendering doctrine, themes, and testing.
-- **[Design System](../../docs/design-system/README.md)**: Semantic guidance and component families.
+- **[Design System](../../docs/design-system/README.md)**: Foundations, token vocabulary, and component families.
 
 ---
 Built with 💎 by [FLYING ROBOTS](https://github.com/flyingrobots)

package/dist/adapters/test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/test/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAOtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,wEAAwE;IACxE,EAAE,CAAC,EAAE,aAAa,CAAC;IACnB,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,wDAAwD;IACxD,KAAK,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;IACjD,gDAAgD;IAChD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AASD;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAyB/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/test/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,wEAAwE;IACxE,EAAE,CAAC,EAAE,aAAa,CAAC;IACnB,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,wDAAwD;IACxD,KAAK,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;IACjD,gDAAgD;IAChD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AASD;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAwB/E"}

package/dist/adapters/test/index.js

@@ -5,7 +5,6 @@ import { plainStyle } from './style.js';
 import { createResolved } from '../../core/theme/resolve.js';
 import { CYAN_MAGENTA } from '../../core/theme/presets.js';
 import { createThemeAccessors } from '../../core/theme/accessors.js';
-import { createTokenGraph } from '../../core/theme/graph.js';
 import { systemClock } from '../../core/clock.js';
 export { mockRuntime } from './runtime.js';
 export { mockIO } from './io.js';
@@ -44,7 +43,6 @@ export function createTestContext(options = {}) {
         : options.io);
     const style = options.style ?? plainStyle();
     const theme = createResolved(options.theme ?? CYAN_MAGENTA, options.noColor ?? false, options.colorScheme ?? 'dark');
-    const tokenGraph = createTokenGraph((options.theme ?? CYAN_MAGENTA));
     const mode = options.mode ?? 'interactive';
     return {
         theme,
@@ -53,7 +51,7 @@ export function createTestContext(options = {}) {
         io,
         clock,
         style,
-        tokenGraph,
+        tokenGraph: theme.tokenGraph,
         resolveBCSS: () => ({}),
         ...createThemeAccessors(theme),
     };

package/dist/adapters/test/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/test/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAA2B,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAyC,MAAM,YAAY,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,WAAW,EAA2B,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAyC,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAwBlE,SAAS,WAAW,CAAC,KAA2D;IAC9E,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC3B,KAAK,KAAK,IAAI;WACd,KAAK,IAAI,KAAK;WACd,OAAO,KAAK,CAAC,GAAG,KAAK,UAAU,CAAC;AACvC,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC;IAC1D,MAAM,KAAK,GAAG,cAAc,KAAK,SAAS;QACxC,CAAC,CAAC,WAAW,EAAE;QACf,CAAC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,KAAK,SAAS;QAC/C,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE;QAClC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,IAAI,YAAY,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK,EAAE,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC,CAAC;IACrH,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,YAAY,CAAgC,CAAC,CAAC;IACpG,MAAM,IAAI,GAAe,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC;IAEvD,OAAO;QACL,KAAK;QACL,IAAI;QACJ,OAAO;QACP,EAAE;QACF,KAAK;QACL,KAAK;QACL,UAAU;QACV,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QACvB,GAAG,oBAAoB,CAAC,KAAK,CAAC;KAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/test/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAA2B,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAyC,MAAM,YAAY,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,WAAW,EAA2B,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAyC,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAwBlE,SAAS,WAAW,CAAC,KAA2D;IAC9E,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC3B,KAAK,KAAK,IAAI;WACd,KAAK,IAAI,KAAK;WACd,OAAO,KAAK,CAAC,GAAG,KAAK,UAAU,CAAC;AACvC,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC;IAC1D,MAAM,KAAK,GAAG,cAAc,KAAK,SAAS;QACxC,CAAC,CAAC,WAAW,EAAE;QACf,CAAC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,KAAK,SAAS;QAC/C,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE;QAClC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,IAAI,YAAY,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK,EAAE,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC,CAAC;IACrH,MAAM,IAAI,GAAe,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC;IAEvD,OAAO;QACL,KAAK;QACL,IAAI;QACJ,OAAO;QACP,EAAE;QACF,KAAK;QACL,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QACvB,GAAG,oBAAoB,CAAC,KAAK,CAAC;KAC/B,CAAC;AACJ,CAAC"}

package/dist/adapters/test/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/adapters/test/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAiBzE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/adapters/test/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAiBzE"}

package/dist/adapters/test/runtime.js

@@ -1,3 +1,4 @@
+import { sanitizePositiveInt } from '../../core/numeric.js';
 /**
  * Create an in-memory {@link RuntimePort} for tests.
  *
@@ -20,9 +21,9 @@ export function mockRuntime(options = {}) {
         },
         stdoutIsTTY: options.stdoutIsTTY ?? true,
         stdinIsTTY: options.stdinIsTTY ?? true,
-        columns: options.columns ?? 80,
-        rows: options.rows ?? 24,
-        refreshRate: options.refreshRate ?? 60,
+        columns: sanitizePositiveInt(options.columns, 80),
+        rows: sanitizePositiveInt(options.rows, 24),
+        refreshRate: sanitizePositiveInt(options.refreshRate, 60),
     };
 }
 //# sourceMappingURL=runtime.js.map

package/dist/adapters/test/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/adapters/test/runtime.ts"],"names":[],"mappings":"AAoBA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IACjC,OAAO;QACL;;;;WAIG;QACH,GAAG,CAAC,GAAW;YACb,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;QAC9B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;KACvC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/adapters/test/runtime.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAoB5D;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IACjC,OAAO;QACL;;;;WAIG;QACH,GAAG,CAAC,GAAW;YACb,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3C,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;KAC1D,CAAC;AACJ,CAAC"}

package/dist/context-theme.d.ts

@@ -1,6 +1,20 @@
 import type { BijouContext } from './ports/context.js';
 import { type ResolvedTheme } from './core/theme/resolve.js';
 import type { Theme } from './core/theme/tokens.js';
+/** Notification emitted when the observed theme graph changes. */
+export interface ThemeChange {
+    /** The context whose theme graph emitted the change. */
+    readonly ctx: BijouContext;
+    /** Token path that changed. `'*'` means broad invalidation after import. */
+    readonly path: string;
+    /** True when the underlying graph requested a full recompute. */
+    readonly fullReload: boolean;
+}
+/** Disposable subscription returned by {@link observeTheme}. */
+export interface ThemeObservation {
+    /** Stop observing future theme changes. */
+    dispose(): void;
+}
 /**
  * Clone a Bijou context with a different already-resolved theme.
  *
@@ -12,4 +26,15 @@ export declare function cloneContextWithResolvedTheme(ctx: BijouContext, theme:
  * Clone a Bijou context with a different theme definition.
  */
 export declare function cloneContextWithTheme(ctx: BijouContext, theme: Theme): BijouContext;
+/**
+ * Observe theme/token updates for a context.
+ *
+ * This is the supported third-party authoring seam for reacting to in-place
+ * token-graph updates. Handlers should invalidate any cached theme-derived
+ * work and re-read tokens through the accessor layer on the provided context.
+ *
+ * When a caller replaces the entire context object, dispose the old
+ * observation and subscribe to the new context instead.
+ */
+export declare function observeTheme(ctx: BijouContext, handler: (change: ThemeChange) => void): ThemeObservation;
 //# sourceMappingURL=context-theme.d.ts.map

package/dist/context-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-theme.d.ts","sourceRoot":"","sources":["../src/context-theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,aAAa,GACnB,YAAY,CAOd;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,KAAK,GACX,YAAY,CAKd"}
+{"version":3,"file":"context-theme.d.ts","sourceRoot":"","sources":["../src/context-theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,aAAa,GACnB,YAAY,CAOd;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,KAAK,GACX,YAAY,CAKd;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,GACrC,gBAAgB,CAQlB"}

package/dist/context-theme.js

@@ -20,4 +20,23 @@ export function cloneContextWithResolvedTheme(ctx, theme) {
 export function cloneContextWithTheme(ctx, theme) {
     return cloneContextWithResolvedTheme(ctx, createResolved(theme, ctx.theme.noColor, ctx.theme.colorScheme));
 }
+/**
+ * Observe theme/token updates for a context.
+ *
+ * This is the supported third-party authoring seam for reacting to in-place
+ * token-graph updates. Handlers should invalidate any cached theme-derived
+ * work and re-read tokens through the accessor layer on the provided context.
+ *
+ * When a caller replaces the entire context object, dispose the old
+ * observation and subscribe to the new context instead.
+ */
+export function observeTheme(ctx, handler) {
+    return ctx.tokenGraph.on((path) => {
+        handler({
+            ctx,
+            path,
+            fullReload: path === '*',
+        });
+    });
+}
 //# sourceMappingURL=context-theme.js.map

package/dist/context-theme.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-theme.js","sourceRoot":"","sources":["../src/context-theme.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAsB,MAAM,yBAAyB,CAAC;AAG7E;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,GAAiB,EACjB,KAAoB;IAEpB,OAAO;QACL,GAAG,GAAG;QACN,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,oBAAoB,CAAC,KAAK,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAiB,EACjB,KAAY;IAEZ,OAAO,6BAA6B,CAClC,GAAG,EACH,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAChE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"context-theme.js","sourceRoot":"","sources":["../src/context-theme.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAsB,MAAM,yBAAyB,CAAC;AAmB7E;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,GAAiB,EACjB,KAAoB;IAEpB,OAAO;QACL,GAAG,GAAG;QACN,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,oBAAoB,CAAC,KAAK,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAiB,EACjB,KAAY;IAEZ,OAAO,6BAA6B,CAClC,GAAG,EACH,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAChE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAiB,EACjB,OAAsC;IAEtC,OAAO,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE;QAChC,OAAO,CAAC;YACN,GAAG;YACH,IAAI;YACJ,UAAU,EAAE,IAAI,KAAK,GAAG;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/context.d.ts

@@ -18,7 +18,19 @@ export declare function getDefaultContext(): BijouContext;
  */
 export declare function setDefaultContext(ctx: BijouContext): void;
 /**
- * Reset the default context to `null`.
+ * Register a lazy initializer for the global default {@link BijouContext}.
+ *
+ * Host adapters can use this to provide ambient context bootstrapping without
+ * forcing higher-level runtime packages to depend on host-specific modules.
+ *
+ * The initializer is invoked only when {@link getDefaultContext} is called and
+ * no explicit default has been set yet.
+ *
+ * @param initializer - Lazy factory for the default context, or `null` to clear it.
+ */
+export declare function setDefaultContextInitializer(initializer: (() => BijouContext) | null): void;
+/**
+ * Reset the default context and lazy initializer.
  *
  * **Test-only** — ensures isolation between test cases.
  */

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAShD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAchD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,CAAC,MAAM,YAAY,CAAC,GAAG,IAAI,GACvC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAGrD"}

package/dist/context.js

@@ -1,4 +1,5 @@
 let defaultContext = null;
+let defaultContextInitializer = null;
 /**
  * Retrieve the global default {@link BijouContext}.
  *
@@ -8,9 +9,14 @@ let defaultContext = null;
  */
 export function getDefaultContext() {
     if (defaultContext === null) {
+        if (defaultContextInitializer != null) {
+            defaultContext = defaultContextInitializer();
+            return defaultContext;
+        }
         throw new Error('[bijou] No default context configured. ' +
-            'Import @flyingrobots/bijou-node to auto-configure, ' +
-            'or call setDefaultContext() explicitly.');
+            'Import @flyingrobots/bijou-node to register Node auto-init, ' +
+            'call startApp(app), or call setDefaultContext() explicitly. ' +
+            'Guide: https://github.com/flyingrobots/bijou/tree/main/packages/bijou-node/GUIDE.md#basic-setup');
     }
     return defaultContext;
 }
@@ -27,11 +33,26 @@ export function setDefaultContext(ctx) {
     defaultContext = ctx;
 }
 /**
- * Reset the default context to `null`.
+ * Register a lazy initializer for the global default {@link BijouContext}.
+ *
+ * Host adapters can use this to provide ambient context bootstrapping without
+ * forcing higher-level runtime packages to depend on host-specific modules.
+ *
+ * The initializer is invoked only when {@link getDefaultContext} is called and
+ * no explicit default has been set yet.
+ *
+ * @param initializer - Lazy factory for the default context, or `null` to clear it.
+ */
+export function setDefaultContextInitializer(initializer) {
+    defaultContextInitializer = initializer;
+}
+/**
+ * Reset the default context and lazy initializer.
  *
  * **Test-only** — ensures isolation between test cases.
  */
 export function _resetDefaultContextForTesting() {
     defaultContext = null;
+    defaultContextInitializer = null;
 }
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,IAAI,cAAc,GAAwB,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,qDAAqD;YACrD,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B;IAC5C,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,IAAI,cAAc,GAAwB,IAAI,CAAC;AAC/C,IAAI,yBAAyB,GAAgC,IAAI,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,IAAI,yBAAyB,IAAI,IAAI,EAAE,CAAC;YACtC,cAAc,GAAG,yBAAyB,EAAE,CAAC;YAC7C,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,8DAA8D;YAC9D,8DAA8D;YAC9D,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,4BAA4B,CAC1C,WAAwC;IAExC,yBAAyB,GAAG,WAAW,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B;IAC5C,cAAc,GAAG,IAAI,CAAC;IACtB,yBAAyB,GAAG,IAAI,CAAC;AACnC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"alert-v3.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert-v3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,YAAY,CAAC;AAkBlE;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAkB3F"}
+{"version":3,"file":"alert-v3.d.ts","sourceRoot":"","sources":["../../../src/core/components/alert-v3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,YAAY,CAAC;AAmBlE;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAkB3F"}

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

@@ -2,11 +2,12 @@ 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';
+import { forceTextPresentation } from '../text/icon-presentation.js';
 const ICONS = {
-    success: '\u2713', // ✓
-    error: '\u2717', // ✗
-    warning: '\u26A0', // ⚠
-    info: '\u2139', // ℹ
+    success: forceTextPresentation('\u2713'), // ✓
+    error: forceTextPresentation('\u2717'), // ✗
+    warning: forceTextPresentation('\u26A0'), // ⚠
+    info: forceTextPresentation('\u2139'), // ℹ
 };
 const BORDER_TOKENS = {
     success: 'success',

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

@@ -1 +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,EAAG,IAAI;IACxB,KAAK,EAAE,QAAQ,EAAK,IAAI;IACxB,OAAO,EAAE,QAAQ,EAAG,IAAI;IACxB,IAAI,EAAE,QAAQ,EAAM,IAAI;CACzB,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"}
+{"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;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,IAAI;IAC9C,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAI,IAAI;IAC9C,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,IAAI;IAC9C,IAAI,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAK,IAAI;CAC/C,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.map

@@ -1 +1 @@
-{"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;AAyCD;;;;;;;;;;;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;AAGnD,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;AAuCD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAsBzE"}

package/dist/core/components/alert.js

@@ -1,19 +1,18 @@
 import { resolveCtx } from '../resolve-ctx.js';
 import { box } from './box.js';
 import { renderByMode } from '../mode-render.js';
+import { forceTextPresentation } from '../text/icon-presentation.js';
 /**
  * Unicode icon characters for each alert variant.
  *
- * ✓ (U+2713) and ✗ (U+2717) are Narrow per Unicode East Asian Width.
- * ⚠ (U+26A0) and ℹ (U+2139) are Ambiguous — 1-wide in terminals,
- * potentially 2-wide in some chat UIs. We treat them as 1-wide here
- * since graphemeWidth correctly classifies them as Narrow.
+ * The symbols are forced into text presentation with VS15 (U+FE0E) so
+ * chat UIs and web terminals do not widen them into emoji presentation.
  */
 const ICONS = {
-    success: '\u2713', // ✓ CHECK MARK
-    error: '\u2717', // ✗ BALLOT X
-    warning: '\u26A0', // ⚠ WARNING SIGN
-    info: '\u2139', // ℹ INFORMATION SOURCE
+    success: forceTextPresentation('\u2713'), // ✓ CHECK MARK
+    error: forceTextPresentation('\u2717'), // ✗ BALLOT X
+    warning: forceTextPresentation('\u26A0'), // ⚠ WARNING SIGN
+    info: forceTextPresentation('\u2139'), // ℹ INFORMATION SOURCE
 };
 /** Uppercase labels used in pipe mode output. */
 const PIPE_LABELS = {

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

@@ -1 +1 @@
-{"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;;;;;;;GAOG;AACH,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,QAAQ,EAAG,eAAe;IACnC,KAAK,EAAE,QAAQ,EAAK,aAAa;IACjC,OAAO,EAAE,QAAQ,EAAG,iBAAiB;IACrC,IAAI,EAAE,QAAQ,EAAM,uBAAuB;CAC5C,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"}
+{"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;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAerE;;;;;GAKG;AACH,MAAM,KAAK,GAAiC;IAC1C,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,eAAe;IACzD,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAI,aAAa;IACvD,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,iBAAiB;IAC3D,IAAI,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAK,uBAAuB;CAClE,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.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,OAAO,EAAiC,MAAM,wBAAwB,CAAC;AACpG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,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,CA6DvE"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/core/components/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,OAAO,EAAa,MAAM,wBAAwB,CAAC;AACjG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,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,CA+DvE"}

package/dist/core/components/badge.js

@@ -1,8 +1,10 @@
-import { createSurface } from '../../ports/surface.js';
+import { createSurface, isPackedSurface } from '../../ports/surface.js';
+import { colorRgb } from '../theme/color.js';
 import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
-import { segmentGraphemes } from '../text/grapheme.js';
+import { graphemeWidth, sanitizePlainTerminalText } from '../text/index.js';
 import { applyBCSSCellTextStyles } from './bcss-style.js';
-import { parseHex, encodeModifiers } from '../render/packed-cell.js';
+import { encodeModifiers } from '../render/packed-cell.js';
+import { segmentSurfaceText } from './surface-text.js';
 /**
  * Render an inline badge (pill-shaped label) for the given text.
  *
@@ -15,14 +17,15 @@ import { parseHex, encodeModifiers } from '../render/packed-cell.js';
 export function badge(text, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const variant = options.variant ?? 'info';
-    const paddedText = ` ${text} `;
-    const graphemes = segmentGraphemes(paddedText);
+    const safeText = sanitizePlainTerminalText(text ?? '');
+    const paddedText = ` ${safeText} `;
+    const graphemes = segmentSurfaceText(paddedText, 'badge');
     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);
+        const char = ctx?.mode === 'pipe' ? `[${safeText}]` : paddedText;
+        return stringToSurface(char, graphemeWidth(char), 1);
     }
     // Resolve global CSS styles
     const bcss = ctx.resolveBCSS({ type: 'Badge', id: options.id, classes: options.class?.split(' ') });
@@ -48,23 +51,21 @@ export function badge(text, options = {}) {
     if (bcss['background']) {
         cell.modifiers = cell.modifiers?.filter(m => m !== 'inverse');
     }
-    const packed = 'buffer' in surface;
-    if (packed && cell.fg) {
-        const fg = parseHex(cell.fg);
+    const packedSurface = isPackedSurface(surface) ? surface : undefined;
+    if (packedSurface) {
+        const fg = cell.fgRGB ?? colorRgb(cell.fg);
         if (fg) {
             const [fR, fG, fB] = fg;
             let bR = -1, bG = 0, bB = 0;
-            if (cell.bg) {
-                const bg = parseHex(cell.bg);
-                if (bg) {
-                    bR = bg[0];
-                    bG = bg[1];
-                    bB = bg[2];
-                }
+            const bg = cell.bgRGB ?? colorRgb(cell.bg);
+            if (bg) {
+                bR = bg[0];
+                bG = bg[1];
+                bB = bg[2];
             }
             const flags = encodeModifiers(cell.modifiers);
             for (let i = 0; i < width; i++) {
-                surface.setRGB(i, 0, graphemes[i], fR, fG, fB, bR, bG, bB, flags);
+                packedSurface.setRGB(i, 0, graphemes[i], fR, fG, fB, bR, bG, bB, flags);
             }
         }
         else {

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"box-v3.d.ts","sourceRoot":"","sources":["../../../src/core/components/box-v3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,OAAO,EAAiC,MAAM,wBAAwB,CAAC;AAIpG,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA0EnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAmIvF;AACD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAmBvF"}
+{"version":3,"file":"box-v3.d.ts","sourceRoot":"","sources":["../../../src/core/components/box-v3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,OAAO,EAAa,MAAM,wBAAwB,CAAC;AAMjG,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA4EnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAoIvF;AACD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAmBvF"}

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

@@ -1,34 +1,33 @@
-import { createSurface } from '../../ports/surface.js';
+import { createSurface, isPackedSurface } from '../../ports/surface.js';
 import { resolveSafeCtx as resolveCtx } from '../resolve-ctx.js';
+import { colorHex, colorRgb } from '../theme/color.js';
 import { clipToWidth } from '../text/clip.js';
+import { sanitizePlainTerminalText } from '../text/index.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';
-import { parseHex, encodeModifiers, CELL_STRIDE, OFF_FLAGS, OFF_ALPHA, FLAG_EMPTY, FLAG_BG_SET } from '../render/packed-cell.js';
-function isPackedSurface(s) {
-    return 'buffer' in s && s.buffer instanceof Uint8Array;
-}
+import { encodeModifiers, CELL_STRIDE, OFF_FLAGS, OFF_ALPHA, FLAG_EMPTY, FLAG_BG_SET } from '../render/packed-cell.js';
 /** Pre-parse a CellTextStyle into numeric RGB + flags for setRGB. Returns undefined if not parseable. */
 function parseStyleRGB(style) {
     let fgR = -1, fgG = 0, fgB = 0;
     let bgR = -1, bgG = 0, bgB = 0;
-    if (style.fg) {
-        const rgb = parseHex(style.fg);
-        if (!rgb)
-            return undefined;
-        fgR = rgb[0];
-        fgG = rgb[1];
-        fgB = rgb[2];
+    const fgRgb = style.fgRGB ?? colorRgb(style.fg);
+    if (style.fg != null && fgRgb == null)
+        return undefined;
+    if (fgRgb) {
+        fgR = fgRgb[0];
+        fgG = fgRgb[1];
+        fgB = fgRgb[2];
     }
-    if (style.bg) {
-        const rgb = parseHex(style.bg);
-        if (!rgb)
-            return undefined;
-        bgR = rgb[0];
-        bgG = rgb[1];
-        bgB = rgb[2];
+    const bgRgb = style.bgRGB ?? colorRgb(style.bg);
+    if (style.bg != null && bgRgb == null)
+        return undefined;
+    if (bgRgb) {
+        bgR = bgRgb[0];
+        bgG = bgRgb[1];
+        bgB = bgRgb[2];
     }
     return { fgR, fgG, fgB, bgR, bgG, bgB, flags: encodeModifiers(style.modifiers) };
 }
@@ -46,7 +45,7 @@ function withInheritedBackground(surface, background) {
     const next = surface.clone();
     if (isPackedSurface(next)) {
         // Fast path: write bg bytes directly into the buffer
-        const bgRGB = parseHex(background);
+        const bgRGB = colorRgb(background);
         if (bgRGB) {
             const buf = next.buffer;
             const [bgR, bgG, bgB] = bgRGB;
@@ -71,7 +70,7 @@ function withInheritedBackground(surface, background) {
             const cell = next.get(x, y);
             if (cell.empty || cell.bg != null)
                 continue;
-            next.set(x, y, { ...cell, bg: background });
+            next.set(x, y, { ...cell, bg: colorHex(background) });
         }
     }
     return next;
@@ -84,6 +83,7 @@ function withInheritedBackground(surface, background) {
 export function boxSurface(content, options = {}) {
     const ctx = resolveCtx(options.ctx);
     const { title, width: fixedWidth, padding = {} } = options;
+    const safeTitle = title != null ? sanitizePlainTerminalText(title) : '';
     const bcss = ctx?.resolveBCSS({ type: 'Box', id: options.id, classes: options.class?.split(' ') }) ?? {};
     const overflow = resolveOverflowBehavior(options.overflow, bcss);
     const normalizedFixedWidth = normalizeFixedWidth(fixedWidth);
@@ -103,8 +103,8 @@ export function boxSurface(content, options = {}) {
             ? wrapSurfaceToWidth(content, Math.max(0, normalizedFixedWidth - 2 - pl - pr))
             : content;
     }
-    const autoTitleWidth = normalizedFixedWidth === undefined && title
-        ? segmentSurfaceText(` ${title} `, 'boxSurface title').length
+    const autoTitleWidth = normalizedFixedWidth === undefined && safeTitle.length > 0
+        ? segmentSurfaceText(` ${safeTitle} `, 'boxSurface title').length
         : 0;
     const innerW = normalizedFixedWidth === undefined
         ? Math.max(contentSurf.width + pl + pr, autoTitleWidth)
@@ -153,9 +153,9 @@ export function boxSurface(content, options = {}) {
         surface.setRGB(outerW - 1, 0, BORDER.tr, fgR, fgG, fgB, bgR, bgG, bgB, flags);
         surface.setRGB(0, outerH - 1, BORDER.bl, fgR, fgG, fgB, bgR, bgG, bgB, flags);
         surface.setRGB(outerW - 1, outerH - 1, BORDER.br, fgR, fgG, fgB, bgR, bgG, bgB, flags);
-        if (title && outerW >= 4) {
+        if (safeTitle.length > 0 && outerW >= 4) {
             const available = Math.max(0, outerW - 4);
-            const titleText = clipToWidth(` ${title} `, available);
+            const titleText = clipToWidth(` ${safeTitle} `, available);
             const titleGs = segmentSurfaceText(titleText, 'boxSurface title');
             const titleLen = Math.min(titleGs.length, available);
             for (let i = 0; i < titleLen; i++) {
@@ -182,9 +182,9 @@ export function boxSurface(content, options = {}) {
         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 });
-        if (title && outerW >= 4) {
+        if (safeTitle.length > 0 && outerW >= 4) {
             const available = Math.max(0, outerW - 4);
-            const titleText = clipToWidth(` ${title} `, available);
+            const titleText = clipToWidth(` ${safeTitle} `, available);
             const titleGs = segmentSurfaceText(titleText, 'boxSurface title');
             const titleLen = Math.min(titleGs.length, available);
             for (let i = 0; i < titleLen; i++) {
@@ -204,8 +204,8 @@ export function boxSurface(content, options = {}) {
  */
 export function headerBoxSurface(label, options = {}) {
     const ctx = resolveCtx(options.ctx);
-    const safeLabel = label ?? '';
-    const detail = options.detail ?? '';
+    const safeLabel = sanitizePlainTerminalText(label ?? '');
+    const detail = sanitizePlainTerminalText(options.detail ?? '');
     const labelToken = options.labelToken ?? ctx?.semantic('primary');
     const mutedToken = ctx?.semantic('muted');
     const segments = [];