waybetter 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# waybetter
+
+The framework behind the wayBetter apps: apps that extend the apps you already use in place, the
+way BetterDiscord extends Discord. A website gets a native window around it; a desktop app built
+on web tech is extended from the inside. Both share this package.
+
+- **`waybetter/runtime/*`**: the page runtime. One DOM-mutation/animation-frame hub, one
+  fetch/XHR hub, a plugin API core, an OKLab theme color model, split-pane rail hiding, link
+  routing and account change reporting.
+- **`waybetter/shell/*`**: pure models for the app chrome around the pages: address bar chips,
+  dock/split-pane rules, dragged links, account profiles, the update chip, command palette
+  ranking and window controls. The Tauri window API is passed in by the caller, never imported.
+
+Plain ESM with `.d.ts` types. Zero dependencies.
+
+## Install
+
+```sh
+npm install waybetter
+```
+
+## Usage
+
+Every module is its own subpath export, so you only pull in what you use:
+
+```ts
+import { configureRuntime, type SiteAdapter } from 'waybetter/runtime/site';
+import { watchDom } from 'waybetter/runtime/domHub';
+import { buildColorModel, deriveColors } from 'waybetter/runtime/themeTokens';
+import { parseAddress } from 'waybetter/shell/addressModel';
+import { fuzzyScore, rankItems } from 'waybetter/shell/palette';
+```
+
+`runtime/site` is the composition root: an app is mostly one adapter object built from these
+pieces. The source comments document each module's contract.
+
+## Modules
+
+**Runtime**
+
+- `accountReport`: reports the signed-in account seen in the page's own UI.
+- `domHub`: one `MutationObserver` and one animation frame shared by every DOM feature.
+- `linkRouting`: routes clicks on the app's own links per the "links to app pages" setting.
+- `netHub`: one shared fetch/XHR hook for URL rewrites, gates and passive JSON taps.
+- `paneNav`: hides a redundant navigation rail when two panes show the same account.
+- `pluginApi`: small helpers shared by user JS plugins.
+- `site`: the page-side composition root for an adapter.
+- `themeTokens`: the OKLab color model themes are built on.
+
+**Shell**
+
+- `addressModel`: `parseAddress(url, site)` for the address bar's breadcrumb chips.
+- `chrome`: layout constants for the custom titlebar and toolbar.
+- `linkDrop`: a dragged link dropped into the dock opens as a tab or split pane.
+- `palette`: command palette fuzzy scoring, ranking and selection movement.
+- `paneModel`: pane geometry: where a "beside" link opens, which panes keep the rail.
+- `profileModel`: the account profile model.
+- `updateModel`: the titlebar update chip model.
+- `windowControls`: native window calls for the titlebar, resize grips and caption buttons.
+
+## Projects using wayBetter
+
+| Project | Target | What it is |
+| --- | --- | --- |
+| [wayBetter for X](https://waybetter.crt.fyi/twttr/) | x.com (website) | Desktop app around the live X: tabs, split panes, real accounts side by side, themes, plugins, drafts and fixes for X's own bugs. The first wayBetter app. |
+
+Built something on wayBetter? Add it to this list with a pull request: name and link, what it extends, one line on what it does.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](./LICENSE).

package/dist/runtime/accountReport.d.ts

@@ -0,0 +1,20 @@
+export type SeenAccount = {
+    handle: string;
+    name: string;
+    avatar: string | null;
+};
+export type AccountReport = {
+    account: SeenAccount;
+} | {
+    signedOut: true;
+};
+export type AccountSite = {
+    /** The account the site's UI shows, or null when there is none (yet). Pure over the DOM. */
+    read(root: ParentNode): SeenAccount | null;
+    /** The site shows its signed-out page. */
+    signedOut(root: ParentNode): boolean;
+};
+export type Invoke = (command: string, args: Record<string, unknown>) => Promise<unknown>;
+export declare function installAccountReport(win: Window, site: AccountSite, invoke?: Invoke): import("./domHub.ts").DomWatchHandle | {
+    dispose(): void;
+};

package/dist/runtime/accountReport.js

