@rudra-js/core 0.1.0

package/dist/component-spec.d.ts

@@ -0,0 +1,426 @@
+import { z } from 'zod';
+/**
+ * The component specification — the only thing a language model is ever allowed
+ * to return.
+ *
+ * The model chooses layout, ordering, emphasis, copy, the recommendation
+ * strategy behind each pick, and which of the host's candidate products to
+ * surface. It never returns markup, code, URLs, prices,
+ * product titles, or images. Every field is an enum, a bounded number, a SKU
+ * reference resolved against the candidate set, or free text that is clamped
+ * and escaped before it renders. That is what makes generated output safe to
+ * put in a server-rendered response.
+ *
+ * Two constraints shape this file, and both are easy to undo by accident:
+ *
+ *  1. It doubles as a provider structured-output schema, so it avoids
+ *     recursion, string length bounds, and numeric ranges. Providers reject
+ *     schemas that use them in strict mode. Bounds are enforced afterwards, in
+ *     reconciliation, where a violation can be repaired rather than fatal.
+ *  2. Optionality is `.nullable()` rather than `.optional()`, because strict
+ *     structured outputs require every declared property to be present. "No
+ *     badge" has to be expressible as `null`, not as a missing key.
+ *
+ * A test asserts both by converting this schema to JSON Schema, so neither is
+ * left to a comment nobody reads.
+ *
+ * Note the asymmetry with `tracking-input`, which rejects unknown fields: these
+ * schemas strip them. The inputs differ in kind. An unrecognised key in a host
+ * payload is a typo, and silently dropping it costs the shopper their history,
+ * so it must be loud. An unrecognised key from a model is drift, and discarding
+ * it is exactly right — rejecting the whole spec over one stray key would cost
+ * the shopper the component. Either way the renderer only ever sees the fields
+ * declared here, which is the property that matters.
+ */
+/** Overall voice of the component. */
+export declare const TONES: readonly ['neutral', 'enthusiastic', 'urgent', 'editorial'];
+/** What a banner is claiming. */
+export declare const BANNER_TONES: readonly ['info', 'promo', 'urgency', 'restock'];
+/** How prominently a single product is placed. */
+export declare const EMPHASIS: readonly ['normal', 'featured'];
+/**
+ * Why a product was chosen — the recommendation strategy behind the pick.
+ *
+ * This is a closed set rather than free text because every value here is a
+ * factual claim about the shopper, and a claim the server can check. "Because
+ * you viewed this" written as prose is unverifiable: nothing downstream can
+ * tell whether the shopper viewed anything. Declared as `most_viewed`,
+ * reconciliation can look it up in the digest and drop the claim if it is
+ * false.
+ *
+ * Every value is deliberately checkable against data already in hand — the
+ * signal digest or the host's own catalog. A basis that needs data the
+ * framework never receives (`new_arrival`, `back_in_stock`, `trending_today`)
+ * is not in this list, because it could only ever be taken on trust.
+ */
+export declare const RECOMMENDATION_BASES: readonly [
+/** Same category as the product being viewed. */
+'similar_to_current', 
+/** The shopper has viewed this product. */
+'most_viewed', 
+/** Goes with something already in the cart. */
+'complements_cart', 
+/** Goes with something the shopper has bought. */
+'complements_purchase', 
+/** In a category the shopper's signals favour. */
+'liked_category', 
+/** No claim about this shopper at all — the safe default. */
+'popular'];
+/** A reference to one product from the candidate set, and why it was chosen. */
+export declare const productReferenceSchema: z.ZodObject<{
+    sku: z.ZodString;
+    basis: z.ZodEnum<{
+        complements_cart: "complements_cart";
+        complements_purchase: "complements_purchase";
+        liked_category: "liked_category";
+        most_viewed: "most_viewed";
+        popular: "popular";
+        similar_to_current: "similar_to_current";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    badge: z.ZodNullable<z.ZodString>;
+    emphasis: z.ZodEnum<{
+        featured: "featured";
+        normal: "normal";
+    }>;
+}, z.core.$strip>;
+export type ProductReference = z.infer<typeof productReferenceSchema>;
+export type RecommendationBasis = (typeof RECOMMENDATION_BASES)[number];
+/** One large featured statement, optionally anchored to a single product. */
+declare const heroBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"hero">;
+    headline: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    sku: z.ZodNullable<z.ZodString>;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** The general-purpose choice when several products are comparably relevant. */
+declare const gridBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"grid">;
+    title: z.ZodNullable<z.ZodString>;
+    columns: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        basis: z.ZodEnum<{
+            complements_cart: "complements_cart";
+            complements_purchase: "complements_purchase";
+            liked_category: "liked_category";
+            most_viewed: "most_viewed";
+            popular: "popular";
+            similar_to_current: "similar_to_current";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        badge: z.ZodNullable<z.ZodString>;
+        emphasis: z.ZodEnum<{
+            featured: "featured";
+            normal: "normal";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A horizontally scanned row, for when order implies a ranking. */
+declare const carouselBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"carousel">;
+    title: z.ZodNullable<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        basis: z.ZodEnum<{
+            complements_cart: "complements_cart";
+            complements_purchase: "complements_purchase";
+            liked_category: "liked_category";
+            most_viewed: "most_viewed";
+            popular: "popular";
+            similar_to_current: "similar_to_current";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        badge: z.ZodNullable<z.ZodString>;
+        emphasis: z.ZodEnum<{
+            featured: "featured";
+            normal: "normal";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A single line of merchandising copy. */
+declare const bannerBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"banner">;
+    tone: z.ZodEnum<{
+        info: "info";
+        promo: "promo";
+        restock: "restock";
+        urgency: "urgency";
+    }>;
+    text: z.ZodString;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Short editorial prose, for explaining the theme of a selection. */
+declare const copyBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"copy">;
+    title: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+/** A set the shop sells together. The shop picks which one; this only asks for it. */
+declare const bundleBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"bundle">;
+    title: z.ZodNullable<z.ZodString>;
+    body: z.ZodNullable<z.ZodString>;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+    bundleId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Blocks do not nest. The vocabulary is closed on purpose. */
+export declare const blockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"hero">;
+    headline: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    sku: z.ZodNullable<z.ZodString>;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"grid">;
+    title: z.ZodNullable<z.ZodString>;
+    columns: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        basis: z.ZodEnum<{
+            complements_cart: "complements_cart";
+            complements_purchase: "complements_purchase";
+            liked_category: "liked_category";
+            most_viewed: "most_viewed";
+            popular: "popular";
+            similar_to_current: "similar_to_current";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        badge: z.ZodNullable<z.ZodString>;
+        emphasis: z.ZodEnum<{
+            featured: "featured";
+            normal: "normal";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"carousel">;
+    title: z.ZodNullable<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        basis: z.ZodEnum<{
+            complements_cart: "complements_cart";
+            complements_purchase: "complements_purchase";
+            liked_category: "liked_category";
+            most_viewed: "most_viewed";
+            popular: "popular";
+            similar_to_current: "similar_to_current";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        badge: z.ZodNullable<z.ZodString>;
+        emphasis: z.ZodEnum<{
+            featured: "featured";
+            normal: "normal";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"banner">;
+    tone: z.ZodEnum<{
+        info: "info";
+        promo: "promo";
+        restock: "restock";
+        urgency: "urgency";
+    }>;
+    text: z.ZodString;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"copy">;
+    title: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"bundle">;
+    title: z.ZodNullable<z.ZodString>;
+    body: z.ZodNullable<z.ZodString>;
+    ctaLabel: z.ZodNullable<z.ZodString>;
+    bundleId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type Block = z.infer<typeof blockSchema>;
+export type BlockKind = Block['kind'];
+export type HeroBlock = z.infer<typeof heroBlockSchema>;
+export type GridBlock = z.infer<typeof gridBlockSchema>;
+export type CarouselBlock = z.infer<typeof carouselBlockSchema>;
+export type BannerBlock = z.infer<typeof bannerBlockSchema>;
+export type CopyBlock = z.infer<typeof copyBlockSchema>;
+export type BundleBlock = z.infer<typeof bundleBlockSchema>;
+/**
+ * Exactly what the model must return. Provenance — version, slot, latency, which
+ * provider answered — is added by the server afterwards, and is deliberately not
+ * part of the model's burden.
+ */
+export declare const generatedSpecSchema: z.ZodObject<{
+    tone: z.ZodEnum<{
+        editorial: "editorial";
+        enthusiastic: "enthusiastic";
+        neutral: "neutral";
+        urgent: "urgent";
+    }>;
+    headline: z.ZodString;
+    subheadline: z.ZodNullable<z.ZodString>;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"hero">;
+        headline: z.ZodString;
+        body: z.ZodNullable<z.ZodString>;
+        sku: z.ZodNullable<z.ZodString>;
+        ctaLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"grid">;
+        title: z.ZodNullable<z.ZodString>;
+        columns: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+        items: z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            basis: z.ZodEnum<{
+                complements_cart: "complements_cart";
+                complements_purchase: "complements_purchase";
+                liked_category: "liked_category";
+                most_viewed: "most_viewed";
+                popular: "popular";
+                similar_to_current: "similar_to_current";
+            }>;
+            reason: z.ZodNullable<z.ZodString>;
+            badge: z.ZodNullable<z.ZodString>;
+            emphasis: z.ZodEnum<{
+                featured: "featured";
+                normal: "normal";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"carousel">;
+        title: z.ZodNullable<z.ZodString>;
+        items: z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            basis: z.ZodEnum<{
+                complements_cart: "complements_cart";
+                complements_purchase: "complements_purchase";
+                liked_category: "liked_category";
+                most_viewed: "most_viewed";
+                popular: "popular";
+                similar_to_current: "similar_to_current";
+            }>;
+            reason: z.ZodNullable<z.ZodString>;
+            badge: z.ZodNullable<z.ZodString>;
+            emphasis: z.ZodEnum<{
+                featured: "featured";
+                normal: "normal";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"banner">;
+        tone: z.ZodEnum<{
+            info: "info";
+            promo: "promo";
+            restock: "restock";
+            urgency: "urgency";
+        }>;
+        text: z.ZodString;
+        ctaLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"copy">;
+        title: z.ZodNullable<z.ZodString>;
+        body: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"bundle">;
+        title: z.ZodNullable<z.ZodString>;
+        body: z.ZodNullable<z.ZodString>;
+        ctaLabel: z.ZodNullable<z.ZodString>;
+        bundleId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+    rationale: z.ZodString;
+}, z.core.$strip>;
+export type GeneratedSpec = z.infer<typeof generatedSpecSchema>;
+/** How a spec came to exist. Surfaced for benchmarking and observability. */
+export type SpecSource = 'llm' | 'cache' | 'fallback';
+/**
+ * Why a component is not what the model would have produced.
+ *
+ * A closed set, like `SpecSource`: it is rendered into pages as
+ * `data-rudra-degraded` and counted in dashboards, so a host needs to know what
+ * it can receive without reading the generator.
+ */
+export type DegradedReason = 
+/** No provider was configured, so nothing was ever asked. */
+'no-provider'
+/** The provider errored, or threw before it reached the vendor. */
+ | 'provider-error'
+/** The deadline fired before an answer arrived. */
+ | 'timeout'
+/** An answer came back that did not satisfy the schema. */
+ | 'invalid-generation'
+/** A usable answer reconciled down to nothing for this shopper. */
+ | 'unusable-on-serve'
+/** The caller asked for the deterministic component on purpose. */
+ | 'requested';
+export declare const SPEC_VERSION: '1';
+/** A generated spec plus the provenance the server owns. This is what renders. */
+export interface ComponentSpec extends GeneratedSpec {
+    specVersion: typeof SPEC_VERSION;
+    slot: string;
+    source: SpecSource;
+    /** Epoch milliseconds at which the underlying generation completed. */
+    generatedAt: number;
+    /** Wall-clock milliseconds spent producing it, including any cache lookup. */
+    latencyMs: number;
+    /** Provider name, or null when no model was involved. */
+    provider: string | null;
+    /** Model identifier, or null when no model was involved. */
+    model: string | null;
+    /**
+     * Why the deterministic component is showing instead of a generated one.
+     * Present on every fallback, including the ones where no model was involved
+     * at all — no provider configured, or the caller asked for it directly.
+     */
+    degradedReason?: DegradedReason;
+}
+/** Throws a `ZodError` if the value is not a well-formed generated spec. */
+export declare function parseGeneratedSpec(value: unknown): GeneratedSpec;
+/** Non-throwing variant, for validating untrusted model output. */
+export declare function safeParseGeneratedSpec(value: unknown): z.ZodSafeParseResult<{
+    tone: "editorial" | "enthusiastic" | "neutral" | "urgent";
+    headline: string;
+    subheadline: string | null;
+    blocks: ({
+        kind: "hero";
+        headline: string;
+        body: string | null;
+        sku: string | null;
+        ctaLabel: string | null;
+    } | {
+        kind: "grid";
+        title: string | null;
+        columns: 2 | 3 | 4;
+        items: {
+            sku: string;
+            basis: "complements_cart" | "complements_purchase" | "liked_category" | "most_viewed" | "popular" | "similar_to_current";
+            reason: string | null;
+            badge: string | null;
+            emphasis: "featured" | "normal";
+        }[];
+    } | {
+        kind: "carousel";
+        title: string | null;
+        items: {
+            sku: string;
+            basis: "complements_cart" | "complements_purchase" | "liked_category" | "most_viewed" | "popular" | "similar_to_current";
+            reason: string | null;
+            badge: string | null;
+            emphasis: "featured" | "normal";
+        }[];
+    } | {
+        kind: "banner";
+        tone: "info" | "promo" | "restock" | "urgency";
+        text: string;
+        ctaLabel: string | null;
+    } | {
+        kind: "copy";
+        title: string | null;
+        body: string;
+    } | {
+        kind: "bundle";
+        title: string | null;
+        body: string | null;
+        ctaLabel: string | null;
+        bundleId: string | null;
+    })[];
+    rationale: string;
+}>;
+export {};
+//# sourceMappingURL=component-spec.d.ts.map

package/dist/component-spec.d.ts.map

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

package/dist/component-spec.js

@@ -0,0 +1,170 @@
+import { z } from 'zod';
+/**
+ * The component specification — the only thing a language model is ever allowed
+ * to return.
+ *
+ * The model chooses layout, ordering, emphasis, copy, the recommendation
+ * strategy behind each pick, and which of the host's candidate products to
+ * surface. It never returns markup, code, URLs, prices,
+ * product titles, or images. Every field is an enum, a bounded number, a SKU
+ * reference resolved against the candidate set, or free text that is clamped
+ * and escaped before it renders. That is what makes generated output safe to
+ * put in a server-rendered response.
+ *
+ * Two constraints shape this file, and both are easy to undo by accident:
+ *
+ *  1. It doubles as a provider structured-output schema, so it avoids
+ *     recursion, string length bounds, and numeric ranges. Providers reject
+ *     schemas that use them in strict mode. Bounds are enforced afterwards, in
+ *     reconciliation, where a violation can be repaired rather than fatal.
+ *  2. Optionality is `.nullable()` rather than `.optional()`, because strict
+ *     structured outputs require every declared property to be present. "No
+ *     badge" has to be expressible as `null`, not as a missing key.
+ *
+ * A test asserts both by converting this schema to JSON Schema, so neither is
+ * left to a comment nobody reads.
+ *
+ * Note the asymmetry with `tracking-input`, which rejects unknown fields: these
+ * schemas strip them. The inputs differ in kind. An unrecognised key in a host
+ * payload is a typo, and silently dropping it costs the shopper their history,
+ * so it must be loud. An unrecognised key from a model is drift, and discarding
+ * it is exactly right — rejecting the whole spec over one stray key would cost
+ * the shopper the component. Either way the renderer only ever sees the fields
+ * declared here, which is the property that matters.
+ */
+/** Overall voice of the component. */
+export const TONES = ['neutral', 'enthusiastic', 'urgent', 'editorial'];
+/** What a banner is claiming. */
+export const BANNER_TONES = ['info', 'promo', 'urgency', 'restock'];
+/** How prominently a single product is placed. */
+export const EMPHASIS = ['normal', 'featured'];
+/**
+ * Why a product was chosen — the recommendation strategy behind the pick.
+ *
+ * This is a closed set rather than free text because every value here is a
+ * factual claim about the shopper, and a claim the server can check. "Because
+ * you viewed this" written as prose is unverifiable: nothing downstream can
+ * tell whether the shopper viewed anything. Declared as `most_viewed`,
+ * reconciliation can look it up in the digest and drop the claim if it is
+ * false.
+ *
+ * Every value is deliberately checkable against data already in hand — the
+ * signal digest or the host's own catalog. A basis that needs data the
+ * framework never receives (`new_arrival`, `back_in_stock`, `trending_today`)
+ * is not in this list, because it could only ever be taken on trust.
+ */
+export const RECOMMENDATION_BASES = [
+    /** Same category as the product being viewed. */
+    'similar_to_current',
+    /** The shopper has viewed this product. */
+    'most_viewed',
+    /** Goes with something already in the cart. */
+    'complements_cart',
+    /** Goes with something the shopper has bought. */
+    'complements_purchase',
+    /** In a category the shopper's signals favour. */
+    'liked_category',
+    /** No claim about this shopper at all — the safe default. */
+    'popular',
+];
+/** A reference to one product from the candidate set, and why it was chosen. */
+export const productReferenceSchema = z.object({
+    /** Must be a SKU the host supplied in `TrackingInput.candidates`. */
+    sku: z.string(),
+    /**
+     * The strategy behind this pick. Reconciliation checks it against the
+     * shopper's signals, so the model cannot assert a relationship that is not
+     * there.
+     */
+    basis: z.enum(RECOMMENDATION_BASES),
+    /**
+     * How the basis is phrased for the shopper, e.g. "Pairs with the boots you
+     * bought". Free text, but it has to be consistent with `basis`, which is not.
+     *
+     * Nullable because reconciliation clears it when it cannot verify the basis:
+     * a pick may still be worth showing when the stated reason for it is not
+     * true, but the prose asserting that reason must not render.
+     */
+    reason: z.string().nullable(),
+    /** Short accent label, e.g. "Back in stock". Null when nothing warrants one. */
+    badge: z.string().nullable(),
+    emphasis: z.enum(EMPHASIS),
+});
+/** One large featured statement, optionally anchored to a single product. */
+const heroBlockSchema = z.object({
+    kind: z.literal('hero'),
+    headline: z.string(),
+    body: z.string().nullable(),
+    sku: z.string().nullable(),
+    ctaLabel: z.string().nullable(),
+});
+/** The general-purpose choice when several products are comparably relevant. */
+const gridBlockSchema = z.object({
+    kind: z.literal('grid'),
+    title: z.string().nullable(),
+    columns: z.union([z.literal(2), z.literal(3), z.literal(4)]),
+    items: z.array(productReferenceSchema),
+});
+/** A horizontally scanned row, for when order implies a ranking. */
+const carouselBlockSchema = z.object({
+    kind: z.literal('carousel'),
+    title: z.string().nullable(),
+    items: z.array(productReferenceSchema),
+});
+/** A single line of merchandising copy. */
+const bannerBlockSchema = z.object({
+    kind: z.literal('banner'),
+    tone: z.enum(BANNER_TONES),
+    text: z.string(),
+    ctaLabel: z.string().nullable(),
+});
+/** Short editorial prose, for explaining the theme of a selection. */
+const copyBlockSchema = z.object({
+    kind: z.literal('copy'),
+    title: z.string().nullable(),
+    body: z.string(),
+});
+/** A set the shop sells together. The shop picks which one; this only asks for it. */
+const bundleBlockSchema = z.object({
+    kind: z.literal('bundle'),
+    title: z.string().nullable(),
+    body: z.string().nullable(),
+    ctaLabel: z.string().nullable(),
+    // Filled in per request. Whatever the model puts here is thrown away.
+    bundleId: z.string().nullable(),
+});
+/** Blocks do not nest. The vocabulary is closed on purpose. */
+export const blockSchema = z.discriminatedUnion('kind', [
+    heroBlockSchema,
+    gridBlockSchema,
+    carouselBlockSchema,
+    bannerBlockSchema,
+    copyBlockSchema,
+    bundleBlockSchema,
+]);
+/**
+ * Exactly what the model must return. Provenance — version, slot, latency, which
+ * provider answered — is added by the server afterwards, and is deliberately not
+ * part of the model's burden.
+ */
+export const generatedSpecSchema = z.object({
+    tone: z.enum(TONES),
+    headline: z.string(),
+    subheadline: z.string().nullable(),
+    blocks: z.array(blockSchema),
+    /**
+     * One sentence on why this arrangement was chosen. For engineers reading
+     * generation logs, not for shoppers; it is not rendered by default.
+     */
+    rationale: z.string(),
+});
+export const SPEC_VERSION = '1';
+/** Throws a `ZodError` if the value is not a well-formed generated spec. */
+export function parseGeneratedSpec(value) {
+    return generatedSpecSchema.parse(value);
+}
+/** Non-throwing variant, for validating untrusted model output. */
+export function safeParseGeneratedSpec(value) {
+    return generatedSpecSchema.safeParse(value);
+}
+//# sourceMappingURL=component-spec.js.map

package/dist/component-spec.js.map

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

package/dist/fallback-component.d.ts

@@ -0,0 +1,11 @@
+import type { GeneratedSpec } from './component-spec.js';
+import type { SignalDigest } from './signal-digest.js';
+import type { TrackingInput } from './tracking-input.js';
+/**
+ * Builds a renderable spec from signals alone. Never throws. Returns a spec with
+ * no blocks only when there is genuinely nothing in stock left to show, which
+ * the renderer treats as "render nothing" — an empty recommendation region is
+ * worse than none.
+ */
+export declare function buildFallbackSpec(input: TrackingInput, digest: SignalDigest): GeneratedSpec;
+//# sourceMappingURL=fallback-component.d.ts.map

package/dist/fallback-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-component.d.ts","sourceRoot":"","sources":["../src/fallback-component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAkDzD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,aAAa,CAiB3F"}