waybetter 0.1.1 → 0.7.0

package/dist/runtime/pageStrings.js

@@ -0,0 +1,76 @@
+// The page runtime's language. Native code hands site tabs the owner's language and exactly the
+// strings the page needs (the app's own page strings, the plugin UI kit's `kit.*` and the bundled
+// plugins' `plugin.*`; waybetter-host `i18n::page_script`) as `<global>.i18n.set({ locale, dir,
+// messages })`, queued in `__wbI18n` until the runtime exists. The messages arrive already resolved
+// along the language's fallback chain by the shell; English is built into the runtime (the build
+// keeps only those prefixes of the app's catalog). A switch applies live: `onChange` listeners
+// re-render. Everything delivered is data: checked, bounded and inserted as text.
+import { formatMessage, normalizeLocale } from "./i18n.js";
+import { pluginNamespace } from "./pluginI18n.js";
+/** A delivery holds at most this many messages, each at most this long. */
+export const PAGE_STRING_LIMITS = Object.freeze({ keys: 4000, value: 2000 });
+export function createPageStrings(options) {
+    const { english, prefixes, label, bundledPrefix } = options;
+    let delivered = {};
+    let active = 'en';
+    const listeners = new Set();
+    const message = (key) => delivered[key] ?? english[key];
+    const t = (key, params) => {
+        const text = message(key);
+        return text === undefined ? key : formatMessage(text, params ?? {}, active);
+    };
+    function set(value) {
+        if (!value || typeof value !== 'object')
+            return;
+        const input = value;
+        const tag = normalizeLocale(input.locale);
+        if (!tag || !input.messages || typeof input.messages !== 'object')
+            return;
+        const next = {};
+        let count = 0;
+        for (const [key, text] of Object.entries(input.messages)) {
+            if (count >= PAGE_STRING_LIMITS.keys)
+                break;
+            if (typeof text !== 'string' || text.length > PAGE_STRING_LIMITS.value || !prefixes.some(prefix => key.startsWith(prefix)))
+                continue;
+            next[key] = text;
+            count += 1;
+        }
+        const changed = tag !== active || JSON.stringify(next) !== JSON.stringify(delivered);
+        delivered = next;
+        active = tag;
+        if (!changed)
+            return;
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error(`[${label}] language listener failed`, error);
+            }
+        }
+    }
+    const onChange = (listener) => {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    };
+    return {
+        message,
+        t,
+        locale: () => active,
+        set,
+        onChange,
+        source: { locale: () => active, message, onChange },
+        // Bundled plugins are installed as `<bundledPrefix><name>.plugin.js`, but their strings are keyed
+        // by their source name: without this, every bundled plugin would stay English.
+        pluginNamespace(id) {
+            const namespace = pluginNamespace(id);
+            if (!bundledPrefix || !namespace.startsWith(bundledPrefix))
+                return namespace;
+            const bare = namespace.slice(bundledPrefix.length);
+            const prefix = `plugin.${bare}.`;
+            return Object.keys(english).some(key => key.startsWith(prefix)) ? bare : namespace;
+        },
+    };
+}
+//# sourceMappingURL=pageStrings.js.map