@@ -0,0 +1,26 @@
+// Tells the app which account is signed in inside this tab's profile, so the account switcher
+// lists real logins (avatar, name, handle) instead of hand-named slots. Read from the site's own
+// UI, which the site renders anyway; nothing is requested. Only a change is reported (`tab_report`),
+// and native code accepts it only from a webview that is on the site, for that webview's own profile.
+import { watchDom } from "./domHub.js";
+export function installAccountReport(win, site, invoke) {
+    if (!invoke)
+        return { dispose() { } };
+    let last = '';
+    const send = (report) => {
+        const key = JSON.stringify(report);
+        if (key === last)
+            return;
+        last = key;
+        invoke('tab_report', { report }).catch(() => { last = ''; });
+    };
+    const check = () => {
+        const account = site.read(win.document);
+        if (account)
+            send({ account });
+        else if (site.signedOut(win.document))
+            send({ signedOut: true });
+    };
+    return watchDom(win, check);
+}
+//# sourceMappingURL=accountReport.js.map

package/dist/runtime/accountReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountReport.js","sourceRoot":"","sources":["../../../runtime/src/accountReport.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,iGAAiG;AACjG,qGAAqG;AACrG,sGAAsG;AAEtG,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAcvC,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,IAAiB,EAAE,MAAe;IAClF,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,KAAI,CAAC,EAAE,CAAC;IACrC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,MAAM,IAAI,GAAG,CAAC,MAAqB,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO;QACzB,IAAI,GAAG,GAAG,CAAC;QACX,MAAM,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,OAAO;YAAE,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;aAC1B,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC;IACF,OAAO,QAAQ,CAAC,GAAgD,EAAE,KAAK,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["// Tells the app which account is signed in inside this tab's profile, so the account switcher\n// lists real logins (avatar, name, handle) instead of hand-named slots. Read from the site's own\n// UI, which the site renders anyway; nothing is requested. Only a change is reported (`tab_report`),\n// and native code accepts it only from a webview that is on the site, for that webview's own profile.\n\nimport { watchDom } from './domHub.ts';\n\nexport type SeenAccount = { handle: string; name: string; avatar: string | null };\nexport type AccountReport = { account: SeenAccount } | { signedOut: true };\n\nexport type AccountSite = {\n  /** The account the site's UI shows, or null when there is none (yet). Pure over the DOM. */\n  read(root: ParentNode): SeenAccount | null;\n  /** The site shows its signed-out page. */\n  signedOut(root: ParentNode): boolean;\n};\n\nexport type Invoke = (command: string, args: Record<string, unknown>) => Promise<unknown>;\n\nexport function installAccountReport(win: Window, site: AccountSite, invoke?: Invoke) {\n  if (!invoke) return { dispose() {} };\n  let last = '';\n  const send = (report: AccountReport) => {\n    const key = JSON.stringify(report);\n    if (key === last) return;\n    last = key;\n    invoke('tab_report', { report }).catch(() => { last = ''; });\n  };\n  const check = () => {\n    const account = site.read(win.document);\n    if (account) send({ account });\n    else if (site.signedOut(win.document)) send({ signedOut: true });\n  };\n  return watchDom(win as unknown as Parameters<typeof watchDom>[0], check);\n}\n"]}

package/dist/runtime/domHub.d.ts

@@ -0,0 +1,37 @@
+export type DomWatch = {
+    /** Also run on text changes (characterData). */
+    characterData?: boolean;
+    /** Also run when one of these attributes changes. */
+    attributes?: string[];
+    /** Skip on the site's heavy pages (`DomHubConfig.heavyPath`). */
+    offOnHeavy?: boolean;
+    /** 'read' features (layout reads) run before 'write' features (the default) in a frame. */
+    phase?: 'read' | 'write';
+};
+export type DomWatchHandle = {
+    schedule(): void;
+    dispose(): void;
+};
+export type DomHubConfig = {
+    /** Console prefix for feature failures, e.g. "wayBetter for X". */
+    label: string;
+    /** Pathnames where `offOnHeavy` features are skipped; null = none. */
+    heavyPath: RegExp | null;
+};
+export type DomWindow = {
+    document: Document;
+    location: {
+        pathname: string;
+    };
+    MutationObserver: typeof MutationObserver;
+    requestAnimationFrame(callback: FrameRequestCallback): number;
+};
+/** Set once by the site adapter, before features register. */
+export declare function configureDomHub(next: Partial<DomHubConfig>): void;
+export declare function isHeavyPath(pathname: string): boolean;
+/**
+ * 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
+ * frame run it once.
+ */
+export declare function watchDom(win: DomWindow, run: () => void, opts?: DomWatch): DomWatchHandle;

