@mintfolio/core 0.1.5

package/src/client/code.ts

@@ -0,0 +1,141 @@
+/** Shared code-language labels, rendered-text extraction, and clipboard access. No UI is mounted on import. */
+const languageLabels: Record<string, string> = {
+  bash: 'Bash',
+  c: 'C',
+  cpp: 'C++',
+  csharp: 'C#',
+  cs: 'C#',
+  css: 'CSS',
+  docker: 'Docker',
+  dockerfile: 'Dockerfile',
+  go: 'Go',
+  gql: 'GraphQL',
+  graphql: 'GraphQL',
+  html: 'HTML',
+  java: 'Java',
+  javascript: 'JavaScript',
+  js: 'JavaScript',
+  json: 'JSON',
+  jsx: 'JSX',
+  kotlin: 'Kotlin',
+  kt: 'Kotlin',
+  less: 'Less',
+  markdown: 'Markdown',
+  md: 'Markdown',
+  mdx: 'MDX',
+  php: 'PHP',
+  powershell: 'PowerShell',
+  ps1: 'PowerShell',
+  py: 'Python',
+  python: 'Python',
+  rb: 'Ruby',
+  ruby: 'Ruby',
+  rs: 'Rust',
+  rust: 'Rust',
+  sass: 'Sass',
+  scss: 'SCSS',
+  shell: 'Shell',
+  sh: 'Shell',
+  sql: 'SQL',
+  svelte: 'Svelte',
+  swift: 'Swift',
+  text: 'Text',
+  toml: 'TOML',
+  ts: 'TypeScript',
+  tsx: 'TSX',
+  typescript: 'TypeScript',
+  vue: 'Vue',
+  xml: 'XML',
+  yaml: 'YAML',
+  yml: 'YAML',
+  zsh: 'Zsh',
+};
+
+export function formatLanguageLabel(language: string): string {
+  const normalized = (language ?? '').trim().toLowerCase();
+  if (!normalized) {
+    return 'Text';
+  }
+
+  if (languageLabels[normalized]) {
+    return languageLabels[normalized];
+  }
+
+  const words = normalized
+    .replace(/[._-]+/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (words.length === 0) {
+    return 'Text';
+  }
+
+  return words
+    .map((word) => {
+      if (word.length <= 4) {
+        return word.toUpperCase();
+      }
+
+      return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+    })
+    .join(' ');
+}
+
+export function resolveCodeLanguage(pre: HTMLPreElement, code: HTMLElement): string {
+  const preLanguage = pre.getAttribute('data-language') ?? pre.dataset.language;
+  if (preLanguage) {
+    return formatLanguageLabel(preLanguage);
+  }
+
+  const className = Array.from(code.classList).find((value) => value.startsWith('language-'));
+  if (className) {
+    return formatLanguageLabel(className.replace('language-', ''));
+  }
+
+  return 'Text';
+}
+
+function fallbackCopyText(text: string): boolean {
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.setAttribute('readonly', 'true');
+  textarea.style.cssText = 'position:fixed;top:-9999px;left:-9999px';
+  document.body.appendChild(textarea);
+  textarea.select();
+
+  let copied = false;
+  try {
+    copied = document.execCommand('copy');
+  } catch {
+    copied = false;
+  }
+
+  textarea.remove();
+  return copied;
+}
+
+export async function copyText(text: string): Promise<boolean> {
+  if (window.isSecureContext && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+      return fallbackCopyText(text);
+    }
+  }
+
+  return fallbackCopyText(text);
+}
+
+export function extractCodeText(code: HTMLElement, pre: HTMLPreElement): string {
+  const renderedLines = Array.from(code.children).filter((child) => child.classList?.contains('line'));
+
+  if (renderedLines.length > 0) {
+    return renderedLines
+      .map((line) => line.textContent ?? '')
+      .join('\n')
+      .replace(/\n$/, '');
+  }
+
+  return (code.textContent ?? pre.textContent ?? '').replace(/\n$/, '');
+}

