@ggui-ai/mcp-server-handlers 0.7.0 → 0.9.0

package/dist/renders/code-delivery-events.d.ts

@@ -1,31 +1,27 @@
 /**
  * Named events for the content-addressable code-delivery channel.
  *
- * `codeUrl` is the only STATIC delivery surface a COMPILED-COMPONENT
- * envelope has. Nothing sits behind it: a bootstrap mounts on
- * `codeUrl`, on a system-card `kind`, or on the live trio (`wsUrl` +
- * `wsToken`); `kind` is static too, but it belongs to system cards,
- * which never reach this channel. An envelope carrying none of the
- * three reads to a host as "not a mountable ggui render". So a failed
- * `codeUrl` mint is not absorbed by a second static channel; what
- * happens next is deployment-shaped:
+ * `codeUrl` is the CACHE-ADDRESSABLE static delivery surface of a
+ * COMPILED-COMPONENT envelope — since #471 it is no longer the only
+ * static one: `deriveRenderMeta` also stamps the size-capped inline
+ * `codeB64` twin, independent of this channel's store. A failed
+ * `codeUrl` mint therefore usually IS absorbed by the inline channel;
+ * what it still costs is deployment-shaped:
  *
- *   - A deployment that mints live-channel credentials still mounts.
- *     The slice keeps `wsUrl` + `wsToken`, the iframe subscribes, and
- *     the WS delivers the render body. The cost is the
- *     zero-round-trip first paint, not the render.
- *   - A host that resolves the render's `resourceUri` re-mints
- *     `codeUrl` against the same store at READ time, so a transient
- *     fault costs it nothing and a persistent one surfaces there as a
- *     read error rather than a blank card.
- *   - A deployment with neither loses the mount for that one
- *     envelope.
+ *   - Every under-cap compiled render keeps mounting via `codeB64`
+ *     (and, when minted, the live trio). The loss is the browser-
+ *     cacheable content-addressable URL — repeat renders of the same
+ *     bytes re-ship them inline instead of hitting HTTP cache.
+ *   - An OVER-CAP render (no `codeB64`) falls back to exactly the
+ *     pre-#471 posture: live trio mounts it; a host that resolves
+ *     `resourceUri` re-mints `codeUrl` at READ time; a deployment
+ *     with neither loses the mount for that one envelope.
  *
- * None of the three is distinguishable from the wire — the render
- * reports success either way — which is why the failure is emitted
- * under a name instead of swallowed. The event carries whether a live
- * channel is wired, because that is the difference between "slower
- * first paint" and "this envelope cannot mount".
+ * None of this is distinguishable from the wire — the render reports
+ * success either way — which is why the failure is emitted under a
+ * name instead of swallowed. The event carries whether a live channel
+ * is wired; combined with the render's size class it separates
+ * "slower / uncacheable delivery" from "this envelope cannot mount".
  */
 /**
  * Every event this module can emit. Closed union — a new emitter picks
@@ -33,7 +29,7 @@
  * compile error rather than an alert filter that quietly stops
  * matching.
  */
-export type CodeDeliveryEvent = 'render_code_write_failed';
+export type CodeDeliveryEvent = 'render_code_write_failed' | 'render_code_b64_over_cap';
 /**
  * The event names as values, so every emitter — in this package or a
  * storage backend elsewhere — spells them from one place.
@@ -41,10 +37,17 @@ export type CodeDeliveryEvent = 'render_code_write_failed';
 export declare const CODE_DELIVERY_EVENTS: {
     /**
      * The `codeUrl` mint failed for a render envelope. That envelope
-     * carries no static delivery channel; see the module docstring for
-     * what survives.
+     * loses the cache-addressable static channel; see the module
+     * docstring for what survives.
      */
     readonly renderCodeWriteFailed: "render_code_write_failed";
