@hraness/design-kit 0.31.1

package/src/status-page-html.ts

@@ -0,0 +1,63 @@
+/**
+ * Static HTML for the shared 404 page. Static-site builders that do not run
+ * React write this into their `404.html`, load `status-page.css` (or
+ * styles.css), and call `attachStatusPage` from the browser entry. For a
+ * missing page the markup matches `StatusPage` in `@hraness/design-kit/react`
+ * byte for byte; tests bind the two. React error pages add the focus and
+ * live-region attributes a runtime error needs. Text arguments are escaped.
+ * The next-links heading has a fixed id, so render one page per document.
+ */
+import { escapeArticleHtml as escape } from "./article-html.js";
+import {
+  STATUS_PAGE_AGENT_PREFIX,
+  STATUS_PAGE_BACK_LABEL,
+  STATUS_PAGE_HINT_PREFIX,
+  STATUS_PAGE_NEXT_HEADING_ID,
+  resolveStatusPage,
+  statusPageRoutesAttribute,
+  type StatusPageContent,
+} from "./status-page.js";
+
+export type StatusPageHtmlOptions = StatusPageContent & Readonly<{
+  /** Heading level of the title; the next-links heading is one level lower. */
+  titleLevel?: 1 | 2 | 3 | 4 | 5;
+  /** Root element. Use "div" when the site layout already provides `main`. */
+  rootElement?: "main" | "div";
+}>;
+
+export function renderStatusPageHtml(options: StatusPageHtmlOptions = {}): string {
+  const page = resolveStatusPage(options);
+  const level = options.titleLevel ?? 1;
+  const root = options.rootElement ?? "main";
+  const notFound = page.kind === "not-found";
+  const routes = notFound ? statusPageRoutesAttribute(page.routes) : undefined;
+  const next = page.next.length === 0 ? "" : [
+    `<nav aria-labelledby="${STATUS_PAGE_NEXT_HEADING_ID}" class="hraness-status-page__next">`,
+    `<h${level + 1} class="hraness-status-page__next-heading" id="${STATUS_PAGE_NEXT_HEADING_ID}">${escape(page.nextHeading)}</h${level + 1}>`,
+    '<ul class="hraness-status-page__next-list">',
+    ...page.next.map((link) => [
+      `<li><a class="hraness-status-page__next-link" href="${escape(link.href)}">`,
+      `<span class="hraness-status-page__next-label">${escape(link.label)}</span>`,
+      link.description === undefined ? "" : `<span class="hraness-status-page__next-description">${escape(link.description)}</span>`,
+      "</a></li>",
+    ].join("")),
+    "</ul></nav>",
+  ].join("");
+  const agent = page.agentIndexHref === undefined ? "" : `<p class="hraness-status-page__agent">${STATUS_PAGE_AGENT_PREFIX} <a href="${escape(page.agentIndexHref)}">${escape(page.agentIndexHref)}</a></p>`;
+  return [
+    `<${root} class="hraness-status-page"${routes === undefined ? "" : ` data-hraness-status-routes="${escape(routes)}"`} data-kind="${page.kind}">`,
+    '<div class="hraness-status-page__inner">',
+    `<div aria-hidden="true" class="hraness-status-page__code"><span class="hraness-status-page__glyph">${escape(page.glyph)}</span><canvas class="hraness-status-page__field"></canvas></div>`,
+    `<h${level} class="hraness-status-page__title">${escape(page.title)}</h${level}>`,
+    `<p class="hraness-status-page__summary">${escape(page.summary)}</p>`,
+    notFound ? `<p class="hraness-status-page__hint" hidden="">${STATUS_PAGE_HINT_PREFIX} <a class="hraness-status-page__hint-link" href="/"></a>?</p>` : "",
+    '<div class="hraness-status-page__actions">',
+    `<a class="hraness-status-page__action hraness-foil" data-emphasis="primary" data-foil="" href="${escape(page.primaryAction.href)}">${escape(page.primaryAction.label)}</a>`,
+    `<a class="hraness-status-page__back" hidden="" href="/">${STATUS_PAGE_BACK_LABEL}</a>`,
+    "</div>",
+    next,
+    agent,
+    "</div>",
+    `</${root}>`,
+  ].join("");
+}

