@keenmate/web-components-devkit 1.0.0-rc01 → 1.0.0-rc03

package/src/examples/css/tokens.css

@@ -9,6 +9,11 @@
        component together — demo pages demonstrate cross-component theming;
      • with no --base-* set, the page still looks right, in light and dark.
 
+   Fallbacks are the contract's own (@keenmate/base-css-variables): an input
+   falls back to its default, a derived token to the contract formula on the
+   --kmwc-* tokens, so a page looks the same with and without the contract.
+   `npm run check:contract` (base-contract-check) enforces it.
+
    Unlike component variables (theme-container.md: never on :root), page
    tokens DO live on :root — the page is the scope here. Feature files read
    only --kmwc-* tokens; colour literals live in this file alone.
@@ -38,42 +43,65 @@
         /* ======================================================================
            COLORS — ACCENT
            ====================================================================== */
-        --kmwc-accent-color: var(--base-accent-color, #667eea);
-        --kmwc-accent-end-color: #764ba2;
-        --kmwc-accent-color-hover: var(--base-accent-color-hover, color-mix(in srgb, var(--kmwc-accent-color) 88%, black));
-        --kmwc-accent-color-active: var(--base-accent-color-active, color-mix(in srgb, var(--kmwc-accent-color) 72%, black));
-        --kmwc-accent-light-bg: var(--base-accent-color-light, color-mix(in srgb, var(--kmwc-accent-color) 12%, transparent));
-        --kmwc-accent-light-bg-hover: var(--base-accent-color-light-hover, color-mix(in srgb, var(--kmwc-accent-color) 20%, transparent));
+        --kmwc-accent-color: var(--base-primary-color, #3b82f6);
+        --kmwc-accent-end-color: oklch(from var(--kmwc-accent-color) calc(l - 0.12) c calc(h + 25));  /* header gradient end */
+        --kmwc-accent-color-hover: var(--base-primary-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-accent-color)), color-mix(in srgb, white 15%, var(--kmwc-accent-color))));
+        --kmwc-accent-color-active: var(--base-primary-color-active, light-dark(color-mix(in srgb, black 30%, var(--kmwc-accent-color)), color-mix(in srgb, white 30%, var(--kmwc-accent-color))));
+        --kmwc-accent-light-bg: var(--base-primary-bg-subtle, light-dark(color-mix(in srgb, var(--kmwc-accent-color) 10%, transparent), color-mix(in srgb, var(--kmwc-accent-color) 20%, transparent)));
+        --kmwc-accent-light-bg-hover: var(--base-primary-bg-subtle-hover, light-dark(color-mix(in srgb, var(--kmwc-accent-color) 15%, transparent), color-mix(in srgb, var(--kmwc-accent-color) 30%, transparent)));
         --kmwc-accent-border-color: color-mix(in srgb, var(--kmwc-accent-color) 40%, transparent);
         --kmwc-accent-shadow-color: color-mix(in srgb, var(--kmwc-accent-color) 35%, transparent);
