waybetter 0.1.1 → 0.6.0

package/dist/runtime/settingsForm.js

@@ -0,0 +1,114 @@
+// A settings schema: what a feature (or a plugin) lets its owner adjust, as data. The same schema
+// gives the stored values their shape (`normalizeSettings`: anything missing or of the wrong type
+// takes the field's default, so an old or damaged store never breaks a feature) and draws the
+// controls from the UI kit's form parts (`buildSettingsForm`: check boxes, number, text, select and
+// list fields inside a kit dialog). Labels and hints are catalog keys the caller translates.
+export const SETTINGS_LIMITS = Object.freeze({ fields: 64, text: 2000, listItems: 500, listItem: 500 });
+const valueFields = (schema) => schema.filter((field) => field.type !== 'divider');
+function fieldValue(field, value) {
+    switch (field.type) {
+        case 'toggle':
+            return typeof value === 'boolean' ? value : field.default;
+        case 'number': {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                return field.default;
+            return Math.min(field.max ?? Infinity, Math.max(field.min ?? -Infinity, value));
+        }
+        case 'text':
+            return typeof value === 'string' ? value.slice(0, Math.min(field.maxLength ?? SETTINGS_LIMITS.text, SETTINGS_LIMITS.text)) : field.default;
+        case 'select':
+            return typeof value === 'string' && field.options.some(option => option.value === value) ? value : field.default;
+        case 'list': {
+            if (!Array.isArray(value))
+                return [...field.default];
+            const max = Math.min(field.maxLength ?? SETTINGS_LIMITS.listItem, SETTINGS_LIMITS.listItem);
+            return value.filter((item) => typeof item === 'string' && item.trim() !== '').map(item => item.slice(0, max)).slice(0, Math.min(field.maxItems ?? SETTINGS_LIMITS.listItems, SETTINGS_LIMITS.listItems));
+        }
+    }
+}
+/** The values for `schema` from whatever was stored: every field present, every value of its type and in range. */
+export function normalizeSettings(schema, stored) {
+    const source = stored && typeof stored === 'object' ? stored : {};
+    const out = {};
+    for (const field of valueFields(schema))
+        out[field.key] = fieldValue(field, source[field.key]);
+    return out;
+}
+/** Problems in a schema (an empty list: valid). */
+export function validateSchema(schema) {
+    const problems = [];
+    const keys = new Set();
+    const fields = valueFields(schema);
+    if (fields.length > SETTINGS_LIMITS.fields)
+        problems.push(`at most ${SETTINGS_LIMITS.fields} fields`);
+    for (const field of fields) {
+        if (!/^[A-Za-z][A-Za-z0-9]{0,39}$/.test(field.key))
+            problems.push(`invalid key ${JSON.stringify(field.key)}`);
+        if (keys.has(field.key))
+            problems.push(`${field.key}: listed twice`);
+        keys.add(field.key);
+        if (!field.label)
+            problems.push(`${field.key}: a label is required`);
+        if (field.type === 'select' && !field.options.some(option => option.value === field.default))
+            problems.push(`${field.key}: the default is not an option`);
+        if (field.type === 'number' && (field.min ?? -Infinity) > (field.max ?? Infinity))
+            problems.push(`${field.key}: min is above max`);
+    }
+    return problems;
+}
+/**
+ * The controls for `schema` showing `values`, built with the kit's element builder and styled by the
+ * kit's form classes. `text(key)` translates a label, hint or option key.
+ */
+export function buildSettingsForm(h, schema, values, text) {
+    const readers = [];
+    const nodes = [];
+    for (const field of schema) {
+        if (field.type === 'divider') {
+            nodes.push(h('div', { class: 'wb-divider' }));
+            continue;
+        }
+        const value = values[field.key];
+        const hint = field.hint ? text(field.hint) : '';
+        if (field.type === 'toggle') {
+            const input = h('input', { type: 'checkbox', checked: value === true });
+            nodes.push(h('label', { class: 'wb-check' }, input, h('span', null, text(field.label), hint ? h('small', null, hint) : null)));
+            readers.push([field, () => input.checked]);
+            continue;
+        }
+        let control;
+        if (field.type === 'number') {
+            const input = h('input', { type: 'number', value: String(value), min: field.min, max: field.max, step: field.step ?? 1 });
+            readers.push([field, () => (input.value.trim() === '' ? NaN : Number(input.value))]);
+            control = input;
+        }
+        else if (field.type === 'select') {
+            const select = h('select', null, field.options.map(option => h('option', { value: option.value, selected: option.value === value }, text(option.label))));
+            readers.push([field, () => select.value]);
+            control = select;
+        }
+        else if (field.type === 'list') {
+            const area = h('textarea', { class: 'wb-mono', rows: 5, spellcheck: false, value: value.join('\n') });
+            readers.push([field, () => area.value.split(/\r?\n/).map(line => line.trim()).filter(Boolean)]);
+            control = area;
+        }
+        else {
+            const input = (field.multiline
+                ? h('textarea', { rows: 4, value: String(value), maxLength: field.maxLength, placeholder: field.placeholder })
+                : h('input', { type: 'text', value: String(value), maxLength: field.maxLength, placeholder: field.placeholder }));
+            readers.push([field, () => input.value]);
+            control = input;
+        }
+        nodes.push(h('label', { class: 'wb-field' }, h('span', { class: 'wb-label' }, text(field.label)), control, hint ? h('p', { class: 'wb-hint' }, hint) : null));
+    }
+    return {
+        nodes,
+        read() {
+            const raw = {};
+            for (const [field, read] of readers)
+                raw[field.key] = read();
+            return normalizeSettings(schema, raw);
+        },
+    };
+}
+//# sourceMappingURL=settingsForm.js.map

