@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/seo-fields.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @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 { SeoListingFieldKey } from '@aglyn/aglyn/app-utils/seo-listing-fields';
+import type { AiSeoFieldValues } from '../model/ai-seo';
+import type { AiStepKind } from '../providers/catalog';
+import type { AiProvider } from '../providers/contract';
+import { type AiPluginSettings } from '../providers/routing';
+import { type AiValidatedGeneration } from './ai-doctrine';
+import type { AiSystemBlock } from './ai-runtime';
+/**
+ * SEO fields by AI (AGL-2910): a search listing — title, description,
+ * breadcrumb label, image description — written from what a page or a
+ * product actually says, and held to the lengths its editor enforces.
+ *
+ * `generateSeoFields` is the one entry point. The "Write SEO" card on a
+ * page's SEO panel and on a product's listing calls it through an `seo` job,
+ * and a page generator calls it for the title and description of the page it
+ * builds. It proposes; it never writes a listing anywhere.
+ *
+ * The tool the model answers through, and the check that holds the answer to
+ * the editor, are `tools/ai-seo-tool.ts`: the tool is built from the editor's
+ * own field list, so a field and its length are said once.
+ *
+ * ## The request
+ *
+ * The fast tier through the routing table (`job.seo`), never a model
+ * literal, and the building doctrine's generation call
+ * (`runValidatedGeneration`, AGL-3009): the doctrine's cached block, which
+ * carries the acceptable-use rules, then these rules, cached after it. The
+ * page's text, its current listing, the site's name and the target keywords
+ * ride in the user turn, so no byte of a site sits inside the cached prefix,
+ * and no site inventory is sent: a listing is written from its page.
+ */
+/**
+ * The output budget, from the routing table. The largest answer the tool
+ * accepts — every field at its limit — is under 300 tokens of JSON
+ * (`ai-job-seo-step.spec.ts` measures it); the rest is headroom, and the fast
+ * tier thinks in none of it.
+ */
+export declare const AI_SEO_FIELDS_MAX_TOKENS: number;
+/** What a listing request carries, and therefore which rules it is sent. */
+export interface AiSeoFieldsInstructionShape {
+    fields: readonly SeoListingFieldKey[];
+    keywords: boolean;
+    otherTitles: boolean;
+}
+/**
+ * The rules for one listing request.
+ *
+ * Byte-identical for every request of the same SHAPE, and identical across
+ * workspaces at every shape: no site's name, text or listing is in here, so
+ * two tenants writing the same kind of listing send the same rules. That is
+ * the invariant `runtime/ai-prompt-cache.spec.ts` holds, and it is weaker
+ * than "one block for everything" on purpose — a rule about target keywords
+ * is worth nothing to a request that carries none, and `job.seo` runs on a
+ * model that caches no prompt this short, so an unread rule is simply paid
+ * for at full input rate on every attempt and every re-ask.
+ */
+export declare function aiSeoFieldsInstructions(shape: AiSeoFieldsInstructionShape): AiSystemBlock[];
+/** The rules for a listing of the default shape, for a door that names no other. */
+export declare const AI_SEO_FIELDS_INSTRUCTIONS: AiSystemBlock[];
+/**
+ * What the site itself is, in the words of whoever set it up (AGL-2918).
+ *
+ * A page's own text says what the page is; it does not say who the page is
+ * written for. On a site whose pages have just been generated that gap is at
+ * its widest — every page reads like the same competent stranger wrote it —
+ * so the words the owner used are carried into the listing rather than
+ * inferred back out of the copy they produced.
+ *
+ * It rides in the user turn and nowhere else: it is one site's own words, so
+ * putting it in a rules block would key the platform's cache entry on a
+ * tenant's sentence, and the rules already say to write from what is given.
+ */
+export interface AiSeoSiteWords {
+    /** What kind of site it is: "a neighborhood dog groomer". */
+    about?: string | null;
+    /** Who it is for: "local dog owners who want a regular groom booked online". */
+    audience?: string | null;
+}
+export interface AiSeoFieldsPromptInput {
+    subject: {
+        kind: 'screen' | 'product';
+        name: string;
+        path?: string | null;
+    };
+    /** The site's name, as its visitors see it. */
+    brand: string;
+    /** What the site is and who it is for, where the caller knows (AGL-2918). */
+    site?: AiSeoSiteWords | null;
+    /** What the page or the product says: a page's Markdown, a product's description. */
+    text: string;
+    fields: readonly SeoListingFieldKey[];
+    current?: AiSeoFieldValues;
+    /**
+     * What is known about the share image, when the listing has one: the
+     * description it carries, and the page text around the same picture where
+     * the page shows it.
+     */
+    image?: {
+        alt?: string | null;
+        context?: string | null;
+    } | null;
+    keywords?: readonly string[];
+    otherTitles?: readonly string[];
+}
+/** The user turn: the subject, what it says now, and the page's own text. */
+export declare function aiSeoFieldsPrompt(input: AiSeoFieldsPromptInput): string;
+export interface GenerateSeoFieldsInput extends Omit<AiSeoFieldsPromptInput, 'fields'> {
+    /** The fields to write; the title, description and breadcrumb label when omitted. */
+    fields?: readonly SeoListingFieldKey[];
+    /** The step kind the call is routed as; `job.seo` when omitted. */
+    step?: AiStepKind;
+    settings?: AiPluginSettings;
+    model?: string;
+    /**
+     * The answer's ceiling: `AI_SEO_FIELDS_MAX_TOKENS` when omitted. A job step
+     * passes the most its registered time allows on the model it runs
+     * (AGL-3035).
+     */
+    maxTokens?: number;
+    signal?: AbortSignal;
+    provider?: AiProvider;
+}
+/** What a listing is written with when the caller names no fields. */
+export declare const AI_SEO_DEFAULT_FIELDS: readonly SeoListingFieldKey[];
+/**
+ * Propose a search listing for a page or a product.
+ *
+ * STABLE: a page generator calls this for the title and description of a
+ * page it builds (`fields: ['title', 'description']`), and the `seo` job
+ * calls it for a page's or a product's whole listing. It asks the routing
+ * table's `job.seo` model through the doctrine's generation call and resolves
+ * to its result — `ok` with the values, `needs_input` when the answer could
+ * not be held to the editor after one re-ask, `refused` when the model
+ * declined. It writes nothing.
+ */
+export declare function generateSeoFields(input: GenerateSeoFieldsInput): Promise<AiValidatedGeneration<AiSeoFieldValues>>;

package/src/lib/runtime/seo-fields.js

