@ggui-ai/mcp-server-handlers 0.1.0-rc.1

package/dist/app-discovery/list-themes.js

@@ -0,0 +1,80 @@
+/**
+ * `ggui_list_themes` — per-app theme catalog discovery tool.
+ *
+ * Returns the list of `ThemeEntry` records the app exposes — every
+ * registered preset by default, or an operator-curated filter when
+ * `App.availableThemeIds` is set. Lets the agent reason about visual
+ * style ("calming" vs "urgent" vs "marketing") by reading descriptions
+ * instead of guessing at preset ids.
+ *
+ * ## Behavior
+ *
+ *   1. Validates input shape (`{appId?: string}`). Cross-tenant
+ *      access protected the same way as `ggui_list_gadgets`.
+ *   2. Reads the global theme catalog via the bound `themes` dep
+ *      (a `() => readonly ThemeCatalogEntry[]` resolver — keeps the
+ *      handler design-package-agnostic).
+ *   3. If `app.availableThemeIds` is set, filters the catalog to just
+ *      those ids; otherwise returns the full catalog.
+ *
+ * ## Audience
+ *
+ * `['agent']` — registered on `/mcp`. Agent-callable anytime; pair
+ * with `ggui_new_session({themeId})` or `ggui_push({themeId})` to
+ * apply a chosen theme.
+ */
+import { z } from 'zod';
+import { AppAccessDeniedError } from './errors.js';
+const inputSchema = {
+    appId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('App id whose theme catalog to return. Defaults to the caller-resolved app id from the auth header. Cross-tenant requests fail with app_access_denied.'),
+};
+/**
+ * Wire shape for a single theme entry. Mirrors `@ggui-ai/design`'s
+ * `ThemeEntry` but kept local so this handler doesn't pull the design
+ * package as a hard dep — the caller passes the catalog via the
+ * `themes` resolver and is responsible for whatever upstream shape
+ * produces it.
+ */
+const themeEntryWireSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    description: z.string(),
+    modes: z.array(z.enum(['light', 'dark'])),
+})
+    .passthrough();
+const outputSchema = {
+    themes: z.array(themeEntryWireSchema),
+};
+export function createGguiListThemesHandler(deps) {
+    return {
+        name: 'ggui_list_themes',
+        title: 'List themes',
+        audience: ['agent'],
+        description: "List visual themes the agent may apply to a session via `ggui_new_session({themeId})` or `ggui_push({themeId})`. Each entry carries an `id` (pass to themeId), `name` (human-readable), `description` (agent-readable: e.g. 'warm marketing palette', 'high-contrast scientific dashboard'), and `modes` (light/dark variants the theme ships). Call this when the user's intent suggests a visual style choice — pick the theme whose description best matches the requested aesthetic. Operator-scoped: returns the per-app allowlist when one is configured, otherwise the full registered catalog.",
+        inputSchema,
+        outputSchema,
+        async handler(rawInput, ctx) {
+            const parsed = z.object(inputSchema).parse(rawInput);
+            const resolvedAppId = parsed.appId ?? ctx.appId;
+            if (parsed.appId !== undefined && parsed.appId !== ctx.appId) {
+                throw new AppAccessDeniedError();
+            }
+            const app = await deps.appMetadataStore.get(resolvedAppId);
+            const catalog = deps.themes();
+            // Filter when allowlist is configured. Preserves catalog order
+            // (so the picker UI stays stable) and silently drops ids that
+            // appear in the allowlist but aren't registered (defensive
+            // against operator typos — agent still sees a working list).
+            if (app?.availableThemeIds && app.availableThemeIds.length > 0) {
+                const allowed = new Set(app.availableThemeIds);
+                return { themes: catalog.filter((t) => allowed.has(t.id)) };
+            }
+            return { themes: catalog };
+        },
+    };
+}

package/dist/blueprints/describe-blueprint-format.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `ggui_describe_blueprint_format` — wire-format documentation for the
+ * blueprint envelope `ggui_ops_generate_blueprint` and `ggui_protocol_validate_blueprint`
+ * accept.
+ *
+ * Pure compute, no DDB. Returns a markdown explainer + a minimum-viable
+ * example. Pinning the format server-side guards against Claude
+ * composing from stale training-data assumptions about the shape.
+ */
+import { z } from 'zod';
+import type { SharedHandler } from '../types.js';
+declare const inputSchema: {};
+declare const outputSchema: {
+    format: z.ZodLiteral<"AgentBlueprint">;
+    documentation: z.ZodString;
+    example: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+};
+interface DescribeBlueprintFormatOutput {
+    readonly format: 'AgentBlueprint';
+    readonly documentation: string;
+    readonly example: Record<string, unknown>;
+}
+export declare function createDescribeBlueprintFormatHandler(): SharedHandler<typeof inputSchema, typeof outputSchema, DescribeBlueprintFormatOutput>;
+export {};
+//# sourceMappingURL=describe-blueprint-format.d.ts.map

