@ggui-ai/protocol 0.2.0-alpha.3 → 0.3.0-rc.0

package/README.md

@@ -1,6 +1,6 @@
 # @ggui-ai/protocol
 
-TypeScript source of truth for the ggui protocol — the open wire format between agents and generated user interfaces. Ships the envelope types (`ActionEnvelope`, `StreamEnvelope`, `ContractErrorPayload`), the canonical error-code union, the WebSocket + MCP transport bindings, and the DTCG design-token contract.
+TypeScript source of truth for the ggui protocol — the open wire format between agents and generated user interfaces. Ships the envelope types (`ActionEnvelope`, `StreamEnvelope`), the canonical error-frame codes, the WebSocket + MCP transport bindings, and the DTCG design-token contract.
 
 The full normative spec lives at [docs.ggui.ai](https://docs.ggui.ai). This package is what an implementer actually imports.
 
@@ -17,13 +17,13 @@ Here is what happens when a user clicks "Add" on a generated todo UI:
 1. **LLM wrote the hook** — `const addTodo = useAction('addTodo');` bound to the button's `onClick`.
 2. **User clicks** — React fires `onClick`, which calls `addTodo(data)`.
 3. **Hook dispatches** — `useAction` (from `@ggui-ai/wire`) sends an `ActionEnvelope` on the live channel.
-4. **WS transport** — the server receives the envelope on the render's live-channel WebSocket.
-5. **Router looks up the tool** — `wiredActionRouter` reads `actionSpec.addTodo.nextStep === 'todo.add'`.
-6. **MCP tool invoked** — the router calls `todo.add` with the validated payload.
-7. **Tool responds** — `todo.add` returns; the response travels back as a `StreamEnvelope` on the live channel.
-8. **UI absorbs the update** — the component's `useStream` callback fires, state updates, no regeneration.
+4. **WS transport** — the server receives the envelope on the GguiSession's live-channel WebSocket.
+5. **Server persists a consume event** — the validated envelope is appended to the session's event ledger, stamped with an advisory `tool` hint derived server-side from `actionSpec.addTodo.nextStep === 'todo.add'`.
+6. **Agent consumes** — the agent drains the event via `ggui_consume` on its next turn and calls `todo.add` itself. Actions drive agent turns; no client-side tool dispatch.
+7. **Agent pushes the update** — the agent's update travels back to the UI on the live channel (`props_update`, or a `StreamEnvelope` on a declared stream channel).
+8. **UI absorbs the update** — props or the component's `useStream` callback update state, no regeneration.
 
-**No SDK glue.** Every step has a named, typed enforcement layer — schema-subset check at push time, `ContractErrorPayload` on `_ggui:contract-error` at runtime, `@ggui-ai/protocol-conformance` at CI time, TypeScript narrowing at author time. Nothing about this pipeline assumes a specific SDK: a third-party implementer honoring the envelope + channel contracts inherits all four enforcement tiers for free.
+**No SDK glue.** Every step has a named, typed enforcement layer — schema-subset check at push time, `CONTRACT_VIOLATION` error frames on the live channel at runtime, `@ggui-ai/protocol-conformance` at CI time, TypeScript narrowing at author time. Nothing about this pipeline assumes a specific SDK: a third-party implementer honoring the envelope + channel contracts inherits all four enforcement tiers for free.
 
 ## Implementer guide
 
@@ -31,15 +31,15 @@ Building a third-party MCP host that renders ggui UIs, a non-React viewer, or an
 
 ## What this package exports
 
-| Surface                                     | What it is                                                       |
-| ------------------------------------------- | ---------------------------------------------------------------- |
-| `@ggui-ai/protocol`                         | Root barrel — envelope types, `Render`, `StreamSpec`, actions    |
-| `@ggui-ai/protocol/content-hash`            | Deterministic hashing for cache keys                             |
-| `@ggui-ai/protocol/blueprint-key`           | Server-only blueprint cache-key derivation (uses `node:crypto`)  |
-| `@ggui-ai/protocol/transport/websocket`     | Live-channel WS binding — subscribe / ack / resume types         |
-| `@ggui-ai/protocol/integrations/mcp-apps`   | MCP Apps host integration types — bootstrap + lifecycle protocol |
-| `@ggui-ai/protocol/version`                 | Protocol version constant + negotiation helpers                  |
-| `@ggui-ai/protocol/errors/version-mismatch` | Typed error for version-negotiation failures                     |
+| Surface                                     | What it is                                                         |
+| ------------------------------------------- | ------------------------------------------------------------------ |
+| `@ggui-ai/protocol`                         | Root barrel — envelope types, `GguiSession`, `StreamSpec`, actions |
+| `@ggui-ai/protocol/content-hash`            | Deterministic hashing for cache keys                               |
+| `@ggui-ai/protocol/blueprint-key`           | Server-only blueprint cache-key derivation (uses `node:crypto`)    |
+| `@ggui-ai/protocol/transport/websocket`     | Live-channel WS binding — subscribe / ack / resume types           |
+| `@ggui-ai/protocol/integrations/mcp-apps`   | MCP Apps host integration types — bootstrap + lifecycle protocol   |
+| `@ggui-ai/protocol/version`                 | Protocol version constant + negotiation helpers                    |
+| `@ggui-ai/protocol/errors/version-mismatch` | Typed error for version-negotiation failures                       |
 
 ## License
 

package/dist/envelope-adapters.d.ts

@@ -7,15 +7,16 @@
  *
  * The only bounded adapter that lives here now is
  * {@link parsePendingEnvelope} — a shape-neutral reader for stored
- * `PendingEvent.envelope` values that may arrive as raw objects (direct
- * DDB writes) or as JSON strings (AppSync `a.json()` semantics).
+ * `PendingEvent.envelope` values that may arrive as raw objects or as
+ * JSON strings, depending on how the deployment's storage layer
+ * serializes rows.
  */
 import type { ConsumeEventEntry } from './types/mcp';
 /**
  * Parse a {@link PendingEvent.envelope} that may arrive as either a raw
- * object (direct DDB writes) or a JSON-stringified object (AppSync
- * `a.json()` semantics). Returns the parsed entry unchanged when
- * already an object.
+ * object or a JSON-stringified object, depending on how the
+ * deployment's storage layer serializes rows. Returns the parsed entry
+ * unchanged when already an object.
  *
  * Throws `SyntaxError` when a string input is malformed JSON. Does NOT
  * validate the entry shape — that's the caller's job.

package/dist/envelope-adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope-adapters.d.ts","sourceRoot":"","sources":["../src/envelope-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GACjC,iBAAiB,CAGnB"}
+{"version":3,"file":"envelope-adapters.d.ts","sourceRoot":"","sources":["../src/envelope-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GACjC,iBAAiB,CAGnB"}

package/dist/envelope-adapters.js

@@ -1,8 +1,8 @@
 /**
  * Parse a {@link PendingEvent.envelope} that may arrive as either a raw
- * object (direct DDB writes) or a JSON-stringified object (AppSync
- * `a.json()` semantics). Returns the parsed entry unchanged when
- * already an object.
+ * object or a JSON-stringified object, depending on how the
+ * deployment's storage layer serializes rows. Returns the parsed entry
+ * unchanged when already an object.
  *
  * Throws `SyntaxError` when a string input is malformed JSON. Does NOT
  * validate the entry shape — that's the caller's job.

package/dist/envelopes/builders.d.ts

@@ -4,8 +4,8 @@
  *
  * **Why centralize.** The `schemaVersion` forward-compat stamp is
  * emitted from many producer sites (wire helper, React-SDK emit
- * paths, OSS in-memory stream buffer, session-channel contract-error
- * router, hosted server paths). Spreading stamp logic across N sites
+ * paths, OSS in-memory stream buffer, hosted server paths).
+ * Spreading stamp logic across N sites
  * causes drift — producers silently skip the stamp. These builders
  * remove the drift surface by giving every producer a single function
  * to call; the default stamp happens inside the builder.
@@ -46,10 +46,10 @@
  */
 import type { ActionEnvelope, EventType } from '../types/events.js';
 import type { ErrorPayload, StreamEnvelope } from '../types/live-channel.js';
-import type { ContractErrorCode, ContractErrorPayload, JsonValue, StreamChannelMode } from '../types/data-contract.js';
+import type { JsonValue, StreamChannelMode } from '../types/data-contract.js';
 /** Input type for {@link makeActionEnvelope}. */
 export interface MakeActionEnvelopeInput<TPayload = JsonValue> {
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly type: EventType;
     readonly payload?: TPayload;
     readonly clientSeq?: number;
@@ -63,7 +63,7 @@ export interface MakeActionEnvelopeInput<TPayload = JsonValue> {
 }
 /** Input type for {@link makeStreamEnvelope}. */
 export interface MakeStreamEnvelopeInput {
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly channel: string;
     readonly mode: StreamChannelMode;
     readonly payload: JsonValue;
@@ -78,23 +78,6 @@ export interface MakeErrorPayloadInput {
     readonly message: string;
     readonly details?: JsonValue;
 }
-/** Input type for {@link makeContractErrorPayload}. */
-export interface MakeContractErrorPayloadInput {
-    readonly toolName: string;
-    readonly actionName?: string;
-    readonly sourceAction?: {
-        readonly type: 'wired-action' | 'refresh-stream' | (string & {});
-        readonly dispatchedAt: string;
-    };
-    readonly error: {
-        readonly code: ContractErrorCode;
-        readonly message: string;
-        readonly causedBy?: string;
-    };
-    readonly timestamp: string;
-    /** See {@link MakeActionEnvelopeInput.schemaVersion}. */
-    readonly schemaVersion?: string;
-}
 /**
  * Build an {@link ActionEnvelope} with `schemaVersion` stamped to
  * {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
@@ -119,7 +102,7 @@ export declare function makeStreamEnvelope(parts: MakeStreamEnvelopeInput): Stre
  * Does NOT stamp `schemaVersion` — `ErrorPayload` is the wire-level
  * error envelope (free-form `code: string`), not an envelope that
  * opts into the forward-compat stamp (see {@link ActionEnvelope} /
- * {@link StreamEnvelope} / {@link ContractErrorPayload}). Keeping
+ * {@link StreamEnvelope}). Keeping
  * `ErrorPayload` stamp-free preserves byte-equivalence with every
  * existing server-side error emission that pre-dates the central
  * builders.
@@ -131,13 +114,4 @@ export declare function makeStreamEnvelope(parts: MakeStreamEnvelopeInput): Stre
  * pre-builder `{code, message}` shape byte-for-byte.
  */
 export declare function makeErrorPayload(parts: MakeErrorPayloadInput): ErrorPayload;
-/**
- * Build a {@link ContractErrorPayload} with `schemaVersion` stamped
- * to {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
- *
- * Filters `undefined` optional fields so the emitted payload keeps
- * byte-equivalence with the pre-refactor session-channel router
- * code.
- */
-export declare function makeContractErrorPayload(parts: MakeContractErrorPayloadInput): ContractErrorPayload;
 //# sourceMappingURL=builders.d.ts.map

package/dist/envelopes/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/envelopes/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAGnC,iDAAiD;AACjD,MAAM,WAAW,uBAAuB,CAAC,QAAQ,GAAG,SAAS;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,SAAS,EACrD,KAAK,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GACvC,cAAc,CAAC,QAAQ,CAAC,CAU1B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,cAAc,CAYhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,oBAAoB,CAatB"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/envelopes/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9E,iDAAiD;AACjD,MAAM,WAAW,uBAAuB,CAAC,QAAQ,GAAG,SAAS;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAmBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,SAAS,EACrD,KAAK,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GACvC,cAAc,CAAC,QAAQ,CAAC,CAU1B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,cAAc,CAYhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAO3E"}

package/dist/envelopes/builders.js

@@ -23,7 +23,7 @@ function resolveSchemaVersion(parts) {
  */
 export function makeActionEnvelope(parts) {
     const envelope = {
-        renderId: parts.renderId,
+        sessionId: parts.sessionId,
         type: parts.type,
     };
     if (parts.payload !== undefined)
@@ -45,7 +45,7 @@ export function makeActionEnvelope(parts) {
  */
 export function makeStreamEnvelope(parts) {
     const envelope = {
-        renderId: parts.renderId,
+        sessionId: parts.sessionId,
         channel: parts.channel,
         mode: parts.mode,
         payload: parts.payload,
@@ -65,7 +65,7 @@ export function makeStreamEnvelope(parts) {
  * Does NOT stamp `schemaVersion` — `ErrorPayload` is the wire-level
  * error envelope (free-form `code: string`), not an envelope that
  * opts into the forward-compat stamp (see {@link ActionEnvelope} /
- * {@link StreamEnvelope} / {@link ContractErrorPayload}). Keeping
+ * {@link StreamEnvelope}). Keeping
  * `ErrorPayload` stamp-free preserves byte-equivalence with every
  * existing server-side error emission that pre-dates the central
  * builders.
@@ -85,25 +85,3 @@ export function makeErrorPayload(parts) {
         payload.details = parts.details;
     return payload;
 }
-/**
- * Build a {@link ContractErrorPayload} with `schemaVersion` stamped
- * to {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
- *
- * Filters `undefined` optional fields so the emitted payload keeps
- * byte-equivalence with the pre-refactor session-channel router
- * code.
- */
-export function makeContractErrorPayload(parts) {
-    const stamp = resolveSchemaVersion(parts);
-    const payload = {
-        toolName: parts.toolName,
-        error: parts.error,
-        timestamp: parts.timestamp,
-        ...(parts.actionName !== undefined ? { actionName: parts.actionName } : {}),
-        ...(parts.sourceAction !== undefined
-            ? { sourceAction: parts.sourceAction }
-            : {}),
-        ...(stamp !== undefined ? { schemaVersion: stamp } : {}),
-    };
-    return payload;
-}

package/dist/errors/version-mismatch.d.ts

@@ -13,7 +13,7 @@
  *   - Client side: on ack receipt, `AckPayload.serverVersion` is
  *     present AND NOT in `CLIENT_SUPPORTED_VERSIONS`. The client
  *     instantiates this class and surfaces it to the caller via the
- *     session's `onError` hook.
+ *     render's `onError` hook.
  *
  * The class pins `.name === 'UpgradeRequiredError'` and `.code ===
  * UPGRADE_REQUIRED` so consumers can pattern-match without

package/dist/errors/version-mismatch.js

@@ -13,7 +13,7 @@
  *   - Client side: on ack receipt, `AckPayload.serverVersion` is
  *     present AND NOT in `CLIENT_SUPPORTED_VERSIONS`. The client
  *     instantiates this class and surfaces it to the caller via the
- *     session's `onError` hook.
+ *     render's `onError` hook.
  *
  * The class pins `.name === 'UpgradeRequiredError'` and `.code ===
  * UPGRADE_REQUIRED` so consumers can pattern-match without

package/dist/gadgets/resolve-app-gadgets.d.ts

@@ -0,0 +1,10 @@
+import type { GadgetDescriptor } from '../types/data-contract';
+/**
+ * Resolve an app's effective gadget set: the first-party stdlib package is the
+ * structural FLOOR, and `declared` (app-declared extensions) layers on top.
+ * Replaces the legacy fallback-when-absent resolution that dropped the stdlib
+ * package the moment an app declared any extension. `declared` wins on a
+ * `package` collision; absent/empty ⇒ exactly the stdlib set; idempotent.
+ */
+export declare function resolveAppGadgets(declared?: readonly GadgetDescriptor[] | null): readonly GadgetDescriptor[];
+//# sourceMappingURL=resolve-app-gadgets.d.ts.map

package/dist/gadgets/resolve-app-gadgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-app-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/resolve-app-gadgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,GAC5C,SAAS,gBAAgB,EAAE,CAG7B"}

package/dist/gadgets/resolve-app-gadgets.js

@@ -0,0 +1,19 @@
+import { STDLIB_GADGETS } from './stdlib-gadgets.js';
+function dedupeByPackage(list) {
+    const m = new Map();
+    for (const g of list)
+        m.set(g.package, g);
+    return [...m.values()];
+}
+/**
+ * Resolve an app's effective gadget set: the first-party stdlib package is the
+ * structural FLOOR, and `declared` (app-declared extensions) layers on top.
+ * Replaces the legacy fallback-when-absent resolution that dropped the stdlib
+ * package the moment an app declared any extension. `declared` wins on a
+ * `package` collision; absent/empty ⇒ exactly the stdlib set; idempotent.
+ */
+export function resolveAppGadgets(declared) {
+    if (!declared || declared.length === 0)
+        return STDLIB_GADGETS;
+    return dedupeByPackage([...STDLIB_GADGETS, ...declared]);
+}

package/dist/gadgets/resolve-contract-gadgets.d.ts

@@ -6,7 +6,7 @@
  * It carries identity only — `(package, export name)` — never
  * `version` or transport metadata. The operator's `App.gadgets`
  * catalog owns those; `filterDescriptorsToContract` snapshots the
- * referenced subset onto `SessionStackEntry.gadgetDescriptors` as a
+ * referenced subset onto `ComponentGguiSession.gadgetDescriptors` as a
  * sidecar.
  */
 import type { DataContract, GadgetDescriptor, GadgetExport, GadgetUse } from '../types/data-contract.js';
@@ -34,7 +34,7 @@ export declare function gadgetExportName(x: GadgetExport): string;
  * Canonical string key for a gadget EXPORT's identity —
  * `(name, package)`. Every site that decides "does this wire ref
  * resolve to that registered export?" MUST key through this helper so
- * the resolver and the push-time gates (`assertGadgetsRegistered`,
+ * the resolver and the render-time gates (`assertGadgetsRegistered`,
  * `assertPublicEnvSatisfied`) agree byte-for-byte on what "the same
  * gadget export" means.
  *
@@ -59,7 +59,7 @@ export declare function gadgetIdentityKey(use: {
 /**
  * Flatten the package-keyed `contract.clientCapabilities.gadgets` into
  * a list of `(package, name)` use records — one per export the
- * contract references. The single accessor every consumer (push
+ * contract references. The single accessor every consumer (render
  * gates, descriptor resolver, code-gen) iterates, so the nested wire
  * shape is walked in exactly one place.
  *
@@ -76,12 +76,12 @@ export declare function listContractGadgets(contract: DataContract): readonly Ga
  * descriptor IS a package, and `App.gadgets` registers at most one
  * descriptor per package, so a package key resolves to exactly one
  * descriptor. The filtered list lands as a sidecar on
- * `SessionStackEntry.gadgetDescriptors`.
+ * `ComponentGguiSession.gadgetDescriptors`.
  *
  * Ordering: descriptors appear in the order their package key first
  * appears on `clientCapabilities.gadgets`. A package absent from
- * `appGadgets` is dropped — the push-time `assertGadgetsRegistered`
- * gate rejects the push with a precise registration-mismatch code
+ * `appGadgets` is dropped — the render-time `assertGadgetsRegistered`
+ * gate rejects the render with a precise registration-mismatch code
  * BEFORE this helper runs, so silent drop here is safe in the happy
  * path.
  *

package/dist/gadgets/resolve-contract-gadgets.js

@@ -28,7 +28,7 @@ export function gadgetExportName(x) {
  * Canonical string key for a gadget EXPORT's identity —
  * `(name, package)`. Every site that decides "does this wire ref
  * resolve to that registered export?" MUST key through this helper so
- * the resolver and the push-time gates (`assertGadgetsRegistered`,
+ * the resolver and the render-time gates (`assertGadgetsRegistered`,
  * `assertPublicEnvSatisfied`) agree byte-for-byte on what "the same
  * gadget export" means.
  *
@@ -52,7 +52,7 @@ export function gadgetIdentityKey(use) {
 /**
  * Flatten the package-keyed `contract.clientCapabilities.gadgets` into
  * a list of `(package, name)` use records — one per export the
- * contract references. The single accessor every consumer (push
+ * contract references. The single accessor every consumer (render
  * gates, descriptor resolver, code-gen) iterates, so the nested wire
  * shape is walked in exactly one place.
  *
@@ -87,12 +87,12 @@ export function listContractGadgets(contract) {
  * descriptor IS a package, and `App.gadgets` registers at most one
  * descriptor per package, so a package key resolves to exactly one
  * descriptor. The filtered list lands as a sidecar on
- * `SessionStackEntry.gadgetDescriptors`.
+ * `ComponentGguiSession.gadgetDescriptors`.
  *
  * Ordering: descriptors appear in the order their package key first
  * appears on `clientCapabilities.gadgets`. A package absent from
- * `appGadgets` is dropped — the push-time `assertGadgetsRegistered`
- * gate rejects the push with a precise registration-mismatch code
+ * `appGadgets` is dropped — the render-time `assertGadgetsRegistered`
+ * gate rejects the render with a precise registration-mismatch code
  * BEFORE this helper runs, so silent drop here is safe in the happy
  * path.
  *

package/dist/gadgets/stdlib-gadgets.d.ts

@@ -12,7 +12,7 @@ export declare const STDLIB_GADGETS_PACKAGE = "@ggui-ai/gadgets";
  * in `@ggui-ai/gadgets` asserts the two stay in sync, so a release-time
  * bump to the runtime package without updating this constant fails CI.
  */
-export declare const STDLIB_GADGETS_VERSION = "0.1.0-rc.3";
+export declare const STDLIB_GADGETS_VERSION = "0.3.0";
 /**
  * v1 catalog of stdlib gadget descriptors. Every entry's
  * `package` defaults to {@link STDLIB_GADGETS_PACKAGE}; the

package/dist/gadgets/stdlib-gadgets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdlib-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/stdlib-gadgets.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EA+F/D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAUnD,CAAC"}
+{"version":3,"file":"stdlib-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/stdlib-gadgets.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAkH/D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAUnD,CAAC"}

package/dist/gadgets/stdlib-gadgets.js

@@ -21,9 +21,11 @@
 // **Parity guarantee:** `@ggui-ai/gadgets` ships a cross-
 // package contract test (`stdlib-parity.test.ts`) that imports both
 // this list and the actual hook exports, then asserts the hook names
-// match exactly. Drift fails the test on CI; the protocol package
-// cannot ship a stale descriptor list without the runtime side
-// catching it.
+// match exactly AND that every `example` block sticks to the real
+// `GadgetHook` contract (statuses from the `GadgetStatus` union,
+// `start()`/`stop()` as the only invokable methods). Drift fails the
+// test on CI; the protocol package cannot ship a stale descriptor
+// list without the runtime side catching it.
 /**
  * The first-party `@ggui-ai/gadgets` package name. Used as
  * the default `package` for every entry in {@link STDLIB_GADGETS}
@@ -37,7 +39,7 @@ export const STDLIB_GADGETS_PACKAGE = '@ggui-ai/gadgets';
  * in `@ggui-ai/gadgets` asserts the two stay in sync, so a release-time
  * bump to the runtime package without updating this constant fails CI.
  */
-export const STDLIB_GADGETS_VERSION = '0.1.0-rc.3';
+export const STDLIB_GADGETS_VERSION = '0.3.0';
 /**
  * v1 catalog of stdlib gadget descriptors. Every entry's
  * `package` defaults to {@link STDLIB_GADGETS_PACKAGE}; the
@@ -66,10 +68,15 @@ export const STDLIB_GADGETS = [
                 description: 'Capture stills or live video from the device camera.',
                 usage: 'Mount when the intent names photo capture, QR / barcode scanning, video recording, or anything that requires a camera feed. The hook returns a stream once `start()` resolves; thread the resulting blob or stream URL into a contextSpec slot or an actionSpec payload to surface it to the agent.',
                 example: {
-                    call: 'const cam = useCamera();',
+                    call: "const cam = useCamera({ facingMode: 'environment' }); // on button click: await cam.start()",
                     returns: {
-                        status: 'ready',
-                        value: { stream: '<MediaStream>', kind: 'video' },
+                        status: 'completed',
+                        value: {
+                            dataUrl: 'data:image/png;base64,…',
+                            width: 640,
+                            height: 480,
+                            mimeType: 'image/png',
+                        },
                     },
                 },
             },
@@ -79,8 +86,8 @@ export const STDLIB_GADGETS = [
                 description: 'Read the system clipboard contents on user gesture.',
                 usage: 'Mount when the intent involves importing copied content (paste-into-form, paste-image-to-upload, paste-link). The Permissions API requires a user gesture; gate `start()` behind a button click. Returned value lands in a contextSpec slot or an actionSpec payload.',
                 example: {
-                    call: 'const paste = useClipboardPaste();',
-                    returns: { status: 'ready', value: 'pasted clipboard text' },
+                    call: 'const paste = useClipboardPaste(); // on button click: await paste.start()',
+                    returns: { status: 'completed', value: 'pasted clipboard text' },
                 },
             },
             {
@@ -89,8 +96,8 @@ export const STDLIB_GADGETS = [
                 description: 'Write to the system clipboard on user gesture.',
                 usage: 'Mount when the intent includes copying generated text, share links, codes, or transcripts to the system clipboard. Fire an actionSpec event so the agent observes the act (it does not see the written value — that stays component-local).',
                 example: {
-                    call: "const write = useClipboardWrite(); write.write('hello');",
-                    returns: { status: 'ready' },
+                    call: "const write = useClipboardWrite({ text: 'hello' }); // on button click: await write.start()",
+                    returns: { status: 'completed', value: 'hello' },
                 },
             },
             {
@@ -98,10 +105,19 @@ export const STDLIB_GADGETS = [
                 description: 'Open the native file picker and read selected files.',
                 usage: 'Mount when the intent names file upload, attachment selection, or document import. No permission required. The hook returns the picked files plus metadata; thread file refs / data URLs into a contextSpec slot or actionSpec payload.',
                 example: {
-                    call: 'const picker = useFilePicker({ accept: "image/*" });',
+                    call: "const picker = useFilePicker({ accept: 'image/*' }); // on button click: await picker.start()",
                     returns: {
-                        status: 'ready',
-                        value: [{ name: 'photo.png', type: 'image/png', size: 12345 }],
+                        status: 'completed',
+                        value: {
+                            files: [
+                                {
+                                    name: 'photo.png',
+                                    type: 'image/png',
+                                    size: 12345,
+                                    _file: '<File>',
+                                },
+                            ],
+                        },
                     },
                 },
             },
@@ -111,10 +127,15 @@ export const STDLIB_GADGETS = [
                 description: "Resolve the device's current geolocation.",
                 usage: 'Mount when the intent names "current location", maps, nearby search, location-aware UI. Browser prompts the user on `start()`; the hook returns coordinates once granted. Thread the resolved coords into a contextSpec slot so the agent observes the latest fix.',
                 example: {
-                    call: 'const geo = useGeolocation();',
+                    call: 'const geo = useGeolocation(); // on button click: await geo.start()',
                     returns: {
-                        status: 'ready',
-                        value: { latitude: 37.7749, longitude: -122.4194, accuracy: 20 },
+                        status: 'completed',
+                        value: {
+                            latitude: 37.7749,
+                            longitude: -122.4194,
+                            accuracy: 20,
+                            timestamp: 1718000000000,
+                        },
                     },
                 },
             },
@@ -124,10 +145,10 @@ export const STDLIB_GADGETS = [
                 description: 'Capture audio from the device microphone.',
                 usage: 'Mount when the intent names voice memos, audio messages, dictation, voice-driven UI. Returns an audio stream / blob; thread it into an actionSpec payload at recording-stop, or into a contextSpec slot for live transcription pipelines.',
                 example: {
-                    call: 'const mic = useMicrophone();',
+                    call: 'const mic = useMicrophone(); // record on click: await mic.start(); end with mic.stop()',
                     returns: {
-                        status: 'ready',
-                        value: { stream: '<MediaStream>', kind: 'audio' },
+                        status: 'completed',
+                        value: { blob: '<Blob>', durationMs: 4200, mimeType: 'audio/webm' },
                     },
                 },
             },
@@ -137,8 +158,8 @@ export const STDLIB_GADGETS = [
                 description: 'Show system / browser notifications to the user.',
                 usage: 'Mount when the intent involves alerting the user about something (reminders, completion of long tasks, incoming messages) and the UI may be in the background. Permission is prompted on first `start()`; the agent does NOT see notification dismissal directly — surface it via an actionSpec if needed.',
                 example: {
-                    call: "const notify = useNotifications(); notify.show({ title: 'Done' });",
-                    returns: { status: 'ready', value: { granted: true } },
+                    call: "const notify = useNotifications({ title: 'Done' }); // after the task completes: await notify.start()",
+                    returns: { status: 'completed', value: { outcome: 'closed' } },
                 },
             },
         ],

package/dist/iframe-bridge.d.ts

@@ -4,32 +4,16 @@
  * Events prefixed with `ggui-` are `postMessage` types (cross-origin iframe boundary).
  * Events prefixed with `ggui:` are `CustomEvent` names (same-origin, dispatched on `window`).
  *
- * The bridge has three directions:
- * 1. **Agent to Component** (inbound): data, streams, progress
- * 2. **Component to Agent** (outbound): user interactions (form submits, clicks)
- * 3. **Component to Host** (outbound): rendering lifecycle (resize, success, error)
+ * The bridge is one-directional: **Agent to Component** (inbound) data
+ * deliveries. Outbound user interaction does NOT travel over this bridge —
+ * generated components emit canonical `data:submit` ActionEnvelopes via the
+ * wire-config action hooks (`useAction`) over the live channel.
  */
 export declare const BRIDGE_EVENTS: {
     /** `postMessage` type for parent-to-iframe data delivery. The parent window posts this type; the iframe bridge script converts it to an `AGENT_DATA` CustomEvent. */
     readonly AGENT_DATA_POST: "ggui-agent-data";
     /** `CustomEvent` name dispatched on `window` when agent data arrives. Components listen for this to receive real-time data from the agent (chat messages, typing indicators, etc.). */
     readonly AGENT_DATA: "ggui:agent-data";
-    /** `CustomEvent` name for streaming text chunks from the agent. Fired incrementally as the agent generates a response. */
-    readonly AGENT_STREAM: "ggui:agent-stream";
-    /** `CustomEvent` name for agent messages. Payload includes `type: 'thinking' | 'chat'`. Thinking messages show what the agent is doing; chat messages are final responses. */
-    readonly AGENT_MSG: "ggui:agent-msg";
-    /** `CustomEvent` name for UI generation log updates. Debug/devtools only — not displayed to end users. */
-    readonly AGENT_LOGS: "ggui:logs";
-    /** `postMessage` type for iframe-to-parent user interaction data. Carries form submissions and click events from generated components back to the host. */
-    readonly USER_DATA_POST: "ggui-user-data";
-    /** `CustomEvent` name dispatched on the parent window when user data arrives from the iframe. The host shell listens for this to forward events to the agent. */
-    readonly USER_DATA: "ggui:user-data";
-    /** `postMessage` type sent when a component's content size changes. Used by the host to auto-resize the iframe to fit content. */
-    readonly RESIZE: "ggui-resize";
-    /** `postMessage` type sent when a component renders successfully. The host uses this to hide loading indicators and show the component. */
-    readonly RENDER_SUCCESS: "ggui-render-success";
-    /** `postMessage` type sent when a component fails to render. The host uses this to show an error state instead of a blank iframe. */
-    readonly RENDER_ERROR: "ggui-render-error";
 };
 /**
  * Srcdoc JS snippet: bridge agent data postMessages into CustomEvents inside iframe.
@@ -37,27 +21,4 @@ export declare const BRIDGE_EVENTS: {
  * events when the parent forwards data via postMessage.
  */
 export declare const SRCDOC_AGENT_DATA_BRIDGE = "\n  window.addEventListener(\"message\", function(event) {\n    if (event.data && event.data.type === \"ggui-agent-data\") {\n      window.dispatchEvent(new CustomEvent(\"ggui:agent-data\", { detail: event.data.payload }));\n    }\n  });";
-/**
- * Srcdoc JS snippet: auto-report content height changes to parent.
- *
- * Uses a ResizeObserver on <html> to detect layout changes and posts
- * a `ggui-resize` message with the current scrollHeight. Also fires
- * an initial measurement on the next animation frame after injection.
- *
- * Inject this into any srcdoc or rendered page <script> so the parent
- * can auto-size the iframe to fit content without scrollbars.
- */
-export declare const SRCDOC_RESIZE_BRIDGE: string;
-/**
- * Srcdoc JS snippet: universal interaction bridge inside iframe.
- *
- * Three layers of automatic event capture (no props.onSubmit needed):
- *   1. Form submit intercept — captures <form> submissions with all field data
- *   2. Interactive element clicks — buttons, [role="button"], links, [data-action]
- *   3. Cursor-pointer fallback (approach C) — any styled-clickable div/span/card
- *
- * All layers skip if props.onSubmit already handled the event (__ggui_submitHandled).
- * Click handler uses bubble phase so component handlers run first.
- */
-export declare const SRCDOC_USER_DATA_BRIDGE = "\n  // Dedup: props.onSubmit sets __ggui_submitHandled = true synchronously.\n  // Both layers check this. We use a microtask to reset it so it stays\n  // true for ALL handlers in the same event cycle (click + submit).\n  function __ggui_wasHandled() {\n    if (!window.__ggui_submitHandled) return false;\n    // Reset via microtask \u2014 stays true for all sync handlers in this tick\n    Promise.resolve().then(function() { window.__ggui_submitHandled = false; });\n    return true;\n  }\n\n  // Layer 1: Form submit intercept (bubble phase \u2014 lets component onSubmit run first)\n  // Handles: <form> submit via enter key or submit-button click.\n  // Uses bubble phase so component's onSubmit (which may call props.onSubmit) fires first.\n  document.addEventListener(\"submit\", function(e) {\n    e.preventDefault();\n    if (__ggui_wasHandled()) return;\n    var form = e.target;\n    var data = {};\n    try { data = Object.fromEntries(new FormData(form)); } catch(_) {}\n    parent.postMessage({ type: \"ggui-user-data\", data: data }, \"*\");\n  });\n\n  // Layers 2+3: Universal click handler (bubble phase \u2014 runs after component handlers)\n  // Handles: buttons, [role=\"button\"], links, [data-action], cursor:pointer elements.\n  // Does NOT handle submit-type elements inside forms (Layer 1 handles those).\n  document.addEventListener(\"click\", function(e) {\n    if (__ggui_wasHandled()) return;\n    if (!e.target || !e.target.closest) return;\n\n    // Layer 2: Find the closest standard interactive element\n    var el = e.target.closest(\"button\")\n      || e.target.closest(\"[role='button']\")\n      || e.target.closest(\"a[href], a[data-action]\")\n      || e.target.closest(\"[data-action]\")\n      || e.target.closest(\"[data-ggui-action]\");\n\n    // Layer 3 (approach C): Fallback \u2014 walk up DOM looking for cursor:pointer\n    if (!el) {\n      var target = e.target;\n      var depth = 0;\n      while (target && target !== document.documentElement && depth < 6) {\n        if (target.nodeType === 1) {\n          try {\n            if (window.getComputedStyle(target).cursor === \"pointer\") {\n              el = target;\n              break;\n            }\n          } catch(_) {}\n        }\n        target = target.parentElement;\n        depth++;\n      }\n    }\n    if (!el) return;\n\n    // Skip submit-type elements inside forms \u2014 Layer 1 handles those.\n    // (click fires before submit, so we must yield to avoid double-fire)\n    // <button> defaults to type=\"submit\", so el.type === \"submit\" catches both\n    // <button> and <button type=\"submit\">. Only <button type=\"button\"> is excluded.\n    if (el.closest(\"form\") && el.type === \"submit\") return;\n\n    // Skip form control elements \u2014 these are data entry, not actions.\n    // Checkboxes, radios, inputs, selects get captured via form submit (Layer 1).\n    var tag = el.tagName;\n    if (tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\" || tag === \"LABEL\") return;\n\n    // For standalone interactive elements, post click event with label + data attributes\n    var data = { action: \"click\" };\n    var label = el.getAttribute(\"aria-label\")\n      || el.getAttribute(\"data-label\")\n      || el.innerText\n      || el.textContent;\n    if (label) data.label = label.trim().substring(0, 200);\n\n    // Spread data-* attributes into payload (data-action, data-value, etc.)\n    if (el.dataset) {\n      for (var key in el.dataset) {\n        if (el.dataset.hasOwnProperty(key)) data[key] = el.dataset[key];\n      }\n    }\n\n    parent.postMessage({ type: \"ggui-user-data\", data: data }, \"*\");\n  });";
 //# sourceMappingURL=iframe-bridge.d.ts.map

package/dist/iframe-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"iframe-bridge.d.ts","sourceRoot":"","sources":["../src/iframe-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;IAExB,qKAAqK;;IAErK,uLAAuL;;IAIvL,0HAA0H;;IAI1H,8KAA8K;;IAI9K,0GAA0G;;IAI1G,2JAA2J;;IAE3J,iKAAiK;;IAIjK,kIAAkI;;IAElI,2IAA2I;;IAE3I,qIAAqI;;CAE7H,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,kPAK/B,CAAC;AAEP;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,QAUzB,CAAC;AAET;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,8lHAmF9B,CAAC"}
+{"version":3,"file":"iframe-bridge.d.ts","sourceRoot":"","sources":["../src/iframe-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;IAExB,qKAAqK;;IAErK,uLAAuL;;CAE/K,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,kPAK/B,CAAC"}