@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/app-utils/seo-audit.js

@@ -0,0 +1,246 @@
+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 "./seo-listing-fields.js";
+import { seoKeywordCoverage, seoKeywordList } from "./seo-keywords.js";
+/**
+ * The SEO check: every page a site publishes held to what a search result
+ * and a crawler need, and the site held to what a search engine and an agent
+ * read about it. Pure and provider-free — nothing here reads, writes or
+ * generates — so any site owner is told what is wrong, and anything that
+ * proposes a fix answers the same findings rather than judging a page its
+ * own way.
+ *
+ * Per page: a title and a description of its own, within the lengths the
+ * listing editor enforces (`seo-listing-fields.ts`) 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 in `/llms.txt`.
+ *
+ * Keyword coverage is reported, never forced: a page that does not say a
+ * keyword is told so, and told to use it only if the page is about it.
+ *
+ * The pages come from `seo-site-scan.ts`, which reads a site the way its
+ * sitemap lists it.
+ */ /** Pages one check covers. A larger site is checked on its first pages by path, and says how many it left. */ export const SEO_AUDIT_MAX_PAGES = 150;
+/** What each finding is called where it is listed. */ export const SEO_FINDING_LABELS = {
+    'title-missing': 'No search title',
+    'title-too-long': 'Title too long',
+    'title-duplicate': 'Title used on another page',
+    'description-missing': 'No search description',
+    'description-too-long': 'Description too long',
+    'description-duplicate': 'Description used on another page',
+    'h1-missing': 'No main heading',
+    'h1-multiple': 'More than one main heading',
+    'h1-thin': 'Main heading says little',
+    'image-alt-missing': 'Images without a description',
+    orphan: 'No page links here',
+    'keyword-missing': 'Target keyword not covered',
+    'search-discouraged': 'Search engines are discouraged',
+    'entity-incomplete': 'Structured data incomplete',
+    'llms-guidance-missing': 'No guidance for AI agents'
+};
+/** 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'
+]);
+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 seoNormalizePath(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 names no page; a path the site does not publish is
+ * reported by the scan that matches the lines to pages.
+ */ export function parseSeoKeywordLines(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 = seoNormalizePath(line.slice(0, at));
+        const keywords = seoKeywordList(line.slice(at + 1));
+        if (keywords.length) out[path] = seoKeywordList([
+            ...(_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 coverageOf(page) {
+    var _page_facts_h1s_;
+    return seoKeywordCoverage(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
+    });
+}
+function pageFindings(page, titles, descriptions, coverage) {
+    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.'));
+    }
+    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));
+}
+/** Check the pages and the site; nothing here reads, writes or generates. */ export function seoAudit(pages, site, options = {}) {
+    var _options_skipped, _options_notes;
+    const titles = sharedValues(pages, (page)=>page.seo.title);
+    const descriptions = sharedValues(pages, (page)=>page.seo.description);
+    const reports = pages.map((page)=>{
+        const keywords = coverageOf(page);
+        const findings = pageFindings(page, titles, descriptions, keywords);
+        return {
+            screenId: page.screenId,
+            path: page.path,
+            name: page.name,
+            versionId: page.versionId,
+            score: scoreOf(findings),
+            findings,
+            keywords
+        };
+    });
+    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.'));
+    }
+    return {
+        pages: reports,
+        skipped: Math.max(0, (_options_skipped = options.skipped) != null ? _options_skipped : 0),
+        site: siteFindings,
+        score: reports.length ? Math.round(reports.reduce((sum, report)=>sum + report.score, 0) / reports.length) : 100,
+        notes: [
+            ...(_options_notes = options.notes) != null ? _options_notes : []
+        ]
+    };
+}
+/** How many findings a report holds, the site's included. */ export function seoAuditFindingCount(report) {
+    return report.pages.reduce((sum, page)=>sum + page.findings.length, report.site.length);
+}
+
+//# sourceMappingURL=seo-audit.js.map