package/dist/blueprints/describe-blueprint-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-blueprint-format.d.ts","sourceRoot":"","sources":["../../src/blueprints/describe-blueprint-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAA,MAAM,WAAW,IAAK,CAAC;AAEvB,QAAA,MAAM,YAAY;;;;CAIjB,CAAC;AAEF,UAAU,6BAA6B;IACrC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AA6GD,wBAAgB,oCAAoC,IAAI,aAAa,CACnE,OAAO,WAAW,EAClB,OAAO,YAAY,EACnB,6BAA6B,CAC9B,CAiBA"}

package/dist/blueprints/describe-blueprint-format.js

@@ -0,0 +1,138 @@
+/**
+ * `ggui_describe_blueprint_format` — wire-format documentation for the
+ * blueprint envelope `ggui_ops_generate_blueprint` and `ggui_protocol_validate_blueprint`
+ * accept.
+ *
+ * Pure compute, no DDB. Returns a markdown explainer + a minimum-viable
+ * example. Pinning the format server-side guards against Claude
+ * composing from stale training-data assumptions about the shape.
+ */
+import { z } from 'zod';
+const inputSchema = {};
+const outputSchema = {
+    format: z.literal('AgentBlueprint'),
+    documentation: z.string(),
+    example: z.record(z.string(), z.unknown()),
+};
+const DOCUMENTATION = `# AgentBlueprint format
+
+The wire shape every blueprint authoring tool consumes:
+
+\`\`\`ts
+interface AgentBlueprint {
+  /** TSX source for the React component. MUST \`export default\` a component. */
+  source: string;
+
+  /**
+   * DataContract envelope describing the component's wire surface
+   * (propsSpec / actionSpec / contextSpec / streamSpec /
+   * agentCapabilities / clientCapabilities). Optional — without it,
+   * the runtime probe
+   * skips and you only get compile + self-check tier validation.
+   * Strongly recommended. Get the full contract format via
+   * \`ggui_protocol_describe_data_contract_format\`.
+   */
+  contract?: DataContract;
+
+  /**
+   * Optional concrete props to render with during the runtime probe.
+   * Must match \`contract.propsSpec\` shape. Defaults to mockup props
+   * synthesized from the prop schema when omitted.
+   */
+  fixtureProps?: Record<string, JsonValue>;
+}
+\`\`\`
+
+## Field semantics
+
+- **\`source\`** is plain TSX — no preamble, no markdown fence.
+  Imports allowed: \`react\`, \`@ggui-ai/design/primitives\`,
+  \`@ggui-ai/design/components\`, \`@ggui-ai/design/compositions\`.
+  No external libraries, no \`fetch\`, no \`eval\`.
+- **\`contract\`** is the same object \`defineContract({ ... } as const)\`
+  produces in path-(a) generation. Pass the literal — \`defineContract\`
+  is a TypeScript-only inference helper, not a runtime transform.
+- **\`fixtureProps\`** is informational for the probe. It does NOT ride
+  onto the persisted blueprint — the user's runtime data fills props
+  at render time.
+
+## Composition workflow
+
+1. Call \`ggui_protocol_describe_data_contract_format\` to learn the contract shape.
+2. Compose your contract object.
+3. Call \`ggui_protocol_get_blueprint_boilerplate({ contract, intent?, shell?, screen? })\`
+   for a typed scaffold.
+4. Modify the source for user intent.
+5. Call \`ggui_protocol_validate_blueprint({ source, contract, fixtureProps? })\` —
+   iterate until \`valid: true\`.
+6. Call \`ggui_ops_generate_blueprint({ name, blueprint, description?, tags? })\`.
+
+## Validation tiers
+
+\`ggui_protocol_validate_blueprint\` runs three tiers in order, short-circuiting on
+the first failure:
+
+| Tier | Check | What fails |
+|------|-------|------------|
+| 1 | \`compile\` | esbuild transform — syntax / import errors |
+| 2 | \`selfCheck\` | default-export presence + prop coverage |
+| 3 | \`runtime\` | happy-dom probe — action wiring, tool calls, prop usage |
+
+Read \`failedAt\` on the result to know which tier stopped.`;
+const EXAMPLE = {
+    source: `import { Card, Stack, Text, Button } from '@ggui-ai/design/primitives';
+import { useAction } from '@ggui-ai/wire';
+
+interface Props {
+  greeting: string;
+}
+
+export default function Hello(props: Props) {
+  const dismiss = useAction<void>('dismiss');
+  return (
+    <Card>
+      <Stack gap={2}>
+        <Text size="lg">{props.greeting}</Text>
+        <Button onClick={() => dismiss()}>Dismiss</Button>
+      </Stack>
+    </Card>
+  );
+}`,
+    contract: {
+        propsSpec: {
+            properties: {
+                greeting: {
+                    schema: { type: 'string' },
+                    required: true,
+                    description: 'Salutation text shown in the card.',
+                },
+            },
+        },
+        actionSpec: {
+            dismiss: {
+                label: 'Dismiss',
+                description: 'User dismissed the greeting.',
+            },
+        },
+    },
+    fixtureProps: {
+        greeting: 'Hello, world',
+    },
+};
+export function createDescribeBlueprintFormatHandler() {
+    return {
+        name: 'ggui_protocol_describe_blueprint_format',
+        title: 'Describe blueprint format',
+        audience: ['protocol'],
+        description: "Returns the wire-format spec for the AgentBlueprint envelope — the shape `ggui_protocol_validate_blueprint` and `ggui_ops_generate_blueprint` accept. Includes field semantics, the composition workflow (which tools to call in what order), the three validation tiers, and a minimum-viable example. **Call this first** when composing a blueprint in a fresh conversation, alongside `ggui_protocol_describe_data_contract_format` for the contract sub-shape. Tools you'll then call: `ggui_protocol_get_blueprint_boilerplate` (scaffold) → `ggui_protocol_validate_blueprint` (check) → `ggui_ops_generate_blueprint` (save).",
+        inputSchema,
+        outputSchema,
+        async handler() {
+            return {
+                format: 'AgentBlueprint',
+                documentation: DOCUMENTATION,
+                example: EXAMPLE,
+            };
+        },
+    };
+}

