super-dsh 0.1.4 → 0.1.5-a

package/superd-hub/dist/fusion-transport.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Fusion transport (native UI fusion, plan Task 3) — the ctx0 page-level head
+ * script plus its injection component.
+ *
+ * The script installs, BEFORE any application bundle materializes:
+ *   - the page-level state atom `__SUPERD_UI_STATE__`
+ *     ({ get activeAgent(): 'native'|string, setAgent(label), subscribe(fn) }),
+ *     initial `'native'`, never persisted (no localStorage);
+ *   - five CALL-TIME patches (the atom is read at request time, never baked
+ *     into a closure — after setAgent the same request expression retargets):
+ *       1. `globalThis.fetch` — while a FOREIGN agent is active, a same-origin
+ *          request whose path starts with `/api` is re-rooted under `/hub`
+ *          and gains exactly one `agent=<label>` param (a pre-existing agent
+ *          key is replaced, never duplicated — the server demuxes repeated
+ *          params to the FIRST value; other query bytes + hash preserved);
+ *       2. `WebSocket` / `EventSource` Proxy constructors + `XMLHttpRequest.open`
+ *          — the same rule (the mux WS lands on `/hub/api/remote.mux`);
+ *       3. `__DSH_FILE_UPLOAD__ = { fetch }` — uploads ride patch 1 (the
+ *          file-upload service reads the hook at construction, so the hook
+ *          must exist before app boot);
+ *       4. `HTMLAnchorElement.prototype.click` — ONLY download anchors with a
+ *          same-origin `/api` href rewrite (the narrow client-shim r2 rule);
+ *          the rewrite is transient — saved around the native click and
+ *          restored after, so an agent switch re-targets the same anchor;
+ *       5. `Storage.prototype` get/set/removeItem — namespace read at call
+ *          time: native = no prefix, foreign = `'<label>:'`.
+ *   - one control-plane exemption: `/api/agent-runtime` is NEVER rewritten —
+ *     the roster always talks to ctx0, so the user can always switch back.
+ * Native mode is zero-interference: every patched face passes its exact
+ * arguments through untouched.
+ *
+ * The component's gated listener ALSO bakes `__SUPERD_UI_FUSION__ = true`
+ * into the ctx0 index (Task 4): the client half's fusion-branch
+ * discriminator, emitted by the same gate as the script so the halves never
+ * disagree (world pages never carry it and keep real hyperlinks — spec §5).
+ *
+ * Quoting discipline: the generated script contains NO double-quoted string —
+ * index-pass rewrites every DOUBLE-quoted root-absolute literal in served
+ * HTML, so all literals stay single-quoted (the client-shim precedent). The
+ * install is idempotent (per-leg guards) and best-effort (every leg is
+ * individually guarded; a failure disables that leg only).
+ *
+ * Injection (the web-trust emission path, ordered AFTER it — spec §3.4 hard
+ * constraint): the row is a `webserver/index-inject` head script pushed by the
+ * `superd-fusion-transport` component, composed through the composite row
+ * `super-dsh/fusion-transport` positioned after `super-dsh/web-trust`. Both
+ * components defer their listener registration behind `inject(['webServer'])`,
+ * so cordis's FIFO effect order guarantees trust pushes first and fusion
+ * pushes last — the non-merging `if(!window.__DSH_TRANSPORT__)` verdict in the
+ * trust script is always evaluated before anything could own that global.
+ * Row gate: the row config `enabled`, ON by default — the composite patch
+ * composing this row is the switch. `enabled: false` (or `disabled: true`)
+ * leaves the component dormant: no listener, no script, no flag global.
+ *
+ * @module @pgmi-builds/superd-hub/fusion-transport
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/**
+ * Render the page-level fusion transport as a classic script (head injection).
+ * Pure and constant: the active label is state, never a baked literal, so the
+ * script takes no arguments. All string literals are single-quoted (see the
+ * module doc block).
+ * @returns JavaScript source.
+ */
+export declare function renderFusionTransport(): string;
+/**
+ * The page global the ctx0 index carries when this row is on: the client
+ * half's fusion-branch discriminator (the Hub UI switch surfaces read its
+ * presence to intercept agent clicks into the switch orchestration instead
+ * of letting the hyperlinks navigate — the sole switch surface since the T-B
+ * RuntimeSeat retirement; world pages never carry it, so they keep the real
+ * navigation half — spec §5 双半边). Baked by the SAME listener as the
+ * transport script, so the two halves can never disagree.
+ */
+export declare const FUSION_FLAG_GLOBAL = "__SUPERD_UI_FUSION__";
+/**
+ * The row's SEMANTICS after the path-separation Part 2 closeout (T-C/T-D
+ * landed; this block is the T-E closeout record) — native-ui-only, there is
+ * no fallback route anywhere:
+ *
+ *   - ON: the ctx0 page fuses. The transport script arms the in-place switch
+ *     and `/hub` is the sole surface for every runtime. The per-label URL
+ *     family (`/<label>/` ctx0 pages, T-C) and the world web UIs (T-D) are
+ *     RETIRED from the product, not gated by this row — there is nothing
+ *     navigational behind them to fall back to.
+ *   - OFF: NO foreign entry exists AT ALL. The served product is the bare
+ *     native UI plus the Hub panel as an information surface: the roster
+ *     still lists the runtimes (the control plane is not gated), but the
+ *     switch affordances render inert with the degradation hint
+ *     (`switchAffordance` in switch-core) instead of dead controls — a row
+ *     has no /<label>/ page to reach and the Hub UI ships no hrefs to reach
+ *     one with.
+ *
+ * The switch is ROW COMPOSITION, exactly like every other row here: the
+ * composite patch composes this row, so the fused surface is what the product
+ * ships. A deployment that does not want it turns the row off where cordis
+ * already owns that decision — a profile layer restating the row with
+ * `config: { enabled: false }` (整行重述: same id, same name) or
+ * `disabled: true`, or dropping `super-dsh/fusion-transport` from the
+ * composition entirely. There is deliberately no env-derived default: a
+ * release gate living in an environment variable is deployment state that no
+ * patch layer can see, read, or diff.
+ */
+export interface FusionConfig {
+    /**
+     * Whether this row injects the transport script and the flag global on
+     * ctx0's index. Default on — the row being composed is the switch.
+     */
+    enabled?: boolean;
+}
+/** Row config: ON unless a patch layer restates the row with `enabled: false`. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/** Cordis plugin name. */
+export declare const name = "superd-fusion-transport";
+/**
+ * No static injects: `webServer` is composed conditionally inside
+ * {@link apply}, so the row loads (dormant) in compositions without one.
+ */
+export declare const inject: string[];
+/**
+ * Mount the fusion injection: one `webserver/index-inject` listener pushing
+ * the rendered head script row — the same emission path as the web-trust
+ * component, composed AFTER it (the composite row order is load order, and
+ * both components register their listeners behind `inject(['webServer'])`, so
+ * cordis's FIFO effect order pushes the fusion row last; spec §3.4) — plus
+ * the {@link FUSION_FLAG_GLOBAL} baked global row (Task 4): one gate, both
+ * halves.
+ *
+ * Off → the component registers nothing: no listener, no row, no script,
+ * no flag global.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`enabled`, default on).
+ */
+export declare function apply(ctx: Context, config: FusionConfig | undefined): void;
+declare const _default: {
+    name: string;
+    inject: string[];
+    Config: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
+    apply: typeof apply;
+};
+export default _default;

