@bauer-group/accessibility-widget 1.0.3

package/dist/util/language-names.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Native language labels for the runtime language switcher.
+ *
+ * Each entry is the language's endonym (its own native name), not a localized
+ * translation. Showing "Deutsch" to a Japanese reader is more useful than
+ * "German" — the user who needs German will recognise their own word for it.
+ *
+ * The autonym pattern also sidesteps N×N translation matrices.
+ */
+import type { Locale } from '../types/index.js';
+export declare const LANGUAGE_NAMES: Record<Locale, string>;
+//# sourceMappingURL=language-names.d.ts.map

package/dist/util/language-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-names.d.ts","sourceRoot":"","sources":["../../src/util/language-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA6BjD,CAAC"}

package/dist/util/svg.d.ts

@@ -0,0 +1,38 @@
+export interface SvgPath {
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number | string;
+}
+export interface SvgCircle {
+    cx: number;
+    cy: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number | string;
+}
+export interface SvgIconOptions {
+    viewBox?: string;
+    width?: number;
+    height?: number;
+    paths?: readonly SvgPath[];
+    circles?: readonly SvgCircle[];
+    /**
+     * Lucide-style outline icon. Applies fill:none, stroke:currentColor,
+     * stroke-width:2, round caps/joins at the <svg> root, so individual
+     * paths/circles don't need to repeat these attributes.
+     */
+    stroke?: boolean;
+    ariaHidden?: boolean;
+}
+/**
+ * Build an SVG element programmatically — no innerHTML, no DOMParser,
+ * so no XSS surface even if path data ever comes from config.
+ */
+export declare function buildIcon(opts: SvgIconOptions): SVGSVGElement;
+/** Accessibility person icon (BFSG signature icon). */
+export declare const ICON_ACCESSIBILITY: SvgIconOptions;
+/** Close / X icon (Lucide: x). */
+export declare const ICON_CLOSE: SvgIconOptions;
+//# sourceMappingURL=svg.d.ts.map

package/dist/util/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../../src/util/svg.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAsC7D;AAED,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,EAAE,cAOhC,CAAC;AAEF,kCAAkC;AAClC,eAAO,MAAM,UAAU,EAAE,cAIxB,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@bauer-group/accessibility-widget",
+  "version": "1.0.3",
+  "description": "Lazy-loading Accessibility-Widget nach BFSG/EN 301 549/WCAG 2.2 AA. Loader ~4 KB gzip, Core ~14 KB gzip. Kein Tracking, kein Cookie, kein DOM-/ARIA-Override.",
+  "license": "AGPL-3.0-only",
+  "author": "BAUER GROUP <info@bauer-group.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bauer-group/SaaS-AccessibilityWidget.git",
+    "directory": "packages/widget"
+  },
+  "homepage": "https://github.com/bauer-group/SaaS-AccessibilityWidget/tree/main/packages/widget",
+  "type": "module",
+  "main": "./dist/accessibility-widget-loader.min.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/accessibility-widget-loader.min.js"
+    },
+    "./loader": "./dist/accessibility-widget-loader.min.js",
+    "./core": "./dist/accessibility-widget-core.min.js",
+    "./styles": "./dist/accessibility-widget.min.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.ts && tsc -p tsconfig.build.json",
+    "dev": "tsx scripts/build.ts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "size": "tsx scripts/measure-size.ts",
+    "clean": "rimraf dist coverage"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "^0.25.0",
+    "jsdom": "^26.0.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "bfsg",
+    "wcag",
+    "wcag2.2",
+    "en301549",
+    "eaa",
+    "widget",
+    "lazy-loading",
+    "barrierefreiheit"
+  ]
+}

package/src/config.ts