package/dist/runtime/pageStrings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageStrings.js","sourceRoot":"","sources":["../../../runtime/src/pageStrings.ts"],"names":[],"mappings":"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","sourcesContent":["// The page runtime's language. Native code hands site tabs the owner's language and exactly the\n// strings the page needs (the app's own page strings, the plugin UI kit's `kit.*` and the bundled\n// plugins' `plugin.*`; waybetter-host `i18n::page_script`) as `<global>.i18n.set({ locale, dir,\n// messages })`, queued in `__wbI18n` until the runtime exists. The messages arrive already resolved\n// along the language's fallback chain by the shell; English is built into the runtime (the build\n// keeps only those prefixes of the app's catalog). A switch applies live: `onChange` listeners\n// re-render. Everything delivered is data: checked, bounded and inserted as text.\n\nimport { formatMessage, normalizeLocale, type Params } from './i18n.ts';\nimport { pluginNamespace, type I18nSource } from './pluginI18n.ts';\n\nexport type PageStringsOptions = {\n  /** English for every string the page shows (the app's page strings and the framework's kit words). */\n  english: Readonly<Record<string, string>>;\n  /** Key prefixes a delivery may carry (`['x.', 'kit.', 'plugin.']`); other keys are dropped. */\n  prefixes: readonly string[];\n  /** Console label (the app's name). */\n  label: string;\n  /**\n   * The file-name prefix the app installs its bundled plugins with (`bt-` for `bt-<name>.plugin.js`)\n   * when their strings are keyed by the source name (`plugin.<name>.*`).\n   */\n  bundledPrefix?: string;\n};\n\nexport type PageStrings = {\n  /** The active language's message for `key`, else English. */\n  message(key: string): string | undefined;\n  /** A runtime string: `t('x.media.download')`. Placeholder values are inserted as text. */\n  t(key: string, params?: Params): string;\n  locale(): string;\n  /** Native code delivers `{ locale, dir, messages }`; anything malformed is ignored (English stays). */\n  set(value: unknown): void;\n  onChange(listener: () => void): () => void;\n  /** The plugin API's view of the language (pluginI18n.ts): `api.i18n` and the UI kit's words. */\n  source: I18nSource;\n  /** A plugin file's catalog namespace (`plugin.<namespace>.*`). */\n  pluginNamespace(id: string): string;\n};\n\n/** A delivery holds at most this many messages, each at most this long. */\nexport const PAGE_STRING_LIMITS = Object.freeze({ keys: 4000, value: 2000 });\n\nexport function createPageStrings(options: PageStringsOptions): PageStrings {\n  const { english, prefixes, label, bundledPrefix } = options;\n  let delivered: Record<string, string> = {};\n  let active = 'en';\n  const listeners = new Set<() => void>();\n\n  const message = (key: string) => delivered[key] ?? english[key];\n  const t = (key: string, params?: Params) => {\n    const text = message(key);\n    return text === undefined ? key : formatMessage(text, params ?? {}, active);\n  };\n\n  function set(value: unknown) {\n    if (!value || typeof value !== 'object') return;\n    const input = value as { locale?: unknown; messages?: unknown };\n    const tag = normalizeLocale(input.locale);\n    if (!tag || !input.messages || typeof input.messages !== 'object') return;\n    const next: Record<string, string> = {};\n    let count = 0;\n    for (const [key, text] of Object.entries(input.messages as Record<string, unknown>)) {\n      if (count >= PAGE_STRING_LIMITS.keys) break;\n      if (typeof text !== 'string' || text.length > PAGE_STRING_LIMITS.value || !prefixes.some(prefix => key.startsWith(prefix))) continue;\n      next[key] = text;\n      count += 1;\n    }\n    const changed = tag !== active || JSON.stringify(next) !== JSON.stringify(delivered);\n    delivered = next;\n    active = tag;\n    if (!changed) return;\n    for (const listener of [...listeners]) {\n      try { listener(); } catch (error) { console.error(`[${label}] language listener failed`, error); }\n    }\n  }\n\n  const onChange = (listener: () => void) => {\n    listeners.add(listener);\n    return () => { listeners.delete(listener); };\n  };\n\n  return {\n    message,\n    t,\n    locale: () => active,\n    set,\n    onChange,\n    source: { locale: () => active, message, onChange },\n    // Bundled plugins are installed as `<bundledPrefix><name>.plugin.js`, but their strings are keyed\n    // by their source name: without this, every bundled plugin would stay English.\n    pluginNamespace(id) {\n      const namespace = pluginNamespace(id);\n      if (!bundledPrefix || !namespace.startsWith(bundledPrefix)) return namespace;\n      const bare = namespace.slice(bundledPrefix.length);\n      const prefix = `plugin.${bare}.`;\n      return Object.keys(english).some(key => key.startsWith(prefix)) ? bare : namespace;\n    },\n  };\n}\n"]}

package/dist/runtime/panelButton.d.ts

@@ -0,0 +1,33 @@
+/** Gap between the button and the pane edge or the site's bottom bar. */
+export declare const BUTTON_GAP = 16;
+/**
+ * Pure: the button's `bottom` offset. `barTop` is the top edge of the site's bottom bar, null when
+ * it has none; a zero-height or implausibly tall bar (a desktop layout may keep an empty one at the
+ * bottom edge) adds nothing.
+ */
+export declare function buttonBottom(barTop: number | null, viewportHeight: number, gap?: number): number;
+export type PanelButtonSite = {
+    /** The floating button's DOM id. */
+    id: string;
+    /** The app's logo (an image URL, usually a data URI: the site's CSP may block others). */
+    logo: string;
+    /** The button's tooltip and accessible name, in the owner's language. */
+    title(): string;
+    /** Puts the entry into the site's own navigation (re-attaching it when the site re-renders); true while it is there. */
+    mountNav?(open: () => void): boolean;
+    /** Pages where the button stays hidden (a full-pane photo or video viewer whose actions sit at the bottom). */
+    hiddenOn?(pathname: string): boolean;
+    /** The site is showing a modal sheet or a dialog layer: the button hides under it. */
+    overlaySelector?: string;
+    /** The site's bottom bar (a mobile layout): the button sits above it. */
+    bottomBarSelector?: string;
+};
+/** Pure: whether the button stays hidden on this route / with a site overlay open. */
+export declare function buttonHidden(site: Pick<PanelButtonSite, 'hiddenOn'>, pathname: string, overlayOpen: boolean): boolean;
+/**
+ * Keeps the panel entry on the page: the site's navigation item when `mountNav` places one, else
+ * the floating button. `open` opens the panel (the runtime's `open()`).
+ */
+export declare function installPanelButton(win: Window & typeof globalThis, site: PanelButtonSite, open: () => void): {
+    sync(): void;
+};

package/dist/runtime/panelButton.js

