@ggui-ai/ui-visual-tester 0.8.0 → 0.10.0

package/fixture/fixture-runtime.js

@@ -19836,7 +19836,7 @@
       case "warning":
       case "error":
       case "info":
-        return `var(--ggui-color-${tone}, ${SEMANTIC_TONE_FALLBACK[tone]})`;
+        return `var(--ggui-color-${tone}-500, ${SEMANTIC_TONE_FALLBACK[tone]})`;
       case "inverse":
         return "var(--ggui-color-surface, #ffffff)";
       case "inherit":
@@ -27817,7 +27817,7 @@
   }
 
   // ../protocol/dist/version.js
-  var PROTOCOL_VERSION = "draft-2026-06-12";
+  var PROTOCOL_VERSION = "draft-2026-08-19";
   var PROTOCOL_SCHEMA_VERSION = PROTOCOL_VERSION;
   var CLIENT_SUPPORTED_VERSIONS = Object.freeze([
     PROTOCOL_SCHEMA_VERSION
@@ -42344,7 +42344,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 
   // ../protocol/dist/gadgets/stdlib-gadgets.js
   var STDLIB_GADGETS_PACKAGE = "@ggui-ai/gadgets";
-  var STDLIB_GADGETS_VERSION = "0.8.0";
+  var STDLIB_GADGETS_VERSION = "0.10.0";
   var STDLIB_GADGETS = [
     {
       package: STDLIB_GADGETS_PACKAGE,
@@ -42495,15 +42495,24 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     // surface as `undefined` at runtime which JSON.stringify drops.
     external_exports.record(external_exports.string(), jsonValueSchema)
   ]));
+  var jsonSchemaTypeNameSchema = external_exports.enum([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+    "object",
+    "null"
+  ]);
   var jsonSchemaSchema = external_exports.lazy(() => external_exports.object({
-    type: external_exports.enum([
-      "string",
-      "number",
-      "integer",
-      "boolean",
-      "array",
-      "object",
-      "null"
+    // Single type OR a draft-07 type array (`['string','null']` —
+    // the canonical nullability form the enforced-props-schema
+    // emission produces). Mirrors `JsonSchemaTypeName | JsonSchemaTypeName[]`
+    // on the TS type — the zod and TS sides are an SSoT pair; widen
+    // both or neither.
+    type: external_exports.union([
+      jsonSchemaTypeNameSchema,
+      external_exports.array(jsonSchemaTypeNameSchema)
     ]).optional(),
     description: external_exports.string().optional(),
     enum: external_exports.array(jsonValueSchema).optional(),
@@ -42671,12 +42680,12 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   }).strict();
   var appPublicEnvSchema = external_exports.record(external_exports.string().regex(PUBLIC_ENV_APP_KEY_RE), external_exports.string()).readonly();
   var dataContractSchema = external_exports.object({
-    propsSpec: propsSpecSchema.optional(),
-    actionSpec: actionSpecSchema.optional(),
-    streamSpec: streamSpecSchema.optional(),
-    contextSpec: contextSpecSchema.optional(),
-    agentCapabilities: agentCapabilitiesSpecSchema.optional(),
-    clientCapabilities: clientCapabilitiesSpecSchema.optional()
+    propsSpec: propsSpecSchema.optional().describe("Initial render data: {description?, properties: {<name>: {schema: <JSON Schema>, required?: boolean, description?, default?, example?}}}. A prop is required at the wire gate ONLY when `required: true`; omitted \u21D2 optional (declare `required: true` for props the render must always pass)."),
+    actionSpec: actionSpecSchema.optional().describe("User gestures the agent reacts to on its next turn: {<action>: {label: string (REQUIRED \u2014 button copy / accessible name), schema?: <payload JSON Schema>, description?, example?, icon?, confirm?, nextStep?: '<agentCapabilities.tools key>'}}. Every action is agent-routed; `nextStep` is a hint, not a dispatch."),
+    streamSpec: streamSpecSchema.optional().describe("Live update channels the agent emits into: {<channel>: {schema: <JSON Schema>, description?, example?, mode?: append|replace, replay?: latest|all|none, complete?, source?: {tool, args?}}}. `source.tool` must be declared in agentCapabilities.tools."),
+    contextSpec: contextSpecSchema.optional().describe("Observable client state the agent reads alongside each action: {<slot>: {schema: <JSON Schema>, description?, default?, debounceMs?, example?}}. State that needs no next-turn reasoning belongs here, not in actionSpec."),
+    agentCapabilities: agentCapabilitiesSpecSchema.optional().describe("MCP tools the AGENT may call: {tools: {<bareToolName>: {toolInfo: {inputSchema (REQUIRED), description?, outputSchema?}, serverInfo?: {name, version?}, usage?, example?: {input, output}}}}. Key by the BARE tool name (after any `mcp__<server>__` prefix); the component never calls these."),
+    clientCapabilities: clientCapabilitiesSpecSchema.optional().describe("Browser-capability gadgets the COMPONENT imports: {gadgets: {<npm package>: {<exportName>: {description?, usage?}}}} \u2014 `use`-prefixed export keys are hooks, PascalCase keys are components; version and transport resolve from the app's registered catalog, never on the wire.")
   }).passthrough();
 
   // ../protocol/dist/schemas/blueprint.js
@@ -42692,11 +42701,17 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     userBlueprintSourceSchema,
     curatedBlueprintSourceSchema
   ]);
+  var BLUEPRINT_VARIANCE_KEYS = ["persona", "aesthetic", "context", "seedPrompt"];
   var blueprintVarianceSchema = external_exports.object({
     persona: external_exports.string().optional().describe('Design persona, e.g. "minimalist" / "data-dense". Part of cache identity.'),
     aesthetic: external_exports.string().optional().describe('Visual aesthetic, e.g. "calm" / "ornate". Part of cache identity.'),
     context: external_exports.record(external_exports.string(), jsonValueSchema).optional().describe('Deliberate design-shaping signals (e.g. {situation:"sad"}) \u2014 part of cache identity. NOT for per-user runtime data; put that in propsSpec/contextSpec.'),
     seedPrompt: external_exports.string().optional().describe("Generation seed directive. Part of cache identity.")
+  }, {
+    // A rejection that teaches (ggui#523 item 2): the first live guest
+    // turn sent `mood` and got a bare "Unrecognized key" — name the
+    // legal set and where the misplaced intent belongs.
+    error: (issue2) => issue2.code === "unrecognized_keys" ? `variance: unknown key(s) ${issue2.keys.map((k) => JSON.stringify(k)).join(", ")} \u2014 variance is EXACTLY {${BLUEPRINT_VARIANCE_KEYS.join(", ")}}; put tonal intent in \`aesthetic\`, and per-user runtime data in props / contextSpec, never in variance` : void 0
   }).strict();
   var blueprintSchema = external_exports.object({
     blueprintId: external_exports.string().min(1),
@@ -42757,15 +42772,17 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     }).strict()
   ]);
   var jsonPatchSchema = external_exports.array(jsonPatchOpSchema);