@@ -0,0 +1,213 @@
+import {
+  FEATURE_IDS,
+  POSITIONS,
+  type FeatureId,
+  type WidgetConfig,
+  type Position,
+} from './types/widget.js';
+import type { Locale } from './types/locale.js';
+import { normalizeLocale, isLocale } from './types/index.js';
+import { warnIfDebug } from './util/debug.js';
+
+/**
+ * Fully-resolved config with no optional fields — every loader / panel /
+ * feature call site can rely on the presence of every key.
+ */
+export interface ResolvedConfig {
+  corePath: string;
+  cssPath: string;
+  coreIntegrity: string | null;
+  cssIntegrity: string | null;
+  locale: Locale;
+  position: Position;
+  offset: { x: number; y: number };
+  zIndex: number;
+  primaryColor: string;
+  buttonLabel: string | null;
+  storageKey: string;
+  initialFeatures: Readonly<Partial<Record<FeatureId, boolean>>>;
+  disabledFeatures: ReadonlySet<FeatureId>;
+  statementUrl: string | null;
+  disclaimer: string | null;
+  hidePoweredBy: boolean;
+  draggableFab: boolean;
+  respectReducedMotion: boolean;
+  hideOnPrint: boolean;
+  debug: boolean;
+}
+
+const DEFAULTS = {
+  corePath: '/accessibility-widget/accessibility-widget-core.min.js',
+  cssPath: '/accessibility-widget/accessibility-widget.min.css',
+  position: 'bottom-right' as Position,
+  offset: { x: 20, y: 20 },
+  zIndex: 2_147_483_646,
+  primaryColor: '#0058a3',
+  storageKey: 'accessibility-widget',
+  draggableFab: false,
+  respectReducedMotion: true,
+  hideOnPrint: true,
+  debug: false,
+} as const;
+
+// Accepts #rgb, #rrggbb, #rrggbbaa, rgb/rgba/hsl/hsla/color() functional forms,
+// and named colors (anything CSS accepts). For the primaryColor field we
+// want ANY valid CSS color, so the regex is permissive — just not empty.
+const NON_TRIVIAL_COLOR_RE =
+  /^(?:#[0-9a-f]{3,8}|(?:rgb|rgba|hsl|hsla|color|lab|lch|oklab|oklch)\s*\(.+\)|[a-z]+)$/i;
+
+export function resolveConfig(input: WidgetConfig | undefined, navLang: string): ResolvedConfig {
+  const cfg = input ?? {};
+  const debug = cfg.debug ?? DEFAULTS.debug;
+
+  return {
+    corePath: cfg.corePath ?? DEFAULTS.corePath,
+    cssPath: cfg.cssPath ?? DEFAULTS.cssPath,
+    coreIntegrity: cfg.coreIntegrity ?? null,
+    cssIntegrity: cfg.cssIntegrity ?? null,
+    locale: resolveLocale(cfg.locale, navLang, debug),
+    position: resolvePosition(cfg.position, debug),
+    offset: resolveOffset(cfg.offset, debug),
+    zIndex: resolveZIndex(cfg.zIndex, debug),
+    primaryColor: resolvePrimaryColor(cfg.primaryColor, debug),
+    buttonLabel: cfg.buttonLabel ?? null,
+    storageKey: resolveStorageKey(cfg.storageKey, debug),
+    initialFeatures: resolveInitialFeatures(cfg.initialFeatures, debug),
+    disabledFeatures: resolveDisabledFeatures(cfg.disabledFeatures, debug),
+    statementUrl: resolveStatementUrl(cfg.statementUrl, debug),
+    disclaimer: resolveDisclaimer(cfg.disclaimer),
+    hidePoweredBy: Boolean(cfg.hidePoweredBy),
+    draggableFab: cfg.draggableFab ?? DEFAULTS.draggableFab,
+    respectReducedMotion: cfg.respectReducedMotion ?? DEFAULTS.respectReducedMotion,
+    hideOnPrint: cfg.hideOnPrint ?? DEFAULTS.hideOnPrint,
+    debug,
+  };
+}
+
+// ─── individual field resolvers ──────────────────────────────────────
+
+function resolveLocale(requested: WidgetConfig['locale'], navLang: string, debug: boolean): Locale {
+  if (!requested || requested === 'auto') return normalizeLocale(navLang, 'de');
+  if (isLocale(requested)) return requested;
+  if (debug)
+    warnIfDebug(
+      `config.locale "${String(requested)}" is not supported; falling back to auto-detect`,
+    );
+  return normalizeLocale(navLang, 'de');
+}
+
+function resolvePosition(requested: WidgetConfig['position'], debug: boolean): Position {
+  if (!requested) return DEFAULTS.position;
+  if ((POSITIONS as readonly string[]).includes(requested)) return requested;
+  if (debug)
+    warnIfDebug(
+      `config.position "${String(requested)}" is not one of ${POSITIONS.join(', ')}; using default`,
+    );
+  return DEFAULTS.position;
+}
+
+function resolveOffset(
+  requested: WidgetConfig['offset'],
+  debug: boolean,
+): { x: number; y: number } {
+  if (!requested) return { ...DEFAULTS.offset };
+  const x = finiteOr(requested.x, DEFAULTS.offset.x, 'config.offset.x', debug);
+  const y = finiteOr(requested.y, DEFAULTS.offset.y, 'config.offset.y', debug);
+  return { x, y };
+}
+
+function resolveZIndex(requested: WidgetConfig['zIndex'], debug: boolean): number {
+  return finiteOr(requested, DEFAULTS.zIndex, 'config.zIndex', debug);
+}
+
+function resolvePrimaryColor(requested: WidgetConfig['primaryColor'], debug: boolean): string {
+  if (requested === undefined) return DEFAULTS.primaryColor;
+  const trimmed = String(requested).trim();
+  if (!trimmed) {
+    if (debug) warnIfDebug('config.primaryColor is empty; using default');
+    return DEFAULTS.primaryColor;
+  }
+  if (!NON_TRIVIAL_COLOR_RE.test(trimmed)) {
+    if (debug)
+      warnIfDebug(
+        `config.primaryColor "${trimmed}" does not look like a CSS color; browsers may reject it`,
+      );
+  }
+  return trimmed;
+}
+
+function resolveStorageKey(requested: WidgetConfig['storageKey'], debug: boolean): string {
+  if (requested === undefined) return DEFAULTS.storageKey;
+  const trimmed = String(requested).trim();
+  if (!trimmed) {
+    if (debug) warnIfDebug('config.storageKey is empty; using default');
+    return DEFAULTS.storageKey;
+  }
+  return trimmed;
+}
+
+function resolveInitialFeatures(
+  requested: WidgetConfig['initialFeatures'],
+  debug: boolean,
+): Readonly<Partial<Record<FeatureId, boolean>>> {
+  if (!requested) return Object.freeze({});
+  const valid: Partial<Record<FeatureId, boolean>> = {};
+  const validIds = new Set<string>(FEATURE_IDS);
+  for (const [key, value] of Object.entries(requested)) {
+    if (!validIds.has(key)) {
+      if (debug) warnIfDebug(`config.initialFeatures: unknown feature id "${key}" ignored`);
+      continue;
+    }
+    valid[key as FeatureId] = Boolean(value);
+  }
+  return Object.freeze(valid);
+}
+
+function resolveDisabledFeatures(
+  requested: WidgetConfig['disabledFeatures'],
+  debug: boolean,
+): ReadonlySet<FeatureId> {
+  if (!requested) return new Set();
+  const result = new Set<FeatureId>();
+  const validIds = new Set<string>(FEATURE_IDS);
+  for (const id of requested) {
+    if (!validIds.has(id)) {
+      if (debug) warnIfDebug(`config.disabledFeatures: unknown feature id "${id}" ignored`);
+      continue;
+    }
+    result.add(id);
+  }
+  return result;
+}
+
+function resolveDisclaimer(requested: WidgetConfig['disclaimer']): string | null {
+  if (requested === undefined || requested === null) return null;
+  const trimmed = String(requested).trim();
+  return trimmed || null;
+}
+
+function resolveStatementUrl(
+  requested: WidgetConfig['statementUrl'],
+  debug: boolean,
+): string | null {
+  if (!requested) return null;
+  const trimmed = String(requested).trim();
+  if (!trimmed) return null;
+  // A best-effort sanity check: block javascript: / data: schemes to avoid
+  // footguns when the host interpolates user input.
+  if (/^\s*(?:javascript|data):/i.test(trimmed)) {
+    if (debug) warnIfDebug(`config.statementUrl "${trimmed}" uses a blocked scheme; ignoring`);
+    return null;
+  }
+  return trimmed;
+}
+
+function finiteOr(value: unknown, fallback: number, label: string, debug: boolean): number {
+  if (value === undefined || value === null) return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) {
+    if (debug) warnIfDebug(`${label} "${String(value)}" is not a finite number; using ${fallback}`);
+    return fallback;
+  }
+  return n;
+}

