waybetter 0.1.1 → 0.6.0

package/dist/runtime/domHub.js

@@ -5,12 +5,52 @@
 // text, a named attribute) and they run together in the next frame: layout readers first, then DOM
 // writers, so a reader never forces a synchronous layout behind another feature's write. Features
 // marked `offOnHeavy` do not run on the site's heavy pages (see `configureDomHub`), e.g. a WASM chat.
-const config = { label: 'wayBetter', heavyPath: null };
+//
+// A site that renders a part of itself inside an open shadow root (X's chat, since 2026-10-01, in
+// the shadow root of its embed host) names the host in `shadowHosts`: the hub's one observer then
+// observes each such root too (picked up when the host appears or gets its root, dropped with the
+// observer), selector observers look inside, and `domRoots` gives features the roots to query.
+const config = { label: 'wayBetter', heavyPath: null, shadowHosts: [] };
 const hubs = new WeakMap();
 /** Set once by the site adapter, before features register. */
 export function configureDomHub(next) {
     Object.assign(config, next);
 }
+/** The page's roots: the document, then the open shadow roots of the configured hosts now in it. */
+export function domRoots(win) {
+    const doc = win.document;
+    const out = [doc];
+    if (!config.shadowHosts.length)
+        return out;
+    let hosts = [];
+    try {
+        hosts = Array.from(doc.querySelectorAll(config.shadowHosts.join(',')));
+    }
+    catch {
+        return out;
+    }
+    for (const host of hosts) {
+        const root = host.shadowRoot;
+        if (root)
+            out.push(root);
+    }
+    return out;
+}
+/** The site names hosts whose shadow roots are part of the page. */
+export function hasShadowHosts() {
+    return config.shadowHosts.length > 0;
+}
+/** A configured host is in the page but has no open shadow root yet (it may attach one later). */
+function hostWithoutRoot(doc) {
+    if (!config.shadowHosts.length)
+        return false;
+    try {
+        return Array.from(doc.querySelectorAll(config.shadowHosts.join(','))).some(host => !host.shadowRoot);
+    }
+    catch {
+        return false;
+    }
+}
 export function isHeavyPath(pathname) {
     return !!config.heavyPath && config.heavyPath.test(pathname);
 }
