@askrjs/askr 0.0.29 → 0.0.31

package/README.md

@@ -23,8 +23,8 @@ createIsland({ root: document.body, component: Counter });
 ### Runtime
 
 `@askrjs/askr` exports the core runtime primitives: `state()`, `derive()`,
-`selector()`, `resource()`, routing helpers, JSX control-flow helpers, and SSR/SSG
-entrypoints.
+`selector()`, `resource()`, `ErrorBoundary`, routing helpers, JSX control-flow
+helpers, and SSR/SSG entrypoints.
 
 ### Explicit reactivity
 
@@ -69,7 +69,25 @@ function Data({ id }: { id: string }) {
 
   if (data.pending) return <div>Loading...</div>;
   if (data.error) return <div>Failed to load</div>;
-  return <div>{data.value.name}</div>;
+return <div>{data.value.name}</div>;
+}
+```
+
+### Developer error boundaries
+
+`ErrorBoundary` is the opt-in boundary primitive for render-time failures. It
+renders a visible fallback in development, still logs the underlying error, and
+can reset when your app state changes.
+
+```ts
+import { ErrorBoundary } from '@askrjs/askr';
+
+function App() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      <FlakyView />
+    </ErrorBoundary>
+  );
 }
 ```
 

package/dist/benchmark.js

@@ -10,8 +10,8 @@ import { BenchmarkTable } from "./bench/components/benchmark-table.js";
 installRendererBridge();
 const benchmarkMetadata = {
 	packageName: "@askrjs/askr",
-	packageVersion: "0.0.29",
-	buildLabel: "0.0.29-local"
+	packageVersion: "0.0.31",
+	buildLabel: "0.0.31-local"
 };
 function getBenchmarkMetadata() {
 	return { ...benchmarkMetadata };

package/dist/common/vnode.d.ts

@@ -2,6 +2,7 @@ import { Props } from "./props.js";
 import { ForState } from "../runtime/for.js";
 import { ControlBoundaryState } from "../runtime/control.js";
 //#region src/common/vnode.d.ts
+declare const __ERROR_BOUNDARY__: unique symbol;
 interface DOMElement {
   type: string | ((props: Props) => any) | symbol;
   props?: Props;

package/dist/common/vnode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vnode.d.ts","names":[],"sources":["../../src/common/vnode.ts"],"mappings":";;;;UAUiB,UAAA;EAKf,IAAA,aAAiB,KAAA,EAAO,KAAA;EACxB,KAAA,GAAQ,KAAA;EACR,QAAA,GAAW,KAAA;EACX,GAAA;EAAA,CACC,MAAA,CAAO,QAAA;EACR,aAAA,GAAgB,oBAAA;EAChB,SAAA,GAAY,QAAA;AAAA;AAAA,KAIF,KAAA,GAAQ,UAAA;AAAA,cAIP,gBAAA;AAAA,iBAEG,aAAA,CAAc,IAAA,YAAgB,IAAA,IAAQ,UAAA"}
+{"version":3,"file":"vnode.d.ts","names":[],"sources":["../../src/common/vnode.ts"],"mappings":";;;;cAUa,kBAAA;AAAA,UAEI,UAAA;EAKf,IAAA,aAAiB,KAAA,EAAO,KAAA;EACxB,KAAA,GAAQ,KAAA;EACR,QAAA,GAAW,KAAA;EACX,GAAA;EAAA,CACC,MAAA,CAAO,QAAA;EACR,aAAA,GAAgB,oBAAA;EAChB,SAAA,GAAY,QAAA;AAAA;AAAA,KAIF,KAAA,GAAQ,UAAA;AAAA,cAIP,gBAAA;AAAA,iBAEG,aAAA,CAAc,IAAA,YAAgB,IAAA,IAAQ,UAAA"}

package/dist/common/vnode.js

@@ -1,10 +1,11 @@
 import { __CONTROL_BOUNDARY__ } from "./control.js";
 //#region src/common/vnode.ts
+const __ERROR_BOUNDARY__ = Symbol.for("askr.error-boundary");
 const __FOR_BOUNDARY__ = __CONTROL_BOUNDARY__;
 function _isDOMElement(node) {
 	return typeof node === "object" && node !== null && "type" in node;
 }
 //#endregion
-export { __FOR_BOUNDARY__, _isDOMElement };
+export { __ERROR_BOUNDARY__, __FOR_BOUNDARY__, _isDOMElement };
 
 //# sourceMappingURL=vnode.js.map

package/dist/common/vnode.js.map

@@ -1 +1 @@
-{"version":3,"file":"vnode.js","names":[],"sources":["../../src/common/vnode.ts"],"sourcesContent":["/**\n * Common call contracts: VNode / virtual DOM shapes\n */\n\nimport type { Props } from './props';\nimport type { ControlBoundaryState } from '../runtime/control';\nimport type { ForState } from '../runtime/for';\nexport { __CONTROL_BOUNDARY__ } from './control';\nimport { __CONTROL_BOUNDARY__ } from './control';\n\nexport interface DOMElement {\n  // Element `type` can be an intrinsic tag name, a component function, or\n  // a special symbol (e.g. `Fragment`). Include `symbol` in the type union\n  // so runtime comparisons against `Fragment` are type-safe.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  type: string | ((props: Props) => any) | symbol;\n  props?: Props;\n  children?: VNode[];\n  key?: string | number | null;\n  [Symbol.iterator]?: never;\n  _controlState?: ControlBoundaryState; // Internal: control boundary state\n  _forState?: ForState<unknown>; // Deprecated internal alias during migration\n}\n\n// Type for virtual DOM nodes\nexport type VNode = DOMElement | string | number | boolean | null | undefined;\n\n// Backward-compatible internal alias while renderer/runtime migrates away from\n// the old For-only boundary naming.\nexport const __FOR_BOUNDARY__ = __CONTROL_BOUNDARY__;\n\nexport function _isDOMElement(node: unknown): node is DOMElement {\n  return typeof node === 'object' && node !== null && 'type' in node;\n}\n"],"mappings":";;AA6BA,MAAa,mBAAmB;AAEhC,SAAgB,cAAc,MAAmC;AAC/D,QAAO,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU"}
+{"version":3,"file":"vnode.js","names":[],"sources":["../../src/common/vnode.ts"],"sourcesContent":["/**\n * Common call contracts: VNode / virtual DOM shapes\n */\n\nimport type { Props } from './props';\nimport type { ControlBoundaryState } from '../runtime/control';\nimport type { ForState } from '../runtime/for';\nexport { __CONTROL_BOUNDARY__ } from './control';\nimport { __CONTROL_BOUNDARY__ } from './control';\n\nexport const __ERROR_BOUNDARY__ = Symbol.for('askr.error-boundary');\n\nexport interface DOMElement {\n  // Element `type` can be an intrinsic tag name, a component function, or\n  // a special symbol (e.g. `Fragment`). Include `symbol` in the type union\n  // so runtime comparisons against `Fragment` are type-safe.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  type: string | ((props: Props) => any) | symbol;\n  props?: Props;\n  children?: VNode[];\n  key?: string | number | null;\n  [Symbol.iterator]?: never;\n  _controlState?: ControlBoundaryState; // Internal: control boundary state\n  _forState?: ForState<unknown>; // Deprecated internal alias during migration\n}\n\n// Type for virtual DOM nodes\nexport type VNode = DOMElement | string | number | boolean | null | undefined;\n\n// Backward-compatible internal alias while renderer/runtime migrates away from\n// the old For-only boundary naming.\nexport const __FOR_BOUNDARY__ = __CONTROL_BOUNDARY__;\n\nexport function _isDOMElement(node: unknown): node is DOMElement {\n  return typeof node === 'object' && node !== null && 'type' in node;\n}\n"],"mappings":";;AAUA,MAAa,qBAAqB,OAAO,IAAI,sBAAsB;AAqBnE,MAAa,mBAAmB;AAEhC,SAAgB,cAAc,MAAmC;AAC/D,QAAO,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU"}

package/dist/components/error-boundary.d.ts

@@ -0,0 +1,25 @@
+import { Props } from "../common/props.js";
+import { JSXElement } from "../common/jsx.js";
+import { ComponentInstance } from "../runtime/component.js";
+
+//#region src/components/error-boundary.d.ts
+type ErrorBoundaryFallbackRender = (error: unknown, reset: () => void) => unknown;
+interface ErrorBoundaryProps extends Props {
+  children?: unknown;
+  fallback?: unknown | ErrorBoundaryFallbackRender;
+  onError?: (error: unknown) => void;
+  resetKey?: unknown;
+}
+type ErrorBoundaryState = NonNullable<ComponentInstance['errorBoundaryState']>;
+type ErrorBoundaryVNode = JSXElement & {
+  __instance?: ComponentInstance;
+};
+declare function ErrorBoundary(props: ErrorBoundaryProps): JSXElement;
+declare function isErrorBoundaryVNode(value: unknown): value is ErrorBoundaryVNode;
+declare function resolveErrorBoundaryState(vnode: ErrorBoundaryVNode): ErrorBoundaryState | null;
+declare function resolveErrorBoundaryFallback(fallback: ErrorBoundaryProps['fallback'], error: unknown, reset: () => void): unknown;
+declare function createBoundaryReset(instance: ComponentInstance): () => void;
+declare function reportBoundaryError(instance: ComponentInstance, error: unknown, onError?: (error: unknown) => void): void;
+//#endregion
+export { ErrorBoundary, ErrorBoundaryFallbackRender, ErrorBoundaryProps };
+//# sourceMappingURL=error-boundary.d.ts.map

package/dist/components/error-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.d.ts","names":[],"sources":["../../src/components/error-boundary.tsx"],"mappings":";;;;;KAUY,2BAAA,IACV,KAAA,WACA,KAAA;AAAA,UAGe,kBAAA,SAA2B,KAAA;EAC1C,QAAA;EACA,QAAA,aAAqB,2BAAA;EACrB,OAAA,IAAW,KAAA;EACX,QAAA;AAAA;AAAA,KAGG,kBAAA,GAAqB,WAAA,CAAY,iBAAA;AAAA,KAEjC,kBAAA,GAAqB,UAAA;EACxB,UAAA,GAAa,iBAAA;AAAA;AAAA,iBA+DC,aAAA,CAAc,KAAA,EAAO,kBAAA,GAAqB,UAAA;AAAA,iBAY1C,oBAAA,CACd,KAAA,YACC,KAAA,IAAS,kBAAA;AAAA,iBAQI,yBAAA,CACd,KAAA,EAAO,kBAAA,GACN,kBAAA;AAAA,iBAIa,4BAAA,CACd,QAAA,EAAU,kBAAA,cACV,KAAA,WACA,KAAA;AAAA,iBAoDc,mBAAA,CAAoB,QAAA,EAAU,iBAAA;AAAA,iBAc9B,mBAAA,CACd,QAAA,EAAU,iBAAA,EACV,KAAA,WACA,OAAA,IAAW,KAAA"}

package/dist/components/error-boundary.js

@@ -0,0 +1,114 @@
+import { __ERROR_BOUNDARY__ } from "../common/vnode.js";
+import { isDevelopmentEnvironment } from "../common/env.js";
+import { logger } from "../dev/logger.js";
+import { ELEMENT_TYPE } from "../common/jsx.js";
+import { getCurrentComponentInstance } from "../runtime/component.js";
+//#region src/components/error-boundary.tsx
+function getBoundaryMessage(error) {
+	if (error instanceof Error) return error.message || error.name || "Unknown error";
+	if (typeof error === "string") return error;
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}
+function ensureBoundaryState(instance, resetKey) {
+	const boundaryState = instance.errorBoundaryState ?? (instance.errorBoundaryState = {
+		error: null,
+		resetKey,
+		notified: false
+	});
+	if (!Object.is(boundaryState.resetKey, resetKey)) {
+		boundaryState.error = null;
+		boundaryState.resetKey = resetKey;
+		boundaryState.notified = false;
+	}
+	return boundaryState;
+}
+function createBoundaryVNode(instance, props) {
+	const key = typeof props.key === "symbol" ? null : props.key ?? null;
+	return {
+		$$typeof: ELEMENT_TYPE,
+		type: __ERROR_BOUNDARY__,
+		props: {
+			children: props.children,
+			fallback: props.fallback,
+			onError: props.onError,
+			resetKey: props.resetKey
+		},
+		key,
+		__instance: instance
+	};
+}
+function ErrorBoundary(props) {
+	const instance = getCurrentComponentInstance();
+	if (!instance) throw new Error("[Askr] ErrorBoundary() can only be used during component render execution.");
+	ensureBoundaryState(instance, props.resetKey);
+	return createBoundaryVNode(instance, props);
+}
+function resolveErrorBoundaryFallback(fallback, error, reset) {
+	if (typeof fallback === "function") return fallback(error, reset);
+	if (fallback !== void 0) return fallback;
+	const message = getBoundaryMessage(error);
+	const wrapper = document.createElement("div");
+	wrapper.setAttribute("role", "alert");
+	wrapper.setAttribute("data-askr-error-boundary", "true");
+	wrapper.style.boxSizing = "border-box";
+	wrapper.style.padding = "1rem";
+	wrapper.style.border = "1px solid currentColor";
+	wrapper.style.borderRadius = "0.75rem";
+	wrapper.style.display = "grid";
+	wrapper.style.gap = "0.75rem";
+	wrapper.style.maxWidth = "100%";
+	const title = document.createElement("strong");
+	title.textContent = "Something went wrong while rendering this view.";
+	const summary = document.createElement("p");
+	summary.textContent = "The app recovered into a visible fallback so the error is not hidden in the console.";
+	summary.style.margin = "0";
+	const details = document.createElement("details");
+	details.open = isDevelopmentEnvironment();
+	const detailsSummary = document.createElement("summary");
+	detailsSummary.textContent = "Error details";
+	const pre = document.createElement("pre");
+	pre.textContent = message;
+	pre.style.margin = "0";
+	pre.style.whiteSpace = "pre-wrap";
+	pre.style.wordBreak = "break-word";
+	const button = document.createElement("button");
+	button.type = "button";
+	button.textContent = "Try again";
+	button.addEventListener("click", () => reset());
+	details.append(detailsSummary, pre);
+	wrapper.append(title, summary, details, button);
+	return wrapper;
+}
+function createBoundaryReset(instance) {
+	return () => {
+		const boundaryState = instance.errorBoundaryState;
+		if (!boundaryState) return;
+		boundaryState.error = null;
+		boundaryState.notified = false;
+		queueMicrotask(() => {
+			instance._enqueueRun?.();
+		});
+	};
+}
+function reportBoundaryError(instance, error, onError) {
+	const boundaryState = instance.errorBoundaryState;
+	if (boundaryState && Object.is(boundaryState.error, error) && boundaryState.notified) return;
+	if (boundaryState) {
+		boundaryState.error = error;
+		boundaryState.notified = true;
+	}
+	try {
+		onError?.(error);
+	} catch (hookError) {
+		logger.error("[Askr] ErrorBoundary onError handler threw:", hookError);
+	}
+	logger.error("[Askr] ErrorBoundary caught render error:", error);
+}
+//#endregion
+export { ErrorBoundary, createBoundaryReset, reportBoundaryError, resolveErrorBoundaryFallback };
+
+//# sourceMappingURL=error-boundary.js.map

package/dist/components/error-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.js","names":[],"sources":["../../src/components/error-boundary.tsx"],"sourcesContent":["import type { Props } from '../common/props';\nimport { ELEMENT_TYPE, type JSXElement } from '../common/jsx';\nimport { __ERROR_BOUNDARY__ } from '../common/vnode';\nimport {\n  getCurrentComponentInstance,\n  type ComponentInstance,\n} from '../runtime/component';\nimport { logger } from '../dev/logger';\nimport { isDevelopmentEnvironment } from '../common/env';\n\nexport type ErrorBoundaryFallbackRender = (\n  error: unknown,\n  reset: () => void\n) => unknown;\n\nexport interface ErrorBoundaryProps extends Props {\n  children?: unknown;\n  fallback?: unknown | ErrorBoundaryFallbackRender;\n  onError?: (error: unknown) => void;\n  resetKey?: unknown;\n}\n\ntype ErrorBoundaryState = NonNullable<ComponentInstance['errorBoundaryState']>;\n\ntype ErrorBoundaryVNode = JSXElement & {\n  __instance?: ComponentInstance;\n};\n\nfunction getBoundaryMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message || error.name || 'Unknown error';\n  }\n\n  if (typeof error === 'string') {\n    return error;\n  }\n\n  try {\n    return JSON.stringify(error);\n  } catch {\n    return String(error);\n  }\n}\n\nfunction ensureBoundaryState(\n  instance: ComponentInstance,\n  resetKey: unknown\n): ErrorBoundaryState {\n  const boundaryState =\n    instance.errorBoundaryState ??\n    (instance.errorBoundaryState = {\n      error: null,\n      resetKey,\n      notified: false,\n    });\n\n  if (!Object.is(boundaryState.resetKey, resetKey)) {\n    boundaryState.error = null;\n    boundaryState.resetKey = resetKey;\n    boundaryState.notified = false;\n  }\n\n  return boundaryState;\n}\n\nfunction createBoundaryVNode(\n  instance: ComponentInstance,\n  props: ErrorBoundaryProps\n): ErrorBoundaryVNode {\n  const key =\n    typeof props.key === 'symbol'\n      ? null\n      : ((props.key ?? null) as string | number | null);\n\n  return {\n    $$typeof: ELEMENT_TYPE,\n    type: __ERROR_BOUNDARY__,\n    props: {\n      children: props.children,\n      fallback: props.fallback,\n      onError: props.onError,\n      resetKey: props.resetKey,\n    },\n    key,\n    __instance: instance,\n  };\n}\n\nexport function ErrorBoundary(props: ErrorBoundaryProps): JSXElement {\n  const instance = getCurrentComponentInstance();\n  if (!instance) {\n    throw new Error(\n      '[Askr] ErrorBoundary() can only be used during component render execution.'\n    );\n  }\n\n  ensureBoundaryState(instance, props.resetKey);\n  return createBoundaryVNode(instance, props);\n}\n\nexport function isErrorBoundaryVNode(\n  value: unknown\n): value is ErrorBoundaryVNode {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as ErrorBoundaryVNode).type === __ERROR_BOUNDARY__\n  );\n}\n\nexport function resolveErrorBoundaryState(\n  vnode: ErrorBoundaryVNode\n): ErrorBoundaryState | null {\n  return vnode.__instance?.errorBoundaryState ?? null;\n}\n\nexport function resolveErrorBoundaryFallback(\n  fallback: ErrorBoundaryProps['fallback'],\n  error: unknown,\n  reset: () => void\n): unknown {\n  if (typeof fallback === 'function') {\n    return fallback(error, reset);\n  }\n\n  if (fallback !== undefined) {\n    return fallback;\n  }\n\n  const message = getBoundaryMessage(error);\n  const wrapper = document.createElement('div');\n  wrapper.setAttribute('role', 'alert');\n  wrapper.setAttribute('data-askr-error-boundary', 'true');\n  wrapper.style.boxSizing = 'border-box';\n  wrapper.style.padding = '1rem';\n  wrapper.style.border = '1px solid currentColor';\n  wrapper.style.borderRadius = '0.75rem';\n  wrapper.style.display = 'grid';\n  wrapper.style.gap = '0.75rem';\n  wrapper.style.maxWidth = '100%';\n\n  const title = document.createElement('strong');\n  title.textContent = 'Something went wrong while rendering this view.';\n\n  const summary = document.createElement('p');\n  summary.textContent =\n    'The app recovered into a visible fallback so the error is not hidden in the console.';\n  summary.style.margin = '0';\n\n  const details = document.createElement('details');\n  details.open = isDevelopmentEnvironment();\n\n  const detailsSummary = document.createElement('summary');\n  detailsSummary.textContent = 'Error details';\n\n  const pre = document.createElement('pre');\n  pre.textContent = message;\n  pre.style.margin = '0';\n  pre.style.whiteSpace = 'pre-wrap';\n  pre.style.wordBreak = 'break-word';\n\n  const button = document.createElement('button');\n  button.type = 'button';\n  button.textContent = 'Try again';\n  button.addEventListener('click', () => reset());\n\n  details.append(detailsSummary, pre);\n  wrapper.append(title, summary, details, button);\n  return wrapper;\n}\n\nexport function createBoundaryReset(instance: ComponentInstance): () => void {\n  return () => {\n    const boundaryState = instance.errorBoundaryState;\n    if (!boundaryState) {\n      return;\n    }\n    boundaryState.error = null;\n    boundaryState.notified = false;\n    queueMicrotask(() => {\n      instance._enqueueRun?.();\n    });\n  };\n}\n\nexport function reportBoundaryError(\n  instance: ComponentInstance,\n  error: unknown,\n  onError?: (error: unknown) => void\n): void {\n  const boundaryState = instance.errorBoundaryState;\n  if (\n    boundaryState &&\n    Object.is(boundaryState.error, error) &&\n    boundaryState.notified\n  ) {\n    return;\n  }\n\n  if (boundaryState) {\n    boundaryState.error = error;\n    boundaryState.notified = true;\n  }\n\n  try {\n    onError?.(error);\n  } catch (hookError) {\n    logger.error('[Askr] ErrorBoundary onError handler threw:', hookError);\n  }\n\n  logger.error('[Askr] ErrorBoundary caught render error:', error);\n}\n"],"mappings":"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"}

package/dist/foundations/core.d.ts

@@ -0,0 +1,15 @@
+import { ComposeHandlersOptions, composeHandlers } from "./utilities/compose-handlers.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { Ref, composeRefs, setRef } from "./utilities/compose-ref.js";
+import { FormatIdOptions, formatId } from "./utilities/use-id.js";
+import { DefaultPreventable, FocusLikeEvent, KeyboardLikeEvent, PointerLikeEvent, PropagationStoppable } from "./utilities/event-types.js";
+import { PressableOptions, PressableResult, pressable } from "./interactions/pressable.js";
+import { DismissableOptions, dismissable } from "./interactions/dismissable.js";
+import { FocusableOptions, FocusableResult, focusable } from "./interactions/focusable.js";
+import { HoverableOptions, HoverableResult, hoverable } from "./interactions/hoverable.js";
+import { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus } from "./interactions/roving-focus.js";
+import { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
+import { ControllableState, controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
+import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
+import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";

package/dist/foundations/core.js

@@ -0,0 +1,13 @@
+import "./utilities/aria.js";
+import "./interactions/pressable.js";
+import "./utilities/compose-handlers.js";
+import "./utilities/compose-ref.js";
+import "./utilities/merge-props.js";
+import "./interactions/interaction-policy.js";
+import "./utilities/use-id.js";
+import "./interactions/dismissable.js";
+import "./interactions/focusable.js";
+import "./interactions/hoverable.js";
+import "./interactions/roving-focus.js";
+import "./state/controllable.js";
+import "./icon/icon.js";

package/dist/foundations/index.d.ts

@@ -1,10 +1,23 @@
 import { JSXElement } from "../common/jsx.js";
+import { ComposeHandlersOptions, composeHandlers } from "./utilities/compose-handlers.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { Ref, composeRefs, setRef } from "./utilities/compose-ref.js";
+import { FormatIdOptions, formatId } from "./utilities/use-id.js";
+import { DefaultPreventable, FocusLikeEvent, KeyboardLikeEvent, PointerLikeEvent, PropagationStoppable } from "./utilities/event-types.js";
+import { PressableOptions, PressableResult, pressable } from "./interactions/pressable.js";
+import { DismissableOptions, dismissable } from "./interactions/dismissable.js";
+import { FocusableOptions, FocusableResult, focusable } from "./interactions/focusable.js";
+import { HoverableOptions, HoverableResult, hoverable } from "./interactions/hoverable.js";
+import { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus } from "./interactions/roving-focus.js";
+import { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
+import { ControllableState, controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
+import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
+import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
 import { LayoutComponent, layout } from "./structures/layout.js";
 import { Slot, SlotProps } from "./structures/slot.js";
 import { Presence, PresenceProps } from "./structures/presence.js";
 import { DefaultPortal, Portal, PortalProps, definePortal } from "./structures/portal.js";
 import { Collection, CollectionItem, createCollection } from "./structures/collection.js";
 import { Layer, LayerManager, LayerOptions, createLayer } from "./structures/layer.js";
-import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
-import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
-export { Collection, CollectionItem, DefaultPortal, IconBase, type IconOwnProps, type IconProps, type IconSizeToken, type IconStyleObject, JSXElement, Layer, LayerManager, LayerOptions, LayoutComponent, Portal, PortalProps, Presence, PresenceProps, Slot, SlotProps, createCollection, createLayer, definePortal, getIconContractProps, isIconSizeToken, joinIconStyle, layout, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle };
+export { Collection, CollectionItem, ComposeHandlersOptions, ControllableState, DefaultPortal, DefaultPreventable, DismissableOptions, FocusLikeEvent, FocusableOptions, FocusableResult, FormatIdOptions, HoverableOptions, HoverableResult, IconBase, type IconOwnProps, type IconProps, type IconSizeToken, type IconStyleObject, InteractionPolicyInput, JSXElement, KeyboardLikeEvent, Layer, LayerManager, LayerOptions, LayoutComponent, Orientation, PointerLikeEvent, Portal, PortalProps, Presence, PresenceProps, PressableOptions, PressableResult, PropagationStoppable, Ref, RovingFocusOptions, RovingFocusResult, Slot, SlotProps, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, formatId, getIconContractProps, hoverable, isControlled, isIconSizeToken, joinIconStyle, layout, makeControllable, mergeInteractionProps, mergeProps, normalizeIconSizeValue, pressable, resolveControllable, resolveIconSizeVariable, resolveIconStrokeWidthVariable, rovingFocus, serializeIconStyle, setRef };

package/dist/foundations/index.js

@@ -1,9 +1,22 @@
 import { DefaultPortal, Portal, definePortal } from "./structures/portal.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { pressable } from "./interactions/pressable.js";
+import { composeHandlers } from "./utilities/compose-handlers.js";
+import { composeRefs, setRef } from "./utilities/compose-ref.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
 import { layout } from "./structures/layout.js";
 import { Slot } from "./structures/slot.js";
 import { Presence } from "./structures/presence.js";
 import { createCollection } from "./structures/collection.js";
 import { createLayer } from "./structures/layer.js";
 import "./structures.js";
+import { formatId } from "./utilities/use-id.js";
+import { dismissable } from "./interactions/dismissable.js";
+import { focusable } from "./interactions/focusable.js";
+import { hoverable } from "./interactions/hoverable.js";
+import { rovingFocus } from "./interactions/roving-focus.js";
+import { controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
 import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
-export { DefaultPortal, IconBase, Portal, Presence, Slot, createCollection, createLayer, definePortal, getIconContractProps, isIconSizeToken, joinIconStyle, layout, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle };
+import "./core.js";
+export { DefaultPortal, IconBase, Portal, Presence, Slot, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, formatId, getIconContractProps, hoverable, isControlled, isIconSizeToken, joinIconStyle, layout, makeControllable, mergeInteractionProps, mergeProps, normalizeIconSizeValue, pressable, resolveControllable, resolveIconSizeVariable, resolveIconStrokeWidthVariable, rovingFocus, serializeIconStyle, setRef };

package/dist/foundations/interactions/dismissable.d.ts

@@ -0,0 +1,66 @@
+import { KeyboardLikeEvent, PointerLikeEvent } from "../utilities/event-types.js";
+
+//#region src/foundations/interactions/dismissable.d.ts
+/**
+ * dismissable
+ *
+ * THE dismissal primitive. Handles Escape key and outside interactions.
+ *
+ * INVARIANTS:
+ * 1. Returns props that compose via mergeProps (no factories)
+ * 2. Disabled state respected exactly once, here
+ * 3. No side effects - pure props generation
+ * 4. Outside detection requires explicit node reference
+ * 5. This is the ONLY dismissal primitive - do not create alternatives
+ *
+ * DESIGN:
+ * - Returns standard event handler props (onKeyDown, onPointerDownCapture)
+ * - Composable via mergeProps with other foundations
+ * - Caller provides node reference for outside detection
+ * - Single onDismiss callback for all dismiss triggers
+ *
+ * PIT OF SUCCESS:
+ * ✓ Can't accidentally bypass (only way to get dismiss behavior)
+ * ✓ Can't duplicate (disabled checked once)
+ * ✓ Composes via mergeProps (standard props)
+ * ✓ Wrong usage is hard (no factories to misuse)
+ *
+ * USAGE:
+ *   const props = dismissable({
+ *     node: elementRef,
+ *     disabled: false,
+ *     onDismiss: () => close()
+ *   });
+ *
+ *   <div ref={elementRef} {...props}>Content</div>
+ *
+ * MISUSE EXAMPLE (PREVENTED):
+ *   ❌ Can't forget to check disabled - checked inside dismissable
+ *   ❌ Can't create custom escape handler - this is the only one
+ *   ❌ Can't bypass via direct event listeners - mergeProps composes correctly
+ */
+interface DismissableOptions {
+  /**
+   * Reference to the element for outside click detection
+   */
+  node?: Node | null;
+  /**
+   * Whether dismiss is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Called when dismiss is triggered (Escape or outside click)
+   */
+  onDismiss?: (trigger: 'escape' | 'outside') => void;
+}
+declare function dismissable({
+  node,
+  disabled,
+  onDismiss
+}: DismissableOptions): {
+  onKeyDown: (e: KeyboardLikeEvent) => void;
+  onPointerDownCapture: (e: PointerLikeEvent) => void;
+};
+//#endregion
+export { DismissableOptions, dismissable };
+//# sourceMappingURL=dismissable.d.ts.map

package/dist/foundations/interactions/dismissable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dismissable.d.ts","names":[],"sources":["../../../src/foundations/interactions/dismissable.ts"],"mappings":";;;;;;AAuCA;;;;;;;;;;;AAsBA;;;;;;;;;;;;;;;;;;;;;;;;UAtBiB,kBAAA;EAgCsC;;;EA5BrD,IAAA,GAAO,IAAA;;;;EAKP,QAAA;;;;EAKA,SAAA,IAAa,OAAA;AAAA;AAAA,iBAQC,WAAA,CAAA;EAAc,IAAA;EAAM,QAAA;EAAU;AAAA,GAAa,kBAAA;iBAC/B,iBAAA;4BASW,gBAAA;AAAA"}

package/dist/foundations/interactions/dismissable.js

@@ -0,0 +1,26 @@
+//#region src/foundations/interactions/dismissable.ts
+function dismissable({ node, disabled, onDismiss }) {
+	function handleKeyDown(e) {
+		if (disabled) return;
+		if (e.key === "Escape") {
+			e.preventDefault?.();
+			e.stopPropagation?.();
+			onDismiss?.("escape");
+		}
+	}
+	function handlePointerDownCapture(e) {
+		if (disabled) return;
+		const target = e.target;
+		if (!(target instanceof Node)) return;
+		if (!node) return;
+		if (!node.contains(target)) onDismiss?.("outside");
+	}
+	return {
+		onKeyDown: handleKeyDown,
+		onPointerDownCapture: handlePointerDownCapture
+	};
+}
+//#endregion
+export { dismissable };
+
+//# sourceMappingURL=dismissable.js.map

package/dist/foundations/interactions/dismissable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dismissable.js","names":[],"sources":["../../../src/foundations/interactions/dismissable.ts"],"sourcesContent":["/**\n * dismissable\n *\n * THE dismissal primitive. Handles Escape key and outside interactions.\n *\n * INVARIANTS:\n * 1. Returns props that compose via mergeProps (no factories)\n * 2. Disabled state respected exactly once, here\n * 3. No side effects - pure props generation\n * 4. Outside detection requires explicit node reference\n * 5. This is the ONLY dismissal primitive - do not create alternatives\n *\n * DESIGN:\n * - Returns standard event handler props (onKeyDown, onPointerDownCapture)\n * - Composable via mergeProps with other foundations\n * - Caller provides node reference for outside detection\n * - Single onDismiss callback for all dismiss triggers\n *\n * PIT OF SUCCESS:\n * ✓ Can't accidentally bypass (only way to get dismiss behavior)\n * ✓ Can't duplicate (disabled checked once)\n * ✓ Composes via mergeProps (standard props)\n * ✓ Wrong usage is hard (no factories to misuse)\n *\n * USAGE:\n *   const props = dismissable({\n *     node: elementRef,\n *     disabled: false,\n *     onDismiss: () => close()\n *   });\n *\n *   <div ref={elementRef} {...props}>Content</div>\n *\n * MISUSE EXAMPLE (PREVENTED):\n *   ❌ Can't forget to check disabled - checked inside dismissable\n *   ❌ Can't create custom escape handler - this is the only one\n *   ❌ Can't bypass via direct event listeners - mergeProps composes correctly\n */\n\nexport interface DismissableOptions {\n  /**\n   * Reference to the element for outside click detection\n   */\n  node?: Node | null;\n\n  /**\n   * Whether dismiss is disabled\n   */\n  disabled?: boolean;\n\n  /**\n   * Called when dismiss is triggered (Escape or outside click)\n   */\n  onDismiss?: (trigger: 'escape' | 'outside') => void;\n}\n\nimport type {\n  KeyboardLikeEvent,\n  PointerLikeEvent,\n} from '../utilities/event-types';\n\nexport function dismissable({ node, disabled, onDismiss }: DismissableOptions) {\n  function handleKeyDown(e: KeyboardLikeEvent) {\n    if (disabled) return;\n    if (e.key === 'Escape') {\n      e.preventDefault?.();\n      e.stopPropagation?.();\n      onDismiss?.('escape');\n    }\n  }\n\n  function handlePointerDownCapture(e: PointerLikeEvent) {\n    if (disabled) return;\n\n    const target = e.target;\n    if (!(target instanceof Node)) return;\n\n    // If no node provided, can't detect outside clicks\n    if (!node) return;\n\n    // Check if click is outside\n    if (!node.contains(target)) {\n      onDismiss?.('outside');\n    }\n  }\n\n  return {\n    onKeyDown: handleKeyDown,\n    // Use capture phase to catch events before they bubble\n    onPointerDownCapture: handlePointerDownCapture,\n  };\n}\n"],"mappings":";AA6DA,SAAgB,YAAY,EAAE,MAAM,UAAU,aAAiC;CAC7E,SAAS,cAAc,GAAsB;AAC3C,MAAI,SAAU;AACd,MAAI,EAAE,QAAQ,UAAU;AACtB,KAAE,kBAAkB;AACpB,KAAE,mBAAmB;AACrB,eAAY,SAAS;;;CAIzB,SAAS,yBAAyB,GAAqB;AACrD,MAAI,SAAU;EAEd,MAAM,SAAS,EAAE;AACjB,MAAI,EAAE,kBAAkB,MAAO;AAG/B,MAAI,CAAC,KAAM;AAGX,MAAI,CAAC,KAAK,SAAS,OAAO,CACxB,aAAY,UAAU;;AAI1B,QAAO;EACL,WAAW;EAEX,sBAAsB;EACvB"}

package/dist/foundations/interactions/focusable.d.ts

@@ -0,0 +1,22 @@
+//#region src/foundations/interactions/focusable.d.ts
+/**
+ * focusable
+ *
+ * Normalize focus-related props for hosts.
+ * - No DOM manipulation here; returns props that the runtime may attach.
+ */
+interface FocusableOptions {
+  disabled?: boolean;
+  tabIndex?: number | undefined;
+}
+interface FocusableResult {
+  tabIndex?: number;
+  'aria-disabled'?: 'true';
+}
+declare function focusable({
+  disabled,
+  tabIndex
+}: FocusableOptions): FocusableResult;
+//#endregion
+export { FocusableOptions, FocusableResult, focusable };
+//# sourceMappingURL=focusable.d.ts.map

package/dist/foundations/interactions/focusable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.d.ts","names":[],"sources":["../../../src/foundations/interactions/focusable.ts"],"mappings":";;AASA;;;;;UAAiB,gBAAA;EACf,QAAA;EACA,QAAA;AAAA;AAAA,UAGe,eAAA;EACf,QAAA;EACA,eAAA;AAAA;AAAA,iBAGc,SAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,gBAAA,GAAmB,eAAA"}

package/dist/foundations/interactions/focusable.js

@@ -0,0 +1,18 @@
+import { ariaDisabled } from "../utilities/aria.js";
+//#region src/foundations/interactions/focusable.ts
+/**
+* focusable
+*
+* Normalize focus-related props for hosts.
+* - No DOM manipulation here; returns props that the runtime may attach.
+*/
+function focusable({ disabled, tabIndex }) {
+	return {
+		tabIndex: disabled ? -1 : tabIndex === void 0 ? 0 : tabIndex,
+		...ariaDisabled(disabled)
+	};
+}
+//#endregion
+export { focusable };
+
+//# sourceMappingURL=focusable.js.map

package/dist/foundations/interactions/focusable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.js","names":[],"sources":["../../../src/foundations/interactions/focusable.ts"],"sourcesContent":["/**\n * focusable\n *\n * Normalize focus-related props for hosts.\n * - No DOM manipulation here; returns props that the runtime may attach.\n */\n\nimport { ariaDisabled } from '../utilities/aria';\n\nexport interface FocusableOptions {\n  disabled?: boolean;\n  tabIndex?: number | undefined;\n}\n\nexport interface FocusableResult {\n  tabIndex?: number;\n  'aria-disabled'?: 'true';\n}\n\nexport function focusable({\n  disabled,\n  tabIndex,\n}: FocusableOptions): FocusableResult {\n  return {\n    tabIndex: disabled ? -1 : tabIndex === undefined ? 0 : tabIndex,\n    ...ariaDisabled(disabled),\n  };\n}\n"],"mappings":";;;;;;;;AAmBA,SAAgB,UAAU,EACxB,UACA,YACoC;AACpC,QAAO;EACL,UAAU,WAAW,KAAK,aAAa,SAAY,IAAI;EACvD,GAAG,aAAa,SAAS;EAC1B"}

package/dist/foundations/interactions/hoverable.d.ts

@@ -0,0 +1,26 @@
+import { DefaultPreventable, PropagationStoppable } from "../utilities/event-types.js";
+
+//#region src/foundations/interactions/hoverable.d.ts
+/**
+ * hoverable
+ *
+ * Produces props for pointer enter/leave handling. Pure and deterministic.
+ */
+interface HoverableOptions {
+  disabled?: boolean;
+  onEnter?: (e: HoverEvent) => void;
+  onLeave?: (e: HoverEvent) => void;
+}
+type HoverEvent = DefaultPreventable & PropagationStoppable;
+interface HoverableResult {
+  onPointerEnter?: (e: HoverEvent) => void;
+  onPointerLeave?: (e: HoverEvent) => void;
+}
+declare function hoverable({
+  disabled,
+  onEnter,
+  onLeave
+}: HoverableOptions): HoverableResult;
+//#endregion
+export { HoverableOptions, HoverableResult, hoverable };
+//# sourceMappingURL=hoverable.d.ts.map

package/dist/foundations/interactions/hoverable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hoverable.d.ts","names":[],"sources":["../../../src/foundations/interactions/hoverable.ts"],"mappings":";;;;;;AAMA;;UAAiB,gBAAA;EACf,QAAA;EACA,OAAA,IAAW,CAAA,EAAG,UAAA;EACd,OAAA,IAAW,CAAA,EAAG,UAAA;AAAA;AAAA,KAQX,UAAA,GAAa,kBAAA,GAAqB,oBAAA;AAAA,UAEtB,eAAA;EACf,cAAA,IAAkB,CAAA,EAAG,UAAA;EACrB,cAAA,IAAkB,CAAA,EAAG,UAAA;AAAA;AAAA,iBAGP,SAAA,CAAA;EACd,QAAA;EACA,OAAA;EACA;AAAA,GACC,gBAAA,GAAmB,eAAA"}

package/dist/foundations/interactions/hoverable.js

@@ -0,0 +1,15 @@
+//#region src/foundations/interactions/hoverable.ts
+function hoverable({ disabled, onEnter, onLeave }) {
+	return {
+		onPointerEnter: disabled ? void 0 : (e) => {
+			onEnter?.(e);
+		},
+		onPointerLeave: disabled ? void 0 : (e) => {
+			onLeave?.(e);
+		}
+	};
+}
+//#endregion
+export { hoverable };
+
+//# sourceMappingURL=hoverable.js.map

package/dist/foundations/interactions/hoverable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hoverable.js","names":[],"sources":["../../../src/foundations/interactions/hoverable.ts"],"sourcesContent":["/**\n * hoverable\n *\n * Produces props for pointer enter/leave handling. Pure and deterministic.\n */\n\nexport interface HoverableOptions {\n  disabled?: boolean;\n  onEnter?: (e: HoverEvent) => void;\n  onLeave?: (e: HoverEvent) => void;\n}\n\nimport type {\n  DefaultPreventable,\n  PropagationStoppable,\n} from '../utilities/event-types';\n\ntype HoverEvent = DefaultPreventable & PropagationStoppable;\n\nexport interface HoverableResult {\n  onPointerEnter?: (e: HoverEvent) => void;\n  onPointerLeave?: (e: HoverEvent) => void;\n}\n\nexport function hoverable({\n  disabled,\n  onEnter,\n  onLeave,\n}: HoverableOptions): HoverableResult {\n  return {\n    onPointerEnter: disabled\n      ? undefined\n      : (e) => {\n          onEnter?.(e);\n        },\n    onPointerLeave: disabled\n      ? undefined\n      : (e) => {\n          onLeave?.(e);\n        },\n  };\n}\n"],"mappings":";AAwBA,SAAgB,UAAU,EACxB,UACA,SACA,WACoC;AACpC,QAAO;EACL,gBAAgB,WACZ,UACC,MAAM;AACL,aAAU,EAAE;;EAElB,gBAAgB,WACZ,UACC,MAAM;AACL,aAAU,EAAE;;EAEnB"}

package/dist/foundations/interactions/interaction-policy.d.ts

@@ -0,0 +1,50 @@
+import { Ref } from "../utilities/compose-ref.js";
+import { DefaultPreventable, KeyboardLikeEvent, PropagationStoppable } from "../utilities/event-types.js";
+//#region src/foundations/interactions/interaction-policy.d.ts
+interface InteractionPolicyInput {
+  /** Whether the host element is a native interactive element (button, a, etc) */
+  isNative: boolean;
+  /** Disabled state - checked ONLY here, never in components */
+  disabled: boolean;
+  /** User-provided press handler - semantic action, not DOM event */
+  onPress?: (e: Event) => void;
+  /** Optional ref to compose */
+  ref?: Ref<unknown>;
+}
+/**
+ * THE interaction policy. Components MUST use this, NEVER implement
+ * interaction logic directly.
+ */
+declare function applyInteractionPolicy({
+  isNative,
+  disabled,
+  onPress,
+  ref
+}: InteractionPolicyInput): {
+  disabled: true | undefined;
+  onClick: (e: Event) => void;
+  ref: Ref<unknown>;
+} | {
+  'aria-disabled': true | undefined;
+  tabIndex: number;
+  ref: Ref<unknown>;
+  onClick: (e: DefaultPreventable & PropagationStoppable) => void;
+  disabled?: true;
+  role?: "button";
+  onKeyDown?: (e: KeyboardLikeEvent) => void;
+  onKeyUp?: (e: KeyboardLikeEvent) => void;
+};
+/**
+ * Merge rule for Slot / asChild
+ *
+ * Precedence:
+ *   policy → user → child
+ *
+ * Event handlers are composed (policy first).
+ * Refs are always composed.
+ * Policy props MUST take precedence to enforce invariants.
+ */
+declare function mergeInteractionProps(childProps: Record<string, unknown>, policyProps: Record<string, unknown>, userProps?: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps };
+//# sourceMappingURL=interaction-policy.d.ts.map

package/dist/foundations/interactions/interaction-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-policy.d.ts","names":[],"sources":["../../../src/foundations/interactions/interaction-policy.ts"],"mappings":";;;UA6DiB,sBAAA;;EAEf,QAAA;;EAEA,QAAA;;EAEA,OAAA,IAAW,CAAA,EAAG,KAAA;;EAEd,GAAA,GAAM,GAAA;AAAA;;;AAwDR;;iBAjDgB,sBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA,OAAA;EACA;AAAA,GACC,sBAAA;;eAcgB,KAAA;;;;;;;;;;;;;;;;;;;;;;iBA8BH,qBAAA,CACd,UAAA,EAAY,MAAA,mBACZ,WAAA,EAAa,MAAA,mBACb,SAAA,GAAY,MAAA,oBAAuB,MAAA"}