package/dist/runtime/domHub.js

@@ -0,0 +1,134 @@
+// One MutationObserver and one animation frame per page for every DOM feature of a site runtime.
+// Without it, each feature (nav items, tweaks, buttons, fixes, viewers) observes the whole <body>
+// subtree and schedules its own frame, so every mutation the site makes costs one callback and one
+// frame of scans per feature. Here a mutation marks the features interested in its kind (child list,
+// 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 };
+const hubs = new WeakMap();
+/** Set once by the site adapter, before features register. */
+export function configureDomHub(next) {
+    Object.assign(config, next);
+}
+export function isHeavyPath(pathname) {
+    return !!config.heavyPath && config.heavyPath.test(pathname);
+}
+function hubFor(win) {
+    const existing = hubs.get(win);
+    if (existing)
+        return existing;
+    const doc = win.document;
+    let frameRequested = false;
+    let observer = null;
+    let observing = '';
+    const frame = () => {
+        frameRequested = false;
+        const heavy = isHeavyPath(win.location.pathname ?? '');
+        for (const phase of ['read', 'write']) {
+            for (const sub of hub.subs.slice()) {
+                if (!sub.pending || (sub.opts.phase ?? 'write') !== phase)
+                    continue;
+                sub.pending = false;
+                if (heavy && sub.opts.offOnHeavy)
+                    continue;
+                try {
+                    sub.run();
+                }
+                catch (error) {
+                    console.error(`[${config.label}] DOM feature failed`, error);
+                }
+            }
+        }
+    };
+    const onRecords = (records) => {
+        let childList = false;
+        let characterData = false;
+        let attributes = null;
+        const known = Array.isArray(records) && records.length > 0;
+        if (known) {
+            for (const record of records) {
+                if (record.type === 'childList')
+                    childList = true;
+                else if (record.type === 'characterData')
+                    characterData = true;
+                else if (record.type === 'attributes' && record.attributeName)
+                    (attributes ??= new Set()).add(record.attributeName);
+            }
+        }
+        for (const sub of hub.subs) {
+            if (!known || childList || (characterData && sub.opts.characterData)
+                || (attributes && sub.opts.attributes?.some(name => attributes.has(name))))
+                hub.mark(sub);
+        }
+    };
+    const start = () => {
+        if (!doc.body || !hub.subs.length)
+            return;
+        const characterData = hub.subs.some(sub => sub.opts.characterData);
+        const filter = [...new Set(hub.subs.flatMap(sub => sub.opts.attributes ?? []))].sort();
+        const key = `${characterData}|${filter.join(',')}`;
+        if (observer && observing === key)
+            return;
+        observer ??= new win.MutationObserver(onRecords);
+        observing = key;
+        // Re-observing the same node replaces its options.
+        observer.observe(doc.body, {
+            childList: true, subtree: true,
+            ...(characterData ? { characterData: true } : {}),
+            ...(filter.length ? { attributes: true, attributeFilter: filter } : {}),
+        });
+    };
+    const hub = {
+        subs: [],
+        mark(sub) {
+            sub.pending = true;
+            if (!frameRequested) {
+                frameRequested = true;
+                win.requestAnimationFrame(frame);
+            }
+        },
+        refresh() {
+            if (!hub.subs.length) {
+                observer?.disconnect();
+                observer = null;
+                observing = '';
+                doc.removeEventListener('DOMContentLoaded', start);
+                hubs.delete(win);
+                return;
+            }
+            if (doc.body)
+                start();
+            else
+                doc.addEventListener('DOMContentLoaded', start, { once: true });
+        },
+    };
+    hubs.set(win, hub);
+    return hub;
+}
+/**
+ * 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
+ * frame run it once.
+ */
+export function watchDom(win, run, opts = {}) {
+    const hub = hubFor(win);
+    const sub = { run, opts, pending: false };
+    hub.subs.push(sub);
+    hub.refresh();
+    let active = true;
+    return {
+        schedule: () => { if (active)
+            hub.mark(sub); },
+        dispose() {
+            if (!active)
+                return;
+            active = false;
+            const index = hub.subs.indexOf(sub);
+            if (index >= 0)
+                hub.subs.splice(index, 1);
+            hub.refresh();
+        },
+    };
+}
+//# sourceMappingURL=domHub.js.map

package/dist/runtime/domHub.js.map

@@ -0,0 +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"]}

