@mohou/host 1.0.20

package/src/compile/sheet.ts

@@ -0,0 +1,174 @@
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { compile } from '@tailwindcss/node'
+import { Scanner } from '@tailwindcss/oxide'
+import { appEntries } from '@mohou/contract'
+import { appCardCss } from '@mohou/app-view/css'
+
+import { readAutogen, sheetFile, writeAutogen } from './autogen.ts'
+import { CompileError } from './codes.ts'
+import { themeTokens } from '../theme/tokens.ts'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Compile one app with Tailwind. The Oxide scanner finds candidates. Host does not parse `className`.
+ * `@theme` only connects `themeTokens` to Tailwind color names.
+ * A matching `.autogen` stamp returns the file and does not keep the text.
+ * @param appDir - absolute app directory
+ */
+export async function compileAppStylesheet(appDir: string): Promise<string> {
+  const hit = await readAutogen(appDir, sheetFile)
+  if (hit !== undefined) return hit
+  await newest(appDir)
+  const built = await compileSources([appDir])
+  const author = await readFile(path.join(appDir, appEntries.stylesheet), 'utf8').catch(() => '')
+  const css = author.length === 0 ? `${built}\n${appCardCss}` : `${built}\n${appCardCss}\n${author}`
+  await writeAutogen(appDir, sheetFile, css).catch(() => undefined)
+  return css
+}
+
+/**
+ * Compile the panel document. Scans panel source and the UI kit. No author `ui.css`.
+ * @param panelDir - panel `src` directory
+ */
+export async function compilePanelStylesheet(panelDir: string): Promise<string> {
+  const built = await compileSources([panelDir], false)
+  return `${built}\n${panelLayoutCss}\n${appCardCss}`
+}
+
+const panelLayoutCss = [
+  'html,body,#root{height:100%;margin:0;overflow:hidden;}',
+  '#mma-host, #mma-host .overflow-auto, #mma-host .mma-frame{scrollbar-width:thin;scrollbar-color:color-mix(in oklch,var(--foreground) 28%,transparent) transparent;}',
+  '#mma-host::-webkit-scrollbar, #mma-host *::-webkit-scrollbar{-webkit-appearance:none;width:8px;height:8px;}',
+  '#mma-host::-webkit-scrollbar-track, #mma-host *::-webkit-scrollbar-track, #mma-host::-webkit-scrollbar-corner, #mma-host *::-webkit-scrollbar-corner{background:transparent;}',
+  '#mma-host::-webkit-scrollbar-thumb, #mma-host *::-webkit-scrollbar-thumb{background:color-mix(in oklch,var(--foreground) 28%,transparent);border:2px solid transparent;border-radius:999px;background-clip:padding-box;}',
+  '#mma-host{height:100%;min-height:0;overflow:hidden;display:flex;flex-direction:column;}',
+  '#mma-host.mma-command{background:radial-gradient(circle at 18% 0%,color-mix(in oklch,var(--foreground) 6%,transparent),transparent 32%),radial-gradient(circle at 100% 100%,color-mix(in oklch,var(--foreground) 5%,transparent),transparent 28%),var(--background);}',
+  '#mma-host .mma-chrome{position:relative;z-index:40;height:64px;display:flex;align-items:center;gap:12px;padding:0 24px;border-bottom:1px solid color-mix(in oklch,var(--foreground) 8%,transparent);background:color-mix(in oklch,var(--card) 72%,transparent);backdrop-filter:blur(20px) saturate(160%);}',
+  '#mma-host .mma-pill-rail{position:relative;display:flex;min-width:0;gap:8px;overflow-x:auto;padding:4px;border-radius:999px;border:1px solid color-mix(in oklch,var(--foreground) 8%,transparent);background:color-mix(in oklch,var(--foreground) 4%,transparent);scrollbar-width:none;}',
+  '#mma-host .mma-pill-rail::-webkit-scrollbar{display:none;height:0;}',
+  '#mma-host .mma-pill-glide{position:absolute;top:4px;left:0;height:calc(100% - 8px);border-radius:999px;background:var(--card);box-shadow:0 4px 12px color-mix(in oklch,var(--foreground) 8%,transparent);transition:transform .42s cubic-bezier(.23,1,.32,1),width .42s cubic-bezier(.23,1,.32,1);pointer-events:none;}',
+  '#mma-host .mma-pill{position:relative;z-index:1;display:inline-flex;max-width:11rem;shrink:0;align-items:center;gap:6px;border-radius:999px;padding:6px 14px;font-size:13px;font-weight:600;color:var(--muted-foreground);transition:color .22s ease;}',
+  '#mma-host .mma-pill[data-active="1"]{color:var(--foreground);}',
+  '[data-mode="dark"] #mma-host .mma-pill-glide{background:color-mix(in oklch,var(--foreground) 10%,transparent);box-shadow:inset 0 1px 0 color-mix(in oklch,var(--foreground) 16%,transparent);}',
+  '#mma-host .mma-toolbar{display:flex;align-items:center;gap:2px;padding:4px;border-radius:16px;border:1px solid color-mix(in oklch,var(--foreground) 8%,transparent);background:color-mix(in oklch,var(--foreground) 4%,transparent);}',
+  '#mma-host .mma-toolbar-rule{width:1px;height:14px;margin:0 4px;flex:none;background:color-mix(in oklch,var(--foreground) 18%,transparent);}',
+  '#mma-host .mma-tip{position:relative;display:inline-flex;align-items:center;}',
+  '#mma-host .mma-tip-label{position:absolute;top:calc(100% + 6px);left:50%;z-index:60;width:max-content;max-width:16rem;transform:translateX(-50%);padding:5px 8px;border-radius:8px;border:1px solid var(--border);background:var(--card);color:var(--card-foreground,var(--foreground));font-size:12px;font-weight:600;letter-spacing:0;line-height:1.3;text-align:center;text-transform:none;white-space:normal;opacity:0;pointer-events:none;box-shadow:var(--shadow);transition:opacity .12s ease;}',
+  '#mma-host .mma-tip[data-align="end"] .mma-tip-label{left:auto;right:0;transform:none;}',
+  '#mma-host .mma-tip:hover .mma-tip-label,#mma-host .mma-tip:focus-within .mma-tip-label{opacity:1;}',
+  '#mma-host .mma-desk{position:relative;display:flex;max-width:min(28rem,42vw);align-items:center;gap:2px;overflow-x:auto;padding:4px;border-radius:16px;border:1px solid color-mix(in oklch,var(--foreground) 8%,transparent);background:color-mix(in oklch,var(--foreground) 4%,transparent);backdrop-filter:blur(16px) saturate(160%);scrollbar-width:none;}',
+  '#mma-host .mma-desk::-webkit-scrollbar{display:none;height:0;}',
+  '#mma-host .mma-desk.mma-desk-fit{max-width:none;}',
+  '#mma-host .mma-desk-pill{position:absolute;top:4px;left:0;height:calc(100% - 8px);border-radius:12px;background:var(--card);box-shadow:0 8px 18px -10px color-mix(in oklch,var(--foreground) 28%,transparent);transition:transform .42s cubic-bezier(.23,1,.32,1),width .42s cubic-bezier(.23,1,.32,1);pointer-events:none;}',
+  '#mma-host .mma-desk-item{position:relative;z-index:1;display:inline-flex;height:32px;max-width:11rem;flex:0 0 auto;align-items:center;gap:6px;overflow:hidden;border-radius:12px;padding:0 12px;font-size:13px;font-weight:600;color:var(--muted-foreground);transition:color .22s ease;}',
+  '#mma-host .mma-desk-mark{display:inline-flex;box-sizing:border-box;min-width:18px;height:18px;flex:none;align-items:center;justify-content:center;padding:0 3px;border-radius:4px;background:color-mix(in oklch,var(--foreground) 12%,transparent);font-size:9px;font-weight:700;letter-spacing:0;line-height:1;text-align:center;}',
+  '#mma-host .mma-desk-item[data-on="1"] .mma-desk-mark{background:color-mix(in oklch,var(--foreground) 18%,transparent);}',
+  '#mma-host .mma-desk-name{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}',
+  '#mma-host .mma-desk-item[data-on="1"]{color:var(--foreground);}',
+  '[data-mode="dark"] #mma-host .mma-desk-pill{background:color-mix(in oklch,var(--foreground) 10%,transparent);box-shadow:inset 0 1px 0 color-mix(in oklch,var(--foreground) 16%,transparent);}',
+  '#mma-host .mma-status{display:flex;flex:none;align-items:center;gap:16px;padding:6px 24px;border-bottom:1px solid color-mix(in oklch,var(--foreground) 6%,transparent);font-size:10px;font-weight:600;line-height:1.2;letter-spacing:.12em;text-transform:uppercase;color:color-mix(in oklch,var(--foreground) 55%,transparent);}',
+  '#mma-host .mma-status .mma-tip{margin-left:auto;}',
+  '#mma-host .mma-status-action{display:inline-flex;align-items:center;gap:6px;padding:2px 4px 2px 8px;border:1px solid transparent;border-radius:999px;color:var(--foreground);font:inherit;font-size:11px;font-weight:600;line-height:1.2;letter-spacing:0;text-transform:none;cursor:pointer;}',
+  '#mma-host .mma-status-action:hover{border:1px solid color-mix(in oklch,var(--foreground) 10%,transparent);background:var(--card);}',
+  '#mma-host .mma-status-split{width:1px;height:12px;flex:none;background:color-mix(in oklch,var(--foreground) 12%,transparent);}',
+  '#mma-host .mma-status-more{color:var(--muted-foreground);}',
+  '#mma-host .mma-status-go{display:inline-flex;width:16px;height:16px;flex:none;align-items:center;justify-content:center;border-radius:5px;background:color-mix(in oklch,var(--foreground) 8%,transparent);}',
+  '#mma-host .mma-pane{animation:mma-pane-in .42s cubic-bezier(.16,1,.3,1) both;}',
+  '@keyframes mma-pane-in{from{opacity:0;transform:translateY(12px)}to{opacity:1;transform:none}}',
+  '@media (prefers-reduced-motion:reduce){#mma-host .mma-pane{animation:none}}',
+  '#mma-host .mma-dot{width:6px;height:6px;border-radius:50%;color:color-mix(in oklch,oklch(0.55 0.05 150) 62%,var(--muted-foreground));background:currentColor;box-shadow:0 0 6px currentColor;}',
+  '#mma-host .mma-dot[data-status="failed"]{color:color-mix(in oklch,oklch(0.62 0.06 78) 58%,var(--muted-foreground));}',
+  '#mma-host .mma-dot[data-status="down"]{color:color-mix(in oklch,var(--destructive) 38%,var(--muted-foreground));}',
+  '#mma-host .mma-library{container-type:inline-size;padding:32px 32px 40px;}',
+  '#mma-host .mma-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));align-items:start;gap:24px;}',
+  '#mma-host .mma-grid:has([data-card="glass"]){align-items:stretch;}',
+  '#mma-host .mma-grid:has([data-card="glass"])>*{display:flex;height:100%;min-height:100%;min-width:0;flex-direction:column;}',
+  '#mma-host .mma-grid:has([data-card="glass"])>* .mma-slot{flex:1;min-height:0;height:100%;}',
+  '[data-mode="dark"] #mma-host .mma-chrome{background:color-mix(in oklch,var(--foreground) 4%,transparent);border-color:color-mix(in oklch,var(--foreground) 12%,transparent);}',
+  '#mma-host .pointer-events-none iframe{pointer-events:none;}',
+  '#mma-host .mma-stage{display:flex;min-height:0;flex:1;}',
+  '#mma-host .mma-frame{min-height:0;flex:1;overflow:hidden;}',
+  '#mma-host .mma-app-frame{padding:16px;}',
+  '#mma-host .mma-app-frame>.mma-frame{border-radius:24px;border:1px solid color-mix(in oklch,var(--foreground) 10%,transparent);background:var(--card);box-shadow:0 20px 40px -18px color-mix(in oklch,var(--foreground) 18%,transparent);}',
+  '#mma-host .mma-app-frame>.mma-frame:has(>.mma-library){overflow:auto;background:color-mix(in oklch,var(--card) 36%,transparent);backdrop-filter:blur(18px) saturate(160%);}',
+  '[data-mode="dark"] #mma-host .mma-app-frame>.mma-frame:has(>.mma-library){background:color-mix(in oklch,var(--foreground) 5%,transparent);}',
+].join('\n')
+
+async function compileSources(dirs: readonly string[], includeKit = true): Promise<string> {
+  const compiler = await compile(inputCss(dirs, includeKit), {
+    base: hostPackageDir(),
+    onDependency() {},
+  })
+  return compiler.build(new Scanner({ sources: compiler.sources }).scan())
+}
+
+function inputCss(dirs: readonly string[], includeKit = true): string {
+  const roots = includeKit ? [kitSourceDir(), viewSourceDir(), ...dirs] : [viewSourceDir(), ...dirs]
+  const sources = roots.map(dir => `@source ${JSON.stringify(`${dir}/**/*.{tsx,ts,jsx,js}`)};`)
+  const colors = themeTokens.flatMap((token) => {
+    if (token === 'radius' || token === 'shadow') return []
+    return [`  --color-${token}: var(--${token});`]
+  })
+  return [
+    '@import "tailwindcss" source(none);',
+    '@import "tw-animate-css";',
+    ...sources,
+    '@custom-variant dark (&:where([data-mode="dark"], [data-mode="dark"] *));',
+    ':root { --primary-svg-color: var(--primary); }',
+    '@theme inline {',
+    ...colors,
+    '  --radius-sm: calc(var(--radius) * 0.6);',
+    '  --radius-md: calc(var(--radius) * 0.8);',
+    '  --radius-lg: var(--radius);',
+    '  --radius-xl: calc(var(--radius) * 1.4);',
+    '  --radius-2xl: calc(var(--radius) * 1.8);',
+    '  --radius-3xl: calc(var(--radius) * 2.2);',
+    '  --radius-4xl: calc(var(--radius) * 2.6);',
+    '  --font-sans: ui-sans-serif, system-ui, sans-serif;',
+    '}',
+    '@layer base {',
+    '  * { @apply border-border outline-ring/50; }',
+    '  html, body, #root { height: 100%; margin: 0; }',
+    '  body { @apply bg-background text-foreground; }',
+    '}',
+    '',
+  ].join('\n')
+}
+
+function kitSourceDir(): string {
+  return path.dirname(require.resolve('@mohou/ui'))
+}
+
+function viewSourceDir(): string {
+  return path.dirname(require.resolve('@mohou/app-view'))
+}
+
+function hostPackageDir(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+}
+
+async function newest(appDir: string): Promise<number> {
+  const names = await readdir(appDir).catch((error: unknown) => {
+    if (isCode(error, 'ENOENT')) throw new CompileError('ui-invalid', 'app stylesheet is missing')
+    throw error
+  })
+  let max = 0
+  for (const name of names) {
+    if (name === 'node_modules' || name.startsWith('.')) continue
+    const file = path.join(appDir, name)
+    const info = await stat(file).catch(() => undefined)
+    if (info === undefined) continue
+    if (info.isDirectory()) max = Math.max(max, await newest(file))
+    else max = Math.max(max, info.mtimeMs)
+  }
+  return max
+}
+
+function isCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === code
+}