+    /**
+     * A compiled render's source exceeded the inline `codeB64` cap, so
+     * the slice was emitted WITHOUT the fetch-free channel. On hosts
+     * whose iframe CSP blocks fetches AND WebSockets, that render
+     * cannot paint — the omission must be visible, not silent.
+     */
+    readonly renderCodeB64OverCap: "render_code_b64_over_cap";
 };
 /**
  * What an emitter knows at the point the mint failed.
@@ -58,9 +61,11 @@ export interface RenderCodeWriteFailure {
      * Whether this deployment mints live-channel credentials.
      *
      * `true` ⇒ the render still mounts over the WS subscribe; the loss
-     * is the instant first paint. `false` ⇒ this envelope has no mount
-     * mode at all, and only a host that resolves `resourceUri` will
-     * still produce a card.
+     * is the instant first paint. `false` ⇒ the envelope mounts only
+     * through the inline `codeB64` channel (present for every under-cap
+     * compiled render, independent of this store); an OVER-CAP render
+     * with `false` here truly has no mount mode, and only a host that
+     * resolves `resourceUri` will still produce a card.
      */
     readonly liveChannelWired: boolean;
     /** Whatever the store threw. Unshaped by construction. */
@@ -73,4 +78,15 @@ export interface RenderCodeWriteFailure {
  * committed must not fail because its delivery-channel telemetry did.
  */
 export declare function reportRenderCodeWriteFailed(failure: RenderCodeWriteFailure): void;
+/**
+ * Emit {@link CODE_DELIVERY_EVENTS.renderCodeB64OverCap}.
+ *
+ * Never throws — same posture as the write-failure emitter above.
+ */
+export declare function reportRenderCodeB64OverCap(over: {
+    readonly sessionId: string;
+    readonly appId: string;
+    /** UTF-8 byte length of the compiled source that exceeded the cap. */
+    readonly sourceBytes: number;
+}): void;
 //# sourceMappingURL=code-delivery-events.d.ts.map

package/dist/renders/code-delivery-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-delivery-events.d.ts","sourceRoot":"","sources":["../../src/renders/code-delivery-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;CAEiD,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAgBN"}
+{"version":3,"file":"code-delivery-events.d.ts","sourceRoot":"","sources":["../../src/renders/code-delivery-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;;OAKG;;CAEiD,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAgBN;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,IAAI,CAUP"}

package/dist/renders/code-delivery-events.js

@@ -1,31 +1,27 @@
 /**
  * Named events for the content-addressable code-delivery channel.
  *
- * `codeUrl` is the only STATIC delivery surface a COMPILED-COMPONENT
- * envelope has. Nothing sits behind it: a bootstrap mounts on
- * `codeUrl`, on a system-card `kind`, or on the live trio (`wsUrl` +
- * `wsToken`); `kind` is static too, but it belongs to system cards,
- * which never reach this channel. An envelope carrying none of the
- * three reads to a host as "not a mountable ggui render". So a failed
- * `codeUrl` mint is not absorbed by a second static channel; what
- * happens next is deployment-shaped:
+ * `codeUrl` is the CACHE-ADDRESSABLE static delivery surface of a
+ * COMPILED-COMPONENT envelope — since #471 it is no longer the only
+ * static one: `deriveRenderMeta` also stamps the size-capped inline
+ * `codeB64` twin, independent of this channel's store. A failed
+ * `codeUrl` mint therefore usually IS absorbed by the inline channel;
+ * what it still costs is deployment-shaped:
  *
- *   - A deployment that mints live-channel credentials still mounts.
- *     The slice keeps `wsUrl` + `wsToken`, the iframe subscribes, and
- *     the WS delivers the render body. The cost is the
- *     zero-round-trip first paint, not the render.
- *   - A host that resolves the render's `resourceUri` re-mints
- *     `codeUrl` against the same store at READ time, so a transient
- *     fault costs it nothing and a persistent one surfaces there as a
- *     read error rather than a blank card.
- *   - A deployment with neither loses the mount for that one
- *     envelope.
+ *   - Every under-cap compiled render keeps mounting via `codeB64`
+ *     (and, when minted, the live trio). The loss is the browser-
+ *     cacheable content-addressable URL — repeat renders of the same
+ *     bytes re-ship them inline instead of hitting HTTP cache.
+ *   - An OVER-CAP render (no `codeB64`) falls back to exactly the
+ *     pre-#471 posture: live trio mounts it; a host that resolves
+ *     `resourceUri` re-mints `codeUrl` at READ time; a deployment
+ *     with neither loses the mount for that one envelope.
  *
- * None of the three is distinguishable from the wire — the render
- * reports success either way — which is why the failure is emitted
- * under a name instead of swallowed. The event carries whether a live
- * channel is wired, because that is the difference between "slower
- * first paint" and "this envelope cannot mount".
+ * None of this is distinguishable from the wire — the render reports
+ * success either way — which is why the failure is emitted under a
+ * name instead of swallowed. The event carries whether a live channel
+ * is wired; combined with the render's size class it separates
+ * "slower / uncacheable delivery" from "this envelope cannot mount".
  */
 /**
  * The event names as values, so every emitter — in this package or a
@@ -34,10 +30,17 @@
 export const CODE_DELIVERY_EVENTS = {
     /**
      * The `codeUrl` mint failed for a render envelope. That envelope
-     * carries no static delivery channel; see the module docstring for
-     * what survives.
+     * loses the cache-addressable static channel; see the module
+     * docstring for what survives.
      */
     renderCodeWriteFailed: 'render_code_write_failed',
+    /**
+     * A compiled render's source exceeded the inline `codeB64` cap, so
+     * the slice was emitted WITHOUT the fetch-free channel. On hosts
+     * whose iframe CSP blocks fetches AND WebSockets, that render
+     * cannot paint — the omission must be visible, not silent.
+     */
+    renderCodeB64OverCap: 'render_code_b64_over_cap',
 };
 /**
  * Emit {@link CODE_DELIVERY_EVENTS.renderCodeWriteFailed}.
@@ -58,3 +61,17 @@ export function reportRenderCodeWriteFailed(failure) {
         errorName: failure.cause instanceof Error ? failure.cause.name : undefined,
     }));
 }
+/**
+ * Emit {@link CODE_DELIVERY_EVENTS.renderCodeB64OverCap}.
+ *
+ * Never throws — same posture as the write-failure emitter above.
+ */
+export function reportRenderCodeB64OverCap(over) {
+    // eslint-disable-next-line no-console -- structured single-line event for log-pipeline pickup
+    console.warn(JSON.stringify({
+        msg: CODE_DELIVERY_EVENTS.renderCodeB64OverCap,
+        sessionId: over.sessionId,
+        appId: over.appId,
+        sourceBytes: over.sourceBytes,
+    }));
+}

package/dist/renders/consume.js

@@ -75,7 +75,7 @@ export function createGguiConsumeHandler(deps) {
         name: 'ggui_consume',
         title: 'Consume',
         audience: ['agent'],
-        description: 'Long-poll for buffered events on a GguiSession. CALL THIS RIGHT AFTER EVERY `ggui_render` THAT RETURNS `nextStep.tool === "ggui_consume"` — that hint is your cue to start listening for the user\'s gesture. Keyed by sessionId (global UUID); tenancy-checked via ctx.appId. Inline long-poll: `timeout` is an integer in [0, 25] seconds (values outside reject INVALID_PARAMS — host MCP clients abort longer tool calls; pick 5-15s typical, 25 max). Returns `{events, status}` — each event carries `{intent, actionData, uiContext, actionId, firedAt}`: `actionData` is WHAT the user did, `uiContext` is the iframe-local snapshot of the contract\'s contextSpec slots AT THE MOMENT they did it. Both inform your reaction without a second round trip. Returns immediately when an action event arrives OR the render completes OR the timeout elapses. On timeout with no event, re-call ggui_consume to keep waiting.  THE LOOP: when `events` is non-empty, REACT, then re-call `ggui_consume` to wait for the next event. Exit only when status:"expired".  IMPORTANT — the iframe state is independent of your backend state: after you mutate via domain tools (todo_toggle, cart_add, etc.), the UI still shows the OLD props until you call `ggui_update`. If the events caused observable state changes the user is looking at, your reaction MUST include `ggui_update` somewhere before re-consuming; otherwise the user sees stale props (the #1 wire compliance bug). Pure-info events that don\'t change displayed state can skip ggui_update. You decide the call order and which tools you need — the protocol just guarantees that `ggui_update` is the way to refresh the iframe.  HOSTS WITH PROGRESSIVE TOOL DISCOVERY (claude.ai-style connectors): if a call here errors with "tool not loaded yet" or "wrong parameter names," call `tool_search({query:"ggui_consume"})` once to warm the tool, then retry with the same args. DO NOT skip the consume — silent gesture drops are the worst protocol failure.',
+        description: 'Long-poll for buffered events on a GguiSession. CALL THIS RIGHT AFTER EVERY `ggui_render` THAT RETURNS `nextStep.tool === "ggui_consume"` — that hint is your cue to start listening for the user\'s gesture. Keyed by sessionId (global UUID); tenancy-checked via ctx.appId. Inline long-poll: `timeout` is an integer in [0, 25] seconds (values outside reject INVALID_PARAMS — host MCP clients abort longer tool calls; pick 5-15s typical, 25 max). Returns `{events, status}` — each event carries `{intent, actionData, uiContext, actionId, firedAt}`: `actionData` is WHAT the user did, `uiContext` is the iframe-local snapshot of the contract\'s contextSpec slots AT THE MOMENT they did it. Both inform your reaction without a second round trip. Returns immediately when an action event arrives OR the render completes OR the timeout elapses. On timeout with no event, re-call ggui_consume to keep waiting.  THE LOOP: when `events` is non-empty, REACT, then re-call `ggui_consume` to wait for the next event. Exit only when status:"expired".  IMPORTANT — the iframe state is independent of your backend state: after you mutate via domain tools (todo_toggle, cart_add, etc.), the UI still shows the OLD props until you call `ggui_amend`. If the events caused observable state changes the user is looking at, your reaction MUST include `ggui_amend` somewhere before re-consuming; otherwise the user sees stale props (the #1 wire compliance bug). Pure-info events that don\'t change displayed state can skip it. `ggui_amend` repaints the SAME card in place (the default move in this loop); `ggui_update` instead renders the state as a NEW card and advances the history number — reserve it for milestones worth a card in the transcript.  HOSTS WITH PROGRESSIVE TOOL DISCOVERY (claude.ai-style connectors): if a call here errors with "tool not loaded yet" or "wrong parameter names," call `tool_search({query:"ggui_consume"})` once to warm the tool, then retry with the same args. DO NOT skip the consume — silent gesture drops are the worst protocol failure.',
         inputSchema,
         outputSchema,
         async handler(rawInput, ctx) {

package/dist/renders/decide-handshake.d.ts

@@ -43,6 +43,7 @@
 import { type BlueprintSource, type BlueprintVariance, type DataContract } from '@ggui-ai/protocol';
 import { type LLMCaller } from '@ggui-ai/negotiator';
 import type { HandlerContext } from '../types.js';
+import { type BlueprintMatchResult } from './blueprint-matcher.js';
 import type { BlueprintRegistryDeps } from './blueprint-registry.js';
 import type { HandshakeNegotiator, HandshakeNegotiatorResult } from './handshake.js';
 import type { InstalledBlueprintsProvider } from './installed-blueprints-provider.js';
@@ -116,6 +117,20 @@ export interface HandshakeDecisionAdapter {
      * passes its structured logger. Absent ⇒ silent.
      */
     warn?(message: string): void;
+    /**
+     * Optional observer for every blueprint-match OUTCOME (hit or miss),
+     * called once per pool probed in the Tier-1 find-similar loop.
+     * Non-error, non-blocking — purely for cache-hit-ratio observability.
+     * Absent ⇒ no-op. OSS ships no default observer; a host MAY wire
+     * this to its own structured logger. Enforced non-blocking: a
+     * throwing observer is caught, reported via `warn` if present, and
+     * never breaks the handshake.
+     */
+    onBlueprintMatch?(input: {
+        readonly pool: string;
+        readonly scope: string;
+        readonly result: BlueprintMatchResult;
+    }): void;
     /** Optional per-app tool-identity catalog (bare tool → canonical serverInfo).
      *  Present ⇒ run the canonicalization step before keying (Tier 1); absent ⇒
      *  no-op (Tier 2). Resolved by ctx.appId. */

package/dist/renders/decide-handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decide-handshake.d.ts","sourceRoot":"","sources":["../../src/renders/decide-handshake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decide-handshake.d.ts","sourceRoot":"","sources":["../../src/renders/decide-handshake.ts"],"names":[],"mappings":"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"}

package/dist/renders/decide-handshake.js

@@ -377,6 +377,24 @@ export async function decideHandshake(adapter, input) {
                     contract: parsedDraft.data,
                     ...(variance !== undefined ? { variance } : {}),
                 });
+                // Isolated in its OWN try/catch, separate from the outer
+                // pool-probe catch below: onBlueprintMatch's contract promises
+                // non-blocking observation, so a throwing observer must never
+                // lose an otherwise-successful matchResult (falling into the
+                // outer catch would either rethrow a non-operational error or
+                // misreport "matchBlueprint probe failed" for a probe that
+                // actually succeeded). Observer failures are surfaced via warn
+                // and the request proceeds — never rethrown.
+                try {
+                    adapter.onBlueprintMatch?.({
+                        pool: pool.label ?? scope,
+                        scope,
+                        result: matchResult,
+                    });
+                }
+                catch (err) {
+                    adapter.warn?.(`[decideHandshake] onBlueprintMatch observer threw for pool ${pool.label ?? scope}; ignoring: ${errMessage(err)}`);
+                }
                 // exact-key is a perfect canonical match — it wins immediately over
                 // any semantic hit from any pool, but ONLY when the requesting agent
                 // can fulfill it: its declared tools must superset the blueprint's

package/dist/renders/declare-tool-catalog.js

@@ -57,7 +57,7 @@ const declareOutputSchema = declareToolCatalogOutputSchema.shape;
 export function createGguiDeclareToolCatalogHandler(deps) {
     return {
         name: "ggui_runtime_declare_tool_catalog",
-        title: "Declare tool catalog",
+        title: "[runtime] Declare Tool Catalog",
         audience: ["runtime"],
         // `_meta.ui.visibility: ['app']` keeps this tool off the LLM's
         // `tools/list` (spec-compliant hosts filter `app`-visible tools out

package/dist/renders/handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/renders/handshake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/renders/handshake.ts"],"names":[],"mappings":"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"}

package/dist/renders/handshake.js

@@ -278,7 +278,7 @@ export function createGguiHandshakeHandler(deps) {
             });
             const nextStep = buildNextStepHint({
                 handshakeId,
-                suggestion: negotiated.suggestion,
+                contract: negotiated.effectiveContract,
             });
             const serverCapabilities = deps.serverCapabilities?.();
             // Truncate `reason` to the wire-output cap (280 chars).
@@ -405,10 +405,15 @@ function isJsonObject(v) {
  * `nextStep.example` verbatim into its next `ggui_render` call.
  */
 function buildNextStepHint(input) {
-    const { handshakeId, suggestion } = input;
-    // `props` is REQUIRED on the new renderInputSchema; absent a contract-
-    // derived placeholder we emit `{}` so the example is copy-paste valid.
-    const propsExample = buildPropsExample(suggestion.blueprintMeta.contractHash) ?? '{}';
+    const { handshakeId, contract } = input;
+    // `props` is REQUIRED on the renderInputSchema, and the proposed
+    // contract's REQUIRED prop entries must appear in it — a bare `{}`
+    // example against such a contract fails validation when followed
+    // verbatim (a live agent flagged exactly that, 2026-08-12). Derive
+    // the example from the effective contract: required entries keyed
+    // with their declared `example`/`default` when present, else a
+    // type-shaped placeholder. No required props → `{}` stays honest.
+    const propsExample = buildPropsExample(contract) ?? '{}';
     // ACCEPT shape: omit `override` entirely — the agent reuses the
     // proposed contract. (Re-aim via `override:{variance}` / `override:
     // {contract}` is taught in the description, not the default hint.)
@@ -419,14 +424,55 @@ function buildNextStepHint(input) {
     };
 }
 /**
- * Build a placeholder JSON example for `props` when the suggestion
- * carries a non-empty propsSpec. Without access to the full contract
- * here we return undefined; the caller falls back to `{}` (valid for
- * the REQUIRED `props` field), and the propsSpec hint surface is
- * delegated to the render.ts handler's recovery error messages.
+ * JSON example for the REQUIRED entries of the contract's propsSpec.
+ * Prefers each entry's declared `example`, then `default`, then a
+ * type-shaped placeholder from its JSON Schema (first enum member,
+ * else '' / 0 / false / [] / {}). Returns undefined when the contract
+ * has no required props — the caller's `{}` fallback is then valid
+ * verbatim.
  */
-function buildPropsExample(_contractHash) {
-    return undefined;
+function buildPropsExample(contract) {
+    const properties = contract.propsSpec?.properties;
+    if (properties === undefined)
+        return undefined;
+    const out = {};
+    for (const [name, entry] of Object.entries(properties)) {
+        if (entry.required !== true)
+            continue;
+        out[name] =
+            entry.example ?? entry.default ?? placeholderForSchema(entry.schema);
+    }
+    if (Object.keys(out).length === 0)
+        return undefined;
+    try {
+        return JSON.stringify(out);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Minimal type-shaped placeholder for a JSON Schema. */
+function placeholderForSchema(schema) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        return '';
+    }
+    const s = schema;
+    if (Array.isArray(s.enum) && s.enum.length > 0) {
+        return s.enum[0];
+    }
+    switch (s.type) {
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'array':
+            return [];
+        case 'object':
+            return {};
+        default:
+            return '';
+    }
 }
 /**
  * Typed error thrown by `ggui_render` when the supplied handshakeId

package/dist/renders/index.d.ts

@@ -59,8 +59,12 @@ export { createGguiRenderHandler, type ChannelNotifier, type GenerationCredentia
 export { applyRecordOp, DEFAULT_REPLAY_MAX_PER_SESSION, DEFAULT_REPLAY_MAX_RETRIES, EMPTY_BUFFER_STATE, normalizeBufferState, ReplayConflictError, replayFromBufferOp, ReplayMaxRetriesExceededError, ReplayGguiSessionNotFoundError, runSequencedRecord, type ApplyRecordResult, type BufferedReplayEnvelope, type BufferState, type FetchedReplayState, type ReplayResult, type ReplaySequencerDeps, type RunSequencedRecordOptions, type StreamReplayInput, } from "./stream-replay-ops.js";
 export { createGguiEmitHandler, type GguiEmitHandlerDeps, type StreamObserverNotifier, } from "./stream.js";
 export { createGguiSubmitActionHandler } from "./submit-action.js";
+export { createGguiRuntimePullHandler, type GguiRuntimePullHandlerDeps, } from "./runtime-pull.js";
+export { createGguiRuntimeTelemetryHandler, type GguiRuntimeTelemetryHandlerDeps, type RuntimeTelemetryLogger, } from "./runtime-telemetry.js";
 export { createGguiSyncContextHandler, type CreateGguiSyncContextHandlerDeps, } from "./sync-context.js";
 export { createGguiUpdateHandler, type BillingGate, type GguiUpdateHandlerDeps, type PropsUpdateNotifier, } from "./update.js";
+export { createGguiAmendHandler, type GguiAmendHandlerDeps, } from "./amend.js";
+export { mutationInputSchema, runPropsMutation, type PropsMutationResult, } from "./props-mutation-core.js";
 export { matchBlueprint, type BlueprintMatchHit, type BlueprintMatchMiss, type BlueprintMatchResult, type MatchBlueprintDeps, type MatchBlueprintOptions, } from "./blueprint-matcher.js";
 export { BlueprintRejectedError, composeEmbeddingInput, composeExactKey, deleteBlueprint, findBlueprintExact, findBlueprintsByEmbedding, listBlueprints, recordBlueprintHit, registerBlueprint, type Blueprint, type BlueprintCandidate, type BlueprintIndex, type BlueprintKind, type BlueprintRegistryDeps, type ContractValidator, type RegisterBlueprintInput, type RegisterBlueprintOptions, } from "./blueprint-registry.js";
 export { consumeHandshakeRecord, createGguiHandshakeHandler, DEFAULT_GENERATOR_SLUG, HANDSHAKE_RECORD_TTL_SEC, HandshakeNotFoundError, handshakeRecordKey, peekHandshakeRecord, type GguiHandshakeHandlerDeps, type HandshakeNegotiator, type HandshakeNegotiatorResult, type HandshakeRecord, type HandshakeStoredInput, type HandshakeStoredTarget, } from "./handshake.js";
@@ -68,7 +72,7 @@ export { buildCacheReuseResult, buildCreateFallback, decideHandshake, type Bluep
 export { installToCache, type InstallToCacheInput } from "./install-to-cache.js";
 export { createInstalledBlueprintsProvider, type CreateInstalledBlueprintsProviderOptions, type InstalledBlueprintCacheIssue, type CompileResult as InstalledBlueprintCompileResult, type InstalledBlueprintEntry, type InstalledBlueprintsProvider, } from "./installed-blueprints-provider.js";
 export { createInMemoryProvisionalPreviewRegistry, evaluateProvisionalPreviewGate, finalizeProvisionalPreview, kickoffProvisionalPreview, PreviewAbortError, PROVISIONAL_PREVIEW_CHANNEL, runProvisionalPreview, type ProvisionalPreviewConfig, type ProvisionalPreviewContext, type ProvisionalPreviewDeps, type ProvisionalPreviewEmit, type ProvisionalPreviewEmitter, type ProvisionalPreviewGate, type ProvisionalPreviewGateInput, type ProvisionalPreviewHandle, type ProvisionalPreviewOutcome, type ProvisionalPreviewRegistry, type ProvisionalPreviewRunContext, type ProvisionalPreviewSkipReason, } from "./provisional-preview.js";
-export { assembleRenderSliceBase, deriveBundleOrigins, deriveContextSlots, deriveContractBundle, derivePropsJson, derivePublicEnvProjection, deriveRenderMeta, resolveGadgetUrls, type RenderMetaView, type RenderSliceBase, type RenderSliceMetaDeps, } from "./slice-meta-derivation.js";
+export { assembleRenderSliceBase, deriveBundleOrigins, deriveContextSlots, deriveContractBundle, derivePropsJson, derivePublicEnvProjection, deriveRenderMeta, spreadRenderMetaViewOntoSlice, rewritePrivateBundleUrls, wsOriginToHttpOrigin, PRIVATE_BUNDLE_PREFIX, resolveGadgetUrls, type RenderMetaView, type RenderSliceBase, type RenderSliceMetaDeps, } from "./slice-meta-derivation.js";
 export type { SeedPoolSource } from "./seed-pool-source.js";
 export { buildSeedPool, type BuildSeedPoolOptions } from "./build-seed-pool.js";
 export { listRegistryBlueprintsForExport, type ExportableBlueprint } from './export-registry.js';

package/dist/renders/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renders/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renders/index.ts"],"names":[],"mappings":"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"}

package/dist/renders/index.js

@@ -65,8 +65,12 @@ export { createGguiRenderHandler, } from "./render.js";
 export { applyRecordOp, DEFAULT_REPLAY_MAX_PER_SESSION, DEFAULT_REPLAY_MAX_RETRIES, EMPTY_BUFFER_STATE, normalizeBufferState, ReplayConflictError, replayFromBufferOp, ReplayMaxRetriesExceededError, ReplayGguiSessionNotFoundError, runSequencedRecord, } from "./stream-replay-ops.js";
 export { createGguiEmitHandler, } from "./stream.js";
 export { createGguiSubmitActionHandler } from "./submit-action.js";
+export { createGguiRuntimePullHandler, } from "./runtime-pull.js";
+export { createGguiRuntimeTelemetryHandler, } from "./runtime-telemetry.js";
 export { createGguiSyncContextHandler, } from "./sync-context.js";
 export { createGguiUpdateHandler, } from "./update.js";
+export { createGguiAmendHandler, } from "./amend.js";
+export { mutationInputSchema, runPropsMutation, } from "./props-mutation-core.js";
 // The handshake handler owns suggestion orchestration directly, via
 // `HandshakeNegotiator.decide` returning a `HandshakeSuggestion`.
 // The LLM-backed negotiator in `@ggui-ai/mcp-server` is the
@@ -83,7 +87,7 @@ export { createInMemoryProvisionalPreviewRegistry, evaluateProvisionalPreviewGat
 // Exported so any server can run the same projections off the
 // resolved render without duplicating the actionSpec / contextSpec
 // walks.
-export { assembleRenderSliceBase, deriveBundleOrigins, deriveContextSlots, deriveContractBundle, derivePropsJson, derivePublicEnvProjection, deriveRenderMeta, resolveGadgetUrls, } from "./slice-meta-derivation.js";
+export { assembleRenderSliceBase, deriveBundleOrigins, deriveContextSlots, deriveContractBundle, derivePropsJson, derivePublicEnvProjection, deriveRenderMeta, spreadRenderMetaViewOntoSlice, rewritePrivateBundleUrls, wsOriginToHttpOrigin, PRIVATE_BUNDLE_PREFIX, resolveGadgetUrls, } from "./slice-meta-derivation.js";
 export { buildSeedPool } from "./build-seed-pool.js";
 export { listRegistryBlueprintsForExport } from './export-registry.js';
 // The render-identity event registry. Exported because storage backends

package/dist/renders/props-mutation-core.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PROPS-MUTATION CORE — the single flow behind BOTH mutation tools
+ * (#483 tool split): `ggui_update` (advances the history epoch,
+ * mints a new record) and `ggui_amend` (in-place, epoch untouched).
+ * Extracted verbatim from the pre-split ggui_update handler; the
+ * per-tool deltas are parameterized on `tool`, everything else is
+ * byte-identical behavior.
+ */
+import { z } from 'zod';
+import type { HandlerContext } from '../types.js';
+import type { GguiUpdateHandlerDeps } from './update.js';
+/**
+ * Input raw-shape shared by BOTH mutation tools — discriminated on
+ * `kind` (`'replace'` + `props` | `'merge'` + `patch`); identical wire
+ * grammar for `ggui_update` and `ggui_amend` (#483). Both validate the
+ * FINAL props (post-merge for `merge`) against the render's
+ * `propsSpec`.
+ */
+export declare const mutationInputSchema: {
+    /**
+     * Globally-unique render id. Optional on the wire so an in-process
+     * dispatcher (live-channel dispatch / threaded mount) can populate it
+     * via `HandlerContext.sessionId` instead. Required at the core
+     * level — see the resolve step inside `runPropsMutation`.
+     */
+    readonly sessionId: z.ZodOptional<z.ZodString>;
+    /**
+     * Mode discriminator. `'replace'` requires `props`; `'merge'`
+     * requires `patch`. The narrowing step inside the core enforces
+     * both presence + mutual exclusion.
+     */
+    readonly kind: z.ZodEnum<{
+        replace: "replace";
+        merge: "merge";
+    }>;
+    /**
+     * Full new props map. Required when `kind === 'replace'`; rejected
+     * otherwise. Validated against the GguiSession's `propsSpec` after
+     * applying.
+     */
+    readonly props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * RFC 7396 JSON Merge Patch. Required when `kind === 'merge'`;
+     * rejected otherwise. The core applies the patch to the existing
+     * props, then validates the merged result against `propsSpec`.
+     * `null` values in the patch DELETE the corresponding key.
+     */
+    readonly patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export interface PropsMutationResult {
+    readonly sessionId: string;
+    readonly updated: boolean;
+    /** Bare mount URI (no epoch pin) — callers compose pinned forms. */
+    readonly mountResourceUri: string;
+    /** Head epoch AFTER the call (row-authoritative; 0 when absent). */
+    readonly epoch: number;
+    readonly warning?: string;
+}
+export declare function runPropsMutation(deps: GguiUpdateHandlerDeps, tool: 'ggui_update' | 'ggui_amend', input: unknown, ctx: HandlerContext): Promise<PropsMutationResult>;
+//# sourceMappingURL=props-mutation-core.d.ts.map

package/dist/renders/props-mutation-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props-mutation-core.d.ts","sourceRoot":"","sources":["../../src/renders/props-mutation-core.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;IAC9B;;;;;OAKG;;IAEH;;;;OAIG;;;;;IAEH;;;;OAIG;;IAEH;;;;;OAKG;;CAEK,CAAC;AAwBX,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,aAAa,GAAG,YAAY,EAClC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAsS9B"}