@@ -0,0 +1,83 @@
+// The way from a site page into the app's panel. The site adapter puts an entry into the site's own
+// navigation when it has one (`mountNav`: X clones its "More" item); where the page draws no
+// navigation (a full-pane viewer opened by URL, signed-out pages, a mobile layout) a small floating
+// button stands in. The button must never cover the site's own UI: it hides while the site layers
+// something over the page and sits above the site's bottom bar. Both are re-checked on every DOM
+// change through the shared DOM hub.
+import { watchDom } from "./domHub.js";
+/** Gap between the button and the pane edge or the site's bottom bar. */
+export const BUTTON_GAP = 16;
+/**
+ * Pure: the button's `bottom` offset. `barTop` is the top edge of the site's bottom bar, null when
+ * it has none; a zero-height or implausibly tall bar (a desktop layout may keep an empty one at the
+ * bottom edge) adds nothing.
+ */
+export function buttonBottom(barTop, viewportHeight, gap = BUTTON_GAP) {
+    if (barTop === null)
+        return gap;
+    const bar = viewportHeight - barTop;
+    return bar > 0 && bar < viewportHeight / 3 ? Math.round(bar) + gap : gap;
+}
+/** Pure: whether the button stays hidden on this route / with a site overlay open. */
+export function buttonHidden(site, pathname, overlayOpen) {
+    return overlayOpen || !!site.hiddenOn?.(pathname);
+}
+/**
+ * Keeps the panel entry on the page: the site's navigation item when `mountNav` places one, else
+ * the floating button. `open` opens the panel (the runtime's `open()`).
+ */
+export function installPanelButton(win, site, open) {
+    const doc = win.document;
+    const create = () => {
+        const button = doc.createElement('button');
+        button.id = site.id;
+        button.type = 'button';
+        button.title = site.title();
+        button.setAttribute('aria-label', button.title);
+        const img = doc.createElement('img');
+        img.src = site.logo;
+        img.alt = '';
+        Object.assign(img.style, { width: '100%', height: '100%', borderRadius: '22%', display: 'block' });
+        button.appendChild(img);
+        Object.assign(button.style, {
+            position: 'fixed', left: '16px', bottom: '16px', zIndex: '2147483646', width: '40px', height: '40px',
+            padding: '0', border: '0', background: 'transparent', cursor: 'pointer', boxShadow: '0 4px 14px rgba(0,0,0,.35)', borderRadius: '22%',
+        });
+        button.addEventListener('click', () => open());
+        return button;
+    };
+    const syncButton = (navMounted) => {
+        const existing = doc.getElementById(site.id);
+        if (navMounted) {
+            existing?.remove();
+            return;
+        }
+        const button = existing ?? create();
+        const overlay = site.overlaySelector ? !!doc.querySelector(site.overlaySelector) : false;
+        const barTop = site.bottomBarSelector ? doc.querySelector(site.bottomBarSelector)?.getBoundingClientRect().top ?? null : null;
+        const display = buttonHidden(site, win.location.pathname, overlay) ? 'none' : 'block';
+        const bottom = `${buttonBottom(barTop, win.innerHeight)}px`;
+        if (button.style.display !== display)
+            button.style.display = display;
+        if (button.style.bottom !== bottom)
+            button.style.bottom = bottom;
+        if (!existing)
+            doc.body.appendChild(button);
+    };
+    const sync = () => {
+        if (!doc.body)
+            return;
+        syncButton(site.mountNav?.(open) ?? false);
+    };
+    const start = () => {
+        sync();
+        // Sites re-render their navigation on route and layout changes; re-attach when the entry disappears.
+        watchDom(win, sync);
+    };
+    if (doc.readyState === 'loading')
+        doc.addEventListener('DOMContentLoaded', start, { once: true });
+    else
+        start();
+    return { sync };
+}
+//# sourceMappingURL=panelButton.js.map