package/src/client/lifecycle.ts

@@ -0,0 +1,76 @@
+export type Cleanup = () => void;
+
+/** Resources owned by one mounted page or widget; disposal is idempotent. */
+export interface PageScope {
+  readonly signal: AbortSignal;
+  add(cleanup: Cleanup): void;
+  timeout(callback: () => void, delay: number): number;
+  frame(callback: FrameRequestCallback): number;
+  dispose(): void;
+}
+
+/** Create a scope for listeners, timers, animation frames, and caller cleanups. */
+export function createPageScope(): PageScope {
+  const controller = new AbortController();
+  const cleanups: Cleanup[] = [];
+  const timers = new Set<number>();
+  const frames = new Set<number>();
+  return {
+    signal: controller.signal,
+    add(cleanup): void { if (controller.signal.aborted) cleanup(); else cleanups.push(cleanup); },
+    timeout(callback, delay): number {
+      const id = window.setTimeout(() => { timers.delete(id); if (!controller.signal.aborted) callback(); }, delay);
+      timers.add(id);
+      return id;
+    },
+    frame(callback): number {
+      const id = window.requestAnimationFrame((time) => { frames.delete(id); if (!controller.signal.aborted) callback(time); });
+      frames.add(id);
+      return id;
+    },
+    dispose(): void {
+      if (controller.signal.aborted) return;
+      controller.abort();
+      timers.forEach((id) => window.clearTimeout(id));
+      frames.forEach((id) => window.cancelAnimationFrame(id));
+      // Run every cleanup even if one widget fails; protected content must still clear.
+      const errors: unknown[] = [];
+      for (const cleanup of cleanups.reverse()) { try { cleanup(); } catch (error) { errors.push(error); } }
+      cleanups.length = 0;
+      timers.clear();
+      frames.clear();
+      if (errors.length) console.error('[mintfolio:lifecycle] Widget cleanup failed', errors);
+    },
+  };
+}
+
+/**
+ * Mount behavior on ordinary documents, Astro swaps, and BFCache restores.
+ * @param target A theme selector or a function resolving its current root.
+ * @param setup Attach behavior to that root and register cleanup with its scope.
+ * @returns Stop listening and dispose the current mount.
+ */
+export function onPage(target: string | (() => HTMLElement | null), setup: (root: HTMLElement, scope: PageScope) => void): Cleanup {
+  const lifetime = new AbortController();
+  let root: HTMLElement | null = null;
+  let scope: PageScope | null = null;
+  const dispose = (): void => { scope?.dispose(); scope = null; root = null; };
+  const mount = (): void => {
+    const next = typeof target === 'string' ? document.querySelector<HTMLElement>(target) : target();
+    if (root === next) return;
+    dispose();
+    if (!next) return;
+    root = next;
+    scope = createPageScope();
+    setup(root, scope);
+  };
+  const options = { signal: lifetime.signal };
+  document.addEventListener('astro:before-swap', dispose, options);
+  document.addEventListener('astro:page-load', mount, options);
+  document.addEventListener('article:content-changed', mount, options);
+  window.addEventListener('pagehide', dispose, options);
+  window.addEventListener('pageshow', mount, options);
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mount, { ...options, once: true });
+  else mount();
+  return (): void => { lifetime.abort(); dispose(); };
+}

package/src/client/lightbox.ts

