@ggui-ai/protocol 0.1.0-rc.1

package/dist/schemas/ops-blueprint.js

@@ -0,0 +1,259 @@
+/**
+ * Zod input + output schemas for the operator-class blueprint tools.
+ * Four tools, all `audience: 'ops'`, all served on `/ops`:
+ *
+ *   - `ggui_ops_generate_blueprint` — author a new blueprint by
+ *     dispatching through the registry's selected generator and
+ *     persisting the result. Optionally pins as the operator default
+ *     for its `(appId, contractHash)` group.
+ *   - `ggui_ops_list_blueprints` — enumerate blueprint metadata
+ *     (no code body) under tenancy + optional filters. Sorted by
+ *     `createdAt desc`.
+ *   - `ggui_ops_update_blueprint` — toggle the operator-default flag
+ *     and/or patch variance tags. Immutable fields (contractHash,
+ *     appId, codeS3Url, codeHash, generator, createdAt, createdBy)
+ *     never mutate; the tool MUST refuse them on input.
+ *   - `ggui_ops_delete_blueprint` — idempotent removal. Second delete
+ *     for the same id returns `{deleted: true}` — never throws.
+ *
+ * The schemas live in `@ggui-ai/protocol` (not the handler package)
+ * for the same reason all wire-shape schemas do: the protocol package
+ * is the source of truth for every MCP wire surface, and consumers
+ * (cloud pod handlers, console UI, fixture authors) can import from
+ * one place. Handler package wraps these into `SharedHandler`
+ * factories.
+ */
+import { z } from 'zod';
+import { dataContractSchema, jsonValueSchema, } from './data-contract.js';
+import { blueprintSchema, blueprintVarianceSchema } from './blueprint.js';
+/**
+ * `ggui_ops_generate_blueprint` input. Operator picks the contract +
+ * optional generator override + variance tags. `setAsOperatorDefault`
+ * pins the newly-minted blueprint as the default for its
+ * `(appId, contractHash)` group (the store clears any prior default
+ * in the same group, mirroring `BlueprintStore.setOperatorDefault`).
+ *
+ * `persona` is a top-level convenience field — handlers fold it into
+ * the `variance.persona` slot after normalization (lowercase + trim
+ * + Levenshtein near-dup warning).
+ *
+ * `appId` is NOT on the input shape — the handler reads it off
+ * `ctx.appId` resolved by the upstream auth adapter. Cross-tenant
+ * authorship would be a security-boundary violation.
+ */
+export const opsGenerateBlueprintInputSchema = z
+    .object({
+    contract: dataContractSchema,
+    generator: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Generator slug (e.g. `ui-gen-default-haiku-4-5`). When omitted, dispatches through `GeneratorRegistry.defaultGenerator()`.'),
+    persona: z
+        .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: z
+        .string()
+        .optional()
+        .describe("Free-form aesthetic tag (e.g. 'glassmorphic', 'brutalist', 'editorial'). Persisted on `Blueprint.variance.aesthetic`. Distinct from persona — persona names the user mental model; aesthetic names the visual treatment."),
+    context: z
+        .record(z.string(), jsonValueSchema)
+        .optional()
+        .describe('Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`.'),
+    seedPrompt: z
+        .string()
+        .optional()
+        .describe("The raw operator prompt that produced this variant. Round-trip input for the variant-selector + audit trail."),
+    setAsOperatorDefault: z
+        .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();
+/**
+ * `ggui_ops_generate_blueprint` output. Metadata-only — the code body
+ * lives in S3 (cloud) or the in-memory code map (OSS) and is fetched
+ * via the existing push fast-path on cache hit.
+ */
+export const opsGenerateBlueprintOutputSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+    codeHash: z
+        .string()
+        .optional()
+        .describe('Content hash of the generated code body. Absent when the generator returned a non-`ok` result and persistence skipped — the failure mode is surfaced through generator-level error reporting elsewhere.'),
+    validatorScore: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Advanced generator's iterative-loop validator score (0-1). Absent for default-generator output."),
+    generator: z
+        .string()
+        .min(1)
+        .describe('Slug of the generator the dispatch resolved to.'),
+})
+    .strict();
+/**
+ * `ggui_ops_register_blueprint` input. Sibling of `*_generate_*` — no
+ * LLM dispatch, no generator. The operator supplies the COMPONENT
+ * CODE BYTES directly and the handler persists them under the same
+ * `(appId, contractHash)` slot. Use cases:
+ *
+ *   - Seeding pre-vetted blueprints at deploy time (fixture corpus,
+ *     migration imports).
+ *   - Round-tripping export+reimport — operator exports a blueprint
+ *     from one tenant and re-registers it in another.
+ *   - Reapplying a fixed version of a blueprint after live edits
+ *     (manual recovery from a bad generate run).
+ *
+ * Same tenancy + variance + default-pin semantics as
+ * `*_generate_*`; the only difference is the LLM/generator dispatch
+ * is replaced with a verbatim accept of the operator's
+ * `componentCode` string.
+ *
+ * `generator` is OPTIONAL here too — when omitted, the handler stamps
+ * the registry default's slug onto the persisted Blueprint so
+ * downstream `*_list_blueprints` consumers see a stable provenance
+ * field. `validatorScore` is never populated (no validator ran);
+ * operators wanting validator metadata should round-trip through
+ * `*_generate_*` instead.
+ */
+export const opsRegisterBlueprintInputSchema = z
+    .object({
+    contract: dataContractSchema,
+    componentCode: z
+        .string()
+        .min(1)
+        .describe('Verbatim component-code body to persist. Stored as-is — 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_*`.'),
+    generator: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional generator slug to stamp on the persisted Blueprint.generator field — purely an audit/provenance hint for downstream `*_list_blueprints` consumers. Defaults to the registry default slug.'),
+    persona: z
+        .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: z
+        .string()
+        .optional()
+        .describe("Free-form aesthetic tag. Persisted on `Blueprint.variance.aesthetic`."),
+    context: z
+        .record(z.string(), jsonValueSchema)
+        .optional()
+        .describe('Small structured signal carried alongside the persona. Persisted on `Blueprint.variance.context`.'),
+    seedPrompt: z
+        .string()
+        .optional()
+        .describe('Optional originating prompt for audit + round-tripping (e.g. the prose the operator originally fed into `*_generate_*` before exporting).'),
+    setAsOperatorDefault: z
+        .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();
+/**
+ * `ggui_ops_register_blueprint` output. Same shape as
+ * `*_generate_*` minus `validatorScore` (no validator runs on the
+ * register path).
+ */
+export const opsRegisterBlueprintOutputSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+    codeHash: z
+        .string()
+        .min(1)
+        .describe('Content hash of the persisted code body (full sha256 hex).'),
+    generator: z
+        .string()
+        .min(1)
+        .describe('Resolved generator slug stamped on the Blueprint.generator field — either the supplied input or the registry default.'),
+})
+    .strict();
+/**
+ * `ggui_ops_list_blueprints` input. `appId` is NOT carried on the
+ * wire — handlers scope from `ctx.appId`. The filters below are AND-
+ * composed against the matching `(appId, *)` view of the store.
+ *
+ * Behavior split:
+ *   - When `contractHash` is the ONLY filter (no semantic keywords
+ *     or persona), handlers dispatch through
+ *     `BlueprintStore.list(appId, contractHash)` for the indexed
+ *     fast path.
+ *   - When `intentKeywords` or `persona` carry semantic intent,
+ *     handlers dispatch through `BlueprintSearch.search()` and
+ *     return the matching rows (sorted by score desc, then
+ *     `createdAt desc`).
+ *   - When no filter is supplied, handlers enumerate every blueprint
+ *     under `appId` via the search seam (which scopes by appId
+ *     internally), sorted `createdAt desc`.
+ */
+export const opsListBlueprintsInputSchema = z
+    .object({
+    contractHash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Filter to a single `(appId, contractHash)` group. Combine with `generator` / `persona` to narrow within the group.'),
+    generator: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Filter to blueprints produced by a specific generator slug.'),
+    persona: z
+        .string()
+        .optional()
+        .describe('Filter on `variance.persona`. Normalized to match persisted form (lowercase+trim).'),
+    intentKeywords: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Semantic-search tokens. When set, dispatches through `BlueprintSearch.search()` rather than indexed `list()`.'),
+})
+    .strict();
+export const opsListBlueprintsOutputSchema = z
+    .object({
+    blueprints: z.array(blueprintSchema),
+})
+    .strict();
+/**
+ * `ggui_ops_update_blueprint` input. Only mutable fields are present
+ * here — `contractHash`, `appId`, `codeS3Url`, `codeHash`,
+ * `generator`, `createdAt`, `createdBy` are immutable invariants
+ * and the schema does NOT accept them. Operators who want to
+ * "replace" a row delete + re-generate.
+ */
+export const opsUpdateBlueprintInputSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+    isOperatorDefault: z
+        .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` — 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();
+export const opsUpdateBlueprintOutputSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+    updatedAt: z.string().min(1),
+})
+    .strict();
+/**
+ * `ggui_ops_delete_blueprint` input + output. Idempotent: the handler
+ * returns `{deleted: true}` regardless of whether the row existed,
+ * matching `BlueprintStore.delete`'s no-throw contract.
+ */
+export const opsDeleteBlueprintInputSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+})
+    .strict();
+export const opsDeleteBlueprintOutputSchema = z
+    .object({
+    deleted: z.literal(true),
+})
+    .strict();

package/dist/schemas/sync-check.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+/**
+ * Schema Sync Check
+ *
+ * Verifies that Zod schemas and TypeScript types define the same fields.
+ * Run: pnpm --filter @ggui-ai/protocol sync-check
+ *
+ * Exits with code 1 if any fields are out of sync.
+ */
+export {};
+//# sourceMappingURL=sync-check.d.ts.map

package/dist/schemas/sync-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-check.d.ts","sourceRoot":"","sources":["../../src/schemas/sync-check.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/schemas/sync-check.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env tsx
+/* eslint-disable no-console */
+/**
+ * Schema Sync Check
+ *
+ * Verifies that Zod schemas and TypeScript types define the same fields.
+ * Run: pnpm --filter @ggui-ai/protocol sync-check
+ *
+ * Exits with code 1 if any fields are out of sync.
+ */
+import { blueprintDraftObjectSchema } from './handshake-suggestion.js';
+// Extract Zod field names from schema .shape
+function zodKeys(schema) {
+    return Object.keys(schema.shape).sort();
+}
+// Expected TypeScript type fields (manually listed — single maintenance point)
+// If you add a field to the TypeScript type, add it here too.
+// BlueprintDraft fields — agent's draft on the handshake input.
+const BLUEPRINT_DRAFT_KEYS = [
+    'contract',
+    'variance',
+    'generator',
+].sort();
+function diff(zodFields, tsFields) {
+    const zodSet = new Set(zodFields);
+    const tsSet = new Set(tsFields);
+    return {
+        inZodOnly: zodFields.filter((k) => !tsSet.has(k)),
+        inTsOnly: tsFields.filter((k) => !zodSet.has(k)),
+    };
+}
+let failed = false;
+function check(name, schema, tsKeys) {
+    const zKeys = zodKeys(schema);
+    const { inZodOnly, inTsOnly } = diff(zKeys, tsKeys);
+    if (inZodOnly.length === 0 && inTsOnly.length === 0) {
+        console.log(`  ✓ ${name}: ${zKeys.length} fields in sync`);
+    }
+    else {
+        console.log(`  ✗ ${name}: OUT OF SYNC`);
+        if (inZodOnly.length > 0)
+            console.log(`    In Zod but not TypeScript: ${inZodOnly.join(', ')}`);
+        if (inTsOnly.length > 0)
+            console.log(`    In TypeScript but not Zod: ${inTsOnly.join(', ')}`);
+        failed = true;
+    }
+}
+// handshakeInputSchema / pushInputSchema are flat top-level shapes — z.infer
+// derives the TS type directly so they stay in sync structurally without a
+// keylist double-bookkeeping. Sub-schemas (blueprintDraft) are checked here.
+console.log('\nSchema Sync Check\n');
+// `BlueprintDraft` lives at the inner `.shape` of the zod object wrapper.
+check('BlueprintDraft', blueprintDraftObjectSchema, BLUEPRINT_DRAFT_KEYS);
+console.log('');
+if (failed) {
+    console.log('Fix: update both packages/protocol/src/schemas/handshake-suggestion.ts AND packages/protocol/src/types/handshake-suggestion.ts\n');
+    console.log('');
+}
+if (failed)
+    process.exit(1);

package/dist/screen-blueprints/define.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `defineScreenBlueprint()` — authoring helper.
+ *
+ * Pass-through identity function. Exists purely to give IDE autocomplete
+ * and type-checking on blueprint manifest files in
+ * `cloud/amplify/data/screen-blueprints/*.ts`.
+ *
+ * The helper is narrow by design — it preserves the literal type of the
+ * blueprint so consumers can do precise inference (e.g. a future typed
+ * seeder that knows which prop names exist in which blueprint).
+ *
+ * @example
+ * ```ts
+ * export default defineScreenBlueprint({
+ *   id: "plan-my-week",
+ *   ...
+ * });
+ * ```
+ */
+import type { ScreenBlueprint } from "./types.js";
+export declare function defineScreenBlueprint<const T extends ScreenBlueprint>(blueprint: T): T;
+//# sourceMappingURL=define.d.ts.map

