@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/tools/ai-seo-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/tools/ai-seo-tool.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 { MEDIA_ALT_MAX_LENGTH } from '@aglyn/aglyn/app-utils/media-alt'\nimport {\n  SEO_LISTING_FIELDS,\n  type SeoListingFieldKey,\n} from '@aglyn/aglyn/app-utils/seo-listing-fields'\nimport { HostEntityType } from '@aglyn/aglyn/foundation/definitions/platform.types'\nimport type {\n  AiSeoFieldValues,\n  AiSeoFindingCode,\n  AiSeoKeywordCoverage,\n  AiSeoSiteFormField,\n} from '../model/ai-seo'\nimport type { AiTool } from '../providers/contract'\nimport { AI_TEXT_LIMITS } from '../runtime/ai-palette'\nimport type { AiDoctrineViolation } from '../runtime/ai-doctrine-validators'\nimport type { AiSeoPageFacts } from '../runtime/seo-page-facts'\n\n/**\n * The strict tools SEO by AI answers through (AGL-2910), and the checks that\n * hold each answer to the editor it proposes for.\n *\n * - `propose_search_listing` — one page's or one product's listing. BUILT\n *   from the editor's own field list, the `seo-listing-fields` catalog the\n *   SEO card draws its inputs from, so a field and its length are said once:\n *   `ai-seo-tool.spec.ts` asserts the parity in both directions.\n * - `propose_seo_fixes` — one batch of a site audit's page fixes.\n * - `propose_site_listing` — the site's structured data and its guidance\n *   for AI agents, the two fields `/llms.txt` leads with.\n *\n * A strict schema forbids extra keys, requires every key and says \"no value\"\n * with `null`; it accepts no length keyword, so every length is stated in a\n * description and enforced here. A check returns a value only when nothing\n * in the answer is broken, and otherwise the violations and the parts at\n * fault, for the generation call's one re-ask.\n */\n\n/* ------------------------------------------------------------------------ *\n * Keywords: coverage, and what stuffing looks like\n * ------------------------------------------------------------------------ */\n\n/** Target keywords one listing may be asked to cover. */\nexport const AI_SEO_MAX_KEYWORDS = 5\n\n/** The most times one keyword may appear, per field, before it reads as stuffing. */\nexport const AI_SEO_KEYWORD_LIMITS: Readonly<Partial<Record<SeoListingFieldKey, number>>> = {\n  title: 1,\n  description: 2,\n  breadcrumb: 1,\n}\n\nconst escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n\n/** How many times `keyword` appears in `text` as whole words, any case. */\nexport function aiSeoKeywordCount(text: string | null | undefined, keyword: string): number {\n  const needle = keyword.trim().toLowerCase()\n  if (!needle || !text) return 0\n  const pattern = new RegExp(\n    `(^|[^\\\\p{L}\\\\p{N}])${escapeRegExp(needle).replace(/\\s+/g, '\\\\s+')}(?=$|[^\\\\p{L}\\\\p{N}])`,\n    'giu',\n  )\n  return [...text.toLowerCase().matchAll(pattern)].length\n}\n\n/** Keywords as a person typed them: trimmed, deduplicated, capped. */\nexport function aiSeoKeywordList(raw: unknown): string[] {\n  const parts = Array.isArray(raw) ? raw.map(String) : String(raw ?? '').split(/[,\\n]/)\n  const seen = new Set<string>()\n  const out: string[] = []\n  for (const part of parts) {\n    const keyword = part.replace(/\\s+/g, ' ').trim().slice(0, 60)\n    const key = keyword.toLowerCase()\n    if (!keyword || seen.has(key)) continue\n    seen.add(key)\n    out.push(keyword)\n    if (out.length >= AI_SEO_MAX_KEYWORDS) break\n  }\n  return out\n}\n\n/** Where a page already says each target keyword. */\nexport function aiSeoKeywordCoverage(\n  keywords: readonly string[],\n  sources: { title?: string | null; description?: string | null; h1?: string | null; body?: string | null },\n): AiSeoKeywordCoverage[] {\n  return keywords.map((keyword) => ({\n    keyword,\n    inTitle: aiSeoKeywordCount(sources.title, keyword) > 0,\n    inDescription: aiSeoKeywordCount(sources.description, keyword) > 0,\n    inH1: aiSeoKeywordCount(sources.h1, keyword) > 0,\n    inBody: aiSeoKeywordCount(sources.body, keyword) > 0,\n  }))\n}\n\n/** A word of four letters or more used three times in one short field reads as stuffing. */\nfunction repeatedWord(text: string): string | null {\n  const counts = new Map<string, number>()\n  for (const word of text.toLowerCase().match(/[\\p{L}\\p{N}]{4,}/gu) ?? []) {\n    const count = (counts.get(word) ?? 0) + 1\n    if (count >= 3) return word\n    counts.set(word, count)\n  }\n  return null\n}\n\nconst collapse = (value: unknown): string =>\n  typeof value === 'string' ? value.replace(/\\s+/g, ' ').trim() : ''\n\nconst text = (description: string) => ({ anyOf: [{ type: 'string' }, { type: 'null' }], description })\n\n/* ------------------------------------------------------------------------ *\n * One listing, from the editor's field list\n * ------------------------------------------------------------------------ */\n\nexport const AI_SEO_FIELDS_TOOL_NAME = 'propose_search_listing'\n\n/** The fields a listing proposal must fill; the image description may be left out. */\nexport const AI_SEO_REQUIRED_FIELDS: ReadonlySet<SeoListingFieldKey> = new Set([\n  'title',\n  'description',\n  'breadcrumb',\n])\n\n/** Fields in the catalog's order, whatever order a caller named them in. */\nexport function orderedSeoListingFields(fields: readonly SeoListingFieldKey[]): SeoListingFieldKey[] {\n  const wanted = new Set(fields)\n  return (Object.keys(SEO_LISTING_FIELDS) as SeoListingFieldKey[]).filter((key) => wanted.has(key))\n}\n\n/** The strict tool for a listing with exactly these fields, each required and nullable. */\nexport function aiSeoFieldsTool(fields: readonly SeoListingFieldKey[]): AiTool {\n  const keys = orderedSeoListingFields(fields)\n  const properties: Record<string, unknown> = {}\n  for (const key of keys) {\n    const field = SEO_LISTING_FIELDS[key]\n    properties[key] = text(\n      `${field.label}. ${field.purpose} At most ${field.maxLength} characters.` +\n        (AI_SEO_REQUIRED_FIELDS.has(key) ? '' : ' null when nothing you were given says what the picture shows.'),\n    )\n  }\n  return {\n    name: AI_SEO_FIELDS_TOOL_NAME,\n    description:\n      'Propose the search listing for one page or one product. Every field is required; ' +\n      'null means no value can be written from what you were given.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties,\n      required: keys,\n      additionalProperties: false,\n    },\n  }\n}\n\nexport interface AiSeoFieldsCheckContext {\n  fields: readonly SeoListingFieldKey[]\n  /** Whether the listing has a social image; without one, an image description is dropped. */\n  hasImage: boolean\n  keywords?: readonly string[]\n  /** Titles other pages of the site use, which this listing must not repeat. */\n  otherTitles?: readonly string[]\n}\n\nconst normalizeTitle = (value: string): string => value.replace(/\\s+/g, ' ').trim().toLowerCase()\n\n/**\n * A listing answer held to the editor: every requested text field written,\n * each within its length, no keyword past its per-field count, no word\n * repeated to rank, no title another page uses.\n */\nexport function checkAiSeoFields(\n  answer: Record<string, unknown>,\n  context: AiSeoFieldsCheckContext,\n): { value: AiSeoFieldValues | null; violations: AiDoctrineViolation[]; offending?: Record<string, unknown> } {\n  const values: AiSeoFieldValues = {}\n  const violations: AiDoctrineViolation[] = []\n  const offending: Record<string, unknown> = {}\n  const otherTitles = new Set((context.otherTitles ?? []).map(normalizeTitle))\n  for (const key of orderedSeoListingFields(context.fields)) {\n    const field = SEO_LISTING_FIELDS[key]\n    const raw = answer[key]\n    if (raw !== null && raw !== undefined && typeof raw !== 'string') {\n      violations.push({ rule: null, code: 'type', message: `${field.label} must be text or null.` })\n      offending[key] = raw\n      continue\n    }\n    const value = collapse(raw)\n    if (!value) {\n      if (AI_SEO_REQUIRED_FIELDS.has(key)) {\n        violations.push({ rule: null, code: 'missing', message: `${field.label} is required.` })\n      }\n      continue\n    }\n    // An image description with no image to describe is a sentence about\n    // nothing; it is left out rather than asked for again.\n    if (key === 'imageAlt' && !context.hasImage) continue\n    if (value.length > field.maxLength) {\n      violations.push({\n        rule: null,\n        code: 'too-long',\n        message: `${field.label} is ${value.length} characters; the limit is ${field.maxLength}.`,\n      })\n      offending[key] = value\n      continue\n    }\n    const limit = AI_SEO_KEYWORD_LIMITS[key]\n    const stuffed = limit\n      ? (context.keywords ?? []).find((keyword) => aiSeoKeywordCount(value, keyword) > limit)\n      : undefined\n    if (stuffed) {\n      violations.push({\n        rule: null,\n        code: 'keyword-stuffing',\n        message: `${field.label} repeats \"${stuffed}\"; use a keyword at most ${limit === 1 ? 'once' : `${limit} times`} there.`,\n      })\n      offending[key] = value\n      continue\n    }\n    const repeated = key === 'imageAlt' ? null : repeatedWord(value)\n    if (repeated) {\n      violations.push({ rule: null, code: 'repetition', message: `${field.label} repeats \"${repeated}\" three times.` })\n      offending[key] = value\n      continue\n    }\n    if (key === 'title' && otherTitles.has(normalizeTitle(value))) {\n      violations.push({\n        rule: null,\n        code: 'duplicate-title',\n        message: `The title \"${value}\" is already another page's title.`,\n      })\n      offending[key] = value\n      continue\n    }\n    values[key] = value\n  }\n  return violations.length ? { value: null, violations, offending } : { value: values, violations: [] }\n}\n\n/* ------------------------------------------------------------------------ *\n * A batch of a site audit's page fixes\n * ------------------------------------------------------------------------ */\n\nexport const AI_SEO_FIXES_TOOL_NAME = 'propose_seo_fixes'\n\n/**\n * How long an image description a batch proposes may be. Shorter than the\n * `alt` ceiling: a description read aloud is better short, and it keeps the\n * largest batch answer inside its measured budget.\n */\nexport const AI_SEO_FIX_ALT_MAX_CHARS = Math.min(150, MEDIA_ALT_MAX_LENGTH)\n\n/** Undescribed images one page of a batch gets descriptions for; the rest wait for the next audit. */\nexport const AI_SEO_FIX_IMAGES_PER_PAGE = 3\n\n/** The undescribed images a batch asks about for a page, in page order. */\nexport function aiSeoFixImages(page: Pick<AiSeoBatchPage, 'facts'>): AiSeoPageFacts['imagesMissingAlt'] {\n  return page.facts.imagesMissingAlt.slice(0, AI_SEO_FIX_IMAGES_PER_PAGE)\n}\n\n/** The strict tool for one batch: a title, description, heading and image descriptions per page. */\nexport function aiSeoFixesTool(screenIds: readonly string[]): AiTool {\n  return {\n    name: AI_SEO_FIXES_TOOL_NAME,\n    description:\n      'Propose fixes for the pages you were given. One entry per page; null means leave that value as it is.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties: {\n        pages: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              screenId: { type: 'string', enum: [...screenIds] },\n              title: text(`${SEO_LISTING_FIELDS.title.purpose} At most ${SEO_LISTING_FIELDS.title.maxLength} characters.`),\n              description: text(\n                `${SEO_LISTING_FIELDS.description.purpose} At most ${SEO_LISTING_FIELDS.description.maxLength} characters.`,\n              ),\n              h1: text(`The page’s one main heading. At most ${AI_TEXT_LIMITS.headline} characters.`),\n              imageAlts: {\n                type: 'array',\n                items: {\n                  type: 'object',\n                  properties: {\n                    nodeId: { type: 'string' },\n                    alt: {\n                      type: 'string',\n                      description: `What the picture shows. At most ${AI_SEO_FIX_ALT_MAX_CHARS} characters.`,\n                    },\n                  },\n                  required: ['nodeId', 'alt'],\n                  additionalProperties: false,\n                },\n              },\n            },\n            required: ['screenId', 'title', 'description', 'h1', 'imageAlts'],\n            additionalProperties: false,\n          },\n        },\n      },\n      required: ['pages'],\n      additionalProperties: false,\n    },\n  }\n}\n\n/** A batch page as the fixes prompt and check read it. */\nexport interface AiSeoBatchPage {\n  screenId: string\n  path: string\n  name: string\n  codes: ReadonlySet<AiSeoFindingCode>\n  keywords: readonly string[]\n  seo: { title?: string; description?: string; breadcrumb?: string; image?: string; imageAlt?: string } | undefined\n  facts: AiSeoPageFacts\n}\n\n/** The findings that let a batch answer propose each value. */\nexport const AI_SEO_FIX_CODES = {\n  title: ['title-missing', 'title-too-long', 'title-duplicate', 'keyword-missing'],\n  description: ['description-missing', 'description-too-long', 'description-duplicate', 'keyword-missing'],\n  h1: ['h1-missing', 'h1-thin'],\n} as const satisfies Record<string, readonly AiSeoFindingCode[]>\n\nexport interface AiSeoBatchAnswer {\n  title: string | null\n  description: string | null\n  h1: string | null\n  imageAlts: Array<{ nodeId: string; alt: string }>\n}\n\n/**\n * A batch answer held to the audit and the editor: values only where a\n * finding asked for them, each within its length, no keyword past its count,\n * no title another page uses, and image descriptions only for this page's\n * undescribed images.\n */\nexport function checkAiSeoFixes(\n  answer: Record<string, unknown>,\n  pages: readonly AiSeoBatchPage[],\n  titlesElsewhere: readonly string[],\n): { value: Record<string, AiSeoBatchAnswer> | null; violations: AiDoctrineViolation[]; offending?: Record<string, unknown> } {\n  const byId = new Map(pages.map((page) => [page.screenId, page]))\n  const violations: AiDoctrineViolation[] = []\n  const offending: Array<Record<string, unknown>> = []\n  const value: Record<string, AiSeoBatchAnswer> = {}\n  const taken = new Set(titlesElsewhere.map(normalizeTitle))\n  const entries = Array.isArray(answer['pages']) ? (answer['pages'] as unknown[]) : null\n  if (!entries) {\n    return { value: null, violations: [{ rule: null, code: 'shape', message: 'The answer must list the pages.' }] }\n  }\n  const asks = (page: AiSeoBatchPage, codes: readonly AiSeoFindingCode[]) =>\n    codes.some((code) => page.codes.has(code))\n  for (const raw of entries) {\n    const entry = (raw ?? {}) as Record<string, unknown>\n    const page = byId.get(String(entry['screenId'] ?? ''))\n    if (!page || value[page.screenId]) continue\n    const broken: string[] = []\n    const fix: AiSeoBatchAnswer = { title: null, description: null, h1: null, imageAlts: [] }\n\n    const title = collapse(entry['title'])\n    if (title && asks(page, AI_SEO_FIX_CODES.title)) {\n      if (title.length > SEO_LISTING_FIELDS.title.maxLength) {\n        broken.push(`title is ${title.length} characters; the limit is ${SEO_LISTING_FIELDS.title.maxLength}`)\n      } else if (page.keywords.some((keyword) => aiSeoKeywordCount(title, keyword) > (AI_SEO_KEYWORD_LIMITS.title ?? 1))) {\n        broken.push('title repeats a keyword')\n      } else if (taken.has(normalizeTitle(title))) {\n        broken.push(`title \"${title}\" is another page's title`)\n      } else {\n        fix.title = title\n        taken.add(normalizeTitle(title))\n      }\n    }\n    const description = collapse(entry['description'])\n    if (description && asks(page, AI_SEO_FIX_CODES.description)) {\n      if (description.length > SEO_LISTING_FIELDS.description.maxLength) {\n        broken.push(\n          `description is ${description.length} characters; the limit is ${SEO_LISTING_FIELDS.description.maxLength}`,\n        )\n      } else if (\n        page.keywords.some((keyword) => aiSeoKeywordCount(description, keyword) > (AI_SEO_KEYWORD_LIMITS.description ?? 2))\n      ) {\n        broken.push('description repeats a keyword')\n      } else {\n        fix.description = description\n      }\n    }\n    const h1 = collapse(entry['h1'])\n    if (h1 && asks(page, AI_SEO_FIX_CODES.h1)) {\n      if (h1.length > AI_TEXT_LIMITS.headline) {\n        broken.push(`h1 is ${h1.length} characters; the limit is ${AI_TEXT_LIMITS.headline}`)\n      } else {\n        fix.h1 = h1\n      }\n    }\n    const undescribed = new Set(aiSeoFixImages(page).map((image) => image.nodeId))\n    for (const rawAlt of Array.isArray(entry['imageAlts']) ? (entry['imageAlts'] as unknown[]) : []) {\n      const altEntry = (rawAlt ?? {}) as Record<string, unknown>\n      const nodeId = String(altEntry['nodeId'] ?? '')\n      const alt = collapse(altEntry['alt'])\n      if (!undescribed.has(nodeId) || !alt || fix.imageAlts.some((known) => known.nodeId === nodeId)) continue\n      if (alt.length > AI_SEO_FIX_ALT_MAX_CHARS) {\n        broken.push(`the description of image ${nodeId} is over ${AI_SEO_FIX_ALT_MAX_CHARS} characters`)\n      } else {\n        fix.imageAlts.push({ nodeId, alt })\n      }\n    }\n    if (broken.length) {\n      violations.push(...broken.map((message) => ({ rule: null, code: 'fix', message: `Page ${page.screenId}: ${message}.` })))\n      offending.push(entry)\n    } else {\n      value[page.screenId] = fix\n    }\n  }\n  return violations.length ? { value: null, violations, offending: { pages: offending } } : { value, violations: [] }\n}\n\n/* ------------------------------------------------------------------------ *\n * The site: structured data and guidance for AI agents\n * ------------------------------------------------------------------------ */\n\nexport const AI_SEO_SITE_TOOL_NAME = 'propose_site_listing'\n\n/** The longest structured-data description the site SEO form accepts. */\nexport const AI_SEO_ENTITY_DESCRIPTION_MAX_CHARS = 300\n\n/** The longest agent guidance the site SEO form accepts. */\nexport const AI_SEO_AGENT_GUIDANCE_MAX_CHARS = 1_000\n\n/** The entity types the tool offers, and the value the site SEO form stores for each. */\nexport const AI_SEO_ENTITY_TYPE_VALUES: Readonly<Record<string, string>> = {\n  Organization: `${HostEntityType.ORGANIZATION}`,\n  Person: `${HostEntityType.PERSON}`,\n}\n\n/** The site-wide proposal's strict tool: structured data and agent guidance, each nullable. */\nexport function aiSeoSiteTool(): AiTool {\n  const properties = {\n    entityType: {\n      anyOf: [{ type: 'string', enum: Object.keys(AI_SEO_ENTITY_TYPE_VALUES) }, { type: 'null' }],\n      description: 'Whether a company or a person publishes the site.',\n    },\n    entityName: text('The publisher’s name as the site gives it.'),\n    entityDescription: text(\n      `What the publisher IS, in one sentence — not what a page is about. At most ${AI_SEO_ENTITY_DESCRIPTION_MAX_CHARS} characters.`,\n    ),\n    contactEmail: text('A contact email address, only when a page of the site shows it.'),\n    contactTelephone: text('A contact telephone number, only when a page of the site shows it.'),\n    contactType: text('What that contact answers, such as customer support or sales.'),\n    whenToUse: text(\n      `For AI agents: the questions this site is the best source for, specifically. At most ${AI_SEO_AGENT_GUIDANCE_MAX_CHARS} characters.`,\n    ),\n    howToUse: text(\n      `For AI agents: which pages answer what, and what not to rely on. At most ${AI_SEO_AGENT_GUIDANCE_MAX_CHARS} characters.`,\n    ),\n  }\n  return {\n    name: AI_SEO_SITE_TOOL_NAME,\n    description:\n      'Propose the site’s structured data and its guidance for AI agents. Every field is required; null means leave it as it is.',\n    strict: true,\n    inputSchema: {\n      type: 'object',\n      properties,\n      required: Object.keys(properties),\n      additionalProperties: false,\n    },\n  }\n}\n\nexport interface AiSeoSiteCheckContext {\n  /** The form fields that are blank on the site now; only these may be proposed. */\n  blank: ReadonlySet<AiSeoSiteFormField>\n  /** Every word the site's pages show, for the contact details to be found in. */\n  siteText: string\n}\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\n/**\n * The site proposal held to the form and to the site: lengths, and a contact\n * detail only when a page shows it. A detail no page shows is left out with\n * a note rather than asked for again — asking again invites composing one.\n */\nexport function checkAiSeoSite(\n  answer: Record<string, unknown>,\n  context: AiSeoSiteCheckContext,\n): {\n  value: { values: Partial<Record<AiSeoSiteFormField, string>>; notes: string[] } | null\n  violations: AiDoctrineViolation[]\n  offending?: Record<string, unknown>\n} {\n  const values: Partial<Record<AiSeoSiteFormField, string>> = {}\n  const notes: string[] = []\n  const violations: AiDoctrineViolation[] = []\n  const offending: Record<string, unknown> = {}\n  const put = (field: AiSeoSiteFormField, value: string) => {\n    if (value && context.blank.has(field)) values[field] = value\n  }\n\n  const type = collapse(answer['entityType'])\n  if (type && AI_SEO_ENTITY_TYPE_VALUES[type]) put('seo.entity.type', AI_SEO_ENTITY_TYPE_VALUES[type])\n  put('seo.entity.name', collapse(answer['entityName']).slice(0, 200))\n\n  const description = collapse(answer['entityDescription'])\n  if (description.length > AI_SEO_ENTITY_DESCRIPTION_MAX_CHARS) {\n    violations.push({\n      rule: null,\n      code: 'too-long',\n      message: `The entity description is ${description.length} characters; the limit is ${AI_SEO_ENTITY_DESCRIPTION_MAX_CHARS}.`,\n    })\n    offending['entityDescription'] = description\n  } else {\n    put('seo.entity.description', description)\n  }\n\n  const siteText = context.siteText.toLowerCase()\n  const siteDigits = context.siteText.replace(/\\D+/g, '')\n  const email = collapse(answer['contactEmail'])\n  if (email) {\n    if (EMAIL.test(email) && siteText.includes(email.toLowerCase())) put('seo.entity.email', email)\n    else notes.push('A contact email was left out: no page of the site shows it.')\n  }\n  const telephone = collapse(answer['contactTelephone'])\n  if (telephone) {\n    const digits = telephone.replace(/\\D+/g, '')\n    if (digits.length >= 7 && siteDigits.includes(digits)) put('seo.entity.telephone', telephone)\n    else notes.push('A contact telephone number was left out: no page of the site shows it.')\n  }\n  if (values['seo.entity.email'] || values['seo.entity.telephone']) {\n    put('seo.entity.contactType', collapse(answer['contactType']).slice(0, 100))\n  }\n\n  for (const [key, field] of [\n    ['whenToUse', 'seo.agent.whenToUse'],\n    ['howToUse', 'seo.agent.howToUse'],\n  ] as const) {\n    const guidance = collapse(answer[key])\n    if (guidance.length > AI_SEO_AGENT_GUIDANCE_MAX_CHARS) {\n      violations.push({\n        rule: null,\n        code: 'too-long',\n        message: `${key} is ${guidance.length} characters; the limit is ${AI_SEO_AGENT_GUIDANCE_MAX_CHARS}.`,\n      })\n      offending[key] = guidance\n    } else {\n      put(field, guidance)\n    }\n  }\n  return violations.length ? { value: null, violations, offending } : { value: { values, notes }, violations: [] }\n}\n"],"names":["MEDIA_ALT_MAX_LENGTH","SEO_LISTING_FIELDS","HostEntityType","AI_TEXT_LIMITS","AI_SEO_MAX_KEYWORDS","AI_SEO_KEYWORD_LIMITS","title","description","breadcrumb","escapeRegExp","value","replace","aiSeoKeywordCount","text","keyword","needle","trim","toLowerCase","pattern","RegExp","matchAll","length","aiSeoKeywordList","raw","parts","Array","isArray","map","String","split","seen","Set","out","part","slice","key","has","add","push","aiSeoKeywordCoverage","keywords","sources","inTitle","inDescription","inH1","h1","inBody","body","repeatedWord","counts","Map","word","match","count","get","set","collapse","anyOf","type","AI_SEO_FIELDS_TOOL_NAME","AI_SEO_REQUIRED_FIELDS","orderedSeoListingFields","fields","wanted","Object","keys","filter","aiSeoFieldsTool","properties","field","label","purpose","maxLength","name","strict","inputSchema","required","additionalProperties","normalizeTitle","checkAiSeoFields","answer","context","values","violations","offending","otherTitles","undefined","rule","code","message","hasImage","limit","stuffed","find","repeated","AI_SEO_FIXES_TOOL_NAME","AI_SEO_FIX_ALT_MAX_CHARS","Math","min","AI_SEO_FIX_IMAGES_PER_PAGE","aiSeoFixImages","page","facts","imagesMissingAlt","aiSeoFixesTool","screenIds","pages","items","screenId","enum","headline","imageAlts","nodeId","alt","AI_SEO_FIX_CODES","checkAiSeoFixes","titlesElsewhere","byId","taken","entries","asks","codes","some","entry","broken","fix","undescribed","image","rawAlt","altEntry","known","AI_SEO_SITE_TOOL_NAME","AI_SEO_ENTITY_DESCRIPTION_MAX_CHARS","AI_SEO_AGENT_GUIDANCE_MAX_CHARS","AI_SEO_ENTITY_TYPE_VALUES","Organization","ORGANIZATION","Person","PERSON","aiSeoSiteTool","entityType","entityName","entityDescription","contactEmail","contactTelephone","contactType","whenToUse","howToUse","EMAIL","checkAiSeoSite","notes","put","blank","siteText","siteDigits","email","test","includes","telephone","digits","guidance"],"mappings":"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"}

