@ponchia/ui 0.4.0 → 0.4.1

package/llms.txt

@@ -20,6 +20,12 @@ CSS (pick one; do not import both):
 @import '@ponchia/ui/css';    /* css/core.css — @import fan-out, needs a bundler */
 ```
 
+`import '@ponchia/ui'` is supported only as a CSS side-effect import in a
+CSS-aware bundler. Do not import the package root from Node/runtime JS; use the
+explicit JS subpaths below.
+
+JS subpaths are ESM-only. In CommonJS, use dynamic `import()`.
+
 Everything lands in `@layer bronto`. Consumer styles in no layer (or a
 later layer) always win over framework styles regardless of selector
 specificity — this is the intended override mechanism; do not fight it
@@ -46,11 +52,13 @@ Optional vanilla behaviors (theme toggle, etc. — SSR-safe, tree-shakeable):
 import { applyStoredTheme } from '@ponchia/ui/behaviors';
 ```
 
-For React/Solid, optional thin hook bindings over those behaviors (peer deps
-`react` / `solid-js`, optional — core stays zero-dep):
+For React/Solid/Qwik, optional thin hook bindings over those behaviors (peer
+deps `react` / `solid-js` / `@builder.io/qwik`, optional — core stays zero-dep):
 
 ```js
-import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid'
+import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid' or '@ponchia/ui/qwik'
+// React: scope with { root: reactRef } or a resolver, not { root: ref.current } during render.
+// Qwik: hooks run in useVisibleTask$; scope with a Qwik signal — useDialog({ root: useSignal() }).
 ```
 
 Optional display glyphs — dot-matrix bitmaps on the `.ui-dotmatrix` primitive
