@alneas/appkit-react 0.1.0 → 0.3.0

package/dist/ai/generative-ui/error-boundary.d.cts

@@ -1,20 +1,116 @@
 import { Component, ReactNode } from 'react';
-/** Props for MinimalErrorBoundary. */
+/**
+ * Client render isolation inputs; see MinimalErrorBoundary for usage.
+ *
+ * @see MinimalErrorBoundary for the canonical usage example.
+ */
 export interface MinimalErrorBoundaryProps {
+    /**
+     * Descendant content whose render errors are isolated on the client.
+     */
     children: ReactNode;
+    /**
+     * Render callback receiving the caught Error; callback failures are not caught by this same boundary.
+     *
+     * @param error - Stored descendant render error.
+     *
+     * @returns Fallback content replacing all children.
+     */
     fallback: (error: Error) => ReactNode;
+    /**
+     * Optional callback invoked by componentDidCatch after a descendant failure.
+     */
     onError?: (error: Error) => void;
 }
+/**
+ * Stored client render failure; see MinimalErrorBoundary lifecycle.
+ *
+ * @see MinimalErrorBoundary for the canonical usage example.
+ */
 interface State {
+    /**
+     * Caught Error, or null before a render failure.
+     */
     error: Error | null;
 }
 /**
- * Lightweight, zero-dependency Error Boundary for safely isolating UI block rendering errors.
+ * Isolates descendant client render failures behind an application fallback.
+ *
+ * @remarks Requires React only. This boundary does not catch SSR, event-handler or async
+ * errors, nor its own fallback errors. It keeps the failure until remounted; changing
+ * children does not reset state. onError exceptions propagate to an outer boundary.
+ *
+ * @example
+ * ```tsx
+ * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+ * export function Block() {
+ *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Content</span></MinimalErrorBoundary>;
+ * }
+ * ```
  */
 export declare class MinimalErrorBoundary extends Component<MinimalErrorBoundaryProps, State> {
+    /**
+     * Current caught-error state; initialized without an error.
+     */
     state: State;
+    /**
+     * Store the descendant render failure for fallback rendering.
+     *
+     * @param error - Error delivered by React.
+     *
+     * @returns Replacement state containing the error.
+     *
+     * @see MinimalErrorBoundary for the usage example.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     static getDerivedStateFromError(error: Error): State;
+    /**
+     * Notify the optional host error observer after React catches a descendant failure.
+     *
+     * @param error - Caught descendant render error.
+     *
+     * @returns No value after observer invocation.
+     *
+     * @throws Observer errors propagate to an outer boundary.
+     *
+     * @see MinimalErrorBoundary for setup.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     componentDidCatch(error: Error): void;
+    /**
+     * Render children until an error is stored, then invoke fallback.
+     *
+     * @returns Descendants or host fallback content.
+     *
+     * @throws Fallback errors propagate to an outer boundary.
+     *
+     * @see MinimalErrorBoundary for setup.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     render(): ReactNode;
 }
 export {};

package/dist/ai/generative-ui/error-boundary.d.ts

@@ -1,20 +1,116 @@
 import { Component, ReactNode } from 'react';
-/** Props for MinimalErrorBoundary. */
+/**
+ * Client render isolation inputs; see MinimalErrorBoundary for usage.
+ *
+ * @see MinimalErrorBoundary for the canonical usage example.
+ */
 export interface MinimalErrorBoundaryProps {
+    /**
+     * Descendant content whose render errors are isolated on the client.
+     */
     children: ReactNode;
+    /**
+     * Render callback receiving the caught Error; callback failures are not caught by this same boundary.
+     *
+     * @param error - Stored descendant render error.
+     *
+     * @returns Fallback content replacing all children.
+     */
     fallback: (error: Error) => ReactNode;
+    /**
+     * Optional callback invoked by componentDidCatch after a descendant failure.
+     */
     onError?: (error: Error) => void;
 }
+/**
+ * Stored client render failure; see MinimalErrorBoundary lifecycle.
+ *
+ * @see MinimalErrorBoundary for the canonical usage example.
+ */
 interface State {
+    /**
+     * Caught Error, or null before a render failure.
+     */
     error: Error | null;
 }
 /**
- * Lightweight, zero-dependency Error Boundary for safely isolating UI block rendering errors.
+ * Isolates descendant client render failures behind an application fallback.
+ *
+ * @remarks Requires React only. This boundary does not catch SSR, event-handler or async
+ * errors, nor its own fallback errors. It keeps the failure until remounted; changing
+ * children does not reset state. onError exceptions propagate to an outer boundary.
+ *
+ * @example
+ * ```tsx
+ * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+ * export function Block() {
+ *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Content</span></MinimalErrorBoundary>;
+ * }
+ * ```
  */
 export declare class MinimalErrorBoundary extends Component<MinimalErrorBoundaryProps, State> {
+    /**
+     * Current caught-error state; initialized without an error.
+     */
     state: State;
+    /**
+     * Store the descendant render failure for fallback rendering.
+     *
+     * @param error - Error delivered by React.
+     *
+     * @returns Replacement state containing the error.
+     *
+     * @see MinimalErrorBoundary for the usage example.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     static getDerivedStateFromError(error: Error): State;
+    /**
+     * Notify the optional host error observer after React catches a descendant failure.
+     *
+     * @param error - Caught descendant render error.
+     *
+     * @returns No value after observer invocation.
+     *
+     * @throws Observer errors propagate to an outer boundary.
+     *
+     * @see MinimalErrorBoundary for setup.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     componentDidCatch(error: Error): void;
+    /**
+     * Render children until an error is stored, then invoke fallback.
+     *
+     * @returns Descendants or host fallback content.
+     *
+     * @throws Fallback errors propagate to an outer boundary.
+     *
+     * @see MinimalErrorBoundary for setup.
+     *
+     * @example
+     * ```tsx
+     * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';
+     * // React invokes the lifecycle method; mount the boundary rather than calling it directly.
+     * export function IsolatedBlock() {
+     *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;
+     * }
+     * ```
+     */
     render(): ReactNode;
 }
 export {};

package/dist/ai/generative-ui/error-boundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.js","names":["MinimalErrorBoundary","Component","error"],"sources":["../../../src/ai/generative-ui/error-boundary.tsx"],"sourcesContent":["import { Component, type ReactNode } from 'react';\n\n/** Props for MinimalErrorBoundary. */\nexport interface MinimalErrorBoundaryProps {\n  children: ReactNode;\n  fallback: (error: Error) => ReactNode;\n  onError?: (error: Error) => void;\n}\n\ninterface State {\n  error: Error | null;\n}\n\n/**\n * Lightweight, zero-dependency Error Boundary for safely isolating UI block rendering errors.\n */\nexport class MinimalErrorBoundary extends Component<MinimalErrorBoundaryProps, State> {\n  override state: State = { error: null };\n\n  static getDerivedStateFromError(error: Error): State {\n    return { error };\n  }\n\n  override componentDidCatch(error: Error) {\n    this.props.onError?.(error);\n  }\n\n  override render(): ReactNode {\n    if (this.state.error) {\n      return this.props.fallback(this.state.error);\n    }\n    return this.props.children;\n  }\n}\n"],"mappings":";;;AAgBA,IAAaA,IAAb,cAA0CC,EAA4C;CACpF,QAAwB,EAAE,OAAO,KAAK;CAEtC,OAAO,yBAAyB,GAAqB;EACnD,OAAO,EAAE,SAAM;CACjB;CAEA,kBAA2B,GAAc;EACvC,KAAK,MAAM,UAAUC,CAAK;CAC5B;CAEA,SAA6B;EAI3B,OAHI,KAAK,MAAM,QACN,KAAK,MAAM,SAAS,KAAK,MAAM,KAAK,IAEtC,KAAK,MAAM;CACpB;AACF"}
+{"version":3,"file":"error-boundary.js","names":["MinimalErrorBoundary","Component","error"],"sources":["../../../src/ai/generative-ui/error-boundary.tsx"],"sourcesContent":["import { Component, type ReactNode } from 'react';\n\n/**\n * Client render isolation inputs; see MinimalErrorBoundary for usage.\n *\n * @see MinimalErrorBoundary for the canonical usage example.\n */\nexport interface MinimalErrorBoundaryProps {\n  /**\n   * Descendant content whose render errors are isolated on the client.\n   */\n  children: ReactNode;\n  /**\n   * Render callback receiving the caught Error; callback failures are not caught by this same boundary.\n   *\n   * @param error - Stored descendant render error.\n   *\n   * @returns Fallback content replacing all children.\n   */\n  fallback: (error: Error) => ReactNode;\n  /**\n   * Optional callback invoked by componentDidCatch after a descendant failure.\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Stored client render failure; see MinimalErrorBoundary lifecycle.\n *\n * @see MinimalErrorBoundary for the canonical usage example.\n */\ninterface State {\n  /**\n   * Caught Error, or null before a render failure.\n   */\n  error: Error | null;\n}\n\n/**\n * Isolates descendant client render failures behind an application fallback.\n *\n * @remarks Requires React only. This boundary does not catch SSR, event-handler or async\n * errors, nor its own fallback errors. It keeps the failure until remounted; changing\n * children does not reset state. onError exceptions propagate to an outer boundary.\n *\n * @example\n * ```tsx\n * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';\n * export function Block() {\n *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Content</span></MinimalErrorBoundary>;\n * }\n * ```\n */\nexport class MinimalErrorBoundary extends Component<MinimalErrorBoundaryProps, State> {\n  /**\n   * Current caught-error state; initialized without an error.\n   */\n  override state: State = { error: null };\n\n  /**\n   * Store the descendant render failure for fallback rendering.\n   *\n   * @param error - Error delivered by React.\n   *\n   * @returns Replacement state containing the error.\n   *\n   * @see MinimalErrorBoundary for the usage example.\n   *\n   * @example\n   * ```tsx\n   * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';\n   * // React invokes the lifecycle method; mount the boundary rather than calling it directly.\n   * export function IsolatedBlock() {\n   *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;\n   * }\n   * ```\n   */\n  static getDerivedStateFromError(error: Error): State {\n    return { error };\n  }\n\n  /**\n   * Notify the optional host error observer after React catches a descendant failure.\n   *\n   * @param error - Caught descendant render error.\n   *\n   * @returns No value after observer invocation.\n   *\n   * @throws Observer errors propagate to an outer boundary.\n   *\n   * @see MinimalErrorBoundary for setup.\n   *\n   * @example\n   * ```tsx\n   * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';\n   * // React invokes the lifecycle method; mount the boundary rather than calling it directly.\n   * export function IsolatedBlock() {\n   *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;\n   * }\n   * ```\n   */\n  override componentDidCatch(error: Error) {\n    this.props.onError?.(error);\n  }\n\n  /**\n   * Render children until an error is stored, then invoke fallback.\n   *\n   * @returns Descendants or host fallback content.\n   *\n   * @throws Fallback errors propagate to an outer boundary.\n   *\n   * @see MinimalErrorBoundary for setup.\n   *\n   * @example\n   * ```tsx\n   * import { MinimalErrorBoundary } from '@alneas/appkit-react/ai/generative-ui';\n   * // React invokes the lifecycle method; mount the boundary rather than calling it directly.\n   * export function IsolatedBlock() {\n   *   return <MinimalErrorBoundary fallback={() => <p>Unavailable</p>}><span>Block content</span></MinimalErrorBoundary>;\n   * }\n   * ```\n   */\n  override render(): ReactNode {\n    if (this.state.error) {\n      return this.props.fallback(this.state.error);\n    }\n    return this.props.children;\n  }\n}\n"],"mappings":";;;AAqDA,IAAaA,IAAb,cAA0CC,EAA4C;CAIpF,QAAwB,EAAE,OAAO,KAAK;CAoBtC,OAAO,yBAAyB,GAAqB;EACnD,OAAO,EAAE,SAAM;CACjB;CAsBA,kBAA2B,GAAc;EACvC,KAAK,MAAM,UAAUC,CAAK;CAC5B;CAoBA,SAA6B;EAI3B,OAHI,KAAK,MAAM,QACN,KAAK,MAAM,SAAS,KAAK,MAAM,KAAK,IAEtC,KAAK,MAAM;CACpB;AACF"}

package/dist/ai/generative-ui/registry.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"registry.cjs","names":["createGenerativeUIContract","createElement","isValidElement","react","_alneas_appkit_core_ai","defineGenerativeUIComponent","definition","type","validate","component","contract","dataSchema","snapshot","data","result","createGenerativeUIRegistry","entries","components","described","describedTypes","failure","block","resolve","element"],"sources":["../../../src/ai/generative-ui/registry.ts"],"sourcesContent":["import { createElement, isValidElement, type ComponentType, type ReactElement } from 'react';\nimport { createGenerativeUIContract } from \"@alneas/appkit-core/ai\";\nimport type { GenerativeUIBlock, GenerativeUIObject } from \"@alneas/appkit-core/ai\";\n\n/** A pure application validator may transform JSON data into the component's typed input. */\nexport type GenerativeUIDataResult<TData> = { readonly ok: true; readonly data: TData } | { readonly ok: false };\n\n/** Safe diagnostic metadata; no raw payload, exception or validator message is exposed. */\nexport interface GenerativeUIIssue {\n  readonly code: 'INVALID_DOCUMENT' | 'UNKNOWN_COMPONENT' | 'INVALID_DATA' | 'RENDER_ERROR';\n  readonly blockId?: string;\n  readonly type?: string;\n}\n\n/** Validated component resolution, before React renders the element. */\nexport type GenerativeUIResolution =\n  | { readonly ok: true; readonly element: ReactElement }\n  | { readonly ok: false; readonly issue: GenerativeUIIssue };\n\n/** Application-owned component registration produced by defineGenerativeUIComponent. */\nexport interface GenerativeUIComponent {\n  readonly type: string;\n  /** Optional inline draft-07 schema, enforced before the component validator. */\n  readonly dataSchema?: GenerativeUIObject;\n  readonly resolve: (data: GenerativeUIObject) => ReactElement | null;\n}\n\n/** Immutable registry. Create a new registry to change the permitted components. */\nexport interface GenerativeUIRegistry {\n  readonly types: readonly string[];\n  /** Available only when every registration supplies dataSchema (including the empty registry). */\n  readonly documentSchema?: GenerativeUIObject;\n  resolve(block: GenerativeUIBlock): GenerativeUIResolution;\n}\n\n/**\n * Binds a component to a pure, synchronous validator. Components receive only the\n * validated `data` prop. Callbacks, current records and credentials belong to trusted\n * application code (for example React Context), never the generated document.\n * Optional dataSchema is snapshotted and validated before the custom validator.\n * It uses the inline draft-07 subset documented by createGenerativeUIContract.\n *\n * @example\n * ```tsx\n * import { defineGenerativeUIComponent } from \"./\";\n * const greeting = defineGenerativeUIComponent({\n *   type: 'greeting',\n *   validate: (data) => typeof data.text === 'string'\n *     ? { ok: true, data: { text: data.text } } : { ok: false },\n *   component: ({ data }) => <p>{data.text}</p>,\n * });\n * ```\n */\nexport function defineGenerativeUIComponent<TData>(definition: {\n  readonly type: string;\n  /** Optional shared schema for model output and runtime validation. */\n  readonly dataSchema?: GenerativeUIObject;\n  readonly validate: (data: GenerativeUIObject) => GenerativeUIDataResult<TData>;\n  readonly component: ComponentType<{ data: TData }>;\n}): GenerativeUIComponent {\n  const { type, validate, component, dataSchema } = definition;\n  if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(type) || typeof validate !== 'function' || !component) {\n    throw new Error('A UI component requires a valid type, validator and component');\n  }\n  const contract = dataSchema !== undefined ? createGenerativeUIContract([{ type, dataSchema }]) : undefined;\n  const snapshot = contract?.components[0].dataSchema;\n  return Object.freeze({\n    type,\n    ...(snapshot ? { dataSchema: snapshot } : {}),\n    resolve(data: GenerativeUIObject) {\n      if (contract && !contract.validateData(type, data)) return null;\n      const result = validate(data);\n      return result?.ok === true ? createElement(component, { data: result.data }) : null;\n    },\n  });\n}\n\n/**\n * Creates an allowlist of application-defined UI components. No global registration,\n * dynamic imports, HTML evaluation or Action execution occurs. Validators must be pure;\n * their failures are isolated per block. Rendering exceptions are handled by the renderer.\n * documentSchema is available only if every component declares dataSchema; missing\n * schemas are not guessed. It covers structural validation, not custom business rules.\n */\nexport function createGenerativeUIRegistry(components: readonly GenerativeUIComponent[]): GenerativeUIRegistry {\n  const entries = new Map<string, GenerativeUIComponent['resolve']>();\n  for (const component of components) {\n    if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(component.type) || typeof component.resolve !== 'function' || entries.has(component.type)) {\n      throw new Error('UI component types must be valid and unique');\n    }\n    entries.set(component.type, component.resolve);\n  }\n  const described = components.filter(\n    (component): component is GenerativeUIComponent & { dataSchema: GenerativeUIObject } =>\n      component.dataSchema !== undefined\n  );\n  const contract = createGenerativeUIContract(described);\n  const describedTypes = new Set(described.map(component => component.type));\n  return Object.freeze({\n    ...(described.length === components.length ? { documentSchema: contract.schema } : {}),\n    types: Object.freeze([...entries.keys()]),\n    resolve(block: GenerativeUIBlock): GenerativeUIResolution {\n      const failure = (code: GenerativeUIIssue['code']): GenerativeUIResolution => ({\n        ok: false,\n        issue: { code, blockId: block.id, type: block.type },\n      });\n      const resolve = entries.get(block.type);\n      if (!resolve) return failure('UNKNOWN_COMPONENT');\n      try {\n        if (describedTypes.has(block.type) && !contract.validateData(block.type, block.data)) return failure('INVALID_DATA');\n        const element = resolve(block.data);\n        return isValidElement(element) ? { ok: true, element } : failure('INVALID_DATA');\n      } catch {\n        return failure('INVALID_DATA');\n      }\n    },\n  });\n}\n"],"mappings":"A,2IAqDA,SAAgBK,EAAmC,EAMzB,CACxB,GAAM,CAAE,OAAM,WAAU,YAAW,cAAeC,EAClD,GAAI,CAAC,iCAAiC,KAAKC,CAAI,GAAK,OAAOC,GAAa,YAAc,CAACC,EACrF,MAAU,MAAM,+DAA+D,EAEjF,IAAMC,EAAWC,IAAe,IAAA,GAAiE,IAAA,IAAjE,EAAYX,EAAAA,2BAAAA,CAA2B,CAAC,CAAE,OAAM,YAAW,CAAC,CAAC,EACvFY,EAAWF,GAAU,WAAW,EAAE,CAAC,WACzC,OAAO,OAAO,OAAO,CACnB,OACA,GAAIE,EAAW,CAAE,WAAYA,CAAS,EAAI,CAAC,EAC3C,QAAQ,EAA0B,CAChC,GAAIF,GAAY,CAACA,EAAS,aAAaH,EAAMM,CAAI,EAAG,OAAO,KAC3D,IAAMC,EAASN,EAASK,CAAI,EAC5B,OAAOC,GAAQ,KAAO,IAAA,EAAOb,EAAAA,cAAAA,CAAcQ,EAAW,CAAE,KAAMK,EAAO,IAAK,CAAC,EAAI,IACjF,CACF,CAAC,CACH,CASA,SAAgBC,EAA2B,EAAoE,CAC7G,IAAMC,EAAU,IAAI,IACpB,IAAK,IAAMP,KAAaQ,EAAY,CAClC,GAAI,CAAC,iCAAiC,KAAKR,EAAU,IAAI,GAAK,OAAOA,EAAU,SAAY,YAAcO,EAAQ,IAAIP,EAAU,IAAI,EACjI,MAAU,MAAM,6CAA6C,EAE/DO,EAAQ,IAAIP,EAAU,KAAMA,EAAU,OAAO,CAC/C,CACA,IAAMS,EAAYD,EAAW,OAC1B,GACCR,EAAU,aAAe,IAAA,EAC7B,EACMC,GAAA,EAAWV,EAAAA,2BAAAA,CAA2BkB,CAAS,EAC/CC,EAAiB,IAAI,IAAID,EAAU,IAAI,GAAaT,EAAU,IAAI,CAAC,EACzE,OAAO,OAAO,OAAO,CACnB,GAAIS,EAAU,SAAWD,EAAW,OAAS,CAAE,eAAgBP,EAAS,MAAO,EAAI,CAAC,EACpF,MAAO,OAAO,OAAO,CAAC,GAAGM,EAAQ,KAAK,CAAC,CAAC,EACxC,QAAQ,EAAkD,CACxD,IAAMI,EAAW,IAA6D,CAC5E,GAAI,GACJ,MAAO,CAAE,OAAM,QAASC,EAAM,GAAI,KAAMA,EAAM,IAAK,CACrD,GACMC,EAAUN,EAAQ,IAAIK,EAAM,IAAI,EACtC,GAAI,CAACC,EAAS,OAAOF,EAAQ,mBAAmB,EAChD,GAAI,CACF,GAAID,EAAe,IAAIE,EAAM,IAAI,GAAK,CAACX,EAAS,aAAaW,EAAM,KAAMA,EAAM,IAAI,EAAG,OAAOD,EAAQ,cAAc,EACnH,IAAMG,EAAUD,EAAQD,EAAM,IAAI,EAClC,OAAA,EAAOnB,EAAAA,eAAAA,CAAeqB,CAAO,EAAI,CAAE,GAAI,GAAM,SAAQ,EAAIH,EAAQ,cAAc,CACjF,MAAQ,CACN,OAAOA,EAAQ,cAAc,CAC/B,CACF,CACF,CAAC,CACH,C"}
+{"version":3,"file":"registry.cjs","names":["createGenerativeUIContract","createElement","isValidElement","react","_alneas_appkit_core_ai","defineGenerativeUIComponent","definition","type","validate","component","contract","dataSchema","snapshot","data","result","createGenerativeUIRegistry","entries","components","described","describedTypes","failure","block","resolve","element"],"sources":["../../../src/ai/generative-ui/registry.ts"],"sourcesContent":["import { createElement, isValidElement, type ComponentType, type ReactElement } from 'react';\nimport { createGenerativeUIContract } from \"@alneas/appkit-core/ai\";\nimport type { GenerativeUIBlock, GenerativeUIObject } from \"@alneas/appkit-core/ai\";\n\n/**\n * Result of a pure validator: ok true supplies typed input; ok false rejects the block.\n *\n * @typeParam TData - Input shape accepted by the registered component.\n *\n * @remarks See defineGenerativeUIComponent for a complete registration example.\n *\n * @see defineGenerativeUIComponent for the canonical usage example.\n */\nexport type GenerativeUIDataResult<TData> = {\n  /** Successful validation discriminator. */\n  readonly ok: true;\n  /** Typed input passed to the registered component. */\n  readonly data: TData;\n} | {\n  /** Rejected validation discriminator; no typed input is available. */\n  readonly ok: false;\n};\n\n/**\n * Safe diagnostic metadata; no raw payload, exception or validator message is exposed.\n * @see GenerativeUIRenderer for the canonical usage example.\n */\nexport interface GenerativeUIIssue {\n  /** Safe failure category for document, allowlist, data or React rendering failures. */\n  readonly code: 'INVALID_DOCUMENT' | 'UNKNOWN_COMPONENT' | 'INVALID_DATA' | 'RENDER_ERROR';\n  /** Block identifier when failure is scoped to a block. */\n  readonly blockId?: string;\n  /** Requested component type when available. */\n  readonly type?: string;\n}\n\n/**\n * Validated component resolution, before React renders the element.\n * @see createGenerativeUIRegistry for the canonical usage example.\n */\nexport type GenerativeUIResolution =\n  | {\n      /** Successful allowlist and data resolution. */\n      readonly ok: true;\n      /** Resolved element; React rendering may still fail later. */\n      readonly element: ReactElement;\n    }\n  | {\n      /** Failed allowlist or data resolution. */\n      readonly ok: false;\n      /** Safe diagnostic metadata without raw payloads or errors. */\n      readonly issue: GenerativeUIIssue;\n    };\n\n/**\n * Application-owned component registration produced by defineGenerativeUIComponent.\n * @see defineGenerativeUIComponent for the canonical usage example.\n */\nexport interface GenerativeUIComponent {\n  /** Stable allowlist key: letter first, then up to 63 letters, digits, underscores, dots or hyphens. */\n  readonly type: string;\n  /** Optional inline draft-07 schema, enforced before the component validator. */\n  readonly dataSchema?: GenerativeUIObject;\n  /**\n   * Resolve input through the registration's schema and validator.\n   *\n   * @param data - JSON object to validate before passing typed data to the component.\n   *\n   * @returns Element for accepted data, or null when validation rejects it.\n   *\n   * @throws Direct calls propagate validator errors; registry.resolve isolates them.\n   *\n   * @remarks See defineGenerativeUIComponent for registration setup.\n   */\n  readonly resolve: (data: GenerativeUIObject) => ReactElement | null;\n}\n\n/**\n * Immutable registry. Create a new registry to change the permitted components.\n * @see createGenerativeUIRegistry for the canonical usage example.\n */\nexport interface GenerativeUIRegistry {\n  /** Frozen registration keys in insertion order. */\n  readonly types: readonly string[];\n  /** Available only when every registration supplies dataSchema (including the empty registry). */\n  readonly documentSchema?: GenerativeUIObject;\n  /**\n   * Resolve one structurally valid block through the allowlist.\n   *\n   * @param block - Block from a validated generative UI document.\n   *\n   * @returns Element on success, or safe issue metadata for an unknown type or rejected data.\n   *\n   * @remarks Validator/registration exceptions become INVALID_DATA; component rendering happens later.\n   * See createGenerativeUIRegistry for usage.\n   */\n  resolve(block: GenerativeUIBlock): GenerativeUIResolution;\n}\n\n/**\n * Binds a component to a pure, synchronous validator. Components receive only the\n * validated `data` prop. Callbacks, current records and credentials belong to trusted\n * application code (for example React Context), never the generated document.\n * Optional dataSchema is snapshotted and validated before the custom validator.\n * It uses the inline draft-07 subset documented by createGenerativeUIContract.\n *\n *\n * @typeParam TData - Validated input shape passed to the registered React component.\n *\n * @param definition - Unique type name, pure synchronous validator, component and optional schema.\n *\n * @returns Frozen registration for createGenerativeUIRegistry; resolve returns null on invalid data.\n *\n * @throws For an invalid type name, missing validator/component or unsupported data schema.\n *\n * @remarks Requires React. The registration itself needs no context or CSS; supplied\n * components own their provider/style requirements. Validator exceptions are caught by\n * registry resolution, but can escape direct registration.resolve calls.\n *\n * @example\n * ```tsx\n * import { defineGenerativeUIComponent } from \"@alneas/appkit-react/ai/generative-ui\";\n * const greeting = defineGenerativeUIComponent<{ text: string }>({\n *   type: 'greeting',\n *   validate: (data) => typeof data.text === 'string'\n *     ? { ok: true, data: { text: data.text } } : { ok: false },\n *   component: ({ data }) => <p>{data.text}</p>,\n * });\n * ```\n */\nexport function defineGenerativeUIComponent<TData>(definition: {\n  /** Allowlist name with the same syntax as GenerativeUIComponent.type. */\n  readonly type: string;\n  /** Optional shared schema for model output and runtime validation. */\n  readonly dataSchema?: GenerativeUIObject;\n  /**\n   * Pure synchronous conversion from JSON to typed input; return ok false to reject.\n   * @param data - JSON object to validate/transform synchronously.\n   *\n   * @returns ok true with typed component input, or ok false to reject this block.\n   */\n  readonly validate: (data: GenerativeUIObject) => GenerativeUIDataResult<TData>;\n  /** Trusted React component receiving only validated data; owns its context/style requirements. */\n  readonly component: ComponentType<{\n    /** Validated input returned by the registration validator. */\n    data: TData;\n  }>;\n}): GenerativeUIComponent {\n  const { type, validate, component, dataSchema } = definition;\n  if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(type) || typeof validate !== 'function' || !component) {\n    throw new Error('A UI component requires a valid type, validator and component');\n  }\n  const contract = dataSchema !== undefined ? createGenerativeUIContract([{ type, dataSchema }]) : undefined;\n  const snapshot = contract?.components[0].dataSchema;\n  return Object.freeze({\n    type,\n    ...(snapshot ? { dataSchema: snapshot } : {}),\n    resolve(data: GenerativeUIObject) {\n      if (contract && !contract.validateData(type, data)) return null;\n      const result = validate(data);\n      return result?.ok === true ? createElement(component, { data: result.data }) : null;\n    },\n  });\n}\n\n/**\n * Creates an allowlist of application-defined UI components. No global registration,\n * dynamic imports, HTML evaluation or Action execution occurs. Validators must be pure;\n * their failures are isolated per block. Rendering exceptions are handled by the renderer.\n * documentSchema is available only if every component declares dataSchema; missing\n * schemas are not guessed. It covers structural validation, not custom business rules.\n *\n * @param components - Registrations with distinct, valid allowlist names; an empty list is permitted.\n *\n * @returns Frozen registry with insertion-ordered types and an optional document schema.\n *\n * @throws For invalid/duplicate names, missing resolve functions or invalid declared schemas.\n *\n * @example\n * ```ts\n * import { createGenerativeUIRegistry } from '@alneas/appkit-react/ai/generative-ui';\n * const registry = createGenerativeUIRegistry([]);\n * const result = registry.resolve({ id: 'missing', type: 'unknown', data: {} });\n * // result.ok is false: no component is registered.\n * ```\n */\nexport function createGenerativeUIRegistry(components: readonly GenerativeUIComponent[]): GenerativeUIRegistry {\n  const entries = new Map<string, GenerativeUIComponent['resolve']>();\n  for (const component of components) {\n    if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(component.type) || typeof component.resolve !== 'function' || entries.has(component.type)) {\n      throw new Error('UI component types must be valid and unique');\n    }\n    entries.set(component.type, component.resolve);\n  }\n  const described = components.filter(\n    (component): component is GenerativeUIComponent & { dataSchema: GenerativeUIObject } =>\n      component.dataSchema !== undefined\n  );\n  const contract = createGenerativeUIContract(described);\n  const describedTypes = new Set(described.map(component => component.type));\n  return Object.freeze({\n    ...(described.length === components.length ? { documentSchema: contract.schema } : {}),\n    types: Object.freeze([...entries.keys()]),\n    resolve(block: GenerativeUIBlock): GenerativeUIResolution {\n      const failure = (code: GenerativeUIIssue['code']): GenerativeUIResolution => ({\n        ok: false,\n        issue: { code, blockId: block.id, type: block.type },\n      });\n      const resolve = entries.get(block.type);\n      if (!resolve) return failure('UNKNOWN_COMPONENT');\n      try {\n        if (describedTypes.has(block.type) && !contract.validateData(block.type, block.data)) return failure('INVALID_DATA');\n        const element = resolve(block.data);\n        return isValidElement(element) ? { ok: true, element } : failure('INVALID_DATA');\n      } catch {\n        return failure('INVALID_DATA');\n      }\n    },\n  });\n}\n"],"mappings":"A,2IAkIA,SAAgBK,EAAmC,EAiBzB,CACxB,GAAM,CAAE,OAAM,WAAU,YAAW,cAAeC,EAClD,GAAI,CAAC,iCAAiC,KAAKC,CAAI,GAAK,OAAOC,GAAa,YAAc,CAACC,EACrF,MAAU,MAAM,+DAA+D,EAEjF,IAAMC,EAAWC,IAAe,IAAA,GAAiE,IAAA,IAAjE,EAAYX,EAAAA,2BAAAA,CAA2B,CAAC,CAAE,OAAM,YAAW,CAAC,CAAC,EACvFY,EAAWF,GAAU,WAAW,EAAE,CAAC,WACzC,OAAO,OAAO,OAAO,CACnB,OACA,GAAIE,EAAW,CAAE,WAAYA,CAAS,EAAI,CAAC,EAC3C,QAAQ,EAA0B,CAChC,GAAIF,GAAY,CAACA,EAAS,aAAaH,EAAMM,CAAI,EAAG,OAAO,KAC3D,IAAMC,EAASN,EAASK,CAAI,EAC5B,OAAOC,GAAQ,KAAO,IAAA,EAAOb,EAAAA,cAAAA,CAAcQ,EAAW,CAAE,KAAMK,EAAO,IAAK,CAAC,EAAI,IACjF,CACF,CAAC,CACH,CAuBA,SAAgBC,EAA2B,EAAoE,CAC7G,IAAMC,EAAU,IAAI,IACpB,IAAK,IAAMP,KAAaQ,EAAY,CAClC,GAAI,CAAC,iCAAiC,KAAKR,EAAU,IAAI,GAAK,OAAOA,EAAU,SAAY,YAAcO,EAAQ,IAAIP,EAAU,IAAI,EACjI,MAAU,MAAM,6CAA6C,EAE/DO,EAAQ,IAAIP,EAAU,KAAMA,EAAU,OAAO,CAC/C,CACA,IAAMS,EAAYD,EAAW,OAC1B,GACCR,EAAU,aAAe,IAAA,EAC7B,EACMC,GAAA,EAAWV,EAAAA,2BAAAA,CAA2BkB,CAAS,EAC/CC,EAAiB,IAAI,IAAID,EAAU,IAAI,GAAaT,EAAU,IAAI,CAAC,EACzE,OAAO,OAAO,OAAO,CACnB,GAAIS,EAAU,SAAWD,EAAW,OAAS,CAAE,eAAgBP,EAAS,MAAO,EAAI,CAAC,EACpF,MAAO,OAAO,OAAO,CAAC,GAAGM,EAAQ,KAAK,CAAC,CAAC,EACxC,QAAQ,EAAkD,CACxD,IAAMI,EAAW,IAA6D,CAC5E,GAAI,GACJ,MAAO,CAAE,OAAM,QAASC,EAAM,GAAI,KAAMA,EAAM,IAAK,CACrD,GACMC,EAAUN,EAAQ,IAAIK,EAAM,IAAI,EACtC,GAAI,CAACC,EAAS,OAAOF,EAAQ,mBAAmB,EAChD,GAAI,CACF,GAAID,EAAe,IAAIE,EAAM,IAAI,GAAK,CAACX,EAAS,aAAaW,EAAM,KAAMA,EAAM,IAAI,EAAG,OAAOD,EAAQ,cAAc,EACnH,IAAMG,EAAUD,EAAQD,EAAM,IAAI,EAClC,OAAA,EAAOnB,EAAAA,eAAAA,CAAeqB,CAAO,EAAI,CAAE,GAAI,GAAM,SAAQ,EAAIH,EAAQ,cAAc,CACjF,MAAQ,CACN,OAAOA,EAAQ,cAAc,CAC/B,CACF,CACF,CAAC,CACH,C"}