package/dist/runtime/settingsForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsForm.js","sourceRoot":"","sources":["../../../runtime/src/settingsForm.ts"],"names":[],"mappings":"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","sourcesContent":["// A settings schema: what a feature (or a plugin) lets its owner adjust, as data. The same schema\n// gives the stored values their shape (`normalizeSettings`: anything missing or of the wrong type\n// takes the field's default, so an old or damaged store never breaks a feature) and draws the\n// controls from the UI kit's form parts (`buildSettingsForm`: check boxes, number, text, select and\n// list fields inside a kit dialog). Labels and hints are catalog keys the caller translates.\n\nimport type { UiKit } from './ui.ts';\n\ntype FieldBase = {\n  /** The key in the stored values. */\n  key: string;\n  /** Catalog key of the label. */\n  label: string;\n  /** Catalog key of a line under the label. */\n  hint?: string;\n};\n\nexport type SettingField =\n  | (FieldBase & { type: 'toggle'; default: boolean })\n  | (FieldBase & { type: 'number'; default: number; min?: number; max?: number; step?: number })\n  | (FieldBase & { type: 'text'; default: string; maxLength?: number; multiline?: boolean; placeholder?: string })\n  | (FieldBase & { type: 'select'; default: string; options: ReadonlyArray<{ value: string; label: string }> })\n  /** Lines of text (patterns, handles): one per line in the form. */\n  | (FieldBase & { type: 'list'; default: readonly string[]; maxItems?: number; maxLength?: number })\n  | { type: 'divider' };\n\nexport type SettingsSchema = readonly SettingField[];\nexport type SettingValue = boolean | number | string | string[];\nexport type SettingValues = Record<string, SettingValue>;\n\nexport const SETTINGS_LIMITS = Object.freeze({ fields: 64, text: 2000, listItems: 500, listItem: 500 });\n\ntype ValueField = Exclude<SettingField, { type: 'divider' }>;\nconst valueFields = (schema: SettingsSchema) => schema.filter((field): field is ValueField => field.type !== 'divider');\n\nfunction fieldValue(field: ValueField, value: unknown): SettingValue {\n  switch (field.type) {\n    case 'toggle':\n      return typeof value === 'boolean' ? value : field.default;\n    case 'number': {\n      if (typeof value !== 'number' || !Number.isFinite(value)) return field.default;\n      return Math.min(field.max ?? Infinity, Math.max(field.min ?? -Infinity, value));\n    }\n    case 'text':\n      return typeof value === 'string' ? value.slice(0, Math.min(field.maxLength ?? SETTINGS_LIMITS.text, SETTINGS_LIMITS.text)) : field.default;\n    case 'select':\n      return typeof value === 'string' && field.options.some(option => option.value === value) ? value : field.default;\n    case 'list': {\n      if (!Array.isArray(value)) return [...field.default];\n      const max = Math.min(field.maxLength ?? SETTINGS_LIMITS.listItem, SETTINGS_LIMITS.listItem);\n      return value.filter((item): item is string => typeof item === 'string' && item.trim() !== '').map(item => item.slice(0, max)).slice(0, Math.min(field.maxItems ?? SETTINGS_LIMITS.listItems, SETTINGS_LIMITS.listItems));\n    }\n  }\n}\n\n/** The values for `schema` from whatever was stored: every field present, every value of its type and in range. */\nexport function normalizeSettings(schema: SettingsSchema, stored: unknown): SettingValues {\n  const source = stored && typeof stored === 'object' ? stored as Record<string, unknown> : {};\n  const out: SettingValues = {};\n  for (const field of valueFields(schema)) out[field.key] = fieldValue(field, source[field.key]);\n  return out;\n}\n\n/** Problems in a schema (an empty list: valid). */\nexport function validateSchema(schema: SettingsSchema): string[] {\n  const problems: string[] = [];\n  const keys = new Set<string>();\n  const fields = valueFields(schema);\n  if (fields.length > SETTINGS_LIMITS.fields) problems.push(`at most ${SETTINGS_LIMITS.fields} fields`);\n  for (const field of fields) {\n    if (!/^[A-Za-z][A-Za-z0-9]{0,39}$/.test(field.key)) problems.push(`invalid key ${JSON.stringify(field.key)}`);\n    if (keys.has(field.key)) problems.push(`${field.key}: listed twice`);\n    keys.add(field.key);\n    if (!field.label) problems.push(`${field.key}: a label is required`);\n    if (field.type === 'select' && !field.options.some(option => option.value === field.default)) problems.push(`${field.key}: the default is not an option`);\n    if (field.type === 'number' && (field.min ?? -Infinity) > (field.max ?? Infinity)) problems.push(`${field.key}: min is above max`);\n  }\n  return problems;\n}\n\nexport type SettingsForm = {\n  /** The controls, in schema order: append them to a dialog's body. */\n  nodes: HTMLElement[];\n  /** The values as the controls show them now (normalized). */\n  read(): SettingValues;\n};\n\n/**\n * The controls for `schema` showing `values`, built with the kit's element builder and styled by the\n * kit's form classes. `text(key)` translates a label, hint or option key.\n */\nexport function buildSettingsForm(h: UiKit['h'], schema: SettingsSchema, values: SettingValues, text: (key: string) => string): SettingsForm {\n  const readers: Array<[ValueField, () => unknown]> = [];\n  const nodes: HTMLElement[] = [];\n  for (const field of schema) {\n    if (field.type === 'divider') { nodes.push(h('div', { class: 'wb-divider' })); continue; }\n    const value = values[field.key];\n    const hint = field.hint ? text(field.hint) : '';\n    if (field.type === 'toggle') {\n      const input = h('input', { type: 'checkbox', checked: value === true }) as HTMLInputElement;\n      nodes.push(h('label', { class: 'wb-check' }, input, h('span', null, text(field.label), hint ? h('small', null, hint) : null)));\n      readers.push([field, () => input.checked]);\n      continue;\n    }\n    let control: HTMLElement;\n    if (field.type === 'number') {\n      const input = h('input', { type: 'number', value: String(value), min: field.min, max: field.max, step: field.step ?? 1 }) as HTMLInputElement;\n      readers.push([field, () => (input.value.trim() === '' ? NaN : Number(input.value))]);\n      control = input;\n    } else if (field.type === 'select') {\n      const select = h('select', null, field.options.map(option => h('option', { value: option.value, selected: option.value === value }, text(option.label)))) as HTMLSelectElement;\n      readers.push([field, () => select.value]);\n      control = select;\n    } else if (field.type === 'list') {\n      const area = h('textarea', { class: 'wb-mono', rows: 5, spellcheck: false, value: (value as string[]).join('\\n') }) as HTMLTextAreaElement;\n      readers.push([field, () => area.value.split(/\\r?\\n/).map(line => line.trim()).filter(Boolean)]);\n      control = area;\n    } else {\n      const input = (field.multiline\n        ? h('textarea', { rows: 4, value: String(value), maxLength: field.maxLength, placeholder: field.placeholder })\n        : h('input', { type: 'text', value: String(value), maxLength: field.maxLength, placeholder: field.placeholder })) as HTMLInputElement | HTMLTextAreaElement;\n      readers.push([field, () => input.value]);\n      control = input;\n    }\n    nodes.push(h('label', { class: 'wb-field' }, h('span', { class: 'wb-label' }, text(field.label)), control, hint ? h('p', { class: 'wb-hint' }, hint) : null));\n  }\n  return {\n    nodes,\n    read() {\n      const raw: Record<string, unknown> = {};\n      for (const [field, read] of readers) raw[field.key] = read();\n      return normalizeSettings(schema, raw);\n    },\n  };\n}\n"]}