@@ -89,6 +97,47 @@ simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
 (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
 
+Optional static report layer for LLM-authored HTML reports — opt-in, never in
+the default bundle. Pair it with the normal bundle, and add data-viz only when
+the report contains charts. For standalone browser HTML, use real URLs; package
+specifiers only work after a bundler rewrites them:
+
+```html
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
+```
+
+In Vite/webpack/etc., import `@ponchia/ui`, `@ponchia/ui/css/report.css`, and
+`@ponchia/ui/css/dataviz.css` instead.
+
+Canonical report skeleton:
+
+```html
+<main class="ui-report ui-report--numbered">
+  <header class="ui-report__cover">
+    <p class="ui-eyebrow">Report</p>
+    <h1 class="ui-report__title">System review</h1>
+    <p class="ui-report__subtitle">Static HTML, Chromium PDF-ready.</p>
+    <ol class="ui-report__meta"><li>2026-06-01</li><li>Generated</li></ol>
+  </header>
+  <section class="ui-report__section">
+    <h2 class="ui-report__section-head">Executive summary</h2>
+    <div class="ui-report__summary">
+      <div class="ui-prose"><p>Use prose only for narrative body content.</p></div>
+    </div>
+  </section>
+</main>
+```
+
+Report rules for agents: static output by default; do not initialize behaviors
+over untrusted generated content; sanitize arbitrary LLM/CMS/user HTML before
+rendering; use semantic headings; give tables captions and header cells; give
+charts captions, legends/direct labels, and fallback data; use
+`ui-chart__plot`/`ui-chart__bar`/`ui-chart__fill` for simple static bar charts;
+use `ui-report__section--unnumbered` for appendices in numbered reports; never
+use raw chromatic inline colors. Full cookbook: `docs/reporting.md`.
+
 ## Authoritative offline references (shipped in this package)
 
 Read these from `node_modules/@ponchia/ui/` — no network needed:
@@ -101,9 +150,14 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   the same source as the types and CI-drift-checked.
 - `docs/theming.md` — the token contract: which tokens to override, the
   light/dark model, and the rationed-accent rule.
+- `docs/stability.md` — the public API matrix: stable vs internal surfaces,
+  root-import contract, behavior trust boundary, and glyph-mask CSP note.
 - `docs/usage.md` — the decision guide: badge vs chip vs dot, default
   density, prose-in-card, when to add a behavior. Read this before
   re-implementing UI the framework already has an opinion about.
+- `docs/reporting.md` — static/PDF-first report cookbook for LLM-authored
+  reports, including report skeletons, chart rules, print utilities, and safety
+  boundaries.
 - `docs/contrast.md` — the published, CI-gated WCAG 2.1 contrast matrix
   for every contractual token pairing, per theme. Generated from the
   resolved palette; the build fails below the declared floor.
@@ -123,7 +177,7 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 
 - Live kitchen-sink demo (every component, light/dark, RTL): https://ponchia.github.io/bronto-ui/
 - Architecture & the CSS-first decision: https://github.com/Ponchia/bronto-ui/blob/main/docs/architecture.md
-- Framework integration guides (Astro / SvelteKit / React-Solid / vanilla):
+- Framework integration guides (Astro / SvelteKit / React-Solid-Qwik / vanilla):
   https://github.com/Ponchia/bronto-ui/tree/main/docs/getting-started
 
 ## Rules an agent should respect
@@ -131,6 +185,9 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - Never invent `ui-*` class names. Every valid class is a member of
   `cls` in `classes/index.d.ts`; if it is not there, it does not exist.
 - Prefer the `ui.*()` recipes over hand-concatenating modifier strings.
+  Report/layout classes added in 0.4.1 are the exception: use `cls.report*`,
+  `cls.chart*`, `cls.printOnly`, or literal documented class names because
+  there are no `ui.report()` / `ui.chart()` recipes yet.
 - Override framework styles by writing your own rules outside
   `@layer bronto` — not with higher specificity or `!important`.
 - Color is tiered (ADR-0001): neutral canvas · one rationed accent · locked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "CSS-first, framework-agnostic UI framework — token-driven restraint (monochrome by default, one rationed accent), OKLCH colorways, a dot-matrix icon set, a colourblind-safe data-viz palette, dot-matrix motifs, zero runtime dependencies.",
   "keywords": [
@@ -48,14 +48,19 @@
     "glyphs",
     "react",
     "solid",
+    "qwik",
     "shiki",
     "llms.txt",
     "CHANGELOG.md",
     "docs/reference.md",
     "docs/theming.md",
     "docs/contrast.md",
+    "docs/stability.md",
     "docs/usage.md",
-    "docs/adr/0001-color-system.md"
+    "docs/reporting.md",
+    "docs/adr/0001-color-system.md",
+    "docs/adr/0002-scope-and-2026-baseline.md",
+    "docs/adr/0003-theme-model.md"
   ],
   "style": "./dist/bronto.css",
   "scripts": {
@@ -63,6 +68,7 @@
     "lint:fix": "stylelint \"css/**/*.css\" --fix",
     "format": "prettier --write .",
     "check:format": "prettier --check .",
+    "size:report": "node scripts/size-report.mjs",
     "tokens:build": "node scripts/gen-tokens-json.mjs",
     "dtcg:build": "node scripts/gen-dtcg.mjs",
     "resolved:build": "node scripts/gen-resolved.mjs",
@@ -84,6 +90,7 @@
     "check:color-policy": "node scripts/check-color-policy.mjs",
     "check:skins": "node scripts/check-skins.mjs",
     "check:charts": "node scripts/check-charts.mjs",
+    "check:report": "node scripts/check-report.mjs",
     "check:types": "tsc -p tsconfig.json",
     "check:dtcg": "node scripts/check-dtcg.mjs",
     "check:resolved": "node scripts/check-resolved.mjs",
@@ -94,26 +101,34 @@
     "check:reference": "node scripts/check-reference.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "check:vscode": "node scripts/check-vscode-data.mjs",
-    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode && npm run check:behaviors && npm run check:bindings && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts",
+    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode && npm run check:behaviors && npm run check:bindings && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:report",
     "test": "node --test \"test/*.test.mjs\"",
     "prepack": "npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run contrast:build && npm run vscode:build && npm run skins:build && npm run charts:build && npm run dist:build && npm run glyphs:build",
     "prepublishOnly": "npm run check && npm test"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.3",
+    "@builder.io/qwik": "^1.20.0",
     "@playwright/test": "^1.60.0",
     "jsdom": "^29.1.1",
     "prettier": "^3.8.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "solid-js": "^1.9.13",
     "stylelint": "^17.11.1",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-use-logical": "^2.1.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@builder.io/qwik": ">=1.5",
     "react": ">=18",
     "solid-js": ">=1.6"
   },
   "peerDependenciesMeta": {
+    "@builder.io/qwik": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -146,6 +161,7 @@
     "./css/app.css": "./dist/css/app.css",
     "./css/skins.css": "./dist/css/skins.css",
     "./css/dataviz.css": "./dist/css/dataviz.css",
+    "./css/report.css": "./dist/css/report.css",
     "./css/unlayered/tokens.css": "./css/tokens.css",
     "./css/unlayered/fonts.css": "./css/fonts.css",
     "./css/unlayered/base.css": "./css/base.css",
@@ -163,6 +179,7 @@
     "./css/unlayered/app.css": "./css/app.css",
     "./css/unlayered/skins.css": "./css/skins.css",
     "./css/unlayered/dataviz.css": "./css/dataviz.css",
+    "./css/unlayered/report.css": "./css/report.css",
     "./tokens": {
       "types": "./tokens/index.d.ts",
       "default": "./tokens/index.js"
@@ -176,8 +193,12 @@
     "./docs/reference.md": "./docs/reference.md",
     "./docs/theming.md": "./docs/theming.md",
     "./docs/contrast.md": "./docs/contrast.md",
+    "./docs/stability.md": "./docs/stability.md",
     "./docs/usage.md": "./docs/usage.md",
+    "./docs/reporting.md": "./docs/reporting.md",
     "./docs/adr/0001-color-system.md": "./docs/adr/0001-color-system.md",
+    "./docs/adr/0002-scope-and-2026-baseline.md": "./docs/adr/0002-scope-and-2026-baseline.md",
+    "./docs/adr/0003-theme-model.md": "./docs/adr/0003-theme-model.md",
     "./classes": {
       "types": "./classes/index.d.ts",
       "default": "./classes/index.js"
@@ -198,6 +219,10 @@
       "types": "./solid/index.d.ts",
       "default": "./solid/index.js"
     },
+    "./qwik": {
+      "types": "./qwik/index.d.ts",
+      "default": "./qwik/index.js"
+    },
     "./skins": {
       "types": "./tokens/skins.d.ts",
       "default": "./tokens/skins.js"

package/qwik/index.d.ts

@@ -0,0 +1,55 @@
+/** @ponchia/ui/qwik — thin Qwik bindings over the SSR-safe behaviors.
+ *  Optional peer dep `@builder.io/qwik`. Hooks run a delegated behavior on
+ *  visible and register cleanup on dispose (via `useVisibleTask$`); they take
+ *  the same options as the behavior and return void. See behaviors/index.d.ts. */
+import type { Cleanup, DelegateOpts, ThemeStorageOpts, ToastOpts } from '../behaviors/index.js';
+
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  // Qwik `useSignal()` (and any { value } / { current } ref shape).
+  | { value: Document | Element | null | undefined }
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
+/** Run any delegated behavior for the component's lifetime (init on visible,
+ *  its returned cleanup on dispose). Prefer the specific `use*` hooks in Qwik
+ *  so the optimizer can serialize the task; this generic form is safe only with
+ *  an optimizer-visible (module-imported) behavior. */
+export declare function useBrontoBehavior(
+  init: (opts?: DelegateOpts) => Cleanup | void,
+  opts?: BrontoBindingOptsResolver,
+): void;
+
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+
+/** The `toast()` imperative (no lifecycle of its own). */
+export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
+
+export { applyStoredTheme } from '../behaviors/index.js';
+export { cls, ui, cx } from '../classes/index.js';

package/qwik/index.js

@@ -0,0 +1,129 @@
+/**
+ * @ponchia/ui/qwik — thin Qwik bindings over @ponchia/ui/behaviors.
+ *
+ * The CSS is the framework; these are *optional* hooks that wrap the SSR-safe
+ * vanilla `init*` behaviors in Qwik's client lifecycle. Thin adapters, not a
+ * component library (architecture ADR). `@builder.io/qwik` is an optional peer
+ * dependency.
+ *
+ * Qwik is resumable: nothing runs until needed, and our behaviors are exactly
+ * the kind of "enhance on the client" glue that fits — they `useVisibleTask$`
+ * (run when the owning component first becomes visible) and register cleanup,
+ * so a server-rendered page stays zero-JS until interaction. Each hook inlines
+ * its specific behavior so the Qwik optimizer can resolve the import inside the
+ * extracted task segment.
+ *
+ *   import { component$ } from '@builder.io/qwik';
+ *   import { useDialog, useToast } from '@ponchia/ui/qwik';
+ *   export default component$(() => {
+ *     useDialog();                 // wires every .ui-modal under document
+ *     const toast = useToast();
+ *     return <button onClick$={() => toast('Saved', { tone: 'success' })}>Save</button>;
+ *   });
+ *
+ * Scope a behavior to a subtree by passing a Qwik signal:
+ *   const root = useSignal();
+ *   useDialog({ root });           // <section ref={root}> … </section>
+ */
+import { useVisibleTask$ } from '@builder.io/qwik';
+import {
+  applyStoredTheme,
+  initThemeToggle,
+  dismissible,
+  initDisclosure,
+  initMenu,
+  initFormValidation,
+  initCombobox,
+  initPopover,
+  initTableSort,
+  initTabs,
+  initDialog,
+  initCarousel,
+  initDotGlyph,
+  toast,
+} from '../behaviors/index.js';
+
+function resolveMaybe(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+function resolveRoot(root) {
+  const value = resolveMaybe(root);
+  if (value && typeof value === 'object') {
+    if ('value' in value) return value.value; // Qwik signal (useSignal)
+    if ('current' in value) return value.current; // generic ref shape
+  }
+  return value;
+}
+
+function resolveOpts(opts) {
+  const value = resolveMaybe(opts);
+  if (!value || typeof value !== 'object') return undefined;
+  const root = resolveRoot(value.root);
+  return root ? { ...value, root } : { ...value, root: undefined };
+}
+
+/** Run a delegated behavior on visible and register its cleanup on dispose.
+ *  `init` and `opts` are resolved inside the visible task, so a Qwik-signal
+ *  root is read after the element is assigned. Shared, non-QRL, so the
+ *  optimizer keeps the captured behavior import inside the task segment. */
+function start(init, opts, ctx) {
+  const cleanup = init(resolveOpts(opts));
+  if (typeof cleanup === 'function') ctx.cleanup(cleanup);
+}
+
+/** Generic escape hatch. NOTE for Qwik: prefer the specific `use*` hooks
+ *  below — they inline a statically-imported behavior so the optimizer can
+ *  serialize the task. Passing a runtime function here is only safe when it
+ *  is itself optimizer-visible (a module import). */
+export function useBrontoBehavior(init, opts) {
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(init, opts, ctx));
+}
+
+export const useThemeToggle = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initThemeToggle, opts, ctx));
+export const useDismissible = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(dismissible, opts, ctx));
+export const useDisclosure = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDisclosure, opts, ctx));
+export const useMenu = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initMenu, opts, ctx));
+export const useFormValidation = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initFormValidation, opts, ctx));
+export const useCombobox = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCombobox, opts, ctx));
+export const usePopover = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initPopover, opts, ctx));
+export const useTableSort = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initTableSort, opts, ctx));
+export const useTabs = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initTabs, opts, ctx));
+export const useDialog = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDialog, opts, ctx));
+export const useCarousel = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCarousel, opts, ctx));
+export const useDotGlyph = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDotGlyph, opts, ctx));
+
+/** The `toast()` imperative (no lifecycle of its own). */
+export const useToast = () => toast;
+
+// No-flash theme application must run before paint — do it in an inline head
+// script, not on visible. Re-exported for manual/SSR-bootstrap use.
+export { applyStoredTheme };
+
+// Convenience: the framework-agnostic class contract, re-exported.
+export { cls, ui, cx } from '../classes/index.js';