-        --kmwc-text-color-on-accent: var(--base-text-color-on-accent, #ffffff);
+        --kmwc-text-color-on-accent: var(--base-on-primary-text-color, color(from color(from var(--kmwc-accent-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
         --kmwc-header-bg: linear-gradient(135deg, var(--kmwc-accent-color) 0%, var(--kmwc-accent-end-color) 100%);
 
         /* ======================================================================
            COLORS — TEXT
            ====================================================================== */
-        --kmwc-text-color-1: var(--base-text-color-1, light-dark(#2d3748, #f5f5f5));
-        --kmwc-text-color-2: var(--base-text-color-2, light-dark(#4a5568, #d4d4d4));
-        --kmwc-text-color-3: var(--base-text-color-3, light-dark(#718096, #a3a3a3));
-        --kmwc-text-color-4: var(--base-text-color-4, light-dark(#9ca3af, #737373));
+        --kmwc-text-color-1: var(--base-text-color-1, light-dark(#334155, #f1f5f9));
+        --kmwc-text-color-2: var(--base-text-color-2, color-mix(in srgb, var(--kmwc-text-color-1) 75%, var(--kmwc-main-bg)));
+        --kmwc-text-color-3: var(--base-text-color-3, color-mix(in srgb, var(--kmwc-text-color-1) 55%, var(--kmwc-main-bg)));
+        --kmwc-text-color-4: var(--base-text-color-4, color-mix(in srgb, var(--kmwc-text-color-1) 40%, var(--kmwc-main-bg)));
 
         /* ======================================================================
            COLORS — SURFACE
            ====================================================================== */
-        --kmwc-page-bg: light-dark(#f7fafc, #111317);
-        --kmwc-main-bg: var(--base-main-bg, light-dark(#ffffff, #1a1a1a));
-        --kmwc-elevated-bg: var(--base-elevated-bg, light-dark(#edf2f7, #2b2b2b));
-        --kmwc-hover-bg: var(--base-hover-bg, color-mix(in srgb, var(--kmwc-text-color-1) 6%, var(--kmwc-main-bg)));
-        --kmwc-border-color: var(--base-border-color, light-dark(#e2e8f0, #3d3d3d));
-        --kmwc-border-color-strong: light-dark(#cbd5e0, #525252);
-        --kmwc-shadow-color: light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.45));
+        --kmwc-page-bg: var(--base-page-bg, light-dark(#f8f9fa, #0f172a));
+        --kmwc-main-bg: var(--base-main-bg, light-dark(#ffffff, #1e293b));
+        --kmwc-elevated-bg: var(--base-elevated-bg, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.03) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.06) c h)));
+        --kmwc-hover-bg: var(--base-hover-bg, light-dark(color-mix(in oklch, oklch(from var(--kmwc-main-bg) calc(l - 0.45) c h) 14%, transparent), color-mix(in oklch, oklch(from var(--kmwc-main-bg) calc(l + 0.45) c h) 28%, transparent)));
+        --kmwc-border-color: var(--base-border-color, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.096) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.192) c h)));
+        --kmwc-border-color-strong: var(--base-input-border-color, light-dark(color-mix(in srgb, var(--kmwc-text-color-1) 45%, var(--kmwc-main-bg)), color-mix(in srgb, var(--kmwc-text-color-1) 35%, var(--kmwc-main-bg))));  /* control outline */
+        --kmwc-shadow-color: var(--base-shadow-color, light-dark(rgba(0, 0, 0, 0.15), rgba(0, 0, 0, 0.4)));
+        --kmwc-table-stripe-bg: color-mix(in srgb, var(--kmwc-elevated-bg) 55%, transparent);  /* zebra rows */
+        --kmwc-overlay-bg: var(--base-overlay-bg, rgba(30, 41, 59, 0.5));  /* behind a modal (spotlight) */
+
+        /* ======================================================================
+           FOCUSED ITEM — the keyboard cursor in a list (spotlight rows); the
+           shared state every Keenmate list uses (wcp --cp-item-active-*)
+           ====================================================================== */
+        --kmwc-outline-width: var(--base-outline-width, 1px);
+        --kmwc-focused-bg: var(--base-focused-bg, transparent);
+        --kmwc-focused-text-color: var(--base-focused-text-color, currentColor);
+        --kmwc-focused-outline: var(--base-focused-outline, var(--kmwc-outline-width) solid var(--kmwc-accent-color));
 
         /* ======================================================================
            COLORS — INPUTS & CODE
            ====================================================================== */
-        --kmwc-input-bg: var(--base-input-bg, light-dark(#ffffff, #1f1f1f));
-        --kmwc-input-color: var(--base-input-color, var(--kmwc-text-color-1));
-        --kmwc-input-border: var(--base-input-border, 1px solid light-dark(#d1d5db, #5a5a5a));
+        --kmwc-input-bg: var(--base-input-bg, var(--kmwc-main-bg));
+        --kmwc-input-color: var(--base-input-text-color, var(--kmwc-text-color-1));
+        --kmwc-input-border: var(--base-input-border, 1px solid var(--kmwc-border-color-strong));
+        --kmwc-input-border-hover: var(--base-input-border-hover, 1px solid var(--kmwc-accent-color));
+        --kmwc-input-border-focus: var(--base-input-border-focus, 1px solid var(--kmwc-accent-color));
+        --kmwc-input-shadow-color-focus: var(--base-input-shadow-color-focus, color-mix(in srgb, var(--kmwc-accent-color) 5%, transparent));
+        --kmwc-input-box-shadow-focus: var(--base-input-box-shadow-focus, 0 0 0 3px var(--kmwc-input-shadow-color-focus));
+        --kmwc-input-placeholder-color: var(--base-input-placeholder-color, var(--kmwc-text-color-3));
+        --kmwc-input-icon-color: var(--base-input-icon-color, var(--kmwc-text-color-3));  /* select caret */
+        --kmwc-input-disabled-bg: var(--base-input-bg-disabled, var(--base-disabled-bg, light-dark(oklch(from var(--kmwc-main-bg) calc(l - 0.024) c h), oklch(from var(--kmwc-main-bg) calc(l + 0.048) c h))));
+        --kmwc-disabled-opacity: var(--base-disabled-opacity, 0.65);
+        --kmwc-checkbox-border-color: var(--base-checkbox-border-color, var(--kmwc-border-color-strong));
+        --kmwc-icon-check: var(--base-icon-check, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22M20 6 9 17l-5-5%22/%3E%3C/svg%3E"));
+        --kmwc-icon-indeterminate: var(--base-icon-indeterminate, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22M5 12h14%22/%3E%3C/svg%3E"));
+        --kmwc-icon-check-size: var(--base-icon-check-size, 68%);
         --kmwc-code-bg: light-dark(#2d3748, #0d1117);
         --kmwc-code-text-color: #e2e8f0;
         --kmwc-code-comment-color: #8b949e;
@@ -90,21 +118,35 @@
         /* ======================================================================
            COLORS — SEMANTIC
            ====================================================================== */
-        --kmwc-success-color: light-dark(#2f855a, #68d391);
-        --kmwc-warning-color: light-dark(#b45309, #fbbf24);
-        --kmwc-danger-color: var(--base-danger-color, light-dark(#dc2626, #f87c86));
-        --kmwc-info-color: light-dark(#2563eb, #60a5fa);
+        /* -color = the role as text on a surface (notes, feedback); the danger
+           button fills with --kmwc-danger-fill-color. */
+        --kmwc-success-color: var(--base-success-text-color, light-dark(#155724, #34d399));
+        --kmwc-warning-color: var(--base-warning-text-color, light-dark(#856404, #fbbf24));
+        --kmwc-danger-color: var(--base-danger-text-color, light-dark(#721c24, #f87171));
+        --kmwc-info-color: var(--base-info-text-color, light-dark(#0c5460, #22d3ee));
+        --kmwc-danger-fill-color: var(--base-danger-color, #dc2626);
+        --kmwc-danger-fill-color-hover: var(--base-danger-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-danger-fill-color)), color-mix(in srgb, white 15%, var(--kmwc-danger-fill-color))));
+        --kmwc-text-color-on-danger: var(--base-on-danger-text-color, color(from color(from var(--kmwc-danger-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
         --kmwc-neutral-color: light-dark(#6b7280, #9ca3af);
         --kmwc-badge-new-bg: light-dark(#e53e3e, #f56565);
+        /* Text on the neutral / badge fills: the contract's on-colour formula on
+           their own background, not on the accent (a light primary would turn it black). */
+        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
+        --kmwc-text-color-on-badge-new: color(from color(from var(--kmwc-badge-new-bg) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
 
         /* ======================================================================
            TYPOGRAPHY & SHAPE
            ====================================================================== */
-        --kmwc-font-family: var(--base-font-family, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif);
-        --kmwc-mono-font-family: ui-monospace, SFMono-Regular, Menlo, 'Courier New', monospace;
+        --kmwc-font-family: var(--base-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+        --kmwc-mono-font-family: var(--base-font-family-mono, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);
         --kmwc-radius-lg: 12px;
         --kmwc-radius-md: 8px;
         --kmwc-radius-sm: 6px;
+        /* One height for inputs, selects and buttons, so a control row lines up.
+           A kit size, not --base-input-size-md-height: the contract's unitless
+           heights assume a 10px rem, the example pages keep the browser's 16px. */
+        --kmwc-control-height: 2.25rem;
+        --kmwc-checkbox-size: calc(1rem * var(--base-checkbox-scale, 1));
         --kmwc-max-width: 1400px;
     }
 }

package/src/examples/index.d.ts

@@ -8,6 +8,7 @@ export interface KmwcPageConfig {
   mode: 'dev' | 'build';
   canonicalOrigin: string;
   storagePrefix: string;
+  isSpotlightEnabled: boolean;
   repository: string;
   homepage: string;
   /** The @keenmate/web-components-devkit version that built the page (shown in the index footer). */
@@ -40,6 +41,20 @@ export interface ChapterNavConfig {
   indexHref?: string;
 }
 
+/** One entry of the spotlight's chapter index (virtual:kmwc-chapters). */
+export interface Chapter {
+  /** Section code (`TH07`), null for an uncoded heading (`Summary`). */
+  code: string | null;
+  /** Heading text without the code. */
+  title: string;
+  /** Heading text as shown (`TH07 · Title`). */
+  label: string;
+  pageHref: string;
+  pageTitle: string;
+  /** `examples-theming.html#th07` — by code, else by the heading slug. */
+  href: string;
+}
+
 export interface Section {
   heading: HTMLElement;
   section: HTMLElement;
@@ -58,6 +73,18 @@ export function renderExamplesIndex(indexConfig: ExamplesIndexConfig): HTMLEleme
 export function mountExamplesKit(): void;
 export function mountChapterNav(navConfig?: ChapterNavConfig): { unmount(): void } | null;
 
+/** Ctrl/Cmd+K chapter search across every example page (mirrors web-commandpalette); null when `isSpotlightEnabled` is false. */
+export function mountSpotlight(): { open(): void; close(): void; toggle(): void; unmount(): void } | null;
+/** Resolve the URL hash (`#th07`, an anchor id or a heading slug) now and on every hash change. */
+export function attachChapterLinks(): void;
+export function scrollToChapterHash(hash?: string): boolean;
+/** Chapters whose code or title contains the query; exact code (`th7` = TH07) first, then code prefix, then the rest. */
+export function searchChapters<T extends Pick<Chapter, 'code' | 'title'>>(chapters: T[], query: string): T[];
+/** Substring match of `needle` against any field (web-commandpalette matchesAny). */
+export function checkMatchesAny(fields: readonly unknown[], needle: string): boolean;
+/** Escaped `text` with the occurrences of `needle` in <mark> (web-commandpalette highlight). */
+export function renderHighlightedText(text: string, needle: string): string;
+
 export function attachCopyLinks(): void;
 export function copyText(text: string): Promise<boolean>;
 export function getSectionUrl(sectionId: string, canonicalOrigin?: string): string;
@@ -73,11 +100,22 @@ export function getSavedTheme(): Theme;
 export function ensureSectionAnchors(root?: Document): Section[];
 export function generateSlug(text: string): string;
 export function getHeadingLabel(heading: Element, fallbackLabel: string): string;
+export function getChapterCode(label: string): string | null;
+export function mapToCodeKey(code: string): string;
+export function findSectionByHash(hash: string, sections: Section[]): Section | null;
 
 export function getPageConfig(): KmwcPageConfig;
 export function attachDomReadyHandler(handler: () => void): void;
 
 export const CHAPTER_NAV_CLASSES: Record<string, string>;
+export const SPOTLIGHT_CLASSES: Record<string, string>;
+export const SPOTLIGHT_RESULTS_ID: string;
+export const SPOTLIGHT_ITEM_ID_PREFIX: string;
+export const SPOTLIGHT_OPEN_KEY: string;
+export const SPOTLIGHT_PAGE_STEP: number;
+export const SPOTLIGHT_FULLSCREEN_MEDIA: string;
+/** `TH07 · Title` → group 1 is the section code. */
+export const CHAPTER_CODE_PATTERN: RegExp;
 export const COPY_LINK_CLASSES: Record<string, string>;
 export const INDEX_PAGE_CLASSES: Record<string, string>;
 export const THEME_SWITCH_CLASSES: Record<string, string>;

package/src/examples/index.js

@@ -1,7 +1,7 @@
 /**
  * `@keenmate/web-components-devkit/examples` — named exports for example pages.
- * The page-level helpers (styles, chapter nav, copy-links, version badge,
- * theme switch) are mounted automatically by the Vite plugin; import from here
+ * The page-level helpers (styles, chapter nav, spotlight, copy-links, version
+ * badge, theme switch) are mounted automatically by the Vite plugin; import from here
  * only for the opt-in bits (controls persistence, index page) or to drive a
  * helper manually.
  */
@@ -9,10 +9,13 @@ export { attachControlsPersistence, getControlsStorageKey } from './controls-per
 export { renderExamplesIndex } from './index-page.js';
 export { mountExamplesKit } from './kit.js';
 export { mountChapterNav } from './chapter-nav.js';
+export { mountSpotlight } from './spotlight.js';
+export { attachChapterLinks, scrollToChapterHash } from './chapter-links.js';
+export { searchChapters, checkMatchesAny, renderHighlightedText } from './chapter-search.js';
 export { attachCopyLinks, copyText, getSectionUrl } from './copy-link.js';
 export { renderVersionBadges, getVersionLabel } from './version-badge.js';
 export { attachDemoCopyButtons } from './demo-code.js';
 export { mountThemeSwitch, applyTheme, getSavedTheme } from './theme-switch.js';
-export { ensureSectionAnchors, generateSlug, getHeadingLabel } from './sections.js';
+export { ensureSectionAnchors, generateSlug, getHeadingLabel, getChapterCode, mapToCodeKey, findSectionByHash } from './sections.js';
 export { getPageConfig, attachDomReadyHandler } from './page-config.js';
 export * from './constants.js';

package/src/examples/kit.js

@@ -1,4 +1,6 @@
 import { mountChapterNav } from './chapter-nav.js';
+import { attachChapterLinks } from './chapter-links.js';
+import { mountSpotlight } from './spotlight.js';
 import { attachCopyLinks } from './copy-link.js';
 import { renderVersionBadges } from './version-badge.js';
 import { mountThemeSwitch } from './theme-switch.js';
@@ -6,16 +8,21 @@ import { attachDemoCopyButtons } from './demo-code.js';
 import { INDEX_PAGE_CLASSES } from './constants.js';
 
 /**
- * (Re)mount the page-level helpers on the current DOM. Runs automatically once
- * per page; call it again after rendering sections asynchronously. Idempotent:
- * copy-link / demo copy buttons skip elements that already have one, the nav
- * and the theme switch are remounted.
+ * (Re)mount the page-level helpers on the current DOM (copy-links, chapter
+ * nav, short chapter links, spotlight, version badges, demo copy buttons,
+ * theme switch). Runs automatically once per page; call it again after
+ * rendering sections asynchronously. Idempotent: copy-link / demo copy buttons
+ * skip elements that already have one, the nav, spotlight and theme switch are
+ * remounted.
  */
 export function mountExamplesKit() {
   // Copy-links before the nav: the nav strips the buttons back out when
   // reading labels, and this order avoids a relayout after the nav is built.
   if (!document.body.classList.contains(INDEX_PAGE_CLASSES.body)) attachCopyLinks();
   mountChapterNav();
+  // After the anchors exist: an arriving #th07 can only resolve now.
+  attachChapterLinks();
+  mountSpotlight();
   renderVersionBadges();
   attachDemoCopyButtons();
   mountThemeSwitch();

package/src/examples/page-config.js

@@ -16,6 +16,7 @@ export function getPageConfig() {
     mode: injectedConfig.mode || 'dev',
     canonicalOrigin: injectedConfig.canonicalOrigin || '',
     storagePrefix: injectedConfig.storagePrefix || injectedConfig.id || 'component',
+    isSpotlightEnabled: injectedConfig.isSpotlightEnabled ?? true,
     repository: injectedConfig.repository || '',
     homepage: injectedConfig.homepage || '',
     devkitVersion: injectedConfig.devkitVersion || '',

package/src/examples/sections.js

@@ -8,7 +8,7 @@
  * reusing an existing section/h2 id before slugging the heading text.
  * Idempotent: a second call returns the same ids.
  */
-import { HEADING_CHIP_SELECTOR, SECTION_CONTAINER_SELECTOR, SECTION_SELECTOR } from './constants.js';
+import { CHAPTER_CODE_PATTERN, HEADING_CHIP_SELECTOR, SECTION_CONTAINER_SELECTOR, SECTION_SELECTOR } from './constants.js';
 
 export function generateSlug(text) {
   return String(text)
@@ -51,3 +51,40 @@ export function ensureSectionAnchors(root = document) {
     return { heading, section, id, label };
   });
 }
+
+/** `TH07 · Title` → 'TH07'; an uncoded label (`Summary`) → null. */
+export function getChapterCode(label) {
+  return String(label).match(CHAPTER_CODE_PATTERN)?.[1] ?? null;
+}
+
+/** Comparison key for a code: case and leading zeros don't matter (`TH07`, `th7` → 'th7'). */
+export function mapToCodeKey(code) {
+  return String(code).toLowerCase().replace(/^([a-z]+)0+(?=\d)/, '$1');
+}
+
+/**
+ * The section a URL hash points at: its anchor id, else its section code
+ * (`#th07`, `#th7` — the short link the codes exist for), else the slug of its
+ * heading text (an uncoded chapter whose section carries its own id).
+ * @param {string} hash `#…` or the bare fragment
+ * @param {ReturnType<typeof ensureSectionAnchors>} sections
+ */
+export function findSectionByHash(hash, sections) {
+  let fragment = String(hash).replace(/^#/, '');
+  try {
+    fragment = decodeURIComponent(fragment);
+  } catch {
+    // a malformed escape — match it as written
+  }
+  if (!fragment) return null;
+  const fragmentKey = mapToCodeKey(fragment);
+  return (
+    sections.find((section) => section.id === fragment) ??
+    sections.find((section) => {
+      const code = getChapterCode(section.label);
+      return code !== null && mapToCodeKey(code) === fragmentKey;
+    }) ??
+    sections.find((section) => generateSlug(section.label) === fragment.toLowerCase()) ??
+    null
+  );
+}