@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/assets/reader-filters.js

@@ -0,0 +1,305 @@
+// Reader views are presentation filters. Published pages remain available at their URLs.
+const source = document.querySelector('#reader-filter-config');
+if (source) {
+  const config = JSON.parse(source.textContent);
+  const facets = config.facets;
+  const slots = [...document.querySelectorAll('[data-reader-filter]')];
+  const page = document.querySelector('[data-reader-page]');
+  const banner = document.querySelector('.reader-outside-view');
+  if (banner) {
+    const message = document.createElement('p');
+    const actions = document.createElement('div');
+    for (const [attribute, label] of [['data-reader-switch', 'Switch to this page’s view'], ['data-reader-reset', 'Show all']]) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.setAttribute(attribute, '');
+      button.textContent = label;
+      actions.append(button);
+    }
+    banner.append(message, actions);
+  }
+  const parseData = value => {
+    try { return JSON.parse(value || '{}'); } catch { return {}; }
+  };
+  const pageFilters = parseData(page?.dataset.readerPage);
+  const controlScope = slot => parseData(slot.dataset.readerFilter).scope === 'page' ? 'page' : 'site';
+  const make = (tag, className, value) => {
+    const element = document.createElement(tag);
+    if (className) element.className = className;
+    if (value !== undefined) element.textContent = value;
+    return element;
+  };
+  const mountControl = (slot, index) => {
+    const control = parseData(slot.dataset.readerFilter);
+    const names = control.facet ? [control.facet] : Object.keys(facets);
+    const checks = control.display === 'checks';
+    const wrapper = make(checks ? 'details' : 'div', checks ? 'reader-filter-controls' : 'reader-filter-control');
+    if (checks) {
+      const summary = make('summary', '', control.label || 'Reader view');
+      summary.append(make('span', 'reader-view-label', 'All content'));
+      wrapper.append(summary);
+    } else if (control.label && names.length > 1) wrapper.append(make('span', 'reader-filter-title', control.label));
+    for (const facet of names) {
+      const definition = facets[facet];
+      if (!definition) continue;
+      if (checks) {
+        const fieldset = make('fieldset');
+        fieldset.dataset.readerFacet = facet;
+        fieldset.append(make('legend', '', definition.label));
+        for (const [value, title] of Object.entries(definition.options)) {
+          const label = make('label');
+          const input = make('input');
+          input.type = 'checkbox';
+          input.value = value;
+          label.append(input, make('span', '', title));
+          fieldset.append(label);
+        }
+        wrapper.append(fieldset);
+      } else {
+        const field = make('div', 'reader-filter-field');
+        field.dataset.readerFacet = facet;
+        const id = `reader-filter-${index}-${facet}`;
+        const label = make('label', '', control.label && names.length === 1 ? control.label : definition.label);
+        label.htmlFor = id;
+        const select = make('select');
+        select.id = id;
+        const all = make('option', '', 'All');
+        all.value = '';
+        select.append(all);
+        const multiple = make('option', '', 'Multiple selected');
+        multiple.value = '__multiple__';
+        multiple.disabled = true;
+        select.append(multiple);
+        for (const [value, title] of Object.entries(definition.options)) {
+          const option = make('option', '', title);
+          option.value = value;
+          select.append(option);
+        }
+        field.append(label, select);
+        wrapper.append(field);
+      }
+    }
+    if (checks) {
+      const actions = make('div', 'reader-filter-actions');
+      const reset = make('button', '', 'Show all');
+      reset.type = 'button';
+      reset.dataset.readerReset = '';
+      const copy = make('button', '', 'Copy view link');
+      copy.type = 'button';
+      copy.dataset.readerCopy = '';
+      actions.append(reset, copy);
+      if (control.scope === 'page') {
+        const inherit = make('button', '', 'Follow site view');
+        inherit.type = 'button';
+        inherit.dataset.readerInherit = '';
+        actions.append(inherit);
+      }
+      const status = make('span', 'reader-filter-status');
+      status.setAttribute('role', 'status');
+      status.setAttribute('aria-live', 'polite');
+      wrapper.append(actions, status);
+    }
+    slot.replaceChildren(wrapper);
+  };
+  slots.forEach(mountControl);
+  const validateSelection = value => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Reader selection must map facets to choice lists');
+    const result = {};
+    for (const [facet, choices] of Object.entries(value)) {
+      if (!Object.hasOwn(facets, facet) || !Array.isArray(choices) || new Set(choices).size !== choices.length || choices.some(choice => typeof choice !== 'string' || !Object.hasOwn(facets[facet].options, choice))) {
+        throw new Error(`Invalid reader selection for ${facet}`);
+      }
+      if (choices.length) result[facet] = [...choices];
+    }
+    return result;
+  };
+  const knownSelection = value => {
+    try { return validateSelection(value); } catch { return {}; }
+  };
+  const parseView = value => {
+    if (value === 'all') return {};
+    if (!value) return null;
+    const selection = {};
+    for (const part of value.split(';')) {
+      const [facet, values, extra] = part.split(':');
+      if (extra !== undefined || !Object.hasOwn(facets, facet) || Object.hasOwn(selection, facet) || !values) return null;
+      selection[facet] = values.split(',');
+    }
+    try { return validateSelection(selection); } catch { return null; }
+  };
+  const formatView = selection => Object.entries(selection).filter(([, values]) => values.length).map(([facet, values]) => `${facet}:${values.join(',')}`).join(';') || 'all';
+  const matches = (required, selection) => Object.entries(required).every(([facet, values]) => !selection[facet]?.length || values.some(value => selection[facet].includes(value)));
+  const describe = selection => Object.entries(selection).flatMap(([facet, values]) => values.map(value => facets[facet].options[value]));
+  const url = new URL(location.href);
+  const fromUrl = url.searchParams.has('view') ? parseView(url.searchParams.get('view')) : null;
+  const fromPageUrl = url.searchParams.has('pageView') ? parseView(url.searchParams.get('pageView')) : null;
+  let stored = null;
+  try { stored = localStorage.getItem(config.storageKey); } catch { /* Storage may be disabled. */ }
+  let selected = knownSelection(fromUrl ?? parseView(stored) ?? {});
+  let pageOverride = fromPageUrl !== null;
+  let pageSelected = knownSelection(fromPageUrl ?? {});
+  const apply = () => {
+    const active = Object.keys(selected).length > 0;
+    const outside = active && !matches(pageFilters, selected);
+    const localSelection = pageOverride ? pageSelected : selected;
+    const localActive = Object.keys(localSelection).length > 0;
+    window.shoalrunReaderSelection = structuredClone(selected);
+    window.shoalrunReaderPageSelection = structuredClone(localSelection);
+    for (const entry of document.querySelectorAll('.nav-entry[data-reader-filters]')) {
+      entry.dataset.readerHidden = String(active && !matches(parseData(entry.dataset.readerFilters), selected));
+    }
+    for (const item of document.querySelectorAll('.reader-section, .doc-card[data-reader-filters], .related-reading li[data-reader-filters]')) {
+      item.hidden = (!outside || pageOverride) && localActive && !matches(parseData(item.dataset.readerFilters), localSelection);
+    }
+    let linkedSection = false;
+    if ((!outside || pageOverride) && location.hash) {
+      let id = location.hash.slice(1);
+      try { id = decodeURIComponent(id); } catch { /* Keep literal fragment. */ }
+      const containing = document.getElementById(id)?.closest('.reader-section[hidden]');
+      if (containing) { containing.hidden = false; linkedSection = true; }
+    }
+    if (banner) {
+      banner.hidden = !outside && !linkedSection;
+      const message = banner.querySelector('p');
+      if (message) message.textContent = linkedSection
+        ? 'This linked section is outside your current reader view. It is shown so the link still works.'
+        : pageOverride
+          ? 'This page is outside your site reader view. The page-only view is active here.'
+          : 'This page is outside your current reader view. Its full content is shown so this link still works.';
+    }
+    for (const slot of slots) {
+      const control = slot.firstElementChild;
+      const controlSelection = controlScope(slot) === 'page' ? localSelection : selected;
+      for (const field of control.querySelectorAll('[data-reader-facet]')) {
+        const values = controlSelection[field.dataset.readerFacet] ?? [];
+        const select = field.querySelector('select');
+        if (select) select.value = values.length > 1 ? '__multiple__' : values[0] ?? '';
+        for (const input of field.querySelectorAll('input[type="checkbox"]')) input.checked = values.includes(input.value);
+      }
+      const label = control.querySelector('.reader-view-label');
+      if (label) label.textContent = Object.keys(controlSelection).length ? describe(controlSelection).join(', ') : 'All content';
+    }
+    for (const choice of document.querySelectorAll('.reader-choice')) {
+      const required = parseData(choice.dataset.readerChoice);
+      const choiceSelection = choice.dataset.readerScope === 'page' ? localSelection : selected;
+      choice.setAttribute('aria-pressed', String(Object.entries(required).every(([facet, values]) => values.every(value => choiceSelection[facet]?.includes(value)))));
+    }
+    document.dispatchEvent(new CustomEvent('reader-view-change', { detail: structuredClone(selected) }));
+    document.dispatchEvent(new CustomEvent('reader-page-view-change', { detail: structuredClone(localSelection) }));
+  };
+  const choose = next => {
+    const before = formatView(selected);
+    selected = validateSelection(next);
+    try { localStorage.setItem(config.storageKey, formatView(selected)); } catch { /* View still works. */ }
+    const nextUrl = new URL(location.href);
+    nextUrl.searchParams.set('view', formatView(selected));
+    history.replaceState(history.state, '', nextUrl);
+    apply();
+    if (before !== formatView(selected)) globalThis.shoalrunAnalytics?.track('reader_filter_change', { scope: 'site', ...Object.fromEntries(Object.entries(selected).map(([key, value]) => [`filter_${key.replaceAll('-', '_')}`, value])) });
+  };
+  const choosePage = next => {
+    const changed = !pageOverride || formatView(pageSelected) !== formatView(validateSelection(next));
+    pageSelected = validateSelection(next);
+    pageOverride = true;
+    const nextUrl = new URL(location.href);
+    nextUrl.searchParams.set('pageView', formatView(pageSelected));
+    history.replaceState(history.state, '', nextUrl);
+    apply();
+    if (changed) globalThis.shoalrunAnalytics?.track('reader_filter_change', { scope: 'page', ...Object.fromEntries(Object.entries(pageSelected).map(([key, value]) => [`filter_${key.replaceAll('-', '_')}`, value])) });
+  };
+  const inheritSiteView = () => {
+    const changed = pageOverride;
+    pageOverride = false;
+    pageSelected = {};
+    const nextUrl = new URL(location.href);
+    nextUrl.searchParams.delete('pageView');
+    history.replaceState(history.state, '', nextUrl);
+    apply();
+    if (changed) globalThis.shoalrunAnalytics?.track('reader_filter_change', { scope: 'page', inherit: true });
+  };
+  if (fromUrl !== null) {
+    try { localStorage.setItem(config.storageKey, formatView(selected)); } catch { /* Optional persistence. */ }
+  } else if (stored !== null) {
+    url.searchParams.set('view', formatView(selected));
+    history.replaceState(history.state, '', url);
+  }
+  document.addEventListener('change', event => {
+    const target = event.target;
+    if (!(target instanceof HTMLInputElement || target instanceof HTMLSelectElement)) return;
+    const field = target.closest('[data-reader-filter] [data-reader-facet]');
+    if (!field) return;
+    const values = target instanceof HTMLSelectElement ? target.value ? [target.value] : []
+      : [...field.querySelectorAll('input:checked')].map(input => input.value);
+    const pageControl = controlScope(target.closest('[data-reader-filter]')) === 'page';
+    const base = pageControl ? pageOverride ? pageSelected : selected : selected;
+    (pageControl ? choosePage : choose)({ ...base, [field.dataset.readerFacet]: values });
+  });
+  document.addEventListener('click', async event => {
+    const button = event.target instanceof Element ? event.target.closest('button') : null;
+    if (!button) return;
+    if (button.matches('[data-reader-reset]')) {
+      const slot = button.closest('[data-reader-filter]');
+      (slot && controlScope(slot) === 'page' ? choosePage : choose)({});
+    }
+    else if (button.matches('[data-reader-inherit]')) inheritSiteView();
+    else if (button.matches('[data-reader-switch]')) {
+      const next = { ...selected };
+      for (const [facet, values] of Object.entries(pageFilters)) if (!next[facet]?.some(value => values.includes(value))) next[facet] = [values[0]];
+      choose(next);
+    } else if (button.matches('.reader-choice')) {
+      const pageChoice = button.dataset.readerScope === 'page';
+      (pageChoice ? choosePage : choose)({ ...(pageChoice ? pageOverride ? pageSelected : selected : selected), ...parseData(button.dataset.readerChoice) });
+    }
+    else if (button.matches('[data-reader-copy]')) {
+      const status = button.closest('[data-reader-filter]')?.querySelector('.reader-filter-status');
+      try { await navigator.clipboard.writeText(location.href); if (status) status.textContent = 'View link copied.'; }
+      catch { if (status) status.textContent = 'Copy this page’s URL to share the view.'; }
+    }
+  });
+  window.addEventListener('hashchange', apply);
+  window.addEventListener('popstate', () => {
+    const nextUrl = new URL(location.href);
+    selected = knownSelection(parseView(nextUrl.searchParams.get('view')) ?? {});
+    const nextPage = nextUrl.searchParams.has('pageView') ? parseView(nextUrl.searchParams.get('pageView')) : null;
+    pageOverride = nextPage !== null;
+    pageSelected = knownSelection(nextPage ?? {});
+    apply();
+  });
+  const api = Object.freeze({
+    facets: structuredClone(facets),
+    getSelection: () => structuredClone(selected),
+    setSelection: (next, options = {}) => choose(options.merge ? { ...selected, ...next } : next),
+    reset: () => choose({}),
+    getPageSelection: () => structuredClone(pageOverride ? pageSelected : selected),
+    setPageSelection: (next, options = {}) => choosePage(options.merge ? { ...(pageOverride ? pageSelected : selected), ...next } : next),
+    resetPage: () => choosePage({}),
+    inheritSiteView,
+    subscribe: listener => {
+      if (typeof listener !== 'function') throw new Error('Reader view listener must be a function');
+      const onChange = event => listener(structuredClone(event.detail));
+      document.addEventListener('reader-view-change', onChange);
+      listener(structuredClone(selected));
+      return () => document.removeEventListener('reader-view-change', onChange);
+    },
+    subscribePage: listener => {
+      if (typeof listener !== 'function') throw new Error('Reader page view listener must be a function');
+      const onChange = event => listener(structuredClone(event.detail));
+      document.addEventListener('reader-page-view-change', onChange);
+      listener(structuredClone(pageOverride ? pageSelected : selected));
+      return () => document.removeEventListener('reader-page-view-change', onChange);
+    },
+    shareUrl: () => {
+      const link = new URL(location.href);
+      link.searchParams.set('view', formatView(selected));
+      return link.href;
+    }
+  });
+  window.shoalrunReaderViews = api;
+  apply();
+  document.dispatchEvent(new CustomEvent('reader-views-ready', { detail: api }));
+  if (config.moduleUrl) import(config.moduleUrl).then(module => {
+    const mount = module.mountReaderViews ?? module.default;
+    if (typeof mount !== 'function') throw new Error('readerFilters.module must export mountReaderViews(api) or a default function');
+    mount(api);
+  }).catch(error => console.error('Reader view integration failed:', error));
+}