package/src/status-page.css

@@ -0,0 +1,276 @@
+/**
+ * Status pages
+ *
+ * One composition for the 404 page and recoverable error pages, shared by the
+ * React `StatusPage` and the static `renderStatusPageHtml` markup. The glyph is
+ * real text; `attachStatusPage` draws it as a dot field on a canvas and marks
+ * the root `data-hraness-status-field="live"` only after the canvas paints.
+ * Sites retheme through --hraness-status-ink, -muted, -accent, -line, -radius,
+ * and -glyph-font; everything else follows the palette tokens.
+ */
+@layer components.hraness-design-kit.legacy {
+  .hraness-status-page {
+    --_hraness-status-ink: var(--hraness-status-ink, var(--foreground, CanvasText));
+    --_hraness-status-muted: var(--hraness-status-muted, var(--muted, GrayText));
+    --_hraness-status-accent: var(--hraness-status-accent, var(--hraness-site-accent, var(--primary, var(--accent, LinkText))));
+    --_hraness-status-line: var(--hraness-status-line, color-mix(in srgb, var(--_hraness-status-ink) 14%, transparent));
+    --_hraness-status-radius: var(--hraness-status-radius, var(--hraness-marketing-radius, 0.75rem));
+
+    display: grid;
+    min-block-size: min(84svh, 52rem);
+    box-sizing: border-box;
+    place-items: center;
+    padding-block: clamp(2.5rem, 7vw, 5rem);
+    padding-inline: max(1rem, var(--layout-edge-inset, 1rem));
+    overflow-x: clip;
+    color: var(--_hraness-status-ink);
+    font-family: var(--font-text, inherit);
+    outline: none;
+  }
+
+  .hraness-status-page__inner {
+    display: flex;
+    inline-size: min(100%, 42rem);
+    min-inline-size: 0;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+  }
+
+  .hraness-status-page__code {
+    position: relative;
+    display: grid;
+    inline-size: 100%;
+    place-items: center;
+    margin-block-end: clamp(0.75rem, 2.5vw, 1.5rem);
+    user-select: none;
+    -webkit-user-select: none;
+  }
+
+  .hraness-status-page__glyph {
+    padding-block: 0.06em;
+    color: color-mix(in srgb, var(--_hraness-status-ink) 82%, transparent);
+    font-family: var(--hraness-status-glyph-font, var(--hraness-type-heading-font, var(--font-heading, inherit)));
+    font-size: clamp(7rem, 30vw, 13.5rem);
+    font-variant-numeric: lining-nums;
+    font-weight: var(--hraness-type-heading-weight, 600);
+    letter-spacing: -0.02em;
+    line-height: 1;
+  }
+
+  /* The canvas reads its accent from `color`. */
+  .hraness-status-page__field {
+    position: absolute;
+    inset: -2.5rem -1.5rem;
+    display: block;
+    inline-size: calc(100% + 3rem);
+    block-size: calc(100% + 5rem);
+    color: var(--_hraness-status-accent);
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 240ms ease-out;
+  }
+
+  .hraness-status-page[data-hraness-status-field="live"] .hraness-status-page__glyph {
+    visibility: hidden;
+  }
+
+  .hraness-status-page[data-hraness-status-field="live"] .hraness-status-page__field {
+    opacity: 1;
+  }
+
+  .hraness-status-page__title {
+    max-inline-size: 22ch;
+    margin: 0;
+    color: var(--_hraness-status-ink);
+    font-family: var(--hraness-type-heading-font, var(--font-heading, inherit));
+    font-size: clamp(1.75rem, 4.2vw, 2.4rem);
+    font-weight: var(--hraness-type-heading-weight, 600);
+    letter-spacing: -0.012em;
+    line-height: 1.15;
+    text-wrap: balance;
+  }
+
+  .hraness-status-page__summary {
+    max-inline-size: 34rem;
+    margin: 0.65rem 0 0;
+    color: var(--_hraness-status-muted);
+    font-size: 1.0625rem;
+    line-height: 1.55;
+    text-wrap: pretty;
+  }
+
+  .hraness-status-page__hint {
+    margin: 0.85rem 0 0;
+    color: var(--_hraness-status-ink);
+    font-size: 1rem;
+    line-height: 1.5;
+  }
+
+  .hraness-status-page__hint-link {
+    color: var(--_hraness-status-accent);
+    font-weight: 600;
+    text-decoration-line: underline;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.2em;
+  }
+
+  .hraness-status-page__hint[hidden],
+  .hraness-status-page__back[hidden] {
+    display: none;
+  }
+
+  .hraness-status-page__actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem 1.25rem;
+    margin-block-start: 1.6rem;
+  }
+
+  /* Zero specificity, so the shared foil treatment wins wherever it loads. */
+  :where(.hraness-status-page__action) {
+    display: inline-flex;
+    min-block-size: 2.75rem;
+    box-sizing: border-box;
+    align-items: center;
+    justify-content: center;
+    padding: 0.6rem 1.3rem;
+    border: 1px solid var(--_hraness-status-line);
+    border-radius: var(--_hraness-status-radius);
+    background: transparent;
+    color: var(--_hraness-status-ink);
+    cursor: pointer;
+    font: inherit;
+    font-size: 0.975rem;
+    font-weight: 600;
+    line-height: 1.2;
+    text-decoration: none;
+  }
+
+  :where(.hraness-status-page__action[data-emphasis="primary"]) {
+    border: 2px solid var(--_hraness-status-accent);
+    background: var(--surface, var(--background, Canvas));
+    box-shadow: 0 1px 4px color-mix(in srgb, var(--_hraness-status-ink) 12%, transparent);
+  }
+
+  .hraness-status-page__back {
+    color: var(--_hraness-status-muted);
+    font-size: 0.95rem;
+    text-decoration-line: underline;
+    text-decoration-color: var(--_hraness-status-line);
+    text-underline-offset: 0.25em;
+  }
+
+  .hraness-status-page__back:hover {
+    color: var(--_hraness-status-ink);
+  }
+
+  .hraness-status-page__next {
+    inline-size: 100%;
+    margin-block-start: clamp(2.75rem, 7vw, 4rem);
+  }
+
+  .hraness-status-page__next-heading {
+    margin: 0 0 0.85rem;
+    color: var(--_hraness-status-muted);
+    font-family: var(--font-text, inherit);
+    font-size: 0.875rem;
+    font-weight: 500;
+    letter-spacing: 0;
+    line-height: 1.4;
+  }
+
+  .hraness-status-page__next-list {
+    display: grid;
+    gap: 0.65rem;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr));
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .hraness-status-page__next-link {
+    display: flex;
+    block-size: 100%;
+    box-sizing: border-box;
+    flex-direction: column;
+    gap: 0.2rem;
+    padding: 0.85rem 1rem;
+    border: 1px solid var(--_hraness-status-line);
+    border-radius: var(--_hraness-status-radius);
+    background: color-mix(in srgb, var(--surface, var(--background, Canvas)) 70%, transparent);
+    color: var(--_hraness-status-ink);
+    text-align: start;
+    text-decoration: none;
+    transition: border-color 160ms ease-out, transform 160ms ease-out;
+  }
+
+  .hraness-status-page__next-link:hover {
+    border-color: color-mix(in srgb, var(--_hraness-status-accent) 55%, var(--_hraness-status-line));
+    transform: translateY(-1px);
+  }
+
+  .hraness-status-page__next-label {
+    font-size: 0.975rem;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+
+  .hraness-status-page__next-description {
+    color: var(--_hraness-status-muted);
+    font-size: 0.875rem;
+    line-height: 1.4;
+  }
+
+  .hraness-status-page__agent {
+    margin: 2rem 0 0;
+    color: var(--_hraness-status-muted);
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: 0.75rem;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+  }
+
+  .hraness-status-page__agent a {
+    color: inherit;
+    text-underline-offset: 0.2em;
+  }
+
+  .hraness-status-page a:focus-visible,
+  .hraness-status-page button:focus-visible {
+    outline: 2px solid var(--_hraness-status-accent);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hraness-status-page__field,
+    .hraness-status-page__next-link {
+      transition: none;
+    }
+
+    .hraness-status-page__next-link:hover {
+      transform: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .hraness-status-page__field {
+      display: none;
+    }
+
+    .hraness-status-page[data-hraness-status-field="live"] .hraness-status-page__glyph {
+      visibility: visible;
+    }
+
+    .hraness-status-page__glyph {
+      color: CanvasText;
+    }
+
+    :where(.hraness-status-page__action),
+    .hraness-status-page__next-link {
+      border-color: ButtonText;
+    }
+  }
+}

package/src/status-page.ts

@@ -0,0 +1,323 @@
+/**
+ * Framework-neutral content for full-page status routes: the 404 page and the
+ * recoverable error pages. React (`@hraness/design-kit/react`) and static HTML
+ * (`renderStatusPageHtml`) render the same markup from these values, styled by
+ * `status-page.css`; `attachStatusPage` from the browser entry adds the dot
+ * field, the "Did you mean" hint, and the same-site Back link.
+ */
+import { assertArticleHref } from "./article.js";
+
+export type StatusPageKind = "not-found" | "error";
+
+export type StatusPageLink = Readonly<{
+  href: string;
+  label: string;
+  /** One short line under the label. Next links only. */
+  description?: string;
+}>;
+
+export type StatusPageContent = Readonly<{
+  kind?: StatusPageKind;
+  /** Product name used in the default primary action ("Go to Sponge"). */
+  siteName?: string;
+  /** Decorative glyph drawn by the dot field. Defaults to "404" or "!". */
+  glyph?: string;
+  title?: string;
+  summary?: string;
+  /**
+   * The one action most readers should take. Point it at the product's main
+   * conversion step, such as starting a library or installing the CLI.
+   */
+  primaryAction?: StatusPageLink;
+  /** At most three places worth starting from, each with an optional line. */
+  next?: readonly StatusPageLink[];
+  nextHeading?: string;
+  /**
+   * Known internal pages. They are never listed; the browser controller
+   * compares them with the missing address and offers the closest one.
+   */
+  routes?: readonly StatusPageLink[];
+  /** A machine-readable index such as "/llms.txt", shown as one quiet line. */
+  agentIndexHref?: string;
+}>;
+
+export const STATUS_PAGE_MAX_NEXT = 3;
+export const STATUS_PAGE_MAX_ROUTES = 2000;
+export const STATUS_PAGE_BACK_LABEL = "Go back";
+export const STATUS_PAGE_HINT_PREFIX = "Did you mean";
+export const STATUS_PAGE_NEXT_HEADING_ID = "hraness-status-page-next";
+export const STATUS_PAGE_AGENT_PREFIX = "AI agents can start at";
+
+export type ResolvedStatusPage = Readonly<{
+  kind: StatusPageKind;
+  glyph: string;
+  title: string;
+  summary: string;
+  primaryAction: StatusPageLink;
+  next: readonly StatusPageLink[];
+  nextHeading: string;
+  routes: readonly StatusPageLink[];
+  agentIndexHref?: string;
+}>;
+
+const defaults = {
+  "not-found": {
+    glyph: "404",
+    title: "We can’t find that page",
+    summary: "The link may be out of date or mistyped.",
+  },
+  error: {
+    glyph: "!",
+    title: "This view could not load",
+    summary: "Retry this view, or return home and continue from there.",
+  },
+} as const satisfies Record<StatusPageKind, Readonly<{ glyph: string; title: string; summary: string }>>;
+
+function assertText(name: string, value: string, limit: number): void {
+  if (value.trim() === "" || value.length > limit) {
+    throw new RangeError(`Status page ${name} must be 1–${limit} characters.`);
+  }
+}
+
+function assertLink(name: string, link: StatusPageLink): void {
+  assertArticleHref(link.href);
+  assertText(`${name} label`, link.label, 48);
+  if (link.description !== undefined) assertText(`${name} description`, link.description, 90);
+}
+
+const ROUTE_LABEL_LIMIT = 80;
+
+/** True when `href` holds whitespace or a C0/C1 control character. */
+function hasControlOrSpace(href: string): boolean {
+  for (const character of href) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 0x20 || (code >= 0x7f && code <= 0x9f) || /\s/u.test(character)) return true;
+  }
+  return false;
+}
+
+/** Shorten a long page title at a word boundary for the "Did you mean" line. */
+function shortRouteLabel(label: string): string {
+  const text = label.trim().replace(/\s+/gu, " ");
+  if (text.length <= ROUTE_LABEL_LIMIT) return text;
+  const cut = text.slice(0, ROUTE_LABEL_LIMIT - 1);
+  const space = cut.lastIndexOf(" ");
+  return `${(space > ROUTE_LABEL_LIMIT / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+/**
+ * Routes usually come straight from a sitemap or article index, so they are
+ * cleaned rather than rejected: entries that are not same-site paths or have
+ * no label are dropped, and long titles are shortened.
+ */
+function usableRoutes(routes: readonly unknown[]): StatusPageLink[] {
+  const usable: StatusPageLink[] = [];
+  for (const route of routes.slice(0, STATUS_PAGE_MAX_ROUTES)) {
+    if (typeof route !== "object" || route === null) continue;
+    const { href, label } = route as { href?: unknown; label?: unknown };
+    if (typeof href !== "string" || typeof label !== "string" || label.trim() === "") continue;
+    if (!isSitePath(href) || hasControlOrSpace(href)) continue;
+    usable.push({ href, label: shortRouteLabel(label) });
+  }
+  return usable;
+}
+
+/** Apply defaults and reject content the page cannot show well. */
+export function resolveStatusPage(content: StatusPageContent = {}): ResolvedStatusPage {
+  const kind = content.kind ?? "not-found";
+  const base = defaults[kind];
+  const siteName = content.siteName?.trim();
+  if (siteName !== undefined) assertText("siteName", siteName, 40);
+  const glyph = content.glyph ?? base.glyph;
+  assertText("glyph", glyph, 4);
+  const title = content.title ?? base.title;
+  assertText("title", title, 60);
+  const summary = content.summary ?? base.summary;
+  assertText("summary", summary, 160);
+  const primaryAction = content.primaryAction ?? {
+    href: "/",
+    label: siteName ? `Go to ${siteName}` : "Go to the homepage",
+  };
+  assertLink("primaryAction", primaryAction);
+  const next = content.next ?? [];
+  if (next.length > STATUS_PAGE_MAX_NEXT) {
+    throw new RangeError(`A status page lists at most ${STATUS_PAGE_MAX_NEXT} next links; pick the ones that lead to your product.`);
+  }
+  next.forEach((link) => assertLink("next", link));
+  const nextHeading = content.nextHeading ?? "Or start here";
+  assertText("nextHeading", nextHeading, 40);
+  const routes = usableRoutes(content.routes ?? []);
+  if (content.agentIndexHref !== undefined) assertArticleHref(content.agentIndexHref);
+  return {
+    kind,
+    glyph,
+    title,
+    summary,
+    primaryAction,
+    next,
+    nextHeading,
+    routes,
+    ...(content.agentIndexHref === undefined ? {} : { agentIndexHref: content.agentIndexHref }),
+  };
+}
+
+/** A path on this site: one leading slash, not followed by a slash or backslash. */
+function isSitePath(href: string): boolean {
+  return /^\/(?![/\\])/u.test(href);
+}
+
+/** Serialized for the browser controller; the only route data in the markup. */
+export function statusPageRoutesAttribute(routes: readonly StatusPageLink[]): string | undefined {
+  if (routes.length === 0) return undefined;
+  return JSON.stringify(routes.map(({ href, label }) => [href, label]));
+}
+
+/** Parse the attribute written by `statusPageRoutesAttribute`, ignoring anything malformed. */
+export function parseStatusPageRoutes(value: string | null | undefined): readonly StatusPageLink[] {
+  if (!value) return [];
+  let parsed: unknown;
+  try { parsed = JSON.parse(value); } catch { return []; }
+  if (!Array.isArray(parsed)) return [];
+  const routes: StatusPageLink[] = [];
+  for (const entry of parsed.slice(0, STATUS_PAGE_MAX_ROUTES)) {
+    if (!Array.isArray(entry)) continue;
+    const [href, label] = entry as unknown[];
+    if (typeof href !== "string" || typeof label !== "string") continue;
+    if (!isSitePath(href) || label.trim() === "") continue;
+    routes.push({ href, label });
+  }
+  return routes;
+}
+
+const MAX_PATH = 160;
+
+/** Lowercased pathname without query, fragment, index files, or trailing slash. */
+export function normalizeStatusPath(value: string): string {
+  // Bound the input first; every step below is linear in its length.
+  let path = value.slice(0, MAX_PATH * 4);
+  const end = path.search(/[?#]/u);
+  if (end !== -1) path = path.slice(0, end);
+  try { path = decodeURIComponent(path); } catch { /* keep the raw path */ }
+  path = path.toLowerCase().split("/").filter((part, index) => index === 0 || part !== "").join("/");
+  path = path.replace(/(?:\/index)?\.html?$/u, "");
+  while (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+  if (!path.startsWith("/")) path = `/${path}`;
+  return path.slice(0, MAX_PATH);
+}
+
+/** The most edits a typo may carry; more than this is a different page. */
+const MAX_EDITS = 3;
+const BEYOND = MAX_EDITS + 1;
+
+/**
+ * Optimal string alignment distance, computed only in the diagonal band the
+ * limit allows, so each comparison costs O(length × limit). Returns
+ * `limit + 1` once the distance is known to exceed the limit.
+ */
+function editDistance(a: string, b: string, limit: number): number {
+  if (Math.abs(a.length - b.length) > limit) return limit + 1;
+  const columns = b.length + 1;
+  let before = new Int32Array(columns).fill(BEYOND);
+  let previous = Int32Array.from({ length: columns }, (_, index) => Math.min(index, BEYOND));
+  let current = new Int32Array(columns).fill(BEYOND);
+  for (let i = 1; i <= a.length; i++) {
+    const low = Math.max(1, i - limit);
+    const high = Math.min(b.length, i + limit);
+    current[low - 1] = low === 1 ? Math.min(i, BEYOND) : BEYOND;
+    if (high < b.length) current[high + 1] = BEYOND;
+    let rowMin = BEYOND;
+    for (let j = low; j <= high; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let value = Math.min((previous[j] ?? BEYOND) + 1, (current[j - 1] ?? BEYOND) + 1, (previous[j - 1] ?? BEYOND) + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        value = Math.min(value, (before[j - 2] ?? BEYOND) + 1);
+      }
+      current[j] = Math.min(value, BEYOND);
+      rowMin = Math.min(rowMin, value);
+    }
+    if (rowMin > limit) return limit + 1;
+    [before, previous, current] = [previous, current, before];
+  }
+  return Math.min(previous[b.length] ?? BEYOND, limit + 1);
+}
+
+function words(path: string): readonly string[] {
+  return path.split(/[/\-_.]+/u).filter((word) => word.length > 0);
+}
+
+/** Edits a single word may carry and still be the same word misspelled. */
+function wordAllowance(word: string): number {
+  if (word.length < 4) return 0;
+  return word.length < 8 ? 1 : 2;
+}
+
+/**
+ * Every word of the address is a word of the page, or that word misspelled.
+ * A different short word (v1/v2, oh/ai) or a different product name in the
+ * same slug template is a different page, not a typo.
+ */
+function wordsMatch(missing: readonly string[], candidate: readonly string[]): boolean {
+  return missing.every((word) => {
+    const allowance = wordAllowance(word);
+    return candidate.some((other) => other === word
+      || (allowance > 0 && editDistance(word, other, allowance) <= allowance));
+  });
+}
+
+type Candidate = Readonly<{ path: string; words: readonly string[]; joined: string; last: string }>;
+
+function candidate(path: string): Candidate {
+  const parts = words(path);
+  return { path, words: parts, joined: parts.join(""), last: path.slice(path.lastIndexOf("/") + 1) };
+}
+
+function score(missing: Candidate, page: Candidate): number | undefined {
+  if (page.path === missing.path) return 0;
+  // Same words with different separators: /gettingstarted, /getting_started.
+  if (missing.joined.length >= 6 && missing.joined === page.joined) return 0.1;
+  const longest = Math.max(missing.path.length, page.path.length);
+  const limit = Math.min(MAX_EDITS, Math.floor(longest / 4));
+  if (limit > 0 && wordsMatch(missing.words, page.words)) {
+    const distance = editDistance(missing.path, page.path, limit);
+    if (distance <= limit) return distance / longest;
+  }
+  // A page that kept its slug but moved section: /blog/x -> /writing/x.
+  if (missing.last.length >= 6 && missing.last === page.last) return 0.5;
+  // A shortened slug: every longer word of the address appears in the page.
+  const longer = missing.words.filter((word) => word.length >= 3);
+  if (longer.length >= 2 && longer.length === missing.words.length
+    && longer.every((word) => page.words.includes(word))) return 0.6;
+  return undefined;
+}
+
+/**
+ * The known internal page closest to a missing address, or nothing when no
+ * page is close enough to be a likely typo, move, or shortened link. The home
+ * page is never suggested; the primary action already leads there.
+ */
+export function suggestStatusRoute(
+  pathname: string,
+  routes: readonly StatusPageLink[],
+): StatusPageLink | undefined {
+  const normalized = normalizeStatusPath(pathname);
+  if (normalized === "/") return undefined;
+  // Too short to tell a typo from a different page (/a, /do, /api), so a
+  // short address only matches a page that differs in case or slashes.
+  const exactOnly = normalized.length < 5;
+  const missing = candidate(normalized);
+  let best: { route: StatusPageLink; score: number; path: string } | undefined;
+  for (const route of routes.slice(0, STATUS_PAGE_MAX_ROUTES)) {
+    if (!isSitePath(route.href)) continue;
+    const path = normalizeStatusPath(route.href);
+    if (path === "/" || (exactOnly && path !== normalized)) continue;
+    const value = score(missing, candidate(path));
+    if (value === undefined) continue;
+    if (best === undefined
+      || value < best.score
+      || (value === best.score && (path.length < best.path.length
+        || (path.length === best.path.length && path < best.path)))) {
+      best = { route, score: value, path };
+    }
+  }
+  return best?.route;
+}

package/src/styles.css

@@ -0,0 +1,21 @@
+@layer base, components;
+@layer components.hraness-ui.legacy.base, components.hraness-ui.legacy, components.hraness-ui.priority1, components.hraness-ui.priority2, components.hraness-ui.priority3, components.hraness-ui.priority4, components.hraness-ui.priority5, components.hraness-ui.priority6, components.hraness-ui.priority7, components.hraness-design-kit.legacy, components.hraness-design-kit.priority1, components.hraness-design-kit.priority2, components.hraness-design-kit.priority3, components.hraness-design-kit.priority4, components.hraness-design-kit.priority5, components.hraness-design-kit.priority6, components.hraness-design-kit.priority7, components.hraness-design-kit.priority8;
+
+@import "./tokens.css";
+@import "./reset.css";
+@import "./typography.css";
+@import "./effects.css";
+@import "@hraness/ui/components.css";
+@import "@hraness/ui/stylex.css";
+@import "./components.css";
+@import "./appearance-menu.css";
+@import "./charts.css";
+@import "./plain-site.css";
+@import "./plain-publication.css";
+@import "./reading.css";
+@import "./status-page.css";
+@import "./product-marketing.css";
+@import "./product-marketing-foundation.css";
+@import "./design-gallery.css";
+@import "./palette-bridge.css";
+@import "./lantern-material.css";