@@ -0,0 +1,163 @@
+import { createPageScope, type Cleanup } from './lifecycle.js';
+
+/** Theme-owned image-preview elements. Core supplies zoom, pan, keyboard and cleanup behavior. */
+export interface LightboxOptions {
+  root: HTMLElement;
+  dialog: HTMLDialogElement;
+  image: HTMLImageElement;
+  viewport: HTMLElement;
+  zoomIn: HTMLButtonElement;
+  zoomOut: HTMLButtonElement;
+  zoomLevel: HTMLOutputElement;
+  reset: HTMLElement;
+  close?: HTMLElement | null;
+  minScale?: number;
+  maxScale?: number;
+  step?: number;
+  signal?: AbortSignal;
+}
+
+export interface LightboxController { close(): void; reset(): void; dispose: Cleanup; }
+
+/** Mount one preview; linked article images keep their original navigation. */
+export function createLightboxController(input: LightboxOptions): LightboxController {
+  const { root, dialog, image, viewport, zoomIn, zoomOut, zoomLevel, reset } = input;
+  const scope = createPageScope();
+  const options = { signal: scope.signal };
+  const minScale = input.minScale ?? 0.5;
+  const maxScale = input.maxScale ?? 4;
+  const step = input.step ?? 0.25;
+  if (![minScale, maxScale, step].every((value) => Number.isFinite(value) && value > 0) || minScale > 1 || maxScale < 1) {
+    throw new Error('Lightbox scale bounds must include 1 and the step must be positive and finite');
+  }
+  let scale = 1;
+  let x = 0;
+  let y = 0;
+  let drag: { id: number; clientX: number; clientY: number; x: number; y: number } | null = null;
+
+  const render = (): void => {
+    const maxX = Math.max(0, (image.offsetWidth * scale - viewport.clientWidth) / 2);
+    const maxY = Math.max(0, (image.offsetHeight * scale - viewport.clientHeight) / 2);
+    x = Math.max(-maxX, Math.min(maxX, x));
+    y = Math.max(-maxY, Math.min(maxY, y));
+    image.style.transform = `translate(${x}px, ${y}px) scale(${scale})`;
+    image.style.cursor = maxX || maxY ? (drag ? 'grabbing' : 'grab') : 'default';
+    zoomLevel.value = `${Math.round(scale * 100)}%`;
+    zoomIn.disabled = scale >= maxScale;
+    zoomOut.disabled = scale <= minScale;
+  };
+
+  const stopDragging = (): void => {
+    const pointerId = drag?.id;
+    drag = null;
+    if (pointerId !== undefined && image.hasPointerCapture(pointerId)) image.releasePointerCapture(pointerId);
+    render();
+  };
+
+  const resetView = (): void => {
+    scale = 1;
+    x = 0;
+    y = 0;
+    stopDragging();
+  };
+
+  const setScale = (value: number): void => {
+    const next = Math.max(minScale, Math.min(maxScale, value));
+    x *= next / scale;
+    y *= next / scale;
+    scale = next;
+    render();
+  };
+
+  zoomIn.addEventListener('click', () => setScale(scale + step), options);
+  zoomOut.addEventListener('click', () => setScale(scale - step), options);
+  reset.addEventListener('click', resetView, options);
+  image.addEventListener('load', render, options);
+  window.addEventListener('resize', () => { if (dialog.open) render(); }, options);
+  viewport.addEventListener('wheel', (event) => {
+    event.preventDefault();
+    if (event.deltaY) setScale(scale - Math.sign(event.deltaY) * step);
+  }, { ...options, passive: false });
+  dialog.addEventListener('keydown', (event) => {
+    if (event.ctrlKey || event.metaKey || event.altKey) return;
+    if (['+', '=', '-', '0'].includes(event.key)) {
+      event.preventDefault();
+      if (event.key === '0') resetView();
+      else setScale(scale + (event.key === '-' ? -step : step));
+    }
+  }, options);
+
+  image.addEventListener('pointerdown', (event) => {
+    if (!event.isPrimary || event.button !== 0 || scale <= 1) return;
+    event.preventDefault();
+    drag = { id: event.pointerId, clientX: event.clientX, clientY: event.clientY, x, y };
+    image.setPointerCapture(event.pointerId);
+    render();
+  }, options);
+  image.addEventListener('pointermove', (event) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    x = drag.x + event.clientX - drag.clientX;
+    y = drag.y + event.clientY - drag.clientY;
+    render();
+  }, options);
+  image.addEventListener('pointerup', stopDragging, options);
+  image.addEventListener('pointercancel', stopDragging, options);
+  image.addEventListener('lostpointercapture', stopDragging, options);
+
+  for (const source of root.querySelectorAll('img')) {
+    // Linked images retain their author's navigation behavior.
+    if (source.closest('a')) continue;
+    const attributes = ['tabindex', 'role', 'aria-haspopup', 'aria-label'].map((name) => [name, source.getAttribute(name)] as const);
+    const cursor = source.style.cursor;
+    scope.add(() => {
+      for (const [name, value] of attributes) {
+        if (value === null) source.removeAttribute(name); else source.setAttribute(name, value);
+      }
+      source.style.cursor = cursor;
+    });
+    source.tabIndex = 0;
+    source.setAttribute('role', 'button');
+    source.setAttribute('aria-haspopup', 'dialog');
+    source.setAttribute('aria-label', `放大图片：${source.alt || '文章插图'}`);
+    source.style.cursor = 'zoom-in';
+    const open = (): void => {
+      image.src = source.currentSrc || source.src;
+      image.alt = source.alt;
+      dialog.showModal();
+      resetView();
+    };
+    source.addEventListener('click', open, options);
+    source.addEventListener(
+      'keydown',
+      (event) => {
+        if (['Enter', ' '].includes(event.key)) {
+          event.preventDefault();
+          open();
+        }
+      },
+      options,
+    );
+  }
+  input.close?.addEventListener('click', () => dialog.close(), options);
+  dialog.addEventListener(
+    'click',
+    (event) => {
+      if (event.target === dialog || event.target === viewport) dialog.close();
+    },
+    options,
+  );
+  const clearImage = (): void => {
+    image.removeAttribute('src');
+    image.alt = '图片预览';
+    resetView();
+  };
+  dialog.addEventListener('close', clearImage, options);
+  scope.add(() => {
+    dialog.close();
+    clearImage();
+  });
+  input.signal?.addEventListener('abort', scope.dispose, { once: true });
+  scope.add(() => input.signal?.removeEventListener('abort', scope.dispose));
+  if (input.signal?.aborted) scope.dispose();
+  return { close: () => dialog.close(), reset: resetView, dispose: scope.dispose };
+}

