@alneas/appkit-react 0.1.0 → 0.2.0

package/dist/ai/action/context.d.ts

@@ -1,8 +1,24 @@
 import { ActionRegistry } from '@alneas/appkit-core/ai';
-/** Context shared by screen-scoped action hooks. */
+/**
+ * Nullable React context holding a screen-owned ActionRegistry.
+ *
+ * @see ScreenActionProvider for setup and useScreenActionRegistry for consumption.
+ */
 export declare const ScreenActionContext: import('react').Context<ActionRegistry | null>;
 /**
- * Accesses the current screen's ActionRegistry.
- * Throws an Error if used outside a ScreenActionProvider.
+ * Reads the nearest screen-owned action registry.
+ *
+ * @returns Current ActionRegistry instance; the hook does not subscribe to changes.
+ *
+ * @throws Error when used outside ScreenActionProvider.
+ *
+ * @remarks No styles are required. Use reactive list hooks when registrations affect render.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenActionRegistry } from '@alneas/appkit-react/ai/action';
+ * function Content() { const registry = useScreenActionRegistry(); return <span>{registry.listActions().length}</span>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenActionRegistry(): ActionRegistry;

package/dist/ai/action/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":["ScreenActionContext","createContext","useScreenActionRegistry","context","useContext"],"sources":["../../../src/ai/action/context.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { ActionRegistry } from \"@alneas/appkit-core/ai\";\n\n/** Context shared by screen-scoped action hooks. */\nexport const ScreenActionContext = createContext<ActionRegistry | null>(null);\n\n/**\n * Accesses the current screen's ActionRegistry.\n * Throws an Error if used outside a ScreenActionProvider.\n */\nexport function useScreenActionRegistry(): ActionRegistry {\n  const context = useContext(ScreenActionContext);\n  if (!context) {\n    throw new Error('useScreenActionRegistry must be used within a <ScreenActionProvider>');\n  }\n  return context;\n}\n"],"mappings":";;;AAIA,IAAaA,IAAsBC,EAAqC,IAAI;AAM5E,SAAgBC,IAA0C;CACxD,IAAMC,IAAUC,EAAWJ,CAAmB;CAC9C,IAAI,CAACG,GACH,MAAU,MAAM,sEAAsE;CAExF,OAAOA;AACT"}
+{"version":3,"file":"context.js","names":["ScreenActionContext","createContext","useScreenActionRegistry","context","useContext"],"sources":["../../../src/ai/action/context.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\nimport type { ActionRegistry } from \"@alneas/appkit-core/ai\";\n\n/**\n * Nullable React context holding a screen-owned ActionRegistry.\n *\n * @see ScreenActionProvider for setup and useScreenActionRegistry for consumption.\n */\nexport const ScreenActionContext = createContext<ActionRegistry | null>(null);\n\n/**\n * Reads the nearest screen-owned action registry.\n *\n * @returns Current ActionRegistry instance; the hook does not subscribe to changes.\n *\n * @throws Error when used outside ScreenActionProvider.\n *\n * @remarks No styles are required. Use reactive list hooks when registrations affect render.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenActionRegistry } from '@alneas/appkit-react/ai/action';\n * function Content() { const registry = useScreenActionRegistry(); return <span>{registry.listActions().length}</span>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenActionRegistry(): ActionRegistry {\n  const context = useContext(ScreenActionContext);\n  if (!context) {\n    throw new Error('useScreenActionRegistry must be used within a <ScreenActionProvider>');\n  }\n  return context;\n}\n"],"mappings":";;;AAQA,IAAaA,IAAsBC,EAAqC,IAAI;AAkB5E,SAAgBC,IAA0C;CACxD,IAAMC,IAAUC,EAAWJ,CAAmB;CAC9C,IAAI,CAACG,GACH,MAAU,MAAM,sEAAsE;CAExF,OAAOA;AACT"}

package/dist/ai/action/types.d.cts

@@ -1,7 +1,14 @@
 import { ReactNode } from 'react';
 import { ActionRegistry, ActionDefinition, ContextGetter } from '@alneas/appkit-core/ai';
-/** Props for ScreenActionProvider. */
+/**
+ * Provider inputs for a screen-specific registry.
+ *
+ * @see ScreenActionProvider for setup.
+ */
 export interface ScreenActionProviderProps {
+    /**
+     * Descendants that register or consume screen actions.
+     */
     children: ReactNode;
     /**
      * Optional custom ActionRegistry instance.
@@ -9,11 +16,36 @@ export interface ScreenActionProviderProps {
      */
     registry?: ActionRegistry;
 }
-/** Options for registering an action via useScreenAction. */
+/**
+ * Action definition accepted by useScreenAction without changing the Core contract.
+ *
+ * @typeParam TInput - Validated handler input; defaults to unknown.
+ *
+ * @typeParam TOutput - Handler result; defaults to unknown.
+ *
+ * @see useScreenAction for registration.
+ */
 export type UseScreenActionOptions<TInput = unknown, TOutput = unknown> = ActionDefinition<TInput, TOutput>;
-/** Options for registering a screen context via useScreenContext. */
+/**
+ * Named lazy context source registered by useScreenContext.
+ *
+ * @typeParam T - Getter result shape; defaults to unknown.
+ *
+ * @see useScreenContext for usage.
+ */
 export interface UseScreenContextOptions<T = unknown> {
+    /**
+     * Registry key; use a stable screen-specific value to avoid collisions.
+     */
     key: string;
+    /**
+     * Optional human/model-facing description.
+     */
     description?: string;
+    /**
+     * On-demand context getter; latest committed callback is invoked by registry reads.
+     *
+     * @returns Context value or promise of the value, according to the Core ContextGetter contract.
+     */
     getter: ContextGetter<T>;
 }

package/dist/ai/action/types.d.ts

@@ -1,7 +1,14 @@
 import { ReactNode } from 'react';
 import { ActionRegistry, ActionDefinition, ContextGetter } from '@alneas/appkit-core/ai';
-/** Props for ScreenActionProvider. */
+/**
+ * Provider inputs for a screen-specific registry.
+ *
+ * @see ScreenActionProvider for setup.
+ */
 export interface ScreenActionProviderProps {
+    /**
+     * Descendants that register or consume screen actions.
+     */
     children: ReactNode;
     /**
      * Optional custom ActionRegistry instance.
@@ -9,11 +16,36 @@ export interface ScreenActionProviderProps {
      */
     registry?: ActionRegistry;
 }
-/** Options for registering an action via useScreenAction. */
+/**
+ * Action definition accepted by useScreenAction without changing the Core contract.
+ *
+ * @typeParam TInput - Validated handler input; defaults to unknown.
+ *
+ * @typeParam TOutput - Handler result; defaults to unknown.
+ *
+ * @see useScreenAction for registration.
+ */
 export type UseScreenActionOptions<TInput = unknown, TOutput = unknown> = ActionDefinition<TInput, TOutput>;
-/** Options for registering a screen context via useScreenContext. */
+/**
+ * Named lazy context source registered by useScreenContext.
+ *
+ * @typeParam T - Getter result shape; defaults to unknown.
+ *
+ * @see useScreenContext for usage.
+ */
 export interface UseScreenContextOptions<T = unknown> {
+    /**
+     * Registry key; use a stable screen-specific value to avoid collisions.
+     */
     key: string;
+    /**
+     * Optional human/model-facing description.
+     */
     description?: string;
+    /**
+     * On-demand context getter; latest committed callback is invoked by registry reads.
+     *
+     * @returns Context value or promise of the value, according to the Core ContextGetter contract.
+     */
     getter: ContextGetter<T>;
 }