package/src/core.ts

@@ -0,0 +1,173 @@
+/*!
+ * BAUER GROUP Accessibility Widget — Core (on-demand bundle)
+ * SPDX-License-Identifier: AGPL-3.0-only · © 2026 BAUER GROUP
+ * AGPL-3.0-only or commercial (info@bauer-group.com) — see LICENSE / LICENSING.md
+ */
+import {
+  isLocale,
+  PROFILE_IDS,
+  type Locale,
+  type ProfileId,
+  type WidgetConfig,
+  type WidgetState,
+} from './types/index.js';
+import { resolveConfig, type ResolvedConfig } from './config.js';
+import { applyState } from './features/apply.js';
+import { applyProfile } from './features/profile.js';
+import { loadState, saveState, clearState } from './state.js';
+import { openPanel, type PanelHandle } from './panel/panel.js';
+import { dispatchWidgetEvent } from './util/events.js';
+
+export interface CoreOpenOptions {
+  trigger?: HTMLElement;
+  config?: WidgetConfig;
+  locale?: Locale | 'auto';
+  statementUrl?: string;
+}
+
+let panel: PanelHandle | null = null;
+let lastTrigger: HTMLElement | null = null;
+
+/**
+ * Read the host-supplied config from window every time (over reading it
+ * once at module load) so late mutations — e.g. SPA navigation that rewrites
+ * AccessibilityWidgetConfig — are honored.
+ */
+function readUserConfig(): WidgetConfig {
+  if (typeof window === 'undefined') return {};
+  return window.AccessibilityWidgetConfig ?? {};
+}
+
+function resolveActiveLocale(
+  config: ResolvedConfig,
+  state: WidgetState,
+  explicit?: Locale | 'auto',
+): Locale {
+  if (explicit && explicit !== 'auto' && isLocale(explicit)) return explicit;
+  if (state.locale && isLocale(state.locale)) return state.locale;
+  return config.locale;
+}
+
+function open(opts: CoreOpenOptions = {}): void {
+  if (panel) return;
+  const mergedInput: WidgetConfig = {
+    ...readUserConfig(),
+    ...(opts.config ?? {}),
+    ...(opts.locale && opts.locale !== 'auto' ? { locale: opts.locale } : {}),
+  };
+  const config: ResolvedConfig = resolveConfig(mergedInput, navigator.language);
+  const state = loadState(config.storageKey);
+  const locale: Locale = resolveActiveLocale(config, state, opts.locale);
+
+  lastTrigger = opts.trigger ?? (document.activeElement as HTMLElement | null);
+  applyState(state);
+
+  panel = openPanel({
+    config,
+    locale,
+    state,
+    // opts.statementUrl wins over config.statementUrl — covers the
+    // "open the widget with a one-off statement link" edge case.
+    statementUrl: opts.statementUrl ?? config.statementUrl ?? undefined,
+    onClose: close,
+    onStateChange: (next) => {
+      dispatchWidgetEvent('stateChange', { state: next });
+    },
+  });
+  dispatchWidgetEvent('open', { trigger: lastTrigger });
+}
+
+function close(): void {
+  panel?.destroy();
+  panel = null;
+  lastTrigger?.focus();
+  lastTrigger = null;
+  dispatchWidgetEvent('close', {});
+}
+
+function set(id: string, value: unknown): void {
+  const cfg = resolveConfig(readUserConfig(), navigator.language);
+  if (cfg.disabledFeatures.has(id as never)) {
+    if (cfg.debug) console.warn(`[aw] core.set: feature "${id}" is disabled by config; ignoring`);
+    return;
+  }
+  const state = loadState(cfg.storageKey);
+  if (id in state.features) {
+    (state.features as Record<string, boolean>)[id] = Boolean(value);
+  } else {
+    (state as unknown as Record<string, unknown>)[id] = value;
+  }
+  saveState(cfg.storageKey, state);
+  applyState(state);
+  panel?.rerender();
+  dispatchWidgetEvent('stateChange', { state });
+}
+
+function applyProfileById(id: string): boolean {
+  const cfg = resolveConfig(readUserConfig(), navigator.language);
+  if (!(PROFILE_IDS as readonly string[]).includes(id)) {
+    if (cfg.debug) console.warn(`[aw] core.applyProfile: unknown profile "${id}"; ignoring`);
+    return false;
+  }
+  const state = loadState(cfg.storageKey);
+  const next = applyProfile(state, id as ProfileId);
+  // Strip features the host has disabled so profile presets can't re-enable them.
+  for (const disabled of cfg.disabledFeatures) {
+    next.features[disabled] = false;
+  }
+  saveState(cfg.storageKey, next);
+  applyState(next);
+  panel?.rerender();
+  dispatchWidgetEvent('profileApplied', { profile: id as ProfileId, state: next });
+  dispatchWidgetEvent('stateChange', { state: next });
+  return true;
+}
+
+function setLocale(next: string): boolean {
+  const cfg = resolveConfig(readUserConfig(), navigator.language);
+  if (!isLocale(next)) {
+    if (cfg.debug)
+      console.warn(`[aw] core.setLocale: "${next}" is not a supported locale; ignoring`);
+    return false;
+  }
+  const state = loadState(cfg.storageKey);
+  if (state.locale === next) return true;
+  const updated: WidgetState = { ...state, locale: next };
+  saveState(cfg.storageKey, updated);
+  panel?.setLocale(next);
+  dispatchWidgetEvent('localeChanged', { locale: next });
+  dispatchWidgetEvent('stateChange', { state: updated });
+  return true;
+}
+
+function reset(): void {
+  const cfg = resolveConfig(readUserConfig(), navigator.language);
+  clearState(cfg.storageKey);
+  const fresh = loadState(cfg.storageKey);
+  applyState(fresh);
+  panel?.rerender();
+  dispatchWidgetEvent('reset', {});
+  dispatchWidgetEvent('stateChange', { state: fresh });
+}
+
+function getState(): WidgetState {
+  const cfg = resolveConfig(readUserConfig(), navigator.language);
+  return loadState(cfg.storageKey);
+}
+
+const api = {
+  open,
+  close,
+  set,
+  applyProfile: applyProfileById,
+  setLocale,
+  reset,
+  getState,
+  version: __AW_VERSION__,
+};
+
+if (typeof window !== 'undefined') {
+  window.AccessibilityWidgetCore = api;
+}
+
+export default api;

