@specbook/ui 0.1.0 → 0.3.0

package/src/embed.ts

@@ -1,4 +1,5 @@
-import type { Target } from './embed/panel'
+import { parseTarget, type Target } from './embed/target'
+import { followTheme } from './embed/theme'
 import tokens from './styles/tokens.css?inline'
 
 const css = `button {
@@ -12,14 +13,27 @@ const css = `button {
   color: var(--sb-accent);
 }
 button:hover { background: var(--sb-surface-raised); }
-button:focus-visible { outline: 2px solid var(--sb-focus-ring); }`
+button:focus-visible { outline: 2px solid var(--sb-focus-ring); }
+@media (pointer: coarse) { button { min-height: 44px; min-width: 44px; } }`
+
+let opened = false
 
 /** The panel (editor, grammars, runner) is a separate chunk fetched on first click. */
-async function open(target: Target) {
+export async function open(target: Target, trigger?: HTMLElement): Promise<void> {
   const { show } = await import('./embed/panel')
-  show(target)
+  opened = true
+  show(target, trigger)
+}
+
+/** Closes the panel, if it is open. */
+export async function close(): Promise<void> {
+  if (!opened) return
+  const { close: closePanel } = await import('./embed/panel')
+  closePanel()
 }
 
+const nameOf = (t: Target) => t.sequence ?? t.request ?? t.operation ?? ''
+
 class SpecbookPlay extends HTMLElement {
   target: Target = {}
 
@@ -33,29 +47,44 @@ class SpecbookPlay extends HTMLElement {
     b.type = 'button'
     b.part.add('play')
     b.textContent = '▶ Play'
-    b.addEventListener('click', () => open(this.target))
+    b.setAttribute('aria-haspopup', 'dialog')
+    b.setAttribute('aria-expanded', 'false')
+    b.setAttribute('aria-label', `Play ${nameOf(this.target)}`.trim())
+    b.addEventListener('click', () => open(this.target, this))
     root.append(b)
+    followTheme(this, this.target.theme)
   }
 }
 
 customElements.define('specbook-play', SpecbookPlay)
 
+/** A button or a link that carries the attribute is the trigger itself; anything else gets a Play button beside it. */
+const isTrigger = (el: HTMLElement) => el.matches('button, a[href], [role="button"]')
+
 function attach(el: HTMLElement) {
-  if (el.dataset.specbookReady) return
+  if (el.dataset.specbookReady !== undefined) return
   el.dataset.specbookReady = ''
-  const play = document.createElement('specbook-play') as SpecbookPlay
-  play.target = {
-    service: el.dataset.specbook || undefined,
-    operation: el.dataset.operation,
-    sequence: el.dataset.sequence,
-    example: el.dataset.example,
-    tab: el.dataset.tab === 'docs' ? 'docs' : undefined,
+  const target = parseTarget(el)
+  if (!target) return
+  if (isTrigger(el)) {
+    el.setAttribute('aria-haspopup', 'dialog')
+    if (!el.hasAttribute('aria-expanded')) el.setAttribute('aria-expanded', 'false')
+    el.addEventListener('click', (e) => {
+      e.preventDefault()
+      open(target, el)
+    })
+    return
   }
+  const play = document.createElement('specbook-play') as SpecbookPlay
+  play.target = target
   el.append(play)
 }
 
-const scan = (root: ParentNode) =>
-  root.querySelectorAll<HTMLElement>('[data-specbook]:not([data-specbook-ready])').forEach(attach)
+const SELECTOR = ['try', 'flow']
+  .map((a) => `[data-specbook-${a}]:not([data-specbook-ready])`)
+  .join(',')
+
+const scan = (root: ParentNode) => root.querySelectorAll<HTMLElement>(SELECTOR).forEach(attach)
 
 scan(document)
 // SPA docs add content after load

package/src/engine.ts

@@ -1,12 +1,23 @@
 // Run orchestration for the UI. Pure TS (no DOM) so it can be unit-tested with a fake registry.
 import {
+  AddressError,
   type AuthProfile,
+  absoluteBase,
+  addressUses,
+  baseUrlFor,
   createFetchTransport,
   createMockTransport,
+  type DiscoveredEndpoints,
   deepMerge,
   type Example,
+  environmentNames,
+  environmentScope,
   installFaker,
+  isDiscovery,
+  type OAuthSettings,
   type OpMeta,
+  oauthFor,
+  parseDiscovery,
   prepareFaker,
   type RequestDef,
   type RunEvent,
@@ -17,11 +28,24 @@ import {
   type SpecbookConfig,
   type Transport,
   usesFaker,
+  withMock,
 } from '@specbook/core'
+import type { EnvironmentStore } from './custom-environments'
 import { type ExtensionBridge, extensionTransport } from './extension'
-import { absoluteBase, routingTransport, withPageSecrets } from './routing'
+import { routingTransport, withPageSecrets } from './routing'
 import { originOf, type SecretStore, secretStore } from './secrets'
 
+/**
+ * The reserved service name a sign-in's token exchange is addressed to. The dev server's proxy answers
+ * `auth:<profile>` from the profile's own `oauth.tokenUrl` (the same prefix lives in `@specbook/vite`).
+ */
+const AUTH_SERVICE_PREFIX = 'auth:'
+const authService = (profile: string) => `${AUTH_SERVICE_PREFIX}${encodeURIComponent(profile)}`
+/** Likewise for an OpenID Connect discovery document, whose host may differ from the token endpoint's. */
+const DISCOVERY_SERVICE_PREFIX = 'discovery:'
+const discoveryService = (profile: string) =>
+  `${DISCOVERY_SERVICE_PREFIX}${encodeURIComponent(profile)}`
+
 export interface ExampleEntry {
   name: string
   source: 'generated' | 'project'
@@ -61,7 +85,7 @@ export interface RunInput {
   version: number
   /** Forced mock status per run (mock env only). */
   mockStatus?: number
-  params?: Record<string, unknown>
+  inputs?: Record<string, unknown>
   vars?: Record<string, unknown>
   onEvent?: (e: RunEvent) => void
   onInput?: Parameters<typeof runSequence>[1]['onInput']
@@ -73,13 +97,46 @@ export interface RunInput {
   fileDir?: string
 }
 
+/** One variable of an environment as the settings show it. */
+export interface VariableRow {
+  name: string
+  value: string
+  /** where the value comes from: the config's defaults or the environment's section, a file, this browser */
+  source: 'default' | 'config' | 'file' | 'browser'
+  /** what the variable falls back to when its own value is removed; undefined when it has no other */
+  fallback?: string
+  /** whether the value can be edited here */
+  editable: boolean
+}
+
+export interface EnvironmentView {
+  rows: VariableRow[]
+  /** where each service's calls go in this environment, or why they cannot */
+  addresses: { service: string; url?: string; error?: string }[]
+  /** which services' addresses and profiles' sign-in fields read each variable */
+  uses: ReturnType<typeof addressUses>
+  /** a browser-made environment: it can be deleted */
+  removable: boolean
+}
+
 export interface EngineOptions {
   /** The bridge to the browser extension when it is installed and enabled for this page. */
   extension?: () => Promise<ExtensionBridge | undefined>
   /** Where the person's typed secrets are kept (the page's store by default). */
   secrets?: SecretStore
+  /** Environments made in this browser (a static page has no files to write them to). */
+  environmentStore?: EnvironmentStore
 }
 
+const ENV_NAME = /^[A-Za-z0-9_-]+$/
+const VAR_NAME = /^[A-Za-z_][\w.-]*$/
+const hasTemplate = (v: unknown): boolean =>
+  typeof v === 'string'
+    ? /\{\{/.test(v)
+    : v !== null && typeof v === 'object' && Object.values(v).some(hasTemplate)
+const text = (v: unknown) =>
+  v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v ?? '')
+
 export function createEngine(reg: Registry, opts: EngineOptions = {}) {
   const mockLoader = {
     statuses: (service: string, opId: string) =>
@@ -95,6 +152,11 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     return (await reg.loadConfig(version)).default as SpecbookConfig
   }
 
+  const isStaticPage = () => reg.mode !== 'dev'
+  const browserEnvs = () => (isStaticPage() ? (opts.environmentStore?.all() ?? {}) : {})
+  // dev: environments created this session, until the registry reloads with their files
+  const createdHere = new Set<string>()
+
   /** Environments the config marks `production` or `sandbox`; the rest are judged by their name. */
   async function environmentRisks(
     version: number,
@@ -105,20 +167,38 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
       const risk = (e as { risk?: string } | undefined)?.risk
       if (risk === 'production' || risk === 'sandbox') out[name] = risk
     }
+    // a copy is as careful as what it was copied from
+    for (const [name, b] of Object.entries(browserEnvs()))
+      if (b.from && out[b.from] && !out[name]) out[name] = out[b.from] as 'production' | 'sandbox'
+    return out
+  }
+
+  /** One line per environment that has a description, for the pickers' tooltips. */
+  async function environmentNotes(version: number): Promise<Record<string, string>> {
+    const c = await config(version)
+    const out: Record<string, string> = {}
+    for (const [name, e] of Object.entries(c.environments ?? {})) {
+      const note = (e as { description?: string } | undefined)?.description
+      if (note) out[name] = note
+    }
+    for (const [name, b] of Object.entries(browserEnvs()))
+      if (b.from) out[name] = `copy of ${b.from}, kept in this browser`
     return out
   }
 
   async function environments(version: number): Promise<string[]> {
     const c = await config(version)
-    const envs = new Set<string>(['mock'])
-    for (const s of Object.values(c.services ?? {}))
-      for (const e of Object.keys(s.baseUrl ?? {})) envs.add(e)
-    for (const e of Object.keys(reg.environmentVars ?? {})) envs.add(e)
-    for (const e of Object.keys(c.environments ?? {})) envs.add(e)
-    return [...envs]
+    return environmentNames(
+      { services: c.services ?? {}, environments: c.environments },
+      [...Object.keys(reg.environmentVars ?? {}), ...createdHere],
+      Object.keys(browserEnvs()),
+    )
   }
 
-  /** The environment's own variables: read live from the dev server, baked in for static builds. */
+  /**
+   * The environment's own variables: read live from the dev server; baked in for a static build, with
+   * the ones this browser holds over them.
+   */
   async function environmentVars(env: string): Promise<Record<string, string>> {
     if (reg.mode === 'dev') {
       try {
@@ -128,7 +208,166 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
         /* fall back to what was baked in */
       }
     }
-    return reg.environmentVars?.[env] ?? {}
+    return { ...reg.environmentVars?.[env], ...browserEnvs()[env]?.vars }
+  }
+
+  /** What an address is rendered with: defaults, the environment's own settings, its file or browser copy. */
+  async function scopeOf(env: string, version: number): Promise<Record<string, unknown>> {
+    return environmentScope(await config(version), env, await environmentVars(env))
+  }
+
+  /** Where `service`'s calls go in `env`; undefined when it has no address there. Throws an AddressError. */
+  async function baseUrlOf(service: string, env: string, version: number) {
+    return baseUrlFor(await config(version), service, env, await scopeOf(env, version))
+  }
+
+  /** A profile's sign-in settings with its address fields rendered for `env`. */
+  async function oauthOf(
+    profile: string,
+    env: string,
+    version: number,
+  ): Promise<OAuthSettings | undefined> {
+    const oauth = ((await config(version)).auth?.[profile] as AuthProfile | undefined)?.oauth
+    // nothing to render, so nothing to ask the dev server for
+    if (!oauth || !hasTemplate(oauth)) return oauth
+    return oauthFor(oauth, await scopeOf(env, version), profile)
+  }
+
+  /**
+   * Addresses for a config the caller already holds (a page reading `engine.config` once for several
+   * services): the same rendering as `baseUrlOf` / `oauthOf`, with an address that cannot be worked out
+   * left undefined. The environment's variables are fetched only when something is written as a template.
+   */
+  async function addressesIn(cfg: SpecbookConfig, env: string) {
+    const templated =
+      Object.values(cfg.services ?? {}).some((s) => hasTemplate(s.baseUrl)) ||
+      Object.values(cfg.auth ?? {}).some((p) => hasTemplate((p as AuthProfile).oauth))
+    const scope = environmentScope(cfg, env, templated ? await environmentVars(env) : {})
+    return {
+      baseUrl(service: string): string | undefined {
+        try {
+          return baseUrlFor(cfg, service, env, scope)
+        } catch {
+          return undefined
+        }
+      },
+      oauth(profile: string): OAuthSettings | undefined {
+        const oauth = (cfg.auth?.[profile] as AuthProfile | undefined)?.oauth
+        try {
+          return oauth ? oauthFor(oauth, scope, profile) : undefined
+        } catch {
+          return undefined
+        }
+      },
+    }
+  }
+
+  /** The environment's variables as the settings show them, and where each service's calls go. */
+  async function environmentView(env: string, version: number): Promise<EnvironmentView> {
+    const c = await config(version)
+    const defaults = c.vars ?? {}
+    const section =
+      (c.environments?.[env] as { vars?: Record<string, unknown> } | undefined)?.vars ?? {}
+    const stored = browserEnvs()[env]
+    const baked = isStaticPage() ? (reg.environmentVars?.[env] ?? {}) : await environmentVars(env)
+    const browser = stored?.vars ?? {}
+    const names = [
+      ...new Set([
+        ...Object.keys(defaults),
+        ...Object.keys(section),
+        ...Object.keys(baked),
+        ...Object.keys(browser),
+      ]),
+    ]
+    const editable = reg.mode === 'dev' || !!opts.environmentStore
+    const rows: VariableRow[] = names.map((name) => {
+      const inherited = name in section ? section[name] : defaults[name]
+      const own = name in browser ? 'browser' : name in baked ? 'file' : undefined
+      const value = name in browser ? browser[name] : name in baked ? baked[name] : inherited
+      const fallbackSource = name in browser && name in baked ? baked[name] : inherited
+      return {
+        name,
+        value: text(value),
+        source: own ?? (name in section ? 'config' : 'default'),
+        fallback: own && fallbackSource !== undefined ? text(fallbackSource) : undefined,
+        editable,
+      }
+    })
+    const scope = environmentScope(c, env, { ...baked, ...browser })
+    const addresses: EnvironmentView['addresses'] = []
+    if (env !== 'mock')
+      for (const service of Object.keys(c.services ?? {})) {
+        try {
+          const url = baseUrlFor(c, service, env, scope)
+          addresses.push({ service, ...(url ? { url } : {}) })
+        } catch (e) {
+          if (!(e instanceof AddressError)) throw e
+          addresses.push({ service, error: e.message })
+        }
+      }
+    return { rows, addresses, uses: addressUses(c), removable: !!stored?.from }
+  }
+
+  /** Whether a person can make environments here: the dev server writes a file, a static page keeps it. */
+  const canCreateEnvironment = () => reg.mode === 'dev' || !!opts.environmentStore
+
+  /** A new environment holding a copy of `from`'s own variables (never its secrets). */
+  async function createEnvironment(name: string, from: string, version: number): Promise<void> {
+    if (!ENV_NAME.test(name))
+      throw new Error('Use letters, digits, "-" and "_" in an environment name')
+    if (name === 'mock' || (await environments(version)).includes(name))
+      throw new Error(`"${name}" already exists`)
+    if (reg.mode === 'dev') {
+      const r = await fetch('/__specbook/environment', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name, from }),
+      })
+      if (!r.ok)
+        throw new Error(((await r.json()) as { error?: string }).error ?? 'could not create')
+      createdHere.add(name)
+      return
+    }
+    if (!opts.environmentStore) throw new Error('This page has nowhere to keep a new environment')
+    const c = await config(version)
+    const section =
+      (c.environments?.[from] as { vars?: Record<string, unknown> } | undefined)?.vars ?? {}
+    const own = { ...section, ...(await environmentVars(from)) }
+    opts.environmentStore.save(name, {
+      from,
+      vars: Object.fromEntries(
+        Object.entries(own)
+          .filter(([, v]) => v !== null && typeof v !== 'object')
+          .map(([k, v]) => [k, String(v)]),
+      ),
+    })
+  }
+
+  /** Sets (or, with `null`, removes) one of an environment's own variables. */
+  async function setVariable(env: string, name: string, value: string | null): Promise<void> {
+    if (!VAR_NAME.test(name)) throw new Error(`"${name}" is not a variable name`)
+    if (reg.mode === 'dev') {
+      const r = await fetch('/__specbook/var', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ env, name, value }),
+      })
+      if (!r.ok) throw new Error(((await r.json()) as { error?: string }).error ?? 'save failed')
+      return
+    }
+    const store = opts.environmentStore
+    if (!store) throw new Error('This page has nowhere to keep a variable')
+    const current = store.all()[env] ?? { vars: {} }
+    const vars = { ...current.vars }
+    if (value === null) delete vars[name]
+    else vars[name] = value
+    if (!current.from && Object.keys(vars).length === 0) store.remove(env)
+    else store.save(env, { ...current, vars })
+  }
+
+  /** Forgets an environment made in this browser. */
+  function deleteEnvironment(env: string): void {
+    opts.environmentStore?.remove(env)
   }
 
   /** Names of the variables the project already supplies in `env`: config, per-environment and env files. */