package/dist/blueprints/describe-data-contract-format.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `ggui_describe_data_contract_format` — wire-format documentation for
+ * the DataContract envelope inside an AgentBlueprint.
+ *
+ * Pure compute, no DDB. Returns markdown explainer + 2-3 examples
+ * covering common shapes (display-only / collect-form / chat).
+ * Pinning the format server-side guards against contract drift between
+ * what Claude composes and what `ggui_protocol_validate_blueprint` expects.
+ */
+import { z } from 'zod';
+import type { SharedHandler } from '../types.js';
+declare const inputSchema: {};
+declare const outputSchema: {
+    format: z.ZodLiteral<"DataContract">;
+    documentation: z.ZodString;
+    examples: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        contract: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+};
+interface DescribeDataContractFormatOutput {
+    readonly format: 'DataContract';
+    readonly documentation: string;
+    readonly examples: ReadonlyArray<{
+        readonly title: string;
+        readonly contract: Record<string, unknown>;
+    }>;
+}
+export declare function createDescribeDataContractFormatHandler(): SharedHandler<typeof inputSchema, typeof outputSchema, DescribeDataContractFormatOutput>;
+export {};
+//# sourceMappingURL=describe-data-contract-format.d.ts.map

package/dist/blueprints/describe-data-contract-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-data-contract-format.d.ts","sourceRoot":"","sources":["../../src/blueprints/describe-data-contract-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAA,MAAM,WAAW,IAAK,CAAC;AAEvB,QAAA,MAAM,YAAY;;;;;;;CASjB,CAAC;AAEF,UAAU,gCAAgC;IACxC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC,CAAC;CACJ;AAoQD,wBAAgB,uCAAuC,IAAI,aAAa,CACtE,OAAO,WAAW,EAClB,OAAO,YAAY,EACnB,gCAAgC,CACjC,CAiBA"}

package/dist/blueprints/describe-data-contract-format.js

