@flyingrobots/bijou-tui 4.4.1 → 7.0.0

package/dist/subapp/mount.d.ts

@@ -33,6 +33,13 @@ export interface MountedApp<SubMsg> {
      */
     cmds: Cmd<SubMsg>[];
 }
+export type SubAppAdapterCases<ParentMsg, SubMsg extends {
+    readonly type: string;
+}> = {
+    readonly [K in SubMsg['type']]: (msg: Extract<SubMsg, {
+        type: K;
+    }>) => ParentMsg;
+};
 /**
  * Mount a sub-app, returning its rendered surface and any pending commands.
  *
@@ -45,6 +52,16 @@ export interface MountedApp<SubMsg> {
  * @returns A tuple of `[Surface | LayoutNode, mapped Cmds]`.
  */
 export declare function mount<SubModel, SubMsg, ParentMsg>(app: App<SubModel, SubMsg>, options: MountOptions<SubModel, SubMsg, ParentMsg>): [ViewOutput, Cmd<ParentMsg>[]];
+/**
+ * Build an exhaustive discriminant-based sub-app message mapper.
+ *
+ * The returned function matches the `onMsg` signature expected by
+ * `initSubApp()`, `updateSubApp()`, and `mount()`, while TypeScript enforces
+ * that every `SubMsg['type']` variant is covered up front.
+ */
+export declare function createSubAppAdapter<ParentMsg, SubMsg extends {
+    readonly type: string;
+}>(cases: SubAppAdapterCases<ParentMsg, SubMsg>): (msg: SubMsg) => ParentMsg;
 export interface SubAppOptions<SubMsg, ParentMsg> {
     /** Function to map a sub-app message into a parent message. */
     onMsg: (msg: SubMsg) => ParentMsg;

package/dist/subapp/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAc,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS;IACvD,wCAAwC;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM;IAChC,0DAA0D;IAC1D,aAAa,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAC/C,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,GACjD,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAMhC;AAED,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,SAAS;IAC9C,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACpD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACtD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EACvC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,GACjC,GAAG,CAAC,SAAS,CAAC,EAAE,CAElB"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAc,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS;IACvD,wCAAwC;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM;IAChC,0DAA0D;IAC1D,aAAa,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,kBAAkB,CAAC,SAAS,EAAE,MAAM,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI;IACpF,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,SAAS;CACjF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAC/C,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,GACjD,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAMhC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACrF,KAAK,EAAE,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,GAC3C,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAK5B;AAED,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,SAAS;IAC9C,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACpD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACtD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EACvC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,GACjC,GAAG,CAAC,SAAS,CAAC,EAAE,CAElB"}

package/dist/subapp/mount.js

@@ -15,6 +15,19 @@ export function mount(app, options) {
     const surfaceOrNode = app.view(model);
     return [surfaceOrNode, []];
 }