@@ -147,14 +386,30 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
    * One transport per run, routing each request by its service (`routeFor`). Typed values are bound to
    * the API's origin first; placeholders left over are filled by the dev server or reported as missing.
    */
-  async function transportFor(env: string, proxyBase: string, version: number): Promise<Transport> {
+  async function transportFor(
+    env: string,
+    proxyBase: string,
+    version: number,
+    /** extra services by name -> base URL: a sign-in's token endpoint, which is not a configured service */
+    extra: Record<string, string> = {},
+  ): Promise<Transport> {
     if (env === 'mock') return createMockTransport({ loader: mockLoader })
     const cfg = await config(version)
+    // the environment's variables are only fetched when an address is written as a template
+    const templated = Object.values(cfg.services ?? {}).some((s) => hasTemplate(s.baseUrl))
+    const scope = templated ? await scopeOf(env, version) : {}
     const pageHref = globalThis.location?.href
     const pageOrigin = globalThis.location?.origin
     const baseOf = (service: string) => {
-      const url = cfg.services?.[service]?.baseUrl?.[env]
-      if (!url) throw new Error(`No base URL for ${service} in the "${env}" environment`)
+      if (extra[service]) return extra[service]
+      let url: string | undefined
+      try {
+        url = baseUrlFor(cfg, service, env, scope)
+      } catch (e) {
+        if (e instanceof AddressError) throw new Error(e.message)
+        throw e
+      }
+      if (!url) throw new Error(`No base URL for ${service} in ${env}`)
       return absoluteBase(url, pageHref)
     }
     const hasProxy = reg.mode !== 'static'
@@ -194,6 +449,14 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
           return await inner(req, signal)
         } catch (e) {
           // a blocked cross-origin call surfaces as a bare TypeError("Failed to fetch")
+          if (
+            e instanceof TypeError &&
+            (req.service.startsWith(AUTH_SERVICE_PREFIX) ||
+              req.service.startsWith(DISCOVERY_SERVICE_PREFIX))
+          )
+            throw new Error(
+              `The browser could not reach the sign-in provider (${extra[req.service] ?? 'unknown'}). It probably does not allow calls from this page (CORS). Embedding the viewer on the API's origin does not help when the sign-in server is on another host; the browser extension can make the call. You can still paste an access token.`,
+            )
           if (e instanceof TypeError)
             throw new Error(
               `The browser could not reach ${req.service} in "${env}". The API probably does not allow calls from this page (CORS). It works when the viewer runs on the API's own origin: embed it in the API's docs route ("Embed the viewer" in the README). Mock data keeps working.`,
@@ -219,6 +482,111 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     }
   }
 
+  type SignInEndpoints = DiscoveredEndpoints & { scopes: Record<string, string> }
+  const discovered = new Map<string, Promise<DiscoveredEndpoints>>()
+
+  /**
+   * Where a profile signs in: the endpoints its config writes out, or the ones its OpenID Connect
+   * discovery document names. The document is fetched the way any other call from the page is (through
+   * the dev server's proxy when there is one) and remembered for the life of the page.
+   */
+  async function oauthEndpoints(i: {
+    env: string
+    version: number
+    profile: string
+    proxyBase?: string
+    signal?: AbortSignal
+  }): Promise<SignInEndpoints> {
+    if (i.env === 'mock') throw new Error('Sign in needs a live environment, not mock')
+    let oauth: OAuthSettings | undefined
+    try {
+      oauth = await oauthOf(i.profile, i.env, i.version)
+    } catch (e) {
+      if (e instanceof AddressError) throw new Error(e.message)
+      throw e
+    }
+    if (!oauth) throw new Error(`"${i.profile}" has no sign-in configured`)
+    if (!isDiscovery(oauth))
+      return {
+        authorizationUrl: oauth.authorizationUrl,
+        tokenUrl: oauth.tokenUrl,
+        scopes: oauth.scopes ?? {},
+      }
+
+    const url = new URL(oauth.openIdConnectUrl)
+    let found = discovered.get(url.href)
+    if (!found) {
+      found = (async () => {
+        const service = discoveryService(i.profile)
+        const send = await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version, {
+          [service]: url.origin,
+        })
+        const res = await send(
+          {
+            service,
+            opId: 'oidc-discovery',
+            method: 'GET',
+            url: url.pathname,
+            query: Object.fromEntries(url.searchParams),
+            headers: { accept: 'application/json' },
+            encoding: 'none',
+          },
+          i.signal,
+        )
+        if (res.status >= 400)
+          throw new Error(`The provider's discovery document answered ${res.status}`)
+        return parseDiscovery(res.body)
+      })()
+      discovered.set(url.href, found)
+      // a failure is not remembered: the next click tries again
+      found.catch(() => discovered.delete(url.href))
+    }
+    const endpoints = await found
+    return {
+      ...endpoints,
+      scopes: oauth.scopes && Object.keys(oauth.scopes).length ? oauth.scopes : endpoints.scopes,
+    }
+  }
+
+  /**
+   * A sign-in's code exchange, sent the way any other call from this page is: through the dev server's
+   * proxy when there is one, else direct or through the extension. The token endpoint comes from the
+   * profile in the config (or its discovery document), never from the caller, so the proxy only ever
+   * forwards to the project's own.
+   */
+  async function oauthExchange(i: {
+    env: string
+    version: number
+    profile: string
+    fields: Record<string, string>
+    proxyBase?: string
+    signal?: AbortSignal
+  }): Promise<unknown> {
+    const { tokenUrl } = await oauthEndpoints(i)
+    const token = new URL(tokenUrl)
+    const service = authService(i.profile)
+    const send = await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version, {
+      [service]: token.origin,
+    })
+    const res = await send(
+      {
+        service,
+        opId: 'oauth-token',
+        method: 'POST',
+        url: token.pathname,
+        query: Object.fromEntries(token.searchParams),
+        headers: { accept: 'application/json' },
+        body: i.fields,
+        encoding: 'form',
+      },
+      i.signal,
+    )
+    const body = res.body as { error?: unknown } | undefined
+    if (res.status >= 400 && typeof body?.error !== 'string')
+      throw new Error(`The token endpoint answered ${res.status}`)
+    return res.body
+  }
+
   const norm = (p: string) => p.replace(/^\.\//, '')
 
   /** Display order: the author's examples first, generated ones last. */
@@ -255,13 +623,9 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     )
     return {
       env: i.env,
-      vars: {
-        ...(c.vars ?? {}),
-        ...(c.environments?.[i.env]?.vars ?? {}),
-        ...(await environmentVars(i.env)),
-      },
+      vars: await scopeOf(i.env, i.version),
       overrides: i.vars,
-      params: i.params,
+      inputs: i.inputs,
       transport: await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version),
       // placeholders stay in the request: the dev server's proxy or a static page's transport fills them
       deferSecrets: true,
