dsh-vision-router 2.2.7 → 2.3.0

package/lib/catalog-corrections.js

@@ -15,7 +15,6 @@ import {
   readResponseTextBounded,
 } from './http-body-limit.js'
 import { stripTrailingSlashes } from './string-normalization.js'
-import { currentVisionProviderTransport } from './vision-provider-transport.js'
 import { directSessionAffinityHeaders } from './session-affinity.js'
 import { isOffloadedImageBlock, offloadedImagePlaceholder } from './image-offload-compat.js'
 
@@ -262,7 +261,7 @@ export async function callAnthropicCompatible(provider, messages, options = {})
   const url = `${stripTrailingSlashes(provider.baseURL)}/v1/messages`
   let response
   try {
-    const transport = currentVisionProviderTransport()
+    const transport = options.providerTransport
     const requestFetch = transport
       ? (input, init) => transport.fetch(input, init, { providerName: provider.name, allowProxy: true })
       : fetch

package/lib/client-host-compat-prelude.js

@@ -1,4 +1,4 @@
-import { htmlHasScriptMarker } from './html-script-marker.js'
+import { injectClientCarrierHtml, installClientScriptCarriers } from './client-script-carrier.js'
 
 const CLIENT_HOST_COMPAT_MARK = 'data-vision-router-host-compat'
 
@@ -243,19 +243,14 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
 })();`
 
 export function injectClientHostCompatibility(html) {
-  if (typeof html !== 'string' || htmlHasScriptMarker(html, CLIENT_HOST_COMPAT_MARK)) return html
-  const safe = CLIENT_HOST_COMPAT_PRELUDE.replace(/<\/script/gi, '<\\/script')
-  const script = `<script ${CLIENT_HOST_COMPAT_MARK}>${safe}</script>`
-  const closeHead = html.indexOf('</head>')
-  if (closeHead !== -1) return `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
-  return `${html}${script}`
+  return injectClientCarrierHtml(html, CLIENT_HOST_COMPAT_MARK, CLIENT_HOST_COMPAT_PRELUDE)
 }
 
 export function installClientHostCompatibility(ctx) {
-  ctx?.inject?.(['webServer'], (webCtx) => {
-    webCtx.effect(
-      () => webCtx.webServer.tapIndex(injectClientHostCompatibility),
-      'vision-router: client Host compatibility boundary',
-    )
+  installClientScriptCarriers(ctx, {
+    marker: CLIENT_HOST_COMPAT_MARK,
+    prelude: CLIENT_HOST_COMPAT_PRELUDE,
+    label: 'vision-router: client Host compatibility',
+    injectHtml: injectClientHostCompatibility,
   })
 }

package/lib/client-maintenance-actions.js

@@ -0,0 +1,145 @@
+/**
+ * Browser-side product maintenance actions, independent of React rendering.
+ *
+ * State access is supplied through getters/setters so the generated client
+ * bundle can keep one small action owner without giving it Settings, routing or
+ * Host-context authority.
+ */
+export function createClientMaintenanceActions({
+  fetchImpl,
+  t,
+  getTestState,
+  setTestState,
+  getUpdateState,
+  setUpdateState,
+  getSelfUpdateState,
+  setSelfUpdateState,
+  confirmImpl,
+  alertImpl,
+} = {}) {
+  if (typeof fetchImpl !== 'function') throw new TypeError('client maintenance actions require fetch')
+  const translate = typeof t === 'function' ? t : (key) => String(key)
+
+  const diagnosticError = (value, fallback) => {
+    if (typeof value === 'string' && value.trim() !== '') return value.trim()
+    if (value && typeof value.message === 'string' && value.message.trim() !== '') {
+      return value.message.trim()
+    }
+    return fallback
+  }
+
+  const runTestConnection = async () => {
+    if (getTestState?.()?.status === 'running') return
+    setTestState?.({ status: 'running' })
+    try {
+      const response = await fetchImpl('/_dsh/vision-router/test-connection')
+      const result = await response.json().catch(() => undefined)
+      setTestState?.({ status: 'done', result })
+    } catch (error) {
+      setTestState?.({
+        status: 'done',
+        result: { ok: false, error: error && error.message ? error.message : String(error) },
+      })
+    }
+  }
+
+  const requestDesktopScreenshotPermission = () => {
+    // Fire-and-forget: the native permission dialog must never hold Settings
+    // save completion open. The actual screenshot tool still reports denial.
+    try {
+      void Promise.resolve(fetchImpl('/_dsh/vision-router/request-screenshot-permission', {
+        method: 'POST',
+        cache: 'no-store',
+      })).catch(() => {})
+    } catch {
+      // Permission prompting is best-effort after an already-landed setting.
+    }
+  }
+
+  const runUpdateCheck = async (force = false) => {
+    const current = getUpdateState?.() ?? {}
+    if (current.status === 'running') return
+    setUpdateState?.({ status: 'running', result: current.result })
+    try {
+      const response = await fetchImpl(
+        '/_dsh/vision-router/update-check' + (force ? '?force=1' : ''),
+        { cache: 'no-store' },
+      )
+      const result = await response.json().catch(() => undefined)
+      if (!response.ok) {
+        throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+      }
+      if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+        throw new Error(translate('updateInvalidResponse'))
+      }
+      setUpdateState?.({ status: 'done', result })
+    } catch (error) {
+      setUpdateState?.({
+        status: 'done',
+        result: {
+          ok: false,
+          error: error && error.message ? error.message : String(error),
+        },
+      })
+    }
+  }
+
+  const runSelfUpdate = async () => {
+    if (getSelfUpdateState?.()?.status === 'running') return
+    const checked = getUpdateState?.()?.result
+    const auto = checked && checked.autoUpdate
+    if (!checked || checked.ok !== true || checked.updateAvailable !== true || !auto || !auto.token) return
+    if (typeof confirmImpl === 'function' && confirmImpl(translate('updateConfirm')) !== true) return
+    setSelfUpdateState?.({ status: 'running', result: undefined })
+    try {
+      const response = await fetchImpl('/_dsh/vision-router/self-update', {
+        method: 'POST',
+        cache: 'no-store',
+        headers: { 'x-dsh-vision-router-update-token': auto.token },
+      })
+      const result = await response.json().catch(() => undefined)
+      if (!response.ok) {
+        throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+      }
+      if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+        throw new Error(translate('updateInvalidResponse'))
+      }
+      setSelfUpdateState?.({ status: 'done', result })
+    } catch (error) {
+      setSelfUpdateState?.({
+        status: 'error',
+        result: { ok: false, error: error && error.message ? error.message : String(error) },
+      })
+    }
+  }
+
+  const openLogFolder = async () => {
+    try {
+      const response = await fetchImpl('/_dsh/vision-router/logs', {
+        method: 'POST',
+        cache: 'no-store',
+      })
+      const result = await response.json().catch(() => undefined)
+      if (!response.ok || !result || result.ok !== true) {
+        throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
+      }
+      return result
+    } catch (error) {
+      if (typeof alertImpl === 'function') {
+        alertImpl(
+          translate('openLogFolderFailed') + '：' +
+            (error && error.message ? error.message : String(error)),
+        )
+      }
+      return undefined
+    }
+  }
+
+  return {
+    runTestConnection,
+    requestDesktopScreenshotPermission,
+    runUpdateCheck,
+    runSelfUpdate,
+    openLogFolder,
+  }
+}