@@ -0,0 +1,215 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { AI_ROUTING_TABLE } from "../providers/routing.js";
+import { AI_SEO_FIELDS_TOOL_NAME, aiSeoFieldsTool, checkAiSeoFields, orderedSeoListingFields } from "../tools/ai-seo-tool.js";
+import { runValidatedGeneration } from "./ai-doctrine.js";
+/**
+ * SEO fields by AI (AGL-2910): a search listing — title, description,
+ * breadcrumb label, image description — written from what a page or a
+ * product actually says, and held to the lengths its editor enforces.
+ *
+ * `generateSeoFields` is the one entry point. The "Write SEO" card on a
+ * page's SEO panel and on a product's listing calls it through an `seo` job,
+ * and a page generator calls it for the title and description of the page it
+ * builds. It proposes; it never writes a listing anywhere.
+ *
+ * The tool the model answers through, and the check that holds the answer to
+ * the editor, are `tools/ai-seo-tool.ts`: the tool is built from the editor's
+ * own field list, so a field and its length are said once.
+ *
+ * ## The request
+ *
+ * The fast tier through the routing table (`job.seo`), never a model
+ * literal, and the building doctrine's generation call
+ * (`runValidatedGeneration`, AGL-3009): the doctrine's cached block, which
+ * carries the acceptable-use rules, then these rules, cached after it. The
+ * page's text, its current listing, the site's name and the target keywords
+ * ride in the user turn, so no byte of a site sits inside the cached prefix,
+ * and no site inventory is sent: a listing is written from its page.
+ */ /* ------------------------------------------------------------------------ *
+ * The request
+ * ------------------------------------------------------------------------ */ /**
+ * The output budget, from the routing table. The largest answer the tool
+ * accepts — every field at its limit — is under 300 tokens of JSON
+ * (`ai-job-seo-step.spec.ts` measures it); the rest is headroom, and the fast
+ * tier thinks in none of it.
+ */ export const AI_SEO_FIELDS_MAX_TOKENS = AI_ROUTING_TABLE['job.seo'].maxTokens;
+/** How many other pages' titles a prompt lists for the model to avoid. */ const OTHER_TITLES_LISTED = 40;
+/**
+ * What one listing field's rule ADDS to the tool's own description of that
+ * field (AGL-2937), stated only when the field is asked for.
+ *
+ * The schema the answer arrives through is built from the editor's field
+ * catalog, and it already names each field, says what the value is for and
+ * states its length. It rides in the same request, ahead of these blocks, so
+ * a rule that restated it would be the same sentence billed twice on a door
+ * whose prompt no model will cache. Each rule here is therefore only what
+ * the schema does not say: how to write the field rather than what it is.
+ * The image description has no rule at all, because its description already
+ * carries both halves of one — what it describes, and when to answer null.
+ *
+ * `runtime/ai-prompt-cache.spec.ts` holds the pair together: whatever
+ * `checkAiSeoFields` can refuse an answer for, the request has to state
+ * somewhere, in a block or in the schema.
+ */ const AI_SEO_FIELD_RULES = {
+    title: 'The title says what the page is, specifically and in plain words; add the site name only where it helps.',
+    description: 'The description is one or two sentences: no quotation marks, no emoji, no capitals for emphasis.',
+    breadcrumb: 'The breadcrumb label is one to three words.'
+};
+/**
+ * The rules for one listing request.
+ *
+ * Byte-identical for every request of the same SHAPE, and identical across
+ * workspaces at every shape: no site's name, text or listing is in here, so
+ * two tenants writing the same kind of listing send the same rules. That is
+ * the invariant `runtime/ai-prompt-cache.spec.ts` holds, and it is weaker
+ * than "one block for everything" on purpose — a rule about target keywords
+ * is worth nothing to a request that carries none, and `job.seo` runs on a
+ * model that caches no prompt this short, so an unread rule is simply paid
+ * for at full input rate on every attempt and every re-ask.
+ */ export function aiSeoFieldsInstructions(shape) {
+    const fields = orderedSeoListingFields(shape.fields);
+    const rules = [
+        'Write only from the text you are given. Never invent a fact, a price, a name, a place, an offer or a claim the text does not state.',
+        ...fields.map((key)=>AI_SEO_FIELD_RULES[key]).filter((rule)=>Boolean(rule)),
+        // Every field a person reads is held to this, keywords or none, so it is
+        // stated on every shape rather than inside the keyword rule it used to
+        // ride in: `checkAiSeoFields` refuses a repeat in a listing that named
+        // no keywords too.
+        'Never repeat the same word three times in one field.',
+        ...shape.keywords ? [
+            'A target keyword goes in only where the page is about it and it reads naturally: at most once in the title and once in the description. Never list keywords, and leave out a keyword the page is not about.'
+        ] : [],
+        ...shape.otherTitles ? [
+            'Do not reuse a title another page of the site already uses.'
+        ] : [],
+        'Write in the language of the page text.'
+    ];
+    return [
+        {
+            text: 'You write the search listing for one page or one product of a website: what a search result shows.\n\n' + `Answer by calling ${AI_SEO_FIELDS_TOOL_NAME} exactly once. A reply in prose cannot be used.\n\n` + `Rules:\n${rules.map((rule)=>`- ${rule}`).join('\n')}`,
+            cacheBreakpoint: true
+        }
+    ];
+}
+/** The rules for a listing of the default shape, for a door that names no other. */ export const AI_SEO_FIELDS_INSTRUCTIONS = aiSeoFieldsInstructions({
+    fields: [
+        'title',
+        'description',
+        'breadcrumb'
+    ],
+    keywords: false,
+    otherTitles: false
+});
+/** The longest a site's own words run in a prompt; they are a phrase, not copy. */ const SITE_WORDS_MAX_CHARS = 160;
+/** One of the site's own words as its line reads, or nothing when it says nothing. */ function siteWordsLine(label, value) {
+    const text = (value != null ? value : '').replace(/\s+/g, ' ').trim().slice(0, SITE_WORDS_MAX_CHARS).trim();
+    return text ? `${label}: ${text}` : '';
+}
+/** The user turn: the subject, what it says now, and the page's own text. */ export function aiSeoFieldsPrompt(input) {
+    var _input_site, _input_site1, _input_keywords, _input_otherTitles;
+    const fields = orderedSeoListingFields(input.fields);
+    const lines = [
+        `Site: ${input.brand || 'untitled site'}`,
+        siteWordsLine('What the site is', (_input_site = input.site) == null ? void 0 : _input_site.about),
+        siteWordsLine('Who the site is for', (_input_site1 = input.site) == null ? void 0 : _input_site1.audience),
+        input.subject.kind === 'product' ? `Product: ${input.subject.name || 'untitled product'}` : `Page: ${input.subject.name || 'untitled page'}${input.subject.path ? ` (${input.subject.path})` : ''}`,
+        `Fields to write: ${fields.join(', ')}`
+    ].filter(Boolean);
+    const current = fields.map((key)=>{
+        var _input_current_key, _input_current;
+        return [
+            key,
+            (_input_current = input.current) == null ? void 0 : (_input_current_key = _input_current[key]) == null ? void 0 : _input_current_key.trim()
+        ];
+    }).filter(([, value])=>Boolean(value));
+    if (current.length) {
+        lines.push('Current listing:', ...current.map(([key, value])=>`- ${key}: ${value}`));
+    }
+    if (input.image) {
+        const known = [
+            input.image.alt && `its current description: ${input.image.alt}`,
+            input.image.context && `the page text beside it: ${input.image.context}`
+        ].filter(Boolean).join('; ');
+        lines.push(`Share image: ${known || 'set, and nothing is known about what it shows'}`);
+    }
+    if ((_input_keywords = input.keywords) == null ? void 0 : _input_keywords.length) lines.push(`Target keywords: ${input.keywords.join(', ')}`);
+    if ((_input_otherTitles = input.otherTitles) == null ? void 0 : _input_otherTitles.length) {
+        lines.push('Titles other pages already use:', ...input.otherTitles.slice(0, OTHER_TITLES_LISTED).map((title)=>`- ${title}`));
+    }
+    lines.push('', input.subject.kind === 'product' ? 'Product description:' : 'Page text:', input.text.trim() || '(no text)');
+    return lines.join('\n');
+}
+/** What a listing is written with when the caller names no fields. */ export const AI_SEO_DEFAULT_FIELDS = [
+    'title',
+    'description',
+    'breadcrumb'
+];
+/**
+ * Propose a search listing for a page or a product.
+ *
+ * STABLE: a page generator calls this for the title and description of a
+ * page it builds (`fields: ['title', 'description']`), and the `seo` job
+ * calls it for a page's or a product's whole listing. It asks the routing
+ * table's `job.seo` model through the doctrine's generation call and resolves
+ * to its result — `ok` with the values, `needs_input` when the answer could
+ * not be held to the editor after one re-ask, `refused` when the model
+ * declined. It writes nothing.
+ */ export async function generateSeoFields(input) {
+    var _input_fields, _input_keywords, _input_step, _input_maxTokens;
+    var _input_otherTitles;
+    const hasImage = Boolean(input.image);
+    const fields = orderedSeoListingFields((_input_fields = input.fields) != null ? _input_fields : AI_SEO_DEFAULT_FIELDS).filter((key)=>key !== 'imageAlt' || hasImage);
+    const keywords = (_input_keywords = input.keywords) != null ? _input_keywords : [];
+    return runValidatedGeneration('seo-fields', _extends({
+        step: (_input_step = input.step) != null ? _input_step : 'job.seo'
+    }, input.settings ? {
+        settings: input.settings
+    } : {}, input.model ? {
+        model: input.model
+    } : {}, {
+        instructions: aiSeoFieldsInstructions({
+            fields,
+            keywords: keywords.length > 0,
+            otherTitles: Boolean((_input_otherTitles = input.otherTitles) == null ? void 0 : _input_otherTitles.length)
+        }),
+        messages: [
+            {
+                role: 'user',
+                content: aiSeoFieldsPrompt(_extends({}, input, {
+                    fields,
+                    keywords
+                }))
+            }
+        ],
+        tool: aiSeoFieldsTool(fields),
+        maxTokens: (_input_maxTokens = input.maxTokens) != null ? _input_maxTokens : AI_SEO_FIELDS_MAX_TOKENS
+    }, input.signal ? {
+        signal: input.signal
+    } : {}, input.provider ? {
+        provider: input.provider
+    } : {}, {
+        check: (answer)=>checkAiSeoFields(answer, {
+                fields,
+                hasImage,
+                keywords,
+                otherTitles: input.otherTitles
+            })
+    }));
+}
+
+//# sourceMappingURL=seo-fields.js.map