package/src/client/navigation.ts

@@ -0,0 +1,46 @@
+export interface ResolveStoredArticleBackHrefInput {
+  /** Optional saved list URL, including its filter query and content anchor. */
+  storedHref: string | null;
+  currentPath: string;
+  currentOrigin: string;
+  /** The archive destination injected by Core into this page's document. */
+  fallbackHref: string;
+}
+
+/**
+ * Return a saved same-origin list destination or Core's archive URL. Reject
+ * external targets and self-navigation without knowing the host's route shape.
+ */
+export function resolveStoredArticleBackHref({
+  storedHref, currentPath, currentOrigin, fallbackHref,
+}: ResolveStoredArticleBackHrefInput): string {
+  if (!storedHref) return fallbackHref;
+  try {
+    const target = new URL(storedHref, currentOrigin);
+    if (target.origin !== currentOrigin || target.pathname === currentPath) return fallbackHref;
+    return `${target.pathname}${target.search}${target.hash}`;
+  } catch {
+    return fallbackHref;
+  }
+}
+
+export interface ShouldPersistArticleBackHrefInput {
+  linkHref: string;
+  currentOrigin: string;
+  currentPath: string;
+  /** Only links rendered from public PostSummary.url carry this theme marker. */
+  isArticleLink: boolean;
+}
+
+/** Save list position only when the visitor follows an internal article link. */
+export function shouldPersistArticleBackHref({
+  linkHref, currentOrigin, currentPath, isArticleLink,
+}: ShouldPersistArticleBackHrefInput): boolean {
+  if (!isArticleLink) return false;
+  try {
+    const target = new URL(linkHref, currentOrigin);
+    return target.origin === currentOrigin && target.pathname !== currentPath;
+  } catch {
+    return false;
+  }
+}