package/dist/ai/generative-ui/registry.d.cts

@@ -1,38 +1,91 @@
 import { ComponentType, ReactElement } from 'react';
 import { GenerativeUIBlock, GenerativeUIObject } from '@alneas/appkit-core/ai';
-/** A pure application validator may transform JSON data into the component's typed input. */
+/**
+ * Result of a pure validator: ok true supplies typed input; ok false rejects the block.
+ *
+ * @typeParam TData - Input shape accepted by the registered component.
+ *
+ * @remarks See defineGenerativeUIComponent for a complete registration example.
+ *
+ * @see defineGenerativeUIComponent for the canonical usage example.
+ */
 export type GenerativeUIDataResult<TData> = {
+    /** Successful validation discriminator. */
     readonly ok: true;
+    /** Typed input passed to the registered component. */
     readonly data: TData;
 } | {
+    /** Rejected validation discriminator; no typed input is available. */
     readonly ok: false;
 };
-/** Safe diagnostic metadata; no raw payload, exception or validator message is exposed. */
+/**
+ * Safe diagnostic metadata; no raw payload, exception or validator message is exposed.
+ * @see GenerativeUIRenderer for the canonical usage example.
+ */
 export interface GenerativeUIIssue {
+    /** Safe failure category for document, allowlist, data or React rendering failures. */
     readonly code: 'INVALID_DOCUMENT' | 'UNKNOWN_COMPONENT' | 'INVALID_DATA' | 'RENDER_ERROR';
+    /** Block identifier when failure is scoped to a block. */
     readonly blockId?: string;
+    /** Requested component type when available. */
     readonly type?: string;
 }