@@ -0,0 +1,292 @@
+/**
+ * `ggui_describe_data_contract_format` — wire-format documentation for
+ * the DataContract envelope inside an AgentBlueprint.
+ *
+ * Pure compute, no DDB. Returns markdown explainer + 2-3 examples
+ * covering common shapes (display-only / collect-form / chat).
+ * Pinning the format server-side guards against contract drift between
+ * what Claude composes and what `ggui_protocol_validate_blueprint` expects.
+ */
+import { z } from 'zod';
+const inputSchema = {};
+const outputSchema = {
+    format: z.literal('DataContract'),
+    documentation: z.string(),
+    examples: z.array(z.object({
+        title: z.string(),
+        contract: z.record(z.string(), z.unknown()),
+    })),
+};
+const DOCUMENTATION = `# DataContract format
+
+Top-level shape on every blueprint's \`contract\` field:
+
+\`\`\`ts
+interface DataContract {
+  /** Initial render data — the props the component receives. */
+  propsSpec?: PropsSpec;
+
+  /** User-interaction events — flat map keyed by action name. */
+  actionSpec?: ActionSpec;
+
+  /** Observable client state — flat map keyed by slot name. */
+  contextSpec?: ContextSpec;
+
+  /** Live update payloads — flat map keyed by stream channel name. */
+  streamSpec?: StreamSpec;
+
+  /** Read-only catalog: MCP tools the AGENT may invoke. Referenced
+   *  from actionSpec[*].nextStep and streamSpec[*].source.tool. The
+   *  component NEVER calls these. */
+  agentCapabilities?: AgentCapabilitiesSpec;
+
+  /** Read-only catalog: browser-capability gadget hooks the COMPONENT
+   *  imports (useGeolocation, useCamera, useClipboardWrite, …).
+   *  Values reach the agent only when threaded into a contextSpec
+   *  slot or an actionSpec payload. */
+  clientCapabilities?: ClientCapabilitiesSpec;
+}
+\`\`\`
+
+\`intent\` is NOT a contract field — the outer pipeline owns it
+(top-level \`intent\` on the flat \`ggui_handshake\` input). The
+four-spec surface — propsSpec / actionSpec / contextSpec / streamSpec
+— describes the wire exhaustively. See
+\`docs/principles/actions-vs-context.md\` for the placement rule on
+the two inbound specs.
+
+## PropsSpec
+
+\`\`\`ts
+interface PropsSpec {
+  description?: string;
+  properties: Record<string, {
+    schema: JsonSchema;       // draft-07 subset: type, enum, items, properties
+    required?: boolean;       // default true
+    description?: string;
+    default?: JsonValue;
+    example?: JsonValue;
+  }>;
+}
+\`\`\`
+
+The boilerplate generator turns each \`properties\` entry into a typed
+TypeScript field on \`Props\`. \`required: false\` becomes \`field?:\`.
+\`schema.nullable: true\` becomes \`| null\`.
+
+## ActionSpec entry
+
+\`\`\`ts
+interface ActionEntry {
+  /** Human label — drives button copy / accessibility name. */
+  label?: string;
+  description?: string;
+  /** Optional payload schema. Action with a payload becomes useAction<T>. */
+  schema?: JsonSchema;
+  /** Optional example payload — surfaces in tool descriptions. */
+  example?: JsonValue;
+  /** Optional hint: which agentCapabilities.tools entry the agent SHOULD
+   *  invoke on its next turn after this action fires. Naming the
+   *  tool here does NOT route the action server-side — every action
+   *  is agent-routed. The hint surfaces on the action event so the
+   *  agent picks the right tool. Must appear in agentCapabilities.tools. */
+  nextStep?: string;
+}
+\`\`\`
+
+In the source, declare with \`const X = useAction<PayloadType>('X')\` and
+fire as \`X(payload)\` (or \`X()\` when payload-less).
+
+## StreamSpec entry
+
+\`\`\`ts
+interface StreamEntry {
+  description?: string;
+  /** Payload schema — every emitted event must conform. */
+  schema: JsonSchema;
+  /** Optional example payload. */
+  example?: JsonValue;
+  /** Optional source binding: agent-tool name whose deliveries feed
+   *  this channel (runtime subscribes / polls). Must appear in
+   *  agentCapabilities.tools. */
+  source?: { tool: string };
+}
+\`\`\`
+
+In the source, declare with \`const stream = useStream<PayloadType>('channel')\`
+and read latest as \`stream.latest\` or iterate \`stream.history\`.
+
+## AgentCapabilitiesSpec entry
+
+\`\`\`ts
+interface AgentCapabilitiesSpec {
+  tools: Record<string, AgentToolEntry>;
+}
+
+interface AgentToolEntry {
+  description?: string;
+  inputSchema?: JsonSchema;
+  outputSchema?: JsonSchema;
+  usage?: string;
+  example?: { input?: JsonValue; output?: JsonValue };
+  required?: boolean;
+}
+\`\`\`
+
+Pure catalog — declares tools the AGENT may invoke. Referenced from
+\`actionSpec[*].nextStep\` (agent next-turn hint) and
+\`streamSpec[*].source.tool\` (channel data source). The component
+NEVER calls these. Cross-ref linter rejects dangling \`nextStep\` /
+\`source.tool\` values that don't resolve to a key here.
+
+## ClientCapabilitiesSpec entry
+
+\`\`\`ts
+interface ClientCapabilitiesSpec {
+  // Keyed by npm PACKAGE name; each value is a per-package use map.
+  gadgets: Record<string, GadgetPackageUse>;
+}
+
+// One package's exports the UI uses, keyed by export NAME (>= 1).
+// The export name's grammar discriminates kind: a 'use'-prefixed
+// name is a hook, a PascalCase name is a component. There is no
+// 'hook' / 'component' field and no 'kind' tag.
+type GadgetPackageUse = Record<string, GadgetExportUse>;
+
+interface GadgetExportUse {
+  /** Intent-specific override of the registered description. */
+  description?: string;
+  /** Intent-specific override of the registered usage hint. */
+  usage?: string;
+}
+
+// Example: a contract that uses one Leaflet component + one stdlib hook
+//   gadgets: {
+//     '@my-org/leaflet': { LeafletMap: {} },
+//     '@ggui-ai/gadgets': { useGeolocation: {} },
+//   }
+\`\`\`
+
+The wire carries IDENTITY ONLY — \`(package, export name)\`. It does
+NOT carry \`version\`: the operator's \`App.gadgets\` catalog owns the
+version pin. Per-export registry metadata (\`permission\`, \`example\`,
+the \`required\` flag) and transport fields (\`bundleUrl\`,
+\`bundleSri\`, …) likewise live on the operator-registered gadget
+package descriptor — NOT on the wire. The renderer resolves them
+server-side from the app's gadget catalog at push time (e.g. a hook's
+browser \`permission\` flows into the iframe's Permissions-Policy
+directive set from there).
+
+Pure declaration — items are React hooks the UI imports + calls. Pure
+UI-side lifecycle; the agent never invokes them. Values reach the
+agent only when threaded into a contextSpec slot or actionSpec
+payload.
+
+## defineContract helper (TypeScript only)
+
+\`\`\`ts
+import { defineContract } from '@ggui-ai/protocol';
+
+export const myContract = defineContract({
+  propsSpec: { ... },
+  actionSpec: { ... },
+} as const);
+\`\`\`
+
+\`defineContract\` is a TypeScript-only helper — at runtime it returns
+its argument unchanged. Always pair with \`as const\` so prop+action
+names propagate as literal-typed strings into \`useAction<T>(name)\` and
+\`useStream<T>(name)\` for autocomplete on the consumer side.`;
+const EXAMPLES = [
+    {
+        title: 'Display-only — no actions, no stream',
+        contract: {
+            propsSpec: {
+                properties: {
+                    city: { schema: { type: 'string' }, required: true },
+                    tempC: { schema: { type: 'number' }, required: true },
+                    condition: {
+                        schema: { type: 'string', enum: ['sunny', 'cloudy', 'rainy'] },
+                        required: true,
+                    },
+                },
+            },
+        },
+    },
+    {
+        title: 'Collect-form — props + submit action with payload',
+        contract: {
+            propsSpec: {
+                properties: {
+                    placeholder: { schema: { type: 'string' }, required: false, default: 'New task' },
+                },
+            },
+            actionSpec: {
+                submit: {
+                    label: 'Add task',
+                    description: 'User submitted a new task title.',
+                    schema: {
+                        type: 'object',
+                        properties: { title: { type: 'string' } },
+                        required: ['title'],
+                    },
+                },
+                cancel: {
+                    label: 'Cancel',
+                    description: 'User dismissed without submitting.',
+                },
+            },
+        },
+    },
+    {
+        title: 'Live chat — initial messages prop + stream + send action',
+        contract: {
+            propsSpec: {
+                properties: {
+                    messages: {
+                        schema: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    role: { type: 'string', enum: ['user', 'agent'] },
+                                    text: { type: 'string' },
+                                },
+                            },
+                        },
+                        required: true,
+                    },
+                },
+            },
+            streamSpec: {
+                agentReply: {
+                    description: 'Token-by-token agent response.',
+                    schema: { type: 'object', properties: { delta: { type: 'string' } } },
+                },
+            },
+            actionSpec: {
+                send: {
+                    label: 'Send',
+                    schema: { type: 'object', properties: { text: { type: 'string' } } },
+                },
+            },
+        },
+    },
+];
+export function createDescribeDataContractFormatHandler() {
+    return {
+        name: 'ggui_protocol_describe_data_contract_format',
+        title: 'Describe data contract format',
+        audience: ['protocol'],
+        description: "Returns the wire-format spec for the DataContract envelope — the `contract` field inside an AgentBlueprint. Covers PropsSpec / ActionSpec / StreamSpec / AgentCapabilitiesSpec / ClientCapabilitiesSpec sub-shapes, the `defineContract({...} as const)` TypeScript helper, and three worked examples (display-only / collect-form / converse-stream). Call this alongside `ggui_protocol_describe_blueprint_format` when composing a blueprint in a fresh conversation. Then call `ggui_protocol_get_blueprint_boilerplate({ contract })` for a typed scaffold.",
+        inputSchema,
+        outputSchema,
+        async handler() {
+            return {
+                format: 'DataContract',
+                documentation: DOCUMENTATION,
+                examples: EXAMPLES,
+            };
+        },
+    };
+}