package/superd-hub/dist/fusion-transport.js

@@ -0,0 +1,369 @@
+/**
+ * Fusion transport (native UI fusion, plan Task 3) — the ctx0 page-level head
+ * script plus its injection component.
+ *
+ * The script installs, BEFORE any application bundle materializes:
+ *   - the page-level state atom `__SUPERD_UI_STATE__`
+ *     ({ get activeAgent(): 'native'|string, setAgent(label), subscribe(fn) }),
+ *     initial `'native'`, never persisted (no localStorage);
+ *   - five CALL-TIME patches (the atom is read at request time, never baked
+ *     into a closure — after setAgent the same request expression retargets):
+ *       1. `globalThis.fetch` — while a FOREIGN agent is active, a same-origin
+ *          request whose path starts with `/api` is re-rooted under `/hub`
+ *          and gains exactly one `agent=<label>` param (a pre-existing agent
+ *          key is replaced, never duplicated — the server demuxes repeated
+ *          params to the FIRST value; other query bytes + hash preserved);
+ *       2. `WebSocket` / `EventSource` Proxy constructors + `XMLHttpRequest.open`
+ *          — the same rule (the mux WS lands on `/hub/api/remote.mux`);
+ *       3. `__DSH_FILE_UPLOAD__ = { fetch }` — uploads ride patch 1 (the
+ *          file-upload service reads the hook at construction, so the hook
+ *          must exist before app boot);
+ *       4. `HTMLAnchorElement.prototype.click` — ONLY download anchors with a
+ *          same-origin `/api` href rewrite (the narrow client-shim r2 rule);
+ *          the rewrite is transient — saved around the native click and
+ *          restored after, so an agent switch re-targets the same anchor;
+ *       5. `Storage.prototype` get/set/removeItem — namespace read at call
+ *          time: native = no prefix, foreign = `'<label>:'`.
+ *   - one control-plane exemption: `/api/agent-runtime` is NEVER rewritten —
+ *     the roster always talks to ctx0, so the user can always switch back.
+ * Native mode is zero-interference: every patched face passes its exact
+ * arguments through untouched.
+ *
+ * The component's gated listener ALSO bakes `__SUPERD_UI_FUSION__ = true`
+ * into the ctx0 index (Task 4): the client half's fusion-branch
+ * discriminator, emitted by the same gate as the script so the halves never
+ * disagree (world pages never carry it and keep real hyperlinks — spec §5).
+ *
+ * Quoting discipline: the generated script contains NO double-quoted string —
+ * index-pass rewrites every DOUBLE-quoted root-absolute literal in served
+ * HTML, so all literals stay single-quoted (the client-shim precedent). The
+ * install is idempotent (per-leg guards) and best-effort (every leg is
+ * individually guarded; a failure disables that leg only).
+ *
+ * Injection (the web-trust emission path, ordered AFTER it — spec §3.4 hard
+ * constraint): the row is a `webserver/index-inject` head script pushed by the
+ * `superd-fusion-transport` component, composed through the composite row
+ * `super-dsh/fusion-transport` positioned after `super-dsh/web-trust`. Both
+ * components defer their listener registration behind `inject(['webServer'])`,
+ * so cordis's FIFO effect order guarantees trust pushes first and fusion
+ * pushes last — the non-merging `if(!window.__DSH_TRANSPORT__)` verdict in the
+ * trust script is always evaluated before anything could own that global.
+ * Row gate: the row config `enabled`, ON by default — the composite patch
+ * composing this row is the switch. `enabled: false` (or `disabled: true`)
+ * leaves the component dormant: no listener, no script, no flag global.
+ *
+ * @module @pgmi-builds/superd-hub/fusion-transport
+ */
+import z from '@deepseek-ai/schemastery';
+/**
+ * Render the page-level fusion transport as a classic script (head injection).
+ * Pure and constant: the active label is state, never a baked literal, so the
+ * script takes no arguments. All string literals are single-quoted (see the
+ * module doc block).
+ * @returns JavaScript source.
+ */
+export function renderFusionTransport() {
+    return `(() => {
+try {
+  const g = globalThis
+
+  // ---- the __SUPERD_UI_STATE__ atom (created once; re-runs keep live state) ----
+  if (g.__SUPERD_UI_STATE__ === undefined || g.__SUPERD_UI_STATE__ === null) {
+    let current = 'native'
+    const subscribers = []
+    g.__SUPERD_UI_STATE__ = {
+      get activeAgent() { return current },
+      setAgent(label) {
+        if (typeof label !== 'string' || label === '') return
+        if (label === current) return
+        current = label
+        for (const fn of subscribers.slice()) {
+          try { fn(current) } catch { /* a broken subscriber never breaks the atom */ }
+        }
+      },
+      subscribe(fn) {
+        if (typeof fn !== 'function') return () => {}
+        subscribers.push(fn)
+        return () => {
+          const at = subscribers.indexOf(fn)
+          if (at !== -1) subscribers.splice(at, 1)
+        }
+      },
+    }
+  }
+  const state = g.__SUPERD_UI_STATE__
+
+  // ---- the one rewrite rule: '/api...' becomes '/hub/api...' + '?agent=<label>' ----
+  const HUB = '/hub'
+  const CONTROL = '/api/agent-runtime'
+  const origin = () => {
+    const loc = g.location
+    if (loc !== undefined && typeof loc.origin === 'string' && loc.origin !== 'null') return loc.origin
+    return 'http://dsh.internal'
+  }
+  // Same authority as the page (scheme-agnostic: ws/wss/http/https share host).
+  const sameAuthority = (url) => {
+    try {
+      return url.host === new URL(origin()).host
+    } catch {
+      return false
+    }
+  }
+  const isApiPath = (path) => path === '/api' || path.startsWith('/api/')
+  // Control-plane exemption: the roster control plane always hits ctx0.
+  const isExempt = (path) => path === CONTROL || path.startsWith(CONTROL + '/')
+  // Key compare matches the server demux shape: searchParams.get('agent')
+  // looks up PERCENT-DECODED keys, so '%61gent=x' demuxes as agent=x and the
+  // surgery must strip those spellings too (+' ' wins the '+' spelling).
+  const decodedKey = (k) => {
+    try { return decodeURIComponent(k.replace(/\\+/g, ' ')) } catch { return k }
+  }
+  const isAgentKey = (k) => k === 'agent' || decodedKey(k) === 'agent'
+  // Pure string surgery on (path, search, hash): the '/hub' prefix grows on
+  // the path, the hash survives byte-for-byte, and EXACTLY ONE agent param
+  // carries the active label. A pre-existing agent key is stripped before the
+  // fresh one lands — appending blindly would leave two agent params and the
+  // server demuxes to the FIRST value (searchParams.get), i.e. the wrong
+  // world with no trace. Non-agent query pairs keep their exact bytes and
+  // order; a bare '?' (no pairs) collapses instead of doubling the question
+  // mark, which would swallow the demux key.
+  const retarget = (path, search, hash) => {
+    if (isExempt(path) || !isApiPath(path)) return null
+    let kept = ''
+    if (search.length > 1) {
+      const survivors = []
+      for (const pair of (search.charAt(0) === '?' ? search.slice(1) : search).split('&')) {
+        if (pair === '') continue
+        const eq = pair.indexOf('=')
+        if (!isAgentKey(eq === -1 ? pair : pair.slice(0, eq))) survivors.push(pair)
+      }
+      kept = survivors.join('&')
+    }
+    return HUB + path + (kept === '' ? '?' : '?' + kept + '&') + 'agent=' + encodeURIComponent(String(state.activeAgent)) + hash
+  }
+  const rewriteUrlString = (s) => {
+    if (typeof s !== 'string' || s === '') return s
+    if (s.startsWith('/')) {
+      if (s.startsWith('//')) return s // protocol-relative: another authority
+      const hashAt = s.indexOf('#')
+      const hash = hashAt === -1 ? '' : s.slice(hashAt)
+      const rest = hashAt === -1 ? s : s.slice(0, hashAt)
+      const queryAt = rest.indexOf('?')
+      const search = queryAt === -1 ? '' : rest.slice(queryAt)
+      const path = queryAt === -1 ? rest : rest.slice(0, queryAt)
+      const next = retarget(path, search, hash)
+      return next === null ? s : next
+    }
+    try {
+      const url = new URL(s, origin())
+      if (!sameAuthority(url)) return s
+      const next = retarget(url.pathname, url.search, url.hash)
+      return next === null ? s : url.origin + next
+    } catch {
+      return s
+    }
+  }
+  const rewriteApiUrl = (input) => {
+    if (typeof input === 'string') return rewriteUrlString(input)
+    if (input !== null && typeof input === 'object' && typeof input.href === 'string') {
+      const next = rewriteUrlString(input.href)
+      return next === input.href ? input : next
+    }
+    return input
+  }
+  // Foreign means a non-native STRING label; anything else behaves native.
+  const foreign = () => typeof state.activeAgent === 'string' && state.activeAgent !== 'native'
+  // Never-throw wrapper: a failed rewrite falls back to the exact input.
+  const rewriteSafe = (input) => {
+    try {
+      return foreign() ? rewriteApiUrl(input) : input
+    } catch {
+      return input
+    }
+  }
+
+  // ---- patches 1 + 3: globalThis.fetch, and the file-upload hook riding it ----
+  if (g.__SUPERD_UI_FUSION_FETCH__ !== true) {
+    g.__SUPERD_UI_FUSION_FETCH__ = true
+    try {
+      const nativeFetch = g.fetch
+      if (typeof nativeFetch === 'function') {
+        const shimFetch = (input, init) => {
+          if (!foreign()) return nativeFetch(input, init)
+          let target = input
+          try {
+            if (typeof Request === 'function' && input instanceof Request) {
+              const url = rewriteApiUrl(input.url)
+              target = url === input.url ? input : new Request(url, input)
+            } else {
+              target = rewriteApiUrl(input)
+            }
+          } catch {
+            target = input
+          }
+          return nativeFetch(target, init)
+        }
+        g.fetch = shimFetch
+        // Read by the file-upload service at construction time: present means
+        // the page fetch carries uploads (no blob worker), and the hook IS the
+        // rewriting fetch, so uploads follow the active agent like patch 1.
+        g.__DSH_FILE_UPLOAD__ = { fetch: shimFetch }
+      }
+    } catch { /* best-effort: this leg dies alone */ }
+  }
+
+  // ---- patch 2: WebSocket / EventSource Proxy constructors + XMLHttpRequest.open ----
+  // Construct through a Proxy, never a hand-rolled wrapper: statics, prototype
+  // and instanceof must survive (the mux client compares readyState constants).
+  if (g.__SUPERD_UI_FUSION_SOCKETS__ !== true) {
+    g.__SUPERD_UI_FUSION_SOCKETS__ = true
+    try {
+      const NativeWebSocket = g.WebSocket
+      if (typeof NativeWebSocket === 'function') {
+        g.WebSocket = new Proxy(NativeWebSocket, {
+          construct: (Target, args) => {
+            const url = rewriteSafe(args[0])
+            if (url !== args[0]) return new Target(url, ...args.slice(1))
+            return Reflect.construct(Target, args)
+          },
+        })
+      }
+    } catch { /* best-effort */ }
+    try {
+      const NativeEventSource = g.EventSource
+      if (typeof NativeEventSource === 'function') {
+        g.EventSource = new Proxy(NativeEventSource, {
+          construct: (Target, args) => {
+            const url = rewriteSafe(args[0])
+            if (url !== args[0]) return new Target(url, ...args.slice(1))
+            return Reflect.construct(Target, args)
+          },
+        })
+      }
+    } catch { /* best-effort */ }
+    try {
+      const NativeXhr = g.XMLHttpRequest
+      if (typeof NativeXhr === 'function' && NativeXhr.prototype !== undefined && typeof NativeXhr.prototype.open === 'function') {
+        const nativeOpen = NativeXhr.prototype.open
+        NativeXhr.prototype.open = function (method, url) {
+          const target = rewriteSafe(url)
+          if (target === url) return nativeOpen.apply(this, arguments)
+          return nativeOpen.apply(this, [method, target].concat(Array.prototype.slice.call(arguments, 2)))
+        }
+      }
+    } catch { /* best-effort */ }
+  }
+
+  // ---- patch 4: download anchors (the narrow rule, client-shim r2 shape) ----
+  // ONLY anchors carrying a download attribute AND a same-origin /api href
+  // rewrite; every other anchor (navigation links included) passes through.
+  try {
+    if (g.HTMLAnchorElement !== undefined && g.HTMLAnchorElement.prototype !== undefined
+      && typeof g.HTMLAnchorElement.prototype.click === 'function'
+      && g.__SUPERD_UI_FUSION_ANCHOR__ !== true) {
+      g.__SUPERD_UI_FUSION_ANCHOR__ = true
+      const nativeAnchorClick = g.HTMLAnchorElement.prototype.click
+      g.HTMLAnchorElement.prototype.click = function (...args) {
+        let original = null
+        try {
+          if (foreign() && this.hasAttribute('download')) {
+            const current = this.getAttribute('href')
+            if (typeof current === 'string' && current !== '') {
+              const next = rewriteSafe(current)
+              if (typeof next === 'string' && next !== current) {
+                this.setAttribute('href', next)
+                original = current
+              }
+            }
+          }
+        } catch { /* best-effort: never break the click itself */ }
+        try {
+          return nativeAnchorClick.apply(this, args)
+        } finally {
+          // The rewrite is TRANSIENT: restored right after the native click,
+          // so the rewritten /hub/api href never outlives it. A persisted
+          // rewrite would survive an agent switch and the next click would
+          // browse the stale /hub/api form — no /api match, no re-rewrite,
+          // wrong-agent download.
+          if (original !== null) {
+            try { this.setAttribute('href', original) } catch { /* best-effort */ }
+          }
+        }
+      }
+    }
+  } catch { /* best-effort */ }
+
+  // ---- patch 5: storage namespace, derived at CALL time ----
+  // Native mode prefixes nothing (bare keys, byte-identical behavior); a
+  // foreign agent reads and writes only its own '<label>:' tree.
+  try {
+    const StorageProto = g.Storage && g.Storage.prototype
+    if (StorageProto !== undefined && g.localStorage !== undefined
+      && g.__SUPERD_UI_FUSION_STORAGE__ !== true
+      && typeof StorageProto.getItem === 'function'
+      && typeof StorageProto.setItem === 'function'
+      && typeof StorageProto.removeItem === 'function') {
+      g.__SUPERD_UI_FUSION_STORAGE__ = true
+      const nativeGetItem = StorageProto.getItem
+      const nativeSetItem = StorageProto.setItem
+      const nativeRemoveItem = StorageProto.removeItem
+      const ns = () => {
+        const active = state.activeAgent
+        return typeof active === 'string' && active !== 'native' ? active + ':' : ''
+      }
+      StorageProto.getItem = function (name) { return nativeGetItem.call(this, ns() + name) }
+      StorageProto.setItem = function (name, value) { return nativeSetItem.call(this, ns() + name, value) }
+      StorageProto.removeItem = function (name) { return nativeRemoveItem.call(this, ns() + name) }
+    }
+  } catch { /* storage namespace is best-effort: never break the page */ }
+} catch { /* the whole install is best-effort: a partial page is still a page */ }
+})()`;
+}
+/**
+ * The page global the ctx0 index carries when this row is on: the client
+ * half's fusion-branch discriminator (the Hub UI switch surfaces read its
+ * presence to intercept agent clicks into the switch orchestration instead
+ * of letting the hyperlinks navigate — the sole switch surface since the T-B
+ * RuntimeSeat retirement; world pages never carry it, so they keep the real
+ * navigation half — spec §5 双半边). Baked by the SAME listener as the
+ * transport script, so the two halves can never disagree.
+ */
+export const FUSION_FLAG_GLOBAL = '__SUPERD_UI_FUSION__';
+/** Row config: ON unless a patch layer restates the row with `enabled: false`. */
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+});
+/** Cordis plugin name. */
+export const name = 'superd-fusion-transport';
+/**
+ * No static injects: `webServer` is composed conditionally inside
+ * {@link apply}, so the row loads (dormant) in compositions without one.
+ */
+export const inject = [];
+/**
+ * Mount the fusion injection: one `webserver/index-inject` listener pushing
+ * the rendered head script row — the same emission path as the web-trust
+ * component, composed AFTER it (the composite row order is load order, and
+ * both components register their listeners behind `inject(['webServer'])`, so
+ * cordis's FIFO effect order pushes the fusion row last; spec §3.4) — plus
+ * the {@link FUSION_FLAG_GLOBAL} baked global row (Task 4): one gate, both
+ * halves.
+ *
+ * Off → the component registers nothing: no listener, no row, no script,
+ * no flag global.
+ * @param ctx - host plugin context.
+ * @param config - the row config (`enabled`, default on).
+ */
+export function apply(ctx, config) {
+    // Composed row = on. Only an explicit `enabled: false` turns it off, so a
+    // composition that omits the config key cannot silently disable the surface.
+    if (config?.enabled === false)
+        return;
+    ctx.inject(['webServer'], () => {
+        ctx.on('webserver/index-inject', (table) => {
+            table.push({ kind: 'script', placement: 'head', text: renderFusionTransport() });
+            table.push({ kind: 'global', name: FUSION_FLAG_GLOBAL, value: true });
+        });
+    });
+}
+export default { name, inject, Config, apply };