package/dist/screen-blueprints/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/screen-blueprints/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,CAAC,SAAS,eAAe,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAEtF"}

package/dist/screen-blueprints/define.js

@@ -0,0 +1,3 @@
+export function defineScreenBlueprint(blueprint) {
+    return blueprint;
+}

package/dist/screen-blueprints/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./define.js";
+export * from "./match.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/screen-blueprints/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/screen-blueprints/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/screen-blueprints/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./define.js";
+export * from "./match.js";

package/dist/screen-blueprints/match.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Blueprint matcher — pure algorithm.
+ *
+ * Given a list of candidate `McpScreenBlueprint` rows (retrieved from DDB
+ * via `byPrimaryDataTool` GSI) and the agent's `sourceTools`, return the
+ * best matching blueprint.
+ *
+ * I/O-free. The DDB query layer lives in `core/src/blueprint-matcher.ts`;
+ * that module's only job is fetching candidates and calling this function.
+ */
+import type { ScreenBlueprintSource } from "./types.js";
+/** Subset of `McpScreenBlueprintRow` the matcher needs. Keeps tests isolated. */
+export interface MatchableBlueprint {
+    blueprintId: string;
+    serverId: string;
+    dataTools: string[];
+    status: "active" | "stale" | "retired";
+    source?: ScreenBlueprintSource;
+    /** Engagement / selection rate populated by the ranker. Undefined = 0. */
+    score?: number;
+}
+/**
+ * Select the best-matching blueprint from `candidates` given the agent's
+ * `sourceTools`. Returns `null` if no candidate's `dataTools` is a subset
+ * of `sourceTools`.
+ *
+ * Subset match semantics: the agent can bring extra tools. A blueprint
+ * matches if every one of its `dataTools` appears in `sourceTools`.
+ *
+ * Ranking: `overlap × source_weight × (score || 1)`. Overlap is the blueprint's
+ * dataTools count (all must match to be a candidate, so higher counts signal
+ * more-specific blueprints). Ties broken by stable input order.
+ */
+export declare function matchBlueprint<T extends MatchableBlueprint>(candidates: readonly T[], sourceTools: readonly string[]): T | null;
+//# sourceMappingURL=match.d.ts.map