package/dist/blueprints/get-blueprint-boilerplate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `ggui_get_blueprint_boilerplate` — scaffolded TSX source tailored to a
+ * caller-supplied DataContract. A composition aid for agents that
+ * author UI source by hand.
+ *
+ * Pure compute, no database, no network. Wraps `generateBoilerplate`
+ * from `@ggui-ai/ui-gen/boilerplate` — the same composer the
+ * generation pipeline uses internally for first-attempt scaffolding
+ * (`buildSystemPrompt` relies on the same primitive). Returns a
+ * `.tsx` string that compiles
+ * out of the box: typed `Props` derived from `contract.propsSpec`, action
+ * handler stubs from `contract.actionSpec`, stream wiring from
+ * `contract.streamSpec`, and primitives pre-imported.
+ *
+ * Workflow guidance lives in the tool description — Claude is expected
+ * to call this AFTER `ggui_validate_data_contract` (when that ships in
+ * the next sub-slice) and BEFORE `ggui_protocol_validate_blueprint`. The contract
+ * is the load-bearing input: a richer contract → a more complete scaffold.
+ */
+import { z } from 'zod';
+import type { SharedHandler } from '../types.js';
+declare const inputSchema: {
+    contract: z.ZodUnknown;
+    intent: z.ZodOptional<z.ZodString>;
+    shell: z.ZodDefault<z.ZodEnum<{
+        chat: "chat";
+        fullscreen: "fullscreen";
+        spatial: "spatial";
+    }>>;
+    screen: z.ZodDefault<z.ZodEnum<{
+        mobile: "mobile";
+        tablet: "tablet";
+        desktop: "desktop";
+        universal: "universal";
+    }>>;
+};
+declare const outputSchema: {
+    source: z.ZodString;
+};
+interface GetBlueprintBoilerplateOutput {
+    readonly source: string;
+}
+export declare function createGetBlueprintBoilerplateHandler(): SharedHandler<typeof inputSchema, typeof outputSchema, GetBlueprintBoilerplateOutput>;
+export {};
+//# sourceMappingURL=get-blueprint-boilerplate.d.ts.map

package/dist/blueprints/get-blueprint-boilerplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-blueprint-boilerplate.d.ts","sourceRoot":"","sources":["../../src/blueprints/get-blueprint-boilerplate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;CAwBhB,CAAC;AAEF,QAAA,MAAM,YAAY;;CAEjB,CAAC;AAEF,UAAU,6BAA6B;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oCAAoC,IAAI,aAAa,CACnE,OAAO,WAAW,EAClB,OAAO,YAAY,EACnB,6BAA6B,CAC9B,CAqBA"}