package/lib/client-presentation-boundary-main.js

@@ -1,3 +1,4 @@
+import { injectClientCarrierHtml, installClientScriptCarriers } from './client-script-carrier.js'
 const CLIENT_PRESENTATION_MARK = 'data-vision-router-presentation-boundary'
 const VISION_MODE_WRAPPER_SOURCE = 'deepseek-official'
 
@@ -1057,21 +1058,52 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
         var visionConfig = settingsState && settingsState.value && typeof settingsState.value === 'object'
           ? settingsState.value
           : {};
-        var pair = resolveVisionModePair(state.groups, state.current, visionConfig);
+        // A Vision click may briefly drive this same Host directory through
+        // selecting -> idle/loading while its projection is recomputed. Smooth
+        // only that owned transaction: unrelated Host reloads (connection,
+        // adapters, settings, credentials) must keep their loading authority.
+        var usable = !!(state.current &&
+          typeof state.current.provider === 'string' && state.current.provider !== '') &&
+          Array.isArray(state.groups) && state.groups.length > 0;
+        var settling = state.status === 'idle' || state.status === 'loading';
+        var livePair = resolveVisionModePair(state.groups, state.current, visionConfig);
+        var complete = usable && livePair.mode !== 'unavailable';
+        var settledMode = React.useRef(null);
+        var toggleTransition = React.useRef(null);
+        if (settledMode.current && settledMode.current.directory !== directory) settledMode.current = null;
+        if (toggleTransition.current && toggleTransition.current.directory !== directory) toggleTransition.current = null;
+        if (complete) settledMode.current = { directory: directory, mode: livePair.mode };
+        var transition = toggleTransition.current;
+        if (transition && state.status === 'selecting') {
+          var pending = state.pending;
+          var matchesPending = !!(pending &&
+            pending.provider === transition.target.provider &&
+            pending.model === transition.target.model &&
+            pending.reasoningEffort === transition.target.reasoningEffort);
+          if (matchesPending) transition.seenSelecting = true;
+          else toggleTransition.current = null;
+        }
+        transition = toggleTransition.current;
+        var ownSettling = !!(transition && transition.seenSelecting && settling && settledMode.current);
+        if (!ownSettling && transition && state.status !== 'selecting' &&
+          (state.status === 'error' || state.status === 'ready')) {
+          toggleTransition.current = null;
+        }
+        var pair = ownSettling ? { mode: settledMode.current.mode } : livePair;
         var active = pair.mode === 'on';
         var toastState = React.useState(null);
         var toast = toastState[0];
         var setToast = toastState[1];
         var busy = state.status === 'selecting';
