@ggui-ai/gadgets 0.2.0-alpha.4 → 0.4.0-rc.0

package/README.md

@@ -4,7 +4,7 @@
 
 ## 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:
+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 — idle → prompting → active → completed (or denied / 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),
@@ -22,7 +22,7 @@ Peer-dep: `react` ^18 || ^19.
 
 ## v1 stdlib catalog
 
-Seven hooks ship in v1, all with a shared `{ status, error, value | data | call }` shape:
+Seven hooks ship in v1, all with a shared `{ value, status, error?, start, stop? }` shape:
 
 | Hook                | Permission        | Description                                                  |
 | ------------------- | ----------------- | ------------------------------------------------------------ |
@@ -34,7 +34,7 @@ Seven hooks ship in v1, all with a shared `{ status, error, value | data | call
 | `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.
+The same list is exported from `@ggui-ai/protocol` as `STDLIB_GADGETS` and forms the structural floor of every app's `ggui_list_gadgets` catalog — operator-declared packages (`ggui.json#app.gadgets`) layer on top, winning on a package-name collision.
 
 ## How a contract uses these hooks
 
@@ -59,8 +59,8 @@ export const photoCaptureContract = defineContract({
     // `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.
+    // (`permission`, `example`, `gotchas`) are NOT on the wire; the
+    // server resolves them from `App.gadgets` at render time.
     gadgets: {
       "@ggui-ai/gadgets": {
         useCamera: {

package/dist/index.d.mts

@@ -10,11 +10,17 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  * {@link GadgetHook}. The factory:
  *
  *   1. Strictly validates the spec at call time via
- *      `strictGadgetDescriptorSchema` — non-empty teaching text
- *      (`description` / `usage` / `example`), at least one of
- *      `package` / `bundleUrl`, plus a non-function `hookImpl` check
- *      the schema can't see. Throws {@link WrapperConformanceError}
- *      with field-level paths on any violation.
+ *      `strictGadgetDescriptorSchema` — `package` (npm name) and a
+ *      pin-only semver `version` are REQUIRED on every descriptor,
+ *      teaching text (`description` / `usage` / `example`) is
+ *      REQUIRED and non-empty, URL fields (`bundleUrl` / `styleUrl` /
+ *      `typesUrl`) must be full URLs — plus a non-function `hookImpl`
+ *      check the schema can't see. Throws
+ *      {@link WrapperConformanceError} with field-level paths on any
+ *      violation. (`typesUrl` is not required HERE — at author time
+ *      the build hasn't emitted a `.d.ts` yet — but registration via
+ *      `registeredGadgetDescriptorSchema` requires it for every
+ *      non-stdlib package.)
  *   2. Returns the React hook function as the primary export, with
  *      the serializable {@link GadgetDescriptor} descriptor attached
  *      as `.descriptor`. Single export, dual purpose:
@@ -26,7 +32,8 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  *        usage: '...',
  *        example: { ... },
  *        package: '@my-org/ggui-leaflet',
- *        styleUrl: '/leaflet.css',
+ *        version: '0.1.0',
+ *        styleUrl: 'https://cdn.example.com/ggui-leaflet/leaflet.css',
  *        hookImpl: (options) => { …real React hook… },
  *      });
  *
@@ -56,8 +63,8 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  * Author input to {@link createGguiGadget}. A `createGguiGadget` call
  * builds a gadget PACKAGE that exposes exactly one HOOK export — so
  * the spec keeps the per-export teaching fields flat (`hook`,
- * `description`, `usage`, `example`, `gotchas`, `permission`,
- * `required`) alongside the package identity + transport fields
+ * `description`, `usage`, `example`, `gotchas`, `permission`)
+ * alongside the package identity + transport fields
  * (`package`, `version`, `bundleUrl`, …) and a `hookImpl` runtime
  * function. The factory assembles these into a
  * {@link GadgetDescriptor} of the package+exports shape.
@@ -190,8 +197,6 @@ interface GadgetExportTeaching {
     readonly gotchas?: string;
     /** Optional Web-Permissions identifier the export gates on. */
     readonly permission?: string;
-    /** Whether the UI MUST mount this export. Default `false`. */
-    readonly required?: boolean;
 }
 /** A hook export declaration — `use`-prefixed name + its impl. */
 interface GadgetHookExportSpec extends GadgetExportTeaching {
@@ -256,7 +261,7 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  * gadget catalog. The wire-side `DataContract.clientCapabilities.gadgets`
  * is intentionally narrow — it is package-keyed and carries identity
  * only (`(package, export name)`, no `version`, no transport
- * metadata), so push-time resolution looks up the matching
+ * metadata), so render-time resolution looks up the matching
  * {@link GadgetDescriptor} descriptor by npm package name. This module
  * declares the pluggable "where do descriptors come from?" port + ships
  * two batteries-included implementations:
@@ -267,8 +272,8 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *
  *   - {@link CachingGadgetCatalog} — decorator over any other adapter
  *     with per-appId TTL caching + single-flight deduplication. Right
- *     for production cloud paths where descriptors live in DynamoDB /
- *     a registry service and re-fetching on every push would burn
+ *     for production paths where descriptors live in a database /
+ *     a registry service and re-fetching on every render would burn
  *     network round-trips. Caches are scoped per-appId so two apps
  *     never see each other's catalogs.
  *
@@ -277,18 +282,18 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *   - One method: `list(appId)`. Single batch read — never an N+1
  *     "fetch descriptor for one package at a time" pattern. The
  *     resolution caller indexes the returned array by `package`
- *     itself. Single network call per push (with cache, often zero).
+ *     itself. Single network call per render (with cache, often zero).
  *
  *   - Return type is `readonly GadgetDescriptor[]` — the same shape the
- *     wire push-time resolution + downstream consumers (boilerplate
+ *     wire render-time resolution + downstream consumers (boilerplate
  *     generator, CSP builder, Permissions-Policy deriver, system
  *     prompt builder) already speak.
  *
  *   - Errors propagate. Adapters MUST throw on retrieval failure
  *     rather than returning an empty array — silent "no gadgets"
- *     would let pushes through with broken gadget refs and surface
+ *     would let renders through with broken gadget refs and surface
  *     as render-time hook-resolution failures. The caller's job is
- *     to decide whether the push fails (gate fires) or proceeds
+ *     to decide whether the render fails (gate fires) or proceeds
  *     ungated.
  *
  * ## Deployment-specific adapters
@@ -303,9 +308,9 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
 /**
  * Per-deployment source of registered gadget descriptors.
  *
- * Named parties: caller (push-time resolution / dev tools) ↔ adapter
- * (deployment-specific descriptor backing store, e.g., JSON, DynamoDB,
- * in-memory).
+ * Named parties: caller (render-time resolution / dev tools) ↔ adapter
+ * (deployment-specific descriptor backing store, e.g., JSON, a
+ * database, in-memory).
  *
  * Obligations:
  *   - `list(appId)` MUST return the full set of descriptors registered
@@ -315,7 +320,7 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *     returning `[]` is forbidden (it would mask broken catalogs).
  *
  * Failure mode: thrown error propagates to caller. Caller decides
- * whether to fail the push (strict) or fall back to a default set
+ * whether to fail the render (strict) or fall back to a default set
  * (lenient).
  *
  * Observable violation: caller observes a thrown error or a
@@ -349,8 +354,8 @@ declare class InMemoryGadgetCatalog implements GadgetCatalogAdapter {
 /**
  * Decorator adapter — wraps any {@link GadgetCatalogAdapter} with
  * per-appId TTL caching + single-flight deduplication. Right for
- * production paths where the inner adapter hits DynamoDB / a registry
- * service and per-push fetches would dominate latency.
+ * production paths where the inner adapter hits a database / a
+ * registry service and per-render fetches would dominate latency.
  *
  * Concurrent `list(appId)` calls during a cache miss share ONE
  * inflight Promise — no thundering herd against the inner adapter.
@@ -424,23 +429,23 @@ declare class CachingGadgetCatalog implements GadgetCatalogAdapter {
  *     without leaking the values themselves.
  *   - Pass `{ optional: true }` to get `undefined` for a missing key
  *     instead of throwing. Use when the wrapper has a sensible
- *     fallback (e.g., a default origin); the push gate enforces that
+ *     fallback (e.g., a default origin); the render gate enforces that
  *     declared `requires` keys are present, so the typical wrapper
  *     path uses the throwing default.
  *   - Empty-string values are returned verbatim (the operator may
  *     have intentionally configured a key with no value).
  *
- * The push gate (`assertPublicEnvSatisfied`) verifies the
+ * The render gate (`assertPublicEnvSatisfied`) verifies the
  * `App.publicEnv` satisfies every declared wrapper's `requires` BEFORE
  * the iframe boots. So in well-configured deployments, the only
  * `getPublicEnv` throws are gadget authoring bugs (typoed key, key
- * not declared in `requires`). In production, the push gate catches
+ * not declared in `requires`). In production, the render gate catches
  * the misconfiguration upstream.
  */
 interface GetPublicEnvOptions {
     /**
      * When true, returns `undefined` for a missing key instead of
-     * throwing. Use sparingly — the push gate enforces declared
+     * throwing. Use sparingly — the render gate enforces declared
      * `requires`, so a missing key usually indicates a wrapper bug
      * (key not in `requires` array). The throwing default is the
      * right call for keys that ARE declared in `requires`.
@@ -511,7 +516,8 @@ declare const useGeolocation: GadgetHook<GeolocationCoords, GeolocationOptions>;
  * the system clipboard via `navigator.clipboard.writeText`. Satisfies
  * `GadgetHook<string, ClipboardWriteOptions>`.
  *
- * One-shot semantics: call `start({text})` to write; status moves
+ * One-shot semantics: pass `{text}` at hook-call time and call
+ * `start()` to write; status moves
  * `idle → prompting → completed` on success or `idle → prompting →
  * denied/error` on failure. The hook's `value` carries the most
  * recently written text so component code can confirm what landed
@@ -523,7 +529,9 @@ declare const useGeolocation: GadgetHook<GeolocationCoords, GeolocationOptions>;
  */
 
 interface ClipboardWriteOptions {
-    /** Text to write. Required at call site, not at hook construction. */
+    /** Text to write. Supplied at hook-call time; read when `start()`
+     *  fires, so component code re-renders the hook call with the
+     *  latest text rather than passing arguments to `start()`. */
     readonly text: string;
 }
 declare const useClipboardWrite: GadgetHook<string, ClipboardWriteOptions>;

package/dist/index.d.ts

@@ -10,11 +10,17 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  * {@link GadgetHook}. The factory:
  *
  *   1. Strictly validates the spec at call time via
- *      `strictGadgetDescriptorSchema` — non-empty teaching text
- *      (`description` / `usage` / `example`), at least one of
- *      `package` / `bundleUrl`, plus a non-function `hookImpl` check
- *      the schema can't see. Throws {@link WrapperConformanceError}
- *      with field-level paths on any violation.
+ *      `strictGadgetDescriptorSchema` — `package` (npm name) and a
+ *      pin-only semver `version` are REQUIRED on every descriptor,
+ *      teaching text (`description` / `usage` / `example`) is
+ *      REQUIRED and non-empty, URL fields (`bundleUrl` / `styleUrl` /
+ *      `typesUrl`) must be full URLs — plus a non-function `hookImpl`
+ *      check the schema can't see. Throws
+ *      {@link WrapperConformanceError} with field-level paths on any
+ *      violation. (`typesUrl` is not required HERE — at author time
+ *      the build hasn't emitted a `.d.ts` yet — but registration via
+ *      `registeredGadgetDescriptorSchema` requires it for every
+ *      non-stdlib package.)
  *   2. Returns the React hook function as the primary export, with
  *      the serializable {@link GadgetDescriptor} descriptor attached
  *      as `.descriptor`. Single export, dual purpose:
@@ -26,7 +32,8 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  *        usage: '...',
  *        example: { ... },
  *        package: '@my-org/ggui-leaflet',
- *        styleUrl: '/leaflet.css',
+ *        version: '0.1.0',
+ *        styleUrl: 'https://cdn.example.com/ggui-leaflet/leaflet.css',
  *        hookImpl: (options) => { …real React hook… },
  *      });
  *
@@ -56,8 +63,8 @@ export { GadgetError, GadgetHook, GadgetStatus } from '@ggui-ai/protocol';
  * Author input to {@link createGguiGadget}. A `createGguiGadget` call
  * builds a gadget PACKAGE that exposes exactly one HOOK export — so
  * the spec keeps the per-export teaching fields flat (`hook`,
- * `description`, `usage`, `example`, `gotchas`, `permission`,
- * `required`) alongside the package identity + transport fields
+ * `description`, `usage`, `example`, `gotchas`, `permission`)
+ * alongside the package identity + transport fields
  * (`package`, `version`, `bundleUrl`, …) and a `hookImpl` runtime
  * function. The factory assembles these into a
  * {@link GadgetDescriptor} of the package+exports shape.
@@ -190,8 +197,6 @@ interface GadgetExportTeaching {
     readonly gotchas?: string;
     /** Optional Web-Permissions identifier the export gates on. */
     readonly permission?: string;
-    /** Whether the UI MUST mount this export. Default `false`. */
-    readonly required?: boolean;
 }
 /** A hook export declaration — `use`-prefixed name + its impl. */
 interface GadgetHookExportSpec extends GadgetExportTeaching {
@@ -256,7 +261,7 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  * gadget catalog. The wire-side `DataContract.clientCapabilities.gadgets`
  * is intentionally narrow — it is package-keyed and carries identity
  * only (`(package, export name)`, no `version`, no transport
- * metadata), so push-time resolution looks up the matching
+ * metadata), so render-time resolution looks up the matching
  * {@link GadgetDescriptor} descriptor by npm package name. This module
  * declares the pluggable "where do descriptors come from?" port + ships
  * two batteries-included implementations:
@@ -267,8 +272,8 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *
  *   - {@link CachingGadgetCatalog} — decorator over any other adapter
  *     with per-appId TTL caching + single-flight deduplication. Right
- *     for production cloud paths where descriptors live in DynamoDB /
- *     a registry service and re-fetching on every push would burn
+ *     for production paths where descriptors live in a database /
+ *     a registry service and re-fetching on every render would burn
  *     network round-trips. Caches are scoped per-appId so two apps
  *     never see each other's catalogs.
  *
@@ -277,18 +282,18 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *   - One method: `list(appId)`. Single batch read — never an N+1
  *     "fetch descriptor for one package at a time" pattern. The
  *     resolution caller indexes the returned array by `package`
- *     itself. Single network call per push (with cache, often zero).
+ *     itself. Single network call per render (with cache, often zero).
  *
  *   - Return type is `readonly GadgetDescriptor[]` — the same shape the
- *     wire push-time resolution + downstream consumers (boilerplate
+ *     wire render-time resolution + downstream consumers (boilerplate
  *     generator, CSP builder, Permissions-Policy deriver, system
  *     prompt builder) already speak.
  *
  *   - Errors propagate. Adapters MUST throw on retrieval failure
  *     rather than returning an empty array — silent "no gadgets"
- *     would let pushes through with broken gadget refs and surface
+ *     would let renders through with broken gadget refs and surface
  *     as render-time hook-resolution failures. The caller's job is
- *     to decide whether the push fails (gate fires) or proceeds
+ *     to decide whether the render fails (gate fires) or proceeds
  *     ungated.
  *
  * ## Deployment-specific adapters
@@ -303,9 +308,9 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
 /**
  * Per-deployment source of registered gadget descriptors.
  *
- * Named parties: caller (push-time resolution / dev tools) ↔ adapter
- * (deployment-specific descriptor backing store, e.g., JSON, DynamoDB,
- * in-memory).
+ * Named parties: caller (render-time resolution / dev tools) ↔ adapter
+ * (deployment-specific descriptor backing store, e.g., JSON, a
+ * database, in-memory).
  *
  * Obligations:
  *   - `list(appId)` MUST return the full set of descriptors registered
@@ -315,7 +320,7 @@ declare function defineGadgetPackage(spec: GadgetPackageSpec): GadgetDescriptor;
  *     returning `[]` is forbidden (it would mask broken catalogs).
  *
  * Failure mode: thrown error propagates to caller. Caller decides
- * whether to fail the push (strict) or fall back to a default set
+ * whether to fail the render (strict) or fall back to a default set
  * (lenient).
  *
  * Observable violation: caller observes a thrown error or a
@@ -349,8 +354,8 @@ declare class InMemoryGadgetCatalog implements GadgetCatalogAdapter {
 /**
  * Decorator adapter — wraps any {@link GadgetCatalogAdapter} with
  * per-appId TTL caching + single-flight deduplication. Right for
- * production paths where the inner adapter hits DynamoDB / a registry
- * service and per-push fetches would dominate latency.
+ * production paths where the inner adapter hits a database / a
+ * registry service and per-render fetches would dominate latency.
  *
  * Concurrent `list(appId)` calls during a cache miss share ONE
  * inflight Promise — no thundering herd against the inner adapter.
@@ -424,23 +429,23 @@ declare class CachingGadgetCatalog implements GadgetCatalogAdapter {
  *     without leaking the values themselves.
  *   - Pass `{ optional: true }` to get `undefined` for a missing key
  *     instead of throwing. Use when the wrapper has a sensible
- *     fallback (e.g., a default origin); the push gate enforces that
+ *     fallback (e.g., a default origin); the render gate enforces that
  *     declared `requires` keys are present, so the typical wrapper
  *     path uses the throwing default.
  *   - Empty-string values are returned verbatim (the operator may
  *     have intentionally configured a key with no value).
  *
- * The push gate (`assertPublicEnvSatisfied`) verifies the
+ * The render gate (`assertPublicEnvSatisfied`) verifies the
  * `App.publicEnv` satisfies every declared wrapper's `requires` BEFORE
  * the iframe boots. So in well-configured deployments, the only
  * `getPublicEnv` throws are gadget authoring bugs (typoed key, key
- * not declared in `requires`). In production, the push gate catches
+ * not declared in `requires`). In production, the render gate catches
  * the misconfiguration upstream.
  */
 interface GetPublicEnvOptions {
     /**
      * When true, returns `undefined` for a missing key instead of
-     * throwing. Use sparingly — the push gate enforces declared
+     * throwing. Use sparingly — the render gate enforces declared
      * `requires`, so a missing key usually indicates a wrapper bug
      * (key not in `requires` array). The throwing default is the
      * right call for keys that ARE declared in `requires`.
@@ -511,7 +516,8 @@ declare const useGeolocation: GadgetHook<GeolocationCoords, GeolocationOptions>;
  * the system clipboard via `navigator.clipboard.writeText`. Satisfies
  * `GadgetHook<string, ClipboardWriteOptions>`.
  *
- * One-shot semantics: call `start({text})` to write; status moves
+ * One-shot semantics: pass `{text}` at hook-call time and call
+ * `start()` to write; status moves
  * `idle → prompting → completed` on success or `idle → prompting →
  * denied/error` on failure. The hook's `value` carries the most
  * recently written text so component code can confirm what landed
@@ -523,7 +529,9 @@ declare const useGeolocation: GadgetHook<GeolocationCoords, GeolocationOptions>;
  */
 
 interface ClipboardWriteOptions {
-    /** Text to write. Required at call site, not at hook construction. */
+    /** Text to write. Supplied at hook-call time; read when `start()`
+     *  fires, so component code re-renders the hook call with the
+     *  latest text rather than passing arguments to `start()`. */
     readonly text: string;
 }
 declare const useClipboardWrite: GadgetHook<string, ClipboardWriteOptions>;

package/dist/index.js

@@ -59,7 +59,6 @@ function createGguiGadget(spec) {
     example,
     gotchas,
     permission,
-    required,
     ...packageFields
   } = spec;
   const violations = [];
@@ -75,8 +74,7 @@ function createGguiGadget(spec) {
     usage,
     example,
     ...gotchas !== void 0 ? { gotchas } : {},
-    ...permission !== void 0 ? { permission } : {},
-    ...required !== void 0 ? { required } : {}
+    ...permission !== void 0 ? { permission } : {}
   };
   const descriptorDraft = {
     ...packageFields,
@@ -131,8 +129,7 @@ function defineGadgetPackage(spec) {
       usage: entry.usage,
       example: entry.example,
       ...entry.gotchas !== void 0 ? { gotchas: entry.gotchas } : {},
-      ...entry.permission !== void 0 ? { permission: entry.permission } : {},
-      ...entry.required !== void 0 ? { required: entry.required } : {}
+      ...entry.permission !== void 0 ? { permission: entry.permission } : {}
     };
     return "hook" in entry ? { hook: entry.hook, ...teaching } : { component: entry.component, ...teaching };
   });
@@ -254,7 +251,7 @@ function getPublicEnv(key, opts, target = globalThis) {
   if (opts?.optional) return void 0;
   const available = Object.keys(env);
   throw new Error(
-    `getPublicEnv('${key}'): not provided in App.publicEnv. Available: [${available.join(", ") || "(none)"}]. Operators set this on the App record; gadget authors declare the key in 'requires' so the push gate verifies it before mount.`
+    `getPublicEnv('${key}'): not provided in App.publicEnv. Available: [${available.join(", ") || "(none)"}]. Operators set this on the App record; gadget authors declare the key in 'requires' so the render gate verifies it before mount.`
   );
 }
 

package/dist/index.mjs

@@ -23,7 +23,6 @@ function createGguiGadget(spec) {
     example,
     gotchas,
     permission,
-    required,
     ...packageFields
   } = spec;
   const violations = [];
@@ -39,8 +38,7 @@ function createGguiGadget(spec) {
     usage,
     example,
     ...gotchas !== void 0 ? { gotchas } : {},
-    ...permission !== void 0 ? { permission } : {},
-    ...required !== void 0 ? { required } : {}
+    ...permission !== void 0 ? { permission } : {}
   };
   const descriptorDraft = {
     ...packageFields,
@@ -97,8 +95,7 @@ function defineGadgetPackage(spec) {
       usage: entry.usage,
       example: entry.example,
       ...entry.gotchas !== void 0 ? { gotchas: entry.gotchas } : {},
-      ...entry.permission !== void 0 ? { permission: entry.permission } : {},
-      ...entry.required !== void 0 ? { required: entry.required } : {}
+      ...entry.permission !== void 0 ? { permission: entry.permission } : {}
     };
     return "hook" in entry ? { hook: entry.hook, ...teaching } : { component: entry.component, ...teaching };
   });
@@ -220,7 +217,7 @@ function getPublicEnv(key, opts, target = globalThis) {
   if (opts?.optional) return void 0;
   const available = Object.keys(env);
   throw new Error(
-    `getPublicEnv('${key}'): not provided in App.publicEnv. Available: [${available.join(", ") || "(none)"}]. Operators set this on the App record; gadget authors declare the key in 'requires' so the push gate verifies it before mount.`
+    `getPublicEnv('${key}'): not provided in App.publicEnv. Available: [${available.join(", ") || "(none)"}]. Operators set this on the App record; gadget authors declare the key in 'requires' so the render gate verifies it before mount.`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/gadgets",
-  "version": "0.2.0-alpha.4",
+  "version": "0.4.0-rc.0",
   "description": "Browser-capability gadget hooks for ggui — declared via DataContract.clientCapabilities.gadgets, mounted by the UI generator's component code.",
   "license": "Apache-2.0",
   "keywords": [
@@ -57,10 +57,10 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^3.2.6"
   },
   "dependencies": {
-    "@ggui-ai/protocol": "0.2.0-alpha.4"
+    "@ggui-ai/protocol": "0.4.0-rc.0"
   },
   "engines": {
     "node": ">=20.0.0"