package/src/features/apply.ts

@@ -0,0 +1,37 @@
+import type { WidgetState } from '../types/index.js';
+import { toggleAttr } from '../util/dom.js';
+import { readingMaskApply } from './reading-mask.js';
+import { readingGuideApply } from './reading-guide.js';
+
+const HTML_ATTR = {
+  contrast: 'data-aw-contrast',
+  grayscale: 'data-aw-grayscale',
+  invert: 'data-aw-invert',
+  dyslexia: 'data-aw-dyslexia',
+  highlight: 'data-aw-highlight-links',
+  pauseAnim: 'data-aw-pause-animations',
+  bigCursor: 'data-aw-big-cursor',
+  focus: 'data-aw-focus',
+} as const;
+
+export function applyState(state: WidgetState): void {
+  const html = document.documentElement;
+  html.setAttribute('data-aw-instant', '1');
+
+  html.style.setProperty('--aw-font-scale', String(state.fontSizeLevel));
+  html.style.setProperty('--aw-line-height', String(state.lineHeightLevel));
+  html.style.setProperty('--aw-letter-spacing', `${state.letterSpacingLevel}em`);
+
+  const f = state.features;
+  toggleAttr(html, HTML_ATTR.contrast, f.contrast ? state.contrastMode : false);
+  toggleAttr(html, HTML_ATTR.grayscale, f.grayscale ? '1' : false);
+  toggleAttr(html, HTML_ATTR.invert, f.invertColors ? '1' : false);
+  toggleAttr(html, HTML_ATTR.dyslexia, f.dyslexiaFont ? '1' : false);
+  toggleAttr(html, HTML_ATTR.highlight, f.highlightLinks ? '1' : false);
+  toggleAttr(html, HTML_ATTR.pauseAnim, f.pauseAnimations ? '1' : false);
+  toggleAttr(html, HTML_ATTR.bigCursor, f.bigCursor ? '1' : false);
+  toggleAttr(html, HTML_ATTR.focus, f.focusOutline ? '1' : false);
+
+  readingMaskApply(f.readingMask);
+  readingGuideApply(f.readingGuide);
+}