-/** Validated component resolution, before React renders the element. */
+/**
+ * Validated component resolution, before React renders the element.
+ * @see createGenerativeUIRegistry for the canonical usage example.
+ */
 export type GenerativeUIResolution = {
+    /** Successful allowlist and data resolution. */
     readonly ok: true;
+    /** Resolved element; React rendering may still fail later. */
     readonly element: ReactElement;
 } | {
+    /** Failed allowlist or data resolution. */
     readonly ok: false;
+    /** Safe diagnostic metadata without raw payloads or errors. */
     readonly issue: GenerativeUIIssue;
 };
-/** Application-owned component registration produced by defineGenerativeUIComponent. */
+/**
+ * Application-owned component registration produced by defineGenerativeUIComponent.
+ * @see defineGenerativeUIComponent for the canonical usage example.
+ */
 export interface GenerativeUIComponent {
+    /** Stable allowlist key: letter first, then up to 63 letters, digits, underscores, dots or hyphens. */
     readonly type: string;
     /** Optional inline draft-07 schema, enforced before the component validator. */
     readonly dataSchema?: GenerativeUIObject;
+    /**
+     * Resolve input through the registration's schema and validator.
+     *
+     * @param data - JSON object to validate before passing typed data to the component.
+     *
+     * @returns Element for accepted data, or null when validation rejects it.
+     *
+     * @throws Direct calls propagate validator errors; registry.resolve isolates them.
+     *
+     * @remarks See defineGenerativeUIComponent for registration setup.
+     */
     readonly resolve: (data: GenerativeUIObject) => ReactElement | null;
 }