package/dist/runtime/site.d.ts

@@ -1,4 +1,5 @@
 import type { AccountSite } from './accountReport.ts';
+import type { ColumnSite } from './column.ts';
 import type { LinkSite } from './linkRouting.ts';
 import type { RailSite } from './paneNav.ts';
 import type { PluginApiSite } from './pluginApi.ts';
@@ -12,6 +13,8 @@ export type SiteAdapter = {
     runtimeGlobal: string;
     /** Pages where heavy-page-sensitive DOM features pause (e.g. a WASM chat); null = none. */
     heavyPath: RegExp | null;
+    /** Hosts whose open shadow roots are part of the page (the DOM hub observes and searches them; `domRoots`). */
+    shadowHosts?: readonly string[];
     /** Request URL substrings that are the site's API calls; only these reach the net hub stages. */
     apiMarks: string[];
     /** Extra URL substrings that reach XHR gates only. */
@@ -19,6 +22,8 @@ export type SiteAdapter = {
     plugins: PluginApiSite;
     /** Split-view rail hiding; omit when the site has no navigation rail. */
     rail?: RailSite;
+    /** Power User Mode: how a site tab becomes a narrow deck column (runtime/column.ts); omit = no decks. */
+    column?: ColumnSite;
     /** Signed-in account reader for the account switcher. */
     account?: AccountSite;
     /** Which in-page clicks the "links to site pages" setting may divert. */

package/dist/runtime/site.js

@@ -4,7 +4,7 @@ import { configureDomHub } from "./domHub.js";
 import { configureNetHub } from "./netHub.js";
 /** Applies the adapter's global knobs (DOM hub, net hub). Call once, before features start. */
 export function configureRuntime(site) {
-    configureDomHub({ label: site.product, heavyPath: site.heavyPath });
+    configureDomHub({ label: site.product, heavyPath: site.heavyPath, shadowHosts: site.shadowHosts ?? [] });
     configureNetHub({ apiMarks: site.apiMarks, xhrMarks: site.xhrMarks });
 }
 /** Whether `href` is on the site's origin (https, one of `hosts`). */

package/dist/runtime/site.js.map

@@ -1 +1 @@
-{"version":3,"file":"site.js","sourceRoot":"","sources":["../../../runtime/src/site.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,mGAAmG;AAEnG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA+B9C,+FAA+F;AAC/F,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACpE,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,IAAgC,EAAE,IAAY;IACtE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC1G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["// The page side of a site adapter. A wayBetter app for one site is mostly this object (plus the\n// native `SiteSpec` in Rust and its Tauri capability files); every runtime module takes its piece.\n\nimport { configureDomHub } from './domHub.ts';\nimport { configureNetHub } from './netHub.ts';\nimport type { AccountSite } from './accountReport.ts';\nimport type { LinkSite } from './linkRouting.ts';\nimport type { RailSite } from './paneNav.ts';\nimport type { PluginApiSite } from './pluginApi.ts';\nimport type { SourceAxis } from './themeTokens.ts';\n\nexport type SiteAdapter = {\n  /** e.g. \"wayBetter for X\"; console prefixes and toasts. */\n  product: string;\n  /** Exact hosts of the site's origin (must match the native `SiteSpec.hosts`). */\n  hosts: readonly string[];\n  /** The runtime's window global (`window.<runtimeGlobal>`), plugins included. */\n  runtimeGlobal: string;\n  /** Pages where heavy-page-sensitive DOM features pause (e.g. a WASM chat); null = none. */\n  heavyPath: RegExp | null;\n  /** Request URL substrings that are the site's API calls; only these reach the net hub stages. */\n  apiMarks: string[];\n  /** Extra URL substrings that reach XHR gates only. */\n  xhrMarks: string[];\n  plugins: PluginApiSite;\n  /** Split-view rail hiding; omit when the site has no navigation rail. */\n  rail?: RailSite;\n  /** Signed-in account reader for the account switcher. */\n  account?: AccountSite;\n  /** Which in-page clicks the \"links to site pages\" setting may divert. */\n  links?: LinkSite;\n  /** The site's own palette per color mode, the source the theme engine maps from. */\n  themeSources?: Record<string, SourceAxis>;\n};\n\n/** Applies the adapter's global knobs (DOM hub, net hub). Call once, before features start. */\nexport function configureRuntime(site: SiteAdapter): void {\n  configureDomHub({ label: site.product, heavyPath: site.heavyPath });\n  configureNetHub({ apiMarks: site.apiMarks, xhrMarks: site.xhrMarks });\n}\n\n/** Whether `href` is on the site's origin (https, one of `hosts`). */\nexport function isSiteUrl(site: Pick<SiteAdapter, 'hosts'>, href: string): boolean {\n  try {\n    const url = new URL(href);\n    return url.protocol === 'https:' && site.hosts.includes(url.hostname) && !url.username && !url.password;\n  } catch {\n    return false;\n  }\n}\n"]}
+{"version":3,"file":"site.js","sourceRoot":"","sources":["../../../runtime/src/site.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,mGAAmG;AAEnG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAoC9C,+FAA+F;AAC/F,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC,CAAC;IACzG,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,IAAgC,EAAE,IAAY;IACtE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC1G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["// The page side of a site adapter. A wayBetter app for one site is mostly this object (plus the\n// native `SiteSpec` in Rust and its Tauri capability files); every runtime module takes its piece.\n\nimport { configureDomHub } from './domHub.ts';\nimport { configureNetHub } from './netHub.ts';\nimport type { AccountSite } from './accountReport.ts';\nimport type { ColumnSite } from './column.ts';\nimport type { LinkSite } from './linkRouting.ts';\nimport type { RailSite } from './paneNav.ts';\nimport type { PluginApiSite } from './pluginApi.ts';\nimport type { SourceAxis } from './themeTokens.ts';\n\nexport type SiteAdapter = {\n  /** e.g. \"wayBetter for X\"; console prefixes and toasts. */\n  product: string;\n  /** Exact hosts of the site's origin (must match the native `SiteSpec.hosts`). */\n  hosts: readonly string[];\n  /** The runtime's window global (`window.<runtimeGlobal>`), plugins included. */\n  runtimeGlobal: string;\n  /** Pages where heavy-page-sensitive DOM features pause (e.g. a WASM chat); null = none. */\n  heavyPath: RegExp | null;\n  /** Hosts whose open shadow roots are part of the page (the DOM hub observes and searches them; `domRoots`). */\n  shadowHosts?: readonly string[];\n  /** Request URL substrings that are the site's API calls; only these reach the net hub stages. */\n  apiMarks: string[];\n  /** Extra URL substrings that reach XHR gates only. */\n  xhrMarks: string[];\n  plugins: PluginApiSite;\n  /** Split-view rail hiding; omit when the site has no navigation rail. */\n  rail?: RailSite;\n  /** Power User Mode: how a site tab becomes a narrow deck column (runtime/column.ts); omit = no decks. */\n  column?: ColumnSite;\n  /** Signed-in account reader for the account switcher. */\n  account?: AccountSite;\n  /** Which in-page clicks the \"links to site pages\" setting may divert. */\n  links?: LinkSite;\n  /** The site's own palette per color mode, the source the theme engine maps from. */\n  themeSources?: Record<string, SourceAxis>;\n};\n\n/** Applies the adapter's global knobs (DOM hub, net hub). Call once, before features start. */\nexport function configureRuntime(site: SiteAdapter): void {\n  configureDomHub({ label: site.product, heavyPath: site.heavyPath, shadowHosts: site.shadowHosts ?? [] });\n  configureNetHub({ apiMarks: site.apiMarks, xhrMarks: site.xhrMarks });\n}\n\n/** Whether `href` is on the site's origin (https, one of `hosts`). */\nexport function isSiteUrl(site: Pick<SiteAdapter, 'hosts'>, href: string): boolean {\n  try {\n    const url = new URL(href);\n    return url.protocol === 'https:' && site.hosts.includes(url.hostname) && !url.username && !url.password;\n  } catch {\n    return false;\n  }\n}\n"]}

package/dist/runtime/siteRuntime.d.ts

@@ -0,0 +1,144 @@
+import type { PageStrings } from './pageStrings.ts';
+import type { PluginContext } from './permissions.ts';
+import type { Params } from './i18n.ts';
+import type { SiteAdapter } from './site.ts';
+export type PageInvoke = (command: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Native commands from the page. The IPC bridge is read at call time: a runtime installed at
+ * document start can run before Tauri has put `__TAURI_INTERNALS__` on the page. A runtime only
+ * ships inside the app's site tabs; automated test browsers (`navigator.webdriver`) have no
+ * bridge, and the features that need it stay off there (undefined).
+ */
+export declare function pageInvoke(win: Window, product: string): PageInvoke | undefined;
+/** A flag-controlled part of the runtime, while it is installed. */
+export type Installed = {
+    dispose(): void;
+};
+export type FlagInstaller<Flags> = readonly [flag: keyof Flags & string, install: () => Installed];
+export type FeatureFlagsOptions<Flags extends Record<string, boolean>> = {
+    /** Every flag with its default; a flag not in here is ignored. */
+    defaults: Flags;
+    /** Console label (the app's name). */
+    label: string;
+    /** Parts that install when their flag turns on and dispose when it turns off, in install order. */
+    installers: ReadonlyArray<FlagInstaller<Flags>>;
+    /** Every applied config (the full map), before the installers (flags that are CSS, or that another part reads). */
+    apply?(config: Flags): void;
+    /**
+     * What owns what: given the delivered flags over the defaults, the flags that really run (an
+     * area whose switch is off turns its features off; featureTable `effectiveFlags`).
+     */
+    resolve?(flags: Flags): Flags;
+    /** The page's document: a column's flags delivered at document start wait for `<html>` to exist. */
+    document?: Document;
+};
+export type FeatureFlags<Flags extends Record<string, boolean>> = {
+    /**
+     * The flags native code delivers (the owner's choices); a deck column's overrides stay on top.
+     * A delivery is the whole state, stored sparsely: a flag it does not name is at its default.
+     */
+    apply(config: Partial<Flags>): void;
+    /**
+     * A deck column's flag overrides (allow-listed natively; unknown keys and non-booleans are
+     * dropped here too). Flags a column stops overriding go back to the global value, or the default
+     * when the global config never named them. Recorded at once; applied now, or once the document
+     * has its `<html>` (a new column webview gets its config at document start).
+     */
+    setColumnFlags(flags: unknown): void;
+    /** Turns one installer on or off directly (a kill switch). */
+    set(flag: keyof Flags & string, enabled: boolean): void;
+    /** Whether a flag's installer is installed right now. */
+    installed(flag: keyof Flags & string): boolean;
+    /** Every flag as it runs right now (defaults, the delivery, ownership, the column). */
+    current(): Flags;
+};
+export declare function createFeatureFlags<Flags extends Record<string, boolean>>(options: FeatureFlagsOptions<Flags>): FeatureFlags<Flags>;
+/** What native code and plugins reach through `window.<runtimeGlobal>`. */
+export type SiteRuntime<Api extends object> = {
+    version: string;
+    /** Running plugins by file (native start/stop scripts manage this). */
+    plugins: Record<string, {
+        start?: () => void;
+        stop?: () => void;
+    }>;
+    /** Load errors by plugin file. */
+    errors: Record<string, string>;
+    /** Native code hands over the feature flags (`features_set`). */
+    features: {
+        apply(config: unknown): void;
+    };
+    /** Native code hands over the owner's language: `{ locale, dir, messages }` (pageStrings.ts). */
+    i18n: {
+        set(strings: unknown): void;
+        locale(): string;
+        t(key: string, params?: Params): string;
+    };
+    /** Native code hands over where clicked site pages open (`{ site: 'same' | 'pane' | 'tab' | 'browser' }`). */
+    links: {
+        configure(value: unknown): void;
+    };
+    /** Native code says whether this pane's navigation repeats another pane's (`{ redundantNav }`). */
+    pane: {
+        set(state: unknown): void;
+    };
+    /** Native code hands over downloaded Google Fonts (validated woff2 bytes) that this tab's theme uses. */
+    fonts: {
+        provide(fonts: unknown): void;
+    };
+    /** Power User Mode: native code hands a deck column its config (null = an ordinary tab again). */
+    column: {
+        set(config: unknown): void;
+        markRead(): void;
+        jumpToUnread(): void;
+        unread(): number;
+    };
+    /** Opens the app's panel in the shell (at a section). */
+    open(section?: string): void;
+    /**
+     * Helpers for `*.plugin.js` files. Read while a plugin's code runs (its module body, constructor,
+     * start() and stop()), this is that plugin's view for its declared `@permissions`; elsewhere it
+     * is the full API.
+     */
+    readonly api: Api;
+    /** Runs `fn` as plugin `id` with `grants` (null = legacy, full API; undefined = as registered). Native start/stop scripts call it. */
+    withPlugin<R>(id: string, grants: readonly string[] | null | undefined, fn: () => R): R;
+    /** Developer mode: a reloaded plugin failed to start (native `dev_start_script`); shown as a toast. */
+    devError(file: unknown, error: unknown): void;
+};
+export type SiteRuntimeOptions<Api extends object, Extra extends object> = {
+    win: Window & typeof globalThis;
+    site: Pick<SiteAdapter, 'product' | 'runtimeGlobal'>;
+    version: string;
+    /** Other window names for the runtime, besides `wayBetter` and `site.runtimeGlobal` (names older plugins use). */
+    aliases?: readonly string[];
+    invoke?: PageInvoke;
+    /** Per-plugin API views (permissions.ts `createPluginContext`). */
+    plugins: PluginContext<Api>;
+    strings: PageStrings;
+    /** The toast for a plugin that failed to start in developer mode ("Plugin failed: {error}"). */
+    pluginFailed(error: string): string;
+    features?: {
+        apply(config: never): void;
+    };
+    /** The theme handle (themeRuntime.ts), exposed as `theme`. */
+    theme?: {
+        apply(choice: unknown): void;
+    };
+    fonts?(fonts: unknown): void;
+    pane?: {
+        set(state: unknown): void;
+    };
+    links?: {
+        configure(value: unknown): void;
+    };
+    column?: SiteRuntime<Api>['column'];
+    /** The app's own members (X: alerts, fixes). */
+    extra?: Extra;
+    /** Values native code may have delivered for the app's own members before the runtime existed: queue global and receiver. */
+    queues?: ReadonlyArray<readonly [queue: string, deliver: (value: unknown) => void]>;
+};
+/**
+ * Builds the runtime object, publishes it under its window names (not writable, not configurable),
+ * takes over what native code queued before it existed, and starts the palette command report.
+ */
+export declare function installSiteRuntime<Api extends object, Extra extends object = Record<never, never>>(options: SiteRuntimeOptions<Api, Extra>): SiteRuntime<Api> & Extra;

package/dist/runtime/siteRuntime.js

@@ -0,0 +1,175 @@
+// The page runtime's composition helpers: what every app's runtime entry does the same way. An
+// app's entry (injected at document start into its site's tabs) installs its features and then:
+//
+//   const invoke = pageInvoke(window, SITE.product);
+//   const flags = createFeatureFlags({ defaults, label: SITE.product, installers, apply });
+//   const runtime = installSiteRuntime({ win: window, site: SITE, version, invoke, plugins, strings, features: flags, ... });
+//   installPanelButton(window, button, () => runtime.open());          // panelButton.ts
+//
+// - `pageInvoke`: the IPC bridge, read at call time.
+// - `createFeatureFlags`: flag-controlled parts that install on enable and dispose on disable, the
+//   flags native code delivers (`features_set`) and a deck column's overrides on top of them.
+// - `installSiteRuntime`: the runtime object under its window names (`window.wayBetter` and the
+//   app's own), the members native code calls (features, theme, fonts, pane, links, i18n, column),
+//   the plugin API views, developer-mode errors, the palette command report, and whatever native
+//   code delivered before the runtime existed (the `__bt*` / `__wb*` queues).
+import { installCommandReport, devErrorReporter } from "./commandReport.js";
+/**
+ * Native commands from the page. The IPC bridge is read at call time: a runtime installed at
+ * document start can run before Tauri has put `__TAURI_INTERNALS__` on the page. A runtime only
+ * ships inside the app's site tabs; automated test browsers (`navigator.webdriver`) have no
+ * bridge, and the features that need it stay off there (undefined).
+ */
+export function pageInvoke(win, product) {
+    const target = win;
+    const inApp = !!target.__TAURI_INTERNALS__ || !target.navigator.webdriver;
+    if (!inApp)
+        return undefined;
+    return (command, args) => {
+        const ipc = target.__TAURI_INTERNALS__;
+        return ipc ? ipc.invoke(command, args) : Promise.reject(new Error(`${product}: IPC bridge not ready`));
+    };
+}
+export function createFeatureFlags(options) {
+    const { defaults, label, installers } = options;
+    const active = new Map();
+    const installerOf = new Map(installers.map(([flag, install]) => [flag, install]));
+    const set = (flag, enabled) => {
+        const install = installerOf.get(flag);
+        if (!install)
+            return;
+        const current = active.get(flag);
+        if (enabled && !current) {
+            try {
+                active.set(flag, install());
+            }
+            catch (error) {
+                console.error(`[${label}] ${flag} failed`, error);
+            }
+        }
+        else if (!enabled && current) {
+            current.dispose();
+            active.delete(flag);
+        }
+    };
+    // Installed at document start, before the site's bundle runs (request gates wrap its fetch).
+    for (const [flag] of installers)
+        set(flag, defaults[flag]);
+    let globalFlags = {};
+    let columnFlags = {};
+    const known = (input) => {
+        const out = {};
+        if (input && typeof input === 'object') {
+            for (const [key, value] of Object.entries(input))
+                if (key in defaults && typeof value === 'boolean')
+                    out[key] = value;
+        }
+        return out;
+    };
+    // What runs: the defaults, the delivered flags over them, what owns what (`resolve`), and a
+    // column's own choices on top.
+    const current = () => {
+        const base = { ...defaults, ...globalFlags };
+        return { ...(options.resolve ? options.resolve(base) : base), ...columnFlags };
+    };
+    const applyAll = () => {
+        const config = current();
+        options.apply?.(config);
+        for (const [flag] of installers)
+            set(flag, config[flag]);
+    };
+    return {
+        apply(config) {
+            globalFlags = known(config);
+            applyAll();
+        },
+        setColumnFlags(flags) {
+            const next = known(flags);
+            const previous = columnFlags;
+            columnFlags = next;
+            if (!Object.keys(previous).length && !Object.keys(next).length)
+                return;
+            const apply = () => { try {
+                applyAll();
+            }
+            catch (error) {
+                console.error(`[${label}] column flags failed`, error);
+            } };
+            const doc = options.document;
+            if (!doc || doc.documentElement)
+                apply();
+            else
+                doc.addEventListener('DOMContentLoaded', apply, { once: true });
+        },
+        set,
+        installed: flag => active.has(flag),
+        current,
+    };
+}
+/**
+ * Builds the runtime object, publishes it under its window names (not writable, not configurable),
+ * takes over what native code queued before it existed, and starts the palette command report.
+ */
+export function installSiteRuntime(options) {
+    const { win, site, plugins, strings } = options;
+    const label = site.product;
+    // A failure in one member never breaks native code's other deliveries (or the page).
+    const guarded = (what, fn) => (value) => {
+        try {
+            fn(value);
+        }
+        catch (error) {
+            console.error(`[${label}] ${what} failed`, error);
+        }
+    };
+    const runtime = {
+        ...(options.extra ?? {}),
+        version: options.version,
+        plugins: {},
+        errors: {},
+        features: { apply: (config) => options.features?.apply(config) },
+        ...(options.theme ? { theme: options.theme } : {}),
+        fonts: { provide: guarded('fonts', (list) => options.fonts?.(list)) },
+        pane: { set: guarded('split navigation', (state) => options.pane?.set(state)) },
+        links: { configure: (value) => options.links?.configure(value) },
+        i18n: { set: guarded('language', (value) => strings.set(value)), locale: strings.locale, t: strings.t },
+        column: {
+            set: guarded('deck column', (config) => options.column?.set(config)),
+            markRead: () => options.column?.markRead(),
+            jumpToUnread: () => options.column?.jumpToUnread(),
+            unread: () => options.column?.unread() ?? 0,
+        },
+        open(section) {
+            win.__TAURI_INTERNALS__?.invoke('open_panel', { section: section ?? null }).catch(() => { });
+        },
+        withPlugin: (id, grants, fn) => plugins.run(id, grants, fn),
+        get api() { return plugins.current(); },
+        devError: devErrorReporter(() => {
+            const ui = plugins.current().ui;
+            return ui ? (message, toastOptions) => { ui.toast(message, toastOptions); } : undefined;
+        }, options.pluginFailed),
+    };
+    // `wayBetter` is the documented name; the app's own names stay for existing plugins.
+    const names = [...new Set(['wayBetter', site.runtimeGlobal, ...(options.aliases ?? [])])];
+    for (const name of names)
+        Object.defineProperty(win, name, { value: runtime, configurable: false, writable: false });
+    // Native code may deliver before this runtime exists.
+    const queued = win;
+    const take = (queue, deliver) => { if (queued[queue])
+        deliver(queued[queue]); };
+    take('__wbI18n', runtime.i18n.set);
+    take('__btFeatures', runtime.features.apply);
+    take('__wbFonts', runtime.fonts.provide);
+    take('__btTheme', value => runtime.theme?.apply(value));
+    take('__btPane', runtime.pane.set);
+    take('__btLinks', runtime.links.configure);
+    take('__btColumn', runtime.column.set);
+    for (const [queue, deliver] of options.queues ?? [])
+        take(queue, deliver);
+    // Plugin commands for the shell's command palette: ids, titles and keywords about this tab only.
+    const commands = plugins.current().commands;
+    if (commands)
+        installCommandReport(commands, options.invoke);
+    return runtime;
+}
+//# sourceMappingURL=siteRuntime.js.map

package/dist/runtime/siteRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteRuntime.js","sourceRoot":"","sources":["../../../runtime/src/siteRuntime.ts"],"names":[],"mappings":"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","sourcesContent":["// The page runtime's composition helpers: what every app's runtime entry does the same way. An\n// app's entry (injected at document start into its site's tabs) installs its features and then:\n//\n//   const invoke = pageInvoke(window, SITE.product);\n//   const flags = createFeatureFlags({ defaults, label: SITE.product, installers, apply });\n//   const runtime = installSiteRuntime({ win: window, site: SITE, version, invoke, plugins, strings, features: flags, ... });\n//   installPanelButton(window, button, () => runtime.open());          // panelButton.ts\n//\n// - `pageInvoke`: the IPC bridge, read at call time.\n// - `createFeatureFlags`: flag-controlled parts that install on enable and dispose on disable, the\n//   flags native code delivers (`features_set`) and a deck column's overrides on top of them.\n// - `installSiteRuntime`: the runtime object under its window names (`window.wayBetter` and the\n//   app's own), the members native code calls (features, theme, fonts, pane, links, i18n, column),\n//   the plugin API views, developer-mode errors, the palette command report, and whatever native\n//   code delivered before the runtime existed (the `__bt*` / `__wb*` queues).\n\nimport { installCommandReport, devErrorReporter } from './commandReport.ts';\nimport type { CommandInfo } from './commands.ts';\nimport type { PageStrings } from './pageStrings.ts';\nimport type { PluginContext } from './permissions.ts';\nimport type { Params } from './i18n.ts';\nimport type { SiteAdapter } from './site.ts';\n\nexport type PageInvoke = (command: string, args: Record<string, unknown>) => Promise<unknown>;\n\ntype BridgeWindow = { __TAURI_INTERNALS__?: { invoke(cmd: string, args?: Record<string, unknown>): Promise<unknown> }; navigator: { webdriver?: boolean } };\n\n/**\n * Native commands from the page. The IPC bridge is read at call time: a runtime installed at\n * document start can run before Tauri has put `__TAURI_INTERNALS__` on the page. A runtime only\n * ships inside the app's site tabs; automated test browsers (`navigator.webdriver`) have no\n * bridge, and the features that need it stay off there (undefined).\n */\nexport function pageInvoke(win: Window, product: string): PageInvoke | undefined {\n  const target = win as unknown as BridgeWindow;\n  const inApp = !!target.__TAURI_INTERNALS__ || !target.navigator.webdriver;\n  if (!inApp) return undefined;\n  return (command, args) => {\n    const ipc = target.__TAURI_INTERNALS__;\n    return ipc ? ipc.invoke(command, args) : Promise.reject(new Error(`${product}: IPC bridge not ready`));\n  };\n}\n\n// ---------------------------------------------------------------------------------------------\n// Feature flags\n\n/** A flag-controlled part of the runtime, while it is installed. */\nexport type Installed = { dispose(): void };\nexport type FlagInstaller<Flags> = readonly [flag: keyof Flags & string, install: () => Installed];\n\nexport type FeatureFlagsOptions<Flags extends Record<string, boolean>> = {\n  /** Every flag with its default; a flag not in here is ignored. */\n  defaults: Flags;\n  /** Console label (the app's name). */\n  label: string;\n  /** Parts that install when their flag turns on and dispose when it turns off, in install order. */\n  installers: ReadonlyArray<FlagInstaller<Flags>>;\n  /** Every applied config (the full map), before the installers (flags that are CSS, or that another part reads). */\n  apply?(config: Flags): void;\n  /**\n   * What owns what: given the delivered flags over the defaults, the flags that really run (an\n   * area whose switch is off turns its features off; featureTable `effectiveFlags`).\n   */\n  resolve?(flags: Flags): Flags;\n  /** The page's document: a column's flags delivered at document start wait for `<html>` to exist. */\n  document?: Document;\n};\n\nexport type FeatureFlags<Flags extends Record<string, boolean>> = {\n  /**\n   * The flags native code delivers (the owner's choices); a deck column's overrides stay on top.\n   * A delivery is the whole state, stored sparsely: a flag it does not name is at its default.\n   */\n  apply(config: Partial<Flags>): void;\n  /**\n   * A deck column's flag overrides (allow-listed natively; unknown keys and non-booleans are\n   * dropped here too). Flags a column stops overriding go back to the global value, or the default\n   * when the global config never named them. Recorded at once; applied now, or once the document\n   * has its `<html>` (a new column webview gets its config at document start).\n   */\n  setColumnFlags(flags: unknown): void;\n  /** Turns one installer on or off directly (a kill switch). */\n  set(flag: keyof Flags & string, enabled: boolean): void;\n  /** Whether a flag's installer is installed right now. */\n  installed(flag: keyof Flags & string): boolean;\n  /** Every flag as it runs right now (defaults, the delivery, ownership, the column). */\n  current(): Flags;\n};\n\nexport function createFeatureFlags<Flags extends Record<string, boolean>>(options: FeatureFlagsOptions<Flags>): FeatureFlags<Flags> {\n  const { defaults, label, installers } = options;\n  const active = new Map<string, Installed>();\n  const installerOf = new Map(installers.map(([flag, install]) => [flag as string, install]));\n\n  const set = (flag: string, enabled: boolean) => {\n    const install = installerOf.get(flag);\n    if (!install) return;\n    const current = active.get(flag);\n    if (enabled && !current) {\n      try { active.set(flag, install()); }\n      catch (error) { console.error(`[${label}] ${flag} failed`, error); }\n    } else if (!enabled && current) {\n      current.dispose();\n      active.delete(flag);\n    }\n  };\n  // Installed at document start, before the site's bundle runs (request gates wrap its fetch).\n  for (const [flag] of installers) set(flag, defaults[flag]);\n\n  let globalFlags: Partial<Flags> = {};\n  let columnFlags: Partial<Flags> = {};\n  const known = (input: unknown): Partial<Flags> => {\n    const out: Record<string, boolean> = {};\n    if (input && typeof input === 'object') {\n      for (const [key, value] of Object.entries(input)) if (key in defaults && typeof value === 'boolean') out[key] = value;\n    }\n    return out as Partial<Flags>;\n  };\n  // What runs: the defaults, the delivered flags over them, what owns what (`resolve`), and a\n  // column's own choices on top.\n  const current = (): Flags => {\n    const base = { ...defaults, ...globalFlags } as Flags;\n    return { ...(options.resolve ? options.resolve(base) : base), ...columnFlags };\n  };\n  const applyAll = () => {\n    const config = current();\n    options.apply?.(config);\n    for (const [flag] of installers) set(flag, config[flag]);\n  };\n\n  return {\n    apply(config) {\n      globalFlags = known(config);\n      applyAll();\n    },\n    setColumnFlags(flags) {\n      const next = known(flags);\n      const previous = columnFlags;\n      columnFlags = next;\n      if (!Object.keys(previous).length && !Object.keys(next).length) return;\n      const apply = () => { try { applyAll(); } catch (error) { console.error(`[${label}] column flags failed`, error); } };\n      const doc = options.document;\n      if (!doc || doc.documentElement) apply();\n      else doc.addEventListener('DOMContentLoaded', apply, { once: true });\n    },\n    set,\n    installed: flag => active.has(flag),\n    current,\n  };\n}\n\n// ---------------------------------------------------------------------------------------------\n// The runtime object\n\n/** What native code and plugins reach through `window.<runtimeGlobal>`. */\nexport type SiteRuntime<Api extends object> = {\n  version: string;\n  /** Running plugins by file (native start/stop scripts manage this). */\n  plugins: Record<string, { start?: () => void; stop?: () => void }>;\n  /** Load errors by plugin file. */\n  errors: Record<string, string>;\n  /** Native code hands over the feature flags (`features_set`). */\n  features: { apply(config: unknown): void };\n  /** Native code hands over the owner's language: `{ locale, dir, messages }` (pageStrings.ts). */\n  i18n: { set(strings: unknown): void; locale(): string; t(key: string, params?: Params): string };\n  /** Native code hands over where clicked site pages open (`{ site: 'same' | 'pane' | 'tab' | 'browser' }`). */\n  links: { configure(value: unknown): void };\n  /** Native code says whether this pane's navigation repeats another pane's (`{ redundantNav }`). */\n  pane: { set(state: unknown): void };\n  /** Native code hands over downloaded Google Fonts (validated woff2 bytes) that this tab's theme uses. */\n  fonts: { provide(fonts: unknown): void };\n  /** Power User Mode: native code hands a deck column its config (null = an ordinary tab again). */\n  column: { set(config: unknown): void; markRead(): void; jumpToUnread(): void; unread(): number };\n  /** Opens the app's panel in the shell (at a section). */\n  open(section?: string): void;\n  /**\n   * Helpers for `*.plugin.js` files. Read while a plugin's code runs (its module body, constructor,\n   * start() and stop()), this is that plugin's view for its declared `@permissions`; elsewhere it\n   * is the full API.\n   */\n  readonly api: Api;\n  /** Runs `fn` as plugin `id` with `grants` (null = legacy, full API; undefined = as registered). Native start/stop scripts call it. */\n  withPlugin<R>(id: string, grants: readonly string[] | null | undefined, fn: () => R): R;\n  /** Developer mode: a reloaded plugin failed to start (native `dev_start_script`); shown as a toast. */\n  devError(file: unknown, error: unknown): void;\n};\n\ntype ApiWithUi = { ui?: { toast(message: string, options: { tone: 'danger'; duration: number }): unknown }; commands?: { list(): CommandInfo[]; onChange(callback: (list: CommandInfo[]) => void): () => void } };\n\nexport type SiteRuntimeOptions<Api extends object, Extra extends object> = {\n  win: Window & typeof globalThis;\n  site: Pick<SiteAdapter, 'product' | 'runtimeGlobal'>;\n  version: string;\n  /** Other window names for the runtime, besides `wayBetter` and `site.runtimeGlobal` (names older plugins use). */\n  aliases?: readonly string[];\n  invoke?: PageInvoke;\n  /** Per-plugin API views (permissions.ts `createPluginContext`). */\n  plugins: PluginContext<Api>;\n  strings: PageStrings;\n  /** The toast for a plugin that failed to start in developer mode (\"Plugin failed: {error}\"). */\n  pluginFailed(error: string): string;\n  features?: { apply(config: never): void };\n  /** The theme handle (themeRuntime.ts), exposed as `theme`. */\n  theme?: { apply(choice: unknown): void };\n  fonts?(fonts: unknown): void;\n  pane?: { set(state: unknown): void };\n  links?: { configure(value: unknown): void };\n  column?: SiteRuntime<Api>['column'];\n  /** The app's own members (X: alerts, fixes). */\n  extra?: Extra;\n  /** Values native code may have delivered for the app's own members before the runtime existed: queue global and receiver. */\n  queues?: ReadonlyArray<readonly [queue: string, deliver: (value: unknown) => void]>;\n};\n\n/**\n * Builds the runtime object, publishes it under its window names (not writable, not configurable),\n * takes over what native code queued before it existed, and starts the palette command report.\n */\nexport function installSiteRuntime<Api extends object, Extra extends object = Record<never, never>>(options: SiteRuntimeOptions<Api, Extra>): SiteRuntime<Api> & Extra {\n  const { win, site, plugins, strings } = options;\n  const label = site.product;\n  // A failure in one member never breaks native code's other deliveries (or the page).\n  const guarded = <T>(what: string, fn: (value: T) => void) => (value: T) => {\n    try { fn(value); } catch (error) { console.error(`[${label}] ${what} failed`, error); }\n  };\n  const runtime = {\n    ...(options.extra ?? {}),\n    version: options.version,\n    plugins: {},\n    errors: {},\n    features: { apply: (config: unknown) => (options.features as { apply(config: unknown): void } | undefined)?.apply(config) },\n    ...(options.theme ? { theme: options.theme } : {}),\n    fonts: { provide: guarded('fonts', (list: unknown) => options.fonts?.(list)) },\n    pane: { set: guarded('split navigation', (state: unknown) => options.pane?.set(state)) },\n    links: { configure: (value: unknown) => options.links?.configure(value) },\n    i18n: { set: guarded('language', (value: unknown) => strings.set(value)), locale: strings.locale, t: strings.t },\n    column: {\n      set: guarded('deck column', (config: unknown) => options.column?.set(config)),\n      markRead: () => options.column?.markRead(),\n      jumpToUnread: () => options.column?.jumpToUnread(),\n      unread: () => options.column?.unread() ?? 0,\n    },\n    open(section?: string) {\n      (win as unknown as BridgeWindow).__TAURI_INTERNALS__?.invoke('open_panel', { section: section ?? null }).catch(() => {});\n    },\n    withPlugin: <R>(id: string, grants: readonly string[] | null | undefined, fn: () => R) => plugins.run(id, grants, fn),\n    get api() { return plugins.current(); },\n    devError: devErrorReporter(() => {\n      const ui = (plugins.current() as ApiWithUi).ui;\n      return ui ? (message, toastOptions) => { ui.toast(message, toastOptions); } : undefined;\n    }, options.pluginFailed),\n  } as unknown as SiteRuntime<Api> & Extra & { theme?: { apply(choice: unknown): void } };\n\n  // `wayBetter` is the documented name; the app's own names stay for existing plugins.\n  const names = [...new Set(['wayBetter', site.runtimeGlobal, ...(options.aliases ?? [])])];\n  for (const name of names) Object.defineProperty(win, name, { value: runtime, configurable: false, writable: false });\n\n  // Native code may deliver before this runtime exists.\n  const queued = win as unknown as Record<string, unknown>;\n  const take = (queue: string, deliver: (value: unknown) => void) => { if (queued[queue]) deliver(queued[queue]); };\n  take('__wbI18n', runtime.i18n.set);\n  take('__btFeatures', runtime.features.apply);\n  take('__wbFonts', runtime.fonts.provide);\n  take('__btTheme', value => runtime.theme?.apply(value));\n  take('__btPane', runtime.pane.set);\n  take('__btLinks', runtime.links.configure);\n  take('__btColumn', runtime.column.set);\n  for (const [queue, deliver] of options.queues ?? []) take(queue, deliver);\n\n  // Plugin commands for the shell's command palette: ids, titles and keywords about this tab only.\n  const commands = (plugins.current() as ApiWithUi).commands;\n  if (commands) installCommandReport(commands, options.invoke);\n  return runtime;\n}\n"]}