package/src/lib/app-utils/seo-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/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 { SEO_LISTING_FIELDS, seoListingFieldTooLong } from './seo-listing-fields'\nimport { seoKeywordCoverage, seoKeywordList, type SeoKeywordCoverage } from './seo-keywords'\nimport type { SeoPageFacts } from './seo-page-facts'\n\n/**\n * The SEO check: every page a site publishes held to what a search result\n * and a crawler need, and the site held to what a search engine and an agent\n * read about it. Pure and provider-free — nothing here reads, writes or\n * generates — so any site owner is told what is wrong, and anything that\n * proposes a fix answers the same findings rather than judging a page its\n * own way.\n *\n * Per page: a title and a description of its own, within the lengths the\n * listing editor enforces (`seo-listing-fields.ts`) and used on no other\n * page; one main heading that says something; a description on every image;\n * a link from somewhere else on the site; and the target keywords a person\n * 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 in `/llms.txt`.\n *\n * Keyword coverage is reported, never forced: a page that does not say a\n * keyword is told so, and told to use it only if the page is about it.\n *\n * The pages come from `seo-site-scan.ts`, which reads a site the way its\n * sitemap lists it.\n */\n\n/** Pages one check covers. A larger site is checked on its first pages by path, and says how many it left. */\nexport const SEO_AUDIT_MAX_PAGES = 150\n\nexport type SeoFindingCode =\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-multiple'\n  | 'h1-thin'\n  | 'image-alt-missing'\n  | 'orphan'\n  | 'keyword-missing'\n  | 'search-discouraged'\n  | 'entity-incomplete'\n  | 'llms-guidance-missing'\n\nexport type SeoSeverity = 'high' | 'medium' | 'low'\n\nexport interface SeoFinding {\n  code: SeoFindingCode\n  severity: SeoSeverity\n  /** One customer-safe sentence. */\n  message: string\n  /** The elements it is about: the images without a description, the extra headings. */\n  nodeIds?: string[]\n  /** The other pages it involves: a duplicate's twins. */\n  screenIds?: string[]\n  /** The target keyword, for `keyword-missing`. */\n  keyword?: string\n}\n\n/** One checked page. */\nexport interface SeoPageReport {\n  screenId: string\n  /** The public path, `/` for the home page. */\n  path: string\n  name: string\n  /** The published version the page was checked on. */\n  versionId: string | null\n  /** 100 with nothing found, less for each finding by its severity. */\n  score: number\n  findings: SeoFinding[]\n  keywords: SeoKeywordCoverage[]\n}\n\n/** The check of a site: every checked page, and what was found about the site itself. */\nexport interface SeoAuditReport {\n  pages: SeoPageReport[]\n  /** Published pages past {@link SEO_AUDIT_MAX_PAGES}, not checked. */\n  skipped: number\n  /** Findings about the site rather than a page. */\n  site: SeoFinding[]\n  /** The average page score. */\n  score: number\n  /** Customer-safe lines about the check itself: a keyword line naming no page, say. */\n  notes: string[]\n}\n\n/** What each finding is called where it is listed. */\nexport const SEO_FINDING_LABELS: Readonly<Record<SeoFindingCode, string>> = {\n  'title-missing': 'No search title',\n  'title-too-long': 'Title too long',\n  'title-duplicate': 'Title used on another page',\n  'description-missing': 'No search description',\n  'description-too-long': 'Description too long',\n  'description-duplicate': 'Description used on another page',\n  'h1-missing': 'No main heading',\n  'h1-multiple': 'More than one main heading',\n  'h1-thin': 'Main heading says little',\n  'image-alt-missing': 'Images without a description',\n  orphan: 'No page links here',\n  'keyword-missing': 'Target keyword not covered',\n  'search-discouraged': 'Search engines are discouraged',\n  'entity-incomplete': 'Structured data incomplete',\n  'llms-guidance-missing': 'No guidance for AI agents',\n}\n\n/** What each severity takes off a page's score. */\nconst SEVERITY_WEIGHT: Record<SeoSeverity, 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/** One page as the check reads it. */\nexport interface SeoAuditPage {\n  screenId: string\n  /** The public path, `/` for the home page. */\n  path: string\n  name: string\n  versionId: string | null\n  /** The listing as the page's head renders it: a title's variables already resolved. */\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: SeoPageFacts\n  /** Whether another checked page or a shared layout links here. */\n  linkedFrom: boolean\n  keywords: readonly string[]\n}\n\n/** The site as the check reads it. */\nexport interface SeoAuditSite {\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 seoNormalizePath(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 names no page; a path the site does not publish is\n * reported by the scan that matches the lines to pages.\n */\nexport function parseSeoKeywordLines(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 = seoNormalizePath(line.slice(0, at))\n    const keywords = seoKeywordList(line.slice(at + 1))\n    if (keywords.length) out[path] = seoKeywordList([...(out[path] ?? []), ...keywords])\n  }\n  return out\n}\n\nfunction finding(\n  code: SeoFindingCode,\n  severity: SeoSeverity,\n  message: string,\n  extra: Partial<Pick<SeoFinding, 'nodeIds' | 'screenIds' | 'keyword'>> = {},\n): SeoFinding {\n  return { code, severity, message, ...extra }\n}\n\n/** The pages that share one value, by that value. */\nfunction sharedValues(\n  pages: readonly SeoAuditPage[],\n  read: (page: SeoAuditPage) => 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 coverageOf(page: SeoAuditPage): SeoKeywordCoverage[] {\n  return seoKeywordCoverage(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\nfunction pageFindings(\n  page: SeoAuditPage,\n  titles: Map<string, string[]>,\n  descriptions: Map<string, string[]>,\n  coverage: readonly SeoKeywordCoverage[],\n): SeoFinding[] {\n  const out: SeoFinding[] = []\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  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 SeoFinding[]): number {\n  return Math.max(0, 100 - findings.reduce((sum, entry) => sum + SEVERITY_WEIGHT[entry.severity], 0))\n}\n\n/** Check the pages and the site; nothing here reads, writes or generates. */\nexport function seoAudit(\n  pages: readonly SeoAuditPage[],\n  site: SeoAuditSite,\n  options: { skipped?: number; notes?: readonly string[] } = {},\n): SeoAuditReport {\n  const titles = sharedValues(pages, (page) => page.seo.title)\n  const descriptions = sharedValues(pages, (page) => page.seo.description)\n  const reports: SeoPageReport[] = pages.map((page) => {\n    const keywords = coverageOf(page)\n    const findings = pageFindings(page, titles, descriptions, keywords)\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,\n    }\n  })\n\n  const siteFindings: SeoFinding[] = []\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  return {\n    pages: reports,\n    skipped: Math.max(0, options.skipped ?? 0),\n    site: siteFindings,\n    score: reports.length\n      ? Math.round(reports.reduce((sum, report) => sum + report.score, 0) / reports.length)\n      : 100,\n    notes: [...(options.notes ?? [])],\n  }\n}\n\n/** How many findings a report holds, the site's included. */\nexport function seoAuditFindingCount(report: Pick<SeoAuditReport, 'pages' | 'site'>): number {\n  return report.pages.reduce((sum, page) => sum + page.findings.length, report.site.length)\n}\n"],"names":["SEO_LISTING_FIELDS","seoListingFieldTooLong","seoKeywordCoverage","seoKeywordList","SEO_AUDIT_MAX_PAGES","SEO_FINDING_LABELS","orphan","SEVERITY_WEIGHT","high","medium","low","THIN_H1_MIN_CHARS","GENERIC_H1","Set","blank","value","String","trim","normalized","replace","toLowerCase","seoNormalizePath","path","trimmed","parseSeoKeywordLines","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","coverageOf","title","seo","description","h1","facts","h1s","text","body","pageFindings","titles","descriptions","coverage","push","maxLength","twins","id","screenIds","nodeIds","map","heading","nodeId","Boolean","first","has","missingAlt","imagesMissingAlt","image","linkedFrom","entry","inTitle","inDescription","inH1","inBody","keyword","scoreOf","findings","Math","max","reduce","sum","seoAudit","site","options","reports","name","versionId","score","siteFindings","discouraged","entity","agent","whenToUse","skipped","round","report","notes","seoAuditFindingCount"],"mappings":"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"}

package/src/lib/app-utils/seo-keywords.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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.
+ */
+/**
+ * Target keywords: the words a site owner wants a page found for, and where
+ * the page already says them.
+ *
+ * The SEO check (`seo-audit.ts`) reports a keyword a page never says, and
+ * anything that writes a listing holds its answer to the same count, so
+ * "the page says it" means one thing everywhere: the keyword as whole words,
+ * in any case, never inside a longer word.
+ */
+/** Target keywords one page may name. */
+export declare const SEO_MAX_KEYWORDS = 5;
+/** The longest target keyword text a site's lines run to: a line a page, for a large site. */
+export declare const SEO_KEYWORD_LINES_MAX_CHARS = 3000;
+/** Whether, and where, a page already says a target keyword. */
+export interface SeoKeywordCoverage {
+    keyword: string;
+    inTitle: boolean;
+    inDescription: boolean;
+    inH1: boolean;
+    inBody: boolean;
+}
+/** How many times `keyword` appears in `text` as whole words, any case. */
+export declare function seoKeywordCount(text: string | null | undefined, keyword: string): number;
+/** Keywords as a person typed them: trimmed, deduplicated, capped at {@link SEO_MAX_KEYWORDS}. */
+export declare function seoKeywordList(raw: unknown): string[];
+/** Where a page already says each target keyword. */
+export declare function seoKeywordCoverage(keywords: readonly string[], sources: {
+    title?: string | null;
+    description?: string | null;
+    h1?: string | null;
+    body?: string | null;
+}): SeoKeywordCoverage[];

package/src/lib/app-utils/seo-keywords.js

@@ -0,0 +1,60 @@
+/**
+ * @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.
+ */ /**
+ * Target keywords: the words a site owner wants a page found for, and where
+ * the page already says them.
+ *
+ * The SEO check (`seo-audit.ts`) reports a keyword a page never says, and
+ * anything that writes a listing holds its answer to the same count, so
+ * "the page says it" means one thing everywhere: the keyword as whole words,
+ * in any case, never inside a longer word.
+ */ /** Target keywords one page may name. */ export const SEO_MAX_KEYWORDS = 5;
+/** The longest target keyword text a site's lines run to: a line a page, for a large site. */ export const SEO_KEYWORD_LINES_MAX_CHARS = 3000;
+/** The longest one keyword is kept. */ const SEO_KEYWORD_MAX_CHARS = 60;
+const escapeRegExp = (value)=>value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** How many times `keyword` appears in `text` as whole words, any case. */ export function seoKeywordCount(text, keyword) {
+    const needle = keyword.trim().toLowerCase();
+    if (!needle || !text) return 0;
+    const pattern = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRegExp(needle).replace(/\s+/g, '\\s+')}(?=$|[^\\p{L}\\p{N}])`, 'giu');
+    return [
+        ...text.toLowerCase().matchAll(pattern)
+    ].length;
+}
+/** Keywords as a person typed them: trimmed, deduplicated, capped at {@link SEO_MAX_KEYWORDS}. */ export function seoKeywordList(raw) {
+    const parts = Array.isArray(raw) ? raw.map(String) : String(raw != null ? raw : '').split(/[,\n]/);
+    const seen = new Set();
+    const out = [];
+    for (const part of parts){
+        const keyword = part.replace(/\s+/g, ' ').trim().slice(0, SEO_KEYWORD_MAX_CHARS);
+        const key = keyword.toLowerCase();
+        if (!keyword || seen.has(key)) continue;
+        seen.add(key);
+        out.push(keyword);
+        if (out.length >= SEO_MAX_KEYWORDS) break;
+    }
+    return out;
+}
+/** Where a page already says each target keyword. */ export function seoKeywordCoverage(keywords, sources) {
+    return keywords.map((keyword)=>({
+            keyword,
+            inTitle: seoKeywordCount(sources.title, keyword) > 0,
+            inDescription: seoKeywordCount(sources.description, keyword) > 0,
+            inH1: seoKeywordCount(sources.h1, keyword) > 0,
+            inBody: seoKeywordCount(sources.body, keyword) > 0
+        }));
+}
+
+//# sourceMappingURL=seo-keywords.js.map

package/src/lib/app-utils/seo-keywords.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/seo-keywords.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\n/**\n * Target keywords: the words a site owner wants a page found for, and where\n * the page already says them.\n *\n * The SEO check (`seo-audit.ts`) reports a keyword a page never says, and\n * anything that writes a listing holds its answer to the same count, so\n * \"the page says it\" means one thing everywhere: the keyword as whole words,\n * in any case, never inside a longer word.\n */\n\n/** Target keywords one page may name. */\nexport const SEO_MAX_KEYWORDS = 5\n\n/** The longest target keyword text a site's lines run to: a line a page, for a large site. */\nexport const SEO_KEYWORD_LINES_MAX_CHARS = 3_000\n\n/** The longest one keyword is kept. */\nconst SEO_KEYWORD_MAX_CHARS = 60\n\n/** Whether, and where, a page already says a target keyword. */\nexport interface SeoKeywordCoverage {\n  keyword: string\n  inTitle: boolean\n  inDescription: boolean\n  inH1: boolean\n  inBody: boolean\n}\n\nconst escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n\n/** How many times `keyword` appears in `text` as whole words, any case. */\nexport function seoKeywordCount(text: string | null | undefined, keyword: string): number {\n  const needle = keyword.trim().toLowerCase()\n  if (!needle || !text) return 0\n  const pattern = new RegExp(\n    `(^|[^\\\\p{L}\\\\p{N}])${escapeRegExp(needle).replace(/\\s+/g, '\\\\s+')}(?=$|[^\\\\p{L}\\\\p{N}])`,\n    'giu',\n  )\n  return [...text.toLowerCase().matchAll(pattern)].length\n}\n\n/** Keywords as a person typed them: trimmed, deduplicated, capped at {@link SEO_MAX_KEYWORDS}. */\nexport function seoKeywordList(raw: unknown): string[] {\n  const parts = Array.isArray(raw) ? raw.map(String) : String(raw ?? '').split(/[,\\n]/)\n  const seen = new Set<string>()\n  const out: string[] = []\n  for (const part of parts) {\n    const keyword = part.replace(/\\s+/g, ' ').trim().slice(0, SEO_KEYWORD_MAX_CHARS)\n    const key = keyword.toLowerCase()\n    if (!keyword || seen.has(key)) continue\n    seen.add(key)\n    out.push(keyword)\n    if (out.length >= SEO_MAX_KEYWORDS) break\n  }\n  return out\n}\n\n/** Where a page already says each target keyword. */\nexport function seoKeywordCoverage(\n  keywords: readonly string[],\n  sources: { title?: string | null; description?: string | null; h1?: string | null; body?: string | null },\n): SeoKeywordCoverage[] {\n  return keywords.map((keyword) => ({\n    keyword,\n    inTitle: seoKeywordCount(sources.title, keyword) > 0,\n    inDescription: seoKeywordCount(sources.description, keyword) > 0,\n    inH1: seoKeywordCount(sources.h1, keyword) > 0,\n    inBody: seoKeywordCount(sources.body, keyword) > 0,\n  }))\n}\n"],"names":["SEO_MAX_KEYWORDS","SEO_KEYWORD_LINES_MAX_CHARS","SEO_KEYWORD_MAX_CHARS","escapeRegExp","value","replace","seoKeywordCount","text","keyword","needle","trim","toLowerCase","pattern","RegExp","matchAll","length","seoKeywordList","raw","parts","Array","isArray","map","String","split","seen","Set","out","part","slice","key","has","add","push","seoKeywordCoverage","keywords","sources","inTitle","title","inDescription","description","inH1","h1","inBody","body"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GAED,uCAAuC,GACvC,OAAO,MAAMA,mBAAmB,EAAC;AAEjC,4FAA4F,GAC5F,OAAO,MAAMC,8BAA8B,KAAK;AAEhD,qCAAqC,GACrC,MAAMC,wBAAwB;AAW9B,MAAMC,eAAe,CAACC,QAA0BA,MAAMC,OAAO,CAAC,uBAAuB;AAErF,yEAAyE,GACzE,OAAO,SAASC,gBAAgBC,IAA+B,EAAEC,OAAe;IAC9E,MAAMC,SAASD,QAAQE,IAAI,GAAGC,WAAW;IACzC,IAAI,CAACF,UAAU,CAACF,MAAM,OAAO;IAC7B,MAAMK,UAAU,IAAIC,OAClB,CAAC,mBAAmB,EAAEV,aAAaM,QAAQJ,OAAO,CAAC,QAAQ,QAAQ,qBAAqB,CAAC,EACzF;IAEF,OAAO;WAAIE,KAAKI,WAAW,GAAGG,QAAQ,CAACF;KAAS,CAACG,MAAM;AACzD;AAEA,gGAAgG,GAChG,OAAO,SAASC,eAAeC,GAAY;IACzC,MAAMC,QAAQC,MAAMC,OAAO,CAACH,OAAOA,IAAII,GAAG,CAACC,UAAUA,OAAOL,cAAAA,MAAO,IAAIM,KAAK,CAAC;IAC7E,MAAMC,OAAO,IAAIC;IACjB,MAAMC,MAAgB,EAAE;IACxB,KAAK,MAAMC,QAAQT,MAAO;QACxB,MAAMV,UAAUmB,KAAKtB,OAAO,CAAC,QAAQ,KAAKK,IAAI,GAAGkB,KAAK,CAAC,GAAG1B;QAC1D,MAAM2B,MAAMrB,QAAQG,WAAW;QAC/B,IAAI,CAACH,WAAWgB,KAAKM,GAAG,CAACD,MAAM;QAC/BL,KAAKO,GAAG,CAACF;QACTH,IAAIM,IAAI,CAACxB;QACT,IAAIkB,IAAIX,MAAM,IAAIf,kBAAkB;IACtC;IACA,OAAO0B;AACT;AAEA,mDAAmD,GACnD,OAAO,SAASO,mBACdC,QAA2B,EAC3BC,OAAyG;IAEzG,OAAOD,SAASb,GAAG,CAAC,CAACb,UAAa,CAAA;YAChCA;YACA4B,SAAS9B,gBAAgB6B,QAAQE,KAAK,EAAE7B,WAAW;YACnD8B,eAAehC,gBAAgB6B,QAAQI,WAAW,EAAE/B,WAAW;YAC/DgC,MAAMlC,gBAAgB6B,QAAQM,EAAE,EAAEjC,WAAW;YAC7CkC,QAAQpC,gBAAgB6B,QAAQQ,IAAI,EAAEnC,WAAW;QACnD,CAAA;AACF"}

package/src/lib/app-utils/seo-page-facts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 './page-markdown';
+/**
+ * What a page SAYS, read off its node tree (AGL-2910): the text a search
+ * listing summarizes, the headings, and the images — each heading and image
+ * by node id, so a finding can name the element it is about and a fix can
+ * address the element it changes.
+ *
+ * Pure, and the platform's: the SEO check (`seo-audit.ts`) judges a page by
+ * these facts, and anything that proposes a listing or a content fix reads
+ * the same ones rather than walking the tree its own way.
+ *
+ * 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 the facts carry. A listing summarizes; it does not need the page. */
+export declare const SEO_PAGE_TEXT_MAX_CHARS = 2000;
+export interface SeoHeading {
+    /** 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 SeoImage {
+    nodeId: string;
+    src: string;
+    alt: string;
+    /** The nearest heading or text before it, which is what the image illustrates. */
+    context: string;
+}
+export interface SeoPageFacts {
+    /** The page's Markdown body, capped. */
+    text: string;
+    wordCount: number;
+    headings: SeoHeading[];
+    h1s: SeoHeading[];
+    images: SeoImage[];
+    imagesMissingAlt: SeoImage[];
+    /** The node the content region starts at; a new heading goes first inside it. */
+    contentRootId: string | null;
+}
+/** Read the facts a listing and the SEO check need from one page's node map. */
+export declare function seoPageFacts(nodes: PageMarkdownNodes | null | undefined, options?: {
+    rootId?: string;
+    maxChars?: number;
+}): SeoPageFacts;

package/src/lib/app-utils/seo-page-facts.js

@@ -0,0 +1,155 @@
+/**
+ * @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 "./page-markdown.js";
+/**
+ * What a page SAYS, read off its node tree (AGL-2910): the text a search
+ * listing summarizes, the headings, and the images — each heading and image
+ * by node id, so a finding can name the element it is about and a fix can
+ * address the element it changes.
+ *
+ * Pure, and the platform's: the SEO check (`seo-audit.ts`) judges a page by
+ * these facts, and anything that proposes a listing or a content fix reads
+ * the same ones rather than walking the tree its own way.
+ *
+ * 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 the facts carry. A listing summarizes; it does not need the page. */ export const 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 the SEO check need from one page's node map. */ export function seoPageFacts(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 : 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