package/dist/runtime/linkRouting.d.ts

@@ -0,0 +1,13 @@
+export type LinkMode = 'same' | 'pane' | 'tab' | 'browser';
+export type LinkRoutingHandle = {
+    configure(value: unknown): void;
+    dispose(): void;
+};
+export type LinkSite = {
+    /** The site page a click on `target` would open in place, when it is one to divert; else null. */
+    clickedUrl(target: Element | null, location: Location): string | null;
+    /** The key of the mode in the native `configure` payload (`{ [configKey]: mode }`). */
+    configKey: string;
+};
+export declare const LINK_MODES: readonly LinkMode[];
+export declare function installLinkRouting(win: Window, site: LinkSite): LinkRoutingHandle;

package/dist/runtime/linkRouting.js

@@ -0,0 +1,35 @@
+// "Links to site pages" setting: when it is not "same", a plain click on one of the site's own pages
+// (a post, a profile, a channel, ...) opens that page beside the pane, in a new tab or in the system
+// browser instead of replacing what you are reading. The click becomes an ordinary new-window
+// request; native code (`new_window_mode`) decides where it opens. Which clicks count is the site
+// adapter's `clickedUrl`; everything else (navigation, tabs, menus, buttons) is never touched.
+export const LINK_MODES = ['same', 'pane', 'tab', 'browser'];
+export function installLinkRouting(win, site) {
+    let mode = 'same';
+    const onClick = (event) => {
+        if (mode === 'same' || event.button !== 0 || event.defaultPrevented)
+            return;
+        // Modified clicks keep the site's own meaning (Ctrl/Cmd+click already opens a new tab).
+        if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey)
+            return;
+        if (win.getSelection?.()?.toString().trim())
+            return;
+        const url = site.clickedUrl(event.target instanceof Element ? event.target : null, win.location);
+        if (!url)
+            return;
+        // Before the site's own handlers (frameworks listen below window): the in-place navigation never starts.
+        event.preventDefault();
+        event.stopPropagation();
+        win.open(url, '_blank', 'noopener');
+    };
+    win.addEventListener('click', onClick, true);
+    return {
+        configure(value) {
+            const next = value?.[site.configKey];
+            if (typeof next === 'string' && LINK_MODES.includes(next))
+                mode = next;
+        },
+        dispose() { win.removeEventListener('click', onClick, true); },
+    };
+}
+//# sourceMappingURL=linkRouting.js.map

package/dist/runtime/linkRouting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkRouting.js","sourceRoot":"","sources":["../../../runtime/src/linkRouting.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,qGAAqG;AACrG,8FAA8F;AAC9F,kGAAkG;AAClG,+FAA+F;AAY/F,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAElF,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,IAAc;IAC5D,IAAI,IAAI,GAAa,MAAM,CAAC;IAC5B,MAAM,OAAO,GAAG,CAAC,KAAiB,EAAE,EAAE;QACpC,IAAI,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,gBAAgB;YAAE,OAAO;QAC5E,wFAAwF;QACxF,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM;YAAE,OAAO;QAC7E,IAAI,GAAG,CAAC,YAAY,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE;YAAE,OAAO;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjG,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,yGAAyG;QACzG,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,CAAC,eAAe,EAAE,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACtC,CAAC,CAAC;IACF,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC7C,OAAO;QACL,SAAS,CAAC,KAAK;YACb,MAAM,IAAI,GAAI,KAAwC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACzE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAK,UAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,IAAI,GAAG,IAAgB,CAAC;QAC5G,CAAC;QACD,OAAO,KAAK,GAAG,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;KAC/D,CAAC;AACJ,CAAC","sourcesContent":["// \"Links to site pages\" setting: when it is not \"same\", a plain click on one of the site's own pages\n// (a post, a profile, a channel, ...) opens that page beside the pane, in a new tab or in the system\n// browser instead of replacing what you are reading. The click becomes an ordinary new-window\n// request; native code (`new_window_mode`) decides where it opens. Which clicks count is the site\n// adapter's `clickedUrl`; everything else (navigation, tabs, menus, buttons) is never touched.\n\nexport type LinkMode = 'same' | 'pane' | 'tab' | 'browser';\nexport type LinkRoutingHandle = { configure(value: unknown): void; dispose(): void };\n\nexport type LinkSite = {\n  /** The site page a click on `target` would open in place, when it is one to divert; else null. */\n  clickedUrl(target: Element | null, location: Location): string | null;\n  /** The key of the mode in the native `configure` payload (`{ [configKey]: mode }`). */\n  configKey: string;\n};\n\nexport const LINK_MODES: readonly LinkMode[] = ['same', 'pane', 'tab', 'browser'];\n\nexport function installLinkRouting(win: Window, site: LinkSite): LinkRoutingHandle {\n  let mode: LinkMode = 'same';\n  const onClick = (event: MouseEvent) => {\n    if (mode === 'same' || event.button !== 0 || event.defaultPrevented) return;\n    // Modified clicks keep the site's own meaning (Ctrl/Cmd+click already opens a new tab).\n    if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n    if (win.getSelection?.()?.toString().trim()) return;\n    const url = site.clickedUrl(event.target instanceof Element ? event.target : null, win.location);\n    if (!url) return;\n    // Before the site's own handlers (frameworks listen below window): the in-place navigation never starts.\n    event.preventDefault();\n    event.stopPropagation();\n    win.open(url, '_blank', 'noopener');\n  };\n  win.addEventListener('click', onClick, true);\n  return {\n    configure(value) {\n      const next = (value as Record<string, unknown> | null)?.[site.configKey];\n      if (typeof next === 'string' && (LINK_MODES as readonly string[]).includes(next)) mode = next as LinkMode;\n    },\n    dispose() { win.removeEventListener('click', onClick, true); },\n  };\n}\n"]}