package/superd-hub/dist/gateway.d.ts

@@ -19,10 +19,15 @@ export declare const name = "superd-hub";
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Two CTX0-owned contributions, neither carrying any selection value:
+ * Three CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
- *     every mount path the hub currently serves.
+ *     every mount path the hub currently serves;
+ *   - the `/hub` route family (native UI fusion Task 2): the single foreign
+ *     seam on ctx0's listener, registered once the listening stack is up.
+ *     World trees compose this same row, but their `webServer` is the VIRTUAL
+ *     per-world translation surface — the `/hub` family belongs to ctx0's
+ *     real listener only (one family per process, demuxed by `?agent=`).
  */
 export declare function apply(ctx: Context): void;
 export default apply;

package/superd-hub/dist/gateway.js

@@ -1,18 +1,44 @@
 import { registerSelectorRpc, registryTargets } from './rpc.js';
 import { agentRosterRow } from './agent-roster.js';
+import { getTarget } from './targets.js';
+import { registerHubRoute } from './hub-route.js';
+import { WorldWebServer } from './world-web-server.js';
 /** Stable Cordis plugin name. */
 export const name = 'superd-hub';
 /**
  * The plugin form (row contract): applied when the row mounts.
  *
- * Two CTX0-owned contributions, neither carrying any selection value:
+ * Three CTX0-owned contributions, none carrying any selection value:
  *   - the world inventory control plane (read-only);
  *   - the agent roster row baked into ctx0's own index, so the selector lists
- *     every mount path the hub currently serves.
+ *     every mount path the hub currently serves;
+ *   - the `/hub` route family (native UI fusion Task 2): the single foreign
+ *     seam on ctx0's listener, registered once the listening stack is up.
+ *     World trees compose this same row, but their `webServer` is the VIRTUAL
+ *     per-world translation surface — the `/hub` family belongs to ctx0's
+ *     real listener only (one family per process, demuxed by `?agent=`).
  */
 export function apply(ctx) {
     registerSelectorRpc(ctx, registryTargets);
     const on = ctx.on;
     on?.call(ctx, 'webserver/index-inject', (table) => { table.push(agentRosterRow()); });
+    ctx.inject(['webServer', 'connection'], (host) => {
+        const real = host.get('webServer');
+        if (real instanceof WorldWebServer)
+            return;
+        const connection = host.get('connection');
+        // The gate is ctx0's authorize source (connection.authorizeIndex); the
+        // addressed world resolves per request through the live foreign-target
+        // table — never a shared selection. The requestRejection face is the
+        // ctx0 browser-trust fence: auth first, then Host/Origin — the family is
+        // never weaker than the neighbors carrying identical traffic.
+        const dispose = registerHubRoute({
+            real: real,
+            authorize: (req, res) => connection.authorizeIndex(req, res),
+            requestRejection: (req) => connection.requestRejection(req),
+            gatewayOf: (label) => getTarget(label)?.gateway,
+        });
+        ctx.effect(() => dispose, 'superd-hub: /hub route family');
+    });
 }
 export default apply;