package/assets/reader.js

@@ -0,0 +1,111 @@
+const status = document.createElement('span');
+status.className = 'copy-status';
+status.setAttribute('role', 'status');
+status.setAttribute('aria-live', 'polite');
+document.body.append(status);
+
+function initializeCode(root) {
+for (const pre of root.querySelectorAll('article pre, .examples pre, .cookbook-chooser-result pre')) {
+  if (pre.dataset.copyReady) continue;
+  pre.dataset.copyReady = 'true';
+  const code = pre.querySelector('code');
+  if (!code) continue;
+  const language = [...code.classList].find(name => name.startsWith('language-'))?.slice(9);
+  const label = language ? language.toUpperCase() : 'Code';
+  const existing = pre.parentElement?.classList.contains('code-block');
+  const block = existing ? pre.parentElement : document.createElement('div');
+  const toolbar = existing ? block.querySelector(':scope > .code-toolbar') : document.createElement('div');
+  if (!existing) {
+    block.className = 'code-block';
+    toolbar.className = 'code-toolbar';
+    const title = document.createElement('span');
+    title.textContent = label;
+    toolbar.append(title);
+  }
+  pre.tabIndex = 0;
+  const heading = [...toolbar.querySelectorAll('.code-block-title, .code-block-filename')].map(item => item.textContent).filter(Boolean).join(' — ');
+  pre.setAttribute('aria-label', `${heading || label} example; scroll to read`);
+  if (!existing) {
+    pre.before(block);
+    block.append(toolbar, pre);
+  }
+
+  if (!navigator.clipboard?.writeText) continue;
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'code-copy';
+  button.textContent = 'Copy';
+  button.setAttribute('aria-label', 'Copy code example');
+  let reset;
+  button.addEventListener('click', async () => {
+    clearTimeout(reset);
+    status.textContent = '';
+    try {
+      await navigator.clipboard.writeText(code.textContent ?? '');
+      button.textContent = 'Copied';
+      status.textContent = 'Code example copied.';
+      globalThis.shoalrunAnalytics?.track('code_copy', { language: language ?? 'text' }, block);
+    } catch {
+      button.textContent = 'Try again';
+      status.textContent = 'Could not copy. Select the code and copy it manually.';
+    }
+    reset = setTimeout(() => { button.textContent = 'Copy'; }, 2500);
+  });
+  toolbar.append(button);
+}
+
+}
+initializeCode(document);
+document.addEventListener('shoalrun:content', event => initializeCode(event.detail.root));
+
+// Mark the section being read in "On this page": the last heading above the top quarter of the window.
+const tocLinks = [...document.querySelectorAll('.page-toc a[href^="#"]')];
+const sections = tocLinks.map(link => [document.getElementById(decodeURIComponent(link.hash.slice(1))), link]).filter(([heading]) => heading);
+let frame = 0;
+let current;
+const markSection = () => {
+  frame = 0;
+  const atEnd = innerHeight + scrollY >= document.documentElement.scrollHeight - 2;
+  let active = atEnd ? sections.at(-1)?.[1] : undefined;
+  if (!active) for (const [heading, link] of sections) {
+    if (heading.getBoundingClientRect().top > innerHeight / 4) break;
+    active = link;
+  }
+  if (active === current) return;
+  current?.removeAttribute('aria-current');
+  active?.setAttribute('aria-current', 'location');
+  current = active;
+};
+if (sections.length) {
+  addEventListener('scroll', () => { frame ||= requestAnimationFrame(markSection); }, { passive: true });
+  addEventListener('resize', () => { frame ||= requestAnimationFrame(markSection); }, { passive: true });
+  markSection();
+}
+
+// Section links: an icon beside each heading copies the section's URL. Without clipboard access it is an ordinary link.
+const linkIcon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>';
+for (const heading of document.querySelectorAll('article :is(h2, h3, h4)[id]')) {
+  if (heading.closest('.doc-tabs, .examples')) continue;
+  const link = document.createElement('a');
+  link.className = 'heading-anchor';
+  link.href = `#${encodeURIComponent(heading.id)}`;
+  link.setAttribute('aria-label', `Copy link to section: ${heading.textContent.trim()}`);
+  link.innerHTML = linkIcon;
+  let reset;
+  link.addEventListener('click', async event => {
+    if (!navigator.clipboard?.writeText) return;
+    event.preventDefault();
+    history.replaceState(null, '', link.hash);
+    clearTimeout(reset);
+    try {
+      await navigator.clipboard.writeText(location.href);
+      link.dataset.copied = '';
+      status.textContent = 'Link to section copied.';
+      globalThis.shoalrunAnalytics?.track('section_link_copy', { targetHeadingId: heading.id }, heading);
+    } catch {
+      status.textContent = 'Could not copy. The link is in the address bar.';
+    }
+    reset = setTimeout(() => { delete link.dataset.copied; status.textContent = ''; }, 2000);
+  });
+  heading.append(link);
+}