+  var BLUEPRINT_DRAFT_KEYS = ["contract", "variance", "generator"];
   var blueprintDraftObjectSchema = external_exports.object({
     contract: dataContractSchema,
-    variance: external_exports.object({
-      persona: external_exports.string().optional(),
-      aesthetic: external_exports.string().optional(),
-      context: external_exports.record(external_exports.string(), jsonValueSchema).optional(),
-      seedPrompt: external_exports.string().optional()
-    }).strict().optional(),
+    // ONE declaration of the variance shape, protocol-wide: the same
+    // schema (with its `.describe()` teaching and its legal-set
+    // rejection message) that `blueprintMeta.variance` projects on the
+    // way back out (ggui#523 item 1 — the mirror-of-a-mirror is gone).
+    variance: blueprintVarianceSchema.optional(),
     generator: external_exports.string().optional()
+  }, {
+    error: (issue2) => issue2.code === "unrecognized_keys" ? `blueprintDraft: unknown key(s) ${issue2.keys.map((k) => JSON.stringify(k)).join(", ")} \u2014 a draft is EXACTLY {${BLUEPRINT_DRAFT_KEYS.join(", ")}}; \`intent\` is a top-level ggui_handshake field, not a draft field, and the four specs live INSIDE \`contract\`` : void 0
   }).strict();
   var blueprintDraftSchema = blueprintDraftObjectSchema;
   var blueprintMetaSchema = external_exports.object({
@@ -42827,6 +42844,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     sessionId: external_exports.string().min(1).describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render.")
   };
   var getSessionInputSchema = external_exports.object(getSessionInputShape);
+  var getRenderSourceInputShape = {
+    sessionId: external_exports.string().min(1).describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render.")
+  };
+  var getRenderSourceInputSchema = external_exports.object(getRenderSourceInputShape);
   var listFeaturedBlueprintsInputShape = {};
   var listFeaturedBlueprintsInputSchema = external_exports.object(listFeaturedBlueprintsInputShape);
   var searchBlueprintsInputShape = {
@@ -42861,7 +42882,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
      * and the contract validators; variance feeds the variance axis
      * and rides through to the suggestion's `blueprintMeta`.
      */
-    blueprintDraft: blueprintDraftSchema.describe("Agent's draft: contract (required) + optional variance + optional generator slug hint. The server combines this with cached blueprints + validator outcomes to produce a three-mode suggestion (cache / agent / synth)."),
+    blueprintDraft: blueprintDraftSchema.describe(`Agent's draft \u2014 a JSON OBJECT, never a JSON-encoded string (pass {contract: {...}}, not "{\\"contract\\":...}"; a string fails input validation with -32602). Fields: contract (required) + optional variance + optional generator slug hint. The server combines this with cached blueprints + validator outcomes to produce a three-mode suggestion (cache / agent / synth).`),
     /**
      * Skip blueprint-search on step-2 and route straight to validation
      * + (if validation passes) agent-mode suggestion against the draft.
@@ -42961,10 +42982,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     "PRODUCTION_FAILED",
     "VALIDATION_ERROR",
     "NO_PLATFORM_KEY",
-    "NO_CREDENTIALS"
+    "NO_CREDENTIALS",
+    "GENERATION_QUEUE_OVERLOADED"
   ]);
   var renderErrorSchema = external_exports.object({
-    code: renderErrorCodeSchema.describe("Canonical failure class. PRODUCTION_FAILED: generation did not produce a component. VALIDATION_ERROR: a server-side precondition rejected the render before generation. NO_PLATFORM_KEY: the server's managed provider-key configuration has no key for the resolved route. NO_CREDENTIALS: no generation credentials are configured on the server."),
+    code: renderErrorCodeSchema.describe("Canonical failure class. PRODUCTION_FAILED: generation did not produce a component. VALIDATION_ERROR: a server-side precondition rejected the render before generation. NO_PLATFORM_KEY: the server's managed provider-key configuration has no key for the resolved route. NO_CREDENTIALS: no generation credentials are configured on the server. GENERATION_QUEUE_OVERLOADED: the deployment's admission gate rejected the request before generation started (queue full or wait timed out) \u2014 not a failed attempt; safe to retry immediately."),
     message: external_exports.string().describe("Human-readable failure detail \u2014 fold into the next attempt or surface to the operator.")
   });
   var resourceReadErrorCodeSchema = external_exports.enum([
@@ -43022,33 +43044,78 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       description: external_exports.string(),
       example: external_exports.string(),
       args: external_exports.object({
-        sessionId: external_exports.string()
+        sessionId: external_exports.string(),
+        // The per-call long-poll window in seconds. Carried on the hint
+        // because consume's own default is 0 (single non-blocking
+        // drain): an agent copying a timeout-less hint gets an instant
+        // empty result and stops looping.
+        timeout: external_exports.number()
       })
-    }).optional().describe("Recovery hint \u2014 when the rendered contract has actions, points the agent at ggui_consume({sessionId}) for the inbound action loop. Absent for pure-display renders.")
+    }).optional().describe("Required-next-call hint \u2014 when the rendered contract has actions, points the agent at ggui_consume({sessionId, timeout}) for the inbound action loop. Absent for pure-display renders.")
   });
   var updateInputSchema = external_exports.discriminatedUnion("kind", [
     external_exports.object({
       sessionId: external_exports.string().describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render."),
       kind: external_exports.literal("replace"),
-      props: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Full replacement props map. New map IS the new state.")
+      props: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Full replacement props map. New map IS the new state, rendered as a NEW card (a new history entry). For an in-place repaint of the mounted card use ggui_amend.")
     }).strict(),
     external_exports.object({
       sessionId: external_exports.string().describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render."),
       kind: external_exports.literal("merge"),
-      patch: external_exports.record(external_exports.string(), external_exports.unknown()).describe("RFC 7396 JSON Merge Patch \u2014 null deletes a key; arrays fully replace.")
+      patch: external_exports.record(external_exports.string(), external_exports.unknown()).describe("RFC 7396 JSON Merge Patch \u2014 null deletes a key; arrays fully replace. The merged state renders as a NEW card (a new history entry). For an in-place repaint of the mounted card use ggui_amend.")
+    }).strict()
+  ]);
+  var amendInputSchema = external_exports.discriminatedUnion("kind", [
+    external_exports.object({
+      sessionId: external_exports.string().describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render."),
+      kind: external_exports.literal("replace"),
+      props: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Full replacement props map, applied to the currently mounted card in place.")
+    }).strict(),
+    external_exports.object({
+      sessionId: external_exports.string().describe("GguiSession opaque id (UUID) \u2014 returned by ggui_render."),
+      kind: external_exports.literal("merge"),
+      patch: external_exports.record(external_exports.string(), external_exports.unknown()).describe("RFC 7396 JSON Merge Patch \u2014 null deletes a key; arrays fully replace. Applied to the currently mounted card in place.")
     }).strict()
   ]);
   var updateOutputSchema = external_exports.object({
     sessionId: external_exports.string(),
     updated: external_exports.boolean(),
     /**
-     * Unchanged from the initial render — the same `ui://ggui/render/{id}`
-     * URI the mount stamped. Mirrored on the LLM-visible structuredContent
-     * so SDKs that strip `_meta` from tool_results can still reach the
+     * The epoch-pinned URI of the NEW history record this update minted
+     * (`ui://ggui/render/{id}[/{key}]#{epoch}` — see epoch-uri.ts). On a
+     * no-op (`updated: false`) no record is minted and this is the bare
+     * live-head URI. Mirrored on the LLM-visible structuredContent so
+     * SDKs that strip `_meta` from tool_results can still reach the
      * mount URI. Kept in sync with the update handler's wire shape —
      * this export and the handler's inline schema must not drift.
      */
-    resourceUri: external_exports.string()
+    resourceUri: external_exports.string(),
+    /**
+     * The session's head epoch after this call: advanced by one on a
+     * real update (`updated: true`), unchanged on a no-op. `ggui_render`
+     * mints epoch 0. The session ROW is the authority
+     * (`GguiSessionBase.epoch`, absent ⇒ 0); the ledger's `ui.reminted`
+     * events are the wire signal only — the ledger is horizon-bounded
+     * and must never be counted as the source of truth.
+     */
+    epoch: external_exports.number().int().min(0),
+    /**
+     * Present ONLY on a no-op (`updated: false`): the patch conformed to
+     * the contract but left the final props semantically identical to
+     * the current state, so nothing was written, nothing changes on
+     * screen, and NO new history record was minted. Model-visible by
+     * design — the common producer of a no-op is an agent echoing
+     * existing props back believing it changed the UI, and this field is
+     * its feedback channel.
+     */
+    warning: external_exports.string().optional()
+  });
+  var amendOutputSchema = external_exports.object({
+    sessionId: external_exports.string(),
+    updated: external_exports.boolean(),
+    resourceUri: external_exports.string(),
+    /** Same no-op feedback channel as ggui_update's `warning`. */
+    warning: external_exports.string().optional()
   });
   var declareToolCatalogInputSchema = external_exports.object({
     toolCatalog: external_exports.record(external_exports.string(), external_exports.object({ name: external_exports.string(), version: external_exports.string().optional() }).strict()).describe("Per-app canonical tool identities: bare tool name -> its server's initialize-declared serverInfo. Host/library-supplied; not an agent action.")
@@ -43057,6 +43124,45 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     saved: external_exports.boolean(),
     appId: external_exports.string()
   }).strict();