package/dist/ai/action/use-execution-session.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-execution-session.cjs","names":["useState","createExecutionSession","useSyncExternalStore","react","_alneas_appkit_core_ai","useExecutionSession","session"],"sources":["../../../src/ai/action/use-execution-session.ts"],"sourcesContent":["import { useLayoutEffect, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\n\n/** Creates a local session and subscribes to its bounded history. Unmount requests cancellation. */\nexport function useExecutionSession(): { session: ExecutionSession; history: readonly ExecutionRecord[] } {\n  const [session] = useState(() => createExecutionSession());\n  useLayoutEffect(() => () => { session.cancel(); }, [session]);\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  return { session, history };\n}\n"],"mappings":"A,2IAIA,SAAgBK,GAA0F,CACxG,GAAM,CAACC,IAAA,EAAWN,EAAAA,SAAAA,MAAAA,EAAeC,EAAAA,uBAAAA,CAAuB,CAAC,EAGzD,OAFA,EAAAE,EAAA,gBAAA,SAA4B,CAAEG,EAAQ,OAAO,CAAG,EAAG,CAACA,CAAO,CAAC,EAErD,CAAE,UAAS,SAAA,EADFJ,EAAAA,qBAAAA,CAAqBI,EAAQ,UAAWA,EAAQ,YAAaA,EAAQ,WACnE,CAAQ,CAC5B,C"}
+{"version":3,"file":"use-execution-session.cjs","names":["useState","createExecutionSession","useSyncExternalStore","react","_alneas_appkit_core_ai","useExecutionSession","session"],"sources":["../../../src/ai/action/use-execution-session.ts"],"sourcesContent":["import { useLayoutEffect, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\n\n/**\n * Creates one local execution session and subscribes to its bounded history.\n *\n * @returns Stable session controls and the current read-only history snapshot.\n *\n * @remarks Requires React; no context/styles. Cleanup requests cancellation but cannot\n * undo backend work or force an uncooperative task to stop. The session controls own\n * execution, cancellation, progress and history; no work starts automatically.\n *\n * @example\n * ```tsx\n * import { useExecutionSession } from '@alneas/appkit-react/ai/action';\n * export function HistoryCount() { const { history } = useExecutionSession(); return <output>{history.length}</output>; }\n * ```\n */\nexport function useExecutionSession(): {\n  /** Stable execution-session controls created for this mounted hook. */\n  session: ExecutionSession;\n  /** Current bounded execution snapshot, updated through subscription. */\n  history: readonly ExecutionRecord[];\n} {\n  const [session] = useState(() => createExecutionSession());\n  useLayoutEffect(() => () => { session.cancel(); }, [session]);\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  return { session, history };\n}\n"],"mappings":"A,2IAkBA,SAAgBK,GAKd,CACA,GAAM,CAACC,IAAA,EAAWN,EAAAA,SAAAA,MAAAA,EAAeC,EAAAA,uBAAAA,CAAuB,CAAC,EAGzD,OAFA,EAAAE,EAAA,gBAAA,SAA4B,CAAEG,EAAQ,OAAO,CAAG,EAAG,CAACA,CAAO,CAAC,EAErD,CAAE,UAAS,SAAA,EADFJ,EAAAA,qBAAAA,CAAqBI,EAAQ,UAAWA,EAAQ,YAAaA,EAAQ,WACnE,CAAQ,CAC5B,C"}

package/dist/ai/action/use-execution-session.d.cts

@@ -1,6 +1,22 @@
 import { ExecutionRecord, ExecutionSession } from '@alneas/appkit-core/ai';
-/** Creates a local session and subscribes to its bounded history. Unmount requests cancellation. */
+/**
+ * Creates one local execution session and subscribes to its bounded history.
+ *
+ * @returns Stable session controls and the current read-only history snapshot.
+ *
+ * @remarks Requires React; no context/styles. Cleanup requests cancellation but cannot
+ * undo backend work or force an uncooperative task to stop. The session controls own
+ * execution, cancellation, progress and history; no work starts automatically.
+ *
+ * @example
+ * ```tsx
+ * import { useExecutionSession } from '@alneas/appkit-react/ai/action';
+ * export function HistoryCount() { const { history } = useExecutionSession(); return <output>{history.length}</output>; }
+ * ```
+ */
 export declare function useExecutionSession(): {
+    /** Stable execution-session controls created for this mounted hook. */
     session: ExecutionSession;
+    /** Current bounded execution snapshot, updated through subscription. */
     history: readonly ExecutionRecord[];
 };

package/dist/ai/action/use-execution-session.d.ts

@@ -1,6 +1,22 @@
 import { ExecutionRecord, ExecutionSession } from '@alneas/appkit-core/ai';
-/** Creates a local session and subscribes to its bounded history. Unmount requests cancellation. */
+/**
+ * Creates one local execution session and subscribes to its bounded history.
+ *
+ * @returns Stable session controls and the current read-only history snapshot.
+ *
+ * @remarks Requires React; no context/styles. Cleanup requests cancellation but cannot
+ * undo backend work or force an uncooperative task to stop. The session controls own
+ * execution, cancellation, progress and history; no work starts automatically.
+ *
+ * @example
+ * ```tsx
+ * import { useExecutionSession } from '@alneas/appkit-react/ai/action';
+ * export function HistoryCount() { const { history } = useExecutionSession(); return <output>{history.length}</output>; }
+ * ```
+ */
 export declare function useExecutionSession(): {
+    /** Stable execution-session controls created for this mounted hook. */
     session: ExecutionSession;
+    /** Current bounded execution snapshot, updated through subscription. */
     history: readonly ExecutionRecord[];
 };

package/dist/ai/action/use-execution-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-execution-session.js","names":["useExecutionSession","session","useState","createExecutionSession","useLayoutEffect","useSyncExternalStore"],"sources":["../../../src/ai/action/use-execution-session.ts"],"sourcesContent":["import { useLayoutEffect, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\n\n/** Creates a local session and subscribes to its bounded history. Unmount requests cancellation. */\nexport function useExecutionSession(): { session: ExecutionSession; history: readonly ExecutionRecord[] } {\n  const [session] = useState(() => createExecutionSession());\n  useLayoutEffect(() => () => { session.cancel(); }, [session]);\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  return { session, history };\n}\n"],"mappings":";;;;AAIA,SAAgBA,IAA0F;CACxG,IAAM,CAACC,KAAWC,QAAeC,EAAuB,CAAC;CAGzD,OAFAC,cAA4B;EAAE,EAAQ,OAAO;CAAG,GAAG,CAACH,CAAO,CAAC,GAErD;EAAE;EAAS,SADFI,EAAqBJ,EAAQ,WAAWA,EAAQ,aAAaA,EAAQ,WACnE;CAAQ;AAC5B"}
+{"version":3,"file":"use-execution-session.js","names":["useExecutionSession","session","useState","createExecutionSession","useLayoutEffect","useSyncExternalStore"],"sources":["../../../src/ai/action/use-execution-session.ts"],"sourcesContent":["import { useLayoutEffect, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\n\n/**\n * Creates one local execution session and subscribes to its bounded history.\n *\n * @returns Stable session controls and the current read-only history snapshot.\n *\n * @remarks Requires React; no context/styles. Cleanup requests cancellation but cannot\n * undo backend work or force an uncooperative task to stop. The session controls own\n * execution, cancellation, progress and history; no work starts automatically.\n *\n * @example\n * ```tsx\n * import { useExecutionSession } from '@alneas/appkit-react/ai/action';\n * export function HistoryCount() { const { history } = useExecutionSession(); return <output>{history.length}</output>; }\n * ```\n */\nexport function useExecutionSession(): {\n  /** Stable execution-session controls created for this mounted hook. */\n  session: ExecutionSession;\n  /** Current bounded execution snapshot, updated through subscription. */\n  history: readonly ExecutionRecord[];\n} {\n  const [session] = useState(() => createExecutionSession());\n  useLayoutEffect(() => () => { session.cancel(); }, [session]);\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  return { session, history };\n}\n"],"mappings":";;;;AAkBA,SAAgBA,IAKd;CACA,IAAM,CAACC,KAAWC,QAAeC,EAAuB,CAAC;CAGzD,OAFAC,cAA4B;EAAE,EAAQ,OAAO;CAAG,GAAG,CAACH,CAAO,CAAC,GAErD;EAAE;EAAS,SADFI,EAAqBJ,EAAQ,WAAWA,EAAQ,aAAaA,EAAQ,WACnE;CAAQ;AAC5B"}

package/dist/ai/action/use-screen-action-registry.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-screen-action-registry.cjs","names":["useScreenActionRegistry","useCallback","useSyncExternalStore","require_ai_action_context","react","SSR_ACTIONS_SNAPSHOT","SSR_CONTEXTS_SNAPSHOT","useScreenActionList","registry","subscribe","onStoreChange","getSnapshot","getServerSnapshot","useScreenContextList","useScreenActions","id","input","context","key"],"sources":["../../../src/ai/action/use-screen-action-registry.ts"],"sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type {\n  ActionDescriptor,\n  ExecutionContext,\n  ActionResult,\n  ContextDescriptor,\n  ContextValueResult,\n} from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\nconst SSR_ACTIONS_SNAPSHOT: readonly ActionDescriptor[] = Object.freeze([]);\nconst SSR_CONTEXTS_SNAPSHOT: readonly ContextDescriptor[] = Object.freeze([]);\n\n/**\n * Returns a reactive list of currently registered actions on the current screen.\n * Safely integrated with useSyncExternalStore; retains snapshot reference equality\n * until registrations change.\n */\nexport function useScreenActionList(): readonly ActionDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listActions(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_ACTIONS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Returns a reactive list of currently registered contexts on the current screen.\n * Safely integrated with useSyncExternalStore; retains snapshot reference equality\n * until registrations change.\n */\nexport function useScreenContextList(): readonly ContextDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listContexts(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_CONTEXTS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Comprehensive hook providing the current screen's actions, contexts,\n * and execution/query helpers.\n */\nexport function useScreenActions(): {\n  actions: readonly ActionDescriptor[];\n  contexts: readonly ContextDescriptor[];\n  executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;\n  getContext: (key: string) => Promise<ContextValueResult<unknown>>;\n  getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;\n} {\n  const registry = useScreenActionRegistry();\n  const actions = useScreenActionList();\n  const contexts = useScreenContextList();\n\n  const executeAction = useCallback(\n    (id: string, input: unknown, context?: ExecutionContext) => registry.executeAction(id, input, context),\n    [registry]\n  );\n\n  const getContext = useCallback(\n    (key: string) => registry.getContext(key),\n    [registry]\n  );\n\n  const getAllContext = useCallback(\n    () => registry.getAllContext(),\n    [registry]\n  );\n\n  return {\n    actions,\n    contexts,\n    executeAction,\n    getContext,\n    getAllContext,\n  };\n}\n"],"mappings":"A,wIAUA,IAAMK,EAAoD,OAAO,OAAO,CAAC,CAAC,EACpEC,EAAsD,OAAO,OAAO,CAAC,CAAC,EAO5E,SAAgBC,GAAmD,CACjE,IAAMC,EAAWR,EAAAA,wBAAwB,EAEnCS,GAAA,EAAYR,EAAAA,YAAAA,CACf,GAA8BO,EAAS,UAAUE,CAAa,EAC/D,CAACF,CAAQ,CACX,EACMG,GAAA,EAAcV,EAAAA,YAAAA,KAAkBO,EAAS,YAAY,EAAG,CAACA,CAAQ,CAAC,EAClEI,GAAA,EAAoBX,EAAAA,YAAAA,KAAkBI,EAAsB,CAAC,CAAC,EAEpE,OAAA,EAAOH,EAAAA,qBAAAA,CAAqBO,EAAWE,EAAaC,CAAiB,CACvE,CAOA,SAAgBC,GAAqD,CACnE,IAAML,EAAWR,EAAAA,wBAAwB,EAEnCS,GAAA,EAAYR,EAAAA,YAAAA,CACf,GAA8BO,EAAS,UAAUE,CAAa,EAC/D,CAACF,CAAQ,CACX,EACMG,GAAA,EAAcV,EAAAA,YAAAA,KAAkBO,EAAS,aAAa,EAAG,CAACA,CAAQ,CAAC,EACnEI,GAAA,EAAoBX,EAAAA,YAAAA,KAAkBK,EAAuB,CAAC,CAAC,EAErE,OAAA,EAAOJ,EAAAA,qBAAAA,CAAqBO,EAAWE,EAAaC,CAAiB,CACvE,CAMA,SAAgBE,GAMd,CACA,IAAMN,EAAWR,EAAAA,wBAAwB,EAmBzC,MAAO,CACL,QAnBcO,EAmBd,EACA,SAnBeM,EAmBf,EACA,eAAA,EAlBoBZ,EAAAA,YAAAA,EACnB,EAAY,EAAgB,IAA+BO,EAAS,cAAcO,EAAIC,EAAOC,CAAO,EACrG,CAACT,CAAQ,CAgBT,EACA,YAAA,EAdiBP,EAAAA,YAAAA,CAChB,GAAgBO,EAAS,WAAWU,CAAG,EACxC,CAACV,CAAQ,CAYT,EACA,eAAA,EAVoBP,EAAAA,YAAAA,KACdO,EAAS,cAAc,EAC7B,CAACA,CAAQ,CAQT,CACF,CACF,C"}
+{"version":3,"file":"use-screen-action-registry.cjs","names":["useScreenActionRegistry","useCallback","useSyncExternalStore","require_ai_action_context","react","SSR_ACTIONS_SNAPSHOT","SSR_CONTEXTS_SNAPSHOT","useScreenActionList","registry","subscribe","onStoreChange","getSnapshot","getServerSnapshot","useScreenContextList","useScreenActions","id","input","context","key"],"sources":["../../../src/ai/action/use-screen-action-registry.ts"],"sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type {\n  ActionDescriptor,\n  ExecutionContext,\n  ActionResult,\n  ContextDescriptor,\n  ContextValueResult,\n} from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\nconst SSR_ACTIONS_SNAPSHOT: readonly ActionDescriptor[] = Object.freeze([]);\nconst SSR_CONTEXTS_SNAPSHOT: readonly ContextDescriptor[] = Object.freeze([]);\n\n/**\n * Subscribes to action descriptors registered on the current screen.\n *\n * @returns Read-only action descriptors; the server snapshot is empty.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenActionList } from '@alneas/appkit-react/ai/action';\n * function Content() { return <output>{useScreenActionList().length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenActionList(): readonly ActionDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listActions(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_ACTIONS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Subscribes to context descriptors registered on the current screen.\n *\n * @returns Read-only context descriptors; the server snapshot is empty.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenContextList } from '@alneas/appkit-react/ai/action';\n * function Content() { return <output>{useScreenContextList().length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenContextList(): readonly ContextDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listContexts(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_CONTEXTS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Combines reactive action/context lists with bound execution and context-read helpers.\n *\n * @returns Descriptors plus executeAction, getContext and getAllContext bound to the current registry.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenActions } from '@alneas/appkit-react/ai/action';\n * function Content() { const { actions } = useScreenActions(); return <output>{actions.length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenActions(): {\n  /**\n   * Reactive action descriptors.\n   */\n  actions: readonly ActionDescriptor[];\n  /**\n   * Reactive lazy-context descriptors.\n   */\n  contexts: readonly ContextDescriptor[];\n  /**\n   * Execute a registered action explicitly.\n   *\n   * @param id - Registered action identifier.\n   *\n   * @param input - Untrusted input passed to its validator.\n   *\n   * @param context - Optional abort/progress context.\n   *\n   * @returns Core ActionResult containing output or a structured failure.\n   */\n  executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;\n  /**\n   * Read one registered lazy context.\n   *\n   * @param key - Registered context key.\n   *\n   * @returns Core context result with a value or structured failure.\n   */\n  getContext: (key: string) => Promise<ContextValueResult<unknown>>;\n  /**\n   * Read all registered context getters.\n   *\n   * @returns Keyed context results, possibly empty.\n   */\n  getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;\n} {\n  const registry = useScreenActionRegistry();\n  const actions = useScreenActionList();\n  const contexts = useScreenContextList();\n\n  const executeAction = useCallback(\n    (id: string, input: unknown, context?: ExecutionContext) => registry.executeAction(id, input, context),\n    [registry]\n  );\n\n  const getContext = useCallback(\n    (key: string) => registry.getContext(key),\n    [registry]\n  );\n\n  const getAllContext = useCallback(\n    () => registry.getAllContext(),\n    [registry]\n  );\n\n  return {\n    actions,\n    contexts,\n    executeAction,\n    getContext,\n    getAllContext,\n  };\n}\n"],"mappings":"A,wIAUA,IAAMK,EAAoD,OAAO,OAAO,CAAC,CAAC,EACpEC,EAAsD,OAAO,OAAO,CAAC,CAAC,EAoB5E,SAAgBC,GAAmD,CACjE,IAAMC,EAAWR,EAAAA,wBAAwB,EAEnCS,GAAA,EAAYR,EAAAA,YAAAA,CACf,GAA8BO,EAAS,UAAUE,CAAa,EAC/D,CAACF,CAAQ,CACX,EACMG,GAAA,EAAcV,EAAAA,YAAAA,KAAkBO,EAAS,YAAY,EAAG,CAACA,CAAQ,CAAC,EAClEI,GAAA,EAAoBX,EAAAA,YAAAA,KAAkBI,EAAsB,CAAC,CAAC,EAEpE,OAAA,EAAOH,EAAAA,qBAAAA,CAAqBO,EAAWE,EAAaC,CAAiB,CACvE,CAoBA,SAAgBC,GAAqD,CACnE,IAAML,EAAWR,EAAAA,wBAAwB,EAEnCS,GAAA,EAAYR,EAAAA,YAAAA,CACf,GAA8BO,EAAS,UAAUE,CAAa,EAC/D,CAACF,CAAQ,CACX,EACMG,GAAA,EAAcV,EAAAA,YAAAA,KAAkBO,EAAS,aAAa,EAAG,CAACA,CAAQ,CAAC,EACnEI,GAAA,EAAoBX,EAAAA,YAAAA,KAAkBK,EAAuB,CAAC,CAAC,EAErE,OAAA,EAAOJ,EAAAA,qBAAAA,CAAqBO,EAAWE,EAAaC,CAAiB,CACvE,CAoBA,SAAgBE,GAmCd,CACA,IAAMN,EAAWR,EAAAA,wBAAwB,EAmBzC,MAAO,CACL,QAnBcO,EAmBd,EACA,SAnBeM,EAmBf,EACA,eAAA,EAlBoBZ,EAAAA,YAAAA,EACnB,EAAY,EAAgB,IAA+BO,EAAS,cAAcO,EAAIC,EAAOC,CAAO,EACrG,CAACT,CAAQ,CAgBT,EACA,YAAA,EAdiBP,EAAAA,YAAAA,CAChB,GAAgBO,EAAS,WAAWU,CAAG,EACxC,CAACV,CAAQ,CAYT,EACA,eAAA,EAVoBP,EAAAA,YAAAA,KACdO,EAAS,cAAc,EAC7B,CAACA,CAAQ,CAQT,CACF,CACF,C"}

package/dist/ai/action/use-screen-action-registry.d.cts

@@ -1,24 +1,93 @@
 import { ActionDescriptor, ExecutionContext, ActionResult, ContextDescriptor, ContextValueResult } from '@alneas/appkit-core/ai';
 /**
- * Returns a reactive list of currently registered actions on the current screen.
- * Safely integrated with useSyncExternalStore; retains snapshot reference equality
- * until registrations change.
+ * Subscribes to action descriptors registered on the current screen.
+ *
+ * @returns Read-only action descriptors; the server snapshot is empty.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenActionList } from '@alneas/appkit-react/ai/action';
+ * function Content() { return <output>{useScreenActionList().length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenActionList(): readonly ActionDescriptor[];
 /**
- * Returns a reactive list of currently registered contexts on the current screen.
- * Safely integrated with useSyncExternalStore; retains snapshot reference equality
- * until registrations change.
+ * Subscribes to context descriptors registered on the current screen.
+ *
+ * @returns Read-only context descriptors; the server snapshot is empty.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenContextList } from '@alneas/appkit-react/ai/action';
+ * function Content() { return <output>{useScreenContextList().length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenContextList(): readonly ContextDescriptor[];
 /**
- * Comprehensive hook providing the current screen's actions, contexts,
- * and execution/query helpers.
+ * Combines reactive action/context lists with bound execution and context-read helpers.
+ *
+ * @returns Descriptors plus executeAction, getContext and getAllContext bound to the current registry.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenActions } from '@alneas/appkit-react/ai/action';
+ * function Content() { const { actions } = useScreenActions(); return <output>{actions.length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenActions(): {
+    /**
+     * Reactive action descriptors.
+     */
     actions: readonly ActionDescriptor[];
+    /**
+     * Reactive lazy-context descriptors.
+     */
     contexts: readonly ContextDescriptor[];
+    /**
+     * Execute a registered action explicitly.
+     *
+     * @param id - Registered action identifier.
+     *
+     * @param input - Untrusted input passed to its validator.
+     *
+     * @param context - Optional abort/progress context.
+     *
+     * @returns Core ActionResult containing output or a structured failure.
+     */
     executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;
+    /**
+     * Read one registered lazy context.
+     *
+     * @param key - Registered context key.
+     *
+     * @returns Core context result with a value or structured failure.
+     */
     getContext: (key: string) => Promise<ContextValueResult<unknown>>;
+    /**
+     * Read all registered context getters.
+     *
+     * @returns Keyed context results, possibly empty.
+     */
     getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;
 };

package/dist/ai/action/use-screen-action-registry.d.ts

@@ -1,24 +1,93 @@
 import { ActionDescriptor, ExecutionContext, ActionResult, ContextDescriptor, ContextValueResult } from '@alneas/appkit-core/ai';
 /**
- * Returns a reactive list of currently registered actions on the current screen.
- * Safely integrated with useSyncExternalStore; retains snapshot reference equality
- * until registrations change.
+ * Subscribes to action descriptors registered on the current screen.
+ *
+ * @returns Read-only action descriptors; the server snapshot is empty.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenActionList } from '@alneas/appkit-react/ai/action';
+ * function Content() { return <output>{useScreenActionList().length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenActionList(): readonly ActionDescriptor[];
 /**
- * Returns a reactive list of currently registered contexts on the current screen.
- * Safely integrated with useSyncExternalStore; retains snapshot reference equality
- * until registrations change.
+ * Subscribes to context descriptors registered on the current screen.
+ *
+ * @returns Read-only context descriptors; the server snapshot is empty.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenContextList } from '@alneas/appkit-react/ai/action';
+ * function Content() { return <output>{useScreenContextList().length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenContextList(): readonly ContextDescriptor[];
 /**
- * Comprehensive hook providing the current screen's actions, contexts,
- * and execution/query helpers.
+ * Combines reactive action/context lists with bound execution and context-read helpers.
+ *
+ * @returns Descriptors plus executeAction, getContext and getAllContext bound to the current registry.
+ *
+ * @throws Error without ScreenActionProvider.
+ *
+ * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.
+ * List snapshots remain stable until registrations change. Actions execute only on an
+ * explicit executeAction call; backend authorization remains host-owned.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenActions } from '@alneas/appkit-react/ai/action';
+ * function Content() { const { actions } = useScreenActions(); return <output>{actions.length}</output>; }
+ * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }
+ * ```
  */
 export declare function useScreenActions(): {
+    /**
+     * Reactive action descriptors.
+     */
     actions: readonly ActionDescriptor[];
+    /**
+     * Reactive lazy-context descriptors.
+     */
     contexts: readonly ContextDescriptor[];
+    /**
+     * Execute a registered action explicitly.
+     *
+     * @param id - Registered action identifier.
+     *
+     * @param input - Untrusted input passed to its validator.
+     *
+     * @param context - Optional abort/progress context.
+     *
+     * @returns Core ActionResult containing output or a structured failure.
+     */
     executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;
+    /**
+     * Read one registered lazy context.
+     *
+     * @param key - Registered context key.
+     *
+     * @returns Core context result with a value or structured failure.
+     */
     getContext: (key: string) => Promise<ContextValueResult<unknown>>;
+    /**
+     * Read all registered context getters.
+     *
+     * @returns Keyed context results, possibly empty.
+     */
     getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;
 };

package/dist/ai/action/use-screen-action-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-screen-action-registry.js","names":["SSR_ACTIONS_SNAPSHOT","SSR_CONTEXTS_SNAPSHOT","useScreenActionList","registry","useScreenActionRegistry","subscribe","useCallback","onStoreChange","getSnapshot","getServerSnapshot","useSyncExternalStore","useScreenContextList","useScreenActions","id","input","context","key"],"sources":["../../../src/ai/action/use-screen-action-registry.ts"],"sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type {\n  ActionDescriptor,\n  ExecutionContext,\n  ActionResult,\n  ContextDescriptor,\n  ContextValueResult,\n} from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\nconst SSR_ACTIONS_SNAPSHOT: readonly ActionDescriptor[] = Object.freeze([]);\nconst SSR_CONTEXTS_SNAPSHOT: readonly ContextDescriptor[] = Object.freeze([]);\n\n/**\n * Returns a reactive list of currently registered actions on the current screen.\n * Safely integrated with useSyncExternalStore; retains snapshot reference equality\n * until registrations change.\n */\nexport function useScreenActionList(): readonly ActionDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listActions(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_ACTIONS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Returns a reactive list of currently registered contexts on the current screen.\n * Safely integrated with useSyncExternalStore; retains snapshot reference equality\n * until registrations change.\n */\nexport function useScreenContextList(): readonly ContextDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listContexts(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_CONTEXTS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Comprehensive hook providing the current screen's actions, contexts,\n * and execution/query helpers.\n */\nexport function useScreenActions(): {\n  actions: readonly ActionDescriptor[];\n  contexts: readonly ContextDescriptor[];\n  executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;\n  getContext: (key: string) => Promise<ContextValueResult<unknown>>;\n  getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;\n} {\n  const registry = useScreenActionRegistry();\n  const actions = useScreenActionList();\n  const contexts = useScreenContextList();\n\n  const executeAction = useCallback(\n    (id: string, input: unknown, context?: ExecutionContext) => registry.executeAction(id, input, context),\n    [registry]\n  );\n\n  const getContext = useCallback(\n    (key: string) => registry.getContext(key),\n    [registry]\n  );\n\n  const getAllContext = useCallback(\n    () => registry.getAllContext(),\n    [registry]\n  );\n\n  return {\n    actions,\n    contexts,\n    executeAction,\n    getContext,\n    getAllContext,\n  };\n}\n"],"mappings":";;;;AAUA,IAAMA,IAAoD,OAAO,OAAO,CAAC,CAAC,GACpEC,IAAsD,OAAO,OAAO,CAAC,CAAC;AAO5E,SAAgBC,IAAmD;CACjE,IAAMC,IAAWC,EAAwB,GAEnCC,IAAYC,GACf,MAA8BH,EAAS,UAAUI,CAAa,GAC/D,CAACJ,CAAQ,CACX,GACMK,IAAcF,QAAkBH,EAAS,YAAY,GAAG,CAACA,CAAQ,CAAC,GAClEM,IAAoBH,QAAkBN,GAAsB,CAAC,CAAC;CAEpE,OAAOU,EAAqBL,GAAWG,GAAaC,CAAiB;AACvE;AAOA,SAAgBE,IAAqD;CACnE,IAAMR,IAAWC,EAAwB,GAEnCC,IAAYC,GACf,MAA8BH,EAAS,UAAUI,CAAa,GAC/D,CAACJ,CAAQ,CACX,GACMK,IAAcF,QAAkBH,EAAS,aAAa,GAAG,CAACA,CAAQ,CAAC,GACnEM,IAAoBH,QAAkBL,GAAuB,CAAC,CAAC;CAErE,OAAOS,EAAqBL,GAAWG,GAAaC,CAAiB;AACvE;AAMA,SAAgBG,IAMd;CACA,IAAMT,IAAWC,EAAwB;CAmBzC,OAAO;EACL,SAnBcF,EAmBd;EACA,UAnBeS,EAmBf;EACA,eAlBoBL,GACnB,GAAY,GAAgB,MAA+BH,EAAS,cAAcU,GAAIC,GAAOC,CAAO,GACrG,CAACZ,CAAQ,CAgBT;EACA,YAdiBG,GAChB,MAAgBH,EAAS,WAAWa,CAAG,GACxC,CAACb,CAAQ,CAYT;EACA,eAVoBG,QACdH,EAAS,cAAc,GAC7B,CAACA,CAAQ,CAQT;CACF;AACF"}
+{"version":3,"file":"use-screen-action-registry.js","names":["SSR_ACTIONS_SNAPSHOT","SSR_CONTEXTS_SNAPSHOT","useScreenActionList","registry","useScreenActionRegistry","subscribe","useCallback","onStoreChange","getSnapshot","getServerSnapshot","useSyncExternalStore","useScreenContextList","useScreenActions","id","input","context","key"],"sources":["../../../src/ai/action/use-screen-action-registry.ts"],"sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport type {\n  ActionDescriptor,\n  ExecutionContext,\n  ActionResult,\n  ContextDescriptor,\n  ContextValueResult,\n} from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\nconst SSR_ACTIONS_SNAPSHOT: readonly ActionDescriptor[] = Object.freeze([]);\nconst SSR_CONTEXTS_SNAPSHOT: readonly ContextDescriptor[] = Object.freeze([]);\n\n/**\n * Subscribes to action descriptors registered on the current screen.\n *\n * @returns Read-only action descriptors; the server snapshot is empty.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenActionList } from '@alneas/appkit-react/ai/action';\n * function Content() { return <output>{useScreenActionList().length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenActionList(): readonly ActionDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listActions(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_ACTIONS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Subscribes to context descriptors registered on the current screen.\n *\n * @returns Read-only context descriptors; the server snapshot is empty.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenContextList } from '@alneas/appkit-react/ai/action';\n * function Content() { return <output>{useScreenContextList().length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenContextList(): readonly ContextDescriptor[] {\n  const registry = useScreenActionRegistry();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => registry.subscribe(onStoreChange),\n    [registry]\n  );\n  const getSnapshot = useCallback(() => registry.listContexts(), [registry]);\n  const getServerSnapshot = useCallback(() => SSR_CONTEXTS_SNAPSHOT, []);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n/**\n * Combines reactive action/context lists with bound execution and context-read helpers.\n *\n * @returns Descriptors plus executeAction, getContext and getAllContext bound to the current registry.\n *\n * @throws Error without ScreenActionProvider.\n *\n * @remarks Requires ScreenActionProvider; no styles. Subscriptions are removed on cleanup.\n * List snapshots remain stable until registrations change. Actions execute only on an\n * explicit executeAction call; backend authorization remains host-owned.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenActions } from '@alneas/appkit-react/ai/action';\n * function Content() { const { actions } = useScreenActions(); return <output>{actions.length}</output>; }\n * export function Screen() { return <ScreenActionProvider><Content /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenActions(): {\n  /**\n   * Reactive action descriptors.\n   */\n  actions: readonly ActionDescriptor[];\n  /**\n   * Reactive lazy-context descriptors.\n   */\n  contexts: readonly ContextDescriptor[];\n  /**\n   * Execute a registered action explicitly.\n   *\n   * @param id - Registered action identifier.\n   *\n   * @param input - Untrusted input passed to its validator.\n   *\n   * @param context - Optional abort/progress context.\n   *\n   * @returns Core ActionResult containing output or a structured failure.\n   */\n  executeAction: (id: string, input: unknown, context?: ExecutionContext) => Promise<ActionResult<unknown>>;\n  /**\n   * Read one registered lazy context.\n   *\n   * @param key - Registered context key.\n   *\n   * @returns Core context result with a value or structured failure.\n   */\n  getContext: (key: string) => Promise<ContextValueResult<unknown>>;\n  /**\n   * Read all registered context getters.\n   *\n   * @returns Keyed context results, possibly empty.\n   */\n  getAllContext: () => Promise<Record<string, ContextValueResult<unknown>>>;\n} {\n  const registry = useScreenActionRegistry();\n  const actions = useScreenActionList();\n  const contexts = useScreenContextList();\n\n  const executeAction = useCallback(\n    (id: string, input: unknown, context?: ExecutionContext) => registry.executeAction(id, input, context),\n    [registry]\n  );\n\n  const getContext = useCallback(\n    (key: string) => registry.getContext(key),\n    [registry]\n  );\n\n  const getAllContext = useCallback(\n    () => registry.getAllContext(),\n    [registry]\n  );\n\n  return {\n    actions,\n    contexts,\n    executeAction,\n    getContext,\n    getAllContext,\n  };\n}\n"],"mappings":";;;;AAUA,IAAMA,IAAoD,OAAO,OAAO,CAAC,CAAC,GACpEC,IAAsD,OAAO,OAAO,CAAC,CAAC;AAoB5E,SAAgBC,IAAmD;CACjE,IAAMC,IAAWC,EAAwB,GAEnCC,IAAYC,GACf,MAA8BH,EAAS,UAAUI,CAAa,GAC/D,CAACJ,CAAQ,CACX,GACMK,IAAcF,QAAkBH,EAAS,YAAY,GAAG,CAACA,CAAQ,CAAC,GAClEM,IAAoBH,QAAkBN,GAAsB,CAAC,CAAC;CAEpE,OAAOU,EAAqBL,GAAWG,GAAaC,CAAiB;AACvE;AAoBA,SAAgBE,IAAqD;CACnE,IAAMR,IAAWC,EAAwB,GAEnCC,IAAYC,GACf,MAA8BH,EAAS,UAAUI,CAAa,GAC/D,CAACJ,CAAQ,CACX,GACMK,IAAcF,QAAkBH,EAAS,aAAa,GAAG,CAACA,CAAQ,CAAC,GACnEM,IAAoBH,QAAkBL,GAAuB,CAAC,CAAC;CAErE,OAAOS,EAAqBL,GAAWG,GAAaC,CAAiB;AACvE;AAoBA,SAAgBG,IAmCd;CACA,IAAMT,IAAWC,EAAwB;CAmBzC,OAAO;EACL,SAnBcF,EAmBd;EACA,UAnBeS,EAmBf;EACA,eAlBoBL,GACnB,GAAY,GAAgB,MAA+BH,EAAS,cAAcU,GAAIC,GAAOC,CAAO,GACrG,CAACZ,CAAQ,CAgBT;EACA,YAdiBG,GAChB,MAAgBH,EAAS,WAAWa,CAAG,GACxC,CAACb,CAAQ,CAYT;EACA,eAVoBG,QACdH,EAAS,cAAc,GAC7B,CAACA,CAAQ,CAQT;CACF;AACF"}

package/dist/ai/action/use-screen-action.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-screen-action.cjs","names":["useScreenActionRegistry","useRef","require_ai_action_context","react","useScreenAction","registry","actionRef","action","unregister","input","context","id","description","metadata"],"sources":["../../../src/ai/action/use-screen-action.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ActionDefinition, ActionValidator, ExecutionContext } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\n/**\n * Registers an action on the current screen's ActionRegistry.\n *\n * Handler and validator automatically capture the latest committed\n * props and state via refs without requiring dependency arrays.\n * Metadata is a registration descriptor; keep it stable and replace it to update the list.\n * The action is automatically unregistered when the component unmounts\n * or when the action ID changes.\n */\nexport function useScreenAction<TInput = unknown, TOutput = unknown>(\n  action: ActionDefinition<TInput, TOutput>\n): void {\n  const registry = useScreenActionRegistry();\n\n  const actionRef = useRef(action);\n  useLayoutEffect(() => {\n    actionRef.current = action;\n  });\n\n  const { id, description, metadata } = action;\n\n  useLayoutEffect(() => {\n    const wrappedValidate: ActionValidator<TInput> = (input) => {\n      return actionRef.current.validate(input);\n    };\n\n    const wrappedHandler = (input: TInput, context?: ExecutionContext) => {\n      return context ? actionRef.current.handler(input, context) : actionRef.current.handler(input);\n    };\n\n    const unregister = registry.registerAction({\n      id,\n      description,\n      validate: wrappedValidate,\n      handler: wrappedHandler,\n      metadata,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, id, description, metadata]);\n}\n"],"mappings":"A,wIAaA,SAAgBI,EACd,EACM,CACN,IAAMC,EAAWL,EAAAA,wBAAwB,EAEnCM,GAAA,EAAYL,EAAAA,OAAAA,CAAOM,CAAM,GAC/B,EAAAJ,EAAA,gBAAA,KAAsB,CACpB,EAAU,QAAUI,CACtB,CAAC,EAED,GAAM,CAAE,KAAI,cAAa,YAAaA,GAEtC,EAAAJ,EAAA,gBAAA,KAAsB,CASpB,IAAMK,EAAaH,EAAS,eAAe,CACzC,KACA,cACA,SAXgD,GACzCC,EAAU,QAAQ,SAASG,CAAK,EAWvC,SARsB,EAAe,IAC9BC,EAAUJ,EAAU,QAAQ,QAAQG,EAAOC,CAAO,EAAIJ,EAAU,QAAQ,QAAQG,CAAK,EAQ5F,UACF,CAAC,EAED,UAAa,CACXD,EAAW,CACb,CACF,EAAG,CAACH,EAAUM,EAAIC,EAAaC,CAAQ,CAAC,CAC1C,C"}
+{"version":3,"file":"use-screen-action.cjs","names":["useScreenActionRegistry","useRef","require_ai_action_context","react","useScreenAction","registry","actionRef","action","unregister","input","context","id","description","metadata"],"sources":["../../../src/ai/action/use-screen-action.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ActionDefinition, ActionValidator, ExecutionContext } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\n/**\n * Registers a validated action on the nearest screen registry after commit.\n *\n * @typeParam TInput - Validated input shape; defaults to unknown.\n *\n * @typeParam TOutput - Handler output shape; defaults to unknown.\n *\n * @param action - Stable ID/description/metadata with validator and handler from the host.\n *\n * @returns No value; effect cleanup unregisters this registration.\n *\n * @throws Error without ScreenActionProvider; registration errors propagate from the layout effect.\n *\n * @remarks Latest committed validator/handler are read through refs. ID, description or\n * metadata identity changes trigger re-registration. No action executes automatically;\n * no styles are required. The host owns effects and authorization in its handler.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenAction, type ActionDefinition } from '@alneas/appkit-react/ai/action';\n * function Registration({ action }: { action: ActionDefinition<string, string> }) { useScreenAction(action); return null; }\n * export function Screen({ action }: { action: ActionDefinition<string, string> }) {\n *   return <ScreenActionProvider><Registration action={action} /></ScreenActionProvider>;\n * }\n * ```\n */\nexport function useScreenAction<TInput = unknown, TOutput = unknown>(\n  action: ActionDefinition<TInput, TOutput>\n): void {\n  const registry = useScreenActionRegistry();\n\n  const actionRef = useRef(action);\n  useLayoutEffect(() => {\n    actionRef.current = action;\n  });\n\n  const { id, description, metadata } = action;\n\n  useLayoutEffect(() => {\n    const wrappedValidate: ActionValidator<TInput> = (input) => {\n      return actionRef.current.validate(input);\n    };\n\n    const wrappedHandler = (input: TInput, context?: ExecutionContext) => {\n      return context ? actionRef.current.handler(input, context) : actionRef.current.handler(input);\n    };\n\n    const unregister = registry.registerAction({\n      id,\n      description,\n      validate: wrappedValidate,\n      handler: wrappedHandler,\n      metadata,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, id, description, metadata]);\n}\n"],"mappings":"A,wIA8BA,SAAgBI,EACd,EACM,CACN,IAAMC,EAAWL,EAAAA,wBAAwB,EAEnCM,GAAA,EAAYL,EAAAA,OAAAA,CAAOM,CAAM,GAC/B,EAAAJ,EAAA,gBAAA,KAAsB,CACpB,EAAU,QAAUI,CACtB,CAAC,EAED,GAAM,CAAE,KAAI,cAAa,YAAaA,GAEtC,EAAAJ,EAAA,gBAAA,KAAsB,CASpB,IAAMK,EAAaH,EAAS,eAAe,CACzC,KACA,cACA,SAXgD,GACzCC,EAAU,QAAQ,SAASG,CAAK,EAWvC,SARsB,EAAe,IAC9BC,EAAUJ,EAAU,QAAQ,QAAQG,EAAOC,CAAO,EAAIJ,EAAU,QAAQ,QAAQG,CAAK,EAQ5F,UACF,CAAC,EAED,UAAa,CACXD,EAAW,CACb,CACF,EAAG,CAACH,EAAUM,EAAIC,EAAaC,CAAQ,CAAC,CAC1C,C"}

package/dist/ai/action/use-screen-action.d.cts

@@ -1,11 +1,28 @@
 import { ActionDefinition } from '@alneas/appkit-core/ai';
 /**
- * Registers an action on the current screen's ActionRegistry.
+ * Registers a validated action on the nearest screen registry after commit.
  *
- * Handler and validator automatically capture the latest committed
- * props and state via refs without requiring dependency arrays.
- * Metadata is a registration descriptor; keep it stable and replace it to update the list.
- * The action is automatically unregistered when the component unmounts
- * or when the action ID changes.
+ * @typeParam TInput - Validated input shape; defaults to unknown.
+ *
+ * @typeParam TOutput - Handler output shape; defaults to unknown.
+ *
+ * @param action - Stable ID/description/metadata with validator and handler from the host.
+ *
+ * @returns No value; effect cleanup unregisters this registration.
+ *
+ * @throws Error without ScreenActionProvider; registration errors propagate from the layout effect.
+ *
+ * @remarks Latest committed validator/handler are read through refs. ID, description or
+ * metadata identity changes trigger re-registration. No action executes automatically;
+ * no styles are required. The host owns effects and authorization in its handler.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenAction, type ActionDefinition } from '@alneas/appkit-react/ai/action';
+ * function Registration({ action }: { action: ActionDefinition<string, string> }) { useScreenAction(action); return null; }
+ * export function Screen({ action }: { action: ActionDefinition<string, string> }) {
+ *   return <ScreenActionProvider><Registration action={action} /></ScreenActionProvider>;
+ * }
+ * ```
  */
 export declare function useScreenAction<TInput = unknown, TOutput = unknown>(action: ActionDefinition<TInput, TOutput>): void;

package/dist/ai/action/use-screen-action.d.ts

@@ -1,11 +1,28 @@
 import { ActionDefinition } from '@alneas/appkit-core/ai';
 /**
- * Registers an action on the current screen's ActionRegistry.
+ * Registers a validated action on the nearest screen registry after commit.
  *
- * Handler and validator automatically capture the latest committed
- * props and state via refs without requiring dependency arrays.
- * Metadata is a registration descriptor; keep it stable and replace it to update the list.
- * The action is automatically unregistered when the component unmounts
- * or when the action ID changes.
+ * @typeParam TInput - Validated input shape; defaults to unknown.
+ *
+ * @typeParam TOutput - Handler output shape; defaults to unknown.
+ *
+ * @param action - Stable ID/description/metadata with validator and handler from the host.
+ *
+ * @returns No value; effect cleanup unregisters this registration.
+ *
+ * @throws Error without ScreenActionProvider; registration errors propagate from the layout effect.
+ *
+ * @remarks Latest committed validator/handler are read through refs. ID, description or
+ * metadata identity changes trigger re-registration. No action executes automatically;
+ * no styles are required. The host owns effects and authorization in its handler.
+ *
+ * @example
+ * ```tsx
+ * import { ScreenActionProvider, useScreenAction, type ActionDefinition } from '@alneas/appkit-react/ai/action';
+ * function Registration({ action }: { action: ActionDefinition<string, string> }) { useScreenAction(action); return null; }
+ * export function Screen({ action }: { action: ActionDefinition<string, string> }) {
+ *   return <ScreenActionProvider><Registration action={action} /></ScreenActionProvider>;
+ * }
+ * ```
  */
 export declare function useScreenAction<TInput = unknown, TOutput = unknown>(action: ActionDefinition<TInput, TOutput>): void;

package/dist/ai/action/use-screen-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-screen-action.js","names":["useScreenAction","registry","useScreenActionRegistry","actionRef","useRef","action","unregister","input","context","id","description","metadata"],"sources":["../../../src/ai/action/use-screen-action.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ActionDefinition, ActionValidator, ExecutionContext } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\n/**\n * Registers an action on the current screen's ActionRegistry.\n *\n * Handler and validator automatically capture the latest committed\n * props and state via refs without requiring dependency arrays.\n * Metadata is a registration descriptor; keep it stable and replace it to update the list.\n * The action is automatically unregistered when the component unmounts\n * or when the action ID changes.\n */\nexport function useScreenAction<TInput = unknown, TOutput = unknown>(\n  action: ActionDefinition<TInput, TOutput>\n): void {\n  const registry = useScreenActionRegistry();\n\n  const actionRef = useRef(action);\n  useLayoutEffect(() => {\n    actionRef.current = action;\n  });\n\n  const { id, description, metadata } = action;\n\n  useLayoutEffect(() => {\n    const wrappedValidate: ActionValidator<TInput> = (input) => {\n      return actionRef.current.validate(input);\n    };\n\n    const wrappedHandler = (input: TInput, context?: ExecutionContext) => {\n      return context ? actionRef.current.handler(input, context) : actionRef.current.handler(input);\n    };\n\n    const unregister = registry.registerAction({\n      id,\n      description,\n      validate: wrappedValidate,\n      handler: wrappedHandler,\n      metadata,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, id, description, metadata]);\n}\n"],"mappings":";;;;AAaA,SAAgBA,EACd,GACM;CACN,IAAMC,IAAWC,EAAwB,GAEnCC,IAAYC,EAAOC,CAAM;CAC/B,QAAsB;EACpB,EAAU,UAAUA;CACtB,CAAC;CAED,IAAM,EAAE,OAAI,gBAAa,gBAAaA;CAEtC,QAAsB;EASpB,IAAMC,IAAaL,EAAS,eAAe;GACzC;GACA;GACA,WAXgD,MACzCE,EAAU,QAAQ,SAASI,CAAK;GAWvC,UARsB,GAAe,MAC9BC,IAAUL,EAAU,QAAQ,QAAQI,GAAOC,CAAO,IAAIL,EAAU,QAAQ,QAAQI,CAAK;GAQ5F;EACF,CAAC;EAED,aAAa;GACX,EAAW;EACb;CACF,GAAG;EAACN;EAAUQ;EAAIC;EAAaC;CAAQ,CAAC;AAC1C"}
+{"version":3,"file":"use-screen-action.js","names":["useScreenAction","registry","useScreenActionRegistry","actionRef","useRef","action","unregister","input","context","id","description","metadata"],"sources":["../../../src/ai/action/use-screen-action.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ActionDefinition, ActionValidator, ExecutionContext } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\n\n/**\n * Registers a validated action on the nearest screen registry after commit.\n *\n * @typeParam TInput - Validated input shape; defaults to unknown.\n *\n * @typeParam TOutput - Handler output shape; defaults to unknown.\n *\n * @param action - Stable ID/description/metadata with validator and handler from the host.\n *\n * @returns No value; effect cleanup unregisters this registration.\n *\n * @throws Error without ScreenActionProvider; registration errors propagate from the layout effect.\n *\n * @remarks Latest committed validator/handler are read through refs. ID, description or\n * metadata identity changes trigger re-registration. No action executes automatically;\n * no styles are required. The host owns effects and authorization in its handler.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenAction, type ActionDefinition } from '@alneas/appkit-react/ai/action';\n * function Registration({ action }: { action: ActionDefinition<string, string> }) { useScreenAction(action); return null; }\n * export function Screen({ action }: { action: ActionDefinition<string, string> }) {\n *   return <ScreenActionProvider><Registration action={action} /></ScreenActionProvider>;\n * }\n * ```\n */\nexport function useScreenAction<TInput = unknown, TOutput = unknown>(\n  action: ActionDefinition<TInput, TOutput>\n): void {\n  const registry = useScreenActionRegistry();\n\n  const actionRef = useRef(action);\n  useLayoutEffect(() => {\n    actionRef.current = action;\n  });\n\n  const { id, description, metadata } = action;\n\n  useLayoutEffect(() => {\n    const wrappedValidate: ActionValidator<TInput> = (input) => {\n      return actionRef.current.validate(input);\n    };\n\n    const wrappedHandler = (input: TInput, context?: ExecutionContext) => {\n      return context ? actionRef.current.handler(input, context) : actionRef.current.handler(input);\n    };\n\n    const unregister = registry.registerAction({\n      id,\n      description,\n      validate: wrappedValidate,\n      handler: wrappedHandler,\n      metadata,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, id, description, metadata]);\n}\n"],"mappings":";;;;AA8BA,SAAgBA,EACd,GACM;CACN,IAAMC,IAAWC,EAAwB,GAEnCC,IAAYC,EAAOC,CAAM;CAC/B,QAAsB;EACpB,EAAU,UAAUA;CACtB,CAAC;CAED,IAAM,EAAE,OAAI,gBAAa,gBAAaA;CAEtC,QAAsB;EASpB,IAAMC,IAAaL,EAAS,eAAe;GACzC;GACA;GACA,WAXgD,MACzCE,EAAU,QAAQ,SAASI,CAAK;GAWvC,UARsB,GAAe,MAC9BC,IAAUL,EAAU,QAAQ,QAAQI,GAAOC,CAAO,IAAIL,EAAU,QAAQ,QAAQI,CAAK;GAQ5F;EACF,CAAC;EAED,aAAa;GACX,EAAW;EACb;CACF,GAAG;EAACN;EAAUQ;EAAIC;EAAaC;CAAQ,CAAC;AAC1C"}

package/dist/ai/action/use-screen-context.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-screen-context.cjs","names":["useScreenActionRegistry","useRef","require_ai_action_context","react","useScreenContext","registry","key","keyOrOptions","getter","maybeGetter","description","maybeDescription","getterRef","unregister"],"sources":["../../../src/ai/action/use-screen-context.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ContextGetter } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\nimport type { UseScreenContextOptions } from './types';\n\n/**\n * Registers an on-demand context getter on the current screen's ActionRegistry.\n *\n * The getter function automatically captures the latest committed props and state\n * via refs without requiring dependency arrays.\n * The context is automatically unregistered when the component unmounts\n * or when the context key changes.\n */\nexport function useScreenContext<T = unknown>(\n  key: string,\n  getter: ContextGetter<T>,\n  description?: string\n): void;\nexport function useScreenContext<T = unknown>(\n  options: UseScreenContextOptions<T>\n): void;\nexport function useScreenContext<T = unknown>(\n  keyOrOptions: string | UseScreenContextOptions<T>,\n  maybeGetter?: ContextGetter<T>,\n  maybeDescription?: string\n): void {\n  const registry = useScreenActionRegistry();\n\n  const key = typeof keyOrOptions === 'string' ? keyOrOptions : keyOrOptions.key;\n  const getter =\n    typeof keyOrOptions === 'string' ? maybeGetter! : keyOrOptions.getter;\n  const description =\n    typeof keyOrOptions === 'string'\n      ? maybeDescription\n      : keyOrOptions.description;\n\n  const getterRef = useRef(getter);\n  useLayoutEffect(() => {\n    getterRef.current = getter;\n  });\n\n  useLayoutEffect(() => {\n    const wrappedGetter: ContextGetter<T> = () => {\n      return getterRef.current();\n    };\n\n    const unregister = registry.registerContext({\n      key,\n      description,\n      getter: wrappedGetter,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, key, description]);\n}\n"],"mappings":"A,wIAqBA,SAAgBI,EACd,EACA,EACA,EACM,CACN,IAAMC,EAAWL,EAAAA,wBAAwB,EAEnCM,EAAM,OAAOC,GAAiB,SAAWA,EAAeA,EAAa,IACrEC,EACJ,OAAOD,GAAiB,SAAWE,EAAeF,EAAa,OAC3DG,EACJ,OAAOH,GAAiB,SACpBI,EACAJ,EAAa,YAEbK,GAAA,EAAYX,EAAAA,OAAAA,CAAOO,CAAM,GAC/B,EAAAL,EAAA,gBAAA,KAAsB,CACpB,EAAU,QAAUK,CACtB,CAAC,GAED,EAAAL,EAAA,gBAAA,KAAsB,CAKpB,IAAMU,EAAaR,EAAS,gBAAgB,CAC1C,MACA,cACA,WANOO,EAAU,QAAQ,CAO3B,CAAC,EAED,UAAa,CACXC,EAAW,CACb,CACF,EAAG,CAACR,EAAUC,EAAKI,CAAW,CAAC,CACjC,C"}
+{"version":3,"file":"use-screen-context.cjs","names":["useScreenActionRegistry","useRef","require_ai_action_context","react","useScreenContext","registry","key","keyOrOptions","getter","maybeGetter","description","maybeDescription","getterRef","unregister"],"sources":["../../../src/ai/action/use-screen-context.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { ContextGetter } from \"@alneas/appkit-core/ai\";\nimport { useScreenActionRegistry } from './context';\nimport type { UseScreenContextOptions } from './types';\n\n/**\n * Registers an on-demand context getter using positional arguments.\n *\n * @typeParam T - Context getter result shape; defaults to unknown.\n *\n * @param key - Stable registry key.\n *\n * @param getter - Pure host getter invoked by registry context reads, using its latest committed version.\n *\n * @param description - Optional human/model-facing description.\n *\n * @returns No value; cleanup unregisters the context.\n *\n * @throws Error without ScreenActionProvider; registry registration failures propagate from the layout effect.\n *\n * @remarks Requires ScreenActionProvider; no styles. Key/description/registry changes\n * re-register the context, while getter changes update a ref after commit.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenContext } from '@alneas/appkit-react/ai/action';\n * function Context() { useScreenContext('selection', () => ({ ids: [] as string[] })); return null; }\n * export function Screen() { return <ScreenActionProvider><Context /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenContext<T = unknown>(\n  key: string,\n  getter: ContextGetter<T>,\n  description?: string\n): void;\n/**\n * Registers an on-demand context getter using an options object.\n *\n * @typeParam T - Context getter result shape; defaults to unknown.\n *\n * @param options - Stable key, optional description and latest committed getter.\n *\n * @returns No value; cleanup unregisters the context.\n *\n * @throws Error without ScreenActionProvider; registry registration errors propagate from the layout effect.\n *\n * @remarks Requires ScreenActionProvider; no styles. Lifecycle matches the positional overload.\n *\n * @example\n * ```tsx\n * import { ScreenActionProvider, useScreenContext } from '@alneas/appkit-react/ai/action';\n * function Context() { useScreenContext({ key: 'selection', getter: () => ({ ids: [] as string[] }) }); return null; }\n * export function Screen() { return <ScreenActionProvider><Context /></ScreenActionProvider>; }\n * ```\n */\nexport function useScreenContext<T = unknown>(\n  options: UseScreenContextOptions<T>\n): void;\nexport function useScreenContext<T = unknown>(\n  keyOrOptions: string | UseScreenContextOptions<T>,\n  maybeGetter?: ContextGetter<T>,\n  maybeDescription?: string\n): void {\n  const registry = useScreenActionRegistry();\n\n  const key = typeof keyOrOptions === 'string' ? keyOrOptions : keyOrOptions.key;\n  const getter =\n    typeof keyOrOptions === 'string' ? maybeGetter! : keyOrOptions.getter;\n  const description =\n    typeof keyOrOptions === 'string'\n      ? maybeDescription\n      : keyOrOptions.description;\n\n  const getterRef = useRef(getter);\n  useLayoutEffect(() => {\n    getterRef.current = getter;\n  });\n\n  useLayoutEffect(() => {\n    const wrappedGetter: ContextGetter<T> = () => {\n      return getterRef.current();\n    };\n\n    const unregister = registry.registerContext({\n      key,\n      description,\n      getter: wrappedGetter,\n    });\n\n    return () => {\n      unregister();\n    };\n  }, [registry, key, description]);\n}\n"],"mappings":"A,wIA0DA,SAAgBI,EACd,EACA,EACA,EACM,CACN,IAAMC,EAAWL,EAAAA,wBAAwB,EAEnCM,EAAM,OAAOC,GAAiB,SAAWA,EAAeA,EAAa,IACrEC,EACJ,OAAOD,GAAiB,SAAWE,EAAeF,EAAa,OAC3DG,EACJ,OAAOH,GAAiB,SACpBI,EACAJ,EAAa,YAEbK,GAAA,EAAYX,EAAAA,OAAAA,CAAOO,CAAM,GAC/B,EAAAL,EAAA,gBAAA,KAAsB,CACpB,EAAU,QAAUK,CACtB,CAAC,GAED,EAAAL,EAAA,gBAAA,KAAsB,CAKpB,IAAMU,EAAaR,EAAS,gBAAgB,CAC1C,MACA,cACA,WANOO,EAAU,QAAQ,CAO3B,CAAC,EAED,UAAa,CACXC,EAAW,CACb,CACF,EAAG,CAACR,EAAUC,EAAKI,CAAW,CAAC,CACjC,C"}