@ggui-ai/gadgets 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 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 Support. 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 support.
+
+   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 Loqu, Inc. (Guuey)
+
+   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

@@ -0,0 +1,121 @@
+# @ggui-ai/gadgets
+
+> Browser-capability gadget hooks for ggui. Declared on a `DataContract` via `clientCapabilities.gadgets[*]`, mounted by the UI generator's component code, surfaced to agents through the protocol's gadget-discovery tool.
+
+## Why
+
+LLM-generated component code needs a stable, narrow API for the small set of browser capabilities that interactive UIs reach for: geolocation, clipboard read/write, notifications, file pickers, microphone, camera. Each capability has the same lifecycle shape — pending → ready → error — and the same permission-prompt UX. Encoding that shape once, in a typed React hook, keeps the generator's output:
+
+- predictable across providers and prompts,
+- testable by code-property assertions on the generated source (not just the rendered DOM),
+- bounded by the v1 stdlib catalog the protocol's contract linter recognizes.
+
+The contract declares WHICH hooks the component will mount; the hooks own how they behave at runtime.
+
+## Installation
+
+```bash
+pnpm add @ggui-ai/gadgets
+```
+
+Peer-dep: `react` ^18 || ^19.
+
+## v1 stdlib catalog
+
+Seven hooks ship in v1, all with a shared `{ status, error, value | data | call }` shape:
+
+| Hook                | Permission        | Description                                                  |
+| ------------------- | ----------------- | ------------------------------------------------------------ |
+| `useGeolocation`    | `geolocation`     | Current position + watch updates.                            |
+| `useClipboardWrite` | `clipboard-write` | Write text or rich payload to the user's clipboard.          |
+| `useClipboardPaste` | `clipboard-read`  | Read the user's clipboard on explicit user gesture.          |
+| `useNotifications`  | `notifications`   | Request permission + post a system notification.             |
+| `useFilePicker`     | _none_            | Open the OS file picker (gated by user activation, no perm). |
+| `useMicrophone`     | `microphone`      | Stream access to the user's microphone via `getUserMedia`.   |
+| `useCamera`         | `camera`          | Stream access to the user's camera via `getUserMedia`.       |
+
+The same list is exported from `@ggui-ai/protocol` as `STDLIB_GADGETS` and seeds the discovery tool (`ggui_list_gadgets`) for any app without an operator-mutated override.
+
+## How a contract uses these hooks
+
+The agent declares the gadgets the component will mount on the contract's `clientCapabilities.gadgets` — a package-keyed map: the npm package name keys the outer map, the export name keys the inner map. The agent names which package + which exports; it does NOT pin a `version` (the operator's `App.gadgets` catalog owns the version). The permission a capability prompts for is NOT a contract field; it is declared by the operator on the registered descriptor's export (`GadgetExport.permission`), and the renderer reads it from there to derive a `Permissions-Policy` header:
+
+```ts
+import { defineContract } from "@ggui-ai/protocol";
+
+export const photoCaptureContract = defineContract({
+  propsSpec: {
+    properties: {
+      title: { schema: { type: "string" }, default: "Take a photo" },
+    },
+  },
+  actionSpec: {
+    capture: {
+      label: "Capture",
+      schema: { type: "object", properties: { dataUrl: { type: "string" } } },
+    },
+  },
+  clientCapabilities: {
+    // `gadgets` is package-keyed: `Record<package, Record<exportName,
+    // { description?, usage? }>>`. The wire carries identity only —
+    // `version`, transport fields, and per-export registry metadata
+    // (`permission`, `example`, `gotchas`, `required`) are NOT on the
+    // wire; the server resolves them from `App.gadgets` at push time.
+    gadgets: {
+      "@ggui-ai/gadgets": {
+        useCamera: {
+          usage: "Live camera preview + capture-to-data-URL on the capture action.",
+        },
+      },
+    },
+  },
+} as const);
+```
+
+The generator reads `clientCapabilities.gadgets` and emits matching `import { useCamera } from '@ggui-ai/gadgets'` lines at the top of the generated component. Permission strings — read from the registered descriptor's per-export `permission` field — union-deduplicate into a `Permissions-Policy` header on the public-render route and an `allow=""` attribute on the MCP-Apps iframe host.
+
+## Hook surface
+
+Every hook returns a `{ status, ... }` object whose status is `'idle' | 'prompting' | 'active' | 'completed' | 'denied' | 'error'`. Specific value fields live alongside it. Example:
+
+```tsx
+import { useGeolocation } from "@ggui-ai/gadgets";
+
+function NearbyStores() {
+  const geo = useGeolocation();
+  if (geo.status === "completed" || geo.status === "active") {
+    return <List origin={geo.value} />;
+  }
+  if (geo.status === "denied") return <Disabled reason="Allow location to see nearby stores" />;
+  return <Skeleton />;
+}
+```
+
+See the per-hook source under `src/use*.ts` for the exact return shape and options surface.
+
+## Authoring your own gadget package
+
+To wrap a third-party browser library (Leaflet, Mapbox, Chart.js, …) as a
+gadget package, use `defineGadgetPackage` — it takes the package identity
+once plus a list of export declarations (hooks and/or components) and
+returns a validated `GadgetDescriptor`:
+
+```ts
+import { defineGadgetPackage } from "@ggui-ai/gadgets";
+
+export const chartDescriptor = defineGadgetPackage({
+  package: "@my-org/gadget-chart",
+  version: "0.1.0",
+  exports: [
+    { component: "Chart", impl: Chart, description: "…", usage: "…", example: {} },
+    { hook: "useChartTheme", impl: useChartTheme, description: "…", usage: "…", example: {} },
+  ],
+});
+```
+
+For a single-hook package, `createGguiGadget` is the convenience builder.
+Emit `descriptor.json` for registry consumption via `@ggui-ai/gadgets/codegen`.
+
+## See also
+
+- [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol) — `GadgetDescriptor`, `GadgetExport`, `ClientCapabilitiesSpec`, `STDLIB_GADGETS`, and the contract linter that validates contracts using these hooks.

package/dist/codegen.d.mts

@@ -0,0 +1,78 @@
+import { GadgetDescriptor } from '@ggui-ai/protocol';
+
+/**
+ * `@ggui-ai/gadgets/codegen` — wrapper-author build helper.
+ *
+ * Emits `descriptor.json` for registry consumption ({@link
+ * writeDescriptorJson}). A gadget wrapper's type narrowing comes from
+ * its own real `.d.ts` (emitted by `tsc --declaration` / `tsup --dts`)
+ * — the registry serves it via `typesUrl`, and the code-gen sandbox
+ * overlays it per-package so a direct `import { useLeafletMap } from
+ * '@scope/wrapper-leaflet'` resolves against the strict hook
+ * signatures. Gadgets are direct-imported — one idiom with the design
+ * primitives — so there is no catalog-augmentation codegen step.
+ *
+ * This file is Node-only — it uses `node:fs/promises`. The codegen
+ * lives at a separate entry (`@ggui-ai/gadgets/codegen`) so the
+ * browser-runtime bundle's import graph stays minimal.
+ */
+
+/**
+ * Emit `descriptor.json` for registry consumption.
+ *
+ * Wrapper authors structure their build like:
+ *
+ * ```ts
+ * // build.ts
+ * import { writeDescriptorJson } from '@ggui-ai/gadgets/codegen';
+ * import { useLeafletMap } from './src/index';
+ *
+ * await writeDescriptorJson({
+ *   descriptors: [useLeafletMap.descriptor],
+ *   outputPath: 'dist/descriptor.json',
+ * });
+ * ```
+ *
+ * The author's build is responsible for type metadata: run
+ * `tsup --dts` (or `tsc --declaration`) to emit the wrapper's
+ * `.d.ts`, compute its SHA-384 SRI, and set `typesUrl` + `typesSri`
+ * on each descriptor BEFORE calling this helper. `writeDescriptorJson`
+ * itself is pure I/O + validation — no TS Compiler API, no signature
+ * extraction. Type narrowing is sourced from the real emitted `.d.ts`
+ * file, not an inline signature string.
+ *
+ * The helper:
+ *   1. Validates each descriptor against
+ *      `registeredGadgetDescriptorSchema` (every registered descriptor
+ *      MUST pass — same gate the `App.gadgets` registration handler
+ *      applies, including the `typesUrl`-required refinement for
+ *      non-stdlib gadgets).
+ *   2. Writes a JSON document `{ version: 'gg2', descriptors: [...] }`.
+ */
+interface WriteDescriptorJsonInput {
+    /**
+     * Descriptors authored via `createGguiGadget(...).descriptor` (or
+     * hand-written), with `typesUrl` + `typesSri` already populated by
+     * the wrapper build.
+     */
+    readonly descriptors: readonly GadgetDescriptor[];
+    /**
+     * Output path for the JSON document. Parent directories are
+     * created as needed.
+     */
+    readonly outputPath: string;
+}
+/**
+ * Output payload of {@link writeDescriptorJson}. Returned for tests
+ * + callers that want to introspect the validated descriptors without
+ * re-reading the file.
+ */
+interface DescriptorJsonDocument {
+    /** Schema-format marker for the descriptor.json document. */
+    readonly version: 'gg2';
+    /** Strict-validated descriptors. */
+    readonly descriptors: readonly GadgetDescriptor[];
+}
+declare function writeDescriptorJson(input: WriteDescriptorJsonInput): Promise<DescriptorJsonDocument>;
+
+export { type DescriptorJsonDocument, type WriteDescriptorJsonInput, writeDescriptorJson };

package/dist/codegen.d.ts

@@ -0,0 +1,78 @@
+import { GadgetDescriptor } from '@ggui-ai/protocol';
+
+/**
+ * `@ggui-ai/gadgets/codegen` — wrapper-author build helper.
+ *
+ * Emits `descriptor.json` for registry consumption ({@link
+ * writeDescriptorJson}). A gadget wrapper's type narrowing comes from
+ * its own real `.d.ts` (emitted by `tsc --declaration` / `tsup --dts`)
+ * — the registry serves it via `typesUrl`, and the code-gen sandbox
+ * overlays it per-package so a direct `import { useLeafletMap } from
+ * '@scope/wrapper-leaflet'` resolves against the strict hook
+ * signatures. Gadgets are direct-imported — one idiom with the design
+ * primitives — so there is no catalog-augmentation codegen step.
+ *
+ * This file is Node-only — it uses `node:fs/promises`. The codegen
+ * lives at a separate entry (`@ggui-ai/gadgets/codegen`) so the
+ * browser-runtime bundle's import graph stays minimal.
+ */
+
+/**
+ * Emit `descriptor.json` for registry consumption.
+ *
+ * Wrapper authors structure their build like:
+ *
+ * ```ts
+ * // build.ts
+ * import { writeDescriptorJson } from '@ggui-ai/gadgets/codegen';
+ * import { useLeafletMap } from './src/index';
+ *
+ * await writeDescriptorJson({
+ *   descriptors: [useLeafletMap.descriptor],
+ *   outputPath: 'dist/descriptor.json',
+ * });
+ * ```
+ *
+ * The author's build is responsible for type metadata: run
+ * `tsup --dts` (or `tsc --declaration`) to emit the wrapper's
+ * `.d.ts`, compute its SHA-384 SRI, and set `typesUrl` + `typesSri`
+ * on each descriptor BEFORE calling this helper. `writeDescriptorJson`
+ * itself is pure I/O + validation — no TS Compiler API, no signature
+ * extraction. Type narrowing is sourced from the real emitted `.d.ts`
+ * file, not an inline signature string.
+ *
+ * The helper:
+ *   1. Validates each descriptor against
+ *      `registeredGadgetDescriptorSchema` (every registered descriptor
+ *      MUST pass — same gate the `App.gadgets` registration handler
+ *      applies, including the `typesUrl`-required refinement for
+ *      non-stdlib gadgets).
+ *   2. Writes a JSON document `{ version: 'gg2', descriptors: [...] }`.
+ */
+interface WriteDescriptorJsonInput {
+    /**
+     * Descriptors authored via `createGguiGadget(...).descriptor` (or
+     * hand-written), with `typesUrl` + `typesSri` already populated by
+     * the wrapper build.
+     */
+    readonly descriptors: readonly GadgetDescriptor[];
+    /**
+     * Output path for the JSON document. Parent directories are
+     * created as needed.
+     */
+    readonly outputPath: string;
+}
+/**
+ * Output payload of {@link writeDescriptorJson}. Returned for tests
+ * + callers that want to introspect the validated descriptors without
+ * re-reading the file.
+ */
+interface DescriptorJsonDocument {
+    /** Schema-format marker for the descriptor.json document. */
+    readonly version: 'gg2';
+    /** Strict-validated descriptors. */
+    readonly descriptors: readonly GadgetDescriptor[];
+}
+declare function writeDescriptorJson(input: WriteDescriptorJsonInput): Promise<DescriptorJsonDocument>;
+
+export { type DescriptorJsonDocument, type WriteDescriptorJsonInput, writeDescriptorJson };

package/dist/codegen.js

@@ -0,0 +1,69 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/codegen.ts
+var codegen_exports = {};
+__export(codegen_exports, {
+  writeDescriptorJson: () => writeDescriptorJson
+});
+module.exports = __toCommonJS(codegen_exports);
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+async function writeDescriptorJson(input) {
+  const { descriptors, outputPath } = input;
+  const { registeredGadgetDescriptorSchema } = await import("@ggui-ai/protocol");
+  const validated = [];
+  for (const descriptor of descriptors) {
+    const parsed = registeredGadgetDescriptorSchema.safeParse(descriptor);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `writeDescriptorJson: descriptor for package '${descriptor.package}@${descriptor.version}' failed strict validation:
+${issues}`
+      );
+    }
+    validated.push(parsed.data);
+  }
+  const document = {
+    version: "gg2",
+    descriptors: validated
+  };
+  await (0, import_promises.mkdir)((0, import_node_path.dirname)(outputPath), { recursive: true });
+  await (0, import_promises.writeFile)(
+    outputPath,
+    `${JSON.stringify(document, null, 2)}
+`,
+    "utf8"
+  );
+  return document;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  writeDescriptorJson
+});

package/dist/codegen.mjs

@@ -0,0 +1,34 @@
+// src/codegen.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname } from "path";
+async function writeDescriptorJson(input) {
+  const { descriptors, outputPath } = input;
+  const { registeredGadgetDescriptorSchema } = await import("@ggui-ai/protocol");
+  const validated = [];
+  for (const descriptor of descriptors) {
+    const parsed = registeredGadgetDescriptorSchema.safeParse(descriptor);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+      throw new Error(
+        `writeDescriptorJson: descriptor for package '${descriptor.package}@${descriptor.version}' failed strict validation:
+${issues}`
+      );
+    }
+    validated.push(parsed.data);
+  }
+  const document = {
+    version: "gg2",
+    descriptors: validated
+  };
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(
+    outputPath,
+    `${JSON.stringify(document, null, 2)}
+`,
+    "utf8"
+  );
+  return document;
+}
+export {
+  writeDescriptorJson
+};