package/dist/runtime/netHub.d.ts

@@ -0,0 +1,55 @@
+/** `input`/`init` are fetch's arguments; returns the rewritten URL, or null to leave the request alone. */
+export type Rewrite = (input: unknown, init: RequestInit | undefined) => string | null;
+/** Returns null when the request is not the gate's; otherwise the promise the page gets instead of `send()`. */
+export type Gate = (input: unknown, init: RequestInit | undefined, send: () => Promise<Response>) => Promise<Response> | null;
+export type Tap = {
+    match(url: string): boolean;
+    maxBytes: number;
+    onJson(body: unknown): void;
+};
+/** XHR counterpart of `Gate` (many web clients still send their API calls with XMLHttpRequest). */
+export type XhrGate = {
+    /**
+     * The page (re)opens this XHR object; called before the native `open`. Returning a string opens
+     * that URL instead (a request rewrite, like `Rewrite` for fetch).
+     */
+    open?(xhr: XMLHttpRequest, request: {
+        method: string;
+        url: string;
+    }): string | void;
+    /**
+     * The page calls `send(body)` on an API (or XHR-mark) request. Returns true when the gate took it
+     * over: it then calls `sendNative()` itself (now or later; `sendNative(body)` sends that body
+     * instead of the page's) or completes the XHR on its own.
+     */
+    send(xhr: XMLHttpRequest, request: {
+        method: string;
+        url: string;
+    }, body: unknown, sendNative: (...body: [] | [unknown]) => void): boolean;
+};
+export type NetHubConfig = {
+    /** URL substrings of the site's API calls; only these reach rewrites, gates and taps. */
+    apiMarks: string[];
+    /** Extra URL substrings that reach XHR gates only (e.g. a chunked media upload endpoint). */
+    xhrMarks: string[];
+};
+type HubWindow = {
+    fetch: typeof fetch;
+    XMLHttpRequest?: typeof XMLHttpRequest;
+    requestIdleCallback?: (callback: () => void, options?: {
+        timeout: number;
+    }) => number;
+};
+/** Set once by the site adapter, before stages register. */
+export declare function configureNetHub(next: Partial<NetHubConfig>): void;
+/** Whether `url` is one of the site's API calls (plain substring checks, no URL parsing). */
+export declare function isApiUrl(url: string): boolean;
+/** The request URL as given (string, URL or Request), without parsing it. */
+export declare function rawUrl(input: unknown): string;
+/** Whether the shared hook is installed as `target.fetch` (for callers that report `installed`). */
+export declare function fetchHooked(target: HubWindow): boolean;
+export declare function addRewrite(target: HubWindow, rewrite: Rewrite): () => void;
+export declare function addGate(target: HubWindow, gate: Gate): () => void;
+export declare function addTap(target: HubWindow, tap: Tap): () => void;
+export declare function addXhrGate(target: HubWindow, gate: XhrGate): () => void;
+export {};