-        var loading = state.status === 'idle' || state.status === 'loading';
+        var loading = settling;
         var removed = props.session && props.session.removed === true;
-        var disabled = props.available !== true || removed || busy || loading || pair.mode === 'unavailable';
+        var disabled = props.available !== true || removed || busy || loading || livePair.mode === 'unavailable';
         var t = typeof props.t === 'function' ? props.t : fallbackTranslate(active);
-        var title = busy
+        var title = busy || ownSettling
           ? t('switching')
           : loading
             ? t('loading')
-            : pair.mode === 'unavailable'
+            : livePair.mode === 'unavailable'
               ? t('unavailable')
               : active ? t('disable') : t('enable');
         var style = {
@@ -1093,7 +1125,7 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
           lineHeight: 1.4,
           fontWeight: active ? 650 : 500,
           cursor: disabled ? 'default' : 'pointer',
-          opacity: disabled && (pair.mode === 'unavailable' || loading) ? 0.45 : 1,
+          opacity: disabled && !ownSettling && (livePair.mode === 'unavailable' || loading) ? 0.45 : 1,
           whiteSpace: 'nowrap'
         };
 
@@ -1120,25 +1152,52 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
           'data-vision-router-mode-toggle': 'true',
           'aria-pressed': active,
           'aria-label': title,
