@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-storefront-claims.js

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /** Conditions a health claim names, as the object of cure, treat, heal or prevent. */ const CONDITIONS = '(?:anxiety|depression|insomnia|stress|pain|aches?|arthritis|inflammation|acne|eczema|psoriasis|rosacea|' + 'migraines?|headaches?|colds?|flu|covid(?:-19)?|viruse?s?|infections?|disease|diseases|illness|illnesses|' + 'cancer|tumou?rs?|diabetes|blood pressure|hypertension|cholesterol|asthma|allergies|adhd|autism|dementia|' + 'alzheimer\'?s|obesity|hair loss|baldness|wrinkles|scars?|nausea|indigestion|constipation|ulcers?|' + 'insulin resistance|fatigue)';
+const CLAIM_PATTERNS = [
+    // What a product does to a condition.
+    {
+        kind: 'health',
+        pattern: new RegExp(`\\b(?:cures?|cured|curing|treats?|treating|treatment for|heals?|healing|relieves?|relief (?:from|of)|` + `prevents?|preventing|prevention of|protects? against|fights?|reverses?|eliminates?|reduces? the risk of)` + `\\s+(?:your\\s+|the\\s+|a\\s+|an\\s+|all\\s+|most\\s+|chronic\\s+|common\\s+|symptoms of\\s+)*${CONDITIONS}\\b`, 'i')
+    },
+    {
+        kind: 'health',
+        pattern: /\b(?:clinically|medically|scientifically) (?:proven|tested|shown|validated|approved)\b|\b(?:fda|ema|mhra)[- ]?(?:approved|cleared|registered|certified)\b|\b(?:doctor|physician|dermatologist|pediatrician|dentist|pharmacist)s?[- ](?:recommended|approved|endorsed)\b|\bhealing (?:properties|powers?|benefits)\b|\bboosts? (?:your |the )?immun(?:e system|ity)\b|\bimmune[- ]boosting\b|\bdetoxif(?:y|ies|ying) (?:your|the) body\b|\b(?:lose|burn) (?:weight|fat) (?:fast|quickly|without)\b|\bmiracle (?:cure|remedy)\b/i
+    },
+    // Money a buyer is promised.
+    {
+        kind: 'financial',
+        pattern: /\bguaranteed (?:returns?|income|profits?|earnings|payouts?|to (?:make|earn) money)\b|\brisk[- ]free (?:investment|returns?|income|profits?)\b|\bget rich\b|\bpassive income\b|\b(?:double|triple|multiply) your (?:money|investment|income|savings)\b|\bmake money (?:fast|quickly|from home)\b|\bfinancial freedom\b|\b(?:investment|financial|tax) advice\b|\bwill (?:increase|appreciate|grow) in value\b|\bpays? for itself\b/i
+    },
+    // Law a buyer is promised.
+    {
+        kind: 'legal',
+        pattern: /\blegal advice\b|\blegally (?:binding|approved|certified|compliant|required)\b|\b(?:court|lawyer|attorney)[- ](?:approved|certified|proven)\b|\blawsuit[- ]proof\b|\bguaranteed to (?:win|hold up)\b|\b(?:compliant|complies) with (?:all|every) (?:laws?|regulations?)\b|\bmeets all legal requirements\b|\b(?:gdpr|hipaa|ada|osha)[- ](?:compliant|certified|approved)\b/i
+    },
+    // Standing a product has, which only the merchant can say it has.
+    {
+        kind: 'endorsement',
+        pattern: /\bcertified (?:organic|vegan|gluten[- ]free|kosher|halal|fair ?trade|b corp|non[- ]gmo|cruelty[- ]free)\b|\b(?:usda|fair ?trade|b corp|non[- ]gmo project) (?:certified|verified|approved)\b|\bofficially licensed\b|\bendorsed by\b|\bas seen (?:on|in)\b|\baward[- ]winning\b|(?<![\w#])(?:#1|number one|no\. ?1)\s(?:rated|best[- ]?sell(?:ing|er)|recommended|brand)\b|\bbest[- ]sell(?:ing|er)\b|\bpatented\b|\bpatent[- ]pending\b/i
+    }
+];
+/** A price written into copy: a currency sign or code beside an amount. */ const PRICE = /(?:[$€£¥]\s?\d[\d,]*(?:\.\d{1,2})?|\b\d[\d,]*(?:\.\d{1,2})?\s?(?:usd|eur|gbp|dollars?|euros?|pounds? sterling)\b)/i;
+const collapse = (text)=>text.replace(/\s+/g, ' ').trim().toLowerCase();
+/** Every phrase a pattern matches in a text, so one re-ask can remove them all. */ function everyMatch(pattern, text) {
+    const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    return [
+        ...text.matchAll(global)
+    ].map((match)=>match[0]);
+}
+/**
+ * Every claim the samples make that they may not. A certification, award,
+ * license or endorsement is allowed when the merchant's own words — the
+ * product's name and text, or the brief — contain the same phrase.
+ */ export function findStorefrontClaims(samples, merchantWords = '') {
+    const own = collapse(merchantWords);
+    const found = [];
+    for (const sample of samples){
+        for (const { kind, pattern } of CLAIM_PATTERNS){
+            for (const phrase of everyMatch(pattern, sample.text)){
+                if (kind === 'endorsement' && own.includes(collapse(phrase))) continue;
+                found.push({
+                    kind,
+                    at: sample.at,
+                    phrase
+                });
+            }
+        }
+    }
+    return found;
+}
+/** A price in the samples that the merchant's own words do not state. */ export function findInventedPrices(samples, merchantWords = '') {
+    const own = collapse(merchantWords);
+    const found = [];
+    for (const sample of samples){
+        for (const phrase of everyMatch(PRICE, sample.text)){
+            if (!own.includes(collapse(phrase))) found.push({
+                kind: 'financial',
+                at: sample.at,
+                phrase
+            });
+        }
+    }
+    return found;
+}
+const CLAIM_WORDS = {
+    health: 'a health claim',
+    financial: 'a financial claim',
+    legal: 'a legal claim',
+    endorsement: 'a certification, award or endorsement the product’s own text does not state'
+};
+/**
+ * The claims as violations the generation loop re-asks for: one per kind, the
+ * phrases quoted in the detail the model is told, the places in `paths`.
+ */ export function storefrontClaimViolations(claims, prices = []) {
+    const violations = [];
+    const kinds = [
+        ...new Set(claims.map((claim)=>claim.kind))
+    ];
+    for (const kind of kinds){
+        const own = claims.filter((claim)=>claim.kind === kind);
+        violations.push({
+            rule: null,
+            code: `storefront-claim-${kind}`,
+            message: `The copy makes ${CLAIM_WORDS[kind]}. Say what the product is and how it is used instead.`,
+            detail: `Remove: ${[
+                ...new Set(own.map((claim)=>`"${claim.phrase}"`))
+            ].join(', ')}.`,
+            paths: [
+                ...new Set(own.map((claim)=>claim.at))
+            ]
+        });
+    }
+    if (prices.length) {
+        violations.push({
+            rule: null,
+            code: 'storefront-price-invented',
+            message: 'The copy states a price nobody gave. Leave prices out; the merchant sets them.',
+            detail: `Remove: ${[
+                ...new Set(prices.map((price)=>`"${price.phrase}"`))
+            ].join(', ')}.`,
+            paths: [
+                ...new Set(prices.map((price)=>price.at))
+            ]
+        });
+    }
+    return violations;
+}
+
+//# sourceMappingURL=ai-storefront-claims.js.map

package/src/lib/model/ai-storefront-claims.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-storefront-claims.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AiDoctrineViolation } from '../runtime/ai-doctrine-validators'\n\n/**\n * STOREFRONT COPY SAFETY (AGL-2916): the claims AI-written product copy may not\n * make, checked in code on every answer rather than asked for in a prompt.\n *\n * A product description is published copy a shopper relies on, and a\n * generator writing one from a name and a photo knows nothing a claim would\n * rest on. So three kinds are refused outright, whatever the product:\n *\n *  - **health** — what a product cures, treats, heals or prevents, clinical or\n *    medical proof, a regulator's approval, a doctor's recommendation;\n *  - **financial** — returns, income or profit promised, an investment that\n *    cannot lose;\n *  - **legal** — legal advice, a legal guarantee, compliance or approval.\n *\n * A fourth kind is refused unless the merchant's own words already state it:\n * a certification, an award, a license or an endorsement. The acceptable-use\n * rules every AI request carries (`runtime/ai-runtime.ts`) forbid copy that\n * claims an endorsement, certification or partnership not given as a fact,\n * and the merchant's product text is the only such fact the generator has.\n *\n * The patterns name CLAIMS, not topics: \"a sweet treat\", \"cured ham\" and \"a\n * soothing lavender scent\" are ordinary copy. A match is refused with the\n * phrase quoted, so the one re-ask the generation loop allows can remove\n * exactly that phrase.\n *\n * A price is refused the same way unless the merchant's own words state it:\n * prices are the merchant's to set, and a generator never invents one.\n */\n\nexport type AiStorefrontClaimKind = 'health' | 'financial' | 'legal' | 'endorsement'\n\n/** Conditions a health claim names, as the object of cure, treat, heal or prevent. */\nconst CONDITIONS =\n  '(?:anxiety|depression|insomnia|stress|pain|aches?|arthritis|inflammation|acne|eczema|psoriasis|rosacea|' +\n  'migraines?|headaches?|colds?|flu|covid(?:-19)?|viruse?s?|infections?|disease|diseases|illness|illnesses|' +\n  'cancer|tumou?rs?|diabetes|blood pressure|hypertension|cholesterol|asthma|allergies|adhd|autism|dementia|' +\n  'alzheimer\\'?s|obesity|hair loss|baldness|wrinkles|scars?|nausea|indigestion|constipation|ulcers?|' +\n  'insulin resistance|fatigue)'\n\nconst CLAIM_PATTERNS: ReadonlyArray<{ kind: AiStorefrontClaimKind; pattern: RegExp }> = [\n  // What a product does to a condition.\n  {\n    kind: 'health',\n    pattern: new RegExp(\n      `\\\\b(?:cures?|cured|curing|treats?|treating|treatment for|heals?|healing|relieves?|relief (?:from|of)|` +\n        `prevents?|preventing|prevention of|protects? against|fights?|reverses?|eliminates?|reduces? the risk of)` +\n        `\\\\s+(?:your\\\\s+|the\\\\s+|a\\\\s+|an\\\\s+|all\\\\s+|most\\\\s+|chronic\\\\s+|common\\\\s+|symptoms of\\\\s+)*${CONDITIONS}\\\\b`,\n      'i',\n    ),\n  },\n  {\n    kind: 'health',\n    pattern:\n      /\\b(?:clinically|medically|scientifically) (?:proven|tested|shown|validated|approved)\\b|\\b(?:fda|ema|mhra)[- ]?(?:approved|cleared|registered|certified)\\b|\\b(?:doctor|physician|dermatologist|pediatrician|dentist|pharmacist)s?[- ](?:recommended|approved|endorsed)\\b|\\bhealing (?:properties|powers?|benefits)\\b|\\bboosts? (?:your |the )?immun(?:e system|ity)\\b|\\bimmune[- ]boosting\\b|\\bdetoxif(?:y|ies|ying) (?:your|the) body\\b|\\b(?:lose|burn) (?:weight|fat) (?:fast|quickly|without)\\b|\\bmiracle (?:cure|remedy)\\b/i,\n  },\n  // Money a buyer is promised.\n  {\n    kind: 'financial',\n    pattern:\n      /\\bguaranteed (?:returns?|income|profits?|earnings|payouts?|to (?:make|earn) money)\\b|\\brisk[- ]free (?:investment|returns?|income|profits?)\\b|\\bget rich\\b|\\bpassive income\\b|\\b(?:double|triple|multiply) your (?:money|investment|income|savings)\\b|\\bmake money (?:fast|quickly|from home)\\b|\\bfinancial freedom\\b|\\b(?:investment|financial|tax) advice\\b|\\bwill (?:increase|appreciate|grow) in value\\b|\\bpays? for itself\\b/i,\n  },\n  // Law a buyer is promised.\n  {\n    kind: 'legal',\n    pattern:\n      /\\blegal advice\\b|\\blegally (?:binding|approved|certified|compliant|required)\\b|\\b(?:court|lawyer|attorney)[- ](?:approved|certified|proven)\\b|\\blawsuit[- ]proof\\b|\\bguaranteed to (?:win|hold up)\\b|\\b(?:compliant|complies) with (?:all|every) (?:laws?|regulations?)\\b|\\bmeets all legal requirements\\b|\\b(?:gdpr|hipaa|ada|osha)[- ](?:compliant|certified|approved)\\b/i,\n  },\n  // Standing a product has, which only the merchant can say it has.\n  {\n    kind: 'endorsement',\n    pattern:\n      /\\bcertified (?:organic|vegan|gluten[- ]free|kosher|halal|fair ?trade|b corp|non[- ]gmo|cruelty[- ]free)\\b|\\b(?:usda|fair ?trade|b corp|non[- ]gmo project) (?:certified|verified|approved)\\b|\\bofficially licensed\\b|\\bendorsed by\\b|\\bas seen (?:on|in)\\b|\\baward[- ]winning\\b|(?<![\\w#])(?:#1|number one|no\\. ?1)\\s(?:rated|best[- ]?sell(?:ing|er)|recommended|brand)\\b|\\bbest[- ]sell(?:ing|er)\\b|\\bpatented\\b|\\bpatent[- ]pending\\b/i,\n  },\n]\n\n/** A price written into copy: a currency sign or code beside an amount. */\nconst PRICE =\n  /(?:[$€£¥]\\s?\\d[\\d,]*(?:\\.\\d{1,2})?|\\b\\d[\\d,]*(?:\\.\\d{1,2})?\\s?(?:usd|eur|gbp|dollars?|euros?|pounds? sterling)\\b)/i\n\nexport interface AiStorefrontCopySample {\n  /** Where the text sits in the answer, as `products[2].description`. */\n  at: string\n  text: string\n}\n\n/** One claim found, with the phrase that makes it. */\nexport interface AiStorefrontClaim {\n  kind: AiStorefrontClaimKind\n  at: string\n  phrase: string\n}\n\nconst collapse = (text: string): string => text.replace(/\\s+/g, ' ').trim().toLowerCase()\n\n/** Every phrase a pattern matches in a text, so one re-ask can remove them all. */\nfunction everyMatch(pattern: RegExp, text: string): string[] {\n  const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`)\n  return [...text.matchAll(global)].map((match) => match[0])\n}\n\n/**\n * Every claim the samples make that they may not. A certification, award,\n * license or endorsement is allowed when the merchant's own words — the\n * product's name and text, or the brief — contain the same phrase.\n */\nexport function findStorefrontClaims(\n  samples: readonly AiStorefrontCopySample[],\n  merchantWords = '',\n): AiStorefrontClaim[] {\n  const own = collapse(merchantWords)\n  const found: AiStorefrontClaim[] = []\n  for (const sample of samples) {\n    for (const { kind, pattern } of CLAIM_PATTERNS) {\n      for (const phrase of everyMatch(pattern, sample.text)) {\n        if (kind === 'endorsement' && own.includes(collapse(phrase))) continue\n        found.push({ kind, at: sample.at, phrase })\n      }\n    }\n  }\n  return found\n}\n\n/** A price in the samples that the merchant's own words do not state. */\nexport function findInventedPrices(\n  samples: readonly AiStorefrontCopySample[],\n  merchantWords = '',\n): AiStorefrontClaim[] {\n  const own = collapse(merchantWords)\n  const found: AiStorefrontClaim[] = []\n  for (const sample of samples) {\n    for (const phrase of everyMatch(PRICE, sample.text)) {\n      if (!own.includes(collapse(phrase))) found.push({ kind: 'financial', at: sample.at, phrase })\n    }\n  }\n  return found\n}\n\nconst CLAIM_WORDS: Readonly<Record<AiStorefrontClaimKind, string>> = {\n  health: 'a health claim',\n  financial: 'a financial claim',\n  legal: 'a legal claim',\n  endorsement: 'a certification, award or endorsement the product’s own text does not state',\n}\n\n/**\n * The claims as violations the generation loop re-asks for: one per kind, the\n * phrases quoted in the detail the model is told, the places in `paths`.\n */\nexport function storefrontClaimViolations(\n  claims: readonly AiStorefrontClaim[],\n  prices: readonly AiStorefrontClaim[] = [],\n): AiDoctrineViolation[] {\n  const violations: AiDoctrineViolation[] = []\n  const kinds = [...new Set(claims.map((claim) => claim.kind))]\n  for (const kind of kinds) {\n    const own = claims.filter((claim) => claim.kind === kind)\n    violations.push({\n      rule: null,\n      code: `storefront-claim-${kind}`,\n      message: `The copy makes ${CLAIM_WORDS[kind]}. Say what the product is and how it is used instead.`,\n      detail: `Remove: ${[...new Set(own.map((claim) => `\"${claim.phrase}\"`))].join(', ')}.`,\n      paths: [...new Set(own.map((claim) => claim.at))],\n    })\n  }\n  if (prices.length) {\n    violations.push({\n      rule: null,\n      code: 'storefront-price-invented',\n      message: 'The copy states a price nobody gave. Leave prices out; the merchant sets them.',\n      detail: `Remove: ${[...new Set(prices.map((price) => `\"${price.phrase}\"`))].join(', ')}.`,\n      paths: [...new Set(prices.map((price) => price.at))],\n    })\n  }\n  return violations\n}\n"],"names":["CONDITIONS","CLAIM_PATTERNS","kind","pattern","RegExp","PRICE","collapse","text","replace","trim","toLowerCase","everyMatch","global","source","flags","includes","matchAll","map","match","findStorefrontClaims","samples","merchantWords","own","found","sample","phrase","push","at","findInventedPrices","CLAIM_WORDS","health","financial","legal","endorsement","storefrontClaimViolations","claims","prices","violations","kinds","Set","claim","filter","rule","code","message","detail","join","paths","length","price"],"mappings":"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"}

package/src/lib/model/ai-template-subjects.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type BindingTokenCatalogEntry } from '@aglyn/aglyn/app-utils/binding-token-catalog';
+/**
+ * What a generated page template renders for (AGL-2909): one page drawn once
+ * per record the site already keeps.
+ *
+ * - `entry` — a content collection's entry page: a blog post, an event, a
+ *   case study. Picked as the collection's entry template screen.
+ * - `product` — the store's product page. Picked as the product template in
+ *   Store settings.
+ * - `author` — an author's page. Picked as the author page screen.
+ *
+ * Everything that differs per record is a binding token, and the tokens a
+ * template may bind are the ones the platform fills on that page. For an
+ * entry and an author those are the besigner's own insert-picker catalogs, so
+ * what a model may bind and what an author can pick are one list; a product's
+ * are the commerce product page's, which no catalog names yet (below).
+ *
+ * Model only: shapes, the vocabularies and the inputs reader, no runtime.
+ */
+export type AiTemplateSubject = 'entry' | 'product' | 'author';
+export declare const AI_TEMPLATE_SUBJECTS: readonly AiTemplateSubject[];
+/**
+ * The tokens the commerce product page fills. The commerce plugin's page
+ * resolver is their definition of record; a spec reads its source and holds
+ * this list to it in both directions, because a plugin never imports another
+ * plugin's internals.
+ */
+export declare const AI_PRODUCT_TEMPLATE_TOKENS: readonly BindingTokenCatalogEntry[];
+export interface AiTemplateSubjectDefinition {
+    subject: AiTemplateSubject;
+    /** One rendered page's record, as a sentence names it. */
+    noun: string;
+    /** The token the page's one h1 binds, so every record shows its own title. */
+    titleToken: string;
+    /** Every token the page may bind. */
+    tokens: readonly BindingTokenCatalogEntry[];
+    /**
+     * Palette blocks that fill themselves from this subject on its page, and
+     * render nothing on another subject's. Inside a Collection Entries card each
+     * fills from that card's entry instead, so a card is exempt.
+     */
+    blocks: readonly string[];
+    /** The template's name when the plan names none. */
+    defaultName: string;
+    /** Where a member puts the page to work, for the proposal and the docs. */
+    appliedIn: string;
+}
+export declare const AI_TEMPLATE_SUBJECT_DEFINITIONS: Readonly<Record<AiTemplateSubject, AiTemplateSubjectDefinition>>;
+/** Every `{{…}}` token a string holds, spelled without inner whitespace. */
+export declare function aiBindingTokensIn(value: string): string[];
+/**
+ * Whether a token may fill a link or media prop whole: its field is an
+ * address or a picture (`{{entry.url}}`, `{{entry.coverImage}}`,
+ * `{{author.image}}`), never copy.
+ */
+export declare function isAiAddressToken(token: string): boolean;
+/** The tokens of a subject a link or media prop may hold. */
+export declare function aiTemplateAddressTokens(definition: AiTemplateSubjectDefinition): string[];
+/** What a template job reads from its inputs. */
+export interface AiTemplateJobInputs {
+    subject: AiTemplateSubject;
+    /** The content collection an entry template is for; `null` for a product or author page. */
+    collectionId: string | null;
+}
+/** The inputs of a template job, or a sentence naming what is missing. */
+export declare function parseAiTemplateJobInputs(inputs: Readonly<Record<string, unknown>> | null | undefined): AiTemplateJobInputs | string;

package/src/lib/model/ai-template-subjects.js

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { AUTHOR_TOKEN_CATALOG, COLLECTION_TOKEN_CATALOG, ENTRY_TOKEN_CATALOG } from "@aglyn/aglyn/app-utils/binding-token-catalog";
+export const AI_TEMPLATE_SUBJECTS = [
+    'entry',
+    'product',
+    'author'
+];
+/**
+ * The tokens the commerce product page fills. The commerce plugin's page
+ * resolver is their definition of record; a spec reads its source and holds
+ * this list to it in both directions, because a plugin never imports another
+ * plugin's internals.
+ */ export const AI_PRODUCT_TEMPLATE_TOKENS = [
+    {
+        token: '{{product.name}}',
+        label: 'Name',
+        description: 'The product’s name.'
+    },
+    {
+        token: '{{product.description}}',
+        label: 'Description',
+        description: 'The product’s description.'
+    },
+    {
+        token: '{{product.price}}',
+        label: 'Price',
+        description: 'The price, or “From” the lowest price when variants differ.'
+    },
+    {
+        token: '{{product.image}}',
+        label: 'Image',
+        description: 'The product’s first image.'
+    },
+    {
+        token: '{{product.slug}}',
+        label: 'Slug',
+        description: 'The product’s URL segment.'
+    }
+];
+/** The pager tokens, which resolve on an author's page over their own archive. */ const PAGINATION_TOKENS = COLLECTION_TOKEN_CATALOG.filter((entry)=>entry.token.startsWith('{{pagination.'));
+export const AI_TEMPLATE_SUBJECT_DEFINITIONS = {
+    entry: {
+        subject: 'entry',
+        noun: 'a collection entry',
+        titleToken: '{{entry.title}}',
+        tokens: [
+            ...ENTRY_TOKEN_CATALOG,
+            ...COLLECTION_TOKEN_CATALOG
+        ],
+        blocks: [
+            'collectionEntryMeta',
+            'collectionEntryBody',
+            'collectionEntryAuthor',
+            'collectionRelated'
+        ],
+        defaultName: 'Entry page template',
+        appliedIn: 'the collection’s entry template screen, under Template screens in Content'
+    },
+    product: {
+        subject: 'product',
+        noun: 'a product',
+        titleToken: '{{product.name}}',
+        tokens: AI_PRODUCT_TEMPLATE_TOKENS,
+        blocks: [],
+        defaultName: 'Product page template',
+        appliedIn: 'the product page template in Store settings'
+    },
+    author: {
+        subject: 'author',
+        noun: 'an author',
+        titleToken: '{{author.name}}',
+        tokens: [
+            ...AUTHOR_TOKEN_CATALOG,
+            ...PAGINATION_TOKENS
+        ],
+        blocks: [
+            'contentAuthorProfile'
+        ],
+        defaultName: 'Author page template',
+        appliedIn: 'the author page screen on the Authors tab'
+    }
+};
+/** Every `{{…}}` token a string holds, spelled without inner whitespace. */ export function aiBindingTokensIn(value) {
+    return [
+        ...value.matchAll(/\{\{\s*([^{}\s]+)\s*\}\}/g)
+    ].map((match)=>`{{${match[1]}}}`);
+}
+/**
+ * Whether a token may fill a link or media prop whole: its field is an
+ * address or a picture (`{{entry.url}}`, `{{entry.coverImage}}`,
+ * `{{author.image}}`), never copy.
+ */ export function isAiAddressToken(token) {
+    var _token_replace_split_pop;
+    const field = (_token_replace_split_pop = token.replace(/^\{\{|\}\}$/g, '').split('.').pop()) != null ? _token_replace_split_pop : '';
+    return /^(?:url|image)$|(?:Url|Image|Video)$/.test(field);
+}
+/** The tokens of a subject a link or media prop may hold. */ export function aiTemplateAddressTokens(definition) {
+    return definition.tokens.map((entry)=>entry.token).filter(isAiAddressToken);
+}
+const RECORD_ID = /^[A-Za-z0-9_-]{1,100}$/;
+/** The inputs of a template job, or a sentence naming what is missing. */ export function parseAiTemplateJobInputs(inputs) {
+    var _ref;
+    const subject = String((_ref = inputs == null ? void 0 : inputs['subject']) != null ? _ref : '');
+    if (!AI_TEMPLATE_SUBJECTS.includes(subject)) {
+        return `Name what the template is for: inputs.subject is one of ${AI_TEMPLATE_SUBJECTS.join(', ')}`;
+    }
+    if (subject !== 'entry') return {
+        subject: subject,
+        collectionId: null
+    };
+    const raw = inputs == null ? void 0 : inputs['collectionId'];
+    const collectionId = typeof raw === 'string' ? raw.trim() : '';
+    if (!RECORD_ID.test(collectionId)) {
+        return 'An entry page template names its content collection in inputs.collectionId';
+    }
+    return {
+        subject: 'entry',
+        collectionId
+    };
+}
+
+//# sourceMappingURL=ai-template-subjects.js.map

package/src/lib/model/ai-template-subjects.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-template-subjects.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  AUTHOR_TOKEN_CATALOG,\n  COLLECTION_TOKEN_CATALOG,\n  ENTRY_TOKEN_CATALOG,\n  type BindingTokenCatalogEntry,\n} from '@aglyn/aglyn/app-utils/binding-token-catalog'\n\n/**\n * What a generated page template renders for (AGL-2909): one page drawn once\n * per record the site already keeps.\n *\n * - `entry` — a content collection's entry page: a blog post, an event, a\n *   case study. Picked as the collection's entry template screen.\n * - `product` — the store's product page. Picked as the product template in\n *   Store settings.\n * - `author` — an author's page. Picked as the author page screen.\n *\n * Everything that differs per record is a binding token, and the tokens a\n * template may bind are the ones the platform fills on that page. For an\n * entry and an author those are the besigner's own insert-picker catalogs, so\n * what a model may bind and what an author can pick are one list; a product's\n * are the commerce product page's, which no catalog names yet (below).\n *\n * Model only: shapes, the vocabularies and the inputs reader, no runtime.\n */\n\nexport type AiTemplateSubject = 'entry' | 'product' | 'author'\n\nexport const AI_TEMPLATE_SUBJECTS: readonly AiTemplateSubject[] = ['entry', 'product', 'author']\n\n/**\n * The tokens the commerce product page fills. The commerce plugin's page\n * resolver is their definition of record; a spec reads its source and holds\n * this list to it in both directions, because a plugin never imports another\n * plugin's internals.\n */\nexport const AI_PRODUCT_TEMPLATE_TOKENS: readonly BindingTokenCatalogEntry[] = [\n  { token: '{{product.name}}', label: 'Name', description: 'The product’s name.' },\n  {\n    token: '{{product.description}}',\n    label: 'Description',\n    description: 'The product’s description.',\n  },\n  {\n    token: '{{product.price}}',\n    label: 'Price',\n    description: 'The price, or “From” the lowest price when variants differ.',\n  },\n  { token: '{{product.image}}', label: 'Image', description: 'The product’s first image.' },\n  { token: '{{product.slug}}', label: 'Slug', description: 'The product’s URL segment.' },\n]\n\n/** The pager tokens, which resolve on an author's page over their own archive. */\nconst PAGINATION_TOKENS = COLLECTION_TOKEN_CATALOG.filter((entry) =>\n  entry.token.startsWith('{{pagination.'),\n)\n\nexport interface AiTemplateSubjectDefinition {\n  subject: AiTemplateSubject\n  /** One rendered page's record, as a sentence names it. */\n  noun: string\n  /** The token the page's one h1 binds, so every record shows its own title. */\n  titleToken: string\n  /** Every token the page may bind. */\n  tokens: readonly BindingTokenCatalogEntry[]\n  /**\n   * Palette blocks that fill themselves from this subject on its page, and\n   * render nothing on another subject's. Inside a Collection Entries card each\n   * fills from that card's entry instead, so a card is exempt.\n   */\n  blocks: readonly string[]\n  /** The template's name when the plan names none. */\n  defaultName: string\n  /** Where a member puts the page to work, for the proposal and the docs. */\n  appliedIn: string\n}\n\nexport const AI_TEMPLATE_SUBJECT_DEFINITIONS: Readonly<\n  Record<AiTemplateSubject, AiTemplateSubjectDefinition>\n> = {\n  entry: {\n    subject: 'entry',\n    noun: 'a collection entry',\n    titleToken: '{{entry.title}}',\n    tokens: [...ENTRY_TOKEN_CATALOG, ...COLLECTION_TOKEN_CATALOG],\n    blocks: ['collectionEntryMeta', 'collectionEntryBody', 'collectionEntryAuthor', 'collectionRelated'],\n    defaultName: 'Entry page template',\n    appliedIn: 'the collection’s entry template screen, under Template screens in Content',\n  },\n  product: {\n    subject: 'product',\n    noun: 'a product',\n    titleToken: '{{product.name}}',\n    tokens: AI_PRODUCT_TEMPLATE_TOKENS,\n    blocks: [],\n    defaultName: 'Product page template',\n    appliedIn: 'the product page template in Store settings',\n  },\n  author: {\n    subject: 'author',\n    noun: 'an author',\n    titleToken: '{{author.name}}',\n    tokens: [...AUTHOR_TOKEN_CATALOG, ...PAGINATION_TOKENS],\n    blocks: ['contentAuthorProfile'],\n    defaultName: 'Author page template',\n    appliedIn: 'the author page screen on the Authors tab',\n  },\n}\n\n/** Every `{{…}}` token a string holds, spelled without inner whitespace. */\nexport function aiBindingTokensIn(value: string): string[] {\n  return [...value.matchAll(/\\{\\{\\s*([^{}\\s]+)\\s*\\}\\}/g)].map((match) => `{{${match[1]}}}`)\n}\n\n/**\n * Whether a token may fill a link or media prop whole: its field is an\n * address or a picture (`{{entry.url}}`, `{{entry.coverImage}}`,\n * `{{author.image}}`), never copy.\n */\nexport function isAiAddressToken(token: string): boolean {\n  const field = token.replace(/^\\{\\{|\\}\\}$/g, '').split('.').pop() ?? ''\n  return /^(?:url|image)$|(?:Url|Image|Video)$/.test(field)\n}\n\n/** The tokens of a subject a link or media prop may hold. */\nexport function aiTemplateAddressTokens(definition: AiTemplateSubjectDefinition): string[] {\n  return definition.tokens.map((entry) => entry.token).filter(isAiAddressToken)\n}\n\n/** What a template job reads from its inputs. */\nexport interface AiTemplateJobInputs {\n  subject: AiTemplateSubject\n  /** The content collection an entry template is for; `null` for a product or author page. */\n  collectionId: string | null\n}\n\nconst RECORD_ID = /^[A-Za-z0-9_-]{1,100}$/\n\n/** The inputs of a template job, or a sentence naming what is missing. */\nexport function parseAiTemplateJobInputs(\n  inputs: Readonly<Record<string, unknown>> | null | undefined,\n): AiTemplateJobInputs | string {\n  const subject = String(inputs?.['subject'] ?? '')\n  if (!(AI_TEMPLATE_SUBJECTS as readonly string[]).includes(subject)) {\n    return `Name what the template is for: inputs.subject is one of ${AI_TEMPLATE_SUBJECTS.join(', ')}`\n  }\n  if (subject !== 'entry') return { subject: subject as AiTemplateSubject, collectionId: null }\n  const raw = inputs?.['collectionId']\n  const collectionId = typeof raw === 'string' ? raw.trim() : ''\n  if (!RECORD_ID.test(collectionId)) {\n    return 'An entry page template names its content collection in inputs.collectionId'\n  }\n  return { subject: 'entry', collectionId }\n}\n"],"names":["AUTHOR_TOKEN_CATALOG","COLLECTION_TOKEN_CATALOG","ENTRY_TOKEN_CATALOG","AI_TEMPLATE_SUBJECTS","AI_PRODUCT_TEMPLATE_TOKENS","token","label","description","PAGINATION_TOKENS","filter","entry","startsWith","AI_TEMPLATE_SUBJECT_DEFINITIONS","subject","noun","titleToken","tokens","blocks","defaultName","appliedIn","product","author","aiBindingTokensIn","value","matchAll","map","match","isAiAddressToken","field","replace","split","pop","test","aiTemplateAddressTokens","definition","RECORD_ID","parseAiTemplateJobInputs","inputs","String","includes","join","collectionId","raw","trim"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,oBAAoB,EACpBC,wBAAwB,EACxBC,mBAAmB,QAEd,+CAA8C;AAuBrD,OAAO,MAAMC,uBAAqD;IAAC;IAAS;IAAW;CAAS,CAAA;AAEhG;;;;;CAKC,GACD,OAAO,MAAMC,6BAAkE;IAC7E;QAAEC,OAAO;QAAoBC,OAAO;QAAQC,aAAa;IAAsB;IAC/E;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QACEF,OAAO;QACPC,OAAO;QACPC,aAAa;IACf;IACA;QAAEF,OAAO;QAAqBC,OAAO;QAASC,aAAa;IAA6B;IACxF;QAAEF,OAAO;QAAoBC,OAAO;QAAQC,aAAa;IAA6B;CACvF,CAAA;AAED,gFAAgF,GAChF,MAAMC,oBAAoBP,yBAAyBQ,MAAM,CAAC,CAACC,QACzDA,MAAML,KAAK,CAACM,UAAU,CAAC;AAuBzB,OAAO,MAAMC,kCAET;IACFF,OAAO;QACLG,SAAS;QACTC,MAAM;QACNC,YAAY;QACZC,QAAQ;eAAId;eAAwBD;SAAyB;QAC7DgB,QAAQ;YAAC;YAAuB;YAAuB;YAAyB;SAAoB;QACpGC,aAAa;QACbC,WAAW;IACb;IACAC,SAAS;QACPP,SAAS;QACTC,MAAM;QACNC,YAAY;QACZC,QAAQZ;QACRa,QAAQ,EAAE;QACVC,aAAa;QACbC,WAAW;IACb;IACAE,QAAQ;QACNR,SAAS;QACTC,MAAM;QACNC,YAAY;QACZC,QAAQ;eAAIhB;eAAyBQ;SAAkB;QACvDS,QAAQ;YAAC;SAAuB;QAChCC,aAAa;QACbC,WAAW;IACb;AACF,EAAC;AAED,0EAA0E,GAC1E,OAAO,SAASG,kBAAkBC,KAAa;IAC7C,OAAO;WAAIA,MAAMC,QAAQ,CAAC;KAA6B,CAACC,GAAG,CAAC,CAACC,QAAU,CAAC,EAAE,EAAEA,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AAC1F;AAEA;;;;CAIC,GACD,OAAO,SAASC,iBAAiBtB,KAAa;QAC9BA;IAAd,MAAMuB,SAAQvB,2BAAAA,MAAMwB,OAAO,CAAC,gBAAgB,IAAIC,KAAK,CAAC,KAAKC,GAAG,cAAhD1B,2BAAsD;IACpE,OAAO,uCAAuC2B,IAAI,CAACJ;AACrD;AAEA,2DAA2D,GAC3D,OAAO,SAASK,wBAAwBC,UAAuC;IAC7E,OAAOA,WAAWlB,MAAM,CAACS,GAAG,CAAC,CAACf,QAAUA,MAAML,KAAK,EAAEI,MAAM,CAACkB;AAC9D;AASA,MAAMQ,YAAY;AAElB,wEAAwE,GACxE,OAAO,SAASC,yBACdC,MAA4D;;IAE5D,MAAMxB,UAAUyB,eAAOD,0BAAAA,MAAQ,CAAC,UAAU,mBAAI;IAC9C,IAAI,CAAC,AAAClC,qBAA2CoC,QAAQ,CAAC1B,UAAU;QAClE,OAAO,CAAC,wDAAwD,EAAEV,qBAAqBqC,IAAI,CAAC,OAAO;IACrG;IACA,IAAI3B,YAAY,SAAS,OAAO;QAAEA,SAASA;QAA8B4B,cAAc;IAAK;IAC5F,MAAMC,MAAML,0BAAAA,MAAQ,CAAC,eAAe;IACpC,MAAMI,eAAe,OAAOC,QAAQ,WAAWA,IAAIC,IAAI,KAAK;IAC5D,IAAI,CAACR,UAAUH,IAAI,CAACS,eAAe;QACjC,OAAO;IACT;IACA,OAAO;QAAE5B,SAAS;QAAS4B;IAAa;AAC1C"}