package/react/index.d.ts

@@ -9,25 +9,46 @@ import type {
   ToastOpts,
 } from '../behaviors/index.js';
 
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
 /** Run any delegated behavior for the component's lifetime (init on mount,
- *  its returned cleanup on unmount). The behavior is run once. */
+ *  its returned cleanup on unmount). The behavior is run once. Options resolve
+ *  on mount, so scoped roots may be React refs or resolver callbacks. */
 export declare function useBrontoBehavior(
   init: (opts?: DelegateOpts) => Cleanup | void,
-  opts?: DelegateOpts,
+  opts?: BrontoBindingOptsResolver,
 ): void;
 
-export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
-export declare function useDismissible(opts?: DelegateOpts): void;
-export declare function useDisclosure(opts?: DelegateOpts): void;
-export declare function useMenu(opts?: DelegateOpts): void;
-export declare function useFormValidation(opts?: DelegateOpts): void;
-export declare function useCombobox(opts?: DelegateOpts): void;
-export declare function usePopover(opts?: DelegateOpts): void;
-export declare function useTableSort(opts?: DelegateOpts): void;
-export declare function useTabs(opts?: DelegateOpts): void;
-export declare function useDialog(opts?: DelegateOpts): void;
-export declare function useCarousel(opts?: DelegateOpts): void;
-export declare function useDotGlyph(opts?: DelegateOpts): void;
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
 
 /** The `toast()` imperative (no lifecycle of its own). */
 export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;