package/src/lib/tools/ai-theme-tool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @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 ThemeComponentOverrideLeaf, type ThemeEditorControl, type ThemeEditorControlId } from '@aglyn/shared-ui-theme/util/theme-editor-fields';
+import type { AiThemeControlChange } from '../model/ai-theme-proposal';
+import type { AiTool } from '../providers/contract';
+/**
+ * The theme tool (AGL-2938): the one structured-output tool a theme job asks
+ * the model to call, DERIVED from the theme editor's field catalog.
+ *
+ * Every property of the schema carries editor controls, and every editor
+ * control is carried by a property — `ai-theme-tool.spec.ts` holds both
+ * directions — so the model is offered exactly what a person editing the
+ * theme is offered: the same color tokens, the same fonts, the same bounds
+ * and the same component whitelist. A control added to the editor fails that
+ * spec until it is offered here too.
+ *
+ * The schema is strict, which on the providers that enforce it means every
+ * object forbids extra keys, every key is required, and "no change" is said
+ * with `null`. Numeric bounds are not keywords a strict schema accepts, so
+ * they are stated in the descriptions and enforced by
+ * {@link parseAiThemeToolInput}, from the same catalog entries.
+ */
+export declare const AI_THEME_TOOL_NAME = "propose_theme_changes";
+/** The value that returns a color or a number to its default. */
+export declare const AI_THEME_TOOL_DEFAULT = "default";
+/** The catalog's color controls, which the `colors` property carries. */
+export declare const AI_THEME_COLOR_CONTROLS: readonly ThemeEditorControl[];
+/** How many component override leaves one call may carry. */
+export declare const AI_THEME_TOOL_MAX_COMPONENT_LEAVES = 40;
+/** The longest summary a proposal keeps. */
+export declare const AI_THEME_SUMMARY_MAX_CHARS = 300;
+/**
+ * Which schema property carries which editor controls. `colors` carries
+ * every color control in both schemes; the rest carry one control each, and
+ * the two component properties both carry the JSON overrides control.
+ */
+export declare const AI_THEME_TOOL_PROPERTIES: ReadonlyArray<{
+    property: string;
+    controls: readonly ThemeEditorControlId[];
+}>;
+/** Properties that carry no editor control: what the call says about itself. */
+export declare const AI_THEME_TOOL_META_PROPERTIES: readonly ["summary"];
+/**
+ * Parity between the editor's catalog and the tool, in both directions: the
+ * controls the tool does not offer, and the control ids it offers that the
+ * catalog does not have. Both are empty, or the tool and the editor offer
+ * different things.
+ */
+export declare function aiThemeToolParity(controls?: ReadonlyArray<Pick<ThemeEditorControl, 'id'>>): {
+    unoffered: string[];
+    unknown: string[];
+};
+export declare const AI_THEME_STYLE_PROPERTIES: readonly string[];
+/**
+ * The component props a theme may set a default for: the ones that choose
+ * among a component's own looks. Nothing that changes what an element IS — an
+ * `href`, a `component`, a handler — is a theme's to default.
+ */
+export declare const AI_THEME_DEFAULT_PROPS: readonly string[];
+/** Whether a CSS value carries a literal color, which belongs to the palette. */
+export declare function carriesLiteralColor(value: string): boolean;
+/**
+ * The tool, built from the catalog. Deterministic for a given catalog, so its
+ * bytes are the same on every request and it sits inside the cached prefix.
+ */
+export declare function aiThemeTool(): AiTool;
+/** What a tool call proposes, held to the editor's constraints. */
+export interface AiThemeToolParse {
+    summary: string;
+    changes: Array<Omit<AiThemeControlChange, 'before'>>;
+    components: ThemeComponentOverrideLeaf[];
+    resetComponents: boolean;
+    /** What the call wrote that the editor would not accept, in words. */
+    dropped: string[];
+    /** What was kept only once it was brought inside the editor's bounds. */
+    notes: string[];
+}
+/** `#abc` or `#aabbcc` as the editor's picker writes it: six lowercase digits. */
+export declare function normalizeThemeHex(value: string): string | null;
+/**
+ * A tool call's input, held to the editor's constraints: tokens and fonts
+ * from the catalog, hex colors as the picker writes them, numbers inside the
+ * editor's bounds, and component leaves on the whitelist with safe values
+ * and no literal color. What does not hold is dropped and named rather than
+ * guessed at; a number out of bounds is brought inside them and named.
+ */
+export declare function parseAiThemeToolInput(input: Record<string, unknown>): AiThemeToolParse;