package/dist/screen-blueprints/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/screen-blueprints/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACvC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,kBAAkB,EACzD,UAAU,EAAE,SAAS,CAAC,EAAE,EACxB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,CAAC,GAAG,IAAI,CAmBV"}

package/dist/screen-blueprints/match.js

@@ -0,0 +1,51 @@
+/**
+ * Source weights — curated designs outrank generated ones when everything
+ * else ties. Matches the spec: "curated generally wins when everything else
+ * ties — because a human made a design call."
+ */
+const SOURCE_WEIGHT = {
+    curated: 3,
+    llm: 2,
+    heuristic: 1,
+};
+/**
+ * Select the best-matching blueprint from `candidates` given the agent's
+ * `sourceTools`. Returns `null` if no candidate's `dataTools` is a subset
+ * of `sourceTools`.
+ *
+ * Subset match semantics: the agent can bring extra tools. A blueprint
+ * matches if every one of its `dataTools` appears in `sourceTools`.
+ *
+ * Ranking: `overlap × source_weight × (score || 1)`. Overlap is the blueprint's
+ * dataTools count (all must match to be a candidate, so higher counts signal
+ * more-specific blueprints). Ties broken by stable input order.
+ */
+export function matchBlueprint(candidates, sourceTools) {
+    if (sourceTools.length === 0 || candidates.length === 0)
+        return null;
+    const available = new Set(sourceTools);
+    const scored = [];
+    for (const bp of candidates) {
+        if (bp.status !== "active")
+            continue;
+        if (!isSubset(bp.dataTools, available))
+            continue;
+        const overlap = bp.dataTools.length;
+        const weight = SOURCE_WEIGHT[bp.source ?? "curated"];
+        const score = bp.score ?? 1;
+        scored.push({ blueprint: bp, overlap, rankScore: overlap * weight * score });
+    }
+    if (scored.length === 0)
+        return null;
+    // Stable sort: highest rankScore first, preserving input order on ties.
+    scored.sort((a, b) => b.rankScore - a.rankScore);
+    return scored[0].blueprint;
+}
+/** `needles ⊆ haystack` — every element of `needles` appears in `haystack`. */
+function isSubset(needles, haystack) {
+    for (const n of needles) {
+        if (!haystack.has(n))
+            return false;
+    }
+    return true;
+}