package/src/lib/runtime/seo-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/seo-fields.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 { SeoListingFieldKey } from '@aglyn/aglyn/app-utils/seo-listing-fields'\nimport type { AiSeoFieldValues } from '../model/ai-seo'\nimport type { AiStepKind } from '../providers/catalog'\nimport type { AiProvider } from '../providers/contract'\nimport { AI_ROUTING_TABLE, type AiPluginSettings } from '../providers/routing'\nimport {\n  AI_SEO_FIELDS_TOOL_NAME,\n  aiSeoFieldsTool,\n  checkAiSeoFields,\n  orderedSeoListingFields,\n} from '../tools/ai-seo-tool'\nimport { runValidatedGeneration, type AiValidatedGeneration } from './ai-doctrine'\nimport type { AiSystemBlock } from './ai-runtime'\n\n/**\n * SEO fields by AI (AGL-2910): a search listing — title, description,\n * breadcrumb label, image description — written from what a page or a\n * product actually says, and held to the lengths its editor enforces.\n *\n * `generateSeoFields` is the one entry point. The \"Write SEO\" card on a\n * page's SEO panel and on a product's listing calls it through an `seo` job,\n * and a page generator calls it for the title and description of the page it\n * builds. It proposes; it never writes a listing anywhere.\n *\n * The tool the model answers through, and the check that holds the answer to\n * the editor, are `tools/ai-seo-tool.ts`: the tool is built from the editor's\n * own field list, so a field and its length are said once.\n *\n * ## The request\n *\n * The fast tier through the routing table (`job.seo`), never a model\n * literal, and the building doctrine's generation call\n * (`runValidatedGeneration`, AGL-3009): the doctrine's cached block, which\n * carries the acceptable-use rules, then these rules, cached after it. The\n * page's text, its current listing, the site's name and the target keywords\n * ride in the user turn, so no byte of a site sits inside the cached prefix,\n * and no site inventory is sent: a listing is written from its page.\n */\n\n/* ------------------------------------------------------------------------ *\n * The request\n * ------------------------------------------------------------------------ */\n\n/**\n * The output budget, from the routing table. The largest answer the tool\n * accepts — every field at its limit — is under 300 tokens of JSON\n * (`ai-job-seo-step.spec.ts` measures it); the rest is headroom, and the fast\n * tier thinks in none of it.\n */\nexport const AI_SEO_FIELDS_MAX_TOKENS = AI_ROUTING_TABLE['job.seo'].maxTokens\n\n/** How many other pages' titles a prompt lists for the model to avoid. */\nconst OTHER_TITLES_LISTED = 40\n\n/**\n * What one listing field's rule ADDS to the tool's own description of that\n * field (AGL-2937), stated only when the field is asked for.\n *\n * The schema the answer arrives through is built from the editor's field\n * catalog, and it already names each field, says what the value is for and\n * states its length. It rides in the same request, ahead of these blocks, so\n * a rule that restated it would be the same sentence billed twice on a door\n * whose prompt no model will cache. Each rule here is therefore only what\n * the schema does not say: how to write the field rather than what it is.\n * The image description has no rule at all, because its description already\n * carries both halves of one — what it describes, and when to answer null.\n *\n * `runtime/ai-prompt-cache.spec.ts` holds the pair together: whatever\n * `checkAiSeoFields` can refuse an answer for, the request has to state\n * somewhere, in a block or in the schema.\n */\nconst AI_SEO_FIELD_RULES: Readonly<Partial<Record<SeoListingFieldKey, string>>> = {\n  title:\n    'The title says what the page is, specifically and in plain words; add the site name only where it helps.',\n  description:\n    'The description is one or two sentences: no quotation marks, no emoji, no capitals for emphasis.',\n  breadcrumb: 'The breadcrumb label is one to three words.',\n}\n\n/** What a listing request carries, and therefore which rules it is sent. */\nexport interface AiSeoFieldsInstructionShape {\n  fields: readonly SeoListingFieldKey[]\n  keywords: boolean\n  otherTitles: boolean\n}\n\n/**\n * The rules for one listing request.\n *\n * Byte-identical for every request of the same SHAPE, and identical across\n * workspaces at every shape: no site's name, text or listing is in here, so\n * two tenants writing the same kind of listing send the same rules. That is\n * the invariant `runtime/ai-prompt-cache.spec.ts` holds, and it is weaker\n * than \"one block for everything\" on purpose — a rule about target keywords\n * is worth nothing to a request that carries none, and `job.seo` runs on a\n * model that caches no prompt this short, so an unread rule is simply paid\n * for at full input rate on every attempt and every re-ask.\n */\nexport function aiSeoFieldsInstructions(\n  shape: AiSeoFieldsInstructionShape,\n): AiSystemBlock[] {\n  const fields = orderedSeoListingFields(shape.fields)\n  const rules = [\n    'Write only from the text you are given. Never invent a fact, a price, a name, a place, an offer or a claim the text does not state.',\n    ...fields.map((key) => AI_SEO_FIELD_RULES[key]).filter((rule): rule is string => Boolean(rule)),\n    // Every field a person reads is held to this, keywords or none, so it is\n    // stated on every shape rather than inside the keyword rule it used to\n    // ride in: `checkAiSeoFields` refuses a repeat in a listing that named\n    // no keywords too.\n    'Never repeat the same word three times in one field.',\n    ...(shape.keywords\n      ? [\n          'A target keyword goes in only where the page is about it and it reads naturally: at most once in the title and once in the description. Never list keywords, and leave out a keyword the page is not about.',\n        ]\n      : []),\n    ...(shape.otherTitles\n      ? ['Do not reuse a title another page of the site already uses.']\n      : []),\n    'Write in the language of the page text.',\n  ]\n  return [\n    {\n      text:\n        'You write the search listing for one page or one product of a website: what a search result shows.\\n\\n' +\n        `Answer by calling ${AI_SEO_FIELDS_TOOL_NAME} exactly once. A reply in prose cannot be used.\\n\\n` +\n        `Rules:\\n${rules.map((rule) => `- ${rule}`).join('\\n')}`,\n      cacheBreakpoint: true,\n    },\n  ]\n}\n\n/** The rules for a listing of the default shape, for a door that names no other. */\nexport const AI_SEO_FIELDS_INSTRUCTIONS: AiSystemBlock[] = aiSeoFieldsInstructions({\n  fields: ['title', 'description', 'breadcrumb'],\n  keywords: false,\n  otherTitles: false,\n})\n\n/**\n * What the site itself is, in the words of whoever set it up (AGL-2918).\n *\n * A page's own text says what the page is; it does not say who the page is\n * written for. On a site whose pages have just been generated that gap is at\n * its widest — every page reads like the same competent stranger wrote it —\n * so the words the owner used are carried into the listing rather than\n * inferred back out of the copy they produced.\n *\n * It rides in the user turn and nowhere else: it is one site's own words, so\n * putting it in a rules block would key the platform's cache entry on a\n * tenant's sentence, and the rules already say to write from what is given.\n */\nexport interface AiSeoSiteWords {\n  /** What kind of site it is: \"a neighborhood dog groomer\". */\n  about?: string | null\n  /** Who it is for: \"local dog owners who want a regular groom booked online\". */\n  audience?: string | null\n}\n\nexport interface AiSeoFieldsPromptInput {\n  subject: { kind: 'screen' | 'product'; name: string; path?: string | null }\n  /** The site's name, as its visitors see it. */\n  brand: string\n  /** What the site is and who it is for, where the caller knows (AGL-2918). */\n  site?: AiSeoSiteWords | null\n  /** What the page or the product says: a page's Markdown, a product's description. */\n  text: string\n  fields: readonly SeoListingFieldKey[]\n  current?: AiSeoFieldValues\n  /**\n   * What is known about the share image, when the listing has one: the\n   * description it carries, and the page text around the same picture where\n   * the page shows it.\n   */\n  image?: { alt?: string | null; context?: string | null } | null\n  keywords?: readonly string[]\n  otherTitles?: readonly string[]\n}\n\n/** The longest a site's own words run in a prompt; they are a phrase, not copy. */\nconst SITE_WORDS_MAX_CHARS = 160\n\n/** One of the site's own words as its line reads, or nothing when it says nothing. */\nfunction siteWordsLine(label: string, value: string | null | undefined): string {\n  const text = (value ?? '').replace(/\\s+/g, ' ').trim().slice(0, SITE_WORDS_MAX_CHARS).trim()\n  return text ? `${label}: ${text}` : ''\n}\n\n/** The user turn: the subject, what it says now, and the page's own text. */\nexport function aiSeoFieldsPrompt(input: AiSeoFieldsPromptInput): string {\n  const fields = orderedSeoListingFields(input.fields)\n  const lines = [\n    `Site: ${input.brand || 'untitled site'}`,\n    siteWordsLine('What the site is', input.site?.about),\n    siteWordsLine('Who the site is for', input.site?.audience),\n    input.subject.kind === 'product'\n      ? `Product: ${input.subject.name || 'untitled product'}`\n      : `Page: ${input.subject.name || 'untitled page'}${input.subject.path ? ` (${input.subject.path})` : ''}`,\n    `Fields to write: ${fields.join(', ')}`,\n    // Only the two site lines can be empty here, and an empty one is a\n    // question nobody answered rather than a blank line to send.\n  ].filter(Boolean)\n  const current = fields\n    .map((key) => [key, input.current?.[key]?.trim()] as const)\n    .filter(([, value]) => Boolean(value))\n  if (current.length) {\n    lines.push('Current listing:', ...current.map(([key, value]) => `- ${key}: ${value}`))\n  }\n  if (input.image) {\n    const known = [\n      input.image.alt && `its current description: ${input.image.alt}`,\n      input.image.context && `the page text beside it: ${input.image.context}`,\n    ]\n      .filter(Boolean)\n      .join('; ')\n    lines.push(`Share image: ${known || 'set, and nothing is known about what it shows'}`)\n  }\n  if (input.keywords?.length) lines.push(`Target keywords: ${input.keywords.join(', ')}`)\n  if (input.otherTitles?.length) {\n    lines.push(\n      'Titles other pages already use:',\n      ...input.otherTitles.slice(0, OTHER_TITLES_LISTED).map((title) => `- ${title}`),\n    )\n  }\n  lines.push(\n    '',\n    input.subject.kind === 'product' ? 'Product description:' : 'Page text:',\n    input.text.trim() || '(no text)',\n  )\n  return lines.join('\\n')\n}\n\nexport interface GenerateSeoFieldsInput extends Omit<AiSeoFieldsPromptInput, 'fields'> {\n  /** The fields to write; the title, description and breadcrumb label when omitted. */\n  fields?: readonly SeoListingFieldKey[]\n  /** The step kind the call is routed as; `job.seo` when omitted. */\n  step?: AiStepKind\n  settings?: AiPluginSettings\n  model?: string\n  /**\n   * The answer's ceiling: `AI_SEO_FIELDS_MAX_TOKENS` when omitted. A job step\n   * passes the most its registered time allows on the model it runs\n   * (AGL-3035).\n   */\n  maxTokens?: number\n  signal?: AbortSignal\n  provider?: AiProvider\n}\n\n/** What a listing is written with when the caller names no fields. */\nexport const AI_SEO_DEFAULT_FIELDS: readonly SeoListingFieldKey[] = ['title', 'description', 'breadcrumb']\n\n/**\n * Propose a search listing for a page or a product.\n *\n * STABLE: a page generator calls this for the title and description of a\n * page it builds (`fields: ['title', 'description']`), and the `seo` job\n * calls it for a page's or a product's whole listing. It asks the routing\n * table's `job.seo` model through the doctrine's generation call and resolves\n * to its result — `ok` with the values, `needs_input` when the answer could\n * not be held to the editor after one re-ask, `refused` when the model\n * declined. It writes nothing.\n */\nexport async function generateSeoFields(\n  input: GenerateSeoFieldsInput,\n): Promise<AiValidatedGeneration<AiSeoFieldValues>> {\n  const hasImage = Boolean(input.image)\n  const fields = orderedSeoListingFields(input.fields ?? AI_SEO_DEFAULT_FIELDS).filter(\n    (key) => key !== 'imageAlt' || hasImage,\n  )\n  const keywords = input.keywords ?? []\n  return runValidatedGeneration('seo-fields', {\n    step: input.step ?? 'job.seo',\n    ...(input.settings ? { settings: input.settings } : {}),\n    ...(input.model ? { model: input.model } : {}),\n    instructions: aiSeoFieldsInstructions({\n      fields,\n      keywords: keywords.length > 0,\n      otherTitles: Boolean(input.otherTitles?.length),\n    }),\n    messages: [{ role: 'user', content: aiSeoFieldsPrompt({ ...input, fields, keywords }) }],\n    tool: aiSeoFieldsTool(fields),\n    maxTokens: input.maxTokens ?? AI_SEO_FIELDS_MAX_TOKENS,\n    ...(input.signal ? { signal: input.signal } : {}),\n    ...(input.provider ? { provider: input.provider } : {}),\n    check: (answer) =>\n      checkAiSeoFields(answer, {\n        fields,\n        hasImage,\n        keywords,\n        otherTitles: input.otherTitles,\n      }),\n  })\n}\n"],"names":["AI_ROUTING_TABLE","AI_SEO_FIELDS_TOOL_NAME","aiSeoFieldsTool","checkAiSeoFields","orderedSeoListingFields","runValidatedGeneration","AI_SEO_FIELDS_MAX_TOKENS","maxTokens","OTHER_TITLES_LISTED","AI_SEO_FIELD_RULES","title","description","breadcrumb","aiSeoFieldsInstructions","shape","fields","rules","map","key","filter","rule","Boolean","keywords","otherTitles","text","join","cacheBreakpoint","AI_SEO_FIELDS_INSTRUCTIONS","SITE_WORDS_MAX_CHARS","siteWordsLine","label","value","replace","trim","slice","aiSeoFieldsPrompt","input","lines","brand","site","about","audience","subject","kind","name","path","current","length","push","image","known","alt","context","AI_SEO_DEFAULT_FIELDS","generateSeoFields","hasImage","step","settings","model","instructions","messages","role","content","tool","signal","provider","check","answer"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAMD,SAASA,gBAAgB,QAA+B,0BAAsB;AAC9E,SACEC,uBAAuB,EACvBC,eAAe,EACfC,gBAAgB,EAChBC,uBAAuB,QAClB,0BAAsB;AAC7B,SAASC,sBAAsB,QAAoC,mBAAe;AAGlF;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED;;4EAE4E,GAE5E;;;;;CAKC,GACD,OAAO,MAAMC,2BAA2BN,gBAAgB,CAAC,UAAU,CAACO,SAAS,CAAA;AAE7E,wEAAwE,GACxE,MAAMC,sBAAsB;AAE5B;;;;;;;;;;;;;;;;CAgBC,GACD,MAAMC,qBAA4E;IAChFC,OACE;IACFC,aACE;IACFC,YAAY;AACd;AASA;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,wBACdC,KAAkC;IAElC,MAAMC,SAASX,wBAAwBU,MAAMC,MAAM;IACnD,MAAMC,QAAQ;QACZ;WACGD,OAAOE,GAAG,CAAC,CAACC,MAAQT,kBAAkB,CAACS,IAAI,EAAEC,MAAM,CAAC,CAACC,OAAyBC,QAAQD;QACzF,yEAAyE;QACzE,uEAAuE;QACvE,uEAAuE;QACvE,mBAAmB;QACnB;WACIN,MAAMQ,QAAQ,GACd;YACE;SACD,GACD,EAAE;WACFR,MAAMS,WAAW,GACjB;YAAC;SAA8D,GAC/D,EAAE;QACN;KACD;IACD,OAAO;QACL;YACEC,MACE,2GACA,CAAC,kBAAkB,EAAEvB,wBAAwB,mDAAmD,CAAC,GACjG,CAAC,QAAQ,EAAEe,MAAMC,GAAG,CAAC,CAACG,OAAS,CAAC,EAAE,EAAEA,MAAM,EAAEK,IAAI,CAAC,OAAO;YAC1DC,iBAAiB;QACnB;KACD;AACH;AAEA,kFAAkF,GAClF,OAAO,MAAMC,6BAA8Cd,wBAAwB;IACjFE,QAAQ;QAAC;QAAS;QAAe;KAAa;IAC9CO,UAAU;IACVC,aAAa;AACf,GAAE;AA0CF,iFAAiF,GACjF,MAAMK,uBAAuB;AAE7B,oFAAoF,GACpF,SAASC,cAAcC,KAAa,EAAEC,KAAgC;IACpE,MAAMP,OAAO,CAACO,gBAAAA,QAAS,IAAIC,OAAO,CAAC,QAAQ,KAAKC,IAAI,GAAGC,KAAK,CAAC,GAAGN,sBAAsBK,IAAI;IAC1F,OAAOT,OAAO,GAAGM,MAAM,EAAE,EAAEN,MAAM,GAAG;AACtC;AAEA,2EAA2E,GAC3E,OAAO,SAASW,kBAAkBC,KAA6B;QAIzBA,aACGA,cAuBnCA,iBACAA;IA5BJ,MAAMrB,SAASX,wBAAwBgC,MAAMrB,MAAM;IACnD,MAAMsB,QAAQ;QACZ,CAAC,MAAM,EAAED,MAAME,KAAK,IAAI,iBAAiB;QACzCT,cAAc,qBAAoBO,cAAAA,MAAMG,IAAI,qBAAVH,YAAYI,KAAK;QACnDX,cAAc,wBAAuBO,eAAAA,MAAMG,IAAI,qBAAVH,aAAYK,QAAQ;QACzDL,MAAMM,OAAO,CAACC,IAAI,KAAK,YACnB,CAAC,SAAS,EAAEP,MAAMM,OAAO,CAACE,IAAI,IAAI,oBAAoB,GACtD,CAAC,MAAM,EAAER,MAAMM,OAAO,CAACE,IAAI,IAAI,kBAAkBR,MAAMM,OAAO,CAACG,IAAI,GAAG,CAAC,EAAE,EAAET,MAAMM,OAAO,CAACG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI;QAC3G,CAAC,iBAAiB,EAAE9B,OAAOU,IAAI,CAAC,OAAO;KAGxC,CAACN,MAAM,CAACE;IACT,MAAMyB,UAAU/B,OACbE,GAAG,CAAC,CAACC;YAAckB,oBAAAA;eAAN;YAAClB;aAAKkB,iBAAAA,MAAMU,OAAO,sBAAbV,qBAAAA,cAAe,CAAClB,IAAI,qBAApBkB,mBAAsBH,IAAI;SAAG;OAChDd,MAAM,CAAC,CAAC,GAAGY,MAAM,GAAKV,QAAQU;IACjC,IAAIe,QAAQC,MAAM,EAAE;QAClBV,MAAMW,IAAI,CAAC,uBAAuBF,QAAQ7B,GAAG,CAAC,CAAC,CAACC,KAAKa,MAAM,GAAK,CAAC,EAAE,EAAEb,IAAI,EAAE,EAAEa,OAAO;IACtF;IACA,IAAIK,MAAMa,KAAK,EAAE;QACf,MAAMC,QAAQ;YACZd,MAAMa,KAAK,CAACE,GAAG,IAAI,CAAC,yBAAyB,EAAEf,MAAMa,KAAK,CAACE,GAAG,EAAE;YAChEf,MAAMa,KAAK,CAACG,OAAO,IAAI,CAAC,yBAAyB,EAAEhB,MAAMa,KAAK,CAACG,OAAO,EAAE;SACzE,CACEjC,MAAM,CAACE,SACPI,IAAI,CAAC;QACRY,MAAMW,IAAI,CAAC,CAAC,aAAa,EAAEE,SAAS,iDAAiD;IACvF;IACA,KAAId,kBAAAA,MAAMd,QAAQ,qBAAdc,gBAAgBW,MAAM,EAAEV,MAAMW,IAAI,CAAC,CAAC,iBAAiB,EAAEZ,MAAMd,QAAQ,CAACG,IAAI,CAAC,OAAO;IACtF,KAAIW,qBAAAA,MAAMb,WAAW,qBAAjBa,mBAAmBW,MAAM,EAAE;QAC7BV,MAAMW,IAAI,CACR,sCACGZ,MAAMb,WAAW,CAACW,KAAK,CAAC,GAAG1B,qBAAqBS,GAAG,CAAC,CAACP,QAAU,CAAC,EAAE,EAAEA,OAAO;IAElF;IACA2B,MAAMW,IAAI,CACR,IACAZ,MAAMM,OAAO,CAACC,IAAI,KAAK,YAAY,yBAAyB,cAC5DP,MAAMZ,IAAI,CAACS,IAAI,MAAM;IAEvB,OAAOI,MAAMZ,IAAI,CAAC;AACpB;AAmBA,oEAAoE,GACpE,OAAO,MAAM4B,wBAAuD;IAAC;IAAS;IAAe;CAAa,CAAA;AAE1G;;;;;;;;;;CAUC,GACD,OAAO,eAAeC,kBACpBlB,KAA6B;QAGUA,eAGtBA,iBAETA,aAUKA;QAJYA;IAZzB,MAAMmB,WAAWlC,QAAQe,MAAMa,KAAK;IACpC,MAAMlC,SAASX,yBAAwBgC,gBAAAA,MAAMrB,MAAM,YAAZqB,gBAAgBiB,uBAAuBlC,MAAM,CAClF,CAACD,MAAQA,QAAQ,cAAcqC;IAEjC,MAAMjC,YAAWc,kBAAAA,MAAMd,QAAQ,YAAdc,kBAAkB,EAAE;IACrC,OAAO/B,uBAAuB,cAAc;QAC1CmD,IAAI,GAAEpB,cAAAA,MAAMoB,IAAI,YAAVpB,cAAc;OAChBA,MAAMqB,QAAQ,GAAG;QAAEA,UAAUrB,MAAMqB,QAAQ;IAAC,IAAI,CAAC,GACjDrB,MAAMsB,KAAK,GAAG;QAAEA,OAAOtB,MAAMsB,KAAK;IAAC,IAAI,CAAC;QAC5CC,cAAc9C,wBAAwB;YACpCE;YACAO,UAAUA,SAASyB,MAAM,GAAG;YAC5BxB,aAAaF,SAAQe,qBAAAA,MAAMb,WAAW,qBAAjBa,mBAAmBW,MAAM;QAChD;QACAa,UAAU;YAAC;gBAAEC,MAAM;gBAAQC,SAAS3B,kBAAkB,aAAKC;oBAAOrB;oBAAQO;;YAAY;SAAE;QACxFyC,MAAM7D,gBAAgBa;QACtBR,SAAS,GAAE6B,mBAAAA,MAAM7B,SAAS,YAAf6B,mBAAmB9B;OAC1B8B,MAAM4B,MAAM,GAAG;QAAEA,QAAQ5B,MAAM4B,MAAM;IAAC,IAAI,CAAC,GAC3C5B,MAAM6B,QAAQ,GAAG;QAAEA,UAAU7B,MAAM6B,QAAQ;IAAC,IAAI,CAAC;QACrDC,OAAO,CAACC,SACNhE,iBAAiBgE,QAAQ;gBACvBpD;gBACAwC;gBACAjC;gBACAC,aAAaa,MAAMb,WAAW;YAChC;;AAEN"}

package/src/lib/runtime/seo-page-facts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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 PageMarkdownNodes } from '@aglyn/aglyn/app-utils/page-markdown';
+/**
+ * What a page SAYS, read off its node tree (AGL-2910): the text a search
+ * listing is written from, the headings, and the images — each heading and
+ * image by node id, because a content fix addresses the element it changes.
+ *
+ * The text is the page's Markdown representation, the one an agent is
+ * served, so what the listing summarizes is what a reader of the page gets.
+ * The walk starts where that serializer starts — the content region — and
+ * skips what it skips, through the same chrome predicate: a heading in the
+ * site's navigation is not the page's heading.
+ */
+/** How much of a page's text a prompt carries. A listing summarizes; it does not need the page. */
+export declare const AI_SEO_PAGE_TEXT_MAX_CHARS = 2000;
+export interface AiSeoHeading {
+    /** The element, or `null` for a heading inside rich text a fix cannot address. */
+    nodeId: string | null;
+    level: number;
+    text: string;
+    /** Whether a content fix can change it: a text component with plain text. */
+    editable: boolean;
+}
+export interface AiSeoImage {
+    nodeId: string;
+    src: string;
+    alt: string;
+    /** The nearest heading or text before it, which is what the image illustrates. */
+    context: string;
+}
+export interface AiSeoPageFacts {
+    /** The page's Markdown body, capped. */
+    text: string;
+    wordCount: number;
+    headings: AiSeoHeading[];
+    h1s: AiSeoHeading[];
+    images: AiSeoImage[];
+    imagesMissingAlt: AiSeoImage[];
+    /** The node the content region starts at; a new heading goes first inside it. */
+    contentRootId: string | null;
+}
+/** Read the facts a listing and an audit need from one page's node map. */
+export declare function aiSeoPageFacts(nodes: PageMarkdownNodes | null | undefined, options?: {
+    rootId?: string;
+    maxChars?: number;
+}): AiSeoPageFacts;

package/src/lib/runtime/seo-page-facts.js

@@ -0,0 +1,150 @@
+/**
+ * @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 { buildPageMarkdown, headingLevelOf, isPageChromeNode, pageContentRootId } from "@aglyn/aglyn/app-utils/page-markdown";
+/**
+ * What a page SAYS, read off its node tree (AGL-2910): the text a search
+ * listing is written from, the headings, and the images — each heading and
+ * image by node id, because a content fix addresses the element it changes.
+ *
+ * The text is the page's Markdown representation, the one an agent is
+ * served, so what the listing summarizes is what a reader of the page gets.
+ * The walk starts where that serializer starts — the content region — and
+ * skips what it skips, through the same chrome predicate: a heading in the
+ * site's navigation is not the page's heading.
+ */ /** How much of a page's text a prompt carries. A listing summarizes; it does not need the page. */ export const AI_SEO_PAGE_TEXT_MAX_CHARS = 2000;
+/** How much text around an image describes it. */ const IMAGE_CONTEXT_MAX_CHARS = 160;
+/** The deepest a walk goes, and it stops at a cycle — a node map is data. */ const MAX_DEPTH = 64;
+/** The text components whose heading level `headingLevelOf` reads. */ const TEXT_COMPONENTS = new Set([
+    'muiTypography',
+    'muiInlineText',
+    'muiListItemText'
+]);
+const collapse = (value)=>value.replace(/\s+/g, ' ').trim();
+/** Author HTML to its text, for a heading stored as rich text. */ function htmlText(html) {
+    return collapse(html.replace(/<[^>]*>/g, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&'));
+}
+/** A text component's own text, and whether it is plain (a fix can rewrite it). */ function textOf(props) {
+    const html = props['html'];
+    if (typeof html === 'string' && html.trim()) return {
+        text: htmlText(html),
+        plain: false
+    };
+    const children = props['children'];
+    return typeof children === 'string' ? {
+        text: collapse(children),
+        plain: true
+    } : {
+        text: '',
+        plain: true
+    };
+}
+const childIdsOf = (node)=>Array.isArray(node == null ? void 0 : node.nodes) ? (node == null ? void 0 : node.nodes).filter((id)=>typeof id === 'string') : [];
+/** Read the facts a listing and an audit need from one page's node map. */ export function aiSeoPageFacts(nodes, options = {}) {
+    var _options_maxChars;
+    const empty = {
+        text: '',
+        wordCount: 0,
+        headings: [],
+        h1s: [],
+        images: [],
+        imagesMissingAlt: [],
+        contentRootId: null
+    };
+    if (!nodes) return empty;
+    const contentRootId = pageContentRootId(nodes, options.rootId);
+    if (!contentRootId) return empty;
+    const markdown = buildPageMarkdown({
+        nodes,
+        rootId: options.rootId
+    });
+    const text = markdown.trim().slice(0, (_options_maxChars = options.maxChars) != null ? _options_maxChars : AI_SEO_PAGE_TEXT_MAX_CHARS);
+    const headings = [];
+    const images = [];
+    let lastText = '';
+    const seen = new Set();
+    const visit = (id, depth)=>{
+        var _node_props, _node_componentId, _props_html;
+        if (depth > MAX_DEPTH || seen.has(id)) return;
+        const node = nodes[id];
+        if (!node) return;
+        seen.add(id);
+        if (isPageChromeNode(node)) return;
+        const props = (_node_props = node.props) != null ? _node_props : {};
+        const componentId = String((_node_componentId = node.componentId) != null ? _node_componentId : '');
+        if (TEXT_COMPONENTS.has(componentId)) {
+            const { text: own, plain } = textOf(props);
+            const level = headingLevelOf(props);
+            if (own) {
+                if (level > 0) headings.push({
+                    nodeId: id,
+                    level,
+                    text: own,
+                    editable: plain
+                });
+                lastText = own;
+            }
+        } else if (componentId === 'markdown' && typeof props['content'] === 'string') {
+            for (const line of String(props['content']).split('\n')){
+                const match = /^(#{1,6})\s+(.+)$/.exec(line.trim());
+                if (match) {
+                    headings.push({
+                        nodeId: null,
+                        level: match[1].length,
+                        text: collapse(match[2]),
+                        editable: false
+                    });
+                }
+            }
+            lastText = collapse(String(props['content'])).slice(0, IMAGE_CONTEXT_MAX_CHARS);
+        } else if (componentId === 'custom-html' && typeof ((_props_html = props['html']) != null ? _props_html : props['children']) === 'string') {
+            var _props_html1;
+            const html = String((_props_html1 = props['html']) != null ? _props_html1 : props['children']);
+            for (const match of html.matchAll(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi)){
+                headings.push({
+                    nodeId: null,
+                    level: Number(match[1]),
+                    text: htmlText(match[2]),
+                    editable: false
+                });
+            }
+        } else if (componentId === 'image') {
+            var _props_src;
+            const src = String((_props_src = props['src']) != null ? _props_src : '').trim();
+            if (src) {
+                var _props_alt;
+                images.push({
+                    nodeId: id,
+                    src,
+                    alt: collapse(String((_props_alt = props['alt']) != null ? _props_alt : '')),
+                    context: lastText.slice(0, IMAGE_CONTEXT_MAX_CHARS)
+                });
+            }
+        }
+        for (const childId of childIdsOf(node))visit(childId, depth + 1);
+    };
+    visit(contentRootId, 0);
+    return {
+        text,
+        wordCount: text ? text.split(/\s+/).filter(Boolean).length : 0,
+        headings,
+        h1s: headings.filter((heading)=>heading.level === 1),
+        images,
+        imagesMissingAlt: images.filter((image)=>!image.alt),
+        contentRootId
+    };
+}
+
+//# sourceMappingURL=seo-page-facts.js.map

package/src/lib/runtime/seo-page-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/seo-page-facts.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  buildPageMarkdown,\n  headingLevelOf,\n  isPageChromeNode,\n  pageContentRootId,\n  type PageMarkdownNode,\n  type PageMarkdownNodes,\n} from '@aglyn/aglyn/app-utils/page-markdown'\n\n/**\n * What a page SAYS, read off its node tree (AGL-2910): the text a search\n * listing is written from, the headings, and the images — each heading and\n * image by node id, because a content fix addresses the element it changes.\n *\n * The text is the page's Markdown representation, the one an agent is\n * served, so what the listing summarizes is what a reader of the page gets.\n * The walk starts where that serializer starts — the content region — and\n * skips what it skips, through the same chrome predicate: a heading in the\n * site's navigation is not the page's heading.\n */\n\n/** How much of a page's text a prompt carries. A listing summarizes; it does not need the page. */\nexport const AI_SEO_PAGE_TEXT_MAX_CHARS = 2_000\n\n/** How much text around an image describes it. */\nconst IMAGE_CONTEXT_MAX_CHARS = 160\n\n/** The deepest a walk goes, and it stops at a cycle — a node map is data. */\nconst MAX_DEPTH = 64\n\n/** The text components whose heading level `headingLevelOf` reads. */\nconst TEXT_COMPONENTS: ReadonlySet<string> = new Set(['muiTypography', 'muiInlineText', 'muiListItemText'])\n\nexport interface AiSeoHeading {\n  /** The element, or `null` for a heading inside rich text a fix cannot address. */\n  nodeId: string | null\n  level: number\n  text: string\n  /** Whether a content fix can change it: a text component with plain text. */\n  editable: boolean\n}\n\nexport interface AiSeoImage {\n  nodeId: string\n  src: string\n  alt: string\n  /** The nearest heading or text before it, which is what the image illustrates. */\n  context: string\n}\n\nexport interface AiSeoPageFacts {\n  /** The page's Markdown body, capped. */\n  text: string\n  wordCount: number\n  headings: AiSeoHeading[]\n  h1s: AiSeoHeading[]\n  images: AiSeoImage[]\n  imagesMissingAlt: AiSeoImage[]\n  /** The node the content region starts at; a new heading goes first inside it. */\n  contentRootId: string | null\n}\n\nconst collapse = (value: string): string => value.replace(/\\s+/g, ' ').trim()\n\n/** Author HTML to its text, for a heading stored as rich text. */\nfunction htmlText(html: string): string {\n  return collapse(html.replace(/<[^>]*>/g, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&'))\n}\n\n/** A text component's own text, and whether it is plain (a fix can rewrite it). */\nfunction textOf(props: Record<string, unknown>): { text: string; plain: boolean } {\n  const html = props['html']\n  if (typeof html === 'string' && html.trim()) return { text: htmlText(html), plain: false }\n  const children = props['children']\n  return typeof children === 'string' ? { text: collapse(children), plain: true } : { text: '', plain: true }\n}\n\nconst childIdsOf = (node: PageMarkdownNode | undefined): string[] =>\n  Array.isArray(node?.nodes) ? (node?.nodes as unknown[]).filter((id): id is string => typeof id === 'string') : []\n\n/** Read the facts a listing and an audit need from one page's node map. */\nexport function aiSeoPageFacts(\n  nodes: PageMarkdownNodes | null | undefined,\n  options: { rootId?: string; maxChars?: number } = {},\n): AiSeoPageFacts {\n  const empty: AiSeoPageFacts = {\n    text: '',\n    wordCount: 0,\n    headings: [],\n    h1s: [],\n    images: [],\n    imagesMissingAlt: [],\n    contentRootId: null,\n  }\n  if (!nodes) return empty\n  const contentRootId = pageContentRootId(nodes, options.rootId)\n  if (!contentRootId) return empty\n\n  const markdown = buildPageMarkdown({ nodes, rootId: options.rootId })\n  const text = markdown.trim().slice(0, options.maxChars ?? AI_SEO_PAGE_TEXT_MAX_CHARS)\n  const headings: AiSeoHeading[] = []\n  const images: AiSeoImage[] = []\n  let lastText = ''\n\n  const seen = new Set<string>()\n  const visit = (id: string, depth: number): void => {\n    if (depth > MAX_DEPTH || seen.has(id)) return\n    const node = nodes[id]\n    if (!node) return\n    seen.add(id)\n    if (isPageChromeNode(node)) return\n    const props = (node.props ?? {}) as Record<string, unknown>\n    const componentId = String(node.componentId ?? '')\n    if (TEXT_COMPONENTS.has(componentId)) {\n      const { text: own, plain } = textOf(props)\n      const level = headingLevelOf(props)\n      if (own) {\n        if (level > 0) headings.push({ nodeId: id, level, text: own, editable: plain })\n        lastText = own\n      }\n    } else if (componentId === 'markdown' && typeof props['content'] === 'string') {\n      for (const line of String(props['content']).split('\\n')) {\n        const match = /^(#{1,6})\\s+(.+)$/.exec(line.trim())\n        if (match) {\n          headings.push({ nodeId: null, level: match[1].length, text: collapse(match[2]), editable: false })\n        }\n      }\n      lastText = collapse(String(props['content'])).slice(0, IMAGE_CONTEXT_MAX_CHARS)\n    } else if (componentId === 'custom-html' && typeof (props['html'] ?? props['children']) === 'string') {\n      const html = String(props['html'] ?? props['children'])\n      for (const match of html.matchAll(/<h([1-6])[^>]*>([\\s\\S]*?)<\\/h\\1>/gi)) {\n        headings.push({ nodeId: null, level: Number(match[1]), text: htmlText(match[2]), editable: false })\n      }\n    } else if (componentId === 'image') {\n      const src = String(props['src'] ?? '').trim()\n      if (src) {\n        images.push({\n          nodeId: id,\n          src,\n          alt: collapse(String(props['alt'] ?? '')),\n          context: lastText.slice(0, IMAGE_CONTEXT_MAX_CHARS),\n        })\n      }\n    }\n    for (const childId of childIdsOf(node)) visit(childId, depth + 1)\n  }\n  visit(contentRootId, 0)\n\n  return {\n    text,\n    wordCount: text ? text.split(/\\s+/).filter(Boolean).length : 0,\n    headings,\n    h1s: headings.filter((heading) => heading.level === 1),\n    images,\n    imagesMissingAlt: images.filter((image) => !image.alt),\n    contentRootId,\n  }\n}\n"],"names":["buildPageMarkdown","headingLevelOf","isPageChromeNode","pageContentRootId","AI_SEO_PAGE_TEXT_MAX_CHARS","IMAGE_CONTEXT_MAX_CHARS","MAX_DEPTH","TEXT_COMPONENTS","Set","collapse","value","replace","trim","htmlText","html","textOf","props","text","plain","children","childIdsOf","node","Array","isArray","nodes","filter","id","aiSeoPageFacts","options","empty","wordCount","headings","h1s","images","imagesMissingAlt","contentRootId","rootId","markdown","slice","maxChars","lastText","seen","visit","depth","has","add","componentId","String","own","level","push","nodeId","editable","line","split","match","exec","length","matchAll","Number","src","alt","context","childId","Boolean","heading","image"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,iBAAiB,EACjBC,cAAc,EACdC,gBAAgB,EAChBC,iBAAiB,QAGZ,uCAAsC;AAE7C;;;;;;;;;;CAUC,GAED,iGAAiG,GACjG,OAAO,MAAMC,6BAA6B,KAAK;AAE/C,gDAAgD,GAChD,MAAMC,0BAA0B;AAEhC,2EAA2E,GAC3E,MAAMC,YAAY;AAElB,oEAAoE,GACpE,MAAMC,kBAAuC,IAAIC,IAAI;IAAC;IAAiB;IAAiB;CAAkB;AA+B1G,MAAMC,WAAW,CAACC,QAA0BA,MAAMC,OAAO,CAAC,QAAQ,KAAKC,IAAI;AAE3E,gEAAgE,GAChE,SAASC,SAASC,IAAY;IAC5B,OAAOL,SAASK,KAAKH,OAAO,CAAC,YAAY,KAAKA,OAAO,CAAC,WAAW,KAAKA,OAAO,CAAC,UAAU;AAC1F;AAEA,iFAAiF,GACjF,SAASI,OAAOC,KAA8B;IAC5C,MAAMF,OAAOE,KAAK,CAAC,OAAO;IAC1B,IAAI,OAAOF,SAAS,YAAYA,KAAKF,IAAI,IAAI,OAAO;QAAEK,MAAMJ,SAASC;QAAOI,OAAO;IAAM;IACzF,MAAMC,WAAWH,KAAK,CAAC,WAAW;IAClC,OAAO,OAAOG,aAAa,WAAW;QAAEF,MAAMR,SAASU;QAAWD,OAAO;IAAK,IAAI;QAAED,MAAM;QAAIC,OAAO;IAAK;AAC5G;AAEA,MAAME,aAAa,CAACC,OAClBC,MAAMC,OAAO,CAACF,wBAAAA,KAAMG,KAAK,IAAI,CAACH,wBAAAA,KAAMG,KAAK,EAAeC,MAAM,CAAC,CAACC,KAAqB,OAAOA,OAAO,YAAY,EAAE;AAEnH,yEAAyE,GACzE,OAAO,SAASC,eACdH,KAA2C,EAC3CI,UAAkD,CAAC,CAAC;QAgBdA;IAdtC,MAAMC,QAAwB;QAC5BZ,MAAM;QACNa,WAAW;QACXC,UAAU,EAAE;QACZC,KAAK,EAAE;QACPC,QAAQ,EAAE;QACVC,kBAAkB,EAAE;QACpBC,eAAe;IACjB;IACA,IAAI,CAACX,OAAO,OAAOK;IACnB,MAAMM,gBAAgBhC,kBAAkBqB,OAAOI,QAAQQ,MAAM;IAC7D,IAAI,CAACD,eAAe,OAAON;IAE3B,MAAMQ,WAAWrC,kBAAkB;QAAEwB;QAAOY,QAAQR,QAAQQ,MAAM;IAAC;IACnE,MAAMnB,OAAOoB,SAASzB,IAAI,GAAG0B,KAAK,CAAC,IAAGV,oBAAAA,QAAQW,QAAQ,YAAhBX,oBAAoBxB;IAC1D,MAAM2B,WAA2B,EAAE;IACnC,MAAME,SAAuB,EAAE;IAC/B,IAAIO,WAAW;IAEf,MAAMC,OAAO,IAAIjC;IACjB,MAAMkC,QAAQ,CAAChB,IAAYiB;YAMVtB,aACYA,mBAgByBL;QAtBpD,IAAI2B,QAAQrC,aAAamC,KAAKG,GAAG,CAAClB,KAAK;QACvC,MAAML,OAAOG,KAAK,CAACE,GAAG;QACtB,IAAI,CAACL,MAAM;QACXoB,KAAKI,GAAG,CAACnB;QACT,IAAIxB,iBAAiBmB,OAAO;QAC5B,MAAML,SAASK,cAAAA,KAAKL,KAAK,YAAVK,cAAc,CAAC;QAC9B,MAAMyB,cAAcC,QAAO1B,oBAAAA,KAAKyB,WAAW,YAAhBzB,oBAAoB;QAC/C,IAAId,gBAAgBqC,GAAG,CAACE,cAAc;YACpC,MAAM,EAAE7B,MAAM+B,GAAG,EAAE9B,KAAK,EAAE,GAAGH,OAAOC;YACpC,MAAMiC,QAAQhD,eAAee;YAC7B,IAAIgC,KAAK;gBACP,IAAIC,QAAQ,GAAGlB,SAASmB,IAAI,CAAC;oBAAEC,QAAQzB;oBAAIuB;oBAAOhC,MAAM+B;oBAAKI,UAAUlC;gBAAM;gBAC7EsB,WAAWQ;YACb;QACF,OAAO,IAAIF,gBAAgB,cAAc,OAAO9B,KAAK,CAAC,UAAU,KAAK,UAAU;YAC7E,KAAK,MAAMqC,QAAQN,OAAO/B,KAAK,CAAC,UAAU,EAAEsC,KAAK,CAAC,MAAO;gBACvD,MAAMC,QAAQ,oBAAoBC,IAAI,CAACH,KAAKzC,IAAI;gBAChD,IAAI2C,OAAO;oBACTxB,SAASmB,IAAI,CAAC;wBAAEC,QAAQ;wBAAMF,OAAOM,KAAK,CAAC,EAAE,CAACE,MAAM;wBAAExC,MAAMR,SAAS8C,KAAK,CAAC,EAAE;wBAAGH,UAAU;oBAAM;gBAClG;YACF;YACAZ,WAAW/B,SAASsC,OAAO/B,KAAK,CAAC,UAAU,GAAGsB,KAAK,CAAC,GAAGjC;QACzD,OAAO,IAAIyC,gBAAgB,iBAAiB,SAAQ9B,cAAAA,KAAK,CAAC,OAAO,YAAbA,cAAiBA,KAAK,CAAC,WAAW,MAAM,UAAU;gBAChFA;YAApB,MAAMF,OAAOiC,QAAO/B,eAAAA,KAAK,CAAC,OAAO,YAAbA,eAAiBA,KAAK,CAAC,WAAW;YACtD,KAAK,MAAMuC,SAASzC,KAAK4C,QAAQ,CAAC,sCAAuC;gBACvE3B,SAASmB,IAAI,CAAC;oBAAEC,QAAQ;oBAAMF,OAAOU,OAAOJ,KAAK,CAAC,EAAE;oBAAGtC,MAAMJ,SAAS0C,KAAK,CAAC,EAAE;oBAAGH,UAAU;gBAAM;YACnG;QACF,OAAO,IAAIN,gBAAgB,SAAS;gBACf9B;YAAnB,MAAM4C,MAAMb,QAAO/B,aAAAA,KAAK,CAAC,MAAM,YAAZA,aAAgB,IAAIJ,IAAI;YAC3C,IAAIgD,KAAK;oBAIgB5C;gBAHvBiB,OAAOiB,IAAI,CAAC;oBACVC,QAAQzB;oBACRkC;oBACAC,KAAKpD,SAASsC,QAAO/B,aAAAA,KAAK,CAAC,MAAM,YAAZA,aAAgB;oBACrC8C,SAAStB,SAASF,KAAK,CAAC,GAAGjC;gBAC7B;YACF;QACF;QACA,KAAK,MAAM0D,WAAW3C,WAAWC,MAAOqB,MAAMqB,SAASpB,QAAQ;IACjE;IACAD,MAAMP,eAAe;IAErB,OAAO;QACLlB;QACAa,WAAWb,OAAOA,KAAKqC,KAAK,CAAC,OAAO7B,MAAM,CAACuC,SAASP,MAAM,GAAG;QAC7D1B;QACAC,KAAKD,SAASN,MAAM,CAAC,CAACwC,UAAYA,QAAQhB,KAAK,KAAK;QACpDhB;QACAC,kBAAkBD,OAAOR,MAAM,CAAC,CAACyC,QAAU,CAACA,MAAML,GAAG;QACrD1B;IACF;AACF"}