-/** Immutable registry. Create a new registry to change the permitted components. */
+/**
+ * Immutable registry. Create a new registry to change the permitted components.
+ * @see createGenerativeUIRegistry for the canonical usage example.
+ */
 export interface GenerativeUIRegistry {
+    /** Frozen registration keys in insertion order. */
     readonly types: readonly string[];
     /** Available only when every registration supplies dataSchema (including the empty registry). */
     readonly documentSchema?: GenerativeUIObject;
+    /**
+     * Resolve one structurally valid block through the allowlist.
+     *
+     * @param block - Block from a validated generative UI document.
+     *
+     * @returns Element on success, or safe issue metadata for an unknown type or rejected data.
+     *
+     * @remarks Validator/registration exceptions become INVALID_DATA; component rendering happens later.
+     * See createGenerativeUIRegistry for usage.
+     */
     resolve(block: GenerativeUIBlock): GenerativeUIResolution;
 }
 /**
@@ -42,10 +95,23 @@ export interface GenerativeUIRegistry {
  * Optional dataSchema is snapshotted and validated before the custom validator.
  * It uses the inline draft-07 subset documented by createGenerativeUIContract.
  *
+ *
+ * @typeParam TData - Validated input shape passed to the registered React component.
+ *
+ * @param definition - Unique type name, pure synchronous validator, component and optional schema.
+ *
+ * @returns Frozen registration for createGenerativeUIRegistry; resolve returns null on invalid data.
+ *
+ * @throws For an invalid type name, missing validator/component or unsupported data schema.
+ *
+ * @remarks Requires React. The registration itself needs no context or CSS; supplied
+ * components own their provider/style requirements. Validator exceptions are caught by
+ * registry resolution, but can escape direct registration.resolve calls.
+ *
  * @example
  * ```tsx
- * import { defineGenerativeUIComponent } from "./index.cjs";
- * const greeting = defineGenerativeUIComponent({
+ * import { defineGenerativeUIComponent } from "@alneas/appkit-react/ai/generative-ui";
+ * const greeting = defineGenerativeUIComponent<{ text: string }>({
  *   type: 'greeting',
  *   validate: (data) => typeof data.text === 'string'
  *     ? { ok: true, data: { text: data.text } } : { ok: false },
@@ -54,11 +120,20 @@ export interface GenerativeUIRegistry {
  * ```
  */
 export declare function defineGenerativeUIComponent<TData>(definition: {
+    /** Allowlist name with the same syntax as GenerativeUIComponent.type. */
     readonly type: string;
     /** Optional shared schema for model output and runtime validation. */
     readonly dataSchema?: GenerativeUIObject;
+    /**
+     * Pure synchronous conversion from JSON to typed input; return ok false to reject.
+     * @param data - JSON object to validate/transform synchronously.
+     *
+     * @returns ok true with typed component input, or ok false to reject this block.
+     */
     readonly validate: (data: GenerativeUIObject) => GenerativeUIDataResult<TData>;
+    /** Trusted React component receiving only validated data; owns its context/style requirements. */
     readonly component: ComponentType<{
+        /** Validated input returned by the registration validator. */
         data: TData;
     }>;
 }): GenerativeUIComponent;