package/src/features/profile.ts

@@ -0,0 +1,18 @@
+import { PROFILES, type ProfileId, type WidgetState } from '../types/index.js';
+
+export function applyProfile(state: WidgetState, profileId: ProfileId): WidgetState {
+  const preset = PROFILES[profileId];
+  const next: WidgetState = {
+    features: { ...state.features },
+    fontSizeLevel: preset.fontSizeLevel ?? state.fontSizeLevel,
+    lineHeightLevel: preset.lineHeightLevel ?? state.lineHeightLevel,
+    letterSpacingLevel: preset.letterSpacingLevel ?? state.letterSpacingLevel,
+    contrastMode: preset.contrastMode ?? state.contrastMode,
+  };
+  if (preset.features) {
+    for (const [k, v] of Object.entries(preset.features)) {
+      next.features[k as keyof typeof next.features] = v as boolean;
+    }
+  }
+  return next;
+}

package/src/features/reading-guide.ts

@@ -0,0 +1,25 @@
+let guideEl: HTMLDivElement | null = null;
+let handler: ((e: MouseEvent | TouchEvent) => void) | null = null;
+
+export function readingGuideApply(on: boolean): void {
+  if (on && !guideEl) {
+    guideEl = document.createElement('div');
+    guideEl.className = 'aw-reading-guide';
+    guideEl.setAttribute('aria-hidden', 'true');
+    document.body.appendChild(guideEl);
+    handler = (e) => {
+      const y = 'clientY' in e ? e.clientY : (e.touches[0]?.clientY ?? 0);
+      guideEl!.style.top = `${y - 16}px`;
+    };
+    document.addEventListener('mousemove', handler as EventListener, { passive: true });
+    document.addEventListener('touchmove', handler as EventListener, { passive: true });
+  } else if (!on && guideEl) {
+    if (handler) {
+      document.removeEventListener('mousemove', handler as EventListener);
+      document.removeEventListener('touchmove', handler as EventListener);
+    }
+    guideEl.remove();
+    guideEl = null;
+    handler = null;
+  }
+}