package/dist/runtime/panelButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"panelButton.js","sourceRoot":"","sources":["../../../runtime/src/panelButton.ts"],"names":[],"mappings":"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","sourcesContent":["// The way from a site page into the app's panel. The site adapter puts an entry into the site's own\n// navigation when it has one (`mountNav`: X clones its \"More\" item); where the page draws no\n// navigation (a full-pane viewer opened by URL, signed-out pages, a mobile layout) a small floating\n// button stands in. The button must never cover the site's own UI: it hides while the site layers\n// something over the page and sits above the site's bottom bar. Both are re-checked on every DOM\n// change through the shared DOM hub.\n\nimport { watchDom, type DomWindow } from './domHub.ts';\n\n/** Gap between the button and the pane edge or the site's bottom bar. */\nexport const BUTTON_GAP = 16;\n\n/**\n * Pure: the button's `bottom` offset. `barTop` is the top edge of the site's bottom bar, null when\n * it has none; a zero-height or implausibly tall bar (a desktop layout may keep an empty one at the\n * bottom edge) adds nothing.\n */\nexport function buttonBottom(barTop: number | null, viewportHeight: number, gap = BUTTON_GAP): number {\n  if (barTop === null) return gap;\n  const bar = viewportHeight - barTop;\n  return bar > 0 && bar < viewportHeight / 3 ? Math.round(bar) + gap : gap;\n}\n\nexport type PanelButtonSite = {\n  /** The floating button's DOM id. */\n  id: string;\n  /** The app's logo (an image URL, usually a data URI: the site's CSP may block others). */\n  logo: string;\n  /** The button's tooltip and accessible name, in the owner's language. */\n  title(): string;\n  /** Puts the entry into the site's own navigation (re-attaching it when the site re-renders); true while it is there. */\n  mountNav?(open: () => void): boolean;\n  /** Pages where the button stays hidden (a full-pane photo or video viewer whose actions sit at the bottom). */\n  hiddenOn?(pathname: string): boolean;\n  /** The site is showing a modal sheet or a dialog layer: the button hides under it. */\n  overlaySelector?: string;\n  /** The site's bottom bar (a mobile layout): the button sits above it. */\n  bottomBarSelector?: string;\n};\n\n/** Pure: whether the button stays hidden on this route / with a site overlay open. */\nexport function buttonHidden(site: Pick<PanelButtonSite, 'hiddenOn'>, pathname: string, overlayOpen: boolean): boolean {\n  return overlayOpen || !!site.hiddenOn?.(pathname);\n}\n\n/**\n * Keeps the panel entry on the page: the site's navigation item when `mountNav` places one, else\n * the floating button. `open` opens the panel (the runtime's `open()`).\n */\nexport function installPanelButton(win: Window & typeof globalThis, site: PanelButtonSite, open: () => void): { sync(): void } {\n  const doc = win.document;\n\n  const create = (): HTMLButtonElement => {\n    const button = doc.createElement('button');\n    button.id = site.id;\n    button.type = 'button';\n    button.title = site.title();\n    button.setAttribute('aria-label', button.title);\n    const img = doc.createElement('img');\n    img.src = site.logo;\n    img.alt = '';\n    Object.assign(img.style, { width: '100%', height: '100%', borderRadius: '22%', display: 'block' });\n    button.appendChild(img);\n    Object.assign(button.style, {\n      position: 'fixed', left: '16px', bottom: '16px', zIndex: '2147483646', width: '40px', height: '40px',\n      padding: '0', border: '0', background: 'transparent', cursor: 'pointer', boxShadow: '0 4px 14px rgba(0,0,0,.35)', borderRadius: '22%',\n    });\n    button.addEventListener('click', () => open());\n    return button;\n  };\n\n  const syncButton = (navMounted: boolean) => {\n    const existing = doc.getElementById(site.id);\n    if (navMounted) { existing?.remove(); return; }\n    const button = existing ?? create();\n    const overlay = site.overlaySelector ? !!doc.querySelector(site.overlaySelector) : false;\n    const barTop = site.bottomBarSelector ? doc.querySelector(site.bottomBarSelector)?.getBoundingClientRect().top ?? null : null;\n    const display = buttonHidden(site, win.location.pathname, overlay) ? 'none' : 'block';\n    const bottom = `${buttonBottom(barTop, win.innerHeight)}px`;\n    if (button.style.display !== display) button.style.display = display;\n    if (button.style.bottom !== bottom) button.style.bottom = bottom;\n    if (!existing) doc.body.appendChild(button);\n  };\n\n  const sync = () => {\n    if (!doc.body) return;\n    syncButton(site.mountNav?.(open) ?? false);\n  };\n  const start = () => {\n    sync();\n    // Sites re-render their navigation on route and layout changes; re-attach when the entry disappears.\n    watchDom(win as unknown as DomWindow, sync);\n  };\n  if (doc.readyState === 'loading') doc.addEventListener('DOMContentLoaded', start, { once: true });\n  else start();\n  return { sync };\n}\n"]}

package/dist/runtime/permissions.d.ts

@@ -0,0 +1,47 @@
+/** Grants a plugin can declare. `network` / `network:none` are declarations only (see above). */
+export declare const PLUGIN_PERMISSIONS: readonly ["storage", "ui", "clipboard", "account", "users", "commands", "network", "network:none"];
+export type PluginPermission = (typeof PLUGIN_PERMISSIONS)[number];
+/** Which permission each gated API member needs. Members not listed need none (DOM helpers, theme). */
+export type PermissionGates = Readonly<Record<string, PluginPermission>>;
+/** The core API's gated members. A site adds its own (e.g. `account`, `users`). */
+export declare const CORE_GATES: PermissionGates;
+/**
+ * Parses the value of a `@permissions` header line (comma and/or space separated, case-insensitive).
+ * Same rules as the native host's `parse_permissions`: unknown names and `network` together with
+ * `network:none` are errors; duplicates collapse; `none` alone means "no gated API".
+ */
+export declare function parsePermissions(value: string): {
+    permissions: PluginPermission[];
+} | {
+    error: string;
+};
+export declare class PluginPermissionError extends Error {
+    readonly plugin: string;
+    readonly member: string;
+    readonly permission: PluginPermission;
+    constructor(plugin: string, member: string, permission: PluginPermission);
+}
+/**
+ * The API as plugin `plugin` sees it with `grants`: gated members it was not granted throw a
+ * `PluginPermissionError` when called; everything else is the shared API. Frozen, like the API.
+ */
+export declare function scopePluginApi<T extends object>(api: T, grants: readonly string[], plugin: string, gates?: PermissionGates): T;
+export type PluginContext<T extends object> = {
+    /**
+     * Runs `fn` as plugin `id` (its module body, constructor, `start()` and `stop()`): while it runs,
+     * `current()` is that plugin's API. `grants`: a list = the plugin declared these; `null` = legacy
+     * plugin without a `@permissions` line (the full API); `undefined` = keep what `id` registered.
+     */
+    run<R>(id: string, grants: readonly string[] | null | undefined, fn: () => R): R;
+    /** The API for the code running now: a plugin's view inside `run`, else the full API. */
+    current(): T;
+    /** What `id` registered: its grants, `null` for legacy, `undefined` when never run. */
+    grants(id: string): readonly string[] | null | undefined;
+};
+/**
+ * Members bound to the plugin a view belongs to (its `i18n`, keyed by the plugin file), applied to
+ * every plugin's view, legacy plugins included. Not a permission: bound members are never gated.
+ */
+export type PluginBindings<T extends object> = (full: T, plugin: string) => Partial<T>;
+/** Per-plugin API views for a runtime whose `api` getter returns `context.current()`. */
+export declare function createPluginContext<T extends object>(full: T, gates?: PermissionGates, bind?: PluginBindings<T>): PluginContext<T>;