package/src/client/postList.ts

@@ -0,0 +1,92 @@
+import { emptyFilters, searchPosts } from '@mintfolio/theme-api/search';
+import type { PostFilters, SearchEntry } from '@mintfolio/theme-api';
+import type { Cleanup } from './lifecycle.js';
+
+/** Filtered content and pagination state; UI structure is entirely caller-owned. */
+export interface PostListState<T> {
+  filters: PostFilters;
+  matches: T[];
+  visible: T[];
+  total: number;
+  limit: number;
+  hasMore: boolean;
+  /** Facets ignore q, matching the blog's existing taxonomy navigation behavior. */
+  facets: { tags: string[]; categories: string[] };
+}
+
+export interface PostListOptions<T> {
+  /** Safe public DTOs or theme models derived exclusively from those DTOs. */
+  items: readonly T[];
+  /** Map each model to Core's normalized public search fields. Called once. */
+  index: (item: T) => SearchEntry;
+  initialFilters?: Partial<PostFilters>;
+  pageSize?: number;
+  initialLimit?: number;
+  /** Optional radio-group UX: clear a selection made unavailable by the other facet. */
+  reconcileFacets?: boolean;
+}
+
+/** No DOM, storage, history, sorting policy, or theme classes are hidden here. */
+export interface PostListController<T> {
+  value(): PostListState<T>;
+  setFilters(filters: Partial<PostFilters>): void;
+  loadMore(): void;
+  setLimit(limit: number): void;
+  subscribe(listener: (state: PostListState<T>) => void): Cleanup;
+  dispose(): void;
+}
+
+function positiveInteger(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`${field} must be a positive safe integer`);
+  return value;
+}
+
+/**
+ * Shared search, combined tag/category filtering, facets, and load-more state.
+ * @returns A controller whose subscriptions receive the initial state immediately.
+ */
+export function createPostListController<T>(options: PostListOptions<T>): PostListController<T> {
+  const indexed = options.items.map((item) => ({ ...options.index(item), item }));
+  const pageSize = positiveInteger(options.pageSize ?? (indexed.length || 1), 'pageSize');
+  let limit = positiveInteger(options.initialLimit ?? pageSize, 'initialLimit');
+  let filters: PostFilters = { ...emptyFilters(), ...options.initialFilters };
+  if (Object.values(filters).some((item) => typeof item !== 'string')) throw new Error('Filters must be strings');
+  let disposed = false;
+  const listeners = new Set<(state: PostListState<T>) => void>();
+  const facets = (): PostListState<T>['facets'] => ({
+    tags: [...new Set(searchPosts(indexed, { category: filters.category }).flatMap((entry) => entry.tags))],
+    categories: [...new Set(searchPosts(indexed, { tag: filters.tag }).map((entry) => entry.category))],
+  });
+  const reconcile = (): void => {
+    if (!options.reconcileFacets) return;
+    if (filters.tag && !facets().tags.includes(filters.tag.toLowerCase())) filters.tag = '';
+    if (filters.category && !facets().categories.includes(filters.category.toLowerCase())) filters.category = '';
+  };
+  reconcile();
+  const value = (): PostListState<T> => {
+    const matches = searchPosts(indexed, filters).map((entry) => entry.item);
+    return { filters: { ...filters }, matches, visible: matches.slice(0, limit), total: matches.length, limit, hasMore: matches.length > limit, facets: facets() };
+  };
+  const emit = (): void => { if (!disposed) for (const listener of listeners) listener(value()); };
+  return {
+    value,
+    setFilters(next): void {
+      if (disposed) return;
+      const changed = { ...filters, ...next };
+      if (Object.values(changed).some((item) => typeof item !== 'string')) throw new Error('Filters must be strings');
+      if (changed.q !== filters.q || changed.tag !== filters.tag || changed.category !== filters.category) limit = pageSize;
+      filters = changed;
+      reconcile();
+      emit();
+    },
+    loadMore(): void { if (!disposed) { limit = Math.min(Number.MAX_SAFE_INTEGER, limit + pageSize); emit(); } },
+    setLimit(next): void { if (!disposed) { limit = positiveInteger(next, 'limit'); emit(); } },
+    subscribe(listener): Cleanup {
+      if (disposed) return () => {};
+      listeners.add(listener);
+      listener(value());
+      return (): void => { listeners.delete(listener); };
+    },
+    dispose(): void { disposed = true; listeners.clear(); },
+  };
+}