package/src/features/reading-mask.ts

@@ -0,0 +1,25 @@
+let maskEl: HTMLDivElement | null = null;
+let handler: ((e: MouseEvent | TouchEvent) => void) | null = null;
+
+export function readingMaskApply(on: boolean): void {
+  if (on && !maskEl) {
+    maskEl = document.createElement('div');
+    maskEl.className = 'aw-reading-mask';
+    maskEl.setAttribute('aria-hidden', 'true');
+    document.body.appendChild(maskEl);
+    handler = (e) => {
+      const y = 'clientY' in e ? e.clientY : (e.touches[0]?.clientY ?? 0);
+      maskEl!.style.setProperty('--aw-mask-y', `${y}px`);
+    };
+    document.addEventListener('mousemove', handler as EventListener, { passive: true });
+    document.addEventListener('touchmove', handler as EventListener, { passive: true });
+  } else if (!on && maskEl) {
+    if (handler) {
+      document.removeEventListener('mousemove', handler as EventListener);
+      document.removeEventListener('touchmove', handler as EventListener);
+    }
+    maskEl.remove();
+    maskEl = null;
+    handler = null;
+  }
+}

package/src/features/structure-nav.ts

@@ -0,0 +1,43 @@
+const NAV_ID = 'aw-struct-nav';
+
+export function structureNavToggle(label: string): boolean {
+  const existing = document.getElementById(NAV_ID);
+  if (existing) {
+    existing.remove();
+    return false;
+  }
+
+  const nav = document.createElement('nav');
+  nav.id = NAV_ID;
+  nav.setAttribute('aria-label', label);
+
+  const closeBtn = document.createElement('button');
+  closeBtn.type = 'button';
+  closeBtn.className = 'aw-struct-nav__close';
+  closeBtn.textContent = '×';
+  closeBtn.setAttribute('aria-label', label);
+  closeBtn.addEventListener('click', () => nav.remove());
+
+  const ul = document.createElement('ul');
+  document.querySelectorAll<HTMLHeadingElement>('h1, h2, h3').forEach((h, i) => {
+    if (!h.id) h.id = `aw-h-${i}`;
+    const level = Number(h.tagName.substring(1));
+    const li = document.createElement('li');
+    li.dataset.level = String(level);
+    const a = document.createElement('a');
+    a.href = `#${h.id}`;
+    a.textContent = (h.textContent ?? '').trim().slice(0, 80);
+    a.addEventListener('click', () => {
+      setTimeout(() => nav.remove(), 150);
+    });
+    li.appendChild(a);
+    ul.appendChild(li);
+  });
+
+  nav.appendChild(closeBtn);
+  nav.appendChild(ul);
+  document.body.appendChild(nav);
+
+  setTimeout(() => ul.querySelector<HTMLAnchorElement>('a')?.focus(), 10);
+  return true;
+}