+          'aria-busy': busy || loading,
           title: title,
           disabled: disabled,
           style: style,
           onClick: function() {
             if (disabled || !pair.target || typeof props.select !== 'function') return;
+            var target = pair.target;
+            toggleTransition.current = {
+              directory: directory,
+              target: target,
+              seenSelecting: false
+            };
             setToast(null);
-            void props.select(pair.target).then(function(accepted){
-              if (!accepted) announceRejectedSelection();
+            void props.select(target).then(function(accepted){
+              if (!accepted) {
+                toggleTransition.current = null;
+                announceRejectedSelection();
+                return;
+              }
+              var latest;
+              try { latest = store && typeof store.getSnapshot === 'function' ? store.getSnapshot() : undefined; } catch (_) {}
+              if (!latest || (latest.status !== 'selecting' && latest.status !== 'idle' && latest.status !== 'loading')) {
+                toggleTransition.current = null;
+              }
             });
           }
         },
-          React.createElement('span', { 'aria-hidden': 'true', style: { fontSize: 13, lineHeight: 1 } }, '👁'),
-          React.createElement('span', null, t('label')),
-          active
-            ? React.createElement('span', {
-                'aria-hidden': 'true',
-                style: { fontSize: 12, lineHeight: 1, fontWeight: 800, marginLeft: 1 }
-              }, '✓')
-            : null
+          // One fixed 14px leading slot carries the state icon: the eye when the
+          // route is ordinary, the check when Vision is on. Appending the check
+          // only while active changed the chip width by ~18px and reflowed the
+          // composer row; reserving trailing space kept the width but left the
+          // inactive chip visually off-centre.
+          React.createElement('span', {
+            'aria-hidden': 'true',
+            style: {
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flex: '0 0 auto',
+              width: 14,
+              height: 14,
+              fontSize: 13,
+              lineHeight: 1
+            }
+          }, active ? '✓' : '👁'),
+          React.createElement('span', null, t('label'))
         );
 
         var toastNode = toast
