@ax-kit/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Utpal Sen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# `@ax-kit/react`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lifecycle-native `document.modelContext` bindings for React.
+
+Pinned draft: WebMCP Draft Community Group Report, 15 October 2026, from
+the W3C Web Machine Learning Community Group. The pin is exported as
+`SPEC_VERSION` from `@ax-kit/core` and repeated in every release note.
+
+Everything here is ours, not the draft's: the draft defines the
+`document.modelContext` surface, while these hooks and the provider are
+conveniences reachable only through this entry so no spec-conformant core
+path can observe them.
+
+## Install
+
+```sh
+pnpm add @ax-kit/react
+```
+
+Requires React 18 or 19 as a peer. Zero runtime dependencies.
+
+## Use
+
+```tsx
+"use client";
+
+import { AxProvider, useAxTool } from "@ax-kit/react";
+
+function CartTools({ total }: { total: number }) {
+  useAxTool({
+    name: "viewCart",
+    description: "Return the current cart contents.",
+    execute: async () => ({ total }),
+  });
+  useAxTool("proceedToCheckout", async () => ({ ok: true }), {
+    description: "Start checkout.",
+    annotations: { consequentialHint: true },
+  });
+  return null;
+}
+
+export function Page({ total }: { total: number }) {
+  return (
+    <AxProvider namespace="cart." middleware={async (next, args, opts) => next(args, opts)}>
+      <CartTools total={total} />
+    </AxProvider>
+  );
+}
+```
+
+Registration is deferred to the client effect with the controller created
+inside it and aborted in cleanup, so StrictMode setup-cleanup-setup leaves
+exactly one registration. Server render access returns an inert handle where
+`window` is absent, and modules using the hooks carry `"use client"`.
+The registered callback forwards to a latest-handler mailbox while identity
+change aborts then registers with tolerance for transient duplicate-name
+rejection. Registration and execution signals stay distinct.
+
+## Dispatch
+
+`dispatchAxClick` drives one click against a React-managed node as a
+fallback-wrapped enhancement over native dispatch: it invokes the nearest
+enclosing `onClick` with a synthesized event carrying the real target, and
+falls back to native bubbling dispatch where the enhancement is missing.
+Click-only and single-handler by design — capture handlers, other event
+types, and further ancestors never run through the bridge. Disabled form
+controls skip the bridge and use native dispatch, which correctly performs
+no action — including controls disabled by an ancestor `fieldset`. The synthesized event carries `type`, bubbling flags, the real
+target, and a usable `nativeEvent`. Bridge failure
+never rejects an invocation native dispatch could complete, a bridged
+handler that throws is reported without a native re-run, and fallback use
+is logged. Plain nodes use native dispatch with no bridge. The native path
+uses the prototype-chain `click`, never a page-owned expando.
+
+```tsx
+import { dispatchAxClick } from "@ax-kit/react";
+
+dispatchAxClick(document.querySelector("button") as Element);
+```

