@volter/world-core 3.0.30 → 3.0.32

package/src/runtime.ts

@@ -344,4 +344,5 @@ export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from
 export { foldHistory } from './log.ts';
 export { volterHome } from './volter-home.ts';
 
-export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from './browser-session-permit.ts';
+
+export { boardFrameKey } from './board-keys.ts';

package/src/twin-fetch.ts

@@ -1,3 +1,4 @@
+import { assertBrowserName } from './browser-state.ts';
 // THE ONE HTTP ADAPTATION (runtime contract R12b): most packs' serve path is the same
 // ~20 lines of glue — the keyless GET /twin manifest door, the body read, a header map,
 // the dispatch into `handle<Vendor>TwinRequest` with the WORLD instant, and a JSON
@@ -55,12 +56,14 @@ export const siteLabel = (hostname: string): string => hostname.toLowerCase().re
 
 /** The address a sites template gives `hostname`, or null where the template is not one or the name makes no address
  *  (a label over 63 characters). */
-export function siteUrlOf(template: string, hostname: string): string | null {
+export function siteUrlOf(template: string, hostname: string, browser?: string): string | null {
   const host = hostname.toLowerCase();
+  if (browser) { try { assertBrowserName(browser); } catch { return null; } }
+  const label = `${browser ? `${browser}--` : ''}${siteLabel(host)}`;
   if (!/^[a-z0-9.-]+$/.test(host)) return null;
   // a one-label site is never an IDN's (`xn--…` would be read as punycode, and is no address)
-  const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', host)
-    : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', siteLabel(host)) : null;
+  const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', browser ? label : host)
+    : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', label) : null;
   try { return filled && new URL(filled).hostname.split('.').every((l) => l.length > 0 && l.length <= 63) ? filled : null; } catch { return null; }
 }
 
@@ -69,7 +72,9 @@ export function siteUrlOf(template: string, hostname: string): string | null {
  *  mints its own URLs from twinPublicBase. */
 export function twinSiteUrl(request: Request, hostname: string): string {
   const at = request.headers.get(TWIN_SITES_HEADER);
-  return (at ? siteUrlOf(at, hostname) : null) ?? `https://${hostname.toLowerCase()}`;
+  let browser = request.headers.get('x-volter-world-browser') ?? undefined;
+  if (browser) { try { assertBrowserName(browser); } catch { browser = undefined; } }
+  return (at ? siteUrlOf(at, hostname, browser) : null) ?? `https://${hostname.toLowerCase()}`;
 }
 
 /** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves

package/vendor-hosts.cjs

@@ -1,8 +1,8 @@
 'use strict';
 // THE VENDOR HOST TABLE — which vendor's twin serves a hostname (and, where two vendors share a host, which path), the
-// one home of that fact in a process, dependency-free and side-effect free. The injector (inject.cjs) routes by it; the
+// Node process's loaded facts. The pure compiler and resolver are host-routing.cjs; this loader reads Node facts.
+// The injector (inject.cjs) routes by the table; the
 // application route (app-route.cjs) never answers a name it gives a vendor, in the injector or in a twin's delivery.
-// Moved out of inject.cjs unchanged (2026-09-27).
 // ── PATH-AWARE DISAMBIGUATION (the shared-host case) ─────────────────────────────────────────
 // A predicate is called as `(hostname, pathname)`. `pathname` is OPTIONAL and is `undefined`
 // wherever the caller genuinely does not have one yet — most importantly the proxy's CONNECT
@@ -25,108 +25,12 @@
 // `browserassets` and `googlefavicon`; kernel packages carry no pack descriptor). Every vendor
 // pack's hosts live on its descriptor as DATA — host | suffix | hostPattern, pathPattern,
 // exclude, key — compiled from pack-facts.json.
-const VENDOR_HOSTS = {
-  googlefavicon: (h) => h === 'www.google.com' || h === 'google.com' || h === 't2.gstatic.com',
-  browserassets: (h) =>
-    h === 'cdnjs.cloudflare.com' ||
-    h === 'www.googletagmanager.com' ||
-    h === 'www.google-analytics.com' ||
-    h === 'connect.facebook.net' ||
-    h === 'snap.licdn.com' ||
-    h === 'px.ads.linkedin.com' ||
-    h === 'static.hotjar.com' ||
-    h === 'fonts.googleapis.com' ||
-    h === 'fonts.gstatic.com' ||
-    h === 'api.fontshare.com' ||
-    h === 'images.subscribe.dev' ||
-    h === 'www.youtube.com' ||
-    h === 'www.youtube-nocookie.com' ||
-    h === 'i.ytimg.com',
-};
-
-// descriptor-first migration (architecture.md, "The descriptor"): packs now declare their hosts as DATA on their descriptor
-// (`hosts` on TwinPack), compiled into the committed pack-facts artifact — a plain JSON this
-// preloaded, dependency-free module can `require` natively. The hand table above shrinks toward
-// empty as entries move; a vendor present in both homes throws (dual declaration is the drift
-// this migration ends, and a broken checkout should refuse to inject rather than half-route).
-/** The keys each pack's compiled rules answer under, by vendor: a pack's own facts learned later (addPackHosts) replace
- *  that vendor's rules, never another's. */
-const COMPILED = new Map();
-/** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
- *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
-const HAND = new Set(Object.keys(VENDOR_HOSTS));
-/** One host rule as a predicate over (hostname, pathname?): its one selector (host | suffix | hostPattern) and its
- *  pathPattern, a path left out matching any. */
-function compileHostRule(rule, where) {
-  const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
-  if (selectors !== 1) throw new Error(`inject: ${where} rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
-  const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
-  const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
-  return (h, p) =>
-    (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
-    && (pathRe === null || p === undefined || pathRe.test(p));
-}
-
-/** A pack's host rules (its descriptor's `hosts`) read as the injector reads them: `names(host)`, whether any include
- *  rule's selector names the host, whatever the path; `takes(host, path)`, whether the request is the pack's (under
- *  one of its keys, an include matches and no exclude does). The content route at a World's place holds a
- *  `<base>/@<host>/<path>` to it (pack-fetch.ts). */
-function hostRules(rules) {
-  const byKey = new Map();
-  for (const rule of rules || []) {
-    const key = rule.key === undefined ? '' : rule.key;
-    if (!byKey.has(key)) byKey.set(key, []);
-    byKey.get(key).push(rule);
-  }
-  const keys = [...byKey.values()].map((keyRules) => ({
-    includes: keyRules.filter((r) => r.exclude !== true).map((r) => compileHostRule(r, 'a pack')),
-    excludes: keyRules.filter((r) => r.exclude === true).map((r) => compileHostRule(r, 'a pack')),
-  }));
-  return {
-    names: (h) => keys.some((k) => k.includes.some((m) => m(h))),
-    takes: (h, p) => keys.some((k) => k.includes.some((m) => m(h, p)) && !k.excludes.some((m) => m(h, p))),
-  };
-}
-
-function compilePackHosts(packs, overlay) {
-  for (const vendor of Object.keys(packs)) {
-    const rules = packs[vendor].hosts;
-    if (!rules || rules.length === 0) continue;
-    for (const key of COMPILED.get(vendor) || []) delete VENDOR_HOSTS[key];
-    COMPILED.delete(vendor);
-    if (VENDOR_HOSTS[vendor] && !(overlay && HAND.has(vendor))) {
-      throw new Error(`inject: vendor "${vendor}" declares hosts on its pack descriptor AND in the hand VENDOR_HOSTS table — one home per fact; delete the hand entry.`);
-    }
-    // Rules group by `key` (default: the vendor id) — aws's descriptor declares the s3 and
-    // secretsmanager routing identities its twin answers under. A key matches when ANY include
-    // rule matches AND NO exclude rule matches.
-    const byKey = new Map();
-    for (const rule of rules) {
-      const key = rule.key === undefined ? vendor : rule.key;
-      if (!byKey.has(key)) byKey.set(key, []);
-      byKey.get(key).push(rule);
-    }
-    for (const [key, keyRules] of byKey) {
-      if (VENDOR_HOSTS[key] && !(overlay && HAND.has(key))) {
-        throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
-      }
-      const compile = (rule) => compileHostRule(rule, `key "${key}" (pack ${vendor})`);
-      const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
-      const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
-      VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
-      COMPILED.set(vendor, [...(COMPILED.get(vendor) || []), key]);
-    }
-  }
-}
-{
-  const facts = require('./pack-facts.cjs').packFacts();
-  const installed = new Set(facts.installed || []);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => !installed.has(vendor))), false);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => installed.has(vendor))), true);
-}
-/** Rules from packs' facts learned after this module loaded (a runtime told the facts of the World it boots): each
- *  vendor's replace its earlier rules. */
-function addPackHosts(packs) { compilePackHosts(packs || {}, true); }
+const routing = require('./host-routing.cjs');
+const facts = require('./pack-facts.cjs').packFacts();
+const table = routing.createHostTable(facts.packs, facts.installed);
+const VENDOR_HOSTS = table.hosts;
+const hostRules = routing.hostRules;
+function addPackHosts(packs) { table.addPackHosts(packs); }
 
 /** Whether any vendor's host rule names `host` (at the host level, whatever the path), whether or not its twin runs. */
 function isVendorHost(host) {
@@ -166,4 +70,8 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+/** Resolve using this Node process's loaded facts. */
+function resolveTwinHost(hostname, map, pathname, claimed) {
+  return routing.resolveTwinHost(VENDOR_HOSTS, hostname, map, pathname, claimed);
+}
+module.exports = { resolveTwinHost, VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/vendor-hosts.d.cts

@@ -9,3 +9,6 @@ export function twinOrigins(env: Readonly<Record<string, string | undefined>>):
 /** A pack's host rules (its descriptor's `hosts`, as data) read as the injector reads them: whether any include names a
  *  host whatever the path, and whether a request to a host and path is the pack's. */
 export function hostRules(rules: ReadonlyArray<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };
+
+/** Resolve an active twin exactly as the proxy, first declared host/path rules, then claimed hosts. */
+export function resolveTwinHost(hostname: string, map: Readonly<Record<string, string>>, pathname?: string, claimed?: Readonly<Record<string, ReadonlySet<string> | (() => ReadonlySet<string>)>>): { vendor: string; origin: string } | null;

package/dist/src/browser-session-permit.d.ts

@@ -1,13 +0,0 @@
-export declare const BROWSER_SESSION_HEADER = "x-volter-browser-session-permit";
-export declare const BROWSER_SESSION_PATH = "/_twin/browser-session";
-export type BrowserSessionChoice = {
-    person: string | null;
-    land: string;
-    until: number;
-};
-/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
-export declare function stripBrowserSessionPermit(request: Request): Request;
-/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
-export declare function withBrowserSessionPermit<T>(service: string, root: string, choice: BrowserSessionChoice, forward: (permit: string) => Promise<T>): Promise<T>;
-/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
-export declare function takeBrowserSessionPermit(request: Request, service: string, root?: string): BrowserSessionChoice | null;

package/dist/src/browser-session-permit.js

@@ -1,51 +0,0 @@
-// A host-only permission to change a browser session. Kept outside the twin's log and never sent to a browser.
-import { withHeaders } from "./with-headers.js";
-import { join } from 'node:path';
-import { getActiveWorldStore } from "./world-store.js";
-import { worldPaths } from "./storage.js";
-export const BROWSER_SESSION_HEADER = 'x-volter-browser-session-permit';
-export const BROWSER_SESSION_PATH = '/_twin/browser-session';
-const directory = (service, root) => join(worldPaths(service, root).dir, 'browser-session-permits');
-/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
-export function stripBrowserSessionPermit(request) {
-    if (!request.headers.has(BROWSER_SESSION_HEADER))
-        return request;
-    const headers = new Headers(request.headers);
-    headers.delete(BROWSER_SESSION_HEADER);
-    return withHeaders(request, headers);
-}
-/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
-export async function withBrowserSessionPermit(service, root, choice, forward) {
-    const store = getActiveWorldStore();
-    const permit = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(32))).toString('hex');
-    const path = join(directory(service, root), permit);
-    store.write(path, JSON.stringify(choice), { secret: true });
-    try {
-        return await forward(permit);
-    }
-    finally {
-        store.remove(path);
-    }
-}
-/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
-export function takeBrowserSessionPermit(request, service, root) {
-    const permit = request.headers.get(BROWSER_SESSION_HEADER);
-    if (!permit || !/^[0-9a-f]{64}$/.test(permit))
-        return null;
-    const store = getActiveWorldStore();
-    const dir = directory(service, root);
-    return store.withLock(`${dir}.lock`, () => {
-        const path = join(dir, permit);
-        const held = store.read(path);
-        if (held === null)
-            return null;
-        store.remove(path);
-        try {
-            const choice = JSON.parse(held);
-            return choice.until > Date.now() && (choice.person === null || typeof choice.person === 'string') && typeof choice.land === 'string' ? choice : null;
-        }
-        catch {
-            return null;
-        }
-    });
-}

package/src/browser-session-permit.ts

@@ -1,43 +0,0 @@
-// A host-only permission to change a browser session. Kept outside the twin's log and never sent to a browser.
-import { withHeaders } from './with-headers.ts';
-import { join } from 'node:path';
-import { getActiveWorldStore } from './world-store.ts';
-import { worldPaths } from './storage.ts';
-
-export const BROWSER_SESSION_HEADER = 'x-volter-browser-session-permit';
-export const BROWSER_SESSION_PATH = '/_twin/browser-session';
-export type BrowserSessionChoice = { person: string | null; land: string; until: number };
-const directory = (service: string, root?: string): string => join(worldPaths(service, root).dir, 'browser-session-permits');
-
-/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
-export function stripBrowserSessionPermit(request: Request): Request {
-  if (!request.headers.has(BROWSER_SESSION_HEADER)) return request;
-  const headers = new Headers(request.headers);
-  headers.delete(BROWSER_SESSION_HEADER);
-  return withHeaders(request, headers);
-}
-
-/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
-export async function withBrowserSessionPermit<T>(service: string, root: string, choice: BrowserSessionChoice, forward: (permit: string) => Promise<T>): Promise<T> {
-  const store = getActiveWorldStore();
-  const permit = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(32))).toString('hex');
-  const path = join(directory(service, root), permit);
-  store.write(path, JSON.stringify(choice), { secret: true });
-  try { return await forward(permit); } finally { store.remove(path); }
-}
-
-/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
-export function takeBrowserSessionPermit(request: Request, service: string, root?: string): BrowserSessionChoice | null {
-  const permit = request.headers.get(BROWSER_SESSION_HEADER);
-  if (!permit || !/^[0-9a-f]{64}$/.test(permit)) return null;
-  const store = getActiveWorldStore(); const dir = directory(service, root);
-  return store.withLock(`${dir}.lock`, () => {
-    const path = join(dir, permit); const held = store.read(path);
-    if (held === null) return null;
-    store.remove(path);
-    try {
-      const choice = JSON.parse(held) as BrowserSessionChoice;
-      return choice.until > Date.now() && (choice.person === null || typeof choice.person === 'string') && typeof choice.land === 'string' ? choice : null;
-    } catch { return null; }
-  });
-}