package/react/index.js

@@ -7,8 +7,8 @@
  * the architecture ADR. `react` is an optional peer dependency.
  *
  * The behaviors delegate from a root (default `document`), so call a hook once
- * near the relevant subtree; pass `{ root: ref.current }` to scope it. The root
- * is captured on mount — keep it stable (a ref), like any effect dependency.
+ * near the relevant subtree; pass `{ root: ref }` or a resolver callback to
+ * scope it. The options resolve on mount, after refs have been assigned.
  *
  *   import { useDialog, useToast } from '@ponchia/ui/react';
  *   function App() {
@@ -35,11 +35,28 @@ import {
   toast,
 } from '../behaviors/index.js';
 
+function resolveMaybe(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+function resolveRoot(root) {
+  const value = resolveMaybe(root);
+  if (value && typeof value === 'object' && 'current' in value) return value.current;
+  return value;
+}
+
+function resolveOpts(opts) {
+  const value = resolveMaybe(opts);
+  if (!value || typeof value !== 'object') return undefined;
+  const root = resolveRoot(value.root);
+  return root ? { ...value, root } : { ...value, root: undefined };
+}
+
 /** Run a delegated behavior for the component's lifetime (init on mount, its
- *  returned cleanup on unmount). The behavior is run once; `opts` is captured
- *  on mount — pass a stable root (a ref) if you scope it. */
+ *  returned cleanup on unmount). The behavior is run once; `opts` resolves
+ *  on mount so refs are usable for scoped roots. */
 export function useBrontoBehavior(init, opts) {
-  useEffect(() => init(opts), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
+  useEffect(() => init(resolveOpts(opts)), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
 }
 
 export const useThemeToggle = (opts) => useBrontoBehavior(initThemeToggle, opts);

package/solid/index.d.ts

@@ -9,25 +9,46 @@ import type {
   ToastOpts,
 } from '../behaviors/index.js';
 
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
 /** Run any delegated behavior for the component's lifetime (init on mount,
- *  its returned cleanup on dispose). */
+ *  its returned cleanup on dispose). The behavior is run once. Options resolve
+ *  on mount, so scoped roots may be refs or resolver callbacks. */
 export declare function useBrontoBehavior(
   init: (opts?: DelegateOpts) => Cleanup | void,
-  opts?: DelegateOpts,
+  opts?: BrontoBindingOptsResolver,
 ): void;
 
-export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
-export declare function useDismissible(opts?: DelegateOpts): void;
-export declare function useDisclosure(opts?: DelegateOpts): void;
-export declare function useMenu(opts?: DelegateOpts): void;
-export declare function useFormValidation(opts?: DelegateOpts): void;
-export declare function useCombobox(opts?: DelegateOpts): void;
-export declare function usePopover(opts?: DelegateOpts): void;
-export declare function useTableSort(opts?: DelegateOpts): void;
-export declare function useTabs(opts?: DelegateOpts): void;
-export declare function useDialog(opts?: DelegateOpts): void;
-export declare function useCarousel(opts?: DelegateOpts): void;
-export declare function useDotGlyph(opts?: DelegateOpts): void;
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
 
 /** The `toast()` imperative (no lifecycle of its own). */
 export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;

package/solid/index.js

@@ -7,7 +7,8 @@
  * `solid-js` is an optional peer dependency.
  *
  * Behaviors delegate from a root (default `document`); call a primitive once in
- * a component that owns the relevant subtree, `{ root: el }` to scope it.
+ * a component that owns the relevant subtree, and pass a root resolver to scope
+ * it when the element is assigned by Solid's ref lifecycle.
  *
  *   import { useDialog, useToast } from '@ponchia/ui/solid';
  *   function App() {
@@ -34,11 +35,28 @@ import {
   toast,
 } from '../behaviors/index.js';
 
+function resolveMaybe(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+function resolveRoot(root) {
+  const value = resolveMaybe(root);
+  if (value && typeof value === 'object' && 'current' in value) return value.current;
+  return value;
+}
+
+function resolveOpts(opts) {
+  const value = resolveMaybe(opts);
+  if (!value || typeof value !== 'object') return undefined;
+  const root = resolveRoot(value.root);
+  return root ? { ...value, root } : { ...value, root: undefined };
+}
+
 /** Run a delegated behavior for the component's lifetime (init on mount, its
- *  returned cleanup on dispose). */
+ *  returned cleanup on dispose). Options resolve on mount, after refs exist. */
 export function useBrontoBehavior(init, opts) {
   onMount(() => {
-    const cleanup = init(opts);
+    const cleanup = init(resolveOpts(opts));
     if (typeof cleanup === 'function') onCleanup(cleanup);
   });
 }