package/dist/runtime/permissions.js

@@ -0,0 +1,141 @@
+// Plugin permissions: what a `*.plugin.js` declares in its header (`@permissions storage, ui`) and
+// the per-plugin view of the plugin API that holds it to that declaration.
+//
+// Be clear about what this is. Plugins are JavaScript running in the site's page: they can read
+// and change the page, call `fetch`, and reach `window.<Runtime>` directly. No page-level check can
+// stop code that wants to get around it. Permissions are
+//   - a declaration the owner reviews before installing (the install screen and the Plugins list
+//     show them), checked again by the store and by reviewers against the source, and
+//   - a guard rail for honest code: the `api` a plugin receives throws on members it did not
+//     declare, so an undeclared use fails loudly in development instead of shipping silently.
+// A plugin without a `@permissions` line is "legacy": it gets the whole API, as before, and the app
+// labels it "legacy, full page access". `network:none` is a promise (checked by review and a source
+// scan at install time), not something the page can enforce.
+/** Grants a plugin can declare. `network` / `network:none` are declarations only (see above). */
+export const PLUGIN_PERMISSIONS = ['storage', 'ui', 'clipboard', 'account', 'users', 'commands', 'network', 'network:none'];
+/** The core API's gated members. A site adds its own (e.g. `account`, `users`). */
+export const CORE_GATES = Object.freeze({
+    storage: 'storage',
+    ui: 'ui',
+    toast: 'ui',
+    copyText: 'clipboard',
+    // Command palette entries (commands.ts); also gates `scope().commands`.
+    commands: 'commands',
+});
+const KNOWN = new Set(PLUGIN_PERMISSIONS);
+/**
+ * Parses the value of a `@permissions` header line (comma and/or space separated, case-insensitive).
+ * Same rules as the native host's `parse_permissions`: unknown names and `network` together with
+ * `network:none` are errors; duplicates collapse; `none` alone means "no gated API".
+ */
+export function parsePermissions(value) {
+    const tokens = value.split(/[\s,]+/).map(token => token.trim().toLowerCase()).filter(Boolean);
+    const out = [];
+    for (const token of tokens) {
+        if (token === 'none')
+            continue;
+        if (!KNOWN.has(token))
+            return { error: `unknown permission "${token.slice(0, 40)}"` };
+        if (!out.includes(token))
+            out.push(token);
+    }
+    if (out.includes('network') && out.includes('network:none'))
+        return { error: '"network" and "network:none" contradict each other' };
+    return { permissions: out };
+}
+export class PluginPermissionError extends Error {
+    plugin;
+    member;
+    permission;
+    constructor(plugin, member, permission) {
+        super(`${plugin}: api.${member} needs the "${permission}" permission. Add it to the plugin's header: @permissions ${permission}`);
+        this.name = 'PluginPermissionError';
+        this.plugin = plugin;
+        this.member = member;
+        this.permission = permission;
+    }
+}
+function denied(plugin, member, permission) {
+    return () => { throw new PluginPermissionError(plugin, member, permission); };
+}
+/** An object whose every function member throws (`api.ui.toast`, `api.users.get`, ...). */
+function deniedObject(value, plugin, member, permission) {
+    const out = {};
+    for (const key of Object.keys(value)) {
+        out[key] = typeof value[key] === 'function' ? denied(plugin, `${member}.${key}`, permission) : undefined;
+    }
+    return Object.freeze(out);
+}
+/** A plugin's scope (`api.scope()`) whose `ui` is gated like `api.ui`. */
+function scopeView(scope, granted, plugin, gates) {
+    const view = {};
+    for (const key of Object.getOwnPropertyNames(scope)) {
+        const gate = gates[key];
+        const descriptor = Object.getOwnPropertyDescriptor(scope, key);
+        if (gate && !granted.has(gate)) {
+            Object.defineProperty(view, key, {
+                enumerable: true,
+                get: () => {
+                    const value = scope[key];
+                    return typeof value === 'function' ? denied(plugin, `scope().${key}`, gate) : deniedObject(value, plugin, `scope().${key}`, gate);
+                },
+            });
+        }
+        else if (descriptor.get) {
+            Object.defineProperty(view, key, { enumerable: true, get: () => scope[key] });
+        }
+        else {
+            const value = descriptor.value;
+            view[key] = typeof value === 'function' ? value.bind(scope) : value;
+        }
+    }
+    return view;
+}
+/**
+ * The API as plugin `plugin` sees it with `grants`: gated members it was not granted throw a
+ * `PluginPermissionError` when called; everything else is the shared API. Frozen, like the API.
+ */
+export function scopePluginApi(api, grants, plugin, gates = CORE_GATES) {
+    const granted = new Set(grants);
+    const out = {};
+    for (const key of Object.keys(api)) {
+        const value = api[key];
+        const gate = gates[key];
+        if (gate && !granted.has(gate)) {
+            out[key] = typeof value === 'function' ? denied(plugin, key, gate) : value && typeof value === 'object' ? deniedObject(value, plugin, key, gate) : undefined;
+        }
+        else if (key === 'scope' && typeof value === 'function') {
+            out[key] = () => scopeView(value.call(api), granted, plugin, gates);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return Object.freeze(out);
+}
+/** Per-plugin API views for a runtime whose `api` getter returns `context.current()`. */
+export function createPluginContext(full, gates = CORE_GATES, bind) {
+    const registered = new Map();
+    const stack = [];
+    return {
+        run(id, grants, fn) {
+            let entry = registered.get(id);
+            if (grants !== undefined || !entry) {
+                const list = Array.isArray(grants) ? Object.freeze(grants.filter(grant => typeof grant === 'string' && KNOWN.has(grant))) : null;
+                const view = list ? scopePluginApi(full, list, id, gates) : full;
+                entry = { grants: list, api: bind ? Object.freeze({ ...view, ...bind(full, id) }) : view };
+                registered.set(id, entry);
+            }
+            stack.push(entry.api);
+            try {
+                return fn();
+            }
+            finally {
+                stack.pop();
+            }
+        },
+        current: () => stack[stack.length - 1] ?? full,
+        grants: id => registered.get(id)?.grants,
+    };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/runtime/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../../runtime/src/permissions.ts"],"names":[],"mappings":"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","sourcesContent":["// Plugin permissions: what a `*.plugin.js` declares in its header (`@permissions storage, ui`) and\n// the per-plugin view of the plugin API that holds it to that declaration.\n//\n// Be clear about what this is. Plugins are JavaScript running in the site's page: they can read\n// and change the page, call `fetch`, and reach `window.<Runtime>` directly. No page-level check can\n// stop code that wants to get around it. Permissions are\n//   - a declaration the owner reviews before installing (the install screen and the Plugins list\n//     show them), checked again by the store and by reviewers against the source, and\n//   - a guard rail for honest code: the `api` a plugin receives throws on members it did not\n//     declare, so an undeclared use fails loudly in development instead of shipping silently.\n// A plugin without a `@permissions` line is \"legacy\": it gets the whole API, as before, and the app\n// labels it \"legacy, full page access\". `network:none` is a promise (checked by review and a source\n// scan at install time), not something the page can enforce.\n\n/** Grants a plugin can declare. `network` / `network:none` are declarations only (see above). */\nexport const PLUGIN_PERMISSIONS = ['storage', 'ui', 'clipboard', 'account', 'users', 'commands', 'network', 'network:none'] as const;\nexport type PluginPermission = (typeof PLUGIN_PERMISSIONS)[number];\n\n/** Which permission each gated API member needs. Members not listed need none (DOM helpers, theme). */\nexport type PermissionGates = Readonly<Record<string, PluginPermission>>;\n\n/** The core API's gated members. A site adds its own (e.g. `account`, `users`). */\nexport const CORE_GATES: PermissionGates = Object.freeze({\n  storage: 'storage',\n  ui: 'ui',\n  toast: 'ui',\n  copyText: 'clipboard',\n  // Command palette entries (commands.ts); also gates `scope().commands`.\n  commands: 'commands',\n});\n\nconst KNOWN = new Set<string>(PLUGIN_PERMISSIONS);\n\n/**\n * Parses the value of a `@permissions` header line (comma and/or space separated, case-insensitive).\n * Same rules as the native host's `parse_permissions`: unknown names and `network` together with\n * `network:none` are errors; duplicates collapse; `none` alone means \"no gated API\".\n */\nexport function parsePermissions(value: string): { permissions: PluginPermission[] } | { error: string } {\n  const tokens = value.split(/[\\s,]+/).map(token => token.trim().toLowerCase()).filter(Boolean);\n  const out: PluginPermission[] = [];\n  for (const token of tokens) {\n    if (token === 'none') continue;\n    if (!KNOWN.has(token)) return { error: `unknown permission \"${token.slice(0, 40)}\"` };\n    if (!out.includes(token as PluginPermission)) out.push(token as PluginPermission);\n  }\n  if (out.includes('network') && out.includes('network:none')) return { error: '\"network\" and \"network:none\" contradict each other' };\n  return { permissions: out };\n}\n\nexport class PluginPermissionError extends Error {\n  readonly plugin: string;\n  readonly member: string;\n  readonly permission: PluginPermission;\n  constructor(plugin: string, member: string, permission: PluginPermission) {\n    super(`${plugin}: api.${member} needs the \"${permission}\" permission. Add it to the plugin's header: @permissions ${permission}`);\n    this.name = 'PluginPermissionError';\n    this.plugin = plugin;\n    this.member = member;\n    this.permission = permission;\n  }\n}\n\ntype Fn = (...args: unknown[]) => unknown;\n\nfunction denied(plugin: string, member: string, permission: PluginPermission): Fn {\n  return () => { throw new PluginPermissionError(plugin, member, permission); };\n}\n\n/** An object whose every function member throws (`api.ui.toast`, `api.users.get`, ...). */\nfunction deniedObject(value: object, plugin: string, member: string, permission: PluginPermission): object {\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    out[key] = typeof (value as Record<string, unknown>)[key] === 'function' ? denied(plugin, `${member}.${key}`, permission) : undefined;\n  }\n  return Object.freeze(out);\n}\n\n/** A plugin's scope (`api.scope()`) whose `ui` is gated like `api.ui`. */\nfunction scopeView(scope: object, granted: ReadonlySet<string>, plugin: string, gates: PermissionGates): object {\n  const view: Record<string, unknown> = {};\n  for (const key of Object.getOwnPropertyNames(scope)) {\n    const gate = gates[key];\n    const descriptor = Object.getOwnPropertyDescriptor(scope, key)!;\n    if (gate && !granted.has(gate)) {\n      Object.defineProperty(view, key, {\n        enumerable: true,\n        get: () => {\n          const value = (scope as Record<string, unknown>)[key];\n          return typeof value === 'function' ? denied(plugin, `scope().${key}`, gate) : deniedObject(value as object, plugin, `scope().${key}`, gate);\n        },\n      });\n    } else if (descriptor.get) {\n      Object.defineProperty(view, key, { enumerable: true, get: () => (scope as Record<string, unknown>)[key] });\n    } else {\n      const value = descriptor.value;\n      view[key] = typeof value === 'function' ? (value as Fn).bind(scope) : value;\n    }\n  }\n  return view;\n}\n\n/**\n * The API as plugin `plugin` sees it with `grants`: gated members it was not granted throw a\n * `PluginPermissionError` when called; everything else is the shared API. Frozen, like the API.\n */\nexport function scopePluginApi<T extends object>(api: T, grants: readonly string[], plugin: string, gates: PermissionGates = CORE_GATES): T {\n  const granted = new Set(grants);\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(api)) {\n    const value = (api as Record<string, unknown>)[key];\n    const gate = gates[key];\n    if (gate && !granted.has(gate)) {\n      out[key] = typeof value === 'function' ? denied(plugin, key, gate) : value && typeof value === 'object' ? deniedObject(value, plugin, key, gate) : undefined;\n    } else if (key === 'scope' && typeof value === 'function') {\n      out[key] = () => scopeView((value as Fn).call(api) as object, granted, plugin, gates);\n    } else {\n      out[key] = value;\n    }\n  }\n  return Object.freeze(out) as T;\n}\n\nexport type PluginContext<T extends object> = {\n  /**\n   * Runs `fn` as plugin `id` (its module body, constructor, `start()` and `stop()`): while it runs,\n   * `current()` is that plugin's API. `grants`: a list = the plugin declared these; `null` = legacy\n   * plugin without a `@permissions` line (the full API); `undefined` = keep what `id` registered.\n   */\n  run<R>(id: string, grants: readonly string[] | null | undefined, fn: () => R): R;\n  /** The API for the code running now: a plugin's view inside `run`, else the full API. */\n  current(): T;\n  /** What `id` registered: its grants, `null` for legacy, `undefined` when never run. */\n  grants(id: string): readonly string[] | null | undefined;\n};\n\n/**\n * Members bound to the plugin a view belongs to (its `i18n`, keyed by the plugin file), applied to\n * every plugin's view, legacy plugins included. Not a permission: bound members are never gated.\n */\nexport type PluginBindings<T extends object> = (full: T, plugin: string) => Partial<T>;\n\n/** Per-plugin API views for a runtime whose `api` getter returns `context.current()`. */\nexport function createPluginContext<T extends object>(full: T, gates: PermissionGates = CORE_GATES, bind?: PluginBindings<T>): PluginContext<T> {\n  const registered = new Map<string, { grants: readonly string[] | null; api: T }>();\n  const stack: T[] = [];\n  return {\n    run(id, grants, fn) {\n      let entry = registered.get(id);\n      if (grants !== undefined || !entry) {\n        const list = Array.isArray(grants) ? Object.freeze(grants.filter(grant => typeof grant === 'string' && KNOWN.has(grant))) : null;\n        const view = list ? scopePluginApi(full, list, id, gates) : full;\n        entry = { grants: list, api: bind ? Object.freeze({ ...view, ...bind(full, id) }) as T : view };\n        registered.set(id, entry);\n      }\n      stack.push(entry.api);\n      try { return fn(); } finally { stack.pop(); }\n    },\n    current: () => stack[stack.length - 1] ?? full,\n    grants: id => registered.get(id)?.grants,\n  };\n}\n"]}

package/dist/runtime/pluginApi.d.ts

@@ -1,3 +1,9 @@
+import { type ThemeApi, type ThemeSource } from './themeApi.ts';
+import { type UiKit } from './ui.ts';
+import { type RootStyles } from './styles.ts';
+import { type CommandDefinition, type CommandInfo, type CommandRegistry } from './commands.ts';
+import { type I18nSource, type PluginI18n, type PluginMessages } from './pluginI18n.ts';
+export type { ThemeApi, ThemeSource, UiKit, CommandDefinition, CommandInfo, CommandRegistry, RootStyles, I18nSource, PluginI18n, PluginMessages };
 export type Dispose = () => void;
 export type PluginStorage = {
     get<T>(key: string, fallback: T): T;
@@ -9,6 +15,8 @@ export type PluginStorage = {
 /** Collects disposers so a plugin's `stop()` is a single `scope.dispose()`. */
 export type PluginScope = {
     css(id: string, css: string): void;
+    /** `api.adoptCSS`, taken off the root on dispose. */
+    adoptCSS(root: ShadowRoot | Document, css: string): RootStyles;
     on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
     observe(selector: string, callback: (element: Element) => void): void;
     onRouteChange(callback: (href: string, previous: string) => void): void;
@@ -17,17 +25,34 @@ export type PluginScope = {
     add<T extends Node>(node: T): T;
     /** Runs `fn` on dispose (restore attributes, clear timers, ...). */
     defer(fn: Dispose): void;
+    /** Calls `callback(theme)` after the theme changes, until dispose. */
+    onThemeChange(callback: Parameters<ThemeApi['onChange']>[0]): void;
+    /** The UI kit, scoped: dialogs and toasts it opened are closed on dispose. */
+    readonly ui: UiKit;
+    /** Command palette entries of the plugin that created this scope, removed on dispose. */
+    readonly commands: {
+        register(definition: CommandDefinition): Dispose;
+    };
     dispose(): void;
 };
 export type CorePluginApi = {
     injectCSS(id: string, css: string): void;
     clearCSS(id: string): void;
+    /**
+     * Styles a shadow root the plugin created (or the document) with a constructable stylesheet:
+     * the page's Content-Security-Policy cannot refuse it, it is parsed once, and it stays with the
+     * root wherever its host is moved. Falls back to a `<style>` element where unsupported.
+     */
+    adoptCSS(root: ShadowRoot | Document, css: string): RootStyles;
     waitFor(selector: string, timeoutMs?: number): Promise<Element>;
     /** Namespaced JSON storage in this tab's localStorage (`<storagePrefix><namespace>:<key>`). */
     storage(namespace: string): PluginStorage;
     /** Called after the page changes route (pushState/replaceState/back/forward). */
     onRouteChange(callback: (href: string, previous: string) => void): Dispose;
-    /** Calls `callback` once for every element matching `selector`, now and as the page renders more. */
+    /**
+     * Calls `callback` once for every element matching `selector`, now and as the page renders more.
+     * Page-wide observers share one MutationObserver (domHub.ts); pass `root` only for a tree of your own.
+     */
     observe(selector: string, callback: (element: Element) => void, root?: ParentNode): Dispose;
     /**
      * Single-key shortcuts: `callback(event, focusedItem)` runs only when the user is not typing, no
@@ -35,9 +60,31 @@ export type CorePluginApi = {
      */
     onKey(callback: (event: KeyboardEvent, item: Element | null) => void): Dispose;
     copyText(text: string): Promise<boolean>;
+    /** A short status message (the UI kit's toast; `ms` is how long it stays). */
     toast(message: string, ms?: number): void;
+    /** Toasts, alerts, confirmations, prompts and dialogs in the active theme (see ui.ts). */
+    ui: UiKit;
+    /** The active theme as values: `current()` and `onChange(fn)` (see themeApi.ts). */
+    theme: ThemeApi;
+    /**
+     * Commands in the shell's command palette (Ctrl+K), listed under the plugin's name and run in
+     * this page (see commands.ts). Removed when the plugin stops.
+     */
+    commands: CommandRegistry;
+    /**
+     * The app's language and the plugin's own strings in it (see pluginI18n.ts). In a plugin's view
+     * it is bound to that plugin (`plugin.<file name>.*` in the app catalog); `namespace(name)` binds
+     * it explicitly.
+     */
+    i18n: PluginI18n;
     scope(): PluginScope;
 };
+/** What the site adapter adds to the core: its theme engine, when it has one. */
+export type CorePluginExtras = {
+    theme?: ThemeSource;
+    /** The app's active locale and catalog (plugin strings, the UI kit's own words). English without it. */
+    i18n?: I18nSource;
+};
 export type PluginApiSite = {
     /** The runtime global, for error messages (`<name>.waitFor timed out`). */
     name: string;
@@ -47,7 +94,9 @@ export type PluginApiSite = {
     storagePrefix: string;
     /** `data-*` key (camelCase) marking plugin `<style>` elements with their id. */
     styleDataKey: string;
+    /** Id of the kit's shadow host element (`<wb-ui id=…>`), kept from the old single toast. */
     toastId: string;
+    /** Accent used when the site has no theme source (and the page shows none). */
     toastBackground: string;
     /** The item a single-key shortcut acts on: the focused element's closest match (a post, a message). */
     itemSelector: string;
@@ -56,4 +105,4 @@ export type PluginApiSite = {
 };
 /** True when a key event belongs to text entry, not to page shortcuts. */
 export declare function isTypingTarget(target: EventTarget | null): boolean;
-export declare function createCorePluginApi(win: Window & typeof globalThis, site: PluginApiSite): CorePluginApi;
+export declare function createCorePluginApi(win: Window & typeof globalThis, site: PluginApiSite, extras?: CorePluginExtras): CorePluginApi;