@keenmate/web-components-devkit 1.0.0-rc02 → 1.0.0-rc04

package/src/examples/css/spotlight.css

@@ -0,0 +1,417 @@
+/* ==============================================================================
+   EXAMPLES KIT — SPOTLIGHT
+   ==============================================================================
+   Ctrl/⌘+K chapter search (spotlight.js). MIRRORS web-commandpalette's CSS
+   (src/css/dialog.css, search.css, results.css, footer.css, animations.css):
+   same elements under the kit prefix, same layout, the same --base-* hooks
+   for backdrop, focused row and highlight — so both look alike under a theme.
+   A rule marked `mirrors …` keeps the wcp rule; keep them in step
+   (scripts/spotlight-mirror.json, `npm run check:spotlight-mirror`).
+   Spotlight-only: the header trigger button and the section-code chip. */
+@layer kmwc {
+    /* ==========================================================================
+       TRIGGER (spotlight only) — left of the theme switch
+       ========================================================================== */
+    .kmwc-spotlight__trigger {
+        position: fixed;
+        top: 0.75rem;
+        right: calc(0.75rem + 36px + 0.5rem);
+        z-index: 9000;
+        display: inline-flex;
+        align-items: center;
+        gap: 0.4rem;
+        height: 36px;
+        padding: 0 0.6rem 0 0.7rem;
+        border-radius: 18px;
+        border: 1px solid var(--kmwc-border-color);
+        background: var(--kmwc-main-bg);
+        color: var(--kmwc-text-color-2);
+        box-shadow: 0 2px 6px var(--kmwc-shadow-color);
+        font: inherit;
+        cursor: pointer;
+    }
+
+    .kmwc-spotlight__trigger:hover {
+        background: var(--kmwc-hover-bg);
+        color: var(--kmwc-text-color-1);
+    }
+
+    .kmwc-spotlight__trigger:focus-visible {
+        outline: 2px solid var(--kmwc-accent-color);
+        outline-offset: 2px;
+    }
+
+    .kmwc-spotlight__trigger svg,
+    .kmwc-spotlight__close svg {
+        width: 18px;
+        height: 18px;
+        flex: none;
+        fill: none;
+        stroke: currentColor;
+        stroke-width: 2;
+        stroke-linecap: round;
+    }
+
+    /* ==========================================================================
+       DIALOG — mirrors wcp dialog.css
+       ========================================================================== */
+    .kmwc-spotlight {
+        position: fixed;
+        inset: 0;
+        z-index: 9100; /* above the kit chrome (9000); wcp: --base-z-popover + 1 */
+        display: none;
+        align-items: flex-start;
+        justify-content: center;
+        padding-top: 128px;
+        font-family: var(--kmwc-font-family);
+    }
+
+    .kmwc-spotlight--active {
+        display: flex;
+    }
+
+    .kmwc-spotlight__backdrop {
+        position: absolute;
+        inset: 0;
+        background-color: var(--kmwc-overlay-bg);
+        backdrop-filter: blur(4px);
+        animation: kmwc-spotlight-fade-in 0.2s ease;
+    }
+
+    .kmwc-spotlight__container {
+        position: relative;
+        width: 100%;
+        max-width: 608px;
+        background-color: var(--kmwc-main-bg);
+        color: var(--kmwc-text-color-1);
+        border-radius: var(--kmwc-radius-md);
+        box-shadow: 0 16px 48px var(--kmwc-shadow-color);
+        animation: kmwc-spotlight-slide-down 0.2s ease;
+        overflow: hidden;
+    }
+
+    @media (max-width: 768px) {
+        .kmwc-spotlight {
+            padding-top: 1rem;
+        }
+
+        .kmwc-spotlight__container {
+            max-width: calc(100% - 2rem);
+        }
+    }
+
+    /* Phone fullscreen sheet — mirrors wcp dialog.css `--fullscreen` */
+    .kmwc-spotlight__fullscreen-bar {
+        display: none;
+        flex: 0 0 auto;
+        align-items: center;
+        justify-content: space-between;
+        gap: 0.5rem;
+        padding: calc(0.5rem + env(safe-area-inset-top)) 0.5rem 0.5rem;
+        border-bottom: 1px solid var(--kmwc-border-color);
+    }
+
+    .kmwc-spotlight__fullscreen-title {
+        font-size: 1.5rem;
+        font-weight: 600;
+        color: var(--kmwc-text-color-1);
+    }
+
+    .kmwc-spotlight__close {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 38px;
+        height: 38px;
+        padding: 0;
+        border: var(--kmwc-input-border);
+        border-radius: var(--kmwc-radius-md);
+        background-color: var(--kmwc-input-bg);
+        color: var(--kmwc-text-color-1);
+        cursor: pointer;
+    }
+
+    .kmwc-spotlight--fullscreen {
+        padding: 0;
+        align-items: stretch;
+        justify-content: stretch;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__backdrop {
+        display: none;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__container {
+        position: fixed;
+        top: 0;
+        inset-inline-start: 0;
+        width: 100vw;
+        max-width: 100vw;
+        height: 100dvh;
+        max-height: 100dvh;
+        border-radius: 0;
+        box-shadow: none;
+        animation: none;
+        display: flex;
+        flex-direction: column;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__fullscreen-bar {
+        display: flex;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__search {
+        flex: 0 0 auto;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__results {
+        flex: 1 1 0;
+        min-height: 0;
+        max-height: none;
+    }
+
+    .kmwc-spotlight--fullscreen .kmwc-spotlight__footer {
+        flex: 0 0 auto;
+        padding-bottom: calc(0.5rem + env(safe-area-inset-bottom));
+    }
+
+    /* ==========================================================================
+       SEARCH — mirrors wcp search.css
+       ========================================================================== */
+    .kmwc-spotlight__search {
+        position: relative;
+        border-bottom: 1px solid var(--kmwc-border-color);
+        padding: 0.5rem;
+    }
+
+    .kmwc-spotlight__input-wrapper {
+        position: relative;
+    }
+
+    .kmwc-spotlight__input {
+        box-sizing: border-box; /* wcp gets it from its shadow-root reset */
+        width: 100%;
+        height: 38px;
+        padding: 0 0.5rem;
+        font: inherit;
+        font-size: 1rem;
+        border: var(--kmwc-input-border);
+        border-radius: var(--kmwc-radius-md);
+        background-color: var(--kmwc-input-bg);
+        color: var(--kmwc-input-color);
+        outline: none;
+        transition: border-color 0.15s ease-out, box-shadow 0.15s ease-out;
+    }
+
+    .kmwc-spotlight__input:focus {
+        border-color: var(--kmwc-accent-color);
+        box-shadow: 0 0 0 3px var(--kmwc-accent-light-bg);
+    }
+
+    .kmwc-spotlight__input::placeholder {
+        color: var(--kmwc-text-color-3);
+        opacity: 1;
+    }
+
+    /* ==========================================================================
+       RESULTS — mirrors wcp results.css
+       ========================================================================== */
+    .kmwc-spotlight__results {
+        max-height: min(384px, max(160px, 100dvh - 128px - 120px));
+        overflow-y: auto;
+        overscroll-behavior: contain;
+        padding: 0.5rem 0;
+        position: relative;
+        scrollbar-width: thin;
+    }
+
+    @media (max-width: 768px) {
+        .kmwc-spotlight__results {
+            max-height: 60vh;
+        }
+    }
+
+    .kmwc-spotlight__home-section:not(:first-child) {
+        border-top: 1px solid var(--kmwc-border-color);
+        margin-top: 0.25rem;
+        padding-top: 0.25rem;
+    }
+
+    .kmwc-spotlight__home-heading {
+        padding: 0.25rem 0.5rem;
+        font-size: 0.7rem;
+        font-weight: 600;
+        color: var(--kmwc-text-color-2);
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+    }
+
+    .kmwc-spotlight__empty {
+        padding: 2rem 0.5rem;
+        text-align: center;
+        color: var(--kmwc-text-color-2);
+        font-size: 0.875rem;
+    }
+
+    .kmwc-spotlight__item {
+        padding: 0.5rem;
+        cursor: pointer;
+        transition: background-color 0.15s ease;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        color: inherit;
+        text-decoration: none;
+    }
+
+    .kmwc-spotlight__item:hover {
+        background-color: var(--kmwc-hover-bg);
+        text-decoration: none;
+    }
+
+    /* The keyboard cursor (where Enter goes): the focused item state — an inset
+       outline (offset = minus its width, so a thicker outline stays inside the row). */
+    .kmwc-spotlight__item--active {
+        background-color: var(--kmwc-focused-bg);
+        outline: var(--kmwc-focused-outline);
+        outline-offset: calc(-1 * var(--kmwc-outline-width));
+    }
+
+    .kmwc-spotlight__item--active:hover {
+        background-color: var(--kmwc-hover-bg);
+    }
+
+    .kmwc-spotlight__item--active .kmwc-spotlight__item-title {
+        color: var(--kmwc-focused-text-color);
+    }
+
+    /* The section code, in the slot wcp gives the item icon (spotlight only). */
+    .kmwc-spotlight__item-code {
+        flex-shrink: 0;
+        min-width: 3.4rem;
+        padding: 0.15rem 0.35rem;
+        border-radius: var(--kmwc-radius-sm);
+        background-color: var(--kmwc-accent-light-bg);
+        color: var(--kmwc-accent-color);
+        font-family: var(--kmwc-mono-font-family);
+        font-size: 0.78rem;
+        font-weight: 700;
+        text-align: center;
+    }
+
+    .kmwc-spotlight__item-content {
+        flex: 1;
+        min-width: 0;
+    }
+
+    .kmwc-spotlight__item-title {
+        display: block;
+        font-size: 0.875rem;
+        font-weight: 500;
+        color: var(--kmwc-text-color-1);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+
+    /* The matched part of the query. */
+    .kmwc-spotlight__item-title mark,
+    .kmwc-spotlight__item-code mark {
+        background-color: var(--kmwc-accent-light-bg-hover);
+        color: var(--kmwc-accent-color);
+        font-weight: 600;
+        padding: 0 2px;
+        border-radius: var(--kmwc-radius-sm);
+    }
+
+    .kmwc-spotlight__item-code mark {
+        padding: 0;
+    }
+
+    /* Screen-reader-only result count (wcp: .cp-sr-only). */
+    .kmwc-spotlight__live {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        margin: -1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+    }
+
+    /* ==========================================================================
+       FOOTER — mirrors wcp footer.css
+       ========================================================================== */
+    .kmwc-spotlight__footer {
+        border-top: 1px solid var(--kmwc-border-color);
+        padding: 0.5rem;
+        display: flex;
+        flex-wrap: wrap;
+        gap: 1rem;
+        font-size: 0.75rem;
+        color: var(--kmwc-text-color-2);
+    }
+
+    .kmwc-spotlight__hint {
+        display: flex;
+        align-items: center;
+        gap: 0.25rem;
+    }
+
+    .kmwc-spotlight__key,
+    .kmwc-spotlight__trigger-key {
+        padding: 2px 0.25rem;
+        background-color: var(--kmwc-elevated-bg);
+        color: var(--kmwc-text-color-1);
+        border: 1px solid var(--kmwc-border-color);
+        border-radius: var(--kmwc-radius-sm);
+        font-family: var(--kmwc-font-family);
+        font-weight: 600;
+        font-size: 0.75rem;
+        line-height: 1;
+    }
+
+    .kmwc-spotlight__trigger-key {
+        color: var(--kmwc-text-color-3);
+        font-weight: 400;
+    }
+
+    /* ==========================================================================
+       ANIMATIONS — mirrors wcp animations.css
+       ========================================================================== */
+    @keyframes kmwc-spotlight-fade-in {
+        from { opacity: 0; }
+        to { opacity: 1; }
+    }
+
+    @keyframes kmwc-spotlight-slide-down {
+        from {
+            opacity: 0;
+            transform: translateY(-20px);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .kmwc-spotlight__backdrop,
+        .kmwc-spotlight__container {
+            animation: none;
+        }
+    }
+
+    @media (max-width: 768px) {
+        .kmwc-spotlight__trigger-key,
+        .kmwc-spotlight__footer {
+            display: none;
+        }
+
+        .kmwc-spotlight__trigger {
+            width: 36px;
+            padding: 0;
+            justify-content: center;
+        }
+    }
+}

package/src/examples/css/style.css

@@ -20,11 +20,14 @@
 
 @import './tokens.css';
 @import './base.css';
+@import './form-controls.css';
 @import './controls.css';
 @import './content.css';
+@import './tables.css';
 @import './widgets.css';
 @import './demo.css';
 @import './copy-link.css';
 @import './chapter-nav.css';
+@import './spotlight.css';
 @import './theme-switch.css';
 @import './index-page.css';

package/src/examples/css/tables.css

@@ -0,0 +1,141 @@
+/* ==============================================================================
+   EXAMPLES KIT — TABLES
+   ==============================================================================
+   Any <table> on a page gets the base look (header fill, row lines, hover),
+   modelled on pure-admin's .pa-table. `.reference-table` is the full-width,
+   fully bordered API / option table most pages use. Modifiers combine:
+
+     .table-bordered   every cell boxed (what .reference-table has)
+     .table-striped    zebra rows
+     .table-compact    tighter cells; controls inside shrink with them
+     .table-full       full width
+     tr.is-highlight   an accent-tinted row
+     .num              a right-aligned, tabular-figure cell
+
+   The base is zero-specificity (:where()), so a page or component rule wins;
+   `kmwc-native` on the table (or an ancestor) leaves it unstyled. */
+@layer kmwc {
+    /* ==========================================================================
+       BASE — every table
+       ========================================================================== */
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) {
+        border-collapse: collapse;
+        font-size: 0.875rem;
+        margin-bottom: 1rem;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(th, td) {
+        padding: 0.6rem 0.9rem;
+        text-align: start;
+        vertical-align: middle;
+        border-bottom: 1px solid var(--kmwc-border-color);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(th) {
+        background: var(--kmwc-elevated-bg);
+        color: var(--kmwc-text-color-1);
+        font-weight: 600;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(thead th) {
+        border-bottom: 2px solid var(--kmwc-border-color);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(tbody tr:hover) {
+        background: var(--kmwc-hover-bg);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(tfoot td, tfoot th) {
+        border-top: 2px solid var(--kmwc-border-color);
+        border-bottom: none;
+        font-weight: 600;
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(caption) {
+        caption-side: top;
+        padding-bottom: 0.5rem;
+        text-align: start;
+        font-size: 0.8rem;
+        color: var(--kmwc-text-color-2);
+    }
+
+    :where(table):not(:where(.kmwc-native, .kmwc-native *)) :where(code) {
+        padding: 0.125rem 0.375rem;
+        font-size: 0.75rem;
+    }
+
+    /* ==========================================================================
+       MODIFIERS
+       ========================================================================== */
+    .table-full {
+        width: 100%;
+    }
+
+    .table-bordered :is(th, td) {
+        border: 1px solid var(--kmwc-border-color);
+    }
+
+    .table-striped tbody tr:nth-child(even) {
+        background: var(--kmwc-table-stripe-bg);
+    }
+
+    .table-striped tbody tr:nth-child(even):hover {
+        background: var(--kmwc-hover-bg);
+    }
+
+    /* Tighter cells, and the controls in them shrink too: buttons, inputs and
+       selects read --kmwc-control-height (form-controls.css). */
+    .table-compact {
+        --kmwc-control-height: 1.75rem;
+        font-size: 0.8125rem;
+    }
+
+    .table-compact :is(th, td) {
+        padding: 0.3rem 0.55rem;
+    }
+
+    .table-compact :is(button, input, select) {
+        font-size: 0.8125rem;
+    }
+
+    .table-compact button {
+        padding-inline: 0.6rem;
+    }
+
+    tr.is-highlight,
+    tr.is-highlight:hover {
+        background: var(--kmwc-accent-light-bg);
+    }
+
+    :is(th, td).num {
+        text-align: end;
+        font-variant-numeric: tabular-nums;
+        white-space: nowrap;
+    }
+
+    /* ==========================================================================
+       REFERENCE TABLE — the API / option table (full width, every cell boxed)
+       ========================================================================== */
+    .reference-table {
+        width: 100%;
+        margin-bottom: 2rem;
+    }
+
+    .reference-table th,
+    .reference-table td {
+        padding: 0.75rem 1rem;
+        border: 1px solid var(--kmwc-border-color);
+    }
+
+    /* A wide table scrolls inside its card instead of widening the page.
+       Widening matters beyond looks: mobile browsers grow the layout viewport
+       to fit, so a 390 px phone reports ~600 px and the page's own device /
+       breakpoint detection lies. */
+    @media (max-width: 768px) {
+        :where(table):not(:where(.kmwc-native, .kmwc-native *)) {
+            display: block;
+            max-width: 100%;
+            overflow-x: auto;
+        }
+    }
+}

package/src/examples/css/tokens.css

@@ -72,6 +72,17 @@
         --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
@@ -79,6 +90,18 @@
         --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;
@@ -119,6 +142,11 @@
         --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>;