@ggui-ai/protocol 0.1.0-rc.1

package/dist/envelopes/builders.js

@@ -0,0 +1,113 @@
+import { PROTOCOL_SCHEMA_VERSION } from '../version.js';
+/**
+ * Resolve the stamp decision for the three semantic paths. Returns
+ * `undefined` when the field should be omitted entirely; returns a
+ * string when it should be stamped.
+ */
+function resolveSchemaVersion(parts) {
+    if ('schemaVersion' in parts) {
+        // Caller wrote the key — trust their decision (string OR explicit
+        // undefined-to-omit).
+        return parts.schemaVersion;
+    }
+    // Key absent — default stamp.
+    return PROTOCOL_SCHEMA_VERSION;
+}
+/**
+ * Build an {@link ActionEnvelope} with `schemaVersion` stamped to
+ * {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
+ *
+ * Filters `undefined` optional fields so the serialized wire message
+ * omits them (matches the producer convention that "absent field =
+ * default").
+ */
+export function makeActionEnvelope(parts) {
+    const envelope = {
+        sessionId: parts.sessionId,
+        type: parts.type,
+    };
+    if (parts.payload !== undefined)
+        envelope.payload = parts.payload;
+    if (parts.stackIndex !== undefined)
+        envelope.stackIndex = parts.stackIndex;
+    if (parts.stackItemId !== undefined)
+        envelope.stackItemId = parts.stackItemId;
+    if (parts.clientSeq !== undefined)
+        envelope.clientSeq = parts.clientSeq;
+    const stamp = resolveSchemaVersion(parts);
+    if (stamp !== undefined)
+        envelope.schemaVersion = stamp;
+    return envelope;
+}
+/**
+ * Build a {@link StreamEnvelope} with `schemaVersion` stamped to
+ * {@link PROTOCOL_SCHEMA_VERSION} unless the caller overrides.
+ *
+ * Filters `undefined` optional fields (`complete`, `seq`) so the
+ * serialized wire message omits them. `seq` is server-assigned in
+ * practice — callers pass the value the buffer hands them.
+ */
+export function makeStreamEnvelope(parts) {
+    const envelope = {
+        sessionId: parts.sessionId,
+        channel: parts.channel,
+        mode: parts.mode,
+        payload: parts.payload,
+    };
+    if (parts.complete !== undefined)
+        envelope.complete = parts.complete;
+    if (parts.seq !== undefined)
+        envelope.seq = parts.seq;
+    const stamp = resolveSchemaVersion(parts);
+    if (stamp !== undefined)
+        envelope.schemaVersion = stamp;
+    return envelope;
+}
+/**
+ * Build an {@link ErrorPayload} for the `{type: 'error'}` wire frame.
+ *
+ * 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
+ * `ErrorPayload` stamp-free preserves byte-equivalence with every
+ * existing server-side error emission that pre-dates the central
+ * builders.
+ *
+ * The builder exists so first-party subscribe / handshake paths emit
+ * canonical codes (e.g. `UPGRADE_REQUIRED`) via a single helper
+ * instead of spreading `{code, message}` object literals. `details`
+ * is filtered when `undefined` so the serialized frame matches the
+ * pre-builder `{code, message}` shape byte-for-byte.
+ */
+export function makeErrorPayload(parts) {
+    const payload = {
+        code: parts.code,
+        message: parts.message,
+    };
+    if (parts.details !== undefined)
+        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/unknown-permission-name.d.ts

@@ -0,0 +1,12 @@
+export interface UnknownPermissionNameErrorOptions {
+    /** The name the SDK caller passed to `requestPermission`. */
+    readonly observedName: string;
+}
+export declare class UnknownPermissionNameError extends Error {
+    /** The name the SDK caller passed. */
+    readonly observedName: string;
+    /** Accepted permission-name enum (Web Permissions API + MCP Apps mirror). */
+    readonly acceptedNames: readonly string[];
+    constructor(opts: UnknownPermissionNameErrorOptions);
+}
+//# sourceMappingURL=unknown-permission-name.d.ts.map

package/dist/errors/unknown-permission-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-permission-name.d.ts","sourceRoot":"","sources":["../../src/errors/unknown-permission-name.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,iCAAiC;IAChD,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAA0B;gBAEvD,IAAI,EAAE,iCAAiC;CAUpD"}

package/dist/errors/unknown-permission-name.js

@@ -0,0 +1,29 @@
+/**
+ * Typed error surface for SDK `requestPermission(name)` calls that pass
+ * a permission name outside the Web Permissions API enum
+ * (`KNOWN_PERMISSION_NAMES`).
+ *
+ * Background: the grant model lives on
+ * `clientCapabilities.gadgets[*].permission`. Without a validation
+ * gate, SDK callers (and LLM-generated component code) could request
+ * arbitrary permission strings, including typos like `'geolocaiton'`
+ * or unsupported names. This error is that gate.
+ *
+ * The class pins `.name === 'UnknownPermissionNameError'` so consumers
+ * can pattern-match without sniffing the message string. Carries the
+ * observed name + the accepted enum so operators can diagnose without
+ * additional context.
+ */
+import { KNOWN_PERMISSION_NAMES } from '../validation/hygiene-rules.js';
+export class UnknownPermissionNameError extends Error {
+    /** The name the SDK caller passed. */
+    observedName;
+    /** Accepted permission-name enum (Web Permissions API + MCP Apps mirror). */
+    acceptedNames = KNOWN_PERMISSION_NAMES;
+    constructor(opts) {
+        super(`Unknown permission name '${opts.observedName}'. ` +
+            `Pick a name from the Web Permissions API enum: [${KNOWN_PERMISSION_NAMES.join(', ')}].`);
+        this.name = 'UnknownPermissionNameError';
+        this.observedName = opts.observedName;
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Typed error surface for the protocol-version handshake.
+ *
+ * Raised by first-party clients + servers when the handshake observes
+ * a version mismatch:
+ *
+ *   - Server side: `SubscribePayload.supportedVersions` is present AND
+ *     does not contain the server's `PROTOCOL_SCHEMA_VERSION`. The
+ *     server emits an `{type: 'error'}` frame with `code:
+ *     UPGRADE_REQUIRED`; first-party servers also surface this class
+ *     to their own observability path so operators see the
+ *     unsatisfied subscribe locally.
+ *   - 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.
+ *
+ * The class pins `.name === 'UpgradeRequiredError'` and `.code ===
+ * UPGRADE_REQUIRED` so consumers can pattern-match without
+ * string-sniffing the message — `UPGRADE_REQUIRED` is reachable via
+ * a typed protocol-error surface, not just via raw string compares.
+ *
+ * Wire-shape coupling: the class carries the observed version(s) +
+ * the receiver's known-accepted set so operators can diagnose without
+ * additional context. The `code` property matches the wire value
+ * emitted in `ErrorPayload.code` — symmetric by design.
+ */
+import { UPGRADE_REQUIRED } from '../version.js';
+export interface UpgradeRequiredErrorOptions {
+    /**
+     * The version the peer declared on the wire. Server-side: the
+     * client's `supportedVersions` entry or the full list. Client-side:
+     * `AckPayload.serverVersion`.
+     */
+    readonly observedVersion?: string | readonly string[];
+    /**
+     * The receiver's accepted-versions set. Server-side: a singleton
+     * `[PROTOCOL_SCHEMA_VERSION]`. Client-side: `CLIENT_SUPPORTED_VERSIONS`.
+     */
+    readonly acceptedVersions: readonly string[];
+    /**
+     * Which side observed the mismatch. Server-side emission sets
+     * `'server'`; client-side surface sets `'client'`.
+     */
+    readonly observedBy: 'server' | 'client';
+}
+export declare class UpgradeRequiredError extends Error {
+    /** Canonical `ErrorPayload.code` value. Symmetric with wire shape. */
+    readonly code: typeof UPGRADE_REQUIRED;
+    readonly observedVersion?: string | readonly string[];
+    readonly acceptedVersions: readonly string[];
+    readonly observedBy: 'server' | 'client';
+    constructor(opts: UpgradeRequiredErrorOptions);
+}
+//# sourceMappingURL=version-mismatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version-mismatch.d.ts","sourceRoot":"","sources":["../../src/errors/version-mismatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC1C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,gBAAgB,CAAoB;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACtD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,QAAQ,CAAC;gBAE7B,IAAI,EAAE,2BAA2B;CAoB9C"}

package/dist/errors/version-mismatch.js

@@ -0,0 +1,52 @@
+/**
+ * Typed error surface for the protocol-version handshake.
+ *
+ * Raised by first-party clients + servers when the handshake observes
+ * a version mismatch:
+ *
+ *   - Server side: `SubscribePayload.supportedVersions` is present AND
+ *     does not contain the server's `PROTOCOL_SCHEMA_VERSION`. The
+ *     server emits an `{type: 'error'}` frame with `code:
+ *     UPGRADE_REQUIRED`; first-party servers also surface this class
+ *     to their own observability path so operators see the
+ *     unsatisfied subscribe locally.
+ *   - 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.
+ *
+ * The class pins `.name === 'UpgradeRequiredError'` and `.code ===
+ * UPGRADE_REQUIRED` so consumers can pattern-match without
+ * string-sniffing the message — `UPGRADE_REQUIRED` is reachable via
+ * a typed protocol-error surface, not just via raw string compares.
+ *
+ * Wire-shape coupling: the class carries the observed version(s) +
+ * the receiver's known-accepted set so operators can diagnose without
+ * additional context. The `code` property matches the wire value
+ * emitted in `ErrorPayload.code` — symmetric by design.
+ */
+import { UPGRADE_REQUIRED } from '../version.js';
+export class UpgradeRequiredError extends Error {
+    /** Canonical `ErrorPayload.code` value. Symmetric with wire shape. */
+    code = UPGRADE_REQUIRED;
+    observedVersion;
+    acceptedVersions;
+    observedBy;
+    constructor(opts) {
+        const observed = opts.observedVersion === undefined
+            ? 'unknown'
+            : Array.isArray(opts.observedVersion)
+                ? opts.observedVersion.join(', ')
+                : String(opts.observedVersion);
+        const accepted = opts.acceptedVersions.join(', ');
+        super(`UPGRADE_REQUIRED: ${opts.observedBy === 'server' ? 'client' : 'server'} ` +
+            `speaks version '${observed}' which is not in the ${opts.observedBy === 'server' ? 'server' : 'client'}'s ` +
+            `accepted set [${accepted}].`);
+        this.name = 'UpgradeRequiredError';
+        if (opts.observedVersion !== undefined) {
+            this.observedVersion = opts.observedVersion;
+        }
+        this.acceptedVersions = opts.acceptedVersions;
+        this.observedBy = opts.observedBy;
+    }
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Contract → descriptor resolution helpers.
+ *
+ * The wire side (`contract.clientCapabilities.gadgets`) is
+ * PACKAGE-KEYED two-level: `Record<package, Record<exportName, …>>`.
+ * 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
+ * sidecar.
+ */
+import type { DataContract, GadgetDescriptor, GadgetExport, GadgetUse } from '../types/data-contract.js';
+/**
+ * The export name a {@link GadgetExport} carries — the `hook` field
+ * for a hook export, the `component` field for a component export.
+ * Discrimination is by field presence; there is no `kind` field. The
+ * single accessor so callers never re-spell the field-presence check.
+ *
+ * Total over the union: it checks BOTH fields explicitly and throws
+ * on a malformed member rather than assuming `component` in the else
+ * branch (which silently returned `undefined` for a both-fields-
+ * absent object). The `GadgetHookExport.component?: never` /
+ * `GadgetComponentExport.hook?: never` exclusivity markers (F1) make
+ * `hook` / `component` OPTIONAL keys of the opposite member, so `'k' in
+ * x` no longer narrows — discrimination is by VALUE presence
+ * (`!== undefined`). A future third union member that carries neither
+ * field falls through to the throw rather than silently mistyping.
+ *
+ * Wire-side use records ({@link GadgetUse}) carry the export name as a
+ * plain `name` field — no accessor needed there.
+ */
+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`,
+ * `assertPublicEnvSatisfied`) agree byte-for-byte on what "the same
+ * gadget export" means.
+ *
+ * `version` is NOT part of the key — it is not on the wire. An App's
+ * `App.gadgets` catalog registers at most one descriptor per package
+ * (enforced by the catalog lint), so `(name, package)` resolves to
+ * exactly one registered export.
+ *
+ * The export name is itself kind-disambiguating: `use`-prefixed hook
+ * names (`HOOK_NAME_RE`) and PascalCase component names
+ * (`COMPONENT_NAME_RE`) are grammar-disjoint, so a hook and a
+ * component can never collide on name.
+ *
+ * Separator `\t`: the hook / component name grammars and
+ * `NPM_PACKAGE_NAME_RE` all exclude tab, so no field value can smuggle
+ * a separator.
+ */
+export declare function gadgetIdentityKey(use: {
+    name: string;
+    package: string;
+}): string;
+/**
+ * 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
+ * gates, descriptor resolver, code-gen) iterates, so the nested wire
+ * shape is walked in exactly one place.
+ *
+ * Returns an empty array when the contract declares no
+ * `clientCapabilities.gadgets`. Pure function. No I/O.
+ */
+export declare function listContractGadgets(contract: DataContract): readonly GadgetUse[];
+/**
+ * Given a wire-side {@link DataContract} and the operator's
+ * `App.gadgets` catalog, return the subset of package descriptors the
+ * contract references via `clientCapabilities.gadgets`.
+ *
+ * Matching key is the npm PACKAGE name — the wire map's own key. A
+ * 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`.
+ *
+ * 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
+ * BEFORE this helper runs, so silent drop here is safe in the happy
+ * path.
+ *
+ * Pure function. No I/O. Returns an empty array when the contract has
+ * no `clientCapabilities.gadgets`, `appGadgets` is empty, or no
+ * package resolves to a registered descriptor.
+ */
+export declare function filterDescriptorsToContract(contract: DataContract, appGadgets: readonly GadgetDescriptor[]): readonly GadgetDescriptor[];
+//# sourceMappingURL=resolve-contract-gadgets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-contract-gadgets.d.ts","sourceRoot":"","sources":["../../src/gadgets/resolve-contract-gadgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAMxD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAET;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,SAAS,SAAS,EAAE,CAiBtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,SAAS,gBAAgB,EAAE,GACtC,SAAS,gBAAgB,EAAE,CAiB7B"}

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

@@ -0,0 +1,119 @@
+/**
+ * The export name a {@link GadgetExport} carries — the `hook` field
+ * for a hook export, the `component` field for a component export.
+ * Discrimination is by field presence; there is no `kind` field. The
+ * single accessor so callers never re-spell the field-presence check.
+ *
+ * Total over the union: it checks BOTH fields explicitly and throws
+ * on a malformed member rather than assuming `component` in the else
+ * branch (which silently returned `undefined` for a both-fields-
+ * absent object). The `GadgetHookExport.component?: never` /
+ * `GadgetComponentExport.hook?: never` exclusivity markers (F1) make
+ * `hook` / `component` OPTIONAL keys of the opposite member, so `'k' in
+ * x` no longer narrows — discrimination is by VALUE presence
+ * (`!== undefined`). A future third union member that carries neither
+ * field falls through to the throw rather than silently mistyping.
+ *
+ * Wire-side use records ({@link GadgetUse}) carry the export name as a
+ * plain `name` field — no accessor needed there.
+ */
+export function gadgetExportName(x) {
+    if (x.hook !== undefined)
+        return x.hook;
+    if (x.component !== undefined)
+        return x.component;
+    throw new Error('gadgetExportName: malformed GadgetExport — neither hook nor component field present');
+}
+/**
+ * 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`,
+ * `assertPublicEnvSatisfied`) agree byte-for-byte on what "the same
+ * gadget export" means.
+ *
+ * `version` is NOT part of the key — it is not on the wire. An App's
+ * `App.gadgets` catalog registers at most one descriptor per package
+ * (enforced by the catalog lint), so `(name, package)` resolves to
+ * exactly one registered export.
+ *
+ * The export name is itself kind-disambiguating: `use`-prefixed hook
+ * names (`HOOK_NAME_RE`) and PascalCase component names
+ * (`COMPONENT_NAME_RE`) are grammar-disjoint, so a hook and a
+ * component can never collide on name.
+ *
+ * Separator `\t`: the hook / component name grammars and
+ * `NPM_PACKAGE_NAME_RE` all exclude tab, so no field value can smuggle
+ * a separator.
+ */
+export function gadgetIdentityKey(use) {
+    return `${use.name}\t${use.package}`;
+}
+/**
+ * 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
+ * gates, descriptor resolver, code-gen) iterates, so the nested wire
+ * shape is walked in exactly one place.
+ *
+ * Returns an empty array when the contract declares no
+ * `clientCapabilities.gadgets`. Pure function. No I/O.
+ */
+export function listContractGadgets(contract) {
+    const declared = contract.clientCapabilities?.gadgets;
+    if (!declared)
+        return [];
+    const out = [];
+    for (const [pkg, exports] of Object.entries(declared)) {
+        for (const [name, meta] of Object.entries(exports)) {
+            out.push({
+                package: pkg,
+                name,
+                ...(meta.description !== undefined
+                    ? { description: meta.description }
+                    : {}),
+                ...(meta.usage !== undefined ? { usage: meta.usage } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Given a wire-side {@link DataContract} and the operator's
+ * `App.gadgets` catalog, return the subset of package descriptors the
+ * contract references via `clientCapabilities.gadgets`.
+ *
+ * Matching key is the npm PACKAGE name — the wire map's own key. A
+ * 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`.
+ *
+ * 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
+ * BEFORE this helper runs, so silent drop here is safe in the happy
+ * path.
+ *
+ * Pure function. No I/O. Returns an empty array when the contract has
+ * no `clientCapabilities.gadgets`, `appGadgets` is empty, or no
+ * package resolves to a registered descriptor.
+ */
+export function filterDescriptorsToContract(contract, appGadgets) {
+    const declared = contract.clientCapabilities?.gadgets;
+    if (!declared || appGadgets.length === 0) {
+        return [];
+    }
+    const byPackage = new Map();
+    for (const descriptor of appGadgets) {
+        byPackage.set(descriptor.package, descriptor);
+    }
+    const out = [];
+    for (const pkg of Object.keys(declared)) {
+        const descriptor = byPackage.get(pkg);
+        if (descriptor)
+            out.push(descriptor);
+    }
+    return out;
+}

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

@@ -0,0 +1,43 @@
+import type { GadgetDescriptor } from '../types/data-contract';
+/**
+ * The first-party `@ggui-ai/gadgets` package name. Used as
+ * the default `package` for every entry in {@link STDLIB_GADGETS}
+ * and as the `DEFAULT_GADGET_PACKAGE` literal in the hygiene linter.
+ */
+export declare const STDLIB_GADGETS_PACKAGE = "@ggui-ai/gadgets";
+/**
+ * Pinned semver of the stdlib gadgets every descriptor declares on
+ * its `version` field. Mirrors
+ * `packages/gadgets/package.json#version`; a cross-package parity test
+ * 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.1";
+/**
+ * v1 catalog of stdlib gadget descriptors. Every entry's
+ * `package` defaults to {@link STDLIB_GADGETS_PACKAGE}; the
+ * `permission` field, where present, mirrors the Web Permissions API
+ * name and lines up with the hygiene linter's
+ * `KNOWN_PERMISSION_HOOKS` table.
+ *
+ * **Ordering:** alphabetical by hook name. Stable so consumers can
+ * diff the list across protocol minor bumps without false positives
+ * from re-ordering.
+ *
+ * **Shape note:** entries are typed `Readonly<GadgetDescriptor>` so
+ * downstream consumers (App.gadgets default-on-read, the LLM
+ * generator's catalog, the `ggui_list_gadgets` handler)
+ * can structurally clone without mutating the source. Callers that
+ * need a mutable copy should `structuredClone` explicitly.
+ */
+export declare const STDLIB_GADGETS: readonly Readonly<GadgetDescriptor>[];
+/**
+ * Hook-name index over {@link STDLIB_GADGETS}. Lazily
+ * constructed for callers that need O(1) "is hook X part of the
+ * stdlib?" checks (the hygiene linter, the per-app gadget validator,
+ * the `ggui_list_gadgets` handler).
+ *
+ * Frozen so accidental mutation is loud, not silent.
+ */
+export declare const STDLIB_GADGET_HOOKS: ReadonlySet<string>;
+//# sourceMappingURL=stdlib-gadgets.d.ts.map

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

@@ -0,0 +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"}