@@ -68,5 +143,19 @@ export declare function defineGenerativeUIComponent<TData>(definition: {
  * their failures are isolated per block. Rendering exceptions are handled by the renderer.
  * documentSchema is available only if every component declares dataSchema; missing
  * schemas are not guessed. It covers structural validation, not custom business rules.
+ *
+ * @param components - Registrations with distinct, valid allowlist names; an empty list is permitted.
+ *
+ * @returns Frozen registry with insertion-ordered types and an optional document schema.
+ *
+ * @throws For invalid/duplicate names, missing resolve functions or invalid declared schemas.
+ *
+ * @example
+ * ```ts
+ * import { createGenerativeUIRegistry } from '@alneas/appkit-react/ai/generative-ui';
+ * const registry = createGenerativeUIRegistry([]);
+ * const result = registry.resolve({ id: 'missing', type: 'unknown', data: {} });
+ * // result.ok is false: no component is registered.
+ * ```
  */
 export declare function createGenerativeUIRegistry(components: readonly GenerativeUIComponent[]): GenerativeUIRegistry;

package/dist/ai/generative-ui/registry.d.ts

@@ -1,38 +1,91 @@
 import { ComponentType, ReactElement } from 'react';
 import { GenerativeUIBlock, GenerativeUIObject } from '@alneas/appkit-core/ai';
-/** A pure application validator may transform JSON data into the component's typed input. */
+/**
+ * Result of a pure validator: ok true supplies typed input; ok false rejects the block.
+ *
+ * @typeParam TData - Input shape accepted by the registered component.
+ *
+ * @remarks See defineGenerativeUIComponent for a complete registration example.
+ *
+ * @see defineGenerativeUIComponent for the canonical usage example.
+ */
 export type GenerativeUIDataResult<TData> = {
+    /** Successful validation discriminator. */
     readonly ok: true;
+    /** Typed input passed to the registered component. */
     readonly data: TData;
 } | {
+    /** Rejected validation discriminator; no typed input is available. */
     readonly ok: false;
 };
-/** Safe diagnostic metadata; no raw payload, exception or validator message is exposed. */
+/**
+ * Safe diagnostic metadata; no raw payload, exception or validator message is exposed.
+ * @see GenerativeUIRenderer for the canonical usage example.
+ */
 export interface GenerativeUIIssue {
+    /** Safe failure category for document, allowlist, data or React rendering failures. */
     readonly code: 'INVALID_DOCUMENT' | 'UNKNOWN_COMPONENT' | 'INVALID_DATA' | 'RENDER_ERROR';
+    /** Block identifier when failure is scoped to a block. */
     readonly blockId?: string;
+    /** Requested component type when available. */
     readonly type?: string;
 }
-/** Validated component resolution, before React renders the element. */
+/**
+ * Validated component resolution, before React renders the element.
+ * @see createGenerativeUIRegistry for the canonical usage example.
+ */
 export type GenerativeUIResolution = {
+    /** Successful allowlist and data resolution. */
     readonly ok: true;
+    /** Resolved element; React rendering may still fail later. */
     readonly element: ReactElement;
 } | {
+    /** Failed allowlist or data resolution. */
     readonly ok: false;
+    /** Safe diagnostic metadata without raw payloads or errors. */
     readonly issue: GenerativeUIIssue;
 };
-/** Application-owned component registration produced by defineGenerativeUIComponent. */
+/**
+ * Application-owned component registration produced by defineGenerativeUIComponent.
+ * @see defineGenerativeUIComponent for the canonical usage example.
+ */
 export interface GenerativeUIComponent {
+    /** Stable allowlist key: letter first, then up to 63 letters, digits, underscores, dots or hyphens. */
     readonly type: string;
     /** Optional inline draft-07 schema, enforced before the component validator. */
     readonly dataSchema?: GenerativeUIObject;
+    /**
+     * Resolve input through the registration's schema and validator.
+     *
+     * @param data - JSON object to validate before passing typed data to the component.
+     *
+     * @returns Element for accepted data, or null when validation rejects it.
+     *
+     * @throws Direct calls propagate validator errors; registry.resolve isolates them.
+     *
+     * @remarks See defineGenerativeUIComponent for registration setup.
+     */
     readonly resolve: (data: GenerativeUIObject) => ReactElement | null;
 }
-/** Immutable registry. Create a new registry to change the permitted components. */
+/**
+ * Immutable registry. Create a new registry to change the permitted components.
+ * @see createGenerativeUIRegistry for the canonical usage example.
+ */
 export interface GenerativeUIRegistry {
+    /** Frozen registration keys in insertion order. */
     readonly types: readonly string[];
     /** Available only when every registration supplies dataSchema (including the empty registry). */
     readonly documentSchema?: GenerativeUIObject;
+    /**
+     * Resolve one structurally valid block through the allowlist.
+     *
+     * @param block - Block from a validated generative UI document.
+     *
+     * @returns Element on success, or safe issue metadata for an unknown type or rejected data.
+     *
+     * @remarks Validator/registration exceptions become INVALID_DATA; component rendering happens later.
+     * See createGenerativeUIRegistry for usage.
+     */
     resolve(block: GenerativeUIBlock): GenerativeUIResolution;
 }
 /**
@@ -42,10 +95,23 @@ export interface GenerativeUIRegistry {
  * Optional dataSchema is snapshotted and validated before the custom validator.
  * It uses the inline draft-07 subset documented by createGenerativeUIContract.
  *
+ *
+ * @typeParam TData - Validated input shape passed to the registered React component.
+ *
+ * @param definition - Unique type name, pure synchronous validator, component and optional schema.
+ *
+ * @returns Frozen registration for createGenerativeUIRegistry; resolve returns null on invalid data.
+ *
+ * @throws For an invalid type name, missing validator/component or unsupported data schema.
+ *
+ * @remarks Requires React. The registration itself needs no context or CSS; supplied
+ * components own their provider/style requirements. Validator exceptions are caught by
+ * registry resolution, but can escape direct registration.resolve calls.
+ *
  * @example
  * ```tsx
- * import { defineGenerativeUIComponent } from "./index.js";
- * const greeting = defineGenerativeUIComponent({
+ * import { defineGenerativeUIComponent } from "@alneas/appkit-react/ai/generative-ui";
+ * const greeting = defineGenerativeUIComponent<{ text: string }>({
  *   type: 'greeting',
  *   validate: (data) => typeof data.text === 'string'
  *     ? { ok: true, data: { text: data.text } } : { ok: false },
@@ -54,11 +120,20 @@ export interface GenerativeUIRegistry {
  * ```
  */
 export declare function defineGenerativeUIComponent<TData>(definition: {
+    /** Allowlist name with the same syntax as GenerativeUIComponent.type. */
     readonly type: string;
     /** Optional shared schema for model output and runtime validation. */
     readonly dataSchema?: GenerativeUIObject;
+    /**
+     * Pure synchronous conversion from JSON to typed input; return ok false to reject.
+     * @param data - JSON object to validate/transform synchronously.
+     *
+     * @returns ok true with typed component input, or ok false to reject this block.
+     */
     readonly validate: (data: GenerativeUIObject) => GenerativeUIDataResult<TData>;
+    /** Trusted React component receiving only validated data; owns its context/style requirements. */
     readonly component: ComponentType<{
+        /** Validated input returned by the registration validator. */
         data: TData;
     }>;
 }): GenerativeUIComponent;
@@ -68,5 +143,19 @@ export declare function defineGenerativeUIComponent<TData>(definition: {
  * their failures are isolated per block. Rendering exceptions are handled by the renderer.
  * documentSchema is available only if every component declares dataSchema; missing
  * schemas are not guessed. It covers structural validation, not custom business rules.
+ *
+ * @param components - Registrations with distinct, valid allowlist names; an empty list is permitted.
+ *
+ * @returns Frozen registry with insertion-ordered types and an optional document schema.
+ *
+ * @throws For invalid/duplicate names, missing resolve functions or invalid declared schemas.
+ *
+ * @example
+ * ```ts
+ * import { createGenerativeUIRegistry } from '@alneas/appkit-react/ai/generative-ui';
+ * const registry = createGenerativeUIRegistry([]);
+ * const result = registry.resolve({ id: 'missing', type: 'unknown', data: {} });
+ * // result.ok is false: no component is registered.
+ * ```
  */
 export declare function createGenerativeUIRegistry(components: readonly GenerativeUIComponent[]): GenerativeUIRegistry;