@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,260 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { SEO_LISTING_FIELDS, seoListingFieldTooLong } from "@aglyn/aglyn/app-utils/seo-listing-fields";
+import { aiSeoKeywordCoverage, aiSeoKeywordList } from "../tools/ai-seo-tool.js";
+/**
+ * The site SEO audit's scoring (AGL-2910): every audited page held to what a
+ * search result and a crawler need, with nothing asked of a model. Pure, so
+ * the audit is proved against fixtures and a job only spends tokens on the
+ * fixes it cannot make without writing.
+ *
+ * Per page: a title and a description of its own, within their lengths and
+ * used on no other page; one main heading that says something; a description
+ * on every image; a link from somewhere else on the site; and the target
+ * keywords a person named, reported where the page already says them.
+ * Per site: whether search engines are told to stay away, whether the
+ * structured data names and describes the publisher, and whether agents get
+ * guidance of the author's own.
+ *
+ * Keyword coverage is reported, never forced. A page that does not say a
+ * keyword is told so; the fix a job proposes uses the keyword only where the
+ * page is about it, and the listing check refuses a keyword used past its
+ * per-field count.
+ */ /** Pages one audit covers. A larger site is audited on its first pages by path, and says how many it left. */ export const AI_SEO_AUDIT_MAX_PAGES = 150;
+/** Pages one batch of fixes carries: one model call a batch. */ export const AI_SEO_AUDIT_BATCH_SIZE = 8;
+/** What each severity takes off a page's score. */ const SEVERITY_WEIGHT = {
+    high: 25,
+    medium: 10,
+    low: 3
+};
+/** A main heading this short or this generic says nothing a searcher can use. */ const THIN_H1_MIN_CHARS = 10;
+const GENERIC_H1 = new Set([
+    'home',
+    'homepage',
+    'home page',
+    'welcome',
+    'hello',
+    'untitled',
+    'new page',
+    'page',
+    'title',
+    'heading'
+]);
+/** The findings a batch of generated fixes answers. */ const GENERATED_FIX_CODES = new Set([
+    'title-missing',
+    'title-too-long',
+    'title-duplicate',
+    'description-missing',
+    'description-too-long',
+    'description-duplicate',
+    'h1-missing',
+    'h1-thin',
+    'image-alt-missing',
+    'keyword-missing'
+]);
+const blank = (value)=>!String(value != null ? value : '').trim();
+const normalized = (value)=>String(value != null ? value : '').replace(/\s+/g, ' ').trim().toLowerCase();
+/** A path as the keyword lines and the routing map both spell it: leading slash, no trailing one. */ export function aiSeoNormalizePath(path) {
+    const trimmed = String(path != null ? path : '').trim();
+    if (!trimmed || trimmed === '/') return '/';
+    return `/${trimmed.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+/**
+ * Target keywords per page, one line a page: `/pricing: plans, pricing`.
+ * A line without a path, or with a path the site does not have, names no
+ * page; the step reports the paths it could not match.
+ */ export function parseAiSeoKeywordLines(raw) {
+    const out = {};
+    for (const line of String(raw != null ? raw : '').split('\n')){
+        var _out_path;
+        const at = line.indexOf(':');
+        if (at <= 0) continue;
+        const path = aiSeoNormalizePath(line.slice(0, at));
+        const keywords = aiSeoKeywordList(line.slice(at + 1));
+        if (keywords.length) out[path] = aiSeoKeywordList([
+            ...(_out_path = out[path]) != null ? _out_path : [],
+            ...keywords
+        ]);
+    }
+    return out;
+}
+function finding(code, severity, message, extra = {}) {
+    return _extends({
+        code,
+        severity,
+        message
+    }, extra);
+}
+/** The pages that share one value, by that value. */ function sharedValues(pages, read) {
+    const groups = new Map();
+    for (const page of pages){
+        var _groups_get;
+        const key = normalized(read(page));
+        if (!key) continue;
+        groups.set(key, [
+            ...(_groups_get = groups.get(key)) != null ? _groups_get : [],
+            page.screenId
+        ]);
+    }
+    return new Map([
+        ...groups
+    ].filter(([, ids])=>ids.length > 1));
+}
+function pageFindings(page, titles, descriptions) {
+    var _h1s_;
+    const out = [];
+    const title = page.seo.title;
+    if (blank(title)) {
+        out.push(finding('title-missing', 'medium', 'This page has no search title, so results show its name beside the site title.'));
+    } else {
+        var _titles_get;
+        if (seoListingFieldTooLong('title', title)) {
+            out.push(finding('title-too-long', 'medium', `The search title is over ${SEO_LISTING_FIELDS.title.maxLength} characters and will be cut off in results.`));
+        }
+        const twins = (_titles_get = titles.get(normalized(title))) == null ? void 0 : _titles_get.filter((id)=>id !== page.screenId);
+        if (twins == null ? void 0 : twins.length) {
+            out.push(finding('title-duplicate', 'high', 'Another page uses the same search title, so results cannot tell them apart.', {
+                screenIds: twins
+            }));
+        }
+    }
+    const description = page.seo.description;
+    if (blank(description) && blank(page.description)) {
+        out.push(finding('description-missing', 'medium', 'This page has no search description, so results show the site’s.'));
+    } else if (!blank(description)) {
+        var _descriptions_get;
+        if (seoListingFieldTooLong('description', description)) {
+            out.push(finding('description-too-long', 'low', `The search description is over ${SEO_LISTING_FIELDS.description.maxLength} characters and will be cut off.`));
+        }
+        const twins = (_descriptions_get = descriptions.get(normalized(description))) == null ? void 0 : _descriptions_get.filter((id)=>id !== page.screenId);
+        if (twins == null ? void 0 : twins.length) {
+            out.push(finding('description-duplicate', 'medium', 'Another page uses the same search description.', {
+                screenIds: twins
+            }));
+        }
+    }
+    const { h1s } = page.facts;
+    if (!h1s.length) {
+        out.push(finding('h1-missing', 'high', 'This page has no main heading.'));
+    } else {
+        if (h1s.length > 1) {
+            out.push(finding('h1-multiple', 'medium', `This page has ${h1s.length} main headings; it should have one.`, {
+                nodeIds: h1s.slice(1).map((heading)=>heading.nodeId).filter((id)=>Boolean(id))
+            }));
+        }
+        const first = h1s[0];
+        if (first.text.length < THIN_H1_MIN_CHARS || GENERIC_H1.has(normalized(first.text))) {
+            out.push(finding('h1-thin', 'medium', `The main heading “${first.text}” says little about the page.`, {
+                nodeIds: first.nodeId ? [
+                    first.nodeId
+                ] : []
+            }));
+        }
+    }
+    const missingAlt = page.facts.imagesMissingAlt;
+    if (missingAlt.length) {
+        out.push(finding('image-alt-missing', 'medium', `${missingAlt.length} ${missingAlt.length === 1 ? 'image has' : 'images have'} no description for readers who cannot see ${missingAlt.length === 1 ? 'it' : 'them'}.`, {
+            nodeIds: missingAlt.map((image)=>image.nodeId)
+        }));
+    }
+    if (!page.linkedFrom && page.path !== '/') {
+        out.push(finding('orphan', 'medium', 'No other page or shared layout links here, so visitors and crawlers may never find it.'));
+    }
+    const coverage = aiSeoKeywordCoverage(page.keywords, {
+        title: page.seo.title,
+        description: page.seo.description,
+        h1: (_h1s_ = h1s[0]) == null ? void 0 : _h1s_.text,
+        body: page.facts.text
+    });
+    for (const entry of coverage){
+        if (!entry.inTitle && !entry.inDescription && !entry.inH1 && !entry.inBody) {
+            out.push(finding('keyword-missing', 'low', `The page never says “${entry.keyword}”. Only use it if the page is about it.`, {
+                keyword: entry.keyword
+            }));
+        }
+    }
+    return out;
+}
+function scoreOf(findings) {
+    return Math.max(0, 100 - findings.reduce((sum, entry)=>sum + SEVERITY_WEIGHT[entry.severity], 0));
+}
+/** Audit the pages and the site; nothing here reads, writes or generates. */ export function aiSeoAudit(pages, site, options = {}) {
+    var _options_skipped, _options_batchSize;
+    const titles = sharedValues(pages, (page)=>page.seo.title);
+    const descriptions = sharedValues(pages, (page)=>page.seo.description);
+    const reports = pages.map((page)=>{
+        var _page_facts_h1s_;
+        const findings = pageFindings(page, titles, descriptions);
+        return {
+            screenId: page.screenId,
+            path: page.path,
+            name: page.name,
+            versionId: page.versionId,
+            score: scoreOf(findings),
+            findings,
+            keywords: aiSeoKeywordCoverage(page.keywords, {
+                title: page.seo.title,
+                description: page.seo.description,
+                h1: (_page_facts_h1s_ = page.facts.h1s[0]) == null ? void 0 : _page_facts_h1s_.text,
+                body: page.facts.text
+            })
+        };
+    });
+    const siteFindings = [];
+    if (site.discouraged) {
+        siteFindings.push(finding('search-discouraged', 'high', 'Search engines are asked not to index this site, so none of its pages appear in results.'));
+    }
+    if (blank(site.entity.name) || blank(site.entity.description)) {
+        siteFindings.push(finding('entity-incomplete', 'low', 'The structured data does not name and describe who publishes the site.'));
+    }
+    if (blank(site.agent.whenToUse)) {
+        siteFindings.push(finding('llms-guidance-missing', 'low', '/llms.txt carries no guidance of your own for AI agents.'));
+    }
+    const queue = reports.filter((report)=>report.findings.some((entry)=>GENERATED_FIX_CODES.has(entry.code))).sort((a, b)=>a.score - b.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)).map((report)=>report.screenId);
+    return {
+        kind: 'audit',
+        pages: reports,
+        skipped: Math.max(0, (_options_skipped = options.skipped) != null ? _options_skipped : 0),
+        site: siteFindings,
+        siteProposal: siteFindings.some((entry)=>entry.code === 'entity-incomplete' || entry.code === 'llms-guidance-missing'),
+        queue,
+        batchSize: Math.max(1, (_options_batchSize = options.batchSize) != null ? _options_batchSize : AI_SEO_AUDIT_BATCH_SIZE),
+        score: reports.length ? Math.round(reports.reduce((sum, report)=>sum + report.score, 0) / reports.length) : 100,
+        notes: []
+    };
+}
+/**
+ * The content fixes that need no model: every main heading after the first
+ * editable one becomes an `h2`, so the page keeps one.
+ */ export function aiSeoHeadingDemotions(facts) {
+    const editable = facts.h1s.filter((heading)=>heading.editable && heading.nodeId);
+    if (facts.h1s.length < 2 || !editable.length) return [];
+    const keep = editable[0].nodeId;
+    return editable.filter((heading)=>heading.nodeId !== keep).map((heading)=>({
+            kind: 'h1-demote',
+            nodeId: heading.nodeId
+        }));
+}
+/** The queue's batches, in order. */ export function aiSeoAuditBatches(report) {
+    const batches = [];
+    for(let start = 0; start < report.queue.length; start += report.batchSize){
+        batches.push(report.queue.slice(start, start + report.batchSize));
+    }
+    return batches;
+}
+
+//# sourceMappingURL=seo-audit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/seo-audit.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  SEO_LISTING_FIELDS,\n  seoListingFieldTooLong,\n} from '@aglyn/aglyn/app-utils/seo-listing-fields'\nimport type {\n  AiSeoAuditReport,\n  AiSeoContentFix,\n  AiSeoFinding,\n  AiSeoFindingCode,\n  AiSeoPageReport,\n  AiSeoSeverity,\n} from '../model/ai-seo'\nimport { aiSeoKeywordCoverage, aiSeoKeywordList } from '../tools/ai-seo-tool'\nimport type { AiSeoPageFacts } from './seo-page-facts'\n\n/**\n * The site SEO audit's scoring (AGL-2910): every audited page held to what a\n * search result and a crawler need, with nothing asked of a model. Pure, so\n * the audit is proved against fixtures and a job only spends tokens on the\n * fixes it cannot make without writing.\n *\n * Per page: a title and a description of its own, within their lengths and\n * used on no other page; one main heading that says something; a description\n * on every image; a link from somewhere else on the site; and the target\n * keywords a person named, reported where the page already says them.\n * Per site: whether search engines are told to stay away, whether the\n * structured data names and describes the publisher, and whether agents get\n * guidance of the author's own.\n *\n * Keyword coverage is reported, never forced. A page that does not say a\n * keyword is told so; the fix a job proposes uses the keyword only where the\n * page is about it, and the listing check refuses a keyword used past its\n * per-field count.\n */\n\n/** Pages one audit covers. A larger site is audited on its first pages by path, and says how many it left. */\nexport const AI_SEO_AUDIT_MAX_PAGES = 150\n\n/** Pages one batch of fixes carries: one model call a batch. */\nexport const AI_SEO_AUDIT_BATCH_SIZE = 8\n\n/** What each severity takes off a page's score. */\nconst SEVERITY_WEIGHT: Record<AiSeoSeverity, number> = { high: 25, medium: 10, low: 3 }\n\n/** A main heading this short or this generic says nothing a searcher can use. */\nconst THIN_H1_MIN_CHARS = 10\nconst GENERIC_H1: ReadonlySet<string> = new Set([\n  'home',\n  'homepage',\n  'home page',\n  'welcome',\n  'hello',\n  'untitled',\n  'new page',\n  'page',\n  'title',\n  'heading',\n])\n\n/** The findings a batch of generated fixes answers. */\nconst GENERATED_FIX_CODES: ReadonlySet<AiSeoFindingCode> = new Set([\n  'title-missing',\n  'title-too-long',\n  'title-duplicate',\n  'description-missing',\n  'description-too-long',\n  'description-duplicate',\n  'h1-missing',\n  'h1-thin',\n  'image-alt-missing',\n  'keyword-missing',\n])\n\n/** One page as the audit reads it. */\nexport interface AiSeoAuditPage {\n  screenId: string\n  /** The public path, `/` for the home page. */\n  path: string\n  name: string\n  versionId: string | null\n  seo: {\n    title?: string | null\n    description?: string | null\n    breadcrumb?: string | null\n    image?: string | null\n    imageAlt?: string | null\n  }\n  /** The screen's own description, which the head falls back to. */\n  description?: string | null\n  facts: AiSeoPageFacts\n  /** Whether another audited page or a shared layout links here. */\n  linkedFrom: boolean\n  keywords: readonly string[]\n}\n\n/** The site as the audit reads it. */\nexport interface AiSeoAuditSite {\n  discouraged: boolean\n  entity: { name?: string | null; description?: string | null }\n  agent: { whenToUse?: string | null }\n}\n\nconst blank = (value: string | null | undefined): boolean => !String(value ?? '').trim()\nconst normalized = (value: string | null | undefined): string =>\n  String(value ?? '').replace(/\\s+/g, ' ').trim().toLowerCase()\n\n/** A path as the keyword lines and the routing map both spell it: leading slash, no trailing one. */\nexport function aiSeoNormalizePath(path: string): string {\n  const trimmed = String(path ?? '').trim()\n  if (!trimmed || trimmed === '/') return '/'\n  return `/${trimmed.replace(/^\\/+/, '').replace(/\\/+$/, '')}`\n}\n\n/**\n * Target keywords per page, one line a page: `/pricing: plans, pricing`.\n * A line without a path, or with a path the site does not have, names no\n * page; the step reports the paths it could not match.\n */\nexport function parseAiSeoKeywordLines(raw: unknown): Record<string, string[]> {\n  const out: Record<string, string[]> = {}\n  for (const line of String(raw ?? '').split('\\n')) {\n    const at = line.indexOf(':')\n    if (at <= 0) continue\n    const path = aiSeoNormalizePath(line.slice(0, at))\n    const keywords = aiSeoKeywordList(line.slice(at + 1))\n    if (keywords.length) out[path] = aiSeoKeywordList([...(out[path] ?? []), ...keywords])\n  }\n  return out\n}\n\nfunction finding(\n  code: AiSeoFindingCode,\n  severity: AiSeoSeverity,\n  message: string,\n  extra: Partial<Pick<AiSeoFinding, 'nodeIds' | 'screenIds' | 'keyword'>> = {},\n): AiSeoFinding {\n  return { code, severity, message, ...extra }\n}\n\n/** The pages that share one value, by that value. */\nfunction sharedValues(\n  pages: readonly AiSeoAuditPage[],\n  read: (page: AiSeoAuditPage) => string | null | undefined,\n): Map<string, string[]> {\n  const groups = new Map<string, string[]>()\n  for (const page of pages) {\n    const key = normalized(read(page))\n    if (!key) continue\n    groups.set(key, [...(groups.get(key) ?? []), page.screenId])\n  }\n  return new Map([...groups].filter(([, ids]) => ids.length > 1))\n}\n\nfunction pageFindings(\n  page: AiSeoAuditPage,\n  titles: Map<string, string[]>,\n  descriptions: Map<string, string[]>,\n): AiSeoFinding[] {\n  const out: AiSeoFinding[] = []\n  const title = page.seo.title\n  if (blank(title)) {\n    out.push(finding('title-missing', 'medium', 'This page has no search title, so results show its name beside the site title.'))\n  } else {\n    if (seoListingFieldTooLong('title', title)) {\n      out.push(finding('title-too-long', 'medium', `The search title is over ${SEO_LISTING_FIELDS.title.maxLength} characters and will be cut off in results.`))\n    }\n    const twins = titles.get(normalized(title))?.filter((id) => id !== page.screenId)\n    if (twins?.length) {\n      out.push(finding('title-duplicate', 'high', 'Another page uses the same search title, so results cannot tell them apart.', { screenIds: twins }))\n    }\n  }\n\n  const description = page.seo.description\n  if (blank(description) && blank(page.description)) {\n    out.push(finding('description-missing', 'medium', 'This page has no search description, so results show the site’s.'))\n  } else if (!blank(description)) {\n    if (seoListingFieldTooLong('description', description)) {\n      out.push(finding('description-too-long', 'low', `The search description is over ${SEO_LISTING_FIELDS.description.maxLength} characters and will be cut off.`))\n    }\n    const twins = descriptions.get(normalized(description))?.filter((id) => id !== page.screenId)\n    if (twins?.length) {\n      out.push(finding('description-duplicate', 'medium', 'Another page uses the same search description.', { screenIds: twins }))\n    }\n  }\n\n  const { h1s } = page.facts\n  if (!h1s.length) {\n    out.push(finding('h1-missing', 'high', 'This page has no main heading.'))\n  } else {\n    if (h1s.length > 1) {\n      out.push(\n        finding('h1-multiple', 'medium', `This page has ${h1s.length} main headings; it should have one.`, {\n          nodeIds: h1s.slice(1).map((heading) => heading.nodeId).filter((id): id is string => Boolean(id)),\n        }),\n      )\n    }\n    const first = h1s[0]\n    if (first.text.length < THIN_H1_MIN_CHARS || GENERIC_H1.has(normalized(first.text))) {\n      out.push(\n        finding('h1-thin', 'medium', `The main heading “${first.text}” says little about the page.`, {\n          nodeIds: first.nodeId ? [first.nodeId] : [],\n        }),\n      )\n    }\n  }\n\n  const missingAlt = page.facts.imagesMissingAlt\n  if (missingAlt.length) {\n    out.push(\n      finding(\n        'image-alt-missing',\n        'medium',\n        `${missingAlt.length} ${missingAlt.length === 1 ? 'image has' : 'images have'} no description for readers who cannot see ${missingAlt.length === 1 ? 'it' : 'them'}.`,\n        { nodeIds: missingAlt.map((image) => image.nodeId) },\n      ),\n    )\n  }\n\n  if (!page.linkedFrom && page.path !== '/') {\n    out.push(finding('orphan', 'medium', 'No other page or shared layout links here, so visitors and crawlers may never find it.'))\n  }\n\n  const coverage = aiSeoKeywordCoverage(page.keywords, {\n    title: page.seo.title,\n    description: page.seo.description,\n    h1: h1s[0]?.text,\n    body: page.facts.text,\n  })\n  for (const entry of coverage) {\n    if (!entry.inTitle && !entry.inDescription && !entry.inH1 && !entry.inBody) {\n      out.push(\n        finding('keyword-missing', 'low', `The page never says “${entry.keyword}”. Only use it if the page is about it.`, {\n          keyword: entry.keyword,\n        }),\n      )\n    }\n  }\n  return out\n}\n\nfunction scoreOf(findings: readonly AiSeoFinding[]): number {\n  return Math.max(0, 100 - findings.reduce((sum, entry) => sum + SEVERITY_WEIGHT[entry.severity], 0))\n}\n\n/** Audit the pages and the site; nothing here reads, writes or generates. */\nexport function aiSeoAudit(\n  pages: readonly AiSeoAuditPage[],\n  site: AiSeoAuditSite,\n  options: { skipped?: number; batchSize?: number } = {},\n): AiSeoAuditReport {\n  const titles = sharedValues(pages, (page) => page.seo.title)\n  const descriptions = sharedValues(pages, (page) => page.seo.description)\n  const reports: AiSeoPageReport[] = pages.map((page) => {\n    const findings = pageFindings(page, titles, descriptions)\n    return {\n      screenId: page.screenId,\n      path: page.path,\n      name: page.name,\n      versionId: page.versionId,\n      score: scoreOf(findings),\n      findings,\n      keywords: aiSeoKeywordCoverage(page.keywords, {\n        title: page.seo.title,\n        description: page.seo.description,\n        h1: page.facts.h1s[0]?.text,\n        body: page.facts.text,\n      }),\n    }\n  })\n\n  const siteFindings: AiSeoFinding[] = []\n  if (site.discouraged) {\n    siteFindings.push(finding('search-discouraged', 'high', 'Search engines are asked not to index this site, so none of its pages appear in results.'))\n  }\n  if (blank(site.entity.name) || blank(site.entity.description)) {\n    siteFindings.push(finding('entity-incomplete', 'low', 'The structured data does not name and describe who publishes the site.'))\n  }\n  if (blank(site.agent.whenToUse)) {\n    siteFindings.push(finding('llms-guidance-missing', 'low', '/llms.txt carries no guidance of your own for AI agents.'))\n  }\n\n  const queue = reports\n    .filter((report) => report.findings.some((entry) => GENERATED_FIX_CODES.has(entry.code)))\n    .sort((a, b) => a.score - b.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))\n    .map((report) => report.screenId)\n\n  return {\n    kind: 'audit',\n    pages: reports,\n    skipped: Math.max(0, options.skipped ?? 0),\n    site: siteFindings,\n    siteProposal: siteFindings.some((entry) => entry.code === 'entity-incomplete' || entry.code === 'llms-guidance-missing'),\n    queue,\n    batchSize: Math.max(1, options.batchSize ?? AI_SEO_AUDIT_BATCH_SIZE),\n    score: reports.length\n      ? Math.round(reports.reduce((sum, report) => sum + report.score, 0) / reports.length)\n      : 100,\n    notes: [],\n  }\n}\n\n/**\n * The content fixes that need no model: every main heading after the first\n * editable one becomes an `h2`, so the page keeps one.\n */\nexport function aiSeoHeadingDemotions(facts: AiSeoPageFacts): AiSeoContentFix[] {\n  const editable = facts.h1s.filter((heading) => heading.editable && heading.nodeId)\n  if (facts.h1s.length < 2 || !editable.length) return []\n  const keep = editable[0].nodeId\n  return editable\n    .filter((heading) => heading.nodeId !== keep)\n    .map((heading) => ({ kind: 'h1-demote', nodeId: heading.nodeId as string }))\n}\n\n/** The queue's batches, in order. */\nexport function aiSeoAuditBatches(report: Pick<AiSeoAuditReport, 'queue' | 'batchSize'>): string[][] {\n  const batches: string[][] = []\n  for (let start = 0; start < report.queue.length; start += report.batchSize) {\n    batches.push(report.queue.slice(start, start + report.batchSize))\n  }\n  return batches\n}\n"],"names":["SEO_LISTING_FIELDS","seoListingFieldTooLong","aiSeoKeywordCoverage","aiSeoKeywordList","AI_SEO_AUDIT_MAX_PAGES","AI_SEO_AUDIT_BATCH_SIZE","SEVERITY_WEIGHT","high","medium","low","THIN_H1_MIN_CHARS","GENERIC_H1","Set","GENERATED_FIX_CODES","blank","value","String","trim","normalized","replace","toLowerCase","aiSeoNormalizePath","path","trimmed","parseAiSeoKeywordLines","raw","out","line","split","at","indexOf","slice","keywords","length","finding","code","severity","message","extra","sharedValues","pages","read","groups","Map","page","key","set","get","screenId","filter","ids","pageFindings","titles","descriptions","h1s","title","seo","push","maxLength","twins","id","screenIds","description","facts","nodeIds","map","heading","nodeId","Boolean","first","text","has","missingAlt","imagesMissingAlt","image","linkedFrom","coverage","h1","body","entry","inTitle","inDescription","inH1","inBody","keyword","scoreOf","findings","Math","max","reduce","sum","aiSeoAudit","site","options","reports","name","versionId","score","siteFindings","discouraged","entity","agent","whenToUse","queue","report","some","sort","a","b","kind","skipped","siteProposal","batchSize","round","notes","aiSeoHeadingDemotions","editable","keep","aiSeoAuditBatches","batches","start"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,kBAAkB,EAClBC,sBAAsB,QACjB,4CAA2C;AASlD,SAASC,oBAAoB,EAAEC,gBAAgB,QAAQ,0BAAsB;AAG7E;;;;;;;;;;;;;;;;;;CAkBC,GAED,4GAA4G,GAC5G,OAAO,MAAMC,yBAAyB,IAAG;AAEzC,8DAA8D,GAC9D,OAAO,MAAMC,0BAA0B,EAAC;AAExC,iDAAiD,GACjD,MAAMC,kBAAiD;IAAEC,MAAM;IAAIC,QAAQ;IAAIC,KAAK;AAAE;AAEtF,+EAA+E,GAC/E,MAAMC,oBAAoB;AAC1B,MAAMC,aAAkC,IAAIC,IAAI;IAC9C;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,qDAAqD,GACrD,MAAMC,sBAAqD,IAAID,IAAI;IACjE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AA+BD,MAAME,QAAQ,CAACC,QAA8C,CAACC,OAAOD,gBAAAA,QAAS,IAAIE,IAAI;AACtF,MAAMC,aAAa,CAACH,QAClBC,OAAOD,gBAAAA,QAAS,IAAII,OAAO,CAAC,QAAQ,KAAKF,IAAI,GAAGG,WAAW;AAE7D,mGAAmG,GACnG,OAAO,SAASC,mBAAmBC,IAAY;IAC7C,MAAMC,UAAUP,OAAOM,eAAAA,OAAQ,IAAIL,IAAI;IACvC,IAAI,CAACM,WAAWA,YAAY,KAAK,OAAO;IACxC,OAAO,CAAC,CAAC,EAAEA,QAAQJ,OAAO,CAAC,QAAQ,IAAIA,OAAO,CAAC,QAAQ,KAAK;AAC9D;AAEA;;;;CAIC,GACD,OAAO,SAASK,uBAAuBC,GAAY;IACjD,MAAMC,MAAgC,CAAC;IACvC,KAAK,MAAMC,QAAQX,OAAOS,cAAAA,MAAO,IAAIG,KAAK,CAAC,MAAO;YAKOF;QAJvD,MAAMG,KAAKF,KAAKG,OAAO,CAAC;QACxB,IAAID,MAAM,GAAG;QACb,MAAMP,OAAOD,mBAAmBM,KAAKI,KAAK,CAAC,GAAGF;QAC9C,MAAMG,WAAW7B,iBAAiBwB,KAAKI,KAAK,CAACF,KAAK;QAClD,IAAIG,SAASC,MAAM,EAAEP,GAAG,CAACJ,KAAK,GAAGnB,iBAAiB;gBAAKuB,YAAAA,GAAG,CAACJ,KAAK,YAATI,YAAa,EAAE;eAAMM;SAAS;IACvF;IACA,OAAON;AACT;AAEA,SAASQ,QACPC,IAAsB,EACtBC,QAAuB,EACvBC,OAAe,EACfC,QAA0E,CAAC,CAAC;IAE5E,OAAO;QAAEH;QAAMC;QAAUC;OAAYC;AACvC;AAEA,mDAAmD,GACnD,SAASC,aACPC,KAAgC,EAChCC,IAAyD;IAEzD,MAAMC,SAAS,IAAIC;IACnB,KAAK,MAAMC,QAAQJ,MAAO;YAGHE;QAFrB,MAAMG,MAAM3B,WAAWuB,KAAKG;QAC5B,IAAI,CAACC,KAAK;QACVH,OAAOI,GAAG,CAACD,KAAK;gBAAKH,cAAAA,OAAOK,GAAG,CAACF,gBAAXH,cAAmB,EAAE;YAAGE,KAAKI,QAAQ;SAAC;IAC7D;IACA,OAAO,IAAIL,IAAI;WAAID;KAAO,CAACO,MAAM,CAAC,CAAC,GAAGC,IAAI,GAAKA,IAAIjB,MAAM,GAAG;AAC9D;AAEA,SAASkB,aACPP,IAAoB,EACpBQ,MAA6B,EAC7BC,YAAmC;QAqE7BC;IAnEN,MAAM5B,MAAsB,EAAE;IAC9B,MAAM6B,QAAQX,KAAKY,GAAG,CAACD,KAAK;IAC5B,IAAIzC,MAAMyC,QAAQ;QAChB7B,IAAI+B,IAAI,CAACvB,QAAQ,iBAAiB,UAAU;IAC9C,OAAO;YAISkB;QAHd,IAAInD,uBAAuB,SAASsD,QAAQ;YAC1C7B,IAAI+B,IAAI,CAACvB,QAAQ,kBAAkB,UAAU,CAAC,yBAAyB,EAAElC,mBAAmBuD,KAAK,CAACG,SAAS,CAAC,2CAA2C,CAAC;QAC1J;QACA,MAAMC,SAAQP,cAAAA,OAAOL,GAAG,CAAC7B,WAAWqC,4BAAtBH,YAA+BH,MAAM,CAAC,CAACW,KAAOA,OAAOhB,KAAKI,QAAQ;QAChF,IAAIW,yBAAAA,MAAO1B,MAAM,EAAE;YACjBP,IAAI+B,IAAI,CAACvB,QAAQ,mBAAmB,QAAQ,+EAA+E;gBAAE2B,WAAWF;YAAM;QAChJ;IACF;IAEA,MAAMG,cAAclB,KAAKY,GAAG,CAACM,WAAW;IACxC,IAAIhD,MAAMgD,gBAAgBhD,MAAM8B,KAAKkB,WAAW,GAAG;QACjDpC,IAAI+B,IAAI,CAACvB,QAAQ,uBAAuB,UAAU;IACpD,OAAO,IAAI,CAACpB,MAAMgD,cAAc;YAIhBT;QAHd,IAAIpD,uBAAuB,eAAe6D,cAAc;YACtDpC,IAAI+B,IAAI,CAACvB,QAAQ,wBAAwB,OAAO,CAAC,+BAA+B,EAAElC,mBAAmB8D,WAAW,CAACJ,SAAS,CAAC,gCAAgC,CAAC;QAC9J;QACA,MAAMC,SAAQN,oBAAAA,aAAaN,GAAG,CAAC7B,WAAW4C,kCAA5BT,kBAA2CJ,MAAM,CAAC,CAACW,KAAOA,OAAOhB,KAAKI,QAAQ;QAC5F,IAAIW,yBAAAA,MAAO1B,MAAM,EAAE;YACjBP,IAAI+B,IAAI,CAACvB,QAAQ,yBAAyB,UAAU,kDAAkD;gBAAE2B,WAAWF;YAAM;QAC3H;IACF;IAEA,MAAM,EAAEL,GAAG,EAAE,GAAGV,KAAKmB,KAAK;IAC1B,IAAI,CAACT,IAAIrB,MAAM,EAAE;QACfP,IAAI+B,IAAI,CAACvB,QAAQ,cAAc,QAAQ;IACzC,OAAO;QACL,IAAIoB,IAAIrB,MAAM,GAAG,GAAG;YAClBP,IAAI+B,IAAI,CACNvB,QAAQ,eAAe,UAAU,CAAC,cAAc,EAAEoB,IAAIrB,MAAM,CAAC,mCAAmC,CAAC,EAAE;gBACjG+B,SAASV,IAAIvB,KAAK,CAAC,GAAGkC,GAAG,CAAC,CAACC,UAAYA,QAAQC,MAAM,EAAElB,MAAM,CAAC,CAACW,KAAqBQ,QAAQR;YAC9F;QAEJ;QACA,MAAMS,QAAQf,GAAG,CAAC,EAAE;QACpB,IAAIe,MAAMC,IAAI,CAACrC,MAAM,GAAGvB,qBAAqBC,WAAW4D,GAAG,CAACrD,WAAWmD,MAAMC,IAAI,IAAI;YACnF5C,IAAI+B,IAAI,CACNvB,QAAQ,WAAW,UAAU,CAAC,kBAAkB,EAAEmC,MAAMC,IAAI,CAAC,6BAA6B,CAAC,EAAE;gBAC3FN,SAASK,MAAMF,MAAM,GAAG;oBAACE,MAAMF,MAAM;iBAAC,GAAG,EAAE;YAC7C;QAEJ;IACF;IAEA,MAAMK,aAAa5B,KAAKmB,KAAK,CAACU,gBAAgB;IAC9C,IAAID,WAAWvC,MAAM,EAAE;QACrBP,IAAI+B,IAAI,CACNvB,QACE,qBACA,UACA,GAAGsC,WAAWvC,MAAM,CAAC,CAAC,EAAEuC,WAAWvC,MAAM,KAAK,IAAI,cAAc,cAAc,2CAA2C,EAAEuC,WAAWvC,MAAM,KAAK,IAAI,OAAO,OAAO,CAAC,CAAC,EACrK;YAAE+B,SAASQ,WAAWP,GAAG,CAAC,CAACS,QAAUA,MAAMP,MAAM;QAAE;IAGzD;IAEA,IAAI,CAACvB,KAAK+B,UAAU,IAAI/B,KAAKtB,IAAI,KAAK,KAAK;QACzCI,IAAI+B,IAAI,CAACvB,QAAQ,UAAU,UAAU;IACvC;IAEA,MAAM0C,WAAW1E,qBAAqB0C,KAAKZ,QAAQ,EAAE;QACnDuB,OAAOX,KAAKY,GAAG,CAACD,KAAK;QACrBO,aAAalB,KAAKY,GAAG,CAACM,WAAW;QACjCe,EAAE,GAAEvB,QAAAA,GAAG,CAAC,EAAE,qBAANA,MAAQgB,IAAI;QAChBQ,MAAMlC,KAAKmB,KAAK,CAACO,IAAI;IACvB;IACA,KAAK,MAAMS,SAASH,SAAU;QAC5B,IAAI,CAACG,MAAMC,OAAO,IAAI,CAACD,MAAME,aAAa,IAAI,CAACF,MAAMG,IAAI,IAAI,CAACH,MAAMI,MAAM,EAAE;YAC1EzD,IAAI+B,IAAI,CACNvB,QAAQ,mBAAmB,OAAO,CAAC,qBAAqB,EAAE6C,MAAMK,OAAO,CAAC,uCAAuC,CAAC,EAAE;gBAChHA,SAASL,MAAMK,OAAO;YACxB;QAEJ;IACF;IACA,OAAO1D;AACT;AAEA,SAAS2D,QAAQC,QAAiC;IAChD,OAAOC,KAAKC,GAAG,CAAC,GAAG,MAAMF,SAASG,MAAM,CAAC,CAACC,KAAKX,QAAUW,MAAMpF,eAAe,CAACyE,MAAM3C,QAAQ,CAAC,EAAE;AAClG;AAEA,2EAA2E,GAC3E,OAAO,SAASuD,WACdnD,KAAgC,EAChCoD,IAAoB,EACpBC,UAAoD,CAAC,CAAC;QAyC/BA,kBAIEA;IA3CzB,MAAMzC,SAASb,aAAaC,OAAO,CAACI,OAASA,KAAKY,GAAG,CAACD,KAAK;IAC3D,MAAMF,eAAed,aAAaC,OAAO,CAACI,OAASA,KAAKY,GAAG,CAACM,WAAW;IACvE,MAAMgC,UAA6BtD,MAAMyB,GAAG,CAAC,CAACrB;YAYpCA;QAXR,MAAM0C,WAAWnC,aAAaP,MAAMQ,QAAQC;QAC5C,OAAO;YACLL,UAAUJ,KAAKI,QAAQ;YACvB1B,MAAMsB,KAAKtB,IAAI;YACfyE,MAAMnD,KAAKmD,IAAI;YACfC,WAAWpD,KAAKoD,SAAS;YACzBC,OAAOZ,QAAQC;YACfA;YACAtD,UAAU9B,qBAAqB0C,KAAKZ,QAAQ,EAAE;gBAC5CuB,OAAOX,KAAKY,GAAG,CAACD,KAAK;gBACrBO,aAAalB,KAAKY,GAAG,CAACM,WAAW;gBACjCe,EAAE,GAAEjC,mBAAAA,KAAKmB,KAAK,CAACT,GAAG,CAAC,EAAE,qBAAjBV,iBAAmB0B,IAAI;gBAC3BQ,MAAMlC,KAAKmB,KAAK,CAACO,IAAI;YACvB;QACF;IACF;IAEA,MAAM4B,eAA+B,EAAE;IACvC,IAAIN,KAAKO,WAAW,EAAE;QACpBD,aAAazC,IAAI,CAACvB,QAAQ,sBAAsB,QAAQ;IAC1D;IACA,IAAIpB,MAAM8E,KAAKQ,MAAM,CAACL,IAAI,KAAKjF,MAAM8E,KAAKQ,MAAM,CAACtC,WAAW,GAAG;QAC7DoC,aAAazC,IAAI,CAACvB,QAAQ,qBAAqB,OAAO;IACxD;IACA,IAAIpB,MAAM8E,KAAKS,KAAK,CAACC,SAAS,GAAG;QAC/BJ,aAAazC,IAAI,CAACvB,QAAQ,yBAAyB,OAAO;IAC5D;IAEA,MAAMqE,QAAQT,QACX7C,MAAM,CAAC,CAACuD,SAAWA,OAAOlB,QAAQ,CAACmB,IAAI,CAAC,CAAC1B,QAAUlE,oBAAoB0D,GAAG,CAACQ,MAAM5C,IAAI,IACrFuE,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEV,KAAK,GAAGW,EAAEX,KAAK,IAAKU,CAAAA,EAAErF,IAAI,GAAGsF,EAAEtF,IAAI,GAAG,CAAC,IAAIqF,EAAErF,IAAI,GAAGsF,EAAEtF,IAAI,GAAG,IAAI,CAAA,GAClF2C,GAAG,CAAC,CAACuC,SAAWA,OAAOxD,QAAQ;IAElC,OAAO;QACL6D,MAAM;QACNrE,OAAOsD;QACPgB,SAASvB,KAAKC,GAAG,CAAC,IAAGK,mBAAAA,QAAQiB,OAAO,YAAfjB,mBAAmB;QACxCD,MAAMM;QACNa,cAAcb,aAAaO,IAAI,CAAC,CAAC1B,QAAUA,MAAM5C,IAAI,KAAK,uBAAuB4C,MAAM5C,IAAI,KAAK;QAChGoE;QACAS,WAAWzB,KAAKC,GAAG,CAAC,IAAGK,qBAAAA,QAAQmB,SAAS,YAAjBnB,qBAAqBxF;QAC5C4F,OAAOH,QAAQ7D,MAAM,GACjBsD,KAAK0B,KAAK,CAACnB,QAAQL,MAAM,CAAC,CAACC,KAAKc,SAAWd,MAAMc,OAAOP,KAAK,EAAE,KAAKH,QAAQ7D,MAAM,IAClF;QACJiF,OAAO,EAAE;IACX;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,sBAAsBpD,KAAqB;IACzD,MAAMqD,WAAWrD,MAAMT,GAAG,CAACL,MAAM,CAAC,CAACiB,UAAYA,QAAQkD,QAAQ,IAAIlD,QAAQC,MAAM;IACjF,IAAIJ,MAAMT,GAAG,CAACrB,MAAM,GAAG,KAAK,CAACmF,SAASnF,MAAM,EAAE,OAAO,EAAE;IACvD,MAAMoF,OAAOD,QAAQ,CAAC,EAAE,CAACjD,MAAM;IAC/B,OAAOiD,SACJnE,MAAM,CAAC,CAACiB,UAAYA,QAAQC,MAAM,KAAKkD,MACvCpD,GAAG,CAAC,CAACC,UAAa,CAAA;YAAE2C,MAAM;YAAa1C,QAAQD,QAAQC,MAAM;QAAW,CAAA;AAC7E;AAEA,mCAAmC,GACnC,OAAO,SAASmD,kBAAkBd,MAAqD;IACrF,MAAMe,UAAsB,EAAE;IAC9B,IAAK,IAAIC,QAAQ,GAAGA,QAAQhB,OAAOD,KAAK,CAACtE,MAAM,EAAEuF,SAAShB,OAAOQ,SAAS,CAAE;QAC1EO,QAAQ9D,IAAI,CAAC+C,OAAOD,KAAK,CAACxE,KAAK,CAACyF,OAAOA,QAAQhB,OAAOQ,SAAS;IACjE;IACA,OAAOO;AACT"}

package/src/lib/runtime/seo-content-fixes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 { AiSeoContentFix } from '../model/ai-seo';
+/**
+ * A site audit's content fixes, applied to a COPY of a page's node map
+ * (AGL-2910). The caller stores the result as a new unpublished version;
+ * nothing here reads or writes a document, and the map it is handed is
+ * never changed.
+ *
+ * Each fix is checked against the page as it is now, not as it was audited:
+ * an image that has gained a description keeps it, a heading that has gone
+ * is skipped, and every skip is named. A heading's new text and a new
+ * heading pass the AI node-tree validator — the one path an AI-emitted node
+ * takes into storage — before they touch the copy.
+ */
+export interface AiSeoContentFixResult {
+    nodes: Record<string, Record<string, unknown>>;
+    /** Fixes that changed the copy. */
+    applied: AiSeoContentFix[];
+    /** Fixes that did not, each with the customer-safe reason. */
+    skipped: Array<{
+        fix: AiSeoContentFix;
+        reason: string;
+    }>;
+}
+/** Apply `fixes` to a copy of `nodes`, whose content region starts at `contentRootId`. */
+export declare function applyAiSeoContentFixes(nodes: Record<string, unknown>, fixes: readonly AiSeoContentFix[], contentRootId: string | null): AiSeoContentFixResult;

package/src/lib/runtime/seo-content-fixes.js

@@ -0,0 +1,168 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { MEDIA_ALT_MAX_LENGTH } from "@aglyn/aglyn/app-utils/media-alt";
+import { CANVAS_ROOT_ELEMENT_ID } from "@aglyn/aglyn/foundation/constants/canvas";
+import { validateAiNodeTree } from "./ai-node-tree.js";
+import { AI_TEXT_LIMITS } from "./ai-palette.js";
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+const TEXT_COMPONENTS = new Set([
+    'muiTypography',
+    'muiInlineText',
+    'muiListItemText'
+]);
+/**
+ * A heading as the validator would store it: the text held to a headline's
+ * length and the element to the palette. `null` when the validator refuses
+ * it — the text is not something a generated heading may say.
+ */ function validatedHeading(level, text) {
+    var _ref, _ref1;
+    var _root_nodes;
+    const result = validateAiNodeTree({
+        rootId: CANVAS_ROOT_ELEMENT_ID,
+        nodes: {
+            [CANVAS_ROOT_ELEMENT_ID]: {
+                $id: CANVAS_ROOT_ELEMENT_ID,
+                componentId: 'div',
+                parentId: null,
+                nodes: [
+                    'heading'
+                ]
+            },
+            heading: {
+                $id: 'heading',
+                componentId: 'muiTypography',
+                parentId: CANVAS_ROOT_ELEMENT_ID,
+                props: {
+                    variant: `h${level}`,
+                    children: text.slice(0, AI_TEXT_LIMITS.headline)
+                },
+                nodes: []
+            }
+        }
+    }, 'screen');
+    if (!result.ok) return null;
+    const root = result.nodes[result.rootId];
+    const node = result.nodes[(_ref = (_root_nodes = root.nodes) == null ? void 0 : _root_nodes[0]) != null ? _ref : ''];
+    const props = (_ref1 = node == null ? void 0 : node['props']) != null ? _ref1 : {};
+    const children = typeof props['children'] === 'string' ? props['children'].trim() : '';
+    return children && node ? {
+        text: children,
+        node
+    } : null;
+}
+const cloneNodes = (nodes)=>JSON.parse(JSON.stringify(nodes));
+/** Apply `fixes` to a copy of `nodes`, whose content region starts at `contentRootId`. */ export function applyAiSeoContentFixes(nodes, fixes, contentRootId) {
+    const copy = cloneNodes(nodes);
+    const applied = [];
+    const skipped = [];
+    const skip = (fix, reason)=>skipped.push({
+            fix,
+            reason
+        });
+    for (const fix of fixes){
+        switch(fix.kind){
+            case 'image-alt':
+                {
+                    var _props_alt;
+                    const node = copy[fix.nodeId];
+                    if (!node || node['componentId'] !== 'image') {
+                        skip(fix, 'The image is no longer on the page.');
+                        break;
+                    }
+                    const props = isRecord(node.props) ? node.props : {};
+                    if (String((_props_alt = props['alt']) != null ? _props_alt : '').trim()) {
+                        skip(fix, 'The image has been given a description since the audit.');
+                        break;
+                    }
+                    const alt = fix.alt.replace(/\s+/g, ' ').trim().slice(0, MEDIA_ALT_MAX_LENGTH);
+                    if (!alt) {
+                        skip(fix, 'The proposed description was empty.');
+                        break;
+                    }
+                    node.props = _extends({}, props, {
+                        alt
+                    });
+                    applied.push(fix);
+                    break;
+                }
+            case 'h1-set':
+            case 'h1-demote':
+                {
+                    const node = copy[fix.nodeId];
+                    const props = node && isRecord(node.props) ? node.props : null;
+                    if (!node || !props || !TEXT_COMPONENTS.has(String(node['componentId']))) {
+                        skip(fix, 'The heading is no longer on the page.');
+                        break;
+                    }
+                    if (typeof props['html'] === 'string' && props['html'].trim()) {
+                        skip(fix, 'The heading is rich text, which a fix does not rewrite.');
+                        break;
+                    }
+                    if (fix.kind === 'h1-demote') {
+                        node.props = _extends({}, props, {
+                            component: 'h2'
+                        });
+                        applied.push(fix);
+                        break;
+                    }
+                    const heading = validatedHeading(1, fix.text);
+                    if (!heading) {
+                        skip(fix, 'The proposed heading could not be used.');
+                        break;
+                    }
+                    node.props = _extends({}, props, {
+                        component: 'h1',
+                        children: heading.text
+                    });
+                    applied.push(fix);
+                    break;
+                }
+            case 'h1-insert':
+                {
+                    const parent = contentRootId ? copy[contentRootId] : undefined;
+                    if (!parent || !contentRootId) {
+                        skip(fix, 'The page has no content region to add a heading to.');
+                        break;
+                    }
+                    const heading = validatedHeading(1, fix.text);
+                    if (!heading) {
+                        skip(fix, 'The proposed heading could not be used.');
+                        break;
+                    }
+                    const id = String(heading.node['$id']);
+                    copy[id] = _extends({}, heading.node, {
+                        parentId: contentRootId,
+                        nodes: []
+                    });
+                    const children = Array.isArray(parent.nodes) ? parent.nodes : [];
+                    parent.nodes = [
+                        id,
+                        ...children
+                    ];
+                    applied.push(fix);
+                    break;
+                }
+        }
+    }
+    return {
+        nodes: copy,
+        applied,
+        skipped
+    };
+}
+
+//# sourceMappingURL=seo-content-fixes.js.map

package/src/lib/runtime/seo-content-fixes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/seo-content-fixes.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 { CANVAS_ROOT_ELEMENT_ID } from '@aglyn/aglyn/foundation/constants/canvas'\nimport type { AiSeoContentFix } from '../model/ai-seo'\nimport { validateAiNodeTree } from './ai-node-tree'\nimport { AI_TEXT_LIMITS } from './ai-palette'\n\n/**\n * A site audit's content fixes, applied to a COPY of a page's node map\n * (AGL-2910). The caller stores the result as a new unpublished version;\n * nothing here reads or writes a document, and the map it is handed is\n * never changed.\n *\n * Each fix is checked against the page as it is now, not as it was audited:\n * an image that has gained a description keeps it, a heading that has gone\n * is skipped, and every skip is named. A heading's new text and a new\n * heading pass the AI node-tree validator — the one path an AI-emitted node\n * takes into storage — before they touch the copy.\n */\n\nexport interface AiSeoContentFixResult {\n  nodes: Record<string, Record<string, unknown>>\n  /** Fixes that changed the copy. */\n  applied: AiSeoContentFix[]\n  /** Fixes that did not, each with the customer-safe reason. */\n  skipped: Array<{ fix: AiSeoContentFix; reason: string }>\n}\n\ntype StoredNode = Record<string, unknown> & { props?: Record<string, unknown>; nodes?: unknown }\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\nconst TEXT_COMPONENTS: ReadonlySet<string> = new Set(['muiTypography', 'muiInlineText', 'muiListItemText'])\n\n/**\n * A heading as the validator would store it: the text held to a headline's\n * length and the element to the palette. `null` when the validator refuses\n * it — the text is not something a generated heading may say.\n */\nfunction validatedHeading(level: 1 | 2, text: string): { text: string; node: Record<string, unknown> } | null {\n  const result = validateAiNodeTree(\n    {\n      rootId: CANVAS_ROOT_ELEMENT_ID,\n      nodes: {\n        [CANVAS_ROOT_ELEMENT_ID]: {\n          $id: CANVAS_ROOT_ELEMENT_ID,\n          componentId: 'div',\n          parentId: null,\n          nodes: ['heading'],\n        },\n        heading: {\n          $id: 'heading',\n          componentId: 'muiTypography',\n          parentId: CANVAS_ROOT_ELEMENT_ID,\n          props: { variant: `h${level}`, children: text.slice(0, AI_TEXT_LIMITS.headline) },\n          nodes: [],\n        },\n      },\n    },\n    'screen',\n  )\n  if (!result.ok) return null\n  const root = result.nodes[result.rootId] as { nodes?: string[] }\n  const node = result.nodes[root.nodes?.[0] ?? ''] as Record<string, unknown> | undefined\n  const props = (node?.['props'] ?? {}) as Record<string, unknown>\n  const children = typeof props['children'] === 'string' ? props['children'].trim() : ''\n  return children && node ? { text: children, node } : null\n}\n\nconst cloneNodes = (nodes: Record<string, unknown>): Record<string, StoredNode> =>\n  JSON.parse(JSON.stringify(nodes)) as Record<string, StoredNode>\n\n/** Apply `fixes` to a copy of `nodes`, whose content region starts at `contentRootId`. */\nexport function applyAiSeoContentFixes(\n  nodes: Record<string, unknown>,\n  fixes: readonly AiSeoContentFix[],\n  contentRootId: string | null,\n): AiSeoContentFixResult {\n  const copy = cloneNodes(nodes)\n  const applied: AiSeoContentFix[] = []\n  const skipped: AiSeoContentFixResult['skipped'] = []\n  const skip = (fix: AiSeoContentFix, reason: string) => skipped.push({ fix, reason })\n\n  for (const fix of fixes) {\n    switch (fix.kind) {\n      case 'image-alt': {\n        const node = copy[fix.nodeId]\n        if (!node || node['componentId'] !== 'image') {\n          skip(fix, 'The image is no longer on the page.')\n          break\n        }\n        const props = isRecord(node.props) ? node.props : {}\n        if (String(props['alt'] ?? '').trim()) {\n          skip(fix, 'The image has been given a description since the audit.')\n          break\n        }\n        const alt = fix.alt.replace(/\\s+/g, ' ').trim().slice(0, MEDIA_ALT_MAX_LENGTH)\n        if (!alt) {\n          skip(fix, 'The proposed description was empty.')\n          break\n        }\n        node.props = { ...props, alt }\n        applied.push(fix)\n        break\n      }\n      case 'h1-set':\n      case 'h1-demote': {\n        const node = copy[fix.nodeId]\n        const props = node && isRecord(node.props) ? node.props : null\n        if (!node || !props || !TEXT_COMPONENTS.has(String(node['componentId']))) {\n          skip(fix, 'The heading is no longer on the page.')\n          break\n        }\n        if (typeof props['html'] === 'string' && props['html'].trim()) {\n          skip(fix, 'The heading is rich text, which a fix does not rewrite.')\n          break\n        }\n        if (fix.kind === 'h1-demote') {\n          node.props = { ...props, component: 'h2' }\n          applied.push(fix)\n          break\n        }\n        const heading = validatedHeading(1, fix.text)\n        if (!heading) {\n          skip(fix, 'The proposed heading could not be used.')\n          break\n        }\n        node.props = { ...props, component: 'h1', children: heading.text }\n        applied.push(fix)\n        break\n      }\n      case 'h1-insert': {\n        const parent = contentRootId ? copy[contentRootId] : undefined\n        if (!parent || !contentRootId) {\n          skip(fix, 'The page has no content region to add a heading to.')\n          break\n        }\n        const heading = validatedHeading(1, fix.text)\n        if (!heading) {\n          skip(fix, 'The proposed heading could not be used.')\n          break\n        }\n        const id = String(heading.node['$id'])\n        copy[id] = { ...heading.node, parentId: contentRootId, nodes: [] }\n        const children = Array.isArray(parent.nodes) ? (parent.nodes as unknown[]) : []\n        parent.nodes = [id, ...children]\n        applied.push(fix)\n        break\n      }\n    }\n  }\n  return { nodes: copy, applied, skipped }\n}\n"],"names":["MEDIA_ALT_MAX_LENGTH","CANVAS_ROOT_ELEMENT_ID","validateAiNodeTree","AI_TEXT_LIMITS","isRecord","value","Array","isArray","TEXT_COMPONENTS","Set","validatedHeading","level","text","root","result","rootId","nodes","$id","componentId","parentId","heading","props","variant","children","slice","headline","ok","node","trim","cloneNodes","JSON","parse","stringify","applyAiSeoContentFixes","fixes","contentRootId","copy","applied","skipped","skip","fix","reason","push","kind","nodeId","String","alt","replace","has","component","parent","undefined","id"],"mappings":"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"}