@svelte-vitals/core 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -115,6 +115,12 @@ interface HeadTag {
     hasCrossorigin?: boolean;
     /** True when a <meta name="robots"> literal content contains `noindex`/`none`. Undefined when dynamic or absent. */
     noindex?: boolean;
+    /** Literal `<script type="application/ld+json">` content, set only when the script is static. Undefined when dynamic. */
+    jsonld?: string;
+    /** Literal visible text of a static <title> or <meta name="description"> content, set only when static. Undefined when dynamic. */
+    text?: string;
+    /** Literal `hreflang` of a `<link rel="alternate">` (e.g. 'en', 'en-US', 'x-default'). Undefined when dynamic/absent. */
+    hreflang?: string;
     /** Where this tag was set relative to the route. Never 'none' (absence = no tag). */
     presence: Exclude<Presence, 'none'>;
     /** Whether the tag's value is static/dynamic/absent (design §4). */
@@ -152,6 +158,8 @@ interface ImageInfo {
     hasWidth: boolean;
     hasHeight: boolean;
     hasLoading: boolean;
+    /** True when the <img> has an `alt` attribute at all (incl. empty `alt=""` decorative; SEO025). */
+    hasAlt: boolean;
     /** 1-based source line, or 0 if unknown. */
     line: number;
     /** Source file the <img> came from. */
@@ -163,6 +171,25 @@ interface ResolvedImages {
     images: ImageInfo[];
 }
 
+/**
+ * A normalized page-body heading occurrence — the mode-independent boundary for
+ * the heading-hierarchy rule (mirrors images.ts). Both providers collect these
+ * so SEO027 never needs to know which mode produced them.
+ */
+interface HeadingInfo {
+    /** Heading level 1–6 (the `n` in <hn>). */
+    level: number;
+    /** 1-based source line, or 0 if unknown (rendered mode does not track lines). */
+    line: number;
+    /** Source file the heading came from. */
+    file: string;
+}
+/** Resolved page-body headings for a single route (page + layout chain). */
+interface ResolvedHeadings {
+    route: string;
+    headings: HeadingInfo[];
+}
+
 /**
  * Source-file locations that satisfy the project-scope rules, shared by every
  * mode so the static (CLI) and rendered (plugin) collectors never drift. This
@@ -178,6 +205,8 @@ interface RuleContext {
     heads: ResolvedHead[];
     /** Per-route <img> elements for Performance rules (absent in modes that don't collect them). */
     images?: ResolvedImages[];
+    /** Per-route page-body headings for SEO027 (absent in modes that don't collect them). */
+    headings?: ResolvedHeadings[];
     project: Project;
     config: Config;
 }
@@ -249,6 +278,47 @@ declare const seo013OgUrl: Rule;
 declare const seo014Viewport: Rule;
 declare const seo015SitemapInRobots: Rule;
 
+declare const seo016JsonLdValidity: Rule;
+declare const seo017DeprecatedType: Rule;
+declare const seo018RelativeUrl: Rule;
+declare const seo019DateFormat: Rule;
+declare const seo020Placeholder: Rule;
+declare const seo021RequiredProps: Rule;
+
+declare const seo022TitleLength: Rule;
+declare const seo023DescriptionLength: Rule;
+
+/**
+ * SEO024 — Character encoding. The charset meta lives in `src/app.html`, so it is
+ * only visible to rendered analysis (`appliesTo: rendered`), exactly like SEO014
+ * (viewport). Static route analysis emits nothing instead of false-flagging it.
+ */
+declare const seo024Charset: Rule;
+
+/**
+ * SEO025 — Image alt text. Reuses the <img> collection (CLI/static only; rendered
+ * mode does not collect images, so the rule no-ops there, like PERF001/002).
+ * Presence only: an explicit empty `alt=""` is a valid decorative-image signal and
+ * passes; a spread `{...rest}` may supply alt, so it is not flagged.
+ */
+declare const seo025ImageAlt: Rule;
+
+/**
+ * SEO026 — hreflang / x-default validity. Opt-in: a route with no
+ * `<link rel="alternate" hreflang>` emits nothing (monolingual sites are never
+ * flagged). When alternates exist, every code must be well-formed and a set of
+ * two or more must declare an x-default. Works in both modes.
+ */
+declare const seo026Hreflang: Rule;
+
+/**
+ * SEO027 — Heading hierarchy (single H1). Reads the per-route page-body headings
+ * channel (collected by both providers). Zero <h1> (no primary heading) and two
+ * or more (diluted topic) are both flagged; exactly one passes. A route whose
+ * headings were not collected (channel unset) emits nothing.
+ */
+declare const seo027Heading: Rule;
+
 declare const allRules: Rule[];
 
 interface RuleInfo {
@@ -291,6 +361,8 @@ interface ImageRuleOptions {
     id: string;
     title: string;
     severity: Severity;
+    /** Vitals category (default 'performance'); SEO025 (alt text) reports under 'seo'. */
+    category?: Category;
     /** Noun phrase for messages, e.g. '<img> width/height'. */
     label: string;
     recommendation: string;
@@ -299,7 +371,7 @@ interface ImageRuleOptions {
     /** Returns true when the image satisfies the rule (passes). */
     ok: (img: ImageInfo) => boolean;
 }
-/** Build a route-scoped Performance rule that checks each <img> against `ok` (issue #10). */
+/** Build a route-scoped <img> rule that checks each image against `ok` (issue #10). */
 declare function imageRule(opts: ImageRuleOptions): Rule;
 
 interface LinkRuleOptions {
@@ -455,4 +527,4 @@ declare function selectRules(rules: Rule[], config: Config): Rule[];
 /** Apply per-rule severity overrides to results (design §6). */
 declare function applyRuleSeverities(results: Result[], config: Config): Result[];
 
-export { BAND_COLOR, type Category, type Classification, type Config, type ConsoleReportOptions, type Detection, type Fix, type HeadProvider, type HeadTag, type HealthResult, type ImageInfo, type JsonReport, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedImages, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, buildHtmlDocument, buildJsonReport, classify, computeHealth, computeScore, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, escapeHtml, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, linkRule, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, runRules, safeHref, scoreBand, scoresByCategory, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, summarize };
+export { BAND_COLOR, type Category, type Classification, type Config, type ConsoleReportOptions, type Detection, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type Rule, type RuleContext, type RuleInfo, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type Summary, type TreatDynamicAs, type Value, allRules, applyRuleSeverities, buildHtmlDocument, buildJsonReport, classify, computeHealth, computeScore, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, escapeHtml, explainRule, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, linkRule, perf001ImageDimensions, perf002ImageLoading, perf003PreloadAs, perf004FontPreloadCrossorigin, runRules, safeHref, scoreBand, scoresByCategory, selectRules, seo001Title, seo002Description, seo003Canonical, seo004OgImage, seo005OgTitle, seo006Robots, seo007Sitemap, seo008JsonLd, seo009HtmlLang, seo010Indexability, seo011TwitterCard, seo012OgDescription, seo013OgUrl, seo014Viewport, seo015SitemapInRobots, seo016JsonLdValidity, seo017DeprecatedType, seo018RelativeUrl, seo019DateFormat, seo020Placeholder, seo021RequiredProps, seo022TitleLength, seo023DescriptionLength, seo024Charset, seo025ImageAlt, seo026Hreflang, seo027Heading, summarize };

package/dist/index.js

@@ -94,7 +94,7 @@ function detect(head, match) {
   return tag ? { presence: tag.presence, value: tag.value } : { presence: "none", value: "absent" };
 }
 function headTagRule(opts) {
-  const docsUrl = docsUrlFor(opts.id);
+  const docsUrl3 = docsUrlFor(opts.id);
   return {
     id: opts.id,
     title: opts.title,
@@ -117,7 +117,7 @@ function headTagRule(opts) {
           location: head.file,
           message,
           recommendation: opts.recommendation,
-          docsUrl,
+          docsUrl: docsUrl3,
           // Copy per finding: opts.fix is a rule-level template shared across all
           // results this rule emits; a fresh object keeps findings independent.
           ...opts.fix ? { fix: { ...opts.fix } } : {}
@@ -296,11 +296,12 @@ var seo009HtmlLang = {
 
 // src/rules/perf/image-rule.ts
 function imageRule(opts) {
-  const docsUrl = docsUrlFor(opts.id);
+  const docsUrl3 = docsUrlFor(opts.id);
+  const category = opts.category ?? "performance";
   return {
     id: opts.id,
     title: opts.title,
-    category: "performance",
+    category,
     severity: opts.severity,
     scope: "route",
     rationale: opts.rationale,
@@ -313,20 +314,20 @@ function imageRule(opts) {
         if (bad.length === 0) {
           out.push({
             id: opts.id,
-            category: "performance",
+            category,
             severity: opts.severity,
             detection: { presence: "own", value: "static" },
             route: route.route,
             message: opts.label,
             recommendation: opts.recommendation,
-            docsUrl
+            docsUrl: docsUrl3
           });
           continue;
         }
         for (const img of bad) {
           out.push({
             id: opts.id,
-            category: "performance",
+            category,
             severity: opts.severity,
             detection: { presence: "none", value: "absent" },
             route: route.route,
@@ -334,7 +335,7 @@ function imageRule(opts) {
             ...img.line > 0 ? { line: img.line } : {},
             message: `Missing ${opts.label}`,
             recommendation: opts.recommendation,
-            docsUrl,
+            docsUrl: docsUrl3,
             ...opts.fix ? { fix: { ...opts.fix } } : {}
           });
         }
@@ -376,7 +377,7 @@ var perf002ImageLoading = imageRule({
 
 // src/rules/perf/link-rule.ts
 function linkRule(opts) {
-  const docsUrl = docsUrlFor(opts.id);
+  const docsUrl3 = docsUrlFor(opts.id);
   return {
     id: opts.id,
     title: opts.title,
@@ -400,7 +401,7 @@ function linkRule(opts) {
             route: head.route,
             message: opts.label,
             recommendation: opts.recommendation,
-            docsUrl
+            docsUrl: docsUrl3
           });
           continue;
         }
@@ -417,7 +418,7 @@ function linkRule(opts) {
             location: tag.file ?? head.file,
             message: `Missing ${opts.label}`,
             recommendation: opts.recommendation,
-            docsUrl,
+            docsUrl: docsUrl3,
             ...opts.fix ? { fix: { ...opts.fix } } : {}
           });
         }
@@ -474,7 +475,7 @@ var seo010Indexability = {
   rationale: "A noindex directive removes the page from search results; an accidental noindex on a public route silently deindexes it.",
   fix: SEO010_FIX,
   async check(ctx) {
-    const docsUrl = docsUrlFor("SEO010");
+    const docsUrl3 = docsUrlFor("SEO010");
     const out = [];
     for (const head of ctx.heads) {
       const noindexed = head.tags.some((t) => t.kind === "meta" && t.name === "robots" && t.noindex === true);
@@ -489,7 +490,7 @@ var seo010Indexability = {
         location: head.file,
         message: "Route is noindex \u2014 verify this is intentional",
         recommendation: 'If this route should be indexed, remove noindex from its <meta name="robots">.',
-        docsUrl,
+        docsUrl: docsUrl3,
         fix: { ...SEO010_FIX }
       });
     }
@@ -587,6 +588,549 @@ var seo015SitemapInRobots = {
   }
 };
 
+// src/rules/seo/jsonld-engine.ts
+function parseJsonLd(raw) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return { ok: false, nodes: [] };
+  }
+  const nodes = [];
+  const visit = (v) => {
+    if (Array.isArray(v)) {
+      v.forEach(visit);
+      return;
+    }
+    if (v && typeof v === "object") {
+      const o = v;
+      nodes.push(o);
+      if (Array.isArray(o["@graph"])) o["@graph"].forEach(visit);
+    }
+  };
+  visit(data);
+  return { ok: true, nodes };
+}
+function typeOf(node) {
+  const t = node["@type"];
+  if (typeof t === "string") return [t];
+  if (Array.isArray(t)) return t.filter((x) => typeof x === "string");
+  return [];
+}
+function collectValues(nodes, keys) {
+  const out = [];
+  const walk = (v) => {
+    if (Array.isArray(v)) {
+      v.forEach(walk);
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const [k, val] of Object.entries(v)) {
+        if (keys.has(k) && typeof val === "string") out.push(val);
+        else if (keys.has(k) && Array.isArray(val)) {
+          for (const e of val) if (typeof e === "string") out.push(e);
+        }
+        walk(val);
+      }
+    }
+  };
+  nodes.forEach(walk);
+  return out;
+}
+function nodeStringValues(node) {
+  const out = [];
+  const walk = (v) => {
+    if (typeof v === "string") {
+      out.push(v);
+      return;
+    }
+    if (Array.isArray(v)) {
+      v.forEach(walk);
+      return;
+    }
+    if (v && typeof v === "object") Object.values(v).forEach(walk);
+  };
+  walk(node);
+  return out;
+}
+function isAbsoluteUrl(s) {
+  const str = s.trim();
+  return /^[a-z][a-z0-9+.-]*:/i.test(str) || str.startsWith("//");
+}
+function isIso8601(s) {
+  const str = s.trim();
+  if (!/^\d{4}(-\d{2}(-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?)?)?$/.test(str)) return false;
+  const y = Number(str.slice(0, 4));
+  const hasMonth = str.length >= 7;
+  const hasDay = str.length >= 10;
+  const m = hasMonth ? Number(str.slice(5, 7)) : 1;
+  if (m < 1 || m > 12) return false;
+  if (hasDay) {
+    const d = Number(str.slice(8, 10));
+    const dt = new Date(Date.UTC(y, m - 1, d));
+    if (dt.getUTCFullYear() !== y || dt.getUTCMonth() !== m - 1 || dt.getUTCDate() !== d) return false;
+  }
+  const tm = /^\d{4}-\d{2}-\d{2}T(\d{2}):(\d{2})(?::(\d{2}))?/.exec(str);
+  if (tm) {
+    const [hh, mm, ss] = [Number(tm[1]), Number(tm[2]), tm[3] !== void 0 ? Number(tm[3]) : 0];
+    if (hh > 23 || mm > 59 || ss > 59) return false;
+  }
+  return true;
+}
+var PLACEHOLDER_RES = [
+  /lorem ipsum/i,
+  /your company/i,
+  /your-?domain/i,
+  /example company/i,
+  /yourcompany/i,
+  /your name here/i
+];
+var PLACEHOLDERS = PLACEHOLDER_RES.map((r) => r.source);
+function hasPlaceholder(s) {
+  return PLACEHOLDER_RES.some((re) => re.test(s));
+}
+var URL_KEYS = /* @__PURE__ */ new Set(["url", "image", "logo", "sameAs", "contentUrl", "thumbnailUrl"]);
+var DATE_KEYS = /* @__PURE__ */ new Set([
+  "datePublished",
+  "dateModified",
+  "dateCreated",
+  "startDate",
+  "endDate",
+  "uploadDate",
+  "validFrom",
+  "expires"
+]);
+var DEPRECATED_TYPES = /* @__PURE__ */ new Set(["HowTo", "FAQPage", "ClaimReview"]);
+function hasNonEmpty(node, key) {
+  if (!(key in node)) return false;
+  const v = node[key];
+  if (v === null || v === void 0) return false;
+  if (typeof v === "string") return v.trim().length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  return true;
+}
+var REQUIRED_PROPS = {
+  Article: ["headline"],
+  BlogPosting: ["headline"],
+  NewsArticle: ["headline"],
+  Product: ["name", "offers"],
+  BreadcrumbList: ["itemListElement"],
+  Organization: ["name", "url"],
+  WebSite: ["name", "url"],
+  Event: ["name", "startDate", "location"],
+  Recipe: ["name", "image", "recipeIngredient", "recipeInstructions"],
+  Person: ["name"],
+  VideoObject: ["name", "description", "thumbnailUrl", "uploadDate"],
+  LocalBusiness: ["name", "address"]
+};
+
+// src/rules/seo/detection.ts
+var PENALIZED = { presence: "none", value: "absent" };
+var PASS = { presence: "own", value: "static" };
+
+// src/rules/seo/seo016-021.ts
+function jsonldTags(head) {
+  return head.tags.filter((t) => t.kind === "jsonld" && typeof t.jsonld === "string");
+}
+var seo016JsonLdValidity = {
+  id: "SEO016",
+  title: "JSON-LD validity",
+  category: "seo",
+  severity: "warning",
+  scope: "route",
+  rationale: "Invalid JSON-LD \u2014 unparseable, or missing @context/@type \u2014 is silently ignored by search engines, so the structured data does nothing.",
+  fix: {
+    description: "Make the JSON-LD valid: parseable JSON with both @context (schema.org) and @type.",
+    snippet: '<svelte:head>\n  <script type="application/ld+json">\n    {"@context":"https://schema.org","@type":"WebPage","name":"\u2026"}\n  </script>\n</svelte:head>',
+    lang: "svelte"
+  },
+  async check(ctx) {
+    const docsUrl3 = docsUrlFor("SEO016");
+    const out = [];
+    for (const head of ctx.heads) {
+      for (const tag of jsonldTags(head)) {
+        const parsed = parseJsonLd(tag.jsonld);
+        let problem;
+        if (!parsed.ok) problem = "JSON-LD is not valid JSON";
+        else if (!parsed.nodes.some((n) => "@context" in n)) problem = "JSON-LD is missing @context";
+        else if (!parsed.nodes.some((n) => typeOf(n).length > 0)) problem = "JSON-LD is missing @type";
+        out.push(
+          problem ? {
+            id: "SEO016",
+            category: "seo",
+            severity: "warning",
+            detection: PENALIZED,
+            route: head.route,
+            location: head.file,
+            message: problem,
+            recommendation: "Make the JSON-LD valid JSON with both @context and @type.",
+            docsUrl: docsUrl3,
+            fix: { ...seo016JsonLdValidity.fix }
+          } : {
+            id: "SEO016",
+            category: "seo",
+            severity: "warning",
+            detection: PASS,
+            route: head.route,
+            message: "JSON-LD validity",
+            recommendation: "Make the JSON-LD valid JSON with both @context and @type.",
+            docsUrl: docsUrl3
+          }
+        );
+      }
+    }
+    return out;
+  }
+};
+function jsonldRule(opts) {
+  const docsUrl3 = docsUrlFor(opts.id);
+  return {
+    id: opts.id,
+    title: opts.title,
+    category: "seo",
+    severity: opts.severity,
+    scope: "route",
+    rationale: opts.rationale,
+    ...opts.fix ? { fix: opts.fix } : {},
+    async check(ctx) {
+      const out = [];
+      for (const head of ctx.heads) {
+        for (const tag of jsonldTags(head)) {
+          const parsed = parseJsonLd(tag.jsonld);
+          if (!parsed.ok) continue;
+          if (!parsed.nodes.some((n) => "@context" in n) || !parsed.nodes.some((n) => typeOf(n).length > 0)) continue;
+          const problem = opts.problem(parsed.nodes);
+          if (problem === false) continue;
+          out.push(
+            problem ? {
+              id: opts.id,
+              category: "seo",
+              severity: opts.severity,
+              detection: PENALIZED,
+              route: head.route,
+              location: head.file,
+              message: problem,
+              recommendation: opts.recommendation,
+              docsUrl: docsUrl3,
+              ...opts.fix ? { fix: { ...opts.fix } } : {}
+            } : {
+              id: opts.id,
+              category: "seo",
+              severity: opts.severity,
+              detection: PASS,
+              route: head.route,
+              message: opts.label,
+              recommendation: opts.recommendation,
+              docsUrl: docsUrl3
+            }
+          );
+        }
+      }
+      return out;
+    }
+  };
+}
+var seo017DeprecatedType = jsonldRule({
+  id: "SEO017",
+  title: "Deprecated structured-data type",
+  severity: "info",
+  label: "Structured-data type",
+  recommendation: "Verify the rich-result status of this @type; Google dropped or restricted some (e.g. HowTo, FAQPage).",
+  rationale: "Some schema types no longer produce rich results, so the markup adds weight without the SERP benefit.",
+  problem: (nodes) => {
+    const dep = nodes.flatMap(typeOf).find((t) => DEPRECATED_TYPES.has(t));
+    return dep ? `@type "${dep}" no longer reliably produces a Google rich result` : void 0;
+  }
+});
+var seo018RelativeUrl = jsonldRule({
+  id: "SEO018",
+  title: "JSON-LD relative URL",
+  severity: "warning",
+  label: "JSON-LD URLs",
+  recommendation: "Use absolute URLs (http/https) for url/@id/image/logo/sameAs/contentUrl/thumbnailUrl in JSON-LD.",
+  rationale: "Search engines need absolute URLs in structured data; a relative URL cannot be resolved reliably.",
+  fix: {
+    description: "Replace relative URLs in JSON-LD with absolute URLs.",
+    snippet: '"image": "https://example.com/logo.png"',
+    lang: "json"
+  },
+  problem: (nodes) => {
+    const bad = collectValues(nodes, URL_KEYS).find((v) => !isAbsoluteUrl(v));
+    return bad ? `Relative URL in JSON-LD: "${bad}" \u2014 use an absolute URL` : void 0;
+  }
+});
+var seo019DateFormat = jsonldRule({
+  id: "SEO019",
+  title: "JSON-LD date format",
+  severity: "info",
+  label: "JSON-LD dates",
+  recommendation: "Use ISO-8601 dates (e.g. 2026-06-26 or 2026-06-26T10:00:00Z) in JSON-LD.",
+  rationale: "Schema.org date properties expect ISO-8601; other formats may be ignored or misparsed.",
+  fix: {
+    description: "Format JSON-LD date properties as ISO-8601.",
+    snippet: '"datePublished": "2026-06-26"',
+    lang: "json"
+  },
+  problem: (nodes) => {
+    const bad = collectValues(nodes, DATE_KEYS).find((v) => !isIso8601(v));
+    return bad ? `Non-ISO-8601 date in JSON-LD: "${bad}"` : void 0;
+  }
+});
+var seo020Placeholder = jsonldRule({
+  id: "SEO020",
+  title: "JSON-LD placeholder text",
+  severity: "info",
+  label: "JSON-LD content",
+  recommendation: "Replace placeholder/boilerplate text in JSON-LD with real values.",
+  rationale: 'Leftover placeholder text (e.g. "Your Company Name", "lorem ipsum") ships misleading structured data.',
+  problem: (nodes) => {
+    const bad = nodes.flatMap(nodeStringValues).find(hasPlaceholder);
+    return bad ? `Placeholder text in JSON-LD: "${bad}"` : void 0;
+  }
+});
+var seo021RequiredProps = jsonldRule({
+  id: "SEO021",
+  title: "JSON-LD required properties",
+  severity: "warning",
+  label: "JSON-LD required properties",
+  recommendation: "Add the properties Google requires for this @type's rich result.",
+  rationale: "A recognized @type missing its required properties is ineligible for the corresponding rich result.",
+  problem: (nodes) => {
+    let hasKnownType = false;
+    for (const node of nodes) {
+      for (const t of typeOf(node)) {
+        const required = REQUIRED_PROPS[t];
+        if (!required) continue;
+        hasKnownType = true;
+        const missing = required.filter((p) => !hasNonEmpty(node, p));
+        if (missing.length > 0) return `${t} JSON-LD is missing required ${missing.join(", ")}`;
+      }
+    }
+    return hasKnownType ? void 0 : false;
+  }
+});
+
+// src/rules/seo/text-metrics.ts
+var segmenter = typeof Intl !== "undefined" && typeof Intl.Segmenter === "function" ? new Intl.Segmenter() : void 0;
+function visibleLength(s) {
+  const collapsed = s.trim().replace(/\s+/g, " ");
+  if (!segmenter) return [...collapsed].length;
+  return [...segmenter.segment(collapsed)].length;
+}
+
+// src/rules/seo/seo022-023.ts
+function lengthRule(opts) {
+  const docsUrl3 = docsUrlFor(opts.id);
+  return {
+    id: opts.id,
+    title: opts.title,
+    category: "seo",
+    severity: "info",
+    scope: "route",
+    rationale: opts.rationale,
+    async check(ctx) {
+      const out = [];
+      for (const head of ctx.heads) {
+        const tag = head.tags.find(opts.match);
+        if (!tag || typeof tag.text !== "string") continue;
+        const len = visibleLength(tag.text);
+        let problem;
+        if (len < opts.min) problem = `${opts.noun} is too short (${len} chars; aim for ${opts.min}\u2013${opts.max})`;
+        else if (len > opts.max) problem = `${opts.noun} is too long (${len} chars; aim for ${opts.min}\u2013${opts.max})`;
+        out.push(
+          problem ? {
+            id: opts.id,
+            category: "seo",
+            severity: "info",
+            detection: PENALIZED,
+            route: head.route,
+            location: tag.file ?? head.file,
+            message: problem,
+            recommendation: opts.recommendation,
+            docsUrl: docsUrl3
+          } : {
+            id: opts.id,
+            category: "seo",
+            severity: "info",
+            detection: PASS,
+            route: head.route,
+            message: opts.label,
+            recommendation: opts.recommendation,
+            docsUrl: docsUrl3
+          }
+        );
+      }
+      return out;
+    }
+  };
+}
+var seo022TitleLength = lengthRule({
+  id: "SEO022",
+  title: "Title length",
+  label: "Title length",
+  noun: "Title",
+  match: (t) => t.kind === "title",
+  min: 30,
+  max: 60,
+  recommendation: "Aim for a title of 30\u201360 characters so it is not truncated in search results.",
+  rationale: "A title that is too short wastes the strongest on-page signal; one that is too long is truncated in the SERP."
+});
+var seo023DescriptionLength = lengthRule({
+  id: "SEO023",
+  title: "Description length",
+  label: "Description length",
+  noun: "Description",
+  match: (t) => t.kind === "meta" && t.name === "description",
+  min: 70,
+  max: 160,
+  recommendation: "Aim for a meta description of 70\u2013160 characters so it is not truncated in search results.",
+  rationale: "A description that is too short under-uses the SERP snippet; one that is too long is truncated by search engines."
+});
+
+// src/rules/seo/seo024-charset.ts
+var seo024Charset = headTagRule({
+  id: "SEO024",
+  title: "Character encoding",
+  severity: "warning",
+  match: (t) => t.kind === "meta" && t.name === "charset",
+  label: "<meta charset>",
+  appliesTo: (head) => head.source === "rendered",
+  recommendation: 'Add <meta charset="utf-8"> (usually the first line of <head> in src/app.html).',
+  rationale: 'Without a declared character encoding the browser must guess, which can render text as mojibake; <meta charset="utf-8"> is the standard declaration.',
+  fix: {
+    description: "Add the charset meta tag (typically the first line of <head> in src/app.html).",
+    snippet: '<meta charset="utf-8" />',
+    lang: "html"
+  }
+});
+
+// src/rules/seo/seo025-image-alt.ts
+var seo025ImageAlt = imageRule({
+  id: "SEO025",
+  title: "Image alt text",
+  category: "seo",
+  severity: "warning",
+  label: "<img> alt text",
+  recommendation: 'Add an alt attribute to every <img> (use alt="" only for purely decorative images).',
+  rationale: "An <img> with no alt attribute is invisible to image search and assistive technology; a descriptive alt is an image-SEO signal.",
+  fix: {
+    description: 'Add a descriptive alt attribute to the <img> (or alt="" if purely decorative).',
+    snippet: '<img src="/photo.jpg" width="800" height="600" alt="Description of the image" />',
+    lang: "svelte"
+  },
+  ok: (img) => img.hasAlt
+});
+
+// src/rules/seo/seo026-hreflang.ts
+var docsUrl = docsUrlFor("SEO026");
+var recommendation = 'Use valid hreflang codes (e.g. "en", "en-US", "x-default") and include an x-default when you have multiple language alternates.';
+var HREFLANG_RE = /^[a-z]{2,3}(-[a-z]{4})?(-([a-z]{2}|\d{3}))?$/i;
+function isValidHreflang(v) {
+  return v.toLowerCase() === "x-default" || HREFLANG_RE.test(v);
+}
+var seo026Hreflang = {
+  id: "SEO026",
+  title: "hreflang validity",
+  category: "seo",
+  severity: "warning",
+  scope: "route",
+  rationale: "A malformed hreflang code or a missing x-default breaks international targeting, so search engines may serve the wrong language version.",
+  async check(ctx) {
+    const out = [];
+    for (const head of ctx.heads) {
+      const alternates = head.tags.filter(
+        (t) => t.kind === "link" && t.rel === "alternate" && typeof t.hreflang === "string"
+      );
+      if (alternates.length === 0) continue;
+      const values = alternates.map((t) => t.hreflang);
+      const badTag = alternates.find((t) => !isValidHreflang(t.hreflang));
+      let problem;
+      let location = head.file;
+      if (badTag) {
+        problem = `Invalid hreflang value "${badTag.hreflang}"`;
+        location = badTag.file ?? head.file;
+      } else if (values.length >= 2 && !values.some((v) => v.toLowerCase() === "x-default")) {
+        problem = "Multiple hreflang alternates without an x-default";
+      }
+      out.push(
+        problem ? {
+          id: "SEO026",
+          category: "seo",
+          severity: "warning",
+          detection: PENALIZED,
+          route: head.route,
+          location,
+          message: problem,
+          recommendation,
+          docsUrl
+        } : {
+          id: "SEO026",
+          category: "seo",
+          severity: "warning",
+          detection: PASS,
+          route: head.route,
+          message: "hreflang",
+          recommendation,
+          docsUrl
+        }
+      );
+    }
+    return out;
+  }
+};
+
+// src/rules/seo/seo027-heading.ts
+var docsUrl2 = docsUrlFor("SEO027");
+var recommendation2 = "Use exactly one <h1> per page for its main topic; demote extra top-level headings to <h2>+.";
+var seo027Heading = {
+  id: "SEO027",
+  title: "Heading hierarchy",
+  category: "seo",
+  severity: "warning",
+  scope: "route",
+  rationale: "Each page should have exactly one <h1> naming its main topic; none leaves the page without a primary heading, and several dilute the topic signal.",
+  async check(ctx) {
+    const out = [];
+    for (const route of ctx.headings ?? []) {
+      const h1 = route.headings.filter((h) => h.level === 1);
+      let problem;
+      let where = {};
+      if (h1.length === 0) {
+        problem = "Missing <h1>";
+        const first = route.headings[0];
+        if (first) where = { location: first.file, ...first.line > 0 ? { line: first.line } : {} };
+      } else if (h1.length > 1) {
+        problem = `Multiple <h1> (${h1.length}); use exactly one`;
+        const extra = h1[1];
+        where = { location: extra.file, ...extra.line > 0 ? { line: extra.line } : {} };
+      }
+      out.push(
+        problem ? {
+          id: "SEO027",
+          category: "seo",
+          severity: "warning",
+          detection: PENALIZED,
+          route: route.route,
+          ...where,
+          message: problem,
+          recommendation: recommendation2,
+          docsUrl: docsUrl2
+        } : {
+          id: "SEO027",
+          category: "seo",
+          severity: "warning",
+          detection: PASS,
+          route: route.route,
+          message: "Heading hierarchy",
+          recommendation: recommendation2,
+          docsUrl: docsUrl2
+        }
+      );
+    }
+    return out;
+  }
+};
+
 // src/rules/index.ts
 var allRules = [
   seo001Title,
@@ -607,7 +1151,19 @@ var allRules = [
   seo012OgDescription,
   seo013OgUrl,
   seo014Viewport,
-  seo015SitemapInRobots
+  seo015SitemapInRobots,
+  seo016JsonLdValidity,
+  seo017DeprecatedType,
+  seo018RelativeUrl,
+  seo019DateFormat,
+  seo020Placeholder,
+  seo021RequiredProps,
+  seo022TitleLength,
+  seo023DescriptionLength,
+  seo024Charset,
+  seo025ImageAlt,
+  seo026Hreflang,
+  seo027Heading
 ];
 function explainRule(id) {
   const target = id.toUpperCase();
@@ -1240,5 +1796,17 @@ export {
   seo013OgUrl,
   seo014Viewport,
   seo015SitemapInRobots,
+  seo016JsonLdValidity,
+  seo017DeprecatedType,
+  seo018RelativeUrl,
+  seo019DateFormat,
+  seo020Placeholder,
+  seo021RequiredProps,
+  seo022TitleLength,
+  seo023DescriptionLength,
+  seo024Charset,
+  seo025ImageAlt,
+  seo026Hreflang,
+  seo027Heading,
   summarize
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Shared, runtime-agnostic core for svelte-vitals (types, rule engine, scorer, reporter).",
   "type": "module",
   "license": "MIT",