+/**
+ * Build an exhaustive discriminant-based sub-app message mapper.
+ *
+ * The returned function matches the `onMsg` signature expected by
+ * `initSubApp()`, `updateSubApp()`, and `mount()`, while TypeScript enforces
+ * that every `SubMsg['type']` variant is covered up front.
+ */
+export function createSubAppAdapter(cases) {
+    return (msg) => {
+        const handler = cases[msg.type];
+        return handler(msg);
+    };
+}
 export function initSubApp(app, options) {
     const [model, cmds] = app.init();
     return [model, mapSubAppCmds(cmds, options)];

package/dist/subapp/mount.js.map

@@ -1 +1 @@
-{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsC3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,GAA0B,EAC1B,OAAkD;IAElD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAE1B,MAAM,aAAa,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEtC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAYD,MAAM,UAAU,UAAU,CACxB,GAA0B,EAC1B,OAAyC;IAEzC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,GAA0B,EAC1B,GAAW,EACX,KAAe,EACf,OAAyC;IAEzC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,SAAS,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,IAAmB,EACnB,MAAkC;IAElC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,aAAa,CACpB,IAAmB,EACnB,OAAyC;IAEzC,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,GAAgB,EAChB,MAAkC;IAElC,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1B,8DAA8D;QAC9D,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,EAAE;YACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAE3C,sDAAsD;QACtD,6CAA6C;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAoB,CAAC,CAAC,OAAO;QACpE,IAAI,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QACxC,OAAO,MAAM,CAAC,MAAgB,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0C3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,GAA0B,EAC1B,OAAkD;IAElD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAE1B,MAAM,aAAa,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEtC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA4C;IAE5C,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAmD,CAA+B,CAAC;QAC7G,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC;AAYD,MAAM,UAAU,UAAU,CACxB,GAA0B,EAC1B,OAAyC;IAEzC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,GAA0B,EAC1B,GAAW,EACX,KAAe,EACf,OAAyC;IAEzC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,SAAS,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,IAAmB,EACnB,MAAkC;IAElC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,aAAa,CACpB,IAAmB,EACnB,OAAyC;IAEzC,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,GAAgB,EAChB,MAAkC;IAElC,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1B,8DAA8D;QAC9D,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,EAAE;YACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAE3C,sDAAsD;QACtD,6CAA6C;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAoB,CAAC,CAAC,OAAO;QACpE,IAAI,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QACxC,OAAO,MAAM,CAAC,MAAgB,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC"}

package/dist/surface-budget.d.ts

@@ -0,0 +1,27 @@
+import { type Surface } from '@flyingrobots/bijou';
+import { type RenderStage, type RenderStageTiming } from './pipeline/pipeline.js';
+export type SurfaceBudgetMetric = 'surface-width' | 'surface-height' | 'surface-area' | 'styled-cells' | 'frame-duration' | 'stage-duration';
+export interface SurfaceBudgetThresholds {
+    readonly maxWidth?: number;
+    readonly maxHeight?: number;
+    readonly maxArea?: number;
+    readonly maxStyledCells?: number;
+    readonly maxFrameDurationMs?: number;
+    readonly maxStageDurationMs?: Partial<Record<RenderStage, number>>;
+}
+export interface EvaluateSurfaceBudgetOptions {
+    readonly surface: Surface;
+    readonly thresholds: SurfaceBudgetThresholds;
+    readonly timings?: readonly RenderStageTiming[];
+    readonly label?: string;
+}
+export interface SurfaceBudgetWarning {
+    readonly label: string;
+    readonly metric: SurfaceBudgetMetric;
+    readonly actual: number;
+    readonly limit: number;
+    readonly message: string;
+    readonly stage?: RenderStage;
+}
+export declare function evaluateSurfaceBudget(options: EvaluateSurfaceBudgetOptions): readonly SurfaceBudgetWarning[];
+//# sourceMappingURL=surface-budget.d.ts.map

package/dist/surface-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-budget.d.ts","sourceRoot":"","sources":["../src/surface-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElF,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,gBAAgB,CAAC;AAErB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAOD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,SAAS,oBAAoB,EAAE,CAgDjC"}

package/dist/surface-budget.js

@@ -0,0 +1,61 @@
+const DEFAULT_SURFACE_BUDGET_LABEL = 'surface';
+const MILLISECOND_UNIT = 'ms';
+const HUNDREDTHS = 100;
+const OPAQUE_OPACITY = 1;
+export function evaluateSurfaceBudget(options) {
+    const { surface, thresholds, timings = [], label = DEFAULT_SURFACE_BUDGET_LABEL } = options;
+    const warnings = [];
+    pushBudgetWarning(warnings, label, 'surface-width', surface.width, thresholds.maxWidth);
+    pushBudgetWarning(warnings, label, 'surface-height', surface.height, thresholds.maxHeight);
+    pushBudgetWarning(warnings, label, 'surface-area', surface.width * surface.height, thresholds.maxArea);
+    if (thresholds.maxStyledCells !== undefined) {
+        pushBudgetWarning(warnings, label, 'styled-cells', countStyledCells(surface), thresholds.maxStyledCells);
+    }
+    pushBudgetWarning(warnings, label, 'frame-duration', timings.reduce((total, timing) => total + timing.durationMs, 0), thresholds.maxFrameDurationMs, MILLISECOND_UNIT);
+    if (thresholds.maxStageDurationMs !== undefined) {
+        for (const timing of timings) {
+            pushBudgetWarning(warnings, label, 'stage-duration', timing.durationMs, thresholds.maxStageDurationMs[timing.stage], MILLISECOND_UNIT, timing.stage);
+        }
+    }
+    return warnings;
+}
+function pushBudgetWarning(warnings, label, metric, actual, limit, unit = '', stage) {
+    if (limit === undefined || !Number.isFinite(limit) || actual <= limit) {
+        return;
+    }
+    warnings.push({
+        label,
+        metric,
+        actual,
+        limit,
+        stage,
+        message: surfaceBudgetMessage(label, metric, actual, limit, unit, stage),
+    });
+}
+function surfaceBudgetMessage(label, metric, actual, limit, unit, stage) {
+    const metricLabel = stage === undefined ? metric : `${metric} ${stage}`;
+    return `${label} ${metricLabel} ${formatBudgetNumber(actual)}${unit} > ${formatBudgetNumber(limit)}${unit}`;
+}
+function formatBudgetNumber(value) {
+    return String(Math.round(value * HUNDREDTHS) / HUNDREDTHS);
+}
+function countStyledCells(surface) {
+    let count = 0;
+    for (let y = 0; y < surface.height; y++) {
+        for (let x = 0; x < surface.width; x++) {
+            if (isStyledCell(surface.get(x, y))) {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+function isStyledCell(cell) {
+    return cell.fg !== undefined
+        || cell.bg !== undefined
+        || cell.fgRGB !== undefined
+        || cell.bgRGB !== undefined
+        || (cell.modifiers?.length ?? 0) > 0
+        || (cell.opacity !== undefined && cell.opacity < OPAQUE_OPACITY);
+}
+//# sourceMappingURL=surface-budget.js.map

package/dist/surface-budget.js.map

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

package/dist/surface-diff.d.ts

@@ -0,0 +1,36 @@
+import { type Cell, type Surface } from '@flyingrobots/bijou';
+export type SurfaceDiffCellKind = 'char' | 'style';
+export type SurfaceDiffRenderMode = 'side-by-side' | 'overlay';
+export interface SurfaceDiffBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface SurfaceDiffCell {
+    readonly x: number;
+    readonly y: number;
+    readonly kind: SurfaceDiffCellKind;
+    readonly before: Cell;
+    readonly after: Cell;
+}
+export interface SurfaceDiff {
+    readonly width: number;
+    readonly height: number;
+    readonly beforeWidth: number;
+    readonly beforeHeight: number;
+    readonly afterWidth: number;
+    readonly afterHeight: number;
+    readonly changedCells: number;
+    readonly charChanges: number;
+    readonly styleOnlyChanges: number;
+    readonly bounds: SurfaceDiffBounds | undefined;
+    readonly cells: readonly SurfaceDiffCell[];
+}
+export interface SurfaceDiffRenderOptions {
+    readonly mode?: SurfaceDiffRenderMode;
+}
+export declare function diffSurfaces(before: Surface, after: Surface): SurfaceDiff;
+export declare function surfaceDiffSurface(before: Surface, after: Surface, options?: SurfaceDiffRenderOptions): Surface;
+export declare function surfaceDiffText(before: Surface, after: Surface, options?: SurfaceDiffRenderOptions): string;
+//# sourceMappingURL=surface-diff.d.ts.map

package/dist/surface-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-diff.d.ts","sourceRoot":"","sources":["../src/surface-diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE7E,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,CAAC;AACnD,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,WAAW,CA2DzE;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAQT;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAiBR"}

package/dist/surface-diff.js

@@ -0,0 +1,202 @@
+import { createSurface } from '@flyingrobots/bijou';
+const EMPTY_CELL = Object.freeze({ char: ' ', empty: true });
+export function diffSurfaces(before, after) {
+    const width = Math.max(before.width, after.width);
+    const height = Math.max(before.height, after.height);
+    const cells = [];
+    let charChanges = 0;
+    let styleOnlyChanges = 0;
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const beforeCell = cellAt(before, x, y);
+            const afterCell = cellAt(after, x, y);
+            const charChanged = cellGlyphKey(beforeCell) !== cellGlyphKey(afterCell);
+            const styleChanged = cellStyleKey(beforeCell) !== cellStyleKey(afterCell);
+            if (!charChanged && !styleChanged) {
+                continue;
+            }
+            const kind = charChanged ? 'char' : 'style';
+            if (kind === 'char') {
+                charChanges++;
+            }
+            else {
+                styleOnlyChanges++;
+            }
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, y);
+            maxX = Math.max(maxX, x);
+            maxY = Math.max(maxY, y);
+            cells.push({ x, y, kind, before: beforeCell, after: afterCell });
+        }
+    }
+    const bounds = cells.length === 0
+        ? undefined
+        : {
+            x: minX,
+            y: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+        };
+    return {
+        width,
+        height,
+        beforeWidth: before.width,
+        beforeHeight: before.height,
+        afterWidth: after.width,
+        afterHeight: after.height,
+        changedCells: cells.length,
+        charChanges,
+        styleOnlyChanges,
+        bounds,
+        cells,
+    };
+}
+export function surfaceDiffSurface(before, after, options = {}) {
+    const diff = diffSurfaces(before, after);
+    const mode = options.mode ?? 'side-by-side';
+    const lines = mode === 'overlay'
+        ? overlayLines(diff, after)
+        : sideBySideLines(diff, before, after);
+    return linesToSurface(lines, diff);
+}
+export function surfaceDiffText(before, after, options = {}) {
+    const diff = diffSurfaces(before, after);
+    const lines = [
+        summaryLine(diff),
+        boundsLine(diff),
+        `mode: ${options.mode ?? 'side-by-side'}`,
+    ];
+    for (const cell of diff.cells) {
+        if (cell.kind === 'char') {
+            lines.push(`(${cell.x},${cell.y}) char ${quoteChar(cell.before)} -> ${quoteChar(cell.after)}`);
+        }
+        else {
+            lines.push(`(${cell.x},${cell.y}) style ${styleLabel(cell.before)} -> ${styleLabel(cell.after)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function cellAt(surface, x, y) {
+    if (x < 0 || y < 0 || x >= surface.width || y >= surface.height) {
+        return EMPTY_CELL;
+    }
+    return surface.get(x, y);
+}
+function cellGlyphKey(cell) {
+    return `${cell.empty === true ? 'empty' : 'paint'}:${cell.char}`;
+}
+function cellStyleKey(cell) {
+    return JSON.stringify({
+        fg: cell.fg ?? null,
+        bg: cell.bg ?? null,
+        fgRGB: cell.fgRGB ?? null,
+        bgRGB: cell.bgRGB ?? null,
+        modifiers: cell.modifiers ?? null,
+        opacity: cell.opacity ?? null,
+    });
+}
+function sideBySideLines(diff, before, after) {
+    const beforeWidth = Math.max(6, before.width);
+    const afterWidth = Math.max(5, after.width);
+    const lines = [
+        summaryLine(diff),
+        boundsLine(diff),
+        `${'before'.padEnd(beforeWidth)} | ${'after'.padEnd(afterWidth)}`,
+    ];
+    for (let y = 0; y < diff.height; y++) {
+        lines.push(`${surfaceRow(before, y, beforeWidth).trimEnd()} | ${surfaceRow(after, y, afterWidth).trimEnd()}`);
+    }
+    return lines;
+}
+function overlayLines(diff, after) {
+    const overlayWidth = Math.max(1, diff.width);
+    const lines = [
+        summaryLine(diff),
+        boundsLine(diff),
+        'overlay',
+    ];
+    const changed = new Map(diff.cells.map((cell) => [`${cell.x},${cell.y}`, cell.kind]));
+    for (let y = 0; y < diff.height; y++) {
+        let row = '';
+        let markers = '';
+        for (let x = 0; x < overlayWidth; x++) {
+            row += displayChar(cellAt(after, x, y));
+            const kind = changed.get(`${x},${y}`);
+            markers += kind === 'char' ? '!' : kind === 'style' ? '~' : '.';
+        }
+        lines.push(row, markers);
+    }
+    return lines;
+}
+function linesToSurface(lines, diff) {
+    const width = Math.max(1, ...lines.map((line) => line.length));
+    const surface = createSurface(width, lines.length);
+    const changed = new Map(diff.cells.map((cell) => [`${cell.x},${cell.y}`, cell.kind]));
+    const overlayStart = lines.indexOf('overlay') + 1;
+    for (let y = 0; y < lines.length; y++) {
+        const line = lines[y] ?? '';
+        for (let x = 0; x < line.length; x++) {
+            const style = overlayStart > 0 && y >= overlayStart && ((y - overlayStart) % 2 === 0)
+                ? changedStyle(changed.get(`${x},${Math.floor((y - overlayStart) / 2)}`))
+                : {};
+            surface.set(x, y, { char: line[x] ?? ' ', empty: false, ...style });
+        }
+    }
+    return surface;
+}
+function changedStyle(kind) {
+    if (kind === 'char') {
+        return { fg: '#111111', bg: '#ffcc00' };
+    }
+    if (kind === 'style') {
+        return { fg: '#111111', bg: '#66ccff' };
+    }
+    return {};
+}
+function surfaceRow(surface, y, width) {
+    let row = '';
+    for (let x = 0; x < width; x++) {
+        row += displayChar(cellAt(surface, x, y));
+    }
+    return row;
+}
+function displayChar(cell) {
+    return cell.empty === true || cell.char === '' ? ' ' : cell.char;
+}
+function summaryLine(diff) {
+    return `surface diff: ${diff.changedCells} changed, ${diff.charChanges} char, ${diff.styleOnlyChanges} style`;
+}
+function boundsLine(diff) {
+    if (diff.bounds === undefined) {
+        return 'bounds: none';
+    }
+    return `bounds: x=${diff.bounds.x} y=${diff.bounds.y} w=${diff.bounds.width} h=${diff.bounds.height}`;
+}
+function quoteChar(cell) {
+    return JSON.stringify(displayChar(cell));
+}
+function styleLabel(cell) {
+    return [
+        `fg=${colorLabel(cell.fg)}`,
+        `bg=${colorLabel(cell.bg)}`,
+        `fgRGB=${rgbLabel(cell.fgRGB)}`,
+        `bgRGB=${rgbLabel(cell.bgRGB)}`,
+        `modifiers=${cell.modifiers?.join('+') ?? 'none'}`,
+        `opacity=${cell.opacity ?? 'default'}`,
+    ].join(' ');
+}
+function colorLabel(value) {
+    if (value == null)
+        return 'default';
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+function rgbLabel(value) {
+    return value === undefined ? 'default' : value.join(',');
+}
+//# sourceMappingURL=surface-diff.js.map

package/dist/surface-diff.js.map

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

package/dist/surface-layout.d.ts

@@ -1,13 +1,29 @@
 import { type Surface } from '@flyingrobots/bijou';
 import type { PlaceOptions } from './layout.js';
+export type SurfaceContent = string | Surface;
+export interface ProseSurfaceOptions {
+    readonly width: number;
+}
+/**
+ * Bridge raw text into surface-land at the composition edge.
+ */
+export declare function contentSurface(content: string): Surface;
+/**
+ * Bridge prose text into surface-land after wrapping at word boundaries.
+ *
+ * Use this for paragraph-like text that should reflow inside a known column
+ * width. Keep `contentSurface()` for preformatted output, tables, boxes, and
+ * other surfaces where callers already control line breaks.
+ */
+export declare function proseSurface(content: string, options: ProseSurfaceOptions): Surface;
 /**
  * Vertical stack for surfaces.
  */
-export declare function vstackSurface(...surfaces: Surface[]): Surface;
+export declare function vstackSurface(...content: SurfaceContent[]): Surface;
 /**
  * Horizontal stack for surfaces with an optional gap.
  */
-export declare function hstackSurface(gap: number, ...surfaces: Surface[]): Surface;
+export declare function hstackSurface(gap: number, ...content: SurfaceContent[]): Surface;
 /**
  * Place a surface within a fixed-size rectangle using horizontal and vertical alignment.
  *
@@ -15,5 +31,5 @@ export declare function hstackSurface(gap: number, ...surfaces: Surface[]): Surf
  * region, mirroring the string-based `place()` behavior. When the content is smaller than
  * the target rectangle, it is aligned within the blank result surface.
  */
-export declare function placeSurface(content: Surface, options: PlaceOptions): Surface;
+export declare function placeSurface(content: SurfaceContent, options: PlaceOptions): Surface;
 //# sourceMappingURL=surface-layout.d.ts.map

package/dist/surface-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-layout.d.ts","sourceRoot":"","sources":["../src/surface-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAe7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAgB1E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAiD7E"}
+{"version":3,"file":"surface-layout.d.ts","sourceRoot":"","sources":["../src/surface-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,OAAO,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAOnF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAgBnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAiBhF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAkDpF"}

package/dist/surface-layout.js

@@ -1,8 +1,33 @@
-import { createSurface } from '@flyingrobots/bijou';
+import { createSurface, graphemeWidth, parseAnsiToSurface, stripAnsi, wrapToWidth, } from '@flyingrobots/bijou';
+/**
+ * Bridge raw text into surface-land at the composition edge.
+ */
+export function contentSurface(content) {
+    const lines = content.split(/\r?\n/);
+    const width = Math.max(1, ...lines.map((line) => graphemeWidth(stripAnsi(line))));
+    const height = Math.max(1, lines.length);
+    return parseAnsiToSurface(content, width, height);
+}
+/**
+ * Bridge prose text into surface-land after wrapping at word boundaries.
+ *
+ * Use this for paragraph-like text that should reflow inside a known column
+ * width. Keep `contentSurface()` for preformatted output, tables, boxes, and
+ * other surfaces where callers already control line breaks.
+ */
+export function proseSurface(content, options) {
+    const finiteWidth = Number.isFinite(options.width) ? options.width : 1;
+    const width = Math.max(1, Math.floor(finiteWidth));
+    const wrapped = wrapToWidth(content, width);
+    const text = wrapped.join('\n');
+    const height = Math.max(1, wrapped.length);
+    return parseAnsiToSurface(text, width, height);
+}
 /**
  * Vertical stack for surfaces.
  */
-export function vstackSurface(...surfaces) {
+export function vstackSurface(...content) {
+    const surfaces = content.map(resolveSurfaceContent);
     if (surfaces.length === 0)
         return createSurface(0, 0);
     const width = Math.max(...surfaces.map(s => s.width));
@@ -18,7 +43,8 @@ export function vstackSurface(...surfaces) {
 /**
  * Horizontal stack for surfaces with an optional gap.
  */
-export function hstackSurface(gap, ...surfaces) {
+export function hstackSurface(gap, ...content) {
+    const surfaces = content.map(resolveSurfaceContent);
     if (surfaces.length === 0)
         return createSurface(0, 0);
     const width = surfaces.reduce((acc, s) => acc + s.width, 0) + (surfaces.length - 1) * gap;
@@ -40,6 +66,7 @@ export function hstackSurface(gap, ...surfaces) {
  * the target rectangle, it is aligned within the blank result surface.
  */
 export function placeSurface(content, options) {
+    const surfaceContent = resolveSurfaceContent(content);
     const width = Math.max(0, Math.floor(options.width));
     const height = Math.max(0, Math.floor(options.height));
     const hAlign = options.hAlign ?? 'left';
@@ -47,16 +74,16 @@ export function placeSurface(content, options) {
     if (width === 0 || height === 0)
         return createSurface(0, 0);
     const result = createSurface(width, height);
-    const clipWidth = Math.min(width, content.width);
-    const clipHeight = Math.min(height, content.height);
+    const clipWidth = Math.min(width, surfaceContent.width);
+    const clipHeight = Math.min(height, surfaceContent.height);
     let col = 0;
-    if (content.width < width) {
+    if (surfaceContent.width < width) {
         switch (hAlign) {
             case 'right':
-                col = width - content.width;
+                col = width - surfaceContent.width;
                 break;
             case 'center':
-                col = Math.floor((width - content.width) / 2);
+                col = Math.floor((width - surfaceContent.width) / 2);
                 break;
             case 'left':
             default:
@@ -65,13 +92,13 @@ export function placeSurface(content, options) {
         }
     }
     let row = 0;
-    if (content.height < height) {
+    if (surfaceContent.height < height) {
         switch (vAlign) {
             case 'bottom':
-                row = height - content.height;
+                row = height - surfaceContent.height;
                 break;
             case 'middle':
-                row = Math.floor((height - content.height) / 2);
+                row = Math.floor((height - surfaceContent.height) / 2);
                 break;
             case 'top':
             default:
@@ -80,8 +107,11 @@ export function placeSurface(content, options) {
         }
     }
     if (clipWidth > 0 && clipHeight > 0) {
-        result.blit(content, Math.max(0, col), Math.max(0, row), 0, 0, clipWidth, clipHeight);
+        result.blit(surfaceContent, Math.max(0, col), Math.max(0, row), 0, 0, clipWidth, clipHeight);
     }
     return result;
 }
+function resolveSurfaceContent(content) {
+    return typeof content === 'string' ? contentSurface(content) : content;
+}
 //# sourceMappingURL=surface-layout.js.map

package/dist/surface-layout.js.map

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

package/dist/types.d.ts

@@ -9,6 +9,7 @@
 import type { BijouContext } from '@flyingrobots/bijou';
 import type { Middleware } from './eventbus.js';
 import type { RenderPipeline } from './pipeline/pipeline.js';
+import type { SurfaceBudgetThresholds } from './surface-budget.js';
 import type { ViewOutput } from './view-output.js';
 /** Represent a keyboard input event with key name and modifier flags. */
 export interface KeyMsg {
@@ -207,6 +208,13 @@ export interface RunOptions<M = any> {
     middlewares?: Middleware<M>[];
     /** Optional hook to extend the render pipeline with custom middleware. */
     configurePipeline?: (pipeline: RenderPipeline) => void;
+    /** Optional non-fatal render budget warnings routed as runtime issues. */
+    surfaceBudget?: SurfaceBudgetThresholds;
+    /**
+     * Pending command count that triggers runtime backpressure diagnostics.
+     * Defaults to 1000. Set to 0 to disable the warning.
+     */
+    commandBackpressureThreshold?: number;
     /** Optional BCSS stylesheet string. */
     css?: string;
 }