package/src/client/protectedArticle.ts

@@ -0,0 +1,80 @@
+import { unlockArticle, type ArticleUnlockError, type UnlockedArticle } from '@mintfolio/theme-api/client';
+import type { Cleanup } from './lifecycle.js';
+
+export type ProtectedArticleStatus = 'locked' | 'unlocking' | 'unlocked';
+
+/** The theme owns DOM rendering; Core owns the short-lived unlock operation. */
+export interface ProtectedArticleOptions {
+  postId: string;
+  payload: unknown;
+  /** Mount the returned fragment once; do not persist or retain plaintext. */
+  onUnlock(content: UnlockedArticle): void;
+  /** Clear article nodes, TOC nodes, preview images, password values and error UI. */
+  onClear(): void;
+  onState?(state: ProtectedArticleStatus): void;
+  onError?(error: ArticleUnlockError | Error): void;
+  signal?: AbortSignal;
+}
+
+export interface ProtectedArticleController {
+  /** Returns false if disposed, already busy, rejected, or superseded by a lock. */
+  unlock(password: string): Promise<boolean>;
+  lock(): void;
+  dispose: Cleanup;
+}
+
+/**
+ * Own authentication races and navigation cleanup once for all themes. No secret
+ * enters storage, history, callbacks other than onUnlock, or error messages.
+ */
+export function createProtectedArticleController(options: ProtectedArticleOptions): ProtectedArticleController {
+  let generation = 0;
+  let disposed = false;
+  let busy = false;
+  let active = true;
+  const lifetime = new AbortController();
+  const lock = (): void => {
+    generation += 1;
+    busy = false;
+    options.onClear();
+    options.onState?.('locked');
+  };
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    lifetime.abort();
+    options.signal?.removeEventListener('abort', dispose);
+    lock();
+  };
+  window.addEventListener('pagehide', () => { active = false; lock(); }, { signal: lifetime.signal });
+  window.addEventListener('pageshow', () => { active = true; lock(); }, { signal: lifetime.signal });
+  document.addEventListener('astro:before-swap', dispose, { signal: lifetime.signal });
+  options.signal?.addEventListener('abort', dispose, { once: true });
+  if (options.signal?.aborted) dispose();
+  return {
+    async unlock(password): Promise<boolean> {
+      if (disposed || !active || busy || !password) return false;
+      const operation = ++generation;
+      busy = true;
+      options.onState?.('unlocking');
+      try {
+        const content = await unlockArticle(options.payload, password, options.postId);
+        if (disposed || !active || operation !== generation) return false;
+        options.onUnlock(content);
+        options.onState?.('unlocked');
+        return true;
+      } catch (error) {
+        if (disposed || !active || operation !== generation) return false;
+        // Also clear any partial mount if the theme's onUnlock callback fails.
+        options.onClear();
+        options.onState?.('locked');
+        options.onError?.(error instanceof Error ? error : new Error('Article unlocking failed'));
+        return false;
+      } finally {
+        if (operation === generation) busy = false;
+      }
+    },
+    lock,
+    dispose,
+  };
+}

package/src/client/toc.ts

