@ggui-ai/protocol 0.2.0-alpha.4 → 0.3.0-rc.0

package/dist/registry/portable-blueprint.d.ts

@@ -0,0 +1,64 @@
+import type { PortableBlueprint } from '../types/portable-blueprint.js';
+import { PORTABLE_BLUEPRINT_SCHEMA_VERSION } from '../types/portable-blueprint.js';
+import type { DataContract } from '../types/data-contract.js';
+import type { BlueprintVariance } from '../types/blueprint.js';
+import type { BlueprintSource } from '../types/blueprint-source.js';
+import type { ToolCatalogShape } from './blueprint-stamp.js';
+export type { PortableBlueprint };
+export { PORTABLE_BLUEPRINT_SCHEMA_VERSION };
+/** The fields needed to mint a {@link PortableBlueprint} (keys are derived). */
+export interface PortableBlueprintSource {
+    readonly contract: DataContract;
+    readonly componentCode: string;
+    readonly variance: BlueprintVariance;
+    /** Provenance of `componentCode` — travels with the artifact. */
+    readonly source: BlueprintSource;
+}
+/**
+ * Rejection message for schemaVersion-1 artifacts. v1 records predate
+ * required provenance, and a blueprint pool is a cache — re-exporting
+ * regenerates the records with full provenance, so there is no
+ * migration shim.
+ */
+export declare const PORTABLE_BLUEPRINT_V1_REJECTION = "re-export the pool: PortableBlueprint schemaVersion 2 requires complete provenance";
+/**
+ * Result of {@link fromPortableBlueprint} — the validating narrower at
+ * the artifact trust boundary (JSON bytes → typed record).
+ *
+ * Rejection policy at the call sites: pool loaders SKIP a rejected
+ * record with a log line (a rejected seed entry is just a cold-gen);
+ * explicit single-artifact import paths hard-error with `reason`.
+ * Coercing a rejected record into the typed shape is banned.
+ */
+export type PortableBlueprintImportResult = {
+    readonly ok: true;
+    /** Canonical rebuild of the validated record (stray keys dropped). */
+    readonly record: PortableBlueprint;
+    /** True if the shipped contractHash/variantKey differed from the recompute. */
+    readonly keyMismatch: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Options for {@link toPortableBlueprint}. */
+export interface ToPortableBlueprintOpts {
+    /**
+     * Tool-identity catalog used to canonicalize the contract at export
+     * time. When provided, its hash is stamped as
+     * `toolIdentityCatalogHash` so importers can detect catalog drift
+     * (same intent → different key). When omitted — the offline-export
+     * case, where no runtime catalog exists — the stamp is left absent
+     * and importers fall back to recomputing keys against their own
+     * catalog.
+     */
+    readonly catalog?: ToolCatalogShape;
+}
+export declare function toPortableBlueprint(src: PortableBlueprintSource, opts?: ToPortableBlueprintOpts): PortableBlueprint;
+/**
+ * Validate one artifact record (parsed JSON, untrusted) into a typed
+ * {@link PortableBlueprint}. Shipped keys are advisory — they are
+ * recomputed here and a divergence is surfaced as `keyMismatch`, never
+ * silently trusted.
+ */
+export declare function fromPortableBlueprint(record: unknown): PortableBlueprintImportResult;
+//# sourceMappingURL=portable-blueprint.d.ts.map

package/dist/registry/portable-blueprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-blueprint.d.ts","sourceRoot":"","sources":["../../src/registry/portable-blueprint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAMpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAI7D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAClC,OAAO,EAAE,iCAAiC,EAAE,CAAC;AAE7C,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,uFAC0C,CAAC;AAEvF;;;;;;;;GAQG;AACH,MAAM,MAAM,6BAA6B,GACrC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,+CAA+C;AAC/C,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,uBAAuB,EAC5B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,iBAAiB,CAcnB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,6BAA6B,CAmFpF"}

package/dist/registry/portable-blueprint.js

@@ -0,0 +1,103 @@
+import { PORTABLE_BLUEPRINT_SCHEMA_VERSION } from '../types/portable-blueprint.js';
+import { parseBlueprintSource } from '../types/blueprint-source.js';
+import { dataContractSchema } from '../schemas/data-contract.js';
+import { blueprintVarianceSchema } from '../schemas/blueprint.js';
+import { blueprintKey, variantKey } from './blueprint-key.js';
+import { PROTOCOL_VERSION } from '../version.js';
+import { computeToolCatalogHash } from './blueprint-stamp.js';
+import { isRecord } from '../validation/is-record.js';
+export { PORTABLE_BLUEPRINT_SCHEMA_VERSION };
+/**
+ * Rejection message for schemaVersion-1 artifacts. v1 records predate
+ * required provenance, and a blueprint pool is a cache — re-exporting
+ * regenerates the records with full provenance, so there is no
+ * migration shim.
+ */
+export const PORTABLE_BLUEPRINT_V1_REJECTION = 're-export the pool: PortableBlueprint schemaVersion 2 requires complete provenance';
+export function toPortableBlueprint(src, opts) {
+    return {
+        schemaVersion: PORTABLE_BLUEPRINT_SCHEMA_VERSION,
+        contract: src.contract,
+        componentCode: src.componentCode,
+        variance: src.variance,
+        contractHash: blueprintKey(src.contract),
+        variantKey: variantKey(src.variance),
+        source: src.source,
+        generatorProtocolVersion: PROTOCOL_VERSION,
+        ...(opts?.catalog !== undefined
+            ? { toolIdentityCatalogHash: computeToolCatalogHash(opts.catalog) }
+            : {}),
+    };
+}
+/**
+ * Validate one artifact record (parsed JSON, untrusted) into a typed
+ * {@link PortableBlueprint}. Shipped keys are advisory — they are
+ * recomputed here and a divergence is surfaced as `keyMismatch`, never
+ * silently trusted.
+ */
+export function fromPortableBlueprint(record) {
+    if (!isRecord(record)) {
+        return { ok: false, reason: 'record is not an object' };
+    }
+    const r = record;
+    if (r['schemaVersion'] !== PORTABLE_BLUEPRINT_SCHEMA_VERSION) {
+        if (r['schemaVersion'] === 1) {
+            return { ok: false, reason: PORTABLE_BLUEPRINT_V1_REJECTION };
+        }
+        return {
+            ok: false,
+            reason: `unsupported PortableBlueprint schemaVersion ${JSON.stringify(r['schemaVersion'])} (expected ${PORTABLE_BLUEPRINT_SCHEMA_VERSION})`,
+        };
+    }
+    const source = parseBlueprintSource(r['source']);
+    if (source === null) {
+        return {
+            ok: false,
+            reason: 'missing or malformed `source` provenance (expected a BlueprintSource union value)',
+        };
+    }
+    const generatorProtocolVersion = r['generatorProtocolVersion'];
+    if (typeof generatorProtocolVersion !== 'string' ||
+        generatorProtocolVersion.length === 0) {
+        return { ok: false, reason: 'missing or empty `generatorProtocolVersion`' };
+    }
+    const componentCode = r['componentCode'];
+    if (typeof componentCode !== 'string' || componentCode.length === 0) {
+        return { ok: false, reason: 'missing or empty `componentCode`' };
+    }
+    const shippedContractHash = r['contractHash'];
+    const shippedVariantKey = r['variantKey'];
+    if (typeof shippedContractHash !== 'string' || typeof shippedVariantKey !== 'string') {
+        return { ok: false, reason: 'missing `contractHash` / `variantKey`' };
+    }
+    const toolIdentityCatalogHash = r['toolIdentityCatalogHash'];
+    if (toolIdentityCatalogHash !== undefined &&
+        typeof toolIdentityCatalogHash !== 'string') {
+        return { ok: false, reason: 'malformed `toolIdentityCatalogHash` (expected string)' };
+    }
+    const contract = dataContractSchema.safeParse(r['contract']);
+    if (!contract.success) {
+        return { ok: false, reason: `malformed \`contract\`: ${contract.error.message}` };
+    }
+    const variance = blueprintVarianceSchema.safeParse(r['variance']);
+    if (!variance.success) {
+        return { ok: false, reason: `malformed \`variance\`: ${variance.error.message}` };
+    }
+    const keyMismatch = blueprintKey(contract.data) !== shippedContractHash ||
+        variantKey(variance.data) !== shippedVariantKey;
+    return {
+        ok: true,
+        record: {
+            schemaVersion: PORTABLE_BLUEPRINT_SCHEMA_VERSION,
+            contract: contract.data,
+            componentCode,
+            variance: variance.data,
+            contractHash: shippedContractHash,
+            variantKey: shippedVariantKey,
+            source,
+            generatorProtocolVersion,
+            ...(toolIdentityCatalogHash !== undefined ? { toolIdentityCatalogHash } : {}),
+        },
+        keyMismatch,
+    };
+}

package/dist/registry/summarize-contract.d.ts

@@ -21,7 +21,7 @@
  *
  *     slots=<name:type,...>;
  *     actions=<name(payloadFields)?,...>; streams=<name,...>;
- *     props=<name:type,...>
+ *     props=<name:type[!],...>
  *
  * Format details:
  *   - slots: `name:type` (e.g. `count:number,draft:string`). Bare
@@ -36,7 +36,12 @@
  *     in the summary lets the judge see this distinction.
  *   - streams: bare `name` (channel schemas vary a lot and are usually
  *     emitted by the agent later; including them adds noise).
- *   - props: `name:type` (initial render shape).
+ *   - props: `name:type` (initial render shape). A trailing `!` marks a
+ *     required prop (e.g. `name:type!` = required; `name:type` =
+ *     optional). Bare `name!` when a required prop's schema has no
+ *     `type` field. Only props the component MUST accept are marked;
+ *     surfacing required-vs-optional lets the rerank judge tell a
+ *     mandatory prop apart from an optional one instead of guessing.
  *
  * Empty slots/actions/streams/props collapse to `∅`.
  */

package/dist/registry/summarize-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"summarize-contract.d.ts","sourceRoot":"","sources":["../../src/registry/summarize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,GAAG,SAAS,GACjC,MAAM,CA6CR"}
+{"version":3,"file":"summarize-contract.d.ts","sourceRoot":"","sources":["../../src/registry/summarize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,GAAG,SAAS,GACjC,MAAM,CAqDR"}

package/dist/registry/summarize-contract.js

@@ -1,3 +1,4 @@
+import { isRecord } from '../validation/is-record.js';
 /** Stable summary of `contract` for embedding + rerank input. */
 export function summarizeContract(contract) {
     if (!contract)
@@ -27,8 +28,16 @@ export function summarizeContract(contract) {
         ? Object.entries(contract.propsSpec.properties)
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([name, entry]) => {
+            // `entry` is a `PropEntry` (PropsSpec.properties is
+            // `Record<string, PropEntry>`), so `schema` and `required`
+            // read directly — no cast.
             const t = readType(entry.schema);
-            return t ? `${name}:${t}` : name;
+            const base = t ? `${name}:${t}` : name;
+            // A trailing `!` marks a mandatory prop so the rerank judge
+            // (and the agent) can tell required from optional. Only the
+            // literal `true` earns the marker; `undefined`/`false` = not
+            // required.
+            return entry.required === true ? `${base}!` : base;
         })
             .join(',')
         : '';
@@ -50,10 +59,10 @@ function readType(schema) {
  *  or `null` when the action takes no payload. Empty `properties` →
  *  null (payload-less). */
 function readPayloadFields(schema) {
-    if (typeof schema !== 'object' || schema === null)
+    if (!isRecord(schema))
         return null;
     const props = schema.properties;
-    if (typeof props !== 'object' || props === null || Array.isArray(props)) {
+    if (!isRecord(props)) {
         return null;
     }
     const keys = Object.keys(props);

package/dist/registry/variant-key.d.ts

@@ -0,0 +1,17 @@
+import type { BlueprintVariance } from '../types/blueprint.js';
+/**
+ * Identity hash of the design-time variance block — the variant axis of
+ * the reuse key. `(contractKey, variantKey)` identifies one reusable
+ * component; runtime props are never an input. Spec §8.
+ *
+ * 16-char sha256 prefix of {@link canonicalizeVariance}'s output, which
+ * is self-normalizing (D9): `undefined`, `{}`, `{persona:''}`, and any
+ * all-empty variance hash to one stable "default variant" sentinel, so
+ * the accept path (verbatim `blueprintMeta.variance`) and the override
+ * path never false-miss on equivalent variance.
+ *
+ * Server-only — depends on `node:crypto`. Exposed at the
+ * `@ggui-ai/protocol/blueprint-key` subpath (see `blueprint-key.ts`).
+ */
+export declare function variantKey(variance: BlueprintVariance | undefined): string;
+//# sourceMappingURL=variant-key.d.ts.map

package/dist/registry/variant-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant-key.d.ts","sourceRoot":"","sources":["../../src/registry/variant-key.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAK1E"}

package/dist/registry/variant-key.js

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeVariance } from './canonicalize-contract.js';
+/**
+ * Identity hash of the design-time variance block — the variant axis of
+ * the reuse key. `(contractKey, variantKey)` identifies one reusable
+ * component; runtime props are never an input. Spec §8.
+ *
+ * 16-char sha256 prefix of {@link canonicalizeVariance}'s output, which
+ * is self-normalizing (D9): `undefined`, `{}`, `{persona:''}`, and any
+ * all-empty variance hash to one stable "default variant" sentinel, so
+ * the accept path (verbatim `blueprintMeta.variance`) and the override
+ * path never false-miss on equivalent variance.
+ *
+ * Server-only — depends on `node:crypto`. Exposed at the
+ * `@ggui-ai/protocol/blueprint-key` subpath (see `blueprint-key.ts`).
+ */
+export function variantKey(variance) {
+    return createHash('sha256')
+        .update(canonicalizeVariance(variance))
+        .digest('hex')
+        .slice(0, 16);
+}

package/dist/schema-learning/derive-contract.d.ts

@@ -43,8 +43,8 @@ export interface DeriveContractInput {
  * - `intent` — "<serverName> — <humanized tool verb>" unless overridden.
  * - `props` — each top-level property of dataTool.outputSchema becomes a PropEntry.
  *   If outputSchema is not an object schema, a single `data` prop wraps the whole thing.
- * - `actions` — one ActionEntry per actionTool, with `tool` wired to the MCP tool name
- *   and `schema` set to the tool's inputSchema (if present).
+ * - `actions` — one ActionEntry per actionTool, with `nextStep` set to the MCP tool
+ *   name (advisory hint) and `schema` set to the tool's inputSchema (if present).
  *
  * Pure — deterministic given identical input.
  */

package/dist/schema-learning/derive-contract.js

@@ -5,8 +5,8 @@
  * - `intent` — "<serverName> — <humanized tool verb>" unless overridden.
  * - `props` — each top-level property of dataTool.outputSchema becomes a PropEntry.
  *   If outputSchema is not an object schema, a single `data` prop wraps the whole thing.
- * - `actions` — one ActionEntry per actionTool, with `tool` wired to the MCP tool name
- *   and `schema` set to the tool's inputSchema (if present).
+ * - `actions` — one ActionEntry per actionTool, with `nextStep` set to the MCP tool
+ *   name (advisory hint) and `schema` set to the tool's inputSchema (if present).
  *
  * Pure — deterministic given identical input.
  */

package/dist/schema-learning/merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/schema-learning/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAc,UAAU,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEnF,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA4BxD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,CAIlG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CA0BxE"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/schema-learning/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAc,UAAU,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGnF,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA4BxD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,CAIlG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CA0BxE"}

package/dist/schema-learning/merge.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../validation/is-record.js";
 /** Infer a JSON Schema from a single JSON value. */
 export function inferSchema(value) {
     if (value === null)
@@ -136,10 +137,10 @@ function dedupeAnyOf(list) {
 }
 /** Deterministic stable key — recursive, sorts object keys at every depth. */
 function canonicalKey(v) {
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v);
     if (Array.isArray(v))
         return "[" + v.map(canonicalKey).join(",") + "]";
+    if (!isRecord(v))
+        return JSON.stringify(v);
     const obj = v;
     const keys = Object.keys(obj).sort();
     return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalKey(obj[k])).join(",") + "}";

package/dist/schemas/app-theme.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/**
+ * Platform CSS-variable namespace — only `--ggui-*` custom properties.
+ *
+ * The charset allows mixed-case ASCII because the canonical theme parser
+ * (`@ggui-ai/design`) emits camelCase token segments verbatim into the
+ * variable name (e.g. `--ggui-color-onSurface`, `--ggui-zIndex-modal`,
+ * `--ggui-font-lineHeight-tight`) — and the design system both EMITS and
+ * CONSUMES those exact keys (`var(--ggui-color-onSurface)`). Case has no
+ * bearing on injection safety; the `--ggui-` prefix is the namespace guard
+ * and value-level breakout characters are forbidden by {@link CSS_VALUE_SAFE_RE}.
+ */
+export declare const GGUI_CSS_VAR_KEY_RE: RegExp;
+/**
+ * A single safe CSS value. The map is serialized into a `:root { --k: v; }`
+ * declaration block inside the rendered iframe, so a value MUST NOT be able to
+ * terminate the declaration or open a new rule/comment. Forbid the breakout
+ * characters `; { } < > @` and the comment opener `/*`. Everything else
+ * (colors, lengths, `calc(...)`, `var(...)`, font-family lists) is allowed.
+ *
+ * PARTIAL gate — this regex alone is NOT a complete validator. Bare `/` and
+ * `*` are intentionally allowed (legal in `16px/1.5`, `calc(2 * 4px)`); only
+ * the `/*` comment-opener SEQUENCE is forbidden, and that check lives in
+ * {@link appThemeSchema}'s `.refine`, not here. Callers MUST validate values
+ * through `appThemeSchema` (the complete validator) — never against this
+ * bare regex on its own.
+ */
+export declare const CSS_VALUE_SAFE_RE: RegExp;
+export declare const appThemeSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>;
+    cssVariables: z.ZodRecord<z.ZodString, z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AppTheme = z.infer<typeof appThemeSchema>;
+//# sourceMappingURL=app-theme.d.ts.map

package/dist/schemas/app-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-theme.d.ts","sourceRoot":"","sources":["../../src/schemas/app-theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAShD,eAAO,MAAM,cAAc;;;;;;;kBAQhB,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/schemas/app-theme.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Platform CSS-variable namespace — only `--ggui-*` custom properties.
+ *
+ * The charset allows mixed-case ASCII because the canonical theme parser
+ * (`@ggui-ai/design`) emits camelCase token segments verbatim into the
+ * variable name (e.g. `--ggui-color-onSurface`, `--ggui-zIndex-modal`,
+ * `--ggui-font-lineHeight-tight`) — and the design system both EMITS and
+ * CONSUMES those exact keys (`var(--ggui-color-onSurface)`). Case has no
+ * bearing on injection safety; the `--ggui-` prefix is the namespace guard
+ * and value-level breakout characters are forbidden by {@link CSS_VALUE_SAFE_RE}.
+ */
+export const GGUI_CSS_VAR_KEY_RE = /^--ggui-[a-zA-Z0-9-]+$/;
+/**
+ * A single safe CSS value. The map is serialized into a `:root { --k: v; }`
+ * declaration block inside the rendered iframe, so a value MUST NOT be able to
+ * terminate the declaration or open a new rule/comment. Forbid the breakout
+ * characters `; { } < > @` and the comment opener `/*`. Everything else
+ * (colors, lengths, `calc(...)`, `var(...)`, font-family lists) is allowed.
+ *
+ * PARTIAL gate — this regex alone is NOT a complete validator. Bare `/` and
+ * `*` are intentionally allowed (legal in `16px/1.5`, `calc(2 * 4px)`); only
+ * the `/*` comment-opener SEQUENCE is forbidden, and that check lives in
+ * {@link appThemeSchema}'s `.refine`, not here. Callers MUST validate values
+ * through `appThemeSchema` (the complete validator) — never against this
+ * bare regex on its own.
+ */
+export const CSS_VALUE_SAFE_RE = /^[^;{}<>@]*$/;
+const cssValue = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(CSS_VALUE_SAFE_RE, 'css value contains a disallowed character')
+    .refine((v) => !v.includes('/*'), 'css value may not contain a comment');
+export const appThemeSchema = z
+    .object({
+    mode: z.enum(['light', 'dark']),
+    cssVariables: z
+        .record(z.string().regex(GGUI_CSS_VAR_KEY_RE, 'css var key must be --ggui-*'), cssValue)
+        .refine((m) => Object.keys(m).length <= 200, 'too many css variables (max 200)'),
+    name: z.string().min(1).max(64).optional(),
+})
+    .strict();

package/dist/schemas/blueprint.d.ts

@@ -5,8 +5,36 @@
  * here is `z.ZodType<Blueprint>` so any drift fails compile.
  */
 import { z } from 'zod';
-import type { AppBlueprintSearchConfig, Blueprint, BlueprintSearchWeights, BlueprintVariance } from '../types/blueprint';
-/** Zod mirror of {@link BlueprintVariance}. */
+import type { AppBlueprintSearchConfig, Blueprint, BlueprintVariance } from '../types/blueprint';
+import type { BlueprintSource, CuratedBlueprintSource, LlmBlueprintSource, UserBlueprintSource } from '../types/blueprint-source';
+/**
+ * Zod mirror of {@link LlmBlueprintSource} — the engine-generated arm.
+ * Both provenance fields are REQUIRED: every generation mint site has
+ * them in scope, and an engine-generated artifact that cannot name its
+ * engine + model is not a real state.
+ */
+export declare const llmBlueprintSourceSchema: z.ZodType<LlmBlueprintSource>;
+/** Zod mirror of {@link UserBlueprintSource} — no engine claim exists. */
+export declare const userBlueprintSourceSchema: z.ZodType<UserBlueprintSource>;
+/** Zod mirror of {@link CuratedBlueprintSource}. */
+export declare const curatedBlueprintSourceSchema: z.ZodType<CuratedBlueprintSource>;
+/**
+ * Zod mirror of {@link BlueprintSource} — the single provenance
+ * vocabulary for blueprints. Mirrors `parseBlueprintSource`'s arms;
+ * `.strict()` members so stray keys surface at the wire layer rather
+ * than riding through.
+ */
+export declare const blueprintSourceSchema: z.ZodType<BlueprintSource>;
+/**
+ * Zod mirror of {@link BlueprintVariance}. The single shared variance
+ * schema: every seam that accepts a variance block (handshake draft,
+ * render override, operator blueprint tools) reuses this one
+ * rather than re-declaring the shape inline. `.strict()` so an unknown
+ * key surfaces as a typo at the wire layer rather than being silently
+ * dropped. The per-field `.describe()` strings ship as JSON-Schema
+ * metadata via `tools/list`, so they stay mechanism-only and
+ * vendor-neutral.
+ */
 export declare const blueprintVarianceSchema: z.ZodType<BlueprintVariance>;
 /**
  * Zod mirror of {@link Blueprint}. Required fields are listed first;
@@ -15,15 +43,6 @@ export declare const blueprintVarianceSchema: z.ZodType<BlueprintVariance>;
  * in persisted rows are a bug worth surfacing rather than tolerating.
  */
 export declare const blueprintSchema: z.ZodType<Blueprint>;
-/**
- * Zod mirror of {@link BlueprintSearchWeights}. Every axis is a
- * non-negative finite number. Per-axis defaults are applied at the
- * impl layer (see `DEFAULT_BLUEPRINT_SEARCH_WEIGHTS` in
- * `@ggui-ai/mcp-server-core`); this schema only validates the shape
- * an operator passes through `App.blueprintSearchConfig.weights`
- * when the operator provides EVERY axis.
- */
-export declare const blueprintSearchWeightsSchema: z.ZodType<BlueprintSearchWeights>;
 /**
  * Zod mirror of {@link AppBlueprintSearchConfig}. All fields optional;
  * server applies the global default for any axis the operator omits.

package/dist/schemas/blueprint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,wBAAwB,EACxB,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAG5B,+CAA+C;AAC/C,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAOtB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAwBd,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAQ3B,CAAC;AAmBjD;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAM7B,CAAC"}
+{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,wBAAwB,EACxB,SAAS,EACT,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AAGnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAMvB,CAAC;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAExB,CAAC;AAE9C,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAE3B,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAI7B,CAAC;AAEjC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAqBtB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAwBd,CAAC;AAmBpC;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAM7B,CAAC"}

package/dist/schemas/blueprint.js

@@ -6,13 +6,66 @@
  */
 import { z } from 'zod';
 import { dataContractSchema, jsonValueSchema } from './data-contract.js';
-/** Zod mirror of {@link BlueprintVariance}. */
+/**
+ * Zod mirror of {@link LlmBlueprintSource} — the engine-generated arm.
+ * Both provenance fields are REQUIRED: every generation mint site has
+ * them in scope, and an engine-generated artifact that cannot name its
+ * engine + model is not a real state.
+ */
+export const llmBlueprintSourceSchema = z
+    .object({
+    kind: z.literal('llm'),
+    generator: z.string().min(1),
+    model: z.string().min(1),
+})
+    .strict();
+/** Zod mirror of {@link UserBlueprintSource} — no engine claim exists. */
+export const userBlueprintSourceSchema = z
+    .object({ kind: z.literal('user') })
+    .strict();
+/** Zod mirror of {@link CuratedBlueprintSource}. */
+export const curatedBlueprintSourceSchema = z
+    .object({ kind: z.literal('curated') })
+    .strict();
+/**
+ * Zod mirror of {@link BlueprintSource} — the single provenance
+ * vocabulary for blueprints. Mirrors `parseBlueprintSource`'s arms;
+ * `.strict()` members so stray keys surface at the wire layer rather
+ * than riding through.
+ */
+export const blueprintSourceSchema = z.union([
+    llmBlueprintSourceSchema,
+    userBlueprintSourceSchema,
+    curatedBlueprintSourceSchema,
+]);
+/**
+ * Zod mirror of {@link BlueprintVariance}. The single shared variance
+ * schema: every seam that accepts a variance block (handshake draft,
+ * render override, operator blueprint tools) reuses this one
+ * rather than re-declaring the shape inline. `.strict()` so an unknown
+ * key surfaces as a typo at the wire layer rather than being silently
+ * dropped. The per-field `.describe()` strings ship as JSON-Schema
+ * metadata via `tools/list`, so they stay mechanism-only and
+ * vendor-neutral.
+ */
 export const blueprintVarianceSchema = z
     .object({
-    persona: z.string().optional(),
-    aesthetic: z.string().optional(),
-    context: z.record(z.string(), jsonValueSchema).optional(),
-    seedPrompt: z.string().optional(),
+    persona: z
+        .string()
+        .optional()
+        .describe('Design persona, e.g. "minimalist" / "data-dense". Part of cache identity.'),
+    aesthetic: z
+        .string()
+        .optional()
+        .describe('Visual aesthetic, e.g. "calm" / "ornate". Part of cache identity.'),
+    context: z
+        .record(z.string(), jsonValueSchema)
+        .optional()
+        .describe('Deliberate design-shaping signals (e.g. {situation:"sad"}) — part of cache identity. NOT for per-user runtime data; put that in propsSpec/contextSpec.'),
+    seedPrompt: z
+        .string()
+        .optional()
+        .describe('Generation seed directive. Part of cache identity.'),
 })
     .strict();
 /**
@@ -28,7 +81,7 @@ export const blueprintSchema = z
     appId: z.string().min(1),
     codeS3Url: z.string().optional(),
     codeHash: z.string().optional(),
-    generator: z.string().min(1),
+    source: blueprintSourceSchema,
     validatorScore: z.number().min(0).max(1).optional(),
     variance: blueprintVarianceSchema,
     // `true | undefined` — store-level invariant: at most one row per
@@ -47,28 +100,11 @@ export const blueprintSchema = z
 })
     .strict();
 /**
- * Zod mirror of {@link BlueprintSearchWeights}. Every axis is a
+ * Zod mirror of the partial-weights shape on
+ * {@link AppBlueprintSearchConfig.weights}. Every axis is a
  * non-negative finite number. Per-axis defaults are applied at the
  * impl layer (see `DEFAULT_BLUEPRINT_SEARCH_WEIGHTS` in
- * `@ggui-ai/mcp-server-core`); this schema only validates the shape
- * an operator passes through `App.blueprintSearchConfig.weights`
- * when the operator provides EVERY axis.
- */
-export const blueprintSearchWeightsSchema = z
-    .object({
-    hash: z.number().min(0),
-    embed: z.number().min(0),
-    struct: z.number().min(0),
-    variance: z.number().min(0),
-    intent: z.number().min(0),
-})
-    .strict();
-/**
- * Zod mirror of the partial-weights shape on
- * {@link AppBlueprintSearchConfig.weights}. Built directly rather
- * than as `.partial()` on `blueprintSearchWeightsSchema` because
- * that schema is typed `z.ZodType<...>` for cross-zod-version
- * compatibility — `.partial()` only exists on `z.ZodObject`.
+ * `@ggui-ai/mcp-server-core`) for any axis the operator omits.
  */
 const partialBlueprintSearchWeightsSchema = z
     .object({