package/src/compile/wrapper.ts

@@ -0,0 +1,297 @@
+import { appResource, httpLayout } from '../http/layout.ts'
+import { admitAssetRef, assetInvalidCode } from './asset-path.ts'
+
+/** Codes the host wrapper emits in the iframe. Callers match `code`. */
+export const hostWrapperCodes = {
+  outside: 'call-outside-wrapper',
+  unmounted: 'call-unmounted',
+  assetInvalid: assetInvalidCode,
+} as const
+
+/** Names the runner and the future kit share. Spell them here. */
+export const hostWrapperBinding = {
+  hook: 'useApp',
+  host: 'miniAppHost',
+} as const
+
+interface WrapperDeps {
+  readonly outsideCode: string
+  readonly unmountedCode: string
+  readonly hook: string
+  readonly host: string
+  readonly appId: string
+  readonly callUrl: string
+  readonly assetRoot: string
+  admitAssetRef(raw: string): string
+}
+
+interface WrapperMessage {
+  source: unknown
+  origin: string
+  data: unknown
+}
+
+interface WrapperWindow extends HostWindow {
+  parent: unknown
+  location?: { reload(): void }
+  addEventListener(type: string, listener: (event: WrapperMessage) => void): void
+}
+
+interface HostWindow {
+  [key: string]: unknown
+}
+
+/**
+ * Install `useApp`. `call` throws outside the host wrapper.
+ * The handle is one object for the life of the document, so an effect may depend on `call`.
+ * Inside the wrapper `call` posts to the loopback call route and reads one JSON result.
+ * `streamCall` is the same route with `accept: text/event-stream`. The body is that call's events.
+ * A parent-posted author event reaches `on` and `onAny`. A gap reaches `onAny` only.
+ * Ping and the retry hint stay off this hook. No imports.
+ * @param deps - codes and the binding names
+ */
+export function installHostWrapper(deps: WrapperDeps): void {
+  const realm = globalThis as unknown as { window?: WrapperWindow }
+  let win: WrapperWindow
+  if (realm.window !== undefined) win = realm.window
+  else win = globalThis
+  let parentOrigin: string | undefined
+  let inside = 0
+  let mounted = false
+  const named = new Map<string, Array<(data: unknown) => void>>()
+  const any: Array<(event: { name: string; data: unknown }) => void> = []
+
+  function fail(code: string, message: string): Error {
+    const error = new Error(message) as Error & { code: string }
+    error.code = code
+    return error
+  }
+
+  function readStreamFrame(line: string, code: string): object {
+    const raw = line.slice(5).trim()
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw fail(code, 'call failed')
+      return parsed
+    } catch (error) {
+      if (error instanceof Error && 'code' in error) throw error
+      throw fail(code, raw.length > 0 ? raw : 'call failed')
+    }
+  }
+
+  const handle = {
+    call(method: string, args?: unknown) {
+      if (!mounted && inside === 0) throw fail(deps.outsideCode, 'useApp() call is outside the host wrapper')
+      return fetch(deps.callUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ appId: deps.appId, method, args }),
+      }).then(async (response) => {
+        const body = await response.json() as { ok?: boolean; value?: unknown; error?: string }
+        if (body.ok !== true) throw fail(deps.unmountedCode, typeof body.error === 'string' ? body.error : 'call failed')
+        return body.value
+      })
+    },
+    streamCall(method: string, args?: unknown) {
+      if (!mounted && inside === 0) throw fail(deps.outsideCode, 'useApp() call is outside the host wrapper')
+      return openStream(method, args)
+    },
+    on(name: string, cb: (data: unknown) => void) {
+      const list = named.get(name) ?? []
+      list.push(cb)
+      named.set(name, list)
+      return () => {
+        const next = (named.get(name) ?? []).filter((item) => {
+          return item !== cb
+        })
+        named.set(name, next)
+      }
+    },
+    onAny(cb: (event: { name: string; data: unknown }) => void) {
+      any.push(cb)
+      return () => {
+        const index = any.indexOf(cb)
+        if (index >= 0) any.splice(index, 1)
+      }
+    },
+    resolveAssetUrl(path: string) {
+      const inner = deps.admitAssetRef(path)
+      return `${deps.assetRoot}/${inner.split('/').map(encodeURIComponent).join('/')}`
+    },
+  }
+
+  function openStream(method: string, args: unknown) {
+    const queued: unknown[] = []
+    let waiting: { resolve: (step: IteratorResult<unknown>) => void; reject: (error: unknown) => void } | undefined
+    let settled = false
+    let failure: unknown
+    let started = false
+    let resolveText: (value: unknown) => void
+    let rejectText: (error: unknown) => void
+    const text = new Promise<unknown>((resolve, reject) => {
+      resolveText = resolve
+      rejectText = reject
+    })
+    void text.catch(() => undefined)
+    const push = (value: unknown): void => {
+      if (waiting !== undefined) {
+        const resume = waiting
+        waiting = undefined
+        resume.resolve({ value, done: false })
+        return
+      }
+      queued.push(value)
+    }
+    const close = (): void => {
+      const resume = waiting
+      waiting = undefined
+      if (resume === undefined) return
+      if (failure instanceof Error) resume.reject(failure)
+      else resume.resolve({ value: undefined, done: true })
+    }
+    const start = (): void => {
+      if (started) return
+      started = true
+      readFrames(method, args, push).then((value) => {
+        settled = true
+        resolveText(value)
+        close()
+      }, (error: unknown) => {
+        settled = true
+        failure = error
+        rejectText(error)
+        close()
+      })
+    }
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<unknown> {
+        return {
+          next() {
+            start()
+            if (queued.length > 0) return Promise.resolve({ value: queued.shift(), done: false as const })
+            if (failure !== undefined) return Promise.reject(failure instanceof Error ? failure : new Error('call failed'))
+            if (settled) return Promise.resolve({ value: undefined, done: true as const })
+            return new Promise((resolve, reject) => {
+              waiting = { resolve, reject }
+            })
+          },
+        }
+      },
+      then(onFulfilled?: (value: unknown) => unknown, onRejected?: (error: unknown) => unknown) {
+        start()
+        return text.then(onFulfilled, onRejected)
+      },
+    }
+  }
+
+  async function readFrames(method: string, args: unknown, push: (value: unknown) => void): Promise<unknown> {
+    const response = await fetch(deps.callUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
+      body: JSON.stringify({ appId: deps.appId, method, args }),
+    })
+    const kind = response.headers.get('content-type') ?? ''
+    if (!response.ok || !kind.includes('text/event-stream') || response.body === null) {
+      const body = await response.json() as { error?: string }
+      throw fail(deps.unmountedCode, typeof body.error === 'string' ? body.error : 'call failed')
+    }
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let pending = ''
+    let returned: unknown
+    for (;;) {
+      const step = await reader.read()
+      if (step.done) return returned
+      pending += decoder.decode(step.value, { stream: true })
+      let split = pending.indexOf('\n\n')
+      while (split >= 0) {
+        const block = pending.slice(0, split)
+        pending = pending.slice(split + 2)
+        const line = block.split('\n').find(item => item.startsWith('data:'))
+        if (line !== undefined) {
+          const frame = readStreamFrame(line, deps.unmountedCode)
+          if ('error' in frame && typeof frame.error === 'string') throw fail(deps.unmountedCode, frame.error)
+          if ('return' in frame) returned = frame.return
+          else if ('value' in frame) push(frame.value)
+        }
+        split = pending.indexOf('\n\n')
+      }
+    }
+  }
+
+  function useApp(): typeof handle {
+    return handle
+  }
+
+  function runInside<T>(render: () => T): T {
+    mounted = true
+    inside += 1
+    try {
+      return render()
+    } finally {
+      inside -= 1
+    }
+  }
+
+  win[deps.hook] = useApp
+  win[deps.host] = { useApp, runInside }
+  win.addEventListener('message', (event) => {
+    if (event.source !== win.parent) return
+    if (parentOrigin === undefined) parentOrigin = event.origin
+    if (event.origin !== parentOrigin) return
+    if (isReload(event.data)) {
+      win.location?.reload()
+      return
+    }
+    deliver(event.data)
+  })
+
+  function isReload(value: unknown): boolean {
+    return typeof value === 'object'
+      && value !== null
+      && 'type' in value
+      && value.type === 'app:reload'
+      && 'appId' in value
+      && value.appId === deps.appId
+  }
+
+  function deliver(value: unknown): void {
+    if (typeof value !== 'object' || value === null) return
+    if (!('appId' in value) || value.appId !== deps.appId) return
+    if ('type' in value && value.type === 'app:gap') {
+      for (const cb of [...any]) cb({ name: '*', data: { gap: true } })
+      return
+    }
+    if (!('name' in value) || typeof value.name !== 'string') return
+    if (!('seq' in value) || typeof value.seq !== 'number') return
+    const data = 'data' in value ? value.data : undefined
+    for (const [name, list] of named) {
+      if (name !== '*' && name !== value.name) continue
+      for (const cb of [...list]) cb(data)
+    }
+    for (const cb of [...any]) cb({ name: value.name, data })
+  }
+}
+
+const wrapperHelpers = new Set(['__name'])
+
+/** Source the runner inlines before the app module. */
+export function renderHostWrapper(appId: string, callUrl = httpLayout.call): string {
+  const deps = {
+    outsideCode: hostWrapperCodes.outside,
+    unmountedCode: hostWrapperCodes.unmounted,
+    hook: hostWrapperBinding.hook,
+    host: hostWrapperBinding.host,
+    appId,
+    callUrl,
+    assetRoot: appResource(appId, httpLayout.assets),
+  }
+  const source = `{\nconst __name = (target) => target;\nconst admitAssetRef = ${admitAssetRef.toString()};\n(${installHostWrapper.toString()})(Object.assign(${JSON.stringify(deps)}, { admitAssetRef }))\n}`
+  for (const match of source.matchAll(/\b(__[A-Za-z]+)\s*\(/g)) {
+    const name = match[1]
+    if (name !== undefined && !wrapperHelpers.has(name)) {
+      throw new Error(`host wrapper helper is not declared: ${name}`)
+    }
+  }
+  return source
+}

package/src/credentials/codes.ts

@@ -0,0 +1,26 @@
+/** Codes the credential provider emits. Callers match `code`. */
+
+export const credentialCodes = [
+  'credential-invalid',
+  'credential-unreadable',
+  'credential-duplicate',
+  'credential-write-unavailable',
+] as const
+
+export type CredentialCode = (typeof credentialCodes)[number]
+
+/** A credential read failed. The file is unchanged. */
+export class CredentialError extends Error {
+  readonly code: CredentialCode
+
+  /**
+   * @param code - one of {@link credentialCodes}
+   * @param message - human text; not the match key. Never includes a secret.
+   * @param options - optional `cause`
+   */
+  constructor(code: CredentialCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'CredentialError'
+    this.code = code
+  }
+}

package/src/credentials/create.ts

@@ -0,0 +1,69 @@
+import { CredentialError } from './codes.ts'
+import { createFileCredentials } from './file.ts'
+import { admitCredentialName, cannotWrite, emptyCredentials, type CredentialListing, type CredentialProvider } from './provider.ts'
+
+/** Sources this package knows how to open. A later source adds one member. */
+export const credentialSourceKinds = ['builtin-json'] as const
+
+export type CredentialSourceKind = (typeof credentialSourceKinds)[number]
+
+/** JSON file. The path is this kind's target, not a field of every source. */
+export interface BuiltinJsonCredentialSource {
+  readonly kind: 'builtin-json'
+  readonly file: string
+}
+
+/** One source spec. Each kind carries its own target. */
+export type CredentialSource = BuiltinJsonCredentialSource
+
+const openers: {
+  readonly [Kind in CredentialSourceKind]: (source: Extract<CredentialSource, { kind: Kind }>) => CredentialProvider
+} = {
+  'builtin-json': source => createFileCredentials(source.file),
+}
+
+/**
+ * One read port over every source. Each kind carries its own target.
+ * The same name in two sources emits `credential-duplicate`. No source wins silently.
+ * An empty list is `emptyCredentials`.
+ * @param sources - source specs. Opening happens here, not at the call site.
+ */
+export function createCredentials(sources: readonly CredentialSource[]): CredentialProvider {
+  if (sources.length === 0) return emptyCredentials()
+  return combineCredentials(sources.map(source => openers[source.kind](source)))
+}
+
+function combineCredentials(providers: readonly CredentialProvider[]): CredentialProvider {
+  // One store owns writes: the first source that accepts them. With one source that is unambiguous,
+  // and a second read-only source cannot silently take a write meant for the first.
+  const writer = providers.find(provider => provider.writable)
+  return {
+    writable: writer !== undefined,
+    async list() {
+      const rows = await Promise.all(providers.map(provider => provider.list()))
+      const seen = new Set<string>()
+      const listings: CredentialListing[] = []
+      for (const row of rows) {
+        for (const item of row) {
+          if (seen.has(item.name)) {
+            throw new CredentialError('credential-duplicate', `credential name is in more than one source: ${item.name}`)
+          }
+          seen.add(item.name)
+          listings.push(item)
+        }
+      }
+      return listings.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+    },
+    async get(name) {
+      admitCredentialName(name)
+      const values = await Promise.all(providers.map(provider => provider.get(name)))
+      const found = values.filter((value): value is string => value !== undefined)
+      if (found.length > 1) {
+        throw new CredentialError('credential-duplicate', `credential name is in more than one source: ${name}`)
+      }
+      return found[0]
+    },
+    put: (name, description, secret) => writer === undefined ? Promise.reject(cannotWrite()) : writer.put(name, description, secret),
+    remove: name => writer === undefined ? Promise.reject(cannotWrite()) : writer.remove(name),
+  }
+}