package/dist/screen-blueprints/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * ScreenBlueprint — authored design for a ggui screen.
+ *
+ * A blueprint describes:
+ *   - which MCP tools provide the data
+ *   - which MCP tools the agent SHOULD call after each user gesture
+ *     (`actionSpec[*].nextStep` hints surfaced on `ggui_consume`)
+ *   - the intent, interaction mechanic, and a free-form layout hint
+ *
+ * Blueprints compile deterministically into {@link DataContract}. They are the
+ * authoring surface of the Screen Designer pipeline — human-curated, heuristic,
+ * or LLM-produced. All three producers emit the same shape.
+ */
+import type { JsonSchema } from "../types/data-contract.js";
+/**
+ * UI interaction mechanic hint. Tiny enum — generation uses it to select
+ * primitives (draggable cards vs swipe stack vs live-polling hook).
+ * Layout details live in {@link ScreenBlueprint.layoutHint} (free text).
+ */
+export type ScreenMechanic = "static" | "drag" | "swipe" | "live" | "form";
+/**
+ * Provenance — who authored this blueprint. Same shape, different producers.
+ *
+ * - `curated`: hand-written TS in `cloud/amplify/data/screen-blueprints/*.ts`
+ * - `heuristic`: rule-based composer ("every `list_*` → default list view")
+ * - `llm`: LLM-driven designer for novel compositions
+ */
+export type ScreenBlueprintSource = "curated" | "heuristic" | "llm";
+/**
+ * Data source for a single prop slot. The tool's outputSchema becomes the
+ * prop's schema (optionally unwrapped via `pick`). For `live` mechanic,
+ * `refresh` declares polling/subscription cadence.
+ */
+export interface ScreenBlueprintDataSource {
+    /** MCP tool name that produces this prop's data. */
+    tool: string;
+    /**
+     * Optional field path into the tool's outputSchema to use as the prop.
+     * Example: `tool: "todoist_list_tasks"` returns `{ tasks, nextPageToken }`.
+     * `pick: "tasks"` uses just the `tasks` array schema as the prop.
+     */
+    pick?: string;
+    /**
+     * Refresh cadence for live widgets. Only meaningful with `mechanic: "live"`.
+     * `poll` = seconds between re-fetches. `subscribe` = agent pushes via stream.
+     */
+    refresh?: {
+        poll?: number;
+        subscribe?: boolean;
+    };
+}
+/**
+ * Direct action — one user interaction fires one MCP tool call. By convention,
+ * the payload keys match the tool's inputSchema keys (identity mapping). If a
+ * future blueprint needs to reshape the payload before dispatch, add a
+ * `payloadMapping` field here AND wire it through the compiler + contract in
+ * the same change.
+ */
+export interface ScreenBlueprintDirectAction {
+    /** MCP tool to invoke when the user triggers this action. */
+    tool: string;
+    /** Human-readable description; drives the button label fallback. */
+    description?: string;
+    /**
+     * Optional JSON Schema for the user-side payload. If omitted, the tool's
+     * inputSchema is used as the payload shape directly.
+     */
+    payload?: JsonSchema;
+    /** Show confirmation prompt before firing. */
+    confirm?: boolean;
+}
+/**
+ * Orchestrated action — one user interaction fires N MCP tool calls.
+ * Dispatch is agent-owned: the host renders the interaction and emits a
+ * consume event; the agent receives the event + `fires` hint and
+ * sequences the tool calls itself. No multi-tool dispatch protocol in v1.
+ */
+export interface ScreenBlueprintOrchestratedAction {
+    /** Human-readable description; drives the button label. Required here. */
+    description: string;
+    /** User-side payload shape. Required — the agent needs it to orchestrate. */
+    payload: JsonSchema;
+    /**
+     * Advisory hint: which MCP tools the agent is expected to fire. Not
+     * dispatched by the host — metadata for docs, admin UI, and the agent's
+     * orchestration reasoning.
+     */
+    fires: string[];
+    /** Show confirmation prompt before firing. */
+    confirm?: boolean;
+}
+/** Deep-link-only action — opens a URL, no tool call. */
+export interface ScreenBlueprintDeepLinkAction {
+    /** URL template. May contain placeholders `{prop.path}` resolved at render. */
+    deepLink: string;
+    /** Human-readable description; drives the button label. */
+    description?: string;
+}
+/**
+ * Action variants — the three ways a user interaction can be wired.
+ *
+ * Discriminated by presence of `tool` / `fires` / `deepLink`. Compiler
+ * uses the discriminator to pick an ActionEntry shape.
+ */
+export type ScreenBlueprintAction = ScreenBlueprintDirectAction | ScreenBlueprintOrchestratedAction | ScreenBlueprintDeepLinkAction;
+/**
+ * A screen blueprint — the authored design record.
+ *
+ * @example
+ * ```ts
+ * export default defineScreenBlueprint({
+ *   id: "plan-my-week",
+ *   server: "_composed",
+ *   displayName: "Plan My Week",
+ *   intent: "Drag tasks onto a weekly calendar to schedule focus blocks",
+ *   mechanic: "drag",
+ *   data: {
+ *     tasks:  { tool: "todoist_list_tasks", pick: "tasks" },
+ *     events: { tool: "gcal_list_events",    pick: "events" },
+ *   },
+ *   actions: {
+ *     scheduleTask: {
+ *       description: "Schedule a task as a calendar focus block",
+ *       payload: { type: "object", properties: { ... } },
+ *       fires: ["todoist_update_task", "gcal_create_event"],
+ *     },
+ *     completeTask: { tool: "todoist_complete_task" },
+ *   },
+ *   layoutHint: "Left: task cards. Right: 7-day grid. Drag to schedule.",
+ * });
+ * ```
+ */
+export interface ScreenBlueprint {
+    /** Unique identifier within `server`. URL-safe. */
+    id: string;
+    /**
+     * Owning MCP server's `serverId`, or `"_composed"` for cross-server
+     * blueprints (blueprints that draw from multiple servers, like Plan My Week
+     * using Todoist + Google Calendar).
+     */
+    server: string;
+    /** Human-readable name shown in admin UI / docs. */
+    displayName: string;
+    /** Concise purpose — becomes `DataContract.intent`. Used for caching. */
+    intent: string;
+    /** Interaction mechanic hint for the generator. Defaults to `"static"`. */
+    mechanic?: ScreenMechanic;
+    /**
+     * Data sources keyed by prop name. Each source's tool outputSchema becomes
+     * the prop schema (optionally unwrapped via `pick`).
+     */
+    data: Record<string, ScreenBlueprintDataSource>;
+    /** User-triggerable actions keyed by action name. */
+    actions?: Record<string, ScreenBlueprintAction>;
+    /** Free-form layout guidance passed to the generator as prompt context. */
+    layoutHint?: string;
+    /**
+     * Provenance. Set automatically by each producer (curated producer = this
+     * file's co-location; heuristic + llm producers set explicitly). Included
+     * here for the compiler's downstream use.
+     */
+    source?: ScreenBlueprintSource;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/screen-blueprints/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/screen-blueprints/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,WAAW,GAAG,KAAK,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iCAAiC;IAChD,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,OAAO,EAAE,UAAU,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC7B,2BAA2B,GAC3B,iCAAiC,GACjC,6BAA6B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IAChD,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAChD,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC"}

package/dist/screen-blueprints/types.js

@@ -0,0 +1 @@
+export {};