package/assets/search-highlight.js

@@ -0,0 +1,32 @@
+const escapeHtml = value => String(value).replace(/[&<>"]/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[char]);
+
+function pieces(value, terms) {
+  const text = String(value);
+  const alternatives = [...new Set(terms.filter(Boolean))]
+    .sort((left, right) => right.length - left.length)
+    .map(term => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  if (!alternatives.length) return [{ value: text, matched: false }];
+  const matches = new RegExp(alternatives.join('|'), 'gi');
+  const result = [];
+  let position = 0;
+  for (const match of text.matchAll(matches)) {
+    if (match.index > position) result.push({ value: text.slice(position, match.index), matched: false });
+    result.push({ value: match[0], matched: true });
+    position = match.index + match[0].length;
+  }
+  if (position < text.length) result.push({ value: text.slice(position), matched: false });
+  return result;
+}
+
+export function highlight(value, terms) {
+  return pieces(value, terms).map(piece => piece.matched ? `<mark>${escapeHtml(piece.value)}</mark>` : escapeHtml(piece.value)).join('');
+}
+
+export function appendHighlighted(target, value, terms) {
+  const document = target.ownerDocument;
+  for (const piece of pieces(value, terms)) {
+    const node = piece.matched ? document.createElement('mark') : document.createTextNode(piece.value);
+    if (piece.matched) node.textContent = piece.value;
+    target.append(node);
+  }
+}

package/assets/search-lexical.js

@@ -0,0 +1,66 @@
+// Built-in search provider: case-insensitive word and phrase matching over /search-index.json.
+// Any provider module exports the same search(query, context) function; prepare(context) is optional.
+let builtIndex = null;
+
+const fallbackStopWords = new Set('a an the i me my we our you your how do does can could would should will is are was were be to of in on for with please what where when why which some any each several'.split(' '));
+
+function phraseMatches(value, phrase) {
+  const escaped = phrase.split(' ').map(word => word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('\\s+');
+  return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}s?(?![\\p{L}\\p{N}])`, 'iu').test(value);
+}
+
+function queryUnits(query, groups) {
+  const words = query.toLocaleLowerCase().split(/\s+/).map(word => word.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '')).filter(Boolean);
+  const entries = groups.flatMap(group => group.map(term => ({ term, group, words: term.split(' ') }))).sort((a, b) => b.words.length - a.words.length);
+  const units = [];
+  for (let at = 0; at < words.length;) {
+    const found = entries.find(entry => entry.words.every((word, offset) => {
+      const actual = words[at + offset];
+      return actual === word || (offset === entry.words.length - 1 && actual === `${word}s`);
+    }));
+    if (found) {
+      units.push({ term: words.slice(at, at + found.words.length).join(' '), alternatives: found.group.filter(term => term !== found.term) });
+      at += found.words.length;
+    } else {
+      units.push({ term: words[at], alternatives: [] });
+      at++;
+    }
+  }
+  return units;
+}
+
+export async function prepare({ variant, indexUrl, signal }) {
+  builtIndex ??= fetch(indexUrl, { signal })
+    .then(response => response.ok ? response.json() : { documents: [] })
+    .catch(error => { builtIndex = null; throw error; });
+  const index = await builtIndex;
+  return { documents: index.documents.filter(doc => doc.variant === variant), synonyms: index.synonyms ?? [] };
+}
+
+// Every term must appear on the page; titles outrank summaries, headings, and body text.
+export async function search(query, context) {
+  const { documents: pages, synonyms } = await prepare(context);
+  const selected = context.readerSelection ?? {};
+  const filtered = Object.keys(selected).length > 0;
+  const matches = required => Object.entries(required ?? {}).every(([facet, values]) => !selected[facet]?.length || values.some(value => selected[facet].includes(value)));
+  const terms = queryUnits(query, synonyms);
+  if (!terms.length) return [];
+  const match = (value, unit) => phraseMatches(value, unit.term) || unit.alternatives.some(term => phraseMatches(value, term));
+  const weight = (value, unit, score) => phraseMatches(value, unit.term) ? score : unit.alternatives.some(term => phraseMatches(value, term)) ? score * 0.5 : 0;
+  const hits = [];
+  for (const doc of pages) {
+    if (filtered && !matches(doc.readerFilters)) continue;
+    const title = doc.title.toLocaleLowerCase();
+    const summary = doc.summary.toLocaleLowerCase();
+    const text = (filtered && doc.readerSegments ? doc.readerSegments.filter(segment => matches(segment.filters)).map(segment => segment.text).join(' ') : doc.text).toLocaleLowerCase();
+    const headings = filtered ? [] : doc.headings.map(heading => heading.title.toLocaleLowerCase());
+    const matched = terms.filter(term => match(title, term) || match(summary, term) || match(text, term) || headings.some(heading => match(heading, term)));
+    if (!matched.length) continue;
+    let score = 0;
+    for (const term of terms) score += weight(title, term, title.startsWith(term.term) ? 12 : 8) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(text, term, 1);
+    const section = filtered || terms.every(term => match(title, term)) ? undefined : doc.headings.find((heading, index) => terms.every(term => match(headings[index], term)));
+    hits.push({ score, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, result: { url: section ? `${doc.url}#${section.id}` : doc.url, title: doc.title, summary: doc.summary, section: section?.title } });
+  }
+  const complete = hits.filter(hit => hit.matched === terms.length);
+  return (complete.length ? complete : hits.filter(hit => hit.partialMatched > 0)).sort((a, b) => (complete.length ? b.matched - a.matched : b.partialMatched - a.partialMatched) || b.score - a.score || a.result.title.localeCompare(b.result.title)).slice(0, context.limit).map(hit => hit.result);
+}

package/assets/search.js

@@ -0,0 +1,150 @@
+// Header search box. Retrieval comes from /assets/search-provider.js, which a project can replace.
+import { appendHighlighted } from './search-highlight.js';
+const siteRoot = new URL('../', import.meta.url);
+const container = document.querySelector('.site-search');
+const input = container?.querySelector('input');
+const list = container?.querySelector('.site-search-results');
+const status = container?.querySelector('.site-search-status');
+
+if (container && input && list && status) {
+  input.placeholder = 'Search';
+  container.hidden = false;
+  const context = { variant: container.dataset.variant, language: document.documentElement.lang, indexUrl: new URL('search-index.json', siteRoot).pathname, limit: 8, readerSelection: window.shoalrunReaderSelection ?? {} };
+  let provider = null;
+  let controller = null;
+  let results = [];
+  let active = -1;
+  let analyticsTimer;
+  const outcome = properties => {
+    clearTimeout(analyticsTimer);
+    analyticsTimer = setTimeout(() => globalThis.shoalrunAnalytics?.track('search_results', properties, input), 300);
+  };
+
+  const load = () => provider ??= import('./search-provider.js').then(module => {
+    if (typeof module.search !== 'function') throw new Error('search-provider.js must export search(query, context)');
+    return module;
+  });
+  const warm = () => load().then(module => module.prepare?.(context)).catch(() => {});
+
+  const valid = result => result && typeof result.url === 'string' && typeof result.title === 'string'
+    && (result.section === undefined || typeof result.section === 'string')
+    && (result.summary === undefined || typeof result.summary === 'string')
+    && (/^\/(?![\/\\])[^\\\u0000-\u001f]*$/.test(result.url) || /^https?:\/\/[^\s\\]+$/i.test(result.url));
+
+  const setActive = index => {
+    active = index;
+    [...list.children].forEach((item, position) => item.setAttribute('aria-selected', String(position === active)));
+    if (active >= 0) {
+      input.setAttribute('aria-activedescendant', `site-search-option-${active}`);
+      list.children[active]?.scrollIntoView({ block: 'nearest' });
+    } else input.removeAttribute('aria-activedescendant');
+  };
+  const close = () => {
+    list.hidden = true;
+    input.setAttribute('aria-expanded', 'false');
+    setActive(-1);
+  };
+  const show = (items, count) => {
+    list.replaceChildren(...items);
+    status.textContent = count === null ? 'Search is unavailable' : `${count} ${count === 1 ? 'result' : 'results'}`;
+    list.hidden = false;
+    input.setAttribute('aria-expanded', 'true');
+    setActive(count ? 0 : -1);
+  };
+
+  const render = async () => {
+    clearTimeout(analyticsTimer);
+    const query = input.value.trim();
+    controller?.abort();
+    if (!query) { results = []; list.replaceChildren(); status.textContent = ''; close(); return; }
+    controller = new AbortController();
+    const signal = controller.signal;
+    try {
+      const module = await load();
+      const found = await module.search(query, { ...context, signal });
+      if (signal.aborted) return;
+      results = (Array.isArray(found) ? found : []).filter(valid).slice(0, context.limit);
+    } catch (error) {
+      if (signal.aborted) return;
+      results = [];
+      show([emptyResult('Search is unavailable right now.')], null);
+      outcome({ queryLength: query.length, resultCount: 0, status: 'error' });
+      return;
+    }
+    const terms = query.split(/\s+/).filter(Boolean);
+    show(results.length ? results.map((result, index) => resultItem(result, index, terms))
+      : [emptyResult(`No pages match “${query}”`)], results.length);
+    outcome({ queryLength: query.length, resultCount: results.length, status: results.length ? 'results' : 'empty' });
+  };
+
+  const emptyResult = message => {
+    const item = document.createElement('li');
+    item.className = 'site-search-empty';
+    item.setAttribute('role', 'presentation');
+    item.textContent = message;
+    return item;
+  };
+  const resultItem = (result, index, terms) => {
+    const item = document.createElement('li');
+    item.id = `site-search-option-${index}`;
+    item.setAttribute('role', 'option');
+    item.setAttribute('aria-selected', 'false');
+    const anchor = document.createElement('a');
+    anchor.href = result.url;
+    anchor.tabIndex = -1;
+    anchor.addEventListener('click', () => {
+      const url = new URL(anchor.href);
+      globalThis.shoalrunAnalytics?.track('search_result_click', { queryLength: input.value.trim().length, resultIndex: index, targetPath: url.pathname }, anchor);
+    });
+    const title = document.createElement('span');
+    title.className = 'search-hit-title';
+    appendHighlighted(title, result.title, terms);
+    if (result.section) {
+      const section = document.createElement('span');
+      section.className = 'search-hit-section';
+      section.append(document.createTextNode(' › '));
+      appendHighlighted(section, result.section, terms);
+      title.append(section);
+    }
+    anchor.append(title);
+    if (result.summary) {
+      const summary = document.createElement('span');
+      summary.className = 'search-hit-summary';
+      appendHighlighted(summary, result.summary, terms);
+      anchor.append(summary);
+    }
+    item.append(anchor);
+    return item;
+  };
+
+  input.addEventListener('focus', () => { warm(); if (input.value.trim()) render(); });
+  input.addEventListener('input', render);
+  document.addEventListener('reader-view-change', event => { context.readerSelection = event.detail; if (input.value.trim()) render(); });
+  input.addEventListener('keydown', event => {
+    if (event.key === 'ArrowDown' && results.length && list.hidden) {
+      // Reopen the closed list before moving through it, so aria-activedescendant never points into a hidden listbox.
+      list.hidden = false;
+      input.setAttribute('aria-expanded', 'true');
+      setActive(0);
+      event.preventDefault();
+    }
+    else if (event.key === 'ArrowDown' && results.length) { setActive((active + 1) % results.length); event.preventDefault(); }
+    else if (event.key === 'ArrowUp' && results.length && !list.hidden) { setActive((active - 1 + results.length) % results.length); event.preventDefault(); }
+    else if (event.key === 'Enter' && active >= 0 && !list.hidden) { list.children[active].querySelector('a').click(); event.preventDefault(); }
+    else if (event.key === 'Escape') {
+      if (!list.hidden) close();
+      else if (input.value) { input.value = ''; render(); }
+      else input.blur();
+      event.preventDefault();
+    }
+  });
+  document.addEventListener('pointerdown', event => { if (!container.contains(event.target)) close(); });
+  document.addEventListener('keydown', event => {
+    const typing = event.target instanceof HTMLElement && (event.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(event.target.tagName));
+    if ((event.key === '/' && !typing) || (event.key.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey))) {
+      input.focus();
+      input.select();
+      event.preventDefault();
+    }
+  });
+}