package/superd-hub/dist/hub-route.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The hub-owned `/hub` route family (native UI fusion, plan Task 2).
+ *
+ * ONE prefix route + ONE upgrade route on ctx0's webServer (design ratified
+ * 2026-09-26): every FOREIGN-agent request funnels into this family and the
+ * demux key rides the query (`?agent=<label>`) instead of the path. The
+ * native `/api` surface is never touched — this family is the only seam. It
+ * registers unconditionally (authorize-gated, inert until a request carries a
+ * registered foreign label); the fusion feature flag never gates server route
+ * registration.
+ *
+ * Semantics per request:
+ *  - `?agent=<label>` with a registered gateway → the request is consumed and
+ *    forwarded to that world: envelope POST → `dispatchRpc`, non-envelope
+ *    GET/HEAD → the world's published `/api` fetch handler, WS upgrade → a
+ *    `WorldMuxServer` bound to that gateway. The demux key is CONSUMED, so
+ *    the world sees exactly the URL its native page would have sent
+ *    (`/hub/api/x?agent=o&p=1` → world `/api/x?p=1`).
+ *  - no `agent` param or `agent=native` → 404 JSON: the family serves foreign
+ *    traffic only; native belongs to `/api`.
+ *  - unknown / not-yet-spawned label → 404 JSON `{error:'unknown-agent',
+ *    label}` — silent degradation, never a locked page.
+ *
+ * The ctx0 gate is the SAME authorize source the world mounts use
+ * (`connection.authorizeIndex`, the boolean face whose false path already
+ * wrote the answer — 401 or the token→cookie 303); the family then runs the
+ * SAME browser-trust fence the sibling `/<label>/api` mounts run
+ * (`requestRejection`, the connection's `isTrustedApiRequest` face) before it
+ * answers anything — the family is never weaker than the neighbors carrying
+ * identical traffic. Forwarding reuses the carrier kernel
+ * ({@link forwardApiCall} / {@link worldMuxOf}) unchanged: this module only
+ * gates, fences and demuxes.
+ *
+ * Mux lifecycle (review round 1): each accepted upgrade constructs ONE
+ * `WorldMuxServer`, which roots a heartbeat interval and a per-connection
+ * WebSocketServer — resources that would otherwise outlive the client forever
+ * (one 2s no-op timer per reconnect). The mux is therefore CLOSED the moment
+ * its socket dies: close-on-disconnect. The carrier's shared-mux-per-mount
+ * shape does not transfer (the hub rebinds per respawn); close-on-disconnect
+ * does.
+ */
+import { type CarrierGatewayFace } from './carrier.js';
+import { type RealWebServerFace } from './world-web-server.js';
+/** The mount prefix the family owns. */
+export declare const HUB_MOUNT_PATH = "/hub";
+/** The WebSocket upgrade path (upstream matches upgrades by pathname, so `?agent=` rides along). */
+export declare const HUB_MUX_PATH = "/hub/api/remote.mux";
+/** Options for registering the family on one (real) webServer. */
+export interface HubRouteOptions {
+    /** The ctx0 webServer the family registers on. */
+    real: RealWebServerFace;
+    /**
+     * ctx0's index authorization (the world-mount gate source): false means the
+     * authorizer already answered (401, or the token→cookie 303) and the family
+     * must not touch any gateway.
+     */
+    authorize(req: unknown, res: unknown): boolean;
+    /**
+     * ctx0's browser-trust fence — the SAME `isTrustedApiRequest` face the
+     * sibling carrier mounts run: returns an HTTP status to reject with, or
+     * undefined for trusted Host/Origin. Runs after {@link authorize} (auth
+     * first, the carrier's own ordering precedent) and before ANY family
+     * answer, so even the demux 404s never speak to untrusted traffic.
+     */
+    requestRejection?(req: unknown): number | undefined;
+    /** The live gateway of a registered label, or undefined (unknown / not yet spawned). */
+    gatewayOf(label: string): CarrierGatewayFace | undefined;
+}
+/**
+ * Register the family on ctx0's webServer.
+ * @param options - see {@link HubRouteOptions}.
+ * @returns the disposer unregistering both routes.
+ */
+export declare function registerHubRoute(options: HubRouteOptions): () => void;