package/dist/index.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("react");const t=(0,e.createContext)({namespace:``,middleware:void 0});function n(n){let r=(0,e.useContext)(t),i=(0,e.useMemo)(()=>({namespace:`${r.namespace}${n.namespace??``}`,middleware:n.middleware===void 0?r.middleware:n.middleware}),[r.namespace,r.middleware,n.namespace,n.middleware]);return(0,e.createElement)(t.Provider,{value:i},n.children)}function r(e){try{if(typeof e.matches==`function`&&e.matches(`:disabled`))return!0}catch{}try{return e.disabled===!0}catch{return!1}}function i(e){let t=e.ownerDocument?.defaultView??void 0;try{return new MouseEvent(`click`,{bubbles:!0,cancelable:!0,view:t??null})}catch{return new Event(`click`,{bubbles:!0,cancelable:!0})}}function a(e){try{for(let t of Object.keys(e))if(t.startsWith(`__reactProps$`))return t}catch{return}}function o(e,t){try{let n=e[t];if(typeof n!=`object`||!n)return;let r=n.onClick;return typeof r==`function`?r:void 0}catch{return}}function s(e){let t=Object.getPrototypeOf(e);for(;t!==null;){let e=t.click;if(typeof e==`function`)return e;t=Object.getPrototypeOf(t)}}function c(e){let t=s(e);if(t!==void 0)try{t.call(e);return}catch{}let n=e.ownerDocument?.defaultView??void 0;try{e.dispatchEvent(new MouseEvent(`click`,{bubbles:!0,cancelable:!0,view:n??null}))}catch{e.dispatchEvent(new Event(`click`,{bubbles:!0,cancelable:!0}))}}function l(e){if(typeof e!=`object`||!e||e.nodeType!==1)throw TypeError(`bad dispatch target`);let t=e,n=e,s=!1;try{for(;n!==null;){let e=a(n);if(e!==void 0){s=!0;let a=o(n,e);if(a!==void 0){if(r(n)||r(t))break;let e=!1,o=!1,s;try{s=i(t)}catch{break}let c={type:`click`,bubbles:!0,cancelable:!0,get defaultPrevented(){return e},target:t,currentTarget:n,nativeEvent:s,preventDefault(){e=!0;try{s.preventDefault()}catch{}},stopPropagation(){o=!0;try{s.stopPropagation()}catch{}},isDefaultPrevented(){return e},isPropagationStopped(){return o}};try{a.call(n,c)}catch(e){console.error(`[ax-kit/react] bridged handler threw; skipping native fallback`,e)}return`bridge`}}n=n.parentElement}}catch{}s&&console.info(`[ax-kit/react] dispatch fallback to native dispatch`);try{c(t)}catch{}return`native`}const u={supported:!1,registered:!1,error:null};function d(){return typeof window<`u`&&typeof document<`u`}function f(e){let t=e.modelContext;if(typeof t==`object`&&t&&typeof t.registerTool==`function`)return t}function p(e,t,n,r,i,a){return m([e,t,n??null,m(r),m(i??null),m(a??null)])}function m(e){try{let t=JSON.stringify(e===void 0?null:e);return typeof t==`string`?t:`unserializable`}catch{return`unserializable`}}function h(e,t,n){if(typeof t!=`function`)throw TypeError(`bad execute`);return{name:e,description:n?.description??``,title:n?.title,inputSchema:n?.inputSchema,execute:t,annotations:n?.annotations,exposedTo:n?.exposedTo}}function g(e){return e instanceof DOMException&&e.name===`InvalidStateError`}function _(){return typeof MessageChannel==`function`?new Promise(e=>{let t=new MessageChannel;t.port1.onmessage=()=>{t.port1.close(),t.port2.close(),e()},t.port2.postMessage(void 0)}):Promise.resolve()}async function v(){await Promise.resolve(),await _()}function y(n,r,i){let a=typeof n==`string`?typeof r==`function`?null:/* @__PURE__ */ TypeError(`bad execute`):typeof n.execute==`function`?null:/* @__PURE__ */ TypeError(`bad execute`),o=typeof n==`string`?typeof r==`function`?h(n,r,i):{name:n,description:i?.description??``,title:i?.title,inputSchema:i?.inputSchema,execute:async()=>{throw TypeError(`bad execute`)},annotations:i?.annotations,exposedTo:i?.exposedTo}:n,{namespace:s,middleware:c}=(0,e.useContext)(t),l=`${s}${o.name}`,m=o.execute,_=(0,e.useRef)(typeof m==`function`?m:async()=>{throw TypeError(`bad execute`)}),y=(0,e.useRef)(c);(0,e.useEffect)(()=>{typeof m==`function`&&(_.current=m)}),(0,e.useEffect)(()=>{y.current=c});let b=p(l,o.description,o.title,o.inputSchema,o.annotations,o.exposedTo),x=a!==null,[S,C]=(0,e.useState)(()=>d()?a===null?{supported:!0,registered:!1,error:null}:{supported:!0,registered:!1,error:a}:u);return(0,e.useEffect)(()=>{if(!d()){C(u);return}if(x){C({supported:!0,registered:!1,error:/* @__PURE__ */ TypeError(`bad execute`)});return}let e=f(document);if(e===void 0){C({supported:!1,registered:!1,error:null});return}let t=e,n=!1,r=new AbortController,i=!1,a=(e,t)=>{let n=_.current,r=y.current;return r===void 0?n(e,t):r(n,e,t)};async function s(e){try{await t.registerTool({name:l,title:o.title,description:o.description,inputSchema:o.inputSchema,execute:a,annotations:o.annotations},{exposedTo:o.exposedTo,signal:r.signal}),!n&&!i&&(i=!0,C({supported:!0,registered:!0,error:null}))}catch(t){if(r.signal.aborted||n)return;if(g(t)&&e===0){if(await v(),r.signal.aborted||n)return;await s(1);return}!n&&!i&&(i=!0,C({supported:!0,registered:!1,error:t??null}))}}return s(0),()=>{n=!0,r.abort(),C({supported:!0,registered:!1,error:null})}},[b,x]),d()?S:u}function b(e){return e===void 0||!d()?!1:f(e)!==void 0}exports.AxProvider=n,exports.dispatchAxClick=l,exports.isAxSupported=b,exports.useAxTool=y;

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+import { ReactNode } from "react";
+//#region src/types.d.ts
+/**
+ * Public shapes for `@ax-kit/react`. Everything here is ours, not
+ * draft-derived: the draft defines `ModelContext` on `document`, while the
+ * hook, action, and provider conveniences live in this entry only so no
+ * spec-conformant core path can observe them.
+ */
+interface AxAnnotations {
+  readonly readOnlyHint?: boolean | undefined;
+  readonly untrustedContentHint?: boolean | undefined;
+  readonly consequentialHint?: boolean | undefined;
+  readonly debugging?: boolean | undefined;
+}
+interface AxExecuteOptions {
+  readonly signal: AbortSignal;
+}
+type AxExecuteCallback = (inputObject: unknown, options: AxExecuteOptions) => Promise<unknown>;
+interface AxToolDefinition {
+  readonly name: string;
+  readonly title?: string | undefined;
+  readonly description: string;
+  readonly inputSchema?: unknown;
+  readonly execute: AxExecuteCallback;
+  readonly annotations?: AxAnnotations | undefined;
+  readonly exposedTo?: ReadonlyArray<string> | undefined;
+}
+interface AxToolHandle {
+  readonly supported: boolean;
+  readonly registered: boolean;
+  readonly error: Error | DOMException | null;
+}
+type AxMiddleware = (next: AxExecuteCallback, args: unknown, options: AxExecuteOptions) => Promise<unknown>;
+interface AxToolOptions {
+  readonly description?: string | undefined;
+  readonly title?: string | undefined;
+  readonly inputSchema?: unknown;
+  readonly annotations?: AxAnnotations | undefined;
+  readonly exposedTo?: ReadonlyArray<string> | undefined;
+}
+//#endregion
+//#region src/context.d.ts
+interface AxProviderProps {
+  readonly namespace?: string | undefined;
+  readonly middleware?: AxMiddleware | undefined;
+  readonly children: ReactNode;
+}
+/**
+ * Share a name prefix plus invocation middleware with a subtree. Nested
+ * providers concatenate prefixes so per-tool wiring stays flat. The
+ * middleware wraps the latest handler only; registration identity is
+ * unaffected by middleware changes.
+ */
+export declare function AxProvider(props: AxProviderProps): ReactNode;
+//#endregion
+//#region src/dispatch.d.ts
+type AxDispatchOutcome = "bridge" | "native";
+/**
+ * Drive one click. Returns how it was handled. Never throws for a reachable
+ * target: bridge failure falls back to native dispatch with a logged
+ * fallback. Non-element targets reject with `TypeError`.
+ */
+export declare function dispatchAxClick(target: Element): AxDispatchOutcome;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Register a tool for the lifetime of the calling component. The
+ * registration controller is created inside the client effect with cleanup
+ * aborting it, so development setup-cleanup-setup leaves exactly one
+ * registration. The registered callback is stable and forwards to a
+ * latest-handler mailbox, while identity change aborts then registers with
+ * tolerance for transient duplicate-name rejection.
+ *
+ * The name-plus-handler form is the same tool under a shorter call: the
+ * description and contract options default to empty so mistakes surface the
+ * draft error family instead of a placeholder.
+ */
+export declare function useAxTool(tool: AxToolDefinition): AxToolHandle;
+export declare function useAxTool(name: string, handler: AxExecuteCallback, options?: AxToolOptions): AxToolHandle;
+/**
+ * Feature-detect the registration surface for one document. False where the
+ * caller must render the inert handle instead of registering.
+ */
+export declare function isAxSupported(doc: Document | undefined): boolean;
+//#endregion
+export type { AxAnnotations, AxDispatchOutcome, AxExecuteCallback, AxExecuteOptions, AxMiddleware, AxProviderProps, AxToolDefinition, AxToolHandle, AxToolOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/context.tsx","../src/dispatch.ts","../src/hooks.ts"],"mappings":";;;;;;;;UAUiB;WACP;WACA;WACA;WACA;;UAGO;WACP,QAAQ;;KAGN,qBACX,sBACA,SAAS,qBACL;UAEY;WACP;WACA;WACA;WACA;WACA,SAAS;WACT,cAAc;WACd,YAAY;;UAGL;WACP;WACA;WACA,OAAO,QAAQ;;KAGb,gBACX,MAAM,mBACN,eACA,SAAS,qBACL;UAEY;WACP;WACA;WACA;WACA,cAAc;WACd,YAAY;;;;UChCL;WACP;WACA,aAAa;WACb,UAAU;;;;;;;;wBASJ,WAAW,OAAO,kBAAkB;;;KCdxC;;;;;;wBA8HI,gBAAgB,QAAQ,UAAU;;;;;;;;;;;;;;;wBCzBlC,UAAU,MAAM,mBAAmB;wBACnC,UACf,cACA,SAAS,mBACT,UAAU,gBACR;;;;;wBA0Ka,cAAc,KAAK"}

package/dist/index.d.mts

@@ -0,0 +1,87 @@
+import { ReactNode } from "react";
+//#region src/types.d.ts
+/**
+ * Public shapes for `@ax-kit/react`. Everything here is ours, not
+ * draft-derived: the draft defines `ModelContext` on `document`, while the
+ * hook, action, and provider conveniences live in this entry only so no
+ * spec-conformant core path can observe them.
+ */
+interface AxAnnotations {
+  readonly readOnlyHint?: boolean | undefined;
+  readonly untrustedContentHint?: boolean | undefined;
+  readonly consequentialHint?: boolean | undefined;
+  readonly debugging?: boolean | undefined;
+}
+interface AxExecuteOptions {
+  readonly signal: AbortSignal;
+}
+type AxExecuteCallback = (inputObject: unknown, options: AxExecuteOptions) => Promise<unknown>;
+interface AxToolDefinition {
+  readonly name: string;
+  readonly title?: string | undefined;
+  readonly description: string;
+  readonly inputSchema?: unknown;
+  readonly execute: AxExecuteCallback;
+  readonly annotations?: AxAnnotations | undefined;
+  readonly exposedTo?: ReadonlyArray<string> | undefined;
+}
+interface AxToolHandle {
+  readonly supported: boolean;
+  readonly registered: boolean;
+  readonly error: Error | DOMException | null;
+}
+type AxMiddleware = (next: AxExecuteCallback, args: unknown, options: AxExecuteOptions) => Promise<unknown>;
+interface AxToolOptions {
+  readonly description?: string | undefined;
+  readonly title?: string | undefined;
+  readonly inputSchema?: unknown;
+  readonly annotations?: AxAnnotations | undefined;
+  readonly exposedTo?: ReadonlyArray<string> | undefined;
+}
+//#endregion
+//#region src/context.d.ts
+interface AxProviderProps {
+  readonly namespace?: string | undefined;
+  readonly middleware?: AxMiddleware | undefined;
+  readonly children: ReactNode;
+}
+/**
+ * Share a name prefix plus invocation middleware with a subtree. Nested
+ * providers concatenate prefixes so per-tool wiring stays flat. The
+ * middleware wraps the latest handler only; registration identity is
+ * unaffected by middleware changes.
+ */
+export declare function AxProvider(props: AxProviderProps): ReactNode;
+//#endregion
+//#region src/dispatch.d.ts
+type AxDispatchOutcome = "bridge" | "native";
+/**
+ * Drive one click. Returns how it was handled. Never throws for a reachable
+ * target: bridge failure falls back to native dispatch with a logged
+ * fallback. Non-element targets reject with `TypeError`.
+ */
+export declare function dispatchAxClick(target: Element): AxDispatchOutcome;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Register a tool for the lifetime of the calling component. The
+ * registration controller is created inside the client effect with cleanup
+ * aborting it, so development setup-cleanup-setup leaves exactly one
+ * registration. The registered callback is stable and forwards to a
+ * latest-handler mailbox, while identity change aborts then registers with
+ * tolerance for transient duplicate-name rejection.
+ *
+ * The name-plus-handler form is the same tool under a shorter call: the
+ * description and contract options default to empty so mistakes surface the
+ * draft error family instead of a placeholder.
+ */
+export declare function useAxTool(tool: AxToolDefinition): AxToolHandle;
+export declare function useAxTool(name: string, handler: AxExecuteCallback, options?: AxToolOptions): AxToolHandle;
+/**
+ * Feature-detect the registration surface for one document. False where the
+ * caller must render the inert handle instead of registering.
+ */
+export declare function isAxSupported(doc: Document | undefined): boolean;
+//#endregion
+export type { AxAnnotations, AxDispatchOutcome, AxExecuteCallback, AxExecuteOptions, AxMiddleware, AxProviderProps, AxToolDefinition, AxToolHandle, AxToolOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/context.tsx","../src/dispatch.ts","../src/hooks.ts"],"mappings":";;;;;;;;UAUiB;WACP;WACA;WACA;WACA;;UAGO;WACP,QAAQ;;KAGN,qBACX,sBACA,SAAS,qBACL;UAEY;WACP;WACA;WACA;WACA;WACA,SAAS;WACT,cAAc;WACd,YAAY;;UAGL;WACP;WACA;WACA,OAAO,QAAQ;;KAGb,gBACX,MAAM,mBACN,eACA,SAAS,qBACL;UAEY;WACP;WACA;WACA;WACA,cAAc;WACd,YAAY;;;;UChCL;WACP;WACA,aAAa;WACb,UAAU;;;;;;;;wBASJ,WAAW,OAAO,kBAAkB;;;KCdxC;;;;;;wBA8HI,gBAAgB,QAAQ,UAAU;;;;;;;;;;;;;;;wBCzBlC,UAAU,MAAM,mBAAmB;wBACnC,UACf,cACA,SAAS,mBACT,UAAU,gBACR;;;;;wBA0Ka,cAAc,KAAK"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+"use client";import{createContext as e,createElement as t,useContext as n,useEffect as r,useMemo as i,useRef as a,useState as o}from"react";const s=e({namespace:``,middleware:void 0});function c(e){let r=n(s),a=i(()=>({namespace:`${r.namespace}${e.namespace??``}`,middleware:e.middleware===void 0?r.middleware:e.middleware}),[r.namespace,r.middleware,e.namespace,e.middleware]);return t(s.Provider,{value:a},e.children)}function l(e){try{if(typeof e.matches==`function`&&e.matches(`:disabled`))return!0}catch{}try{return e.disabled===!0}catch{return!1}}function u(e){let t=e.ownerDocument?.defaultView??void 0;try{return new MouseEvent(`click`,{bubbles:!0,cancelable:!0,view:t??null})}catch{return new Event(`click`,{bubbles:!0,cancelable:!0})}}function d(e){try{for(let t of Object.keys(e))if(t.startsWith(`__reactProps$`))return t}catch{return}}function f(e,t){try{let n=e[t];if(typeof n!=`object`||!n)return;let r=n.onClick;return typeof r==`function`?r:void 0}catch{return}}function p(e){let t=Object.getPrototypeOf(e);for(;t!==null;){let e=t.click;if(typeof e==`function`)return e;t=Object.getPrototypeOf(t)}}function m(e){let t=p(e);if(t!==void 0)try{t.call(e);return}catch{}let n=e.ownerDocument?.defaultView??void 0;try{e.dispatchEvent(new MouseEvent(`click`,{bubbles:!0,cancelable:!0,view:n??null}))}catch{e.dispatchEvent(new Event(`click`,{bubbles:!0,cancelable:!0}))}}function h(e){if(typeof e!=`object`||!e||e.nodeType!==1)throw TypeError(`bad dispatch target`);let t=e,n=e,r=!1;try{for(;n!==null;){let e=d(n);if(e!==void 0){r=!0;let i=f(n,e);if(i!==void 0){if(l(n)||l(t))break;let e=!1,r=!1,a;try{a=u(t)}catch{break}let o={type:`click`,bubbles:!0,cancelable:!0,get defaultPrevented(){return e},target:t,currentTarget:n,nativeEvent:a,preventDefault(){e=!0;try{a.preventDefault()}catch{}},stopPropagation(){r=!0;try{a.stopPropagation()}catch{}},isDefaultPrevented(){return e},isPropagationStopped(){return r}};try{i.call(n,o)}catch(e){console.error(`[ax-kit/react] bridged handler threw; skipping native fallback`,e)}return`bridge`}}n=n.parentElement}}catch{}r&&console.info(`[ax-kit/react] dispatch fallback to native dispatch`);try{m(t)}catch{}return`native`}const g={supported:!1,registered:!1,error:null};function _(){return typeof window<`u`&&typeof document<`u`}function v(e){let t=e.modelContext;if(typeof t==`object`&&t&&typeof t.registerTool==`function`)return t}function y(e,t,n,r,i,a){return b([e,t,n??null,b(r),b(i??null),b(a??null)])}function b(e){try{let t=JSON.stringify(e===void 0?null:e);return typeof t==`string`?t:`unserializable`}catch{return`unserializable`}}function x(e,t,n){if(typeof t!=`function`)throw TypeError(`bad execute`);return{name:e,description:n?.description??``,title:n?.title,inputSchema:n?.inputSchema,execute:t,annotations:n?.annotations,exposedTo:n?.exposedTo}}function S(e){return e instanceof DOMException&&e.name===`InvalidStateError`}function C(){return typeof MessageChannel==`function`?new Promise(e=>{let t=new MessageChannel;t.port1.onmessage=()=>{t.port1.close(),t.port2.close(),e()},t.port2.postMessage(void 0)}):Promise.resolve()}async function w(){await Promise.resolve(),await C()}function T(e,t,i){let c=typeof e==`string`?typeof t==`function`?null:/* @__PURE__ */ TypeError(`bad execute`):typeof e.execute==`function`?null:/* @__PURE__ */ TypeError(`bad execute`),l=typeof e==`string`?typeof t==`function`?x(e,t,i):{name:e,description:i?.description??``,title:i?.title,inputSchema:i?.inputSchema,execute:async()=>{throw TypeError(`bad execute`)},annotations:i?.annotations,exposedTo:i?.exposedTo}:e,{namespace:u,middleware:d}=n(s),f=`${u}${l.name}`,p=l.execute,m=a(typeof p==`function`?p:async()=>{throw TypeError(`bad execute`)}),h=a(d);r(()=>{typeof p==`function`&&(m.current=p)}),r(()=>{h.current=d});let b=y(f,l.description,l.title,l.inputSchema,l.annotations,l.exposedTo),C=c!==null,[T,E]=o(()=>_()?c===null?{supported:!0,registered:!1,error:null}:{supported:!0,registered:!1,error:c}:g);return r(()=>{if(!_()){E(g);return}if(C){E({supported:!0,registered:!1,error:/* @__PURE__ */ TypeError(`bad execute`)});return}let e=v(document);if(e===void 0){E({supported:!1,registered:!1,error:null});return}let t=e,n=!1,r=new AbortController,i=!1,a=(e,t)=>{let n=m.current,r=h.current;return r===void 0?n(e,t):r(n,e,t)};async function o(e){try{await t.registerTool({name:f,title:l.title,description:l.description,inputSchema:l.inputSchema,execute:a,annotations:l.annotations},{exposedTo:l.exposedTo,signal:r.signal}),!n&&!i&&(i=!0,E({supported:!0,registered:!0,error:null}))}catch(t){if(r.signal.aborted||n)return;if(S(t)&&e===0){if(await w(),r.signal.aborted||n)return;await o(1);return}!n&&!i&&(i=!0,E({supported:!0,registered:!1,error:t??null}))}}return o(0),()=>{n=!0,r.abort(),E({supported:!0,registered:!1,error:null})}},[b,C]),_()?T:g}function E(e){return e===void 0||!_()?!1:v(e)!==void 0}export{c as AxProvider,h as dispatchAxClick,E as isAxSupported,T as useAxTool};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["raw","doc","AxContext","createContext","AxProvider","parent","useContext","value","useMemo","props","createElement","isDisabled","el","nativeEventFor","view","target","readPropsKey","key","readHandler","handler","nativeClickOf","proto","found","nativeDispatch","nativeClick","dispatchAxClick","original","node","sawReactNode","defaultPrevented","propagationStopped","nativeEvent","synthetic","error","INERT","hasWindow","surfaceOf","candidate","doc","snapshotIdentity","safeJson","name","description","title","inputSchema","annotations","exposedTo","text","fromCallback","options","isDuplicateName","nextTask","channel","resolve","quiesce","useAxTool","validationError","arg0","arg1","tool","arg2","effectiveName","namespace","rawExecute","handlerRef","useRef","middlewareRef","middleware","useEffect","validationFailed","state","setState","useState","detected","surface","cancelled","controller","settled","stableExecute","latest","wrap","args","opts","register","attempt","isAxSupported"],"sources":["../src/context.tsx","../src/dispatch.ts","../src/hooks.ts"],"sourcesContent":["// Copyright 2026 Utpal Sen\n// SPDX-License-Identifier: Apache-2.0\n\n\"use client\";\n\nimport type { Context, ReactNode } from \"react\";\nimport { createContext, createElement, useContext, useMemo } from \"react\";\nimport type { AxMiddleware } from \"./types.js\";\n\nexport interface AxContextValue {\n\treadonly namespace: string;\n\treadonly middleware: AxMiddleware | undefined;\n}\n\nexport const AxContext: Context<AxContextValue> = createContext<AxContextValue>(\n\t{\n\t\tnamespace: \"\",\n\t\tmiddleware: undefined,\n\t},\n);\n\nexport interface AxProviderProps {\n\treadonly namespace?: string | undefined;\n\treadonly middleware?: AxMiddleware | undefined;\n\treadonly children: ReactNode;\n}\n\n/**\n * Share a name prefix plus invocation middleware with a subtree. Nested\n * providers concatenate prefixes so per-tool wiring stays flat. The\n * middleware wraps the latest handler only; registration identity is\n * unaffected by middleware changes.\n */\nexport function AxProvider(props: AxProviderProps): ReactNode {\n\tconst parent = useContext(AxContext);\n\tconst value = useMemo<AxContextValue>(\n\t\t() => ({\n\t\t\tnamespace: `${parent.namespace}${props.namespace ?? \"\"}`,\n\t\t\tmiddleware:\n\t\t\t\tprops.middleware !== undefined ? props.middleware : parent.middleware,\n\t\t}),\n\t\t[parent.namespace, parent.middleware, props.namespace, props.middleware],\n\t);\n\treturn createElement(AxContext.Provider, { value }, props.children);\n}\n","// Copyright 2026 Utpal Sen\n// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Click dispatch for React-managed nodes. Best-effort progressive\n * enhancement over native dispatch: invoke the nearest enclosing `onClick`\n * via the framework props prefix with a synthesized event carrying the real\n * target, and always fall back to native bubbling dispatch. Click-only and\n * single-handler by design: capture handlers, other event types, and further\n * ancestors never run through the bridge. Plain DOM and everything the\n * bridge misses use native dispatch with no bridge. Failure of the\n * enhancement never rejects an invocation native dispatch could complete. A\n * bridged handler that throws is reported without a native re-run, so one\n * logical click never invokes the handler twice. Scoped to React-managed\n * nodes; plain DOM uses native dispatch with no bridge.\n */\n\nconst PROPS_PREFIX = \"__reactProps$\";\n\nexport type AxDispatchOutcome = \"bridge\" | \"native\";\n\ninterface AxSyntheticClick {\n\treadonly type: \"click\";\n\treadonly bubbles: boolean;\n\treadonly cancelable: boolean;\n\treadonly defaultPrevented: boolean;\n\treadonly target: EventTarget;\n\treadonly currentTarget: EventTarget;\n\treadonly nativeEvent: Event;\n\tpreventDefault(): void;\n\tstopPropagation(): void;\n\tisDefaultPrevented(): boolean;\n\tisPropagationStopped(): boolean;\n}\n\nfunction isDisabled(el: Element): boolean {\n\ttry {\n\t\tif (typeof el.matches === \"function\" && el.matches(\":disabled\")) {\n\t\t\treturn true;\n\t\t}\n\t} catch {\n\t\t// Fall through to the own-property check below.\n\t}\n\ttry {\n\t\treturn (el as unknown as { disabled?: unknown }).disabled === true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction nativeEventFor(target: Element): Event {\n\tconst view = target.ownerDocument?.defaultView ?? undefined;\n\ttry {\n\t\treturn new MouseEvent(\"click\", {\n\t\t\tbubbles: true,\n\t\t\tcancelable: true,\n\t\t\tview: view ?? null,\n\t\t});\n\t} catch {\n\t\treturn new Event(\"click\", { bubbles: true, cancelable: true });\n\t}\n}\n\nfunction readPropsKey(el: Element): string | undefined {\n\ttry {\n\t\tfor (const key of Object.keys(el)) {\n\t\t\tif (key.startsWith(PROPS_PREFIX)) {\n\t\t\t\treturn key;\n\t\t\t}\n\t\t}\n\t} catch {\n\t\treturn undefined;\n\t}\n\treturn undefined;\n}\n\nfunction readHandler(\n\tel: Element,\n\tkey: string,\n): ((event: unknown) => void) | undefined {\n\ttry {\n\t\tconst props = (el as unknown as Record<string, unknown>)[key] as\n\t\t\t| Record<string, unknown>\n\t\t\t| null\n\t\t\t| undefined;\n\t\tif (typeof props !== \"object\" || props === null) {\n\t\t\treturn undefined;\n\t\t}\n\t\tconst handler = props.onClick;\n\t\treturn typeof handler === \"function\"\n\t\t\t? (handler as (event: unknown) => void)\n\t\t\t: undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * The native click up the target's own prototype chain, skipping own\n * expandos. A page-owned `click` property must never shadow the trusted\n * activation the bridge falls back to.\n */\nfunction nativeClickOf(target: Element): (() => void) | undefined {\n\tlet proto: unknown = Object.getPrototypeOf(target);\n\twhile (proto !== null) {\n\t\tconst found = (proto as Record<string, unknown>).click;\n\t\tif (typeof found === \"function\") {\n\t\t\treturn found as () => void;\n\t\t}\n\t\tproto = Object.getPrototypeOf(proto);\n\t}\n\treturn undefined;\n}\n\nfunction nativeDispatch(target: Element): void {\n\tconst nativeClick = nativeClickOf(target);\n\tif (nativeClick !== undefined) {\n\t\ttry {\n\t\t\tnativeClick.call(target);\n\t\t\treturn;\n\t\t} catch {\n\t\t\t// Fall through to event dispatch below.\n\t\t}\n\t}\n\tconst view = target.ownerDocument?.defaultView ?? undefined;\n\ttry {\n\t\ttarget.dispatchEvent(\n\t\t\tnew MouseEvent(\"click\", {\n\t\t\t\tbubbles: true,\n\t\t\t\tcancelable: true,\n\t\t\t\tview: view ?? null,\n\t\t\t}),\n\t\t);\n\t} catch {\n\t\ttarget.dispatchEvent(\n\t\t\tnew Event(\"click\", { bubbles: true, cancelable: true }),\n\t\t);\n\t}\n}\n\n/**\n * Drive one click. Returns how it was handled. Never throws for a reachable\n * target: bridge failure falls back to native dispatch with a logged\n * fallback. Non-element targets reject with `TypeError`.\n */\nexport function dispatchAxClick(target: Element): AxDispatchOutcome {\n\tif (\n\t\ttypeof target !== \"object\" ||\n\t\ttarget === null ||\n\t\t(target as Node).nodeType !== 1\n\t) {\n\t\tthrow new TypeError(\"bad dispatch target\");\n\t}\n\tconst original = target;\n\tlet node: Element | null = target;\n\tlet sawReactNode = false;\n\ttry {\n\t\twhile (node !== null) {\n\t\t\tconst key = readPropsKey(node);\n\t\t\tif (key !== undefined) {\n\t\t\t\tsawReactNode = true;\n\t\t\t\tconst handler = readHandler(node, key);\n\t\t\t\tif (handler !== undefined) {\n\t\t\t\t\tif (isDisabled(node) || isDisabled(original)) {\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tlet defaultPrevented = false;\n\t\t\t\t\tlet propagationStopped = false;\n\t\t\t\t\tlet nativeEvent: Event;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tnativeEvent = nativeEventFor(original);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tconst synthetic: AxSyntheticClick = {\n\t\t\t\t\t\ttype: \"click\",\n\t\t\t\t\t\tbubbles: true,\n\t\t\t\t\t\tcancelable: true,\n\t\t\t\t\t\tget defaultPrevented(): boolean {\n\t\t\t\t\t\t\treturn defaultPrevented;\n\t\t\t\t\t\t},\n\t\t\t\t\t\ttarget: original,\n\t\t\t\t\t\tcurrentTarget: node,\n\t\t\t\t\t\tnativeEvent,\n\t\t\t\t\t\tpreventDefault(): void {\n\t\t\t\t\t\t\tdefaultPrevented = true;\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tnativeEvent.preventDefault();\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// Native event is best-effort only.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t},\n\t\t\t\t\t\tstopPropagation(): void {\n\t\t\t\t\t\t\tpropagationStopped = true;\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tnativeEvent.stopPropagation();\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// Native event is best-effort only.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t},\n\t\t\t\t\t\tisDefaultPrevented(): boolean {\n\t\t\t\t\t\t\treturn defaultPrevented;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tisPropagationStopped(): boolean {\n\t\t\t\t\t\t\treturn propagationStopped;\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t\ttry {\n\t\t\t\t\t\thandler.call(node, synthetic);\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tconsole.error(\n\t\t\t\t\t\t\t\"[ax-kit/react] bridged handler threw; skipping native fallback\",\n\t\t\t\t\t\t\terror,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn \"bridge\";\n\t\t\t\t}\n\t\t\t}\n\t\t\tnode = node.parentElement;\n\t\t}\n\t} catch {\n\t\t// Best-effort only: fall through to native dispatch below.\n\t}\n\tif (sawReactNode) {\n\t\tconsole.info(\"[ax-kit/react] dispatch fallback to native dispatch\");\n\t}\n\ttry {\n\t\tnativeDispatch(original);\n\t} catch {\n\t\t// Native dispatch is the last resort; its failure is observed by the\n\t\t// caller through the DOM, never as a rejection here.\n\t}\n\treturn \"native\";\n}\n","// Copyright 2026 Utpal Sen\n// SPDX-License-Identifier: Apache-2.0\n\n\"use client\";\n\nimport { useContext, useEffect, useRef, useState } from \"react\";\nimport { AxContext } from \"./context.js\";\nimport type {\n\tAxExecuteCallback,\n\tAxModelContextLike,\n\tAxToolDefinition,\n\tAxToolHandle,\n\tAxToolOptions,\n} from \"./types.js\";\n\nconst INERT: AxToolHandle = {\n\tsupported: false,\n\tregistered: false,\n\terror: null,\n};\n\nfunction hasWindow(): boolean {\n\treturn typeof window !== \"undefined\" && typeof document !== \"undefined\";\n}\n\nfunction surfaceOf(doc: Document): AxModelContextLike | undefined {\n\tconst raw = doc as unknown as Record<string, unknown>;\n\tconst candidate = raw.modelContext;\n\tif (typeof candidate !== \"object\" || candidate === null) {\n\t\treturn undefined;\n\t}\n\tconst register = (candidate as Record<string, unknown>).registerTool;\n\tif (typeof register !== \"function\") {\n\t\treturn undefined;\n\t}\n\treturn candidate as AxModelContextLike;\n}\n\nfunction snapshotIdentity(\n\tname: string,\n\tdescription: string,\n\ttitle: string | undefined,\n\tinputSchema: unknown,\n\tannotations: unknown,\n\texposedTo: ReadonlyArray<string> | undefined,\n): string {\n\treturn safeJson([\n\t\tname,\n\t\tdescription,\n\t\ttitle ?? null,\n\t\tsafeJson(inputSchema),\n\t\tsafeJson(annotations ?? null),\n\t\tsafeJson(exposedTo ?? null),\n\t]);\n}\n\nfunction safeJson(value: unknown): string {\n\ttry {\n\t\tconst text: unknown = JSON.stringify(value === undefined ? null : value);\n\t\treturn typeof text === \"string\" ? text : \"unserializable\";\n\t} catch {\n\t\treturn \"unserializable\";\n\t}\n}\n\nfunction fromCallback(\n\tname: string,\n\thandler: AxExecuteCallback | undefined,\n\toptions: AxToolOptions | undefined,\n): AxToolDefinition {\n\tif (typeof handler !== \"function\") {\n\t\tthrow new TypeError(\"bad execute\");\n\t}\n\treturn {\n\t\tname,\n\t\tdescription: options?.description ?? \"\",\n\t\ttitle: options?.title,\n\t\tinputSchema: options?.inputSchema,\n\t\texecute: handler,\n\t\tannotations: options?.annotations,\n\t\texposedTo: options?.exposedTo,\n\t};\n}\n\nfunction isDuplicateName(error: unknown): boolean {\n\treturn error instanceof DOMException && error.name === \"InvalidStateError\";\n}\n\nfunction nextTask(): Promise<void> {\n\tif (typeof MessageChannel === \"function\") {\n\t\treturn new Promise<void>((resolve) => {\n\t\t\tconst channel = new MessageChannel();\n\t\t\tchannel.port1.onmessage = (): void => {\n\t\t\t\tchannel.port1.close();\n\t\t\t\tchannel.port2.close();\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tchannel.port2.postMessage(undefined);\n\t\t});\n\t}\n\treturn Promise.resolve();\n}\n\nasync function quiesce(): Promise<void> {\n\tawait Promise.resolve();\n\tawait nextTask();\n}\n\n/**\n * Register a tool for the lifetime of the calling component. The\n * registration controller is created inside the client effect with cleanup\n * aborting it, so development setup-cleanup-setup leaves exactly one\n * registration. The registered callback is stable and forwards to a\n * latest-handler mailbox, while identity change aborts then registers with\n * tolerance for transient duplicate-name rejection.\n *\n * The name-plus-handler form is the same tool under a shorter call: the\n * description and contract options default to empty so mistakes surface the\n * draft error family instead of a placeholder.\n */\nexport function useAxTool(tool: AxToolDefinition): AxToolHandle;\nexport function useAxTool(\n\tname: string,\n\thandler: AxExecuteCallback,\n\toptions?: AxToolOptions,\n): AxToolHandle;\nexport function useAxTool(\n\targ0: AxToolDefinition | string,\n\targ1?: AxExecuteCallback,\n\targ2?: AxToolOptions,\n): AxToolHandle {\n\tconst validationError: TypeError | null =\n\t\ttypeof arg0 === \"string\"\n\t\t\t? typeof arg1 !== \"function\"\n\t\t\t\t? new TypeError(\"bad execute\")\n\t\t\t\t: null\n\t\t\t: typeof (arg0 as unknown as { execute?: unknown }).execute !== \"function\"\n\t\t\t\t? new TypeError(\"bad execute\")\n\t\t\t\t: null;\n\tconst tool: AxToolDefinition =\n\t\ttypeof arg0 === \"string\"\n\t\t\t? typeof arg1 === \"function\"\n\t\t\t\t? fromCallback(arg0, arg1, arg2)\n\t\t\t\t: {\n\t\t\t\t\t\tname: arg0,\n\t\t\t\t\t\tdescription: arg2?.description ?? \"\",\n\t\t\t\t\t\ttitle: arg2?.title,\n\t\t\t\t\t\tinputSchema: arg2?.inputSchema,\n\t\t\t\t\t\texecute: async (): Promise<unknown> => {\n\t\t\t\t\t\t\tthrow new TypeError(\"bad execute\");\n\t\t\t\t\t\t},\n\t\t\t\t\t\tannotations: arg2?.annotations,\n\t\t\t\t\t\texposedTo: arg2?.exposedTo,\n\t\t\t\t\t}\n\t\t\t: arg0;\n\tconst { namespace, middleware } = useContext(AxContext);\n\tconst effectiveName = `${namespace}${tool.name}`;\n\n\tconst rawExecute = (tool as unknown as { execute?: unknown }).execute;\n\tconst safeExecute: AxExecuteCallback =\n\t\ttypeof rawExecute === \"function\"\n\t\t\t? (rawExecute as AxExecuteCallback)\n\t\t\t: async (): Promise<unknown> => {\n\t\t\t\t\tthrow new TypeError(\"bad execute\");\n\t\t\t\t};\n\tconst handlerRef = useRef<AxExecuteCallback>(safeExecute);\n\tconst middlewareRef = useRef(middleware);\n\t// Write the mailbox in an effect, never during render: a render-time\n\t// write could expose a handler from an abandoned render while the\n\t// previous registration stays active.\n\tuseEffect(() => {\n\t\tif (typeof rawExecute === \"function\") {\n\t\t\thandlerRef.current = rawExecute as AxExecuteCallback;\n\t\t}\n\t});\n\tuseEffect(() => {\n\t\tmiddlewareRef.current = middleware;\n\t});\n\n\tconst identity = snapshotIdentity(\n\t\teffectiveName,\n\t\ttool.description,\n\t\ttool.title,\n\t\ttool.inputSchema,\n\t\ttool.annotations,\n\t\ttool.exposedTo,\n\t);\n\tconst key = identity;\n\tconst validationFailed = validationError !== null;\n\n\tconst [state, setState] = useState<AxToolHandle>(() => {\n\t\tif (!hasWindow()) {\n\t\t\treturn INERT;\n\t\t}\n\t\tif (validationError !== null) {\n\t\t\treturn { supported: true, registered: false, error: validationError };\n\t\t}\n\t\treturn { supported: true, registered: false, error: null };\n\t});\n\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: key encodes identity\n\tuseEffect(() => {\n\t\tif (!hasWindow()) {\n\t\t\tsetState(INERT);\n\t\t\treturn;\n\t\t}\n\t\tif (validationFailed) {\n\t\t\tsetState({\n\t\t\t\tsupported: true,\n\t\t\t\tregistered: false,\n\t\t\t\terror: new TypeError(\"bad execute\"),\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tconst doc: Document = document;\n\t\tconst detected = surfaceOf(doc);\n\t\tif (detected === undefined) {\n\t\t\tsetState({ supported: false, registered: false, error: null });\n\t\t\treturn;\n\t\t}\n\t\tconst surface: AxModelContextLike = detected;\n\t\tlet cancelled = false;\n\t\tconst controller = new AbortController();\n\t\tlet settled = false;\n\n\t\tconst stableExecute: AxExecuteCallback = (args, opts) => {\n\t\t\tconst latest = handlerRef.current;\n\t\t\tconst wrap = middlewareRef.current;\n\t\t\tif (wrap === undefined) {\n\t\t\t\treturn latest(args, opts);\n\t\t\t}\n\t\t\treturn wrap(latest, args, opts);\n\t\t};\n\n\t\tasync function register(attempt: number): Promise<void> {\n\t\t\ttry {\n\t\t\t\tawait surface.registerTool(\n\t\t\t\t\t{\n\t\t\t\t\t\tname: effectiveName,\n\t\t\t\t\t\ttitle: tool.title,\n\t\t\t\t\t\tdescription: tool.description,\n\t\t\t\t\t\tinputSchema: tool.inputSchema,\n\t\t\t\t\t\texecute: stableExecute,\n\t\t\t\t\t\tannotations: tool.annotations,\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\texposedTo: tool.exposedTo,\n\t\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t\tif (!cancelled && !settled) {\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tsetState({ supported: true, registered: true, error: null });\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\tif (controller.signal.aborted || cancelled) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (isDuplicateName(error) && attempt === 0) {\n\t\t\t\t\tawait quiesce();\n\t\t\t\t\tif (controller.signal.aborted || cancelled) {\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tawait register(1);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (!cancelled && !settled) {\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tsetState({\n\t\t\t\t\t\tsupported: true,\n\t\t\t\t\t\tregistered: false,\n\t\t\t\t\t\terror: (error as Error | DOMException) ?? null,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tvoid register(0);\n\t\treturn () => {\n\t\t\tcancelled = true;\n\t\t\tcontroller.abort();\n\t\t\tsetState({ supported: true, registered: false, error: null });\n\t\t};\n\t}, [key, validationFailed]);\n\n\tif (!hasWindow()) {\n\t\treturn INERT;\n\t}\n\treturn state;\n}\n\n/**\n * Feature-detect the registration surface for one document. False where the\n * caller must render the inert handle instead of registering.\n */\nexport function isAxSupported(doc: Document | undefined): boolean {\n\tif (doc === undefined) {\n\t\treturn false;\n\t}\n\tif (!hasWindow()) {\n\t\treturn false;\n\t}\n\treturn surfaceOf(doc) !== undefined;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@ax-kit/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Lifecycle-native ModelContext bindings for React",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-ax/ax-kit.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/open-ax/ax-kit",
+  "bugs": "https://github.com/open-ax/ax-kit/issues",
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/browser-playwright": "5.0.2",
+    "happy-dom": "20.14.6",
+    "playwright": "1.63.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsdown": "0.23.1",
+    "typescript": "6.0.3",
+    "vitest": "5.0.2",
+    "@ax-kit/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "size": "echo \"no size gate for bindings\"",
+    "publint": "publint --strict",
+    "attw": "attw --pack . --profile node16"
+  }
 }