@@ -0,0 +1,90 @@
+import { createPageScope, type Cleanup } from './lifecycle.js';
+
+/** Element references make TOC behavior independent of layout and class names. */
+export interface TocOptions {
+  headings: readonly HTMLElement[];
+  links?: readonly HTMLAnchorElement[];
+  /** Sticky header offset in pixels; use a function for responsive layouts. */
+  offset?: number | (() => number);
+  activeClass?: string;
+  scrollActiveLink?: boolean;
+  onActive?(headingId: string): void;
+  /** Document reading progress from 0 to 100. */
+  onProgress?(percentage: number): void;
+  onNavigate?(headingId: string): void;
+  signal?: AbortSignal;
+}
+
+export interface TocController {
+  refresh(): void;
+  scrollTo(headingId: string): void;
+  dispose: Cleanup;
+}
+
+/** Track headings and navigate without adding a history entry for each section. */
+export function createTocController(options: TocOptions): TocController {
+  const scope = createPageScope();
+  let activeId = '';
+  let pending = false;
+  const offset = (): number => typeof options.offset === 'function' ? options.offset() : options.offset ?? 0;
+  const headingFor = (link: HTMLAnchorElement): HTMLElement | undefined => {
+    let id: string;
+    try { id = decodeURIComponent(new URL(link.href).hash.slice(1)); } catch { return undefined; }
+    return options.headings.find((heading) => heading.id === id);
+  };
+  const setActive = (id: string): void => {
+    if (!id || activeId === id) return;
+    activeId = id;
+    for (const link of options.links ?? []) {
+      const active = headingFor(link)?.id === id;
+      if (options.activeClass) link.classList.toggle(options.activeClass, active);
+      if (active) {
+        link.setAttribute('aria-current', 'true');
+        if (options.scrollActiveLink) link.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      } else link.removeAttribute('aria-current');
+    }
+    options.onActive?.(id);
+  };
+  const refresh = (): void => {
+    if (scope.signal.aborted) return;
+    const entries = options.headings.filter((heading) => heading.isConnected);
+    let current: HTMLElement | undefined = entries[0];
+    let nearest = Infinity;
+    for (const heading of entries) {
+      const distance = heading.getBoundingClientRect().top - offset();
+      if (distance <= 0 && Math.abs(distance) < nearest) { nearest = Math.abs(distance); current = heading; }
+    }
+    const height = document.documentElement.scrollHeight - window.innerHeight;
+    if (window.scrollY >= height - 50) current = entries.at(-1);
+    if (current) setActive(current.id);
+    options.onProgress?.(height > 0 ? Math.max(0, Math.min(100, window.scrollY / height * 100)) : 0);
+  };
+  const schedule = (): void => {
+    if (pending) return;
+    pending = true;
+    scope.frame(() => { pending = false; refresh(); });
+  };
+  const scrollTo = (id: string): void => {
+    const heading = options.headings.find((entry) => entry.id === id);
+    if (!heading || scope.signal.aborted) return;
+    window.scrollTo({ top: heading.getBoundingClientRect().top + window.scrollY - offset(), behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' });
+    const url = new URL(location.href);
+    url.hash = id;
+    history.replaceState(history.state, '', url);
+    setActive(id);
+    options.onNavigate?.(id);
+  };
+  for (const link of options.links ?? []) link.addEventListener('click', (event) => {
+    const heading = headingFor(link);
+    if (!heading) return;
+    event.preventDefault();
+    scrollTo(heading.id);
+  }, { signal: scope.signal });
+  window.addEventListener('scroll', schedule, { signal: scope.signal, passive: true });
+  window.addEventListener('resize', schedule, { signal: scope.signal });
+  options.signal?.addEventListener('abort', scope.dispose, { once: true });
+  scope.add(() => options.signal?.removeEventListener('abort', scope.dispose));
+  if (options.signal?.aborted) scope.dispose();
+  else schedule();
+  return { refresh, scrollTo, dispose: scope.dispose };
+}