@flyingrobots/bijou 4.4.1 → 7.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
@@ -68,11 +76,73 @@ Select the family based on the interaction semantic, not just the visual shape.
 - **`breadcrumb()`**: Path context.
 - **`stepper()`**: Ordered stages in a linear process.
 
+### Theme Authoring
+- **`extendTheme()`**: Build a custom theme from a known-good preset.
+- **`doctorTheme()`**: Structured checks for invalid colors, weak contrast,
+  and suspicious token reuse.
+- **`themeContrastRatio()`**: Deterministic foreground/background contrast
+  calculation for token-pair tests.
+
+### Mode-Aware Authoring
+- **`renderByMode()`**: Dispatch a component to the current output contract.
+- **`lintModeLowering()`**: Compare explicit semantic facts across output modes.
+- **`modeLoweringReportText()`**: Render a compact lowering report for tests,
+  docs, and review comments.
+- **`defineComponentMetadata()`**: Declare validated package, family, mode,
+  arg, variant, invariant, example, and source facts for tooling.
+- **`componentMetadataSummary()`**: Render compact metadata for docs, MCP
+  payloads, and agent-facing reports.
+- **`defineBlock()`**: Declare a validated reusable block with package, family,
+  scale, mode, slot, variant, config, component, story, semantic facts, optional
+  view data contracts, and command intents.
+- **`standardBlocks` / standard block exports**: Import the first-party
+  standard block definitions for AppShell, ReaderSurface, InspectorPanel,
+  inline status, in-flow status, transient overlay feedback, activity stream,
+  shortcut cues, and progress. These expose contracts, stories, data
+  requirements, command intents, and schema-bound posture, with deterministic
+  first-proof render output across all output modes. Production AppShell
+  behavior remains a later runtime slice.
+- **`defineBlockPackage()`**: Declare exported blocks, docs, tags, version, and
+  Bijou peer compatibility for ordinary NPM block packages.
+- **`defineBlockSchemaAdapter()` / `defineSchemaBlock()`**: Validate unknown
+  boundary data before producing immutable block render input and binding facts,
+  without fetching, subscribing, dispatching, or rendering AppShell.
+- **`blockMetadataSummary()`**: Render compact block metadata for docs, MCP
+  payloads, and agent-facing reports.
+- **`defineAppShellComposition()`**: Compose runtime-backed blocks into logical
+  AppShell slots with an explicit provider scope, without rendering or
+  subscribing.
+- **`blockRenderNode()` / `renderBlockTree()`**: Explicitly render nested block
+  declarations into parent slots when a preview or host intentionally wants a
+  block tree, while ordinary `block.render()` remains a local single-block
+  render contract.
+- **`defineDataRequirement()` / `defineDataProvider()` / `providerScope()`**:
+  Declare data requirements and explicit local provider availability without
+  hidden global registration.
+- **`defineViewData()`**: Group named data requirements for a view or block
+  without binding them to providers.
+- **`resolveProviderRequirement()`**: Resolve a requirement against an explicit
+  local provider scope as frozen metadata, without subscribing or fetching.
+- **`bindingFrameFromSnapshots()`**: Assemble read-only render frames from
+  resolved provider metadata and already-created immutable snapshots.
+- **`bindingSnapshot()` / `bindingFrame()`**: Model provider-delivered plain
+  data as copied, versioned immutable snapshots and read-only render frames.
+- **`commandIntent()`**: Declare user intent outputs as inspectable metadata,
+  without business-logic callbacks or provider mutation handles.
+- **`captureStoryMatrix()`**: Capture every profile/variant pair from a story
+  renderer.
+- **`storyCaptureMatrixText()`**: Render a deterministic multi-mode story
+  matrix for docs and tests.
+- **`createFixturePromotionRecord()`**: Preserve provenance when a fixture,
+  docs page, story, example, or MCP payload is promoted into another surface.
+- **`fixturePromotionText()`**: Render that promotion record for review and
+  agent output.
+
 ## Documentation
 
 - **[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/active-binding-collection.d.ts

@@ -0,0 +1,49 @@
+import { type DataRequirement, type ProviderId, type ViewDataContract } from './binding.js';
+import { type BindingLifecycleOwner, type BindingLifecycleRecord } from './binding-lifecycle.js';
+declare const ACTIVE_BINDING_ENTRY_BRAND: unique symbol;
+declare const ACTIVE_BINDING_COLLECTION_BRAND: unique symbol;
+export interface ActiveBindingEntryInput {
+    readonly owner: BindingLifecycleOwner;
+    readonly requirement: DataRequirement;
+    readonly providerId?: string;
+}
+export interface ActiveBindingEntry {
+    readonly [ACTIVE_BINDING_ENTRY_BRAND]: true;
+    readonly owner: BindingLifecycleOwner;
+    readonly requirement: DataRequirement;
+    readonly providerId?: ProviderId;
+}
+export interface ActiveBindingProviderAssignment {
+    readonly requirementId: string;
+    readonly providerId: string;
+}
+export interface ActiveBindingContractInput {
+    readonly owner: BindingLifecycleOwner;
+    readonly contract: ViewDataContract;
+    readonly providerIds?: readonly ActiveBindingProviderAssignment[];
+}
+export interface CollectActiveBindingsInput {
+    readonly entries?: readonly ActiveBindingEntry[];
+    readonly contracts?: readonly ActiveBindingContractInput[];
+}
+export declare class ActiveBindingCollection {
+    #private;
+    readonly [ACTIVE_BINDING_COLLECTION_BRAND]: true;
+    constructor(entries: readonly ActiveBindingEntry[]);
+    entries(): readonly ActiveBindingEntry[];
+    requirements(): readonly DataRequirement[];
+    owners(): readonly BindingLifecycleOwner[];
+    lifecycleRecords(): readonly BindingLifecycleRecord[];
+    get(ownerId: string, requirementId: string): ActiveBindingEntry | undefined;
+    has(ownerId: string, requirementId: string): boolean;
+    byOwner(ownerId: string): readonly ActiveBindingEntry[];
+    byRequirement(requirementId: string): readonly ActiveBindingEntry[];
+    with(entry: ActiveBindingEntry): ActiveBindingCollection;
+}
+export declare function activeBindingEntry(input: ActiveBindingEntryInput): ActiveBindingEntry;
+export declare function isActiveBindingEntry(value: unknown): value is ActiveBindingEntry;
+export declare function activeBindingCollection(entries: readonly ActiveBindingEntry[]): ActiveBindingCollection;
+export declare function isActiveBindingCollection(value: unknown): value is ActiveBindingCollection;
+export declare function collectActiveBindings(input: CollectActiveBindingsInput): ActiveBindingCollection;
+export {};
+//# sourceMappingURL=active-binding-collection.d.ts.map

package/dist/core/active-binding-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-binding-collection.d.ts","sourceRoot":"","sources":["../../src/core/active-binding-collection.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EAEf,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,QAAA,MAAM,0BAA0B,EAAE,OAAO,MAAqC,CAAC;AAC/E,QAAA,MAAM,+BAA+B,EAAE,OAAO,MAA0C,CAAC;AAEzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,IAAI,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAClC;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;CACnE;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC5D;AAED,qBAAa,uBAAuB;;IAClC,QAAQ,CAAC,CAAC,+BAA+B,CAAC,EAAG,IAAI,CAAC;gBAItC,OAAO,EAAE,SAAS,kBAAkB,EAAE;IA6ClD,OAAO,IAAI,SAAS,kBAAkB,EAAE;IAIxC,YAAY,IAAI,SAAS,eAAe,EAAE;IAW1C,MAAM,IAAI,SAAS,qBAAqB,EAAE;IAW1C,gBAAgB,IAAI,SAAS,sBAAsB,EAAE;IAWrD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAe3E,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAIpD,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE;IAYvD,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE;IAYnE,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,uBAAuB;CAGzD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CAwBrF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAOhF;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,uBAAuB,CAEzB;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAO1F;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,0BAA0B,GAChC,uBAAuB,CAiBzB"}

package/dist/core/active-binding-collection.js

@@ -0,0 +1,264 @@
+import { isDataRequirement, isViewDataContract, } from './binding.js';
+import { bindingLifecycleRecord, isBindingLifecycleOwner, } from './binding-lifecycle.js';
+const ACTIVE_BINDING_ENTRY_BRAND = Symbol('ActiveBindingEntry');
+const ACTIVE_BINDING_COLLECTION_BRAND = Symbol('ActiveBindingCollection');
+export class ActiveBindingCollection {
+    [ACTIVE_BINDING_COLLECTION_BRAND];
+    #entries;
+    #entriesByKey;
+    constructor(entries) {
+        if (!Array.isArray(entries)) {
+            throw new Error('active binding collection: entries must be an array');
+        }
+        Object.defineProperty(this, ACTIVE_BINDING_COLLECTION_BRAND, { value: true });
+        const entriesByKey = new Map();
+        const entryIndexesByKey = new Map();
+        const normalizedEntries = [];
+        entries.forEach((entry, index) => {
+            if (!isActiveBindingEntry(entry)) {
+                throw new Error(`active binding collection: entry at index ${index} was not created by activeBindingEntry()`);
+            }
+            const key = activeBindingKey(entry.owner.id, entry.requirement.id);
+            const existingEntry = entriesByKey.get(key);
+            if (existingEntry !== undefined) {
+                const mergedEntry = mergeDuplicateEntry(existingEntry, entry);
+                const existingIndex = entryIndexesByKey.get(key);
+                if (existingIndex === undefined) {
+                    throw new Error(`active binding collection: missing index for owner ${entry.owner.id} `
+                        + `requirement ${entry.requirement.id}`);
+                }
+                entriesByKey.set(key, mergedEntry);
+                normalizedEntries[existingIndex] = mergedEntry;
+                return;
+            }
+            entriesByKey.set(key, entry);
+            entryIndexesByKey.set(key, normalizedEntries.length);
+            normalizedEntries.push(entry);
+        });
+        this.#entries = Object.freeze(normalizedEntries);
+        this.#entriesByKey = entriesByKey;
+        Object.freeze(this);
+    }
+    entries() {
+        return Object.freeze([...this.#entries]);
+    }
+    requirements() {
+        const requirementsById = new Map();
+        this.#entries.forEach((entry) => {
+            if (!requirementsById.has(entry.requirement.id)) {
+                requirementsById.set(entry.requirement.id, entry.requirement);
+            }
+        });
+        return Object.freeze([...requirementsById.values()]);
+    }
+    owners() {
+        const ownersById = new Map();
+        this.#entries.forEach((entry) => {
+            if (!ownersById.has(entry.owner.id)) {
+                ownersById.set(entry.owner.id, entry.owner);
+            }
+        });
+        return Object.freeze([...ownersById.values()]);
+    }
+    lifecycleRecords() {
+        return Object.freeze(this.#entries.map((entry) => bindingLifecycleRecord({
+            owner: entry.owner,
+            requirementId: entry.requirement.id,
+            providerId: entry.providerId,
+            facts: entry.requirement.facts,
+        })));
+    }
+    get(ownerId, requirementId) {
+        return this.#entriesByKey.get(activeBindingKey(normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'ownerId',
+            value: ownerId,
+        }), normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'requirementId',
+            value: requirementId,
+        })));
+    }
+    has(ownerId, requirementId) {
+        return this.get(ownerId, requirementId) !== undefined;
+    }
+    byOwner(ownerId) {
+        const normalizedOwnerId = normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'ownerId',
+            value: ownerId,
+        });
+        return Object.freeze(this.#entries.filter((entry) => entry.owner.id === normalizedOwnerId));
+    }
+    byRequirement(requirementId) {
+        const normalizedRequirementId = normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'requirementId',
+            value: requirementId,
+        });
+        return Object.freeze(this.#entries.filter((entry) => entry.requirement.id === normalizedRequirementId));
+    }
+    with(entry) {
+        return new ActiveBindingCollection([...this.#entries, entry]);
+    }
+}
+export function activeBindingEntry(input) {
+    if (!isBindingLifecycleOwner(input.owner)) {
+        throw new Error('active binding entry: owner was not created by defineBindingLifecycleOwner()');
+    }
+    if (!isDataRequirement(input.requirement)) {
+        throw new Error('active binding entry: requirement was not created by defineDataRequirement()');
+    }
+    const entry = {
+        owner: input.owner,
+        requirement: input.requirement,
+        providerId: optionalRequiredText({
+            scope: 'active binding entry',
+            field: 'providerId',
+            value: input.providerId,
+        }),
+    };
+    Object.defineProperty(entry, ACTIVE_BINDING_ENTRY_BRAND, { value: true });
+    return Object.freeze(entry);
+}
+export function isActiveBindingEntry(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && Object.prototype.hasOwnProperty.call(value, ACTIVE_BINDING_ENTRY_BRAND)
+        && value[ACTIVE_BINDING_ENTRY_BRAND] === true);
+}
+export function activeBindingCollection(entries) {
+    return new ActiveBindingCollection(entries);
+}
+export function isActiveBindingCollection(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && Object.prototype.hasOwnProperty.call(value, ACTIVE_BINDING_COLLECTION_BRAND)
+        && value[ACTIVE_BINDING_COLLECTION_BRAND] === true);
+}
+export function collectActiveBindings(input) {
+    if (input === undefined || input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('active binding collection: input must be an object');
+    }
+    if (input.entries !== undefined && !Array.isArray(input.entries)) {
+        throw new Error('active binding collection: entries must be an array');
+    }
+    if (input.contracts !== undefined && !Array.isArray(input.contracts)) {
+        throw new Error('active binding collection: contracts must be an array');
+    }
+    const entries = [...(input.entries ?? [])];
+    (input.contracts ?? []).forEach((source, index) => {
+        entries.push(...activeBindingEntriesFromContract(source, index));
+    });
+    return new ActiveBindingCollection(entries);
+}
+function activeBindingEntriesFromContract(source, index) {
+    if (!isObjectRecord(source)) {
+        throw new Error(`active binding collection: contract ${index} must be an object`);
+    }
+    if (!isBindingLifecycleOwner(source.owner)) {
+        throw new Error(`active binding collection: contract ${index} owner was not created by defineBindingLifecycleOwner()`);
+    }
+    if (!isViewDataContract(source.contract)) {
+        throw new Error(`active binding collection: contract ${index} was not created by defineViewData()`);
+    }
+    const providerIds = providerAssignmentsByRequirementId(source.providerIds);
+    const requirementIds = new Set(source.contract.requirementIds());
+    providerIds.forEach((_, requirementId) => {
+        if (!requirementIds.has(requirementId)) {
+            throw new Error(`active binding collection: provider assignment ${requirementId} `
+                + `does not match contract ${index}`);
+        }
+    });
+    const requirements = source.contract.requirements().map((requirement, requirementIndex) => {
+        if (!isDataRequirement(requirement)) {
+            throw new Error(`active binding collection: contract ${index} requirement ${requirementIndex} `
+                + 'was not created by defineDataRequirement()');
+        }
+        return requirement;
+    });
+    return Object.freeze(requirements.map((requirement) => activeBindingEntry({
+        owner: source.owner,
+        requirement,
+        providerId: providerIds.get(requirement.id),
+    })));
+}
+function providerAssignmentsByRequirementId(assignments) {
+    if (assignments === undefined) {
+        return new Map();
+    }
+    if (!Array.isArray(assignments)) {
+        throw new Error('active binding collection: providerIds must be an array');
+    }
+    if (assignments.length === 0) {
+        return new Map();
+    }
+    const providerIds = new Map();
+    assignments.forEach((assignment, index) => {
+        if (!isObjectRecord(assignment)) {
+            throw new Error(`active binding collection: provider assignment ${index} must be an object`);
+        }
+        if (typeof assignment['requirementId'] !== 'string') {
+            throw new Error(`active binding collection: provider assignment ${index} `
+                + 'requirementId must be a string');
+        }
+        if (typeof assignment['providerId'] !== 'string') {
+            throw new Error(`active binding collection: provider assignment ${index} providerId must be a string`);
+        }
+        const requirementId = normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'requirementId',
+            value: assignment['requirementId'],
+        });
+        if (providerIds.has(requirementId)) {
+            throw new Error(`active binding collection: duplicate provider assignment ${requirementId}`);
+        }
+        providerIds.set(requirementId, normalizeRequiredText({
+            scope: 'active binding collection',
+            field: 'providerId',
+            value: assignment['providerId'],
+        }));
+    });
+    return providerIds;
+}
+function activeBindingKey(ownerId, requirementId) {
+    return `${ownerId}\u0000${requirementId}`;
+}
+function isObjectRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function mergeDuplicateEntry(existingEntry, incomingEntry) {
+    if (existingEntry.providerId !== undefined
+        && incomingEntry.providerId !== undefined
+        && existingEntry.providerId !== incomingEntry.providerId) {
+        throw new Error(`active binding collection: conflicting providers for owner ${incomingEntry.owner.id} `
+            + `requirement ${incomingEntry.requirement.id}`);
+    }
+    const providerId = existingEntry.providerId ?? incomingEntry.providerId;
+    if (providerId === existingEntry.providerId) {
+        return existingEntry;
+    }
+    return activeBindingEntry({
+        owner: existingEntry.owner,
+        requirement: existingEntry.requirement,
+        providerId,
+    });
+}
+function normalizeRequiredText(options) {
+    const normalized = options.value.trim();
+    if (normalized === '') {
+        throw new Error(`${options.scope}: ${options.field} is required`);
+    }
+    return normalized;
+}
+function optionalRequiredText(options) {
+    if (options.value === undefined) {
+        return undefined;
+    }
+    return normalizeRequiredText({
+        scope: options.scope,
+        field: options.field,
+        value: options.value,
+    });
+}
+//# sourceMappingURL=active-binding-collection.js.map