@@ -1183,7 +1242,7 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
                   }
                   try {
                     return Promise.resolve(directory.select(selection)).then(
-                      function(){ return true; },
+                      function(result){ return !result || result.ok !== false; },
                       function(){ return false; }
                     );
                   } catch (_) {
@@ -1304,23 +1363,14 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
 })();`
 
 export function injectClientPresentationBoundary(html) {
-  if (typeof html !== 'string' || html.includes(CLIENT_PRESENTATION_MARK)) return html
-  const safe = CLIENT_PRESENTATION_PRELUDE.replace(/<\/script/gi, '<\\/script')
-  const script = `<script ${CLIENT_PRESENTATION_MARK}>${safe}</script>`
-  // DSH's client-modules index tap prepends the queue-mode loader bootstrap at
-  // <head>. Run after that parser bootstrap so we can wrap both load() and the
-  // later create() transition. The create wrapper re-applies the boundary when
-  // rc.8 replaces loader.load while entering live mode.
-  const closeHead = html.indexOf('</head>')
-  if (closeHead !== -1) return `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
-  return `${html}${script}`
+  return injectClientCarrierHtml(html, CLIENT_PRESENTATION_MARK, CLIENT_PRESENTATION_PRELUDE)
 }
 
 export function installClientPresentationBoundary(ctx) {
-  ctx?.inject?.(['webServer'], (webCtx) => {
-    webCtx.effect(
-      () => webCtx.webServer.tapIndex(injectClientPresentationBoundary),
-      'vision-router: client presentation boundary',
-    )
+  installClientScriptCarriers(ctx, {
+    marker: CLIENT_PRESENTATION_MARK,
+    prelude: CLIENT_PRESENTATION_PRELUDE,
+    label: 'vision-router: client presentation boundary',
+    injectHtml: injectClientPresentationBoundary,
   })
 }

package/lib/client-presentation-boundary.js

@@ -1,4 +1,4 @@
-import { htmlHasScriptMarker } from './html-script-marker.js'
+import { injectClientCarrierHtml, installClientScriptCarriers } from './client-script-carrier.js'
 import {
   CLIENT_PRESENTATION_PRELUDE as BASE_CLIENT_PRESENTATION_PRELUDE,
   resolveVisionModePair,
@@ -10,39 +10,50 @@ import { installVisionModelVisibilityBoundary } from './vision-model-visibility-
 
 const CLIENT_PRESENTATION_MARK = 'data-vision-router-presentation-boundary'
 
-const VISION_TOGGLE_TEXT_GLYPH = String.raw`          React.createElement('span', { 'aria-hidden': 'true', style: { fontSize: 13, lineHeight: 1 } }, '👁'),
-          React.createElement('span', null, t('label')),
-          active
-            ? React.createElement('span', {
-                'aria-hidden': 'true',
-                style: { fontSize: 12, lineHeight: 1, fontWeight: 800, marginLeft: 1 }
-              }, '✓')
-            : null`
-
-const VISION_TOGGLE_FIXED_SVG = String.raw`          React.createElement('svg', {
-            width: 14,
-            height: 14,
-            viewBox: '0 0 14 14',
-            fill: 'none',
+const VISION_TOGGLE_TEXT_GLYPH = String.raw`          // One fixed 14px leading slot carries the state icon: the eye when the
+          // route is ordinary, the check when Vision is on. Appending the check
+          // only while active changed the chip width by ~18px and reflowed the
+          // composer row; reserving trailing space kept the width but left the
+          // inactive chip visually off-centre.
+          React.createElement('span', {
+            'aria-hidden': 'true',
+            style: {
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flex: '0 0 auto',
+              width: 14,
+              height: 14,
+              fontSize: 13,
+              lineHeight: 1
+            }
+          }, active ? '✓' : '👁'),
+          React.createElement('span', null, t('label'))`
+
+const VISION_TOGGLE_FIXED_SVG = String.raw`          // One fixed 14px leading slot carries the state icon: the eye when the
+          // route is ordinary, the check when Vision is on. Appending the check
+          // only while active changed the chip width by ~18px and reflowed the
+          // composer row; reserving trailing space kept the width but left the
+          // inactive chip visually off-centre.
+          React.createElement('span', {
             'aria-hidden': 'true',
-            focusable: 'false',
-            style: { display: 'block', flex: '0 0 auto' }
-          }, React.createElement('path', {
-            fillRule: 'evenodd',
-            clipRule: 'evenodd',
-            d: 'M7 2.25c-2.84 0-5.04 1.69-6.25 4.25a1.15 1.15 0 0 0 0 1C1.96 10.06 4.16 11.75 7 11.75s5.04-1.69 6.25-4.25a1.15 1.15 0 0 0 0-1C12.04 3.94 9.84 2.25 7 2.25Zm0 1.25c2.16 0 3.96 1.21 5.05 3.5C10.96 9.29 9.16 10.5 7 10.5S3.04 9.29 1.95 7C3.04 4.71 4.84 3.5 7 3.5Zm0 1.25A2.25 2.25 0 1 0 7 9.25a2.25 2.25 0 0 0 0-4.5Zm0 1.25a1 1 0 1 1 0 2 1 1 0 0 1 0-2Z',
-            fill: 'currentColor'
-          })),
-          React.createElement('span', null, t('label')),
-          active
+            style: {
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flex: '0 0 auto',
+              width: 14,
+              height: 14
+            }
+          }, active
             ? React.createElement('svg', {
-                width: 12,
-                height: 12,
+                width: 14,
+                height: 14,
                 viewBox: '0 0 14 14',
                 fill: 'none',
                 'aria-hidden': 'true',
                 focusable: 'false',
-                style: { display: 'block', flex: '0 0 auto', marginLeft: 1 }
+                style: { display: 'block', flex: '0 0 auto' }
               }, React.createElement('path', {
                 d: 'M2.75 7.15 5.6 10 11.25 4.35',
                 stroke: 'currentColor',
@@ -50,7 +61,21 @@ const VISION_TOGGLE_FIXED_SVG = String.raw`          React.createElement('svg',
                 strokeLinecap: 'round',
                 strokeLinejoin: 'round'
               }))
-            : null`
+            : React.createElement('svg', {
+                width: 14,
+                height: 14,
+                viewBox: '0 0 14 14',
+                fill: 'none',
+                'aria-hidden': 'true',
+                focusable: 'false',
+                style: { display: 'block', flex: '0 0 auto' }
+              }, React.createElement('path', {
+                fillRule: 'evenodd',
+                clipRule: 'evenodd',
+                d: 'M7 2.25c-2.84 0-5.04 1.69-6.25 4.25a1.15 1.15 0 0 0 0 1C1.96 10.06 4.16 11.75 7 11.75s5.04-1.69 6.25-4.25a1.15 1.15 0 0 0 0-1C12.04 3.94 9.84 2.25 7 2.25Zm0 1.25c2.16 0 3.96 1.21 5.05 3.5C10.96 9.29 9.16 10.5 7 10.5S3.04 9.29 1.95 7C3.04 4.71 4.84 3.5 7 3.5Zm0 1.25A2.25 2.25 0 1 0 7 9.25a2.25 2.25 0 0 0 0-4.5Zm0 1.25a1 1 0 1 1 0 2 1 1 0 0 1 0-2Z',
+                fill: 'currentColor'
+              }))),
+          React.createElement('span', null, t('label'))`
 
 const BITMAP_LIMITS_BASE = String.raw`      var maxBitmapSourceBytes = 64 * 1024 * 1024;
       var maxBitmapDimension = 10000;
@@ -187,20 +212,15 @@ export {
 }
 
 export function injectClientPresentationBoundary(html) {
-  if (typeof html !== 'string' || htmlHasScriptMarker(html, CLIENT_PRESENTATION_MARK)) return html
-  const safe = CLIENT_PRESENTATION_PRELUDE.replace(/<\/script/gi, '<\\/script')
-  const script = `<script ${CLIENT_PRESENTATION_MARK}>${safe}</script>`
-  const closeHead = html.indexOf('</head>')
-  if (closeHead !== -1) return `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
-  return `${html}${script}`
+  return injectClientCarrierHtml(html, CLIENT_PRESENTATION_MARK, CLIENT_PRESENTATION_PRELUDE)
 }
 
 export function installClientPresentationBoundary(ctx) {
-  ctx?.inject?.(['webServer'], (webCtx) => {
-    webCtx.effect(
-      () => webCtx.webServer.tapIndex(injectClientPresentationBoundary),
-      'vision-router: client presentation boundary',
-    )
+  installClientScriptCarriers(ctx, {
+    marker: CLIENT_PRESENTATION_MARK,
+    prelude: CLIENT_PRESENTATION_PRELUDE,
+    label: 'vision-router: client presentation boundary',
+    injectHtml: injectClientPresentationBoundary,
   })
   // Keep Host-version compatibility in its own capability-detected prelude.
   // This lets the large legacy client factory stay byte-stable while alpha/new

package/lib/client-script-carrier.js

@@ -0,0 +1,90 @@
+import { htmlHasScriptMarker } from './html-script-marker.js'
+
+const CARRIER_REGISTRY = '__dshVisionRouterClientCarriers'
+
+function carrierKey(marker) {
+  const value = String(marker || 'vision-router-client-script')
+  return `vr:${value.replace(/^data-vision-router-/, '')}`
+}
+
+/**
+ * Wrap one browser prelude with a shared one-shot fence. Modern served-Web
+ * pages can receive both structured index rows and tapIndex HTML transforms,
+ * while Desktop/static carriers receive only the structured row. The fence
+ * keeps both delivery paths safe without relying on each prelude to implement
+ * its own duplicate-execution semantics.
+ */
+export function clientCarrierSource(marker, prelude) {
+  const key = JSON.stringify(carrierKey(marker))
+  return `(function(){\n  var root = window;\n  var registry = root.${CARRIER_REGISTRY};\n  if (!registry || typeof registry !== 'object') {\n    registry = Object.create(null);\n    try { Object.defineProperty(root, '${CARRIER_REGISTRY}', { value: registry, configurable: true }); }\n    catch (_) { root.${CARRIER_REGISTRY} = registry; }\n  }\n  var key = ${key};\n  if (registry[key]) return;\n  registry[key] = true;\n  try {\n${prelude}\n  } catch (error) {\n    try { delete registry[key]; } catch (_) { registry[key] = false; }\n    throw error;\n  }\n})();`
+}
+
+export function injectClientCarrierHtml(html, marker, prelude) {
+  const structuredMark = `/* ${marker} */`
+  if (typeof html !== 'string' || htmlHasScriptMarker(html, marker) || html.includes(structuredMark)) return html
+  const safe = clientCarrierSource(marker, prelude).replace(/<\/script/gi, '<\\/script')
+  const script = `<script ${marker}>${safe}</script>`
+  const closeHead = html.indexOf('</head>')
+  return closeHead === -1 ? `${html}${script}` : `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
+}
+
+
+export function injectClientStyleHtml(html, marker, css) {
+  if (typeof html !== 'string' || typeof marker !== 'string' || marker === '') return html
+  if (html.includes(`<style ${marker}>`)) return html
+  const style = `<style ${marker}>${String(css || '')}</style>`
+  const closeHead = html.indexOf('</head>')
+  return closeHead === -1 ? `${html}${style}` : `${html.slice(0, closeHead)}${style}${html.slice(closeHead)}`
+}
+
+export function appendStructuredClientStyle(table, marker, css) {
+  if (!Array.isArray(table) || typeof marker !== 'string' || marker === '') return false
+  const signature = `/* ${marker}:style */`
+  if (table.some((row) => row?.kind === 'style' && typeof row.text === 'string' && row.text.includes(signature))) return false
+  table.push({ kind: 'style', placement: 'head', text: `${signature}
+${String(css || '')}` })
+  return true
+}
+
+export function appendStructuredClientCarrier(table, marker, prelude) {
+  if (!Array.isArray(table)) return false
+  const signature = `/* ${marker} */`
+  if (table.some((row) => row?.kind === 'script' && typeof row.text === 'string' && row.text.includes(signature))) {
+    return false
+  }
+  table.push({
+    kind: 'script',
+    placement: 'head',
+    text: `${signature}\n${clientCarrierSource(marker, prelude)}`,
+  })
+  return true
+}
+
+/**
+ * Register the same client prelude on both supported browser carriers:
+ * - structured `webserver/index-inject` rows for Desktop/static shells;
+ * - `tapIndex()` HTML transforms for served-Web and older Hosts.
+ */
+export function installClientScriptCarriers(ctx, { marker, prelude, label, injectHtml, style }) {
+  if (!ctx || typeof ctx.inject !== 'function') return
+  ctx.inject(['webServer'], (webCtx) => {
+    if (typeof webCtx.on === 'function') {
+      webCtx.on('webserver/index-inject', (table) => {
+        if (style) appendStructuredClientStyle(table, style.marker || marker, style.text)
+        appendStructuredClientCarrier(table, marker, prelude)
+      })
+    }
+    if (typeof webCtx.effect === 'function' && webCtx.webServer?.tapIndex) {
+      const baseTransform = typeof injectHtml === 'function'
+        ? injectHtml
+        : (html) => injectClientCarrierHtml(html, marker, prelude)
+      const transform = style
+        ? (html) => baseTransform(injectClientStyleHtml(html, style.marker || marker, style.text))
+        : baseTransform
+      webCtx.effect(
+        () => webCtx.webServer.tapIndex(transform),
+        label,
+      )
+    }
+  })
+}