package/src/lib/model/ai-theme-proposal.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type HostThemeSource } from '@aglyn/aglyn/app-utils/marketplace-theme';
+import type { HostTheme, HostThemeScheme } from '@aglyn/shared-data-types';
+import { type ThemeColorToken, type ThemeComponentOverrideLeaf, type ThemeEditorControlId } from '@aglyn/shared-ui-theme/util/theme-editor-fields';
+/**
+ * A theme proposal (AGL-2938): what a theme job hands a person to apply.
+ *
+ * Not a theme. A proposal is a set of theme editor controls set to values,
+ * applied to whatever the site's theme is when the person applies it, through
+ * the same writes the editor performs. A proposal that names three colors
+ * changes three colors, and every control it does not name is untouched by
+ * construction rather than by the model's restraint — which is what makes
+ * "make it feel warmer" a targeted diff instead of a regenerated theme.
+ *
+ * Pure and free of anything server-side: the job step builds a proposal, and
+ * the Theme section's widget previews and applies one, from this module.
+ */
+export declare const AI_THEME_PROPOSAL_VERSION = 1;
+/**
+ * `modify` changes what the brief is about and nothing else; `create` is a
+ * whole design over every control the editor has.
+ */
+export type AiThemeProposalMode = 'modify' | 'create';
+export declare const AI_THEME_PROPOSAL_MODES: readonly AiThemeProposalMode[];
+/** The parts of a theme a brief can be about. */
+export type AiThemeChangeGroup = 'color' | 'darkScheme' | 'typography' | 'shape' | 'spacing' | 'navigation' | 'components';
+export declare const AI_THEME_CHANGE_GROUPS: readonly AiThemeChangeGroup[];
+/** The controls a proposal sets one value on; component overrides are leaves of their own. */
+export type AiThemeValueControl = Exclude<ThemeEditorControlId, 'components'>;
+/** Every value control, as the catalog lists them. */
+export declare const AI_THEME_VALUE_CONTROLS: readonly AiThemeValueControl[];
+/** One editor control set to a value, or back to its default with `null`. */
+export interface AiThemeControlChange {
+    control: AiThemeValueControl;
+    /** The scheme a color is set for; `null` for every other control. */
+    scheme: HostThemeScheme | null;
+    value: string | number | null;
+    /** What the site had set when the proposal was made; `null` when it inherited. */
+    before: string | number | null;
+}
+/** A value the proposal carries that the model did not write, and why. */
+export interface AiThemeCorrection {
+    control: `color.${ThemeColorToken}`;
+    scheme: HostThemeScheme;
+    /** The value before the correction; `null` when the slot inherited. */
+    from: string | null;
+    to: string;
+    /**
+     * `contrast` — the pair fell below its bar and this is the nearest shade
+     * of the foreground that clears it. `dark-value` — the proposal changed an
+     * accent for light and gave no dark value, and this keeps the same hue
+     * readable on the dark background.
+     */
+    reason: 'contrast' | 'dark-value';
+    /** The colors a contrast correction was measured against. */
+    against?: string[];
+    /** The worst ratio before the correction. */
+    ratio?: number;
+    /** The bar the pair has to clear. */
+    required?: number;
+}
+export interface AiThemeProposal {
+    version: typeof AI_THEME_PROPOSAL_VERSION;
+    mode: AiThemeProposalMode;
+    /** One sentence naming what the proposal changes, in the brief's language. */
+    summary: string;
+    /**
+     * Where the site's theme came from when the proposal was made, which is
+     * how the editor's Save stores it: an installed theme's edits become its
+     * override patch, a default theme stores only the changed values, and a
+     * site's own theme changes in place.
+     */
+    source: HostThemeSource;
+    changes: AiThemeControlChange[];
+    components: ThemeComponentOverrideLeaf[];
+    /** The site's own component overrides are dropped before `components` apply. */
+    resetComponents: boolean;
+    corrections: AiThemeCorrection[];
+    /** What the model proposed that the proposal leaves out, in words. */
+    dropped: string[];
+    /** Anything else a person should read before applying, in words. */
+    notes: string[];
+}
+/** The color token a control writes, or `null` for a control that is not a color. */
+export declare function aiThemeColorToken(control: string): ThemeColorToken | null;
+/** What a control holds on a theme, as a proposal's `before` names it. */
+export declare function readAiThemeControl(theme: HostTheme | undefined, control: AiThemeValueControl, scheme: HostThemeScheme | null): string | number | null;
+/**
+ * The theme a set of changes produces on top of `theme`: each change written
+ * the way the editor writes it, then the component overrides. Returns a new
+ * object; `theme` is not mutated.
+ */
+export declare function applyAiThemeChanges(theme: HostTheme | undefined, proposal: {
+    changes: ReadonlyArray<Pick<AiThemeControlChange, 'control' | 'scheme' | 'value'>>;
+    components: readonly ThemeComponentOverrideLeaf[];
+    resetComponents: boolean;
+}): HostTheme;
+/** The part of the theme a value control belongs to. */
+export declare function aiThemeControlGroup(control: AiThemeValueControl): AiThemeChangeGroup;
+/**
+ * The part of the theme a component override belongs to: the type ramp's
+ * overrides are typography, the app bar's and the toolbar's are navigation,
+ * and the rest are components.
+ */
+export declare function aiThemeComponentGroup(component: ThemeComponentOverrideLeaf['component']): AiThemeChangeGroup;
+/**
+ * The parts of the theme a job may change. A `create` job is a whole design.
+ * A `modify` job may change only what its brief is about, so "make it feel
+ * warmer" reaches the colors and nothing else; a brief that names no part at
+ * all — in another language, or in words this does not know — is taken to
+ * be about the whole design rather than refused.
+ */
+export declare function aiThemeBriefScope(brief: string, mode: AiThemeProposalMode): ReadonlySet<AiThemeChangeGroup>;
+/** A color as the site renders it in one scheme: its own value, else the brand's. */
+export declare function effectiveThemeColor(theme: HostTheme | undefined, scheme: HostThemeScheme, token: ThemeColorToken): string | undefined;
+/**
+ * The colors a set of changes gives a light value and no dark one, while the
+ * site's dark scheme is on. Each is a visitor in dark mode seeing half a
+ * change.
+ */
+export declare function aiThemeMissingDarkValues(changes: ReadonlyArray<Pick<AiThemeControlChange, 'control' | 'scheme'>>, themeAfter: HostTheme): ThemeColorToken[];
+/**
+ * The dark value an accent keeps when a proposal gave none: the same hue,
+ * lightened only as far as it takes to read on the dark background as a fill
+ * or an indicator. Surfaces, text and tints have no such value — a pale light
+ * surface lightened is still a light surface — so they go on inheriting the
+ * platform's dark palette, which is what a site with no dark design renders.
+ */
+export declare function deriveAiThemeDarkAccent(light: string, themeAfter: HostTheme): string | null;
+/** A foreground that has to read on each of its backgrounds. */
+export interface AiThemeContrastPair {
+    foreground: ThemeColorToken;
+    backgrounds: readonly ThemeColorToken[];
+    required: number;
+}
+/**
+ * The pairs a proposal is held to. Body text on the page and on paper, and
+ * secondary text on the page, are the pairs the theme publish check
+ * (`validateThemeForPublish`) measures, at its bars; the primary color on
+ * the page is held to the bar a fill or an indicator owes.
+ */
+export declare const AI_THEME_CONTRAST_PAIRS: readonly AiThemeContrastPair[];
+export interface AiThemeContrastResult {
+    theme: HostTheme;
+    corrections: AiThemeCorrection[];
+    notes: string[];
+}
+/**
+ * Every pair a set of changes takes below its bar, corrected to the nearest
+ * shade of its foreground that clears it, and named.
+ *
+ * Only pairs the changes touched are corrected. A pair that already fell
+ * short with neither of its colors changed is named in `notes` and left
+ * alone, because correcting it would change a color the brief did not ask
+ * about. A dark scheme the site has switched off is not measured: no visitor
+ * sees it.
+ */
+export declare function correctAiThemeContrast(themeAfter: HostTheme, touchedChanges: ReadonlyArray<Pick<AiThemeControlChange, 'control' | 'scheme'>>): AiThemeContrastResult;
+export interface BuildAiThemeProposalInput {
+    /** The site's theme as the editor shows it, overrides resolved. */
+    base: HostTheme | undefined;
+    source: HostThemeSource;
+    mode: AiThemeProposalMode;
+    brief: string;
+    summary: string;
+    changes: ReadonlyArray<Pick<AiThemeControlChange, 'control' | 'scheme' | 'value'>>;
+    components: readonly ThemeComponentOverrideLeaf[];
+    resetComponents: boolean;
+    /** What reading the model's answer already left out, in words. */
+    dropped?: readonly string[];
+    notes?: readonly string[];
+}
+/**
+ * A proposal from what the model proposed, held to the editor and to the
+ * doctrine: changes that change nothing are gone, a modify brief reaches
+ * only the parts of the theme it names, accents keep a dark value, and every
+ * pair the proposal touches clears its contrast bar.
+ */
+export declare function buildAiThemeProposal(input: BuildAiThemeProposalInput): AiThemeProposal;
+/**
+ * What applying a proposal to the site's CURRENT theme produces, held to the
+ * contrast bars again: the theme may have changed since the proposal was
+ * made, and a proposal that cleared its bars against the old background can
+ * fall short against the new one. The corrections this makes are named
+ * beside the proposal's own.
+ */
+export declare function aiThemeProposalAfter(theme: HostTheme | undefined, proposal: Pick<AiThemeProposal, 'changes' | 'components' | 'resetComponents'>): AiThemeContrastResult;
+/** The changes whose `before` no longer matches the theme a proposal is applied to. */
+export declare function aiThemeStaleChanges(theme: HostTheme | undefined, proposal: Pick<AiThemeProposal, 'changes'>): AiThemeControlChange[];
+/**
+ * A proposal as a job output stores it, or `null` for anything that is not
+ * one. The job writes these through the Admin SDK and nothing else can, but
+ * a reader that applies what it reads to a theme checks the shape first.
+ */
+export declare function readAiThemeProposal(value: unknown): AiThemeProposal | null;