@@ -270,6 +634,8 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
       onEvent: i.onEvent,
       onInput: i.onInput,
       signal: i.signal,
+      // the project's own, else the runner's default
+      timeoutMs: c.timeoutMs,
       example: (op: { service: string; id: string }, name: string) =>
         loadExample(`${op.service}/${op.id}`, name, i.version),
       readFile: (path: string, dir?: string) => readFile(path, dir ?? i.fileDir),
@@ -294,27 +660,31 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     return usesFaker([base, data, target.dataPatches, path, query, headers, i.vars])
   }
 
+  /**
+   * Makes faker ready for `locale` (a bundled module offers each locale as its own chunk, so only the ones it falls back
+   * through are fetched). Generated values need it before a run: a form that offers one asks for it when it opens.
+   */
+  async function fakerReady(version: number, locale?: string, seed?: number): Promise<boolean> {
+    if (!reg.loadFaker) return false
+    const [mod, cfg] = await Promise.all([reg.loadFaker(version), config(version)])
+    const ready = await prepareFaker(mod, cfg.faker, locale)
+    installFaker(ready as never, cfg.faker, { locale, seed })
+    return true
+  }
+
   async function run(
     target: RequestDef<any, any, any> | Sequence<any, any>,
     i: RunInput,
   ): Promise<RunResult> {
     // `init` generators call faker, so it must be ready before any run unless we can see it isn't used.
-    if (reg.loadFaker && (await mayUseFaker(target, i))) {
-      const [mod, cfg] = await Promise.all([reg.loadFaker(i.version), config(i.version)])
-      // a bundled module offers each locale as its own chunk; fetch only the ones this run falls back through
-      const ready = await prepareFaker(mod, cfg.faker, i.locale)
-      installFaker(ready as never, cfg.faker, { locale: i.locale, seed: i.seed })
-    }
+    if (reg.loadFaker && (await mayUseFaker(target, i)))
+      await fakerReady(i.version, i.locale, i.seed)
     const o = await baseOptions(i)
     if (target.kind === 'sequence') return runSequence(target, o)
-    const def =
-      i.mockStatus !== undefined && i.env === 'mock'
-        ? target.with({ mock: { status: i.mockStatus } })
-        : target
-    return runRequest(def, o)
+    return runRequest(target, i.env === 'mock' ? { ...o, mockStatus: i.mockStatus } : o)
   }
 