+  var RUNTIME_PULL_MAX_LIMIT = 100;
+  var RUNTIME_PULL_MAX_WAIT_SECONDS = 20;
+  var gguiSessionEventSchema = external_exports.object({
+    seq: external_exports.number().int().min(1).describe('Monotonic, gap-free per render; starts at 1 (0 is the "no events yet" cursor sentinel, never an event).'),
+    type: external_exports.string().min(1).describe("Wire-frame type \u2014 see the canonical GguiSessionEventType taxonomy; plain string so servers can mint new types without a protocol bump."),
+    timestamp: external_exports.string().describe("ISO 8601 UTC timestamp the server stamped on emission."),
+    data: external_exports.unknown().describe("Type-specific payload \u2014 structurally identical to the matching live-channel frame payload.")
+  });
+  var runtimePullInputShape = {
+    sessionId: external_exports.string().min(1).describe('Active render id \u2014 sourced from `_meta["ai.ggui/render"].sessionId` on the iframe boot envelope. Unknown and cross-tenant ids surface uniformly as session_not_found.'),
+    sinceSequence: external_exports.number().int().min(0).optional().describe("Replay cursor \u2014 only events with seq > sinceSequence return. Omit (= 0) on first pull; advance to the last event's seq (or lastSequence on an empty page) on every subsequent pull."),
+    limit: external_exports.number().int().min(1).optional().describe(`Max events per page. Values above ${RUNTIME_PULL_MAX_LIMIT} are clamped to ${RUNTIME_PULL_MAX_LIMIT}; omit for the default ${RUNTIME_PULL_MAX_LIMIT}. When hasMore is true, immediately re-pull with the advanced cursor.`),
+    wait: external_exports.number().min(0).optional().describe(`Subscription-mode hold, in seconds. When set and the cursor page is empty, the server holds this call until an event lands or the hold elapses (values above ${RUNTIME_PULL_MAX_WAIT_SECONDS} are clamped to ${RUNTIME_PULL_MAX_WAIT_SECONDS}). An empty page after a full hold is a NORMAL result \u2014 immediately re-pull to stay subscribed, or back off to sparse un-held pulls after a few consecutive empties. Omit (= 0) for an immediate return.`)
+  };
+  var runtimePullInputSchema = external_exports.object(runtimePullInputShape);
+  var runtimePullEventsPageSchema = external_exports.object({
+    events: external_exports.array(gguiSessionEventSchema),
+    lastSequence: external_exports.number().int().min(0),
+    hasMore: external_exports.boolean()
+  });
+  var runtimePullHorizonSchema = external_exports.object({
+    reason: external_exports.literal("REPLAY_HORIZON_PASSED"),
+    currentSequence: external_exports.number().int().min(0)
+  });
+  var runtimePullOutputSchema = external_exports.union([
+    runtimePullEventsPageSchema,
+    runtimePullHorizonSchema
+  ]);
+  var RUNTIME_TELEMETRY_MAX_EVENTS = 40;
+  var runtimeTelemetryInputShape = {
+    sessionId: external_exports.string().min(1).describe("Render id the report concerns \u2014 sourced from the boot envelope. Client-claimed: used as a log tag only."),
+    events: external_exports.array(external_exports.object({
+      at: external_exports.number().min(0).describe("Milliseconds since iframe boot (monotonic, client clock)."),
+      kind: external_exports.string().min(1).max(64).describe("Event name \u2014 e.g. 'boot.path', 'status.connected', 'channel_failover_swap', 'doorbell.ring'."),
+      detail: external_exports.string().max(512).optional().describe("Optional compact context (JSON fragment or message).")
+    })).min(1).max(RUNTIME_TELEMETRY_MAX_EVENTS).describe("Batched ladder/doorbell events, oldest first.")
+  };
+  var runtimeTelemetryInputSchema = external_exports.object(runtimeTelemetryInputShape);
+  var runtimeTelemetryOutputSchema = external_exports.object({ ok: external_exports.literal(true) });
 
   // ../protocol/dist/schemas/invoke.js
   var textBlockSchema = external_exports.object({
@@ -43182,87 +43288,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   // ../protocol/dist/registry/canonicalize-contract.js
   var import_canonicalize = __toESM(require_canonicalize(), 1);
 
+  // ../protocol/dist/validation/enforced-props-schema.js
+  var import_canonicalize2 = __toESM(require_canonicalize(), 1);
+
   // ../protocol/dist/types/data-contract.js
   var CONTEXT_SLOT_VALUE_MAX_BYTES = 16 * 1024;
   var CONTEXT_SNAPSHOT_MAX_BYTES = 64 * 1024;
 
-  // ../protocol/dist/schemas/ops-blueprint.js
-  var opsGenerateBlueprintInputSchema = external_exports.object({
-    contract: dataContractSchema,
-    generator: external_exports.string().min(1).optional().describe("Generator slug (e.g. `ui-gen-default-haiku-4-5`). When omitted, dispatches through `GeneratorRegistry.defaultGenerator()`."),
-    persona: external_exports.string().optional().describe("Free-form persona tag (e.g. 'minimalist', 'data-dense'). Normalized via lowercase+trim before persistence; logged as a warning when within Levenshtein distance < 2 of an existing tag for the same appId."),
-    aesthetic: external_exports.string().optional().describe("Free-form aesthetic tag (e.g. 'glassmorphic', 'brutalist', 'editorial'). Persisted on `Blueprint.variance.aesthetic`. Distinct from persona \u2014 persona names the user mental model; aesthetic names the visual treatment."),
-    context: external_exports.record(external_exports.string(), jsonValueSchema).optional().describe("Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`."),
-    seedPrompt: external_exports.string().optional().describe("The raw operator prompt that produced this variant. Round-trip input for the variant-selector + audit trail."),
-    setAsOperatorDefault: external_exports.boolean().optional().describe("When true, pins the new blueprint as the operator default for its `(appId, contractHash)` group, clearing any prior default in the same group.")
-  }).strict();
-  var opsGenerateBlueprintOutputSchema = external_exports.object({
-    blueprintId: external_exports.string().min(1),
-    codeHash: external_exports.string().optional().describe("Content hash of the generated code body. Absent when the generator returned a non-`ok` result and persistence skipped \u2014 the failure mode is surfaced through generator-level error reporting elsewhere."),
-    validatorScore: external_exports.number().min(0).max(1).optional().describe("Advanced generator's iterative-loop validator score (0-1). Absent for default-generator output."),
-    source: llmBlueprintSourceSchema.describe("Provenance stamped on the persisted `Blueprint.source` \u2014 always the `llm` arm on this path: `generator` is the engine slug the dispatch resolved to (stamped from the engine's own metadata claim); `model` is the LLM model id the engine called.")
-  }).strict();
-  var opsRegisterBlueprintInputSchema = external_exports.object({
-    contract: dataContractSchema,
-    componentCode: external_exports.string().min(1).describe("Verbatim component-code body to persist. Stored as-is \u2014 no LLM call, no validator pass. Operator owns correctness; the handler computes the canonical sha256 codeHash and routes the bytes through the same persistence seams as `*_generate_*`."),
-    persona: external_exports.string().optional().describe("Free-form persona tag (e.g. 'minimalist', 'data-dense'). Normalized via lowercase+trim before persistence; logged as a warning when within Levenshtein distance < 2 of an existing tag for the same appId."),
-    aesthetic: external_exports.string().optional().describe("Free-form aesthetic tag. Persisted on `Blueprint.variance.aesthetic`."),
-    context: external_exports.record(external_exports.string(), jsonValueSchema).optional().describe("Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`."),
-    seedPrompt: external_exports.string().optional().describe("Optional originating prompt for audit + round-tripping (e.g. the prose the operator originally fed into `*_generate_*` before exporting)."),
-    setAsOperatorDefault: external_exports.boolean().optional().describe("When true, pins the new blueprint as the operator default for its `(appId, contractHash)` group, clearing any prior default in the same group.")
-  }).strict();
-  var opsRegisterBlueprintOutputSchema = external_exports.object({
-    blueprintId: external_exports.string().min(1),
-    codeHash: external_exports.string().min(1).describe("Content hash of the persisted code body (full sha256 hex)."),
-    source: userBlueprintSourceSchema.describe('Provenance stamped on the persisted `Blueprint.source` \u2014 always `{kind: "user"}` on this path: operator-supplied bytes, no LLM dispatch, no engine claim to record.')
-  }).strict();
-  var opsListBlueprintsInputSchema = external_exports.object({
-    contractHash: external_exports.string().min(1).optional().describe("Filter to a single `(appId, contractHash)` group. Combine with `generator` / `persona` to narrow within the group."),
-    generator: external_exports.string().min(1).optional().describe('Filter to engine-generated blueprints (`source.kind === "llm"`) whose `source.generator` equals this slug. `user`-sourced rows never match (they carry no engine provenance).'),
-    persona: external_exports.string().optional().describe("Filter on `variance.persona`. Normalized to match persisted form (lowercase+trim)."),
-    intentKeywords: external_exports.array(external_exports.string().min(1)).optional().describe("Semantic-search tokens. When set, dispatches through `BlueprintSearch.search()` rather than indexed `list()`.")
-  }).strict();
-  var opsListBlueprintsOutputSchema = external_exports.object({
-    blueprints: external_exports.array(blueprintSchema)
-  }).strict();
-  var opsUpdateBlueprintInputSchema = external_exports.object({
-    blueprintId: external_exports.string().min(1),
-    isOperatorDefault: external_exports.literal(true).optional().describe("When `true`, pins this blueprint as the operator default for its `(appId, contractHash)` group. Clears any prior default. Cannot set to `false` \u2014 to unpin, set another blueprint in the same group as default, or delete this one."),
-    variance: blueprintVarianceSchema.optional().describe('Partial-merge into the existing variance. Supplied keys overwrite; omitted keys preserve. Pass `{persona: ""}` to clear a persona (handler treats empty string as removal).')
-  }).strict();
-  var opsUpdateBlueprintOutputSchema = external_exports.object({
-    blueprintId: external_exports.string().min(1),
-    updatedAt: external_exports.string().min(1)
-  }).strict();
-  var opsDeleteBlueprintInputSchema = external_exports.object({
-    blueprintId: external_exports.string().min(1)
-  }).strict();
-  var opsDeleteBlueprintOutputSchema = external_exports.object({
-    deleted: external_exports.literal(true)
-  }).strict();
-
-  // ../protocol/dist/envelopes/builders.js
-  function resolveSchemaVersion(parts) {
-    if ("schemaVersion" in parts) {
-      return parts.schemaVersion;
-    }
-    return PROTOCOL_SCHEMA_VERSION;
-  }
-  function makeActionEnvelope(parts) {
-    const envelope = {
-      sessionId: parts.sessionId,
-      type: parts.type
-    };
-    if (parts.payload !== void 0)
-      envelope.payload = parts.payload;
-    if (parts.clientSeq !== void 0)
-      envelope.clientSeq = parts.clientSeq;
-    const stamp = resolveSchemaVersion(parts);
-    if (stamp !== void 0)
-      envelope.schemaVersion = stamp;
-    return envelope;
-  }
-
   // ../protocol/dist/validation/ajv-runtime.js
   var import_ajv = __toESM(require_ajv(), 1);
   var import_ajv_formats = __toESM(require_dist(), 1);
@@ -43305,8 +43337,20 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   if (!standaloneAjv.getKeyword("nullable")) {
     standaloneAjv.addKeyword({ keyword: "nullable" });
   }
+  var standaloneCjsAjv = new import_ajv.default({
+    ...AJV_OPTIONS,
+    code: { source: true }
+  });
+  (0, import_ajv_formats.default)(standaloneCjsAjv);
+  if (!standaloneCjsAjv.getKeyword("example")) {
+    standaloneCjsAjv.addKeyword({ keyword: "example" });
+  }
+  if (!standaloneCjsAjv.getKeyword("nullable")) {
+    standaloneCjsAjv.addKeyword({ keyword: "nullable" });
+  }
   function injectClosedShape(schema) {
-    const isObjectNode = schema.type === "object" || schema.properties !== void 0;
+    const typeSet = new Set(Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : []);
+    const isObjectNode = typeSet.has("object") || schema.properties !== void 0;
     if (isObjectNode) {
       const out = { ...schema };
       if (out.properties) {
@@ -43327,7 +43371,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
         out.anyOf = out.anyOf.map(injectClosedShape);
       return out;
     }
-    if (schema.type === "array" && schema.items) {
+    if (typeSet.has("array") && schema.items) {
       return { ...schema, items: injectClosedShape(schema.items) };
     }
     if (schema.oneOf || schema.anyOf) {
@@ -43347,7 +43391,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   function mapAjvErrorsToViolations(errors, data) {
     if (!errors)
       return [];
-    return errors.map((err) => mapOne(err, data));
+    return errors.map((err) => ({
+      ...mapOne(err, data),
+      ...err.keyword ? { keyword: err.keyword } : {}
+    }));
   }
   function prefixViolations(violations, prefix) {
     if (!prefix)
@@ -43694,6 +43741,88 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     return validateActionData(envelope.payload, spec, precompiledActions);
   }
 
+  // ../protocol/dist/schemas/ops-blueprint.js
+  var opsGenerateBlueprintInputSchema = external_exports.object({
+    appId: external_exports.string().min(1).optional().describe("Target app for this curation call. Defaults to the caller's bound app identity; callers not bound to an app must provide it. The deployment's authorization policy decides whether the caller may curate the named app."),
+    contract: dataContractSchema,
+    generator: external_exports.string().min(1).optional().describe("Generator slug (e.g. `ui-gen-default-haiku-4-5`). When omitted, dispatches through `GeneratorRegistry.defaultGenerator()`."),
+    persona: external_exports.string().optional().describe("Free-form persona tag (e.g. 'minimalist', 'data-dense'). Normalized via lowercase+trim before persistence; logged as a warning when within Levenshtein distance < 2 of an existing tag for the same appId."),
+    aesthetic: external_exports.string().optional().describe("Free-form aesthetic tag (e.g. 'glassmorphic', 'brutalist', 'editorial'). Persisted on `Blueprint.variance.aesthetic`. Distinct from persona \u2014 persona names the user mental model; aesthetic names the visual treatment."),
+    context: external_exports.record(external_exports.string(), jsonValueSchema).optional().describe("Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`."),
+    seedPrompt: external_exports.string().optional().describe("The raw operator prompt that produced this variant. Round-trip input for the variant-selector + audit trail."),
+    setAsOperatorDefault: external_exports.boolean().optional().describe("When true, pins the new blueprint as the operator default for its `(appId, contractHash)` group, clearing any prior default in the same group.")
+  }).strict();
+  var opsGenerateBlueprintOutputSchema = external_exports.object({
+    blueprintId: external_exports.string().min(1),
+    codeHash: external_exports.string().optional().describe("Content hash of the generated code body. Absent when the generator returned a non-`ok` result and persistence skipped \u2014 the failure mode is surfaced through generator-level error reporting elsewhere."),
+    validatorScore: external_exports.number().min(0).max(1).optional().describe("Advanced generator's iterative-loop validator score (0-1). Absent for default-generator output."),
+    source: llmBlueprintSourceSchema.describe("Provenance stamped on the persisted `Blueprint.source` \u2014 always the `llm` arm on this path: `generator` is the engine slug the dispatch resolved to (stamped from the engine's own metadata claim); `model` is the LLM model id the engine called.")
+  }).strict();
+  var opsRegisterBlueprintInputSchema = external_exports.object({
+    appId: external_exports.string().min(1).optional().describe("Target app for this curation call. Defaults to the caller's bound app identity; callers not bound to an app must provide it. The deployment's authorization policy decides whether the caller may curate the named app."),
+    contract: dataContractSchema,
+    componentCode: external_exports.string().min(1).describe("Verbatim component-code body to persist. Stored as-is \u2014 no LLM call, no validator pass. Operator owns correctness; the handler computes the canonical sha256 codeHash and routes the bytes through the same persistence seams as `*_generate_*`."),
+    persona: external_exports.string().optional().describe("Free-form persona tag (e.g. 'minimalist', 'data-dense'). Normalized via lowercase+trim before persistence; logged as a warning when within Levenshtein distance < 2 of an existing tag for the same appId."),
+    aesthetic: external_exports.string().optional().describe("Free-form aesthetic tag. Persisted on `Blueprint.variance.aesthetic`."),
+    context: external_exports.record(external_exports.string(), jsonValueSchema).optional().describe("Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`."),
+    seedPrompt: external_exports.string().optional().describe("Optional originating prompt for audit + round-tripping (e.g. the prose the operator originally fed into `*_generate_*` before exporting)."),
+    setAsOperatorDefault: external_exports.boolean().optional().describe("When true, pins the new blueprint as the operator default for its `(appId, contractHash)` group, clearing any prior default in the same group.")
+  }).strict();
+  var opsRegisterBlueprintOutputSchema = external_exports.object({
+    blueprintId: external_exports.string().min(1),
+    codeHash: external_exports.string().min(1).describe("Content hash of the persisted code body (full sha256 hex)."),
+    source: userBlueprintSourceSchema.describe('Provenance stamped on the persisted `Blueprint.source` \u2014 always `{kind: "user"}` on this path: operator-supplied bytes, no LLM dispatch, no engine claim to record.')
+  }).strict();
+  var opsListBlueprintsInputSchema = external_exports.object({
+    appId: external_exports.string().min(1).optional().describe("Target app for this curation call. Defaults to the caller's bound app identity; callers not bound to an app must provide it. The deployment's authorization policy decides whether the caller may curate the named app."),
+    contractHash: external_exports.string().min(1).optional().describe("Filter to a single `(appId, contractHash)` group. Combine with `generator` / `persona` to narrow within the group."),
+    generator: external_exports.string().min(1).optional().describe('Filter to engine-generated blueprints (`source.kind === "llm"`) whose `source.generator` equals this slug. `user`-sourced rows never match (they carry no engine provenance).'),
+    persona: external_exports.string().optional().describe("Filter on `variance.persona`. Normalized to match persisted form (lowercase+trim)."),
+    intentKeywords: external_exports.array(external_exports.string().min(1)).optional().describe("Semantic-search tokens. When set, dispatches through `BlueprintSearch.search()` rather than indexed `list()`.")
+  }).strict();
+  var opsListBlueprintsOutputSchema = external_exports.object({
+    blueprints: external_exports.array(blueprintSchema)
+  }).strict();
+  var opsUpdateBlueprintInputSchema = external_exports.object({
+    appId: external_exports.string().min(1).optional().describe("Target app for this curation call. Defaults to the caller's bound app identity; callers not bound to an app must provide it. The deployment's authorization policy decides whether the caller may curate the named app. Must match the app the addressed blueprint belongs to."),
+    blueprintId: external_exports.string().min(1),
+    isOperatorDefault: external_exports.literal(true).optional().describe("When `true`, pins this blueprint as the operator default for its `(appId, contractHash)` group. Clears any prior default. Cannot set to `false` \u2014 to unpin, set another blueprint in the same group as default, or delete this one."),
+    variance: blueprintVarianceSchema.optional().describe('Partial-merge into the existing variance. Supplied keys overwrite; omitted keys preserve. Pass `{persona: ""}` to clear a persona (handler treats empty string as removal).')
+  }).strict();
+  var opsUpdateBlueprintOutputSchema = external_exports.object({
+    blueprintId: external_exports.string().min(1),
+    updatedAt: external_exports.string().min(1)
+  }).strict();
+  var opsDeleteBlueprintInputSchema = external_exports.object({
+    appId: external_exports.string().min(1).optional().describe("Target app for this curation call. Defaults to the caller's bound app identity; callers not bound to an app must provide it. The deployment's authorization policy decides whether the caller may curate the named app. Must match the app the addressed blueprint belongs to."),
+    blueprintId: external_exports.string().min(1)
+  }).strict();
+  var opsDeleteBlueprintOutputSchema = external_exports.object({
+    deleted: external_exports.literal(true)
+  }).strict();
+
+  // ../protocol/dist/envelopes/builders.js
+  function resolveSchemaVersion(parts) {
+    if ("schemaVersion" in parts) {
+      return parts.schemaVersion;
+    }
+    return PROTOCOL_SCHEMA_VERSION;
+  }
+  function makeActionEnvelope(parts) {
+    const envelope = {
+      sessionId: parts.sessionId,
+      type: parts.type
+    };
+    if (parts.payload !== void 0)
+      envelope.payload = parts.payload;
+    if (parts.clientSeq !== void 0)
+      envelope.clientSeq = parts.clientSeq;
+    const stamp = resolveSchemaVersion(parts);
+    if (stamp !== void 0)
+      envelope.schemaVersion = stamp;
+    return envelope;
+  }
+
   // ../wire/dist/contract.js
   var ClientContractViolationError = class extends Error {
     direction;
@@ -46764,19 +46893,26 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   function globalExpr(gguiKey, legacyName) {
     return `(globalThis.__ggui__&&globalThis.__ggui__["${gguiKey}"]||window["${legacyName}"])`;
   }
-  function buildDataUrlReactShim(globalName) {
+  function toDataUrl(js) {
+    return `data:text/javascript,${encodeURIComponent(js)}`;
+  }
+  function jsReactShim(globalName) {
     const namedExports = REACT_EXPORTS.map((e) => `export const ${e} = R.${e};`).join(" ");
     const resolve = globalExpr("react", globalName);
-    const js = `const R = ${resolve}; export default R; ${namedExports}`;
-    return `data:text/javascript,${encodeURIComponent(js)}`;
+    return `const R = ${resolve}; export default R; ${namedExports}`;
   }
-  function buildDataUrlReactDomShim() {
+  function buildDataUrlReactShim(globalName) {
+    return toDataUrl(jsReactShim(globalName));
+  }
+  function jsReactDomShim() {
     const REACT_DOM_EXPORTS = ["createPortal", "flushSync", "unstable_batchedUpdates"];
     const namedExports = REACT_DOM_EXPORTS.map((e) => `export const ${e} = D.${e};`).join(" ");
-    const js = `const D = globalThis.__ggui__["reactDom"]; export default D; ${namedExports}`;
-    return `data:text/javascript,${encodeURIComponent(js)}`;
+    return `const D = globalThis.__ggui__["reactDom"]; export default D; ${namedExports}`;
   }
-  function buildDataUrlJsxShim(globalName) {
+  function buildDataUrlReactDomShim() {
+    return toDataUrl(jsReactDomShim());
+  }
+  function jsJsxShim(globalName) {
     const resolve = globalExpr("react", globalName);
     const js = [
       `const R = ${resolve};`,
@@ -46789,9 +46925,12 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       `export{jsx,jsx as jsxs,jsx as jsxDEV};`,
       `export const Fragment=R.Fragment;`
     ].join("");
-    return `data:text/javascript,${encodeURIComponent(js)}`;
+    return js;
   }
-  function buildDataUrlGlobalShim(globalName, gguiKey, exportNames, fallbackGlobals, fallbackGguiKeys) {
+  function buildDataUrlJsxShim(globalName) {
+    return toDataUrl(jsJsxShim(globalName));
+  }
+  function jsGlobalShim(globalName, gguiKey, exportNames, fallbackGlobals, fallbackGguiKeys) {
     if (exportNames && exportNames.length > 0) {
       const globals = [globalName, ...fallbackGlobals || []];
       const gguiKeys = [gguiKey, ...fallbackGguiKeys || []];
@@ -46802,17 +46941,20 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       ));
       const mergeExpr = resolveExprs.join(",");
       const named = exportNames.map((n) => `export const ${n} = M["${n}"];`).join(" ");
-      const js2 = resolveExprs.length > 1 ? `const M = Object.assign({}, ${mergeExpr}); ${named} export default M;` : `const M = ${resolveExprs[0]}; ${named} export default M;`;
-      return `data:text/javascript,${encodeURIComponent(js2)}`;
+      return resolveExprs.length > 1 ? `const M = Object.assign({}, ${mergeExpr}); ${named} export default M;` : `const M = ${resolveExprs[0]}; ${named} export default M;`;
     }
     const resolve = globalExpr(gguiKey, globalName);
-    const js = `const M = ${resolve} || {}; const handler = { get(_, key) { return M[key]; } }; export default new Proxy({}, handler);`;
-    return `data:text/javascript,${encodeURIComponent(js)}`;
+    return `const M = ${resolve} || {}; const handler = { get(_, key) { return M[key]; } }; export default new Proxy({}, handler);`;
   }
-  function buildDataUrlWireShim() {
+  function buildDataUrlGlobalShim(globalName, gguiKey, exportNames, fallbackGlobals, fallbackGguiKeys) {
+    return toDataUrl(jsGlobalShim(globalName, gguiKey, exportNames, fallbackGlobals, fallbackGguiKeys));
+  }
+  function jsWireShim() {
     const named = WIRE_EXPORTS.map((e) => `export const ${e} = w.${e};`).join(" ");
-    const js = `const w = globalThis.__ggui__.wire; ${named} export default w;`;
-    return `data:text/javascript,${encodeURIComponent(js)}`;
+    return `const w = globalThis.__ggui__.wire; ${named} export default w;`;
+  }
+  function buildDataUrlWireShim() {
+    return toDataUrl(jsWireShim());
   }
   function extractNamedImports(code, specifier) {
     const esc2 = specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -46829,7 +46971,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     }
     return [...names];
   }
-  function buildGadgetPackageShim(packageName, exportNames) {
+  function jsGadgetPackageShim(packageName, exportNames) {
     const pkgLit = JSON.stringify(packageName);
     const hasComponent = exportNames.some((n) => /^[A-Z]/.test(n));
     const parts = [];
@@ -46846,7 +46988,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       parts.push(`export const ${name}=${factory}(${JSON.stringify(name)});`);
     }
     parts.push(`export default new Proxy({},{get:function(_,k){return NS()[k];}});`);
-    return `data:text/javascript,${encodeURIComponent(parts.join(""))}`;
+    return parts.join("");
+  }
+  function buildGadgetPackageShim(packageName, exportNames) {
+    return toDataUrl(jsGadgetPackageShim(packageName, exportNames));
   }
   function rewriteDataUrl(code, opts) {
     const reactGlobal = opts.reactGlobal ?? "__REACT";
@@ -46881,6 +47026,29 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     }
     return code;
   }
+  var ASSET_SHIM_FOR_SPECIFIER = {
+    "react/jsx-runtime": "jsx-runtime",
+    "react/jsx-dev-runtime": "jsx-runtime",
+    "react-dom": "react-dom",
+    react: "react",
+    "@ggui-ai/design/primitives": "primitives",
+    "@ggui-ai/design/components": "components",
+    "@ggui-ai/design/compositions": "compositions",
+    "@ggui-ai/design/interact": "interact",
+    "@ggui-ai/design/templates": "templates",
+    "@ggui-ai/design/app-components": "app-components",
+    "@ggui-ai/design/tokens": "tokens",
+    "@ggui-ai/design": "design",
+    "@ggui-ai/wire": "wire",
+    "@ggui-ai/gadgets": "gadgets"
+  };
+  function rewriteAssetUrl(code, opts) {
+    const base = opts.shimBaseUrl.replace(/\/$/, "");
+    for (const [specifier, shimName] of Object.entries(ASSET_SHIM_FOR_SPECIFIER)) {
+      code = replaceSpecifier(code, specifier, `${base}/${shimName}.js`);
+    }
+    return code;
+  }
   function rewriteImportmap(code, opts) {
     const base = opts.reactBaseUrl ?? "https://esm.sh/react@18.2.0";
     code = replaceSpecifier(code, "react/jsx-runtime", `${base}/jsx-runtime`);
@@ -46894,6 +47062,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
         return rewriteDataUrl(code, options);
       case "importmap":
         return rewriteImportmap(code, options);
+      case "asset-url":
+        return rewriteAssetUrl(code, options);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-visual-tester",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Behavioral validator for ggui-generated component code. Renders a component in real Chromium via Playwright, clicks each action declared in its contract, and verifies the action actually does something — mutating bound state or dispatching to the agent. Catches buttons wired to no-op handlers that structural validators miss. Playwright is an optional peer dependency, injected by the caller.",
   "keywords": [
     "ggui",
@@ -48,9 +48,9 @@
   "dependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@ggui-ai/design": "0.8.0",
-    "@ggui-ai/wire": "0.8.0",
-    "@ggui-ai/protocol": "0.8.0"
+    "@ggui-ai/protocol": "0.10.0",
+    "@ggui-ai/wire": "0.10.0",
+    "@ggui-ai/design": "0.10.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",