@@ -22,6 +62,34 @@ function hubFor(win) {
     let frameRequested = false;
     let observer = null;
     let observing = '';
+    let options = { childList: true, subtree: true };
+    // Shadow roots the observer already observes (with the current options).
+    let roots = new WeakSet();
+    let retries = 0;
+    let retry = null;
+    /** Observes configured shadow roots that are new; a new one marks every feature (its content is new to them). */
+    const observeRoots = () => {
+        if (!observer || !config.shadowHosts.length)
+            return;
+        let added = false;
+        for (const root of domRoots(win).slice(1)) {
+            if (roots.has(root))
+                continue;
+            roots.add(root);
+            observer.observe(root, options);
+            added = true;
+        }
+        if (added) {
+            retries = 0;
+            for (const sub of hub.subs)
+                hub.mark(sub);
+        }
+        // attachShadow makes no mutation: a host that has no root yet is looked at again, a few times.
+        if (!retry && retries < 20 && hostWithoutRoot(doc)) {
+            retries += 1;
+            retry = setTimeout(() => { retry = null; observeRoots(); }, 300);
+        }
+    };
     const frame = () => {
         frameRequested = false;
         const heavy = isHeavyPath(win.location.pathname ?? '');
@@ -56,6 +124,8 @@ function hubFor(win) {
                     (attributes ??= new Set()).add(record.attributeName);
             }
         }
+        if (!known || childList)
+            observeRoots();
         for (const sub of hub.subs) {
             if (!known || childList || (characterData && sub.opts.characterData)
                 || (attributes && sub.opts.attributes?.some(name => attributes.has(name))))
@@ -72,12 +142,15 @@ function hubFor(win) {
             return;
         observer ??= new win.MutationObserver(onRecords);
         observing = key;
-        // Re-observing the same node replaces its options.
-        observer.observe(doc.body, {
+        options = {
             childList: true, subtree: true,
             ...(characterData ? { characterData: true } : {}),
             ...(filter.length ? { attributes: true, attributeFilter: filter } : {}),
-        });
+        };
+        // Re-observing the same node replaces its options (the shadow roots get them again too).
+        observer.observe(doc.body, options);
+        roots = new WeakSet();
+        observeRoots();
     };
     const hub = {
         subs: [],
@@ -93,6 +166,11 @@ function hubFor(win) {
                 observer?.disconnect();
                 observer = null;
                 observing = '';
+                roots = new WeakSet();
+                if (retry) {
+                    clearTimeout(retry);
+                    retry = null;
+                }
                 doc.removeEventListener('DOMContentLoaded', start);
                 hubs.delete(win);
                 return;
@@ -106,6 +184,63 @@ function hubFor(win) {
     hubs.set(win, hub);
     return hub;
 }
+// One per window and heavy-page behaviour: every selector observer of that kind shares its watch.
+const selectorHubs = new WeakMap();
+/**
+ * Calls `callback` once for every element matching `selector`, now and as the page renders more.
+ * Every call shares the hub's one MutationObserver and one frame: a page with a hundred selector
+ * observers still has one observer, and a mutation costs one frame in which each observer looks
+ * for elements it has not seen yet. Returns the disposer.
+ */
+export function observeSelector(win, selector, callback, options = {}) {
+    const offOnHeavy = !!options.offOnHeavy;
+    let kinds = selectorHubs.get(win);
+    if (!kinds) {
+        kinds = new Map();
+        selectorHubs.set(win, kinds);
+    }
+    let hub = kinds.get(offOnHeavy);
+    if (!hub) {
+        hub = { subs: [], handle: null };
+        kinds.set(offOnHeavy, hub);
+    }
+    const owner = hub;
+    const report = options.report ?? ((error) => console.error(`[${config.label}] DOM feature failed`, error));
+    const sub = { selector, callback, seen: new WeakSet(), report };
+    const scan = (target) => {
+        for (const root of domRoots(win)) {
+            for (const element of Array.from(root.querySelectorAll(target.selector))) {
+                if (target.seen.has(element))
+                    continue;
+                target.seen.add(element);
+                try {
+                    target.callback(element);
+                }
+                catch (error) {
+                    target.report(error);
+                }
+            }
+        }
+    };
+    owner.subs.push(sub);
+    owner.handle ??= watchDom(win, () => { for (const item of owner.subs.slice())
+        scan(item); }, { offOnHeavy });
+    if (!(offOnHeavy && isHeavyPath(win.location.pathname ?? '')))
+        scan(sub);
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        const index = owner.subs.indexOf(sub);
+        if (index >= 0)
+            owner.subs.splice(index, 1);
+        if (!owner.subs.length) {
+            owner.handle?.dispose();
+            owner.handle = null;
+        }
+    };
+}
 /**
  * Runs `run` in the next animation frame after body mutations of the watched kinds (child list
  * always), or whenever `schedule()` is called (scroll, popstate, input, ...). Several calls in one

package/dist/runtime/domHub.js.map

@@ -1 +1 @@
-{"version":3,"file":"domHub.js","sourceRoot":"","sources":["../../../runtime/src/domHub.ts"],"names":[],"mappings":"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","sourcesContent":["// One MutationObserver and one animation frame per page for every DOM feature of a site runtime.\n// Without it, each feature (nav items, tweaks, buttons, fixes, viewers) observes the whole <body>\n// subtree and schedules its own frame, so every mutation the site makes costs one callback and one\n// frame of scans per feature. Here a mutation marks the features interested in its kind (child list,\n// text, a named attribute) and they run together in the next frame: layout readers first, then DOM\n// writers, so a reader never forces a synchronous layout behind another feature's write. Features\n// marked `offOnHeavy` do not run on the site's heavy pages (see `configureDomHub`), e.g. a WASM chat.\n\nexport type DomWatch = {\n  /** Also run on text changes (characterData). */\n  characterData?: boolean;\n  /** Also run when one of these attributes changes. */\n  attributes?: string[];\n  /** Skip on the site's heavy pages (`DomHubConfig.heavyPath`). */\n  offOnHeavy?: boolean;\n  /** 'read' features (layout reads) run before 'write' features (the default) in a frame. */\n  phase?: 'read' | 'write';\n};\nexport type DomWatchHandle = { schedule(): void; dispose(): void };\n\nexport type DomHubConfig = {\n  /** Console prefix for feature failures, e.g. \"wayBetter for X\". */\n  label: string;\n  /** Pathnames where `offOnHeavy` features are skipped; null = none. */\n  heavyPath: RegExp | null;\n};\n\nexport type DomWindow = {\n  document: Document;\n  location: { pathname: string };\n  MutationObserver: typeof MutationObserver;\n  requestAnimationFrame(callback: FrameRequestCallback): number;\n};\ntype Sub = { run: () => void; opts: DomWatch; pending: boolean };\ntype Hub = { subs: Sub[]; mark(sub: Sub): void; refresh(): void };\n\nconst config: DomHubConfig = { label: 'wayBetter', heavyPath: null };\nconst hubs = new WeakMap<object, Hub>();\n\n/** Set once by the site adapter, before features register. */\nexport function configureDomHub(next: Partial<DomHubConfig>): void {\n  Object.assign(config, next);\n}\n\nexport function isHeavyPath(pathname: string): boolean {\n  return !!config.heavyPath && config.heavyPath.test(pathname);\n}\n\nfunction hubFor(win: DomWindow): Hub {\n  const existing = hubs.get(win);\n  if (existing) return existing;\n  const doc = win.document;\n  let frameRequested = false;\n  let observer: MutationObserver | null = null;\n  let observing = '';\n\n  const frame = () => {\n    frameRequested = false;\n    const heavy = isHeavyPath(win.location.pathname ?? '');\n    for (const phase of ['read', 'write'] as const) {\n      for (const sub of hub.subs.slice()) {\n        if (!sub.pending || (sub.opts.phase ?? 'write') !== phase) continue;\n        sub.pending = false;\n        if (heavy && sub.opts.offOnHeavy) continue;\n        try { sub.run(); } catch (error) { console.error(`[${config.label}] DOM feature failed`, error); }\n      }\n    }\n  };\n  const onRecords = (records: MutationRecord[]) => {\n    let childList = false;\n    let characterData = false;\n    let attributes: Set<string> | null = null;\n    const known = Array.isArray(records) && records.length > 0;\n    if (known) {\n      for (const record of records) {\n        if (record.type === 'childList') childList = true;\n        else if (record.type === 'characterData') characterData = true;\n        else if (record.type === 'attributes' && record.attributeName) (attributes ??= new Set()).add(record.attributeName);\n      }\n    }\n    for (const sub of hub.subs) {\n      if (!known || childList || (characterData && sub.opts.characterData)\n        || (attributes && sub.opts.attributes?.some(name => attributes!.has(name)))) hub.mark(sub);\n    }\n  };\n  const start = () => {\n    if (!doc.body || !hub.subs.length) return;\n    const characterData = hub.subs.some(sub => sub.opts.characterData);\n    const filter = [...new Set(hub.subs.flatMap(sub => sub.opts.attributes ?? []))].sort();\n    const key = `${characterData}|${filter.join(',')}`;\n    if (observer && observing === key) return;\n    observer ??= new win.MutationObserver(onRecords);\n    observing = key;\n    // Re-observing the same node replaces its options.\n    observer.observe(doc.body, {\n      childList: true, subtree: true,\n      ...(characterData ? { characterData: true } : {}),\n      ...(filter.length ? { attributes: true, attributeFilter: filter } : {}),\n    });\n  };\n\n  const hub: Hub = {\n    subs: [],\n    mark(sub) {\n      sub.pending = true;\n      if (!frameRequested) { frameRequested = true; win.requestAnimationFrame(frame); }\n    },\n    refresh() {\n      if (!hub.subs.length) {\n        observer?.disconnect();\n        observer = null;\n        observing = '';\n        doc.removeEventListener('DOMContentLoaded', start);\n        hubs.delete(win);\n        return;\n      }\n      if (doc.body) start();\n      else doc.addEventListener('DOMContentLoaded', start, { once: true });\n    },\n  };\n  hubs.set(win, hub);\n  return hub;\n}\n\n/**\n * Runs `run` in the next animation frame after body mutations of the watched kinds (child list\n * always), or whenever `schedule()` is called (scroll, popstate, input, ...). Several calls in one\n * frame run it once.\n */\nexport function watchDom(win: DomWindow, run: () => void, opts: DomWatch = {}): DomWatchHandle {\n  const hub = hubFor(win);\n  const sub: Sub = { run, opts, pending: false };\n  hub.subs.push(sub);\n  hub.refresh();\n  let active = true;\n  return {\n    schedule: () => { if (active) hub.mark(sub); },\n    dispose() {\n      if (!active) return;\n      active = false;\n      const index = hub.subs.indexOf(sub);\n      if (index >= 0) hub.subs.splice(index, 1);\n      hub.refresh();\n    },\n  };\n}\n"]}
+{"version":3,"file":"domHub.js","sourceRoot":"","sources":["../../../runtime/src/domHub.ts"],"names":[],"mappings":"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","sourcesContent":["// One MutationObserver and one animation frame per page for every DOM feature of a site runtime.\n// Without it, each feature (nav items, tweaks, buttons, fixes, viewers) observes the whole <body>\n// subtree and schedules its own frame, so every mutation the site makes costs one callback and one\n// frame of scans per feature. Here a mutation marks the features interested in its kind (child list,\n// text, a named attribute) and they run together in the next frame: layout readers first, then DOM\n// writers, so a reader never forces a synchronous layout behind another feature's write. Features\n// marked `offOnHeavy` do not run on the site's heavy pages (see `configureDomHub`), e.g. a WASM chat.\n//\n// A site that renders a part of itself inside an open shadow root (X's chat, since 2026-10-01, in\n// the shadow root of its embed host) names the host in `shadowHosts`: the hub's one observer then\n// observes each such root too (picked up when the host appears or gets its root, dropped with the\n// observer), selector observers look inside, and `domRoots` gives features the roots to query.\n\nexport type DomWatch = {\n  /** Also run on text changes (characterData). */\n  characterData?: boolean;\n  /** Also run when one of these attributes changes. */\n  attributes?: string[];\n  /** Skip on the site's heavy pages (`DomHubConfig.heavyPath`). */\n  offOnHeavy?: boolean;\n  /** 'read' features (layout reads) run before 'write' features (the default) in a frame. */\n  phase?: 'read' | 'write';\n};\nexport type DomWatchHandle = { schedule(): void; dispose(): void };\n\nexport type DomHubConfig = {\n  /** Console prefix for feature failures, e.g. \"wayBetter for X\". */\n  label: string;\n  /** Pathnames where `offOnHeavy` features are skipped; null = none. */\n  heavyPath: RegExp | null;\n  /** Selectors of hosts whose open shadow roots are part of the page (observed and searched like it). */\n  shadowHosts: readonly string[];\n};\n\nexport type DomWindow = {\n  document: Document;\n  location: { pathname: string };\n  MutationObserver: typeof MutationObserver;\n  requestAnimationFrame(callback: FrameRequestCallback): number;\n};\ntype Sub = { run: () => void; opts: DomWatch; pending: boolean };\ntype Hub = { subs: Sub[]; mark(sub: Sub): void; refresh(): void };\n\nconst config: DomHubConfig = { label: 'wayBetter', heavyPath: null, shadowHosts: [] };\nconst hubs = new WeakMap<object, Hub>();\n\n/** Set once by the site adapter, before features register. */\nexport function configureDomHub(next: Partial<DomHubConfig>): void {\n  Object.assign(config, next);\n}\n\n/** The page's roots: the document, then the open shadow roots of the configured hosts now in it. */\nexport function domRoots(win: { document: Document }): Array<Document | ShadowRoot> {\n  const doc = win.document;\n  const out: Array<Document | ShadowRoot> = [doc];\n  if (!config.shadowHosts.length) return out;\n  let hosts: Element[] = [];\n  try { hosts = Array.from(doc.querySelectorAll(config.shadowHosts.join(','))); } catch { return out; }\n  for (const host of hosts) {\n    const root = (host as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot;\n    if (root) out.push(root);\n  }\n  return out;\n}\n\n/** The site names hosts whose shadow roots are part of the page. */\nexport function hasShadowHosts(): boolean {\n  return config.shadowHosts.length > 0;\n}\n\n/** A configured host is in the page but has no open shadow root yet (it may attach one later). */\nfunction hostWithoutRoot(doc: Document): boolean {\n  if (!config.shadowHosts.length) return false;\n  try { return Array.from(doc.querySelectorAll(config.shadowHosts.join(','))).some(host => !(host as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot); } catch { return false; }\n}\n\nexport function isHeavyPath(pathname: string): boolean {\n  return !!config.heavyPath && config.heavyPath.test(pathname);\n}\n\nfunction hubFor(win: DomWindow): Hub {\n  const existing = hubs.get(win);\n  if (existing) return existing;\n  const doc = win.document;\n  let frameRequested = false;\n  let observer: MutationObserver | null = null;\n  let observing = '';\n  let options: MutationObserverInit = { childList: true, subtree: true };\n  // Shadow roots the observer already observes (with the current options).\n  let roots = new WeakSet<Node>();\n  let retries = 0;\n  let retry: ReturnType<typeof setTimeout> | null = null;\n  /** Observes configured shadow roots that are new; a new one marks every feature (its content is new to them). */\n  const observeRoots = () => {\n    if (!observer || !config.shadowHosts.length) return;\n    let added = false;\n    for (const root of domRoots(win).slice(1)) {\n      if (roots.has(root)) continue;\n      roots.add(root);\n      observer.observe(root, options);\n      added = true;\n    }\n    if (added) { retries = 0; for (const sub of hub.subs) hub.mark(sub); }\n    // attachShadow makes no mutation: a host that has no root yet is looked at again, a few times.\n    if (!retry && retries < 20 && hostWithoutRoot(doc)) {\n      retries += 1;\n      retry = setTimeout(() => { retry = null; observeRoots(); }, 300);\n    }\n  };\n\n  const frame = () => {\n    frameRequested = false;\n    const heavy = isHeavyPath(win.location.pathname ?? '');\n    for (const phase of ['read', 'write'] as const) {\n      for (const sub of hub.subs.slice()) {\n        if (!sub.pending || (sub.opts.phase ?? 'write') !== phase) continue;\n        sub.pending = false;\n        if (heavy && sub.opts.offOnHeavy) continue;\n        try { sub.run(); } catch (error) { console.error(`[${config.label}] DOM feature failed`, error); }\n      }\n    }\n  };\n  const onRecords = (records: MutationRecord[]) => {\n    let childList = false;\n    let characterData = false;\n    let attributes: Set<string> | null = null;\n    const known = Array.isArray(records) && records.length > 0;\n    if (known) {\n      for (const record of records) {\n        if (record.type === 'childList') childList = true;\n        else if (record.type === 'characterData') characterData = true;\n        else if (record.type === 'attributes' && record.attributeName) (attributes ??= new Set()).add(record.attributeName);\n      }\n    }\n    if (!known || childList) observeRoots();\n    for (const sub of hub.subs) {\n      if (!known || childList || (characterData && sub.opts.characterData)\n        || (attributes && sub.opts.attributes?.some(name => attributes!.has(name)))) hub.mark(sub);\n    }\n  };\n  const start = () => {\n    if (!doc.body || !hub.subs.length) return;\n    const characterData = hub.subs.some(sub => sub.opts.characterData);\n    const filter = [...new Set(hub.subs.flatMap(sub => sub.opts.attributes ?? []))].sort();\n    const key = `${characterData}|${filter.join(',')}`;\n    if (observer && observing === key) return;\n    observer ??= new win.MutationObserver(onRecords);\n    observing = key;\n    options = {\n      childList: true, subtree: true,\n      ...(characterData ? { characterData: true } : {}),\n      ...(filter.length ? { attributes: true, attributeFilter: filter } : {}),\n    };\n    // Re-observing the same node replaces its options (the shadow roots get them again too).\n    observer.observe(doc.body, options);\n    roots = new WeakSet();\n    observeRoots();\n  };\n\n  const hub: Hub = {\n    subs: [],\n    mark(sub) {\n      sub.pending = true;\n      if (!frameRequested) { frameRequested = true; win.requestAnimationFrame(frame); }\n    },\n    refresh() {\n      if (!hub.subs.length) {\n        observer?.disconnect();\n        observer = null;\n        observing = '';\n        roots = new WeakSet();\n        if (retry) { clearTimeout(retry); retry = null; }\n        doc.removeEventListener('DOMContentLoaded', start);\n        hubs.delete(win);\n        return;\n      }\n      if (doc.body) start();\n      else doc.addEventListener('DOMContentLoaded', start, { once: true });\n    },\n  };\n  hubs.set(win, hub);\n  return hub;\n}\n\ntype SelectorSub = { selector: string; callback: (element: Element) => void; seen: WeakSet<Element>; report(error: unknown): void };\ntype SelectorHub = { subs: SelectorSub[]; handle: DomWatchHandle | null };\n// One per window and heavy-page behaviour: every selector observer of that kind shares its watch.\nconst selectorHubs = new WeakMap<object, Map<boolean, SelectorHub>>();\n\nexport type ObserveOptions = {\n  /** Skip on the site's heavy pages (default false). */\n  offOnHeavy?: boolean;\n  /** A callback that throws is handed here (default: the hub's console line). */\n  report?(error: unknown): void;\n};\n\n/**\n * Calls `callback` once for every element matching `selector`, now and as the page renders more.\n * Every call shares the hub's one MutationObserver and one frame: a page with a hundred selector\n * observers still has one observer, and a mutation costs one frame in which each observer looks\n * for elements it has not seen yet. Returns the disposer.\n */\nexport function observeSelector(win: DomWindow, selector: string, callback: (element: Element) => void, options: ObserveOptions = {}): () => void {\n  const offOnHeavy = !!options.offOnHeavy;\n  let kinds = selectorHubs.get(win);\n  if (!kinds) { kinds = new Map(); selectorHubs.set(win, kinds); }\n  let hub = kinds.get(offOnHeavy);\n  if (!hub) { hub = { subs: [], handle: null }; kinds.set(offOnHeavy, hub); }\n  const owner = hub;\n  const report = options.report ?? ((error: unknown) => console.error(`[${config.label}] DOM feature failed`, error));\n  const sub: SelectorSub = { selector, callback, seen: new WeakSet(), report };\n  const scan = (target: SelectorSub) => {\n    for (const root of domRoots(win)) {\n      for (const element of Array.from(root.querySelectorAll(target.selector))) {\n        if (target.seen.has(element)) continue;\n        target.seen.add(element);\n        try { target.callback(element); } catch (error) { target.report(error); }\n      }\n    }\n  };\n  owner.subs.push(sub);\n  owner.handle ??= watchDom(win, () => { for (const item of owner.subs.slice()) scan(item); }, { offOnHeavy });\n  if (!(offOnHeavy && isHeavyPath(win.location.pathname ?? ''))) scan(sub);\n  let active = true;\n  return () => {\n    if (!active) return;\n    active = false;\n    const index = owner.subs.indexOf(sub);\n    if (index >= 0) owner.subs.splice(index, 1);\n    if (!owner.subs.length) { owner.handle?.dispose(); owner.handle = null; }\n  };\n}\n\n/**\n * Runs `run` in the next animation frame after body mutations of the watched kinds (child list\n * always), or whenever `schedule()` is called (scroll, popstate, input, ...). Several calls in one\n * frame run it once.\n */\nexport function watchDom(win: DomWindow, run: () => void, opts: DomWatch = {}): DomWatchHandle {\n  const hub = hubFor(win);\n  const sub: Sub = { run, opts, pending: false };\n  hub.subs.push(sub);\n  hub.refresh();\n  let active = true;\n  return {\n    schedule: () => { if (active) hub.mark(sub); },\n    dispose() {\n      if (!active) return;\n      active = false;\n      const index = hub.subs.indexOf(sub);\n      if (index >= 0) hub.subs.splice(index, 1);\n      hub.refresh();\n    },\n  };\n}\n"]}

package/dist/runtime/featureModules.d.ts

@@ -0,0 +1,157 @@
+import { type DomWatch, type DomWatchHandle } from './domHub.ts';
+import { type AreaSpec, type FeatureTable, type Flags } from './featureTable.ts';
+import { type Params } from './i18n.ts';
+import type { CommandDefinition } from './commands.ts';
+import type { PluginI18n } from './pluginI18n.ts';
+import type { Dispose, PluginScope, PluginStorage } from './pluginApi.ts';
+import { type SettingValues, type SettingsSchema } from './settingsForm.ts';
+import { type UiKit } from './ui.ts';
+/** Palette commands one area may register: its "settings" entry and four actions (the tab reports at most 48). */
+export declare const AREA_COMMAND_BUDGET = 5;
+/** Misses in a row (separate visits) before a feature pauses itself. */
+export declare const PROBE_STRIKES = 3;
+/**
+ * A selector a feature depends on. `english`: it reads an English label, so it only counts on an
+ * English page. `when`: it only counts while this selector matches (the part of the page it lives
+ * in is there: a column the site drops in a narrow window is no verdict).
+ */
+export type Probe = string | {
+    selector: string;
+    english?: boolean;
+    when?: string;
+};
+export type FeatureSettings = {
+    /** The stored values, normalized by the schema. */
+    get(): SettingValues;
+    /** Saves (merged over the current values). False when storage refused it. */
+    set(patch: SettingValues): boolean;
+    /** Calls `callback(values)` after a save, until the feature stops. */
+    onChange(callback: (values: SettingValues) => void): void;
+    /** Opens this feature's settings dialog. */
+    open(): void;
+};
+export type FeatureContext<Api> = {
+    /** The flag id and the feature's own name (`navigation.focusMode` -> `focusMode`). */
+    readonly id: string;
+    readonly name: string;
+    readonly area: AreaSpec;
+    /** The app's plugin API, unrestricted: a feature module is the app's own code. */
+    readonly api: Api;
+    /** The page's window (use it and its `document` instead of the globals: tests run without them). */
+    readonly win: Window & typeof globalThis;
+    /** This feature's stylesheet (one per `name`, replaced in place, cleared by an empty string; removed on stop). It also styles the site's configured open shadow roots (domHub `shadowHosts`). */
+    css(css: string, name?: string): void;
+    /** `callback` once per element matching `selector`, through the shared hub; paused on heavy pages unless the feature says `heavy`. */
+    observe(selector: string, callback: (element: Element) => void): void;
+    /** A raw hub subscription (domHub `watchDom`), disposed on stop. */
+    watch(run: () => void, options?: DomWatch): DomWatchHandle;
+    on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    onKey(callback: (event: KeyboardEvent, item: Element | null) => void): void;
+    onRouteChange(callback: (href: string, previous: string) => void): void;
+    /** Tracks a node the feature inserted; removed on stop. */
+    add<T extends Node>(node: T): T;
+    /** Runs `fn` on stop. */
+    defer(fn: Dispose): void;
+    /** The UI kit; what the feature opened is closed on stop. */
+    readonly ui: UiKit;
+    /** A palette command under the area's name (counts towards `AREA_COMMAND_BUDGET`), removed on stop. */
+    command(definition: CommandDefinition): void;
+    /**
+     * The feature's word `key`: `plugin.<area namespace>.<name>.<key>` in the app's catalog, or
+     * `plugin.<words>.<key>` for a module that names its own namespace (`words`). (Not
+     * named `t`: the i18n tools read `t('…')` as a whole catalog key.)
+     */
+    text(key: string, params?: Params): string;
+    /** The feature's storage (its module's `storage` namespace). */
+    readonly storage: PluginStorage;
+    /** Its settings (a module with a `settings` schema; otherwise empty values). */
+    readonly settings: FeatureSettings;
+    /** The selector of probe `name` (a hotfix override wins). */
+    selector(name: string): string;
+    /** The surfaces the page is on right now. */
+    surfaces(): readonly string[];
+};
+export type FeatureModule<Api> = {
+    /** The flag id; the table must list it with `backing: 'module'`. */
+    id: string;
+    /** Selectors it depends on, by name (read them back with `ctx.selector(name)`). */
+    probes?: Readonly<Record<string, Probe>>;
+    /**
+     * Where its words are in the catalog. Default: `plugin.<area namespace>.<name>.<key>`. A feature
+     * ported from a plugin names that plugin's namespace (`focus-mode`) and keeps its keys
+     * (`plugin.focus-mode.<key>`, its label `plugin.focus-mode.name`): nothing is retranslated.
+     */
+    words?: string;
+    /** Storage namespace (default `<area namespace>.<name>`; a ported plugin keeps its old one). */
+    storage?: string;
+    /** The key its settings are stored under (default `settings`). */
+    settingsKey?: string;
+    settings?: SettingsSchema;
+    start(ctx: FeatureContext<Api>): void;
+};
+/** What the registry needs of the plugin API (the core API has all of it). */
+export type RegistryApi = {
+    scope(): PluginScope;
+    injectCSS(id: string, css: string): void;
+    clearCSS(id: string): void;
+    storage(namespace: string): PluginStorage;
+    onRouteChange(callback: (href: string, previous: string) => void): Dispose;
+    ui: UiKit;
+    i18n: PluginI18n;
+    commands: {
+        withOwner<T>(owner: string, fn: () => T): T;
+    };
+};
+export type HotfixData = {
+    selectors?: Readonly<Record<string, unknown>>;
+    flags?: Readonly<Record<string, unknown>>;
+};
+export type FeatureHealth = {
+    id: string;
+    area: string;
+    state: 'paused' | 'needs-english';
+    probes: string[];
+};
+export type FeatureRegistryOptions<Api extends RegistryApi> = {
+    win: Window & typeof globalThis;
+    table: FeatureTable;
+    api: Api;
+    /** Console prefix (the app's name). */
+    label: string;
+    /** The surfaces the page is on (`['timeline', 'home']`); the app's classifier. */
+    surfaces(): readonly string[];
+    /** The app catalog's message for `key` in the active language (the registry's words are the kit's: `kit.feature.*`, `kit.save`). */
+    message?(key: string): string | undefined;
+    locale?(): string;
+    /** The signed hotfix data, when the app has any (selector overrides and kill flags). */
+    hotfix?(): HotfixData | null | undefined;
+    /** The page has rendered its content (the site's main column is there); default: the body has children. */
+    settled?(): boolean;
+    /** The page's language is English (probes marked `english` only count then); default: `<html lang>` starts with `en`. */
+    english?(): boolean;
+    /** ms after the page settled before probes are judged (default 3000) and between settle checks (default 500). */
+    settleMs?: number;
+    pollMs?: number;
+    timers?: {
+        setTimeout(fn: () => void, ms: number): unknown;
+        clearTimeout(id: unknown): void;
+    };
+};
+export type FeatureRegistry<Api> = {
+    define(module: FeatureModule<Api>): void;
+    /** The effective flags (featureTable `effectiveFlags`): starts and stops modules to match. */
+    setFlags(flags: Readonly<Flags>): void;
+    /** Re-checks surfaces (the registry also does it on every route change). */
+    refresh(): void;
+    /** The ids of the modules running right now. */
+    active(): string[];
+    /** Paused features and features waiting for an English page. */
+    health(): FeatureHealth[];
+    /** Opens the settings dialog of an area (or of one feature). False when nothing in it has settings right now. */
+    openSettings(area: string, feature?: string): boolean;
+    /** Stops everything (the runtime is going away; tests). */
+    dispose(): void;
+};
+export declare function createFeatureRegistry<Api extends RegistryApi>(options: FeatureRegistryOptions<Api>): FeatureRegistry<Api>;
+/** Whether an area's switch is on in `flags` (a missing value counts as on). */
+export declare const areaEnabled: (flags: Readonly<Flags>, area: string) => boolean;