-  /** `base` keeps its init/capture/assert/mock; `overrides` replace path/query/headers/data. */
+  /** `base` keeps its init/capture/assert and mock hook; `overrides` replace path/query/headers/data. */
   async function operationRequest(
     key: string,
     version: number,
@@ -327,7 +697,8 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     const op = mod[key.split('/')[1] as string]
     if (!op) throw new Error(`Operation module for ${key} has no export`)
     const defined = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
-    return op.request({ ...(base?.input ?? {}), ...defined })
+    const made = op.request({ ...(base?.input ?? {}), ...defined })
+    return base?.mockHook ? withMock(made, base.mockHook) : made
   }
 
   async function operationMeta(key: string, version: number): Promise<OpMeta | undefined> {
@@ -400,8 +771,21 @@ export function createEngine(reg: Registry, opts: EngineOptions = {}) {
     config,
     environments,
     environmentRisks,
+    environmentNotes,
+    environmentVars,
+    environmentView,
+    canCreateEnvironment,
+    createEnvironment,
+    deleteEnvironment,
+    setVariable,
+    baseUrlOf,
+    oauthOf,
+    addressesIn,
     managedSecrets,
+    oauthEndpoints,
+    oauthExchange,
     run,
+    fakerReady,
     operationRequest,
     operationMeta,
     examplesOf,