kaloko 0.3.0 → 0.4.1

package/src/lib/design-export.mjs

@@ -0,0 +1,162 @@
+// Exportability (#42): a design version leaves Kaloko in open formats only, as a folder or a zip that opens from disk:
+// the live HTML with its assets (the design folder layout), tokens.json (W3C DTCG), scenario.yml (qawalk.scenario.v1),
+// the screenshots, kaloko.json (what is where) and index.html, a start page without scripts.
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createWriteStream } from 'node:fs'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { gunzipSync } from 'node:zlib'
+import { join, dirname, relative, basename, isAbsolute } from 'node:path'
+import yaml from 'js-yaml'
+import { zipStream } from './zip.mjs'
+import { UserError } from './util.mjs'
+import { TOKENS_FILE } from './design-core.mjs'
+
+export const DESIGN_EXPORT_SCHEMA = 'qawalk.design-export.v1'
+const enc = encodeURIComponent
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+const titleOf = (t, locale) => (t && typeof t === 'object' ? t[locale] ?? t.default ?? Object.values(t)[0] : t) || ''
+const flowOrder = (nodes) => nodes.filter((n) => n.kind !== 'decision').slice().sort((a, b) => (a.col ?? 0) - (b.col ?? 0) || (a.lane ?? 0) - (b.lane ?? 0))
+
+/** A qawalk.scenario.v1 document from a run manifest: a design version carries the whole flow (steps, criteria, edges). */
+export function scenarioFromManifest (m) {
+  const lanes = m.lanes || []
+  const nodes = m.nodes.map((n) => {
+    const own = (n.criteria || []).filter((c) => !c.pack)
+    const packs = [...new Set((n.criteria || []).filter((c) => c.pack).map((c) => c.pack))]
+    return {
+      id: n.id, kind: n.kind, title: n.title,
+      ...(n.path != null ? { path: n.path } : {}), ...(n.purpose ? { purpose: n.purpose } : {}),
+      ...(lanes.length && Number.isInteger(n.lane) ? { lane: n.lane } : {}), ...(n.session ? { session: n.session } : {}),
+      // run manifests do not carry how a step is reached; the scenario needs it, so the export names the manual way
+      ...(['decision', 'stack'].includes(n.kind) ? {} : { execution: n.execution?.strategy && n.execution?.instructions ? { strategy: n.execution.strategy, instructions: n.execution.instructions } : { strategy: 'manual', instructions: `Open ${typeof n.path === 'string' ? n.path : `the ${n.id} step`}.` } }),
+      ...(own.length ? { criteria: own.map((c) => ({ id: c.id, text: c.text, check: c.check })) } : {}), ...(packs.length ? { packs } : {})
+    }
+  })
+  return {
+    schema: 'qawalk.scenario.v1', id: m.scenario.id, title: m.scenario.title || m.scenario.id, kind: m.scenario.kind === 'flow' ? 'flow' : 'task',
+    ...(m.project?.slug ? { project: m.project.slug } : {}),
+    locales: m.scope.locales, viewports: m.scope.viewports, ...(lanes.length ? { lanes } : {}), ...(m.sessions ? { sessions: m.sessions } : {}),
+    nodes, edges: (m.edges || []).map((e) => ({ from: e.from, to: e.to, ...(e.label ? { label: e.label } : {}), ...(e.kind && e.kind !== 'main' ? { kind: e.kind } : {}) }))
+  }
+}
+
+/** Start page of an exported design: the steps in flow order with each locale's page and screenshot; plain HTML, no script. */
+export function exportIndexHtml ({ index }) {
+  const loc0 = index.locales[0]
+  const rows = index.steps.map((s) => `<li><h2>${esc(titleOf(s.title, loc0))} <small>${esc(s.id)}</small></h2>${s.purpose ? `<p>${esc(s.purpose)}</p>` : ''}<p>${index.locales.filter((l) => s.pages[l]).map((l) => `<a href="${esc(s.pages[l].split('/').map(enc).join('/'))}">${esc(l)}: ${esc(titleOf(s.title, l))}</a>`).join(' · ') || '<em>no page</em>'}</p>${s.screenshots.length ? `<p class="shots">${s.screenshots.map((x) => `<a href="${esc(x.file)}"><img src="${esc(x.file)}" alt="${esc(`${s.id} ${x.locale} ${x.viewport}`)}" loading="lazy" width="160"></a>`).join('')}</p>` : ''}</li>`).join('\n')
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(index.scenario.title)} · ${esc(index.ref)}</title>
+<style>:root{color-scheme:light dark;--ink:#151514;--paper:#fff;--line:#ddd}@media (prefers-color-scheme:dark){:root{--ink:#eee;--paper:#151514;--line:#333}}body{margin:0;font:16px/1.5 system-ui,sans-serif;color:var(--ink);background:var(--paper)}main{max-width:960px;margin:0 auto;padding:32px 16px}ol{padding-left:20px}li{border-top:1px solid var(--line);padding:12px 0}h2{font-size:18px;margin:0}small{font-weight:400;opacity:.6}.shots img{border:1px solid var(--line);border-radius:4px;margin:0 8px 8px 0;height:auto}code{font-size:14px}</style></head>
+<body><main><h1>${esc(index.scenario.title)}</h1>
+<p>${esc(index.ref)}${index.version ? ` · v${esc(index.version)}${index.version_name ? ` “${esc(index.version_name)}”` : ''}` : ''} · exported ${esc(index.exported_at.slice(0, 10))} from Kaloko. Everything here is plain HTML, CSS, JS and images; it opens from disk without Kaloko.</p>
+<p>Files: <a href="scenario.yml">scenario.yml</a> (steps, criteria, flow)${index.tokens ? ` · <a href="${TOKENS_FILE}">${TOKENS_FILE}</a> (W3C DTCG design tokens)` : ''} · <a href="kaloko.json">kaloko.json</a> (what is where)</p>
+<ol>
+${rows}
+</ol></main></body></html>
+`
+}
+
+/**
+ * A relative path inside the export, or a UserError: names come from the service's responses (file lists, step ids,
+ * locales), and none of them may leave the export folder (no "..", no absolute or drive paths, no backslashes).
+ */
+export function safeExportPath (p) {
+  const s = String(p ?? '')
+  const parts = s.split('/')
+  if (!s || s.length > 1024 || /[\\\u0000]/.test(s) || /^[a-zA-Z]:/.test(s) || isAbsolute(s) || parts.some((x) => !x || x === '.' || x === '..')) throw new UserError(`Refusing to write ${JSON.stringify(s.slice(0, 120))}: not a plain relative path inside the export.`)
+  return s
+}
+
+/** A folder or, when `out` ends with .zip, a zip with one top folder; put(path, bytes) then close(). */
+export function exportSink (out) {
+  if (!out.endsWith('.zip')) return { put: async (p, bytes) => { const t = join(out, safeExportPath(p)); await mkdir(dirname(t), { recursive: true }); await writeFile(t, bytes) }, close: async () => {} }
+  const top = basename(out, '.zip')
+  const entries = []
+  return {
+    put: async (p, bytes) => { entries.push({ name: `${top}/${safeExportPath(p)}`, body: bytes instanceof Uint8Array ? bytes : new TextEncoder().encode(bytes) }) },
+    close: async () => { await mkdir(dirname(out), { recursive: true }); await pipeline(Readable.fromWeb(zipStream(entries)), createWriteStream(out)) }
+  }
+}
+
+/** Run id behind a reference: design (the design reference, per branch), vN, or a run id. */
+async function runIdOf ({ client, org, scenarioId, ref, branch }) {
+  if (ref === 'design') {
+    const refs = await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/references`)
+    const id = refs.design_by_branch?.[branch] || refs.design
+    if (!id) throw new UserError(`${scenarioId} has no design reference yet; name a version with --version <n> (kaloko history lists them).`)
+    return id
+  }
+  if (/^v\d+$/.test(ref)) {
+    const v = (await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/versions`)).find((x) => String(x.version) === ref.slice(1))
+    if (!v) throw new UserError(`${scenarioId} has no version ${ref}.`)
+    return v.id
+  }
+  return ref
+}
+
+/**
+ * Exports a design version (or the draft) of a scenario into `out` (folder or .zip). Returns the index (kaloko.json).
+ * `ref`: design | vN | draft | a run id.
+ */
+export async function exportDesign ({ config, scenarioId, client, ref = 'design', branch = 'main', out, say = () => {} }) {
+  const org = config.org
+  const draft = ref === 'draft'
+  const runId = draft ? null : await runIdOf({ client, org, scenarioId, ref, branch })
+  const manifest = draft
+    ? await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/draft/manifest${branch !== 'main' ? `?branch=${enc(branch)}` : ''}`)
+    : await client.request('GET', `/orgs/${org}/runs/${runId}`)
+  if (manifest.source !== 'design' && !manifest.draft) throw new UserError(`${runId} is not a design version; kaloko export --run ${runId} exports any run.`)
+  const revs = await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/revisions?ref=${enc(draft ? (branch === 'main' ? 'draft' : `draft:${branch}`) : runId)}`)
+  const sink = exportSink(out)
+  const fileOf = async (path) => {
+    const res = draft ? await fetch(manifest.files_base + path) : await client.fetch(`/orgs/${org}/runs/${runId}/files/${path.split('/').map(enc).join('/')}`)
+    if (!res.ok) throw new UserError(`${path}: HTTP ${res.status}`)
+    return Buffer.from(await res.arrayBuffer())
+  }
+  // the live files keep the design folder layout: links between steps work from disk exactly as in the folder
+  const paths = new Map(), clashes = []
+  const pages = {}
+  for (const s of revs.steps.filter((x) => x.state === 'default')) {
+    ;(pages[s.node] ||= {})[s.locale] = s.entry
+    for (const [p, hash] of Object.entries(s.files)) {
+      safeExportPath(p) // checked before anything is written
+      if (paths.has(p)) { if (paths.get(p).hash !== hash) clashes.push(p); continue }
+      paths.set(p, { hash, revision: s.revision })
+    }
+  }
+  for (const [p, { revision }] of paths) {
+    const res = await client.fetch(`/orgs/${org}/revisions/${revision}/files/${p.split('/').map(enc).join('/')}`)
+    let buf = Buffer.from(await res.arrayBuffer())
+    if (res.headers.get('X-QAwalk-Encoding') === 'gzip') buf = gunzipSync(buf)
+    await sink.put(p, buf)
+  }
+  const steps = []
+  let shots = 0
+  for (const n of flowOrder(manifest.nodes)) {
+    const screenshots = []
+    for (const [locale, vps] of Object.entries(n.captures || {})) for (const [viewport, c] of Object.entries(vps || {})) {
+      const src = c?.image || c?.png
+      if (!src) continue
+      const file = `screenshots/${n.id}/${locale}/${viewport}.${src.split('.').pop()}`
+      await sink.put(file, await fileOf(src))
+      screenshots.push({ locale, viewport, file, size: c.size || null })
+      shots++
+    }
+    steps.push({ id: n.id, title: n.title, purpose: n.purpose || '', kind: n.kind, pages: pages[n.id] || {}, screenshots })
+  }
+  const index = {
+    schema: DESIGN_EXPORT_SCHEMA, scenario: { id: scenarioId, title: manifest.scenario?.title || scenarioId }, ref, run_id: runId,
+    version: manifest.version ?? null, version_name: manifest.version_name ?? null, branch, exported_at: new Date().toISOString(),
+    locales: manifest.scope.locales, viewports: manifest.scope.viewports, tokens: paths.has(TOKENS_FILE) ? TOKENS_FILE : null,
+    formats: { pages: 'HTML, CSS, JS and assets in the design folder layout (<step>/index.html, <step>/<locale>/index.html, _shared/)', tokens: 'W3C Design Tokens (DTCG) JSON', scenario: 'qawalk.scenario.v1 YAML', screenshots: 'WebP or PNG per step, locale and viewport' },
+    steps
+  }
+  await sink.put('scenario.yml', `# Exported from Kaloko (${ref}); validate with: kaloko validate scenario.yml\n` + yaml.dump(scenarioFromManifest(manifest), { lineWidth: 140, noRefs: true }))
+  await sink.put('kaloko.json', JSON.stringify(index, null, 2) + '\n')
+  await sink.put('index.html', exportIndexHtml({ index }))
+  await sink.close()
+  if (clashes.length) say(`! ${clashes.length} file(s) differ between steps (${clashes.slice(0, 3).join(', ')}); the export keeps the first step's copy.`)
+  say(`Design ${scenarioId} at ${ref}${index.version ? ` (v${index.version})` : ''} → ${relative(process.cwd(), out) || '.'}\n  ${paths.size} live file(s), ${shots} screenshot(s), ${steps.length} step(s); open index.html from disk.`)
+  return index
+}

package/src/lib/design-lint.mjs

@@ -0,0 +1,189 @@
+// Portable interactive HTML (#42): checks a design folder against what works on the live origin
+// (<revision>.<USERCONTENT_HOST>, sandboxed, CSP default-src 'self'), from disk (file://) and from a zip.
+// Errors are things that certainly break there; warnings make prototypes fragile or captures unstable.
+// The rules are explained in skills/kaloko/reference/portable-html.md. lintFiles is pure (tests, other tools).
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+import { BUNDLE_LIMITS, SHARED_DIR, TOKENS_FILE, TEXT_TYPES, contentTypeOf, extOf, resolveRef } from './design-core.mjs'
+
+/** Rule id → level and a short reason (the fix is in each finding). */
+export const LINT_RULES = {
+  'external-url': ['error', 'loads a file from another site; the live origin allows only files of the bundle'],
+  'root-relative': ['error', 'a path starting with / points outside the design folder on the live origin and from disk'],
+  'outside-folder': ['error', 'a relative path that climbs out of the design folder'],
+  'missing-file': ['error', 'a referenced file that is not in the folder'],
+  'file-type': ['error', 'a referenced file type the bundle does not allow'],
+  'eval': ['error', "eval and new Function are blocked (no 'unsafe-eval')"],
+  'service-worker': ['error', 'service workers are refused on live steps'],
+  'embedded-frame': ['error', 'iframe, object and embed are blocked (frame-src and object-src none)'],
+  'websocket': ['error', 'network connections are blocked (connect-src self)'],
+  'too-large': ['error', 'over the bundle limits'],
+  'tokens-json': ['error', 'tokens.json is not valid JSON'],
+  'storage': ['warn', 'storage and cookies throw in the sandboxed frame and are not shared between viewers'],
+  'nondeterministic': ['warn', 'random values and the current time change every capture'],
+  'directory-link': ['warn', 'a link to a folder does not open its index.html from disk or a zip'],
+  'broken-link': ['warn', 'a link to a page that is not in the folder'],
+  'new-window': ['warn', 'popups are blocked in the sandbox'],
+  'top-navigation': ['warn', 'the frame may not navigate the canvas'],
+  'modal': ['warn', 'alert, confirm and prompt are blocked in the sandbox'],
+  'form-action': ['warn', 'form submission is blocked (form-action none)'],
+  'doctype': ['warn', 'without <!doctype html> the page renders in quirks mode'],
+  'charset': ['warn', 'without <meta charset> text may decode wrongly from disk'],
+  'viewport-meta': ['warn', 'without the viewport meta, mobile viewports render a zoomed-out desktop page'],
+  'lang': ['warn', '<html lang> tells screen readers and the language checks what language the page is in'],
+  'title': ['warn', 'the page title names the step in tabs, history and screen readers'],
+  'img-alt': ['warn', 'images need an alt text (empty for decoration)'],
+  'reduced-motion': ['warn', 'animations should respect prefers-reduced-motion'],
+  'large-file': ['warn', 'over the size budget'],
+  'tokens-unused': ['warn', 'the token set is there but no CSS custom property uses it'],
+  'missing-step': ['warn', 'a scenario step without a design'],
+  'external-link': ['info', 'a link that leaves the prototype'],
+  'stray-folder': ['info', 'a folder that is not a step of the scenario'],
+  'no-tokens': ['info', 'no token set: the inspector cannot name values']
+}
+export const BUDGET = { file_bytes: 1024 * 1024, step_bytes: 5 * 1024 * 1024 }
+
+const lineAt = (text, i) => { let n = 1; for (let k = 0; k < i && k < text.length; k++) if (text.charCodeAt(k) === 10) n++; return n }
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i
+const stripQ = (u) => u.split('#')[0].split('?')[0]
+const kb = (b) => `${Math.round(b / 1024)} kB`
+
+/**
+ * Lints the files of a design folder. `files`: Map path → { bytes, text? } (text for text types), `steps`: step ids of
+ * the scenario (null = every top-level folder but _shared). Returns findings { rule, level, file, line, message, fix }.
+ */
+export function lintFiles (files, { steps = null } = {}) {
+  const out = []
+  const add = (rule, file, line, message, fix = '') => out.push({ rule, level: LINT_RULES[rule][0], file, line: line || null, message, fix })
+  const has = (p) => files.has(p)
+  const isDir = (p) => [...files.keys()].some((f) => f.startsWith(p.replace(/\/?$/, '/')))
+  let anyMotion = null, reducedMotion = false, usesVars = false
+  const resource = (file, text, i, raw, { script = false, data = false } = {}) => {
+    const u = raw.trim()
+    if (!u || u.startsWith('#') || /^(about:blank|blob:)/i.test(u)) return
+    const line = lineAt(text, i)
+    if (/^data:/i.test(u)) { if (script) add('external-url', file, line, 'a script from a data: URL is blocked (script-src self)', 'Put the script into a .js file of the bundle.'); return }
+    if (/^javascript:/i.test(u)) return
+    if (/^(https?:)?\/\//i.test(u) || SCHEME.test(u)) return add('external-url', file, line, `loads ${u.slice(0, 120)} from another site; it will not load on the live step (CSP default-src 'self')`, data ? 'Live steps have no network: put the data into a JSON fixture of the bundle and fetch(\'./fixtures/….json\').' : 'Download the file into _shared/ (fonts as woff2) and reference it with a relative path.')
+    if (u.startsWith('/')) return add('root-relative', file, line, `${u.slice(0, 120)} starts with /, which is the origin root on the live step and the disk root from file://`, `Use a path relative to ${file} (for example ../${SHARED_DIR}/…).`)
+    const p = resolveRef(file, stripQ(u))
+    if (!p) return add('outside-folder', file, line, `${u.slice(0, 120)} points outside the design folder`, 'Keep every file the page needs inside the design folder.')
+    if (!contentTypeOf(p)) return add('file-type', file, line, `${p}: .${extOf(p) || '?'} files are not part of a bundle`, 'Convert it (fonts to woff2, images to webp/png/svg) or drop it.')
+    if (!has(p)) add('missing-file', file, line, `${u.slice(0, 120)} → ${p} is not in the folder`, 'Add the file or fix the path (paths are case-sensitive on the service).')
+  }
+  const link = (file, text, i, raw, attrs) => {
+    const u = raw.trim(); const line = lineAt(text, i)
+    const tg = attrs.match(/\starget\s*=\s*["']?_(blank|top|parent)/i)
+    if (tg) add('new-window', file, line, `a link with target=_${tg[1]} does nothing in the sandboxed live step`, 'Drop the target attribute; links between steps open in the same frame.')
+    if (!u || u.startsWith('#') || /^(mailto|tel|javascript):/i.test(u)) return
+    if (/^(https?:)?\/\//i.test(u)) return add('external-link', file, line, `${u.slice(0, 120)} leaves the prototype`, '')
+    if (u.startsWith('/')) return add('root-relative', file, line, `link ${u.slice(0, 120)} starts with /: it 404s on the live step and from disk`, 'Link relatively, e.g. ../payment/index.html.')
+    const bare = stripQ(u)
+    if (!bare) return
+    const p = resolveRef(file, bare)
+    if (!p) return add('outside-folder', file, line, `link ${u.slice(0, 120)} points outside the design folder`, '')
+    if (bare.endsWith('/') || (!extOf(p) && isDir(p))) return add('directory-link', file, line, `link ${u.slice(0, 120)} points at a folder; from disk or a zip the browser shows a listing or nothing`, `Link the page itself: ${bare.replace(/\/?$/, '/')}index.html`)
+    if (!has(p)) add('broken-link', file, line, `link ${u.slice(0, 120)} → ${p} is not in the folder`, 'Point it at a step page (../<step>/index.html) or add the page.')
+  }
+  const css = (file, text, base = 0, whole = text) => {
+    for (const m of text.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi)) resource(file, whole, base + m.index, m[2])
+    for (const m of text.matchAll(/@import\s+(['"])([^'"]+)\1/gi)) resource(file, whole, base + m.index, m[2])
+    if (/var\(--/.test(text)) usesVars = true
+    if (/prefers-reduced-motion/.test(text)) reducedMotion = true
+    if (!anyMotion) { const m = text.match(/(?:^|[;{\s])(animation(?:-name)?|transition)\s*:\s*(?!none\b)[^;}]*[1-9]/m); if (m) anyMotion = { file, line: lineAt(whole, base + m.index) } }
+  }
+  const js = (file, text, base = 0, whole = text) => {
+    const at = (re, fn) => { for (const m of text.matchAll(re)) fn(m, lineAt(whole, base + m.index)) }
+    at(/(?:^|[^.\w$])(?:import|export)\s[^'"]*?from\s*(['"])([^'"]+)\1|import\s*\(\s*(['"])([^'"]+)\3\s*\)/g, (m) => { const u = m[2] || m[4]; if (/^(\.|\/|https?:|\/\/)/.test(u)) resource(file, whole, base + m.index, u, { script: true }) })
+    at(/\bfetch\(\s*(['"`])([^'"`$]+)\1/g, (m) => resource(file, whole, base + m.index, m[2], { data: true }))
+    at(/\bnew\s+(?:XMLHttpRequest|EventSource|WebSocket)\b/g, (m, l) => add('websocket', file, l, `${m[0].replace(/^new\s+/, '')} needs a network the live step does not have (connect-src self)`, 'Read fixtures from JSON files in the bundle with fetch(\'./fixtures/…json\').'))
+    at(/(?:^|[^.\w$])(?:eval\s*\(|new\s+Function\s*\(|set(?:Timeout|Interval)\s*\(\s*['"`])/g, (m, l) => add('eval', file, l, 'code from a string is blocked on the live step (no \'unsafe-eval\')', 'Pass a function instead of a string; do not use eval or new Function.'))
+    at(/navigator\.serviceWorker/g, (m, l) => add('service-worker', file, l, 'service workers are refused on live steps and outlive the page', 'Remove the registration; prototypes need no offline cache.'))
+    at(/\b(localStorage|sessionStorage|indexedDB|document\.cookie)\b/g, (m, l) => add('storage', file, l, `${m[1]} throws in the sandboxed live step (opaque origin) and is empty for every other viewer`, 'Keep prototype state in the URL (location.hash or ?query) or in memory; wrap any storage access in try/catch.'))
+    at(/\b(Date\.now\(\)|new Date\(\s*\)|Math\.random\(\)|crypto\.(?:randomUUID|getRandomValues)\()/g, (m, l) => add('nondeterministic', file, l, `${m[1].replace(/\($/, '()')} makes every capture different, so unchanged steps look changed`, 'Use fixed dates (new Date(\'2026-01-15T10:00\')) and a seeded generator for fake data.'))
+    at(/(?:^|[^.\w$]|window\.)(alert|confirm|prompt)\s*\(/g, (m, l) => add('modal', file, l, `${m[1]}() is blocked in the sandbox (no allow-modals)`, 'Show an in-page <dialog> instead.'))
+    at(/(?:^|[^.\w$])window\.open\s*\(/g, (m, l) => add('new-window', file, l, 'window.open is blocked in the sandbox (no allow-popups)', 'Navigate in the same frame (location.href = \'../next/index.html\').'))
+    at(/\b(?:top|parent)\.location\b/g, (m, l) => add('top-navigation', file, l, `${m[0]} tries to navigate the canvas`, 'Navigate the frame itself, or use data-kaloko-go="<step>".'))
+  }
+  for (const [file, f] of files) {
+    if (f.bytes > BUNDLE_LIMITS.max_file_bytes) add('too-large', file, null, `${kb(f.bytes)}: over the ${Math.round(BUNDLE_LIMITS.max_file_bytes / 1048576)} MB limit of one file`, 'Compress it or split it.')
+    else if (f.bytes > BUDGET.file_bytes) add('large-file', file, null, `${kb(f.bytes)}: over the ${kb(BUDGET.file_bytes)} budget of one file`, /\.(png|jpe?g|gif)$/i.test(file) ? 'Use webp or avif at the size it is shown.' : /\.(woff2?)$/i.test(file) ? 'Subset the font to the characters you use.' : 'Keep prototypes light: every viewer loads it.')
+    if (f.text == null) continue
+    const t = f.text, ext = extOf(file)
+    if (ext === 'css') css(file, t)
+    else if (ext === 'js' || ext === 'mjs') js(file, t)
+    else if (ext === 'html' || ext === 'svg') {
+      for (const m of t.matchAll(/\s(src|poster|data-src)\s*=\s*(['"])([^'"]*)\2/gi)) resource(file, t, m.index, m[3], { script: /<script\b[^>]*$/i.test(t.slice(Math.max(0, m.index - 200), m.index)) })
+      for (const m of t.matchAll(/<link\b([^>]*)>/gi)) { const h = m[1].match(/\shref\s*=\s*(['"])([^'"]*)\1/i); const rel = (m[1].match(/\srel\s*=\s*(['"]?)([^'"\s>]+)\1/i)?.[2] || '').toLowerCase(); if (h && !/^(canonical|alternate|author|help|license|next|prev|search|dns-prefetch|preconnect)$/.test(rel)) resource(file, t, m.index, h[2]) }
+      for (const m of t.matchAll(/<(?:use|image|feImage)\b[^>]*\s(?:xlink:)?href\s*=\s*(['"])([^'"]*)\1/gi)) resource(file, t, m.index, m[2])
+      for (const m of t.matchAll(/\ssrcset\s*=\s*(['"])([^'"]*)\1/gi)) for (const part of m[2].split(',')) resource(file, t, m.index, part.trim().split(/\s+/)[0])
+      for (const m of t.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) css(file, m[1], m.index + m[0].indexOf(m[1]), t)
+      for (const m of t.matchAll(/\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) css(file, m[1] ?? m[2], m.index, t)
+      for (const m of t.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) if (!/\ssrc\s*=/.test(m[1]) && !/type\s*=\s*["']?(application\/(ld\+)?json|importmap|text\/template)/i.test(m[1])) js(file, m[2], m.index + m[0].indexOf(m[2]), t)
+      if (ext === 'svg') continue
+      for (const m of t.matchAll(/<(a|area)\b([^>]*)>/gi)) { const h = m[2].match(/\shref\s*=\s*(['"])([^'"]*)\1/i); if (h) link(file, t, m.index, h[2], m[2]) }
+      for (const m of t.matchAll(/<(iframe|object|embed|frame)\b/gi)) add('embedded-frame', file, lineAt(t, m.index), `<${m[1].toLowerCase()}> is blocked on the live step`, 'Draw the embedded content into the page (an image or markup of it).')
+      for (const m of t.matchAll(/<form\b[^>]*\saction\s*=\s*(['"])([^'"]*)\1/gi)) if (m[2] && m[2] !== '#') add('form-action', file, lineAt(t, m.index), `submitting to ${m[2].slice(0, 80)} is blocked on the live step`, 'Handle submit in a script (event.preventDefault()) and move on with a link or data-kaloko-go.')
+      for (const m of t.matchAll(/<img\b([^>]*)>/gi)) if (!/\salt\s*=/i.test(m[1])) add('img-alt', file, lineAt(t, m.index), 'an <img> without alt', 'Add alt="…" (alt="" for decoration).')
+      if (!/^\s*(<!--[\s\S]*?-->\s*)*<!doctype html/i.test(t)) add('doctype', file, 1, 'no <!doctype html>', 'Start the page with <!doctype html>.')
+      if (!/<meta\s+charset\s*=/i.test(t) && !/<meta[^>]+content\s*=\s*["'][^"']*charset=/i.test(t)) add('charset', file, null, 'no <meta charset>', 'Add <meta charset="utf-8"> first in <head>.')
+      if (!/<meta[^>]+name\s*=\s*["']?viewport/i.test(t)) add('viewport-meta', file, null, 'no viewport meta', 'Add <meta name="viewport" content="width=device-width, initial-scale=1">.')
+      if (!/<html\b[^>]*\slang\s*=\s*["']?[a-z]/i.test(t)) add('lang', file, null, '<html> has no lang', 'Add <html lang="en"> (the locale of the page).')
+      if (!/<title>\s*[^<\s]/i.test(t)) add('title', file, null, 'no <title>', 'Name the step in <title>.')
+    }
+  }
+  if (anyMotion && !reducedMotion) add('reduced-motion', anyMotion.file, anyMotion.line, 'animations or transitions without a prefers-reduced-motion rule anywhere in the folder', 'Add @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important } } to the shared CSS.')
+  if (files.has(TOKENS_FILE)) {
+    try { JSON.parse(files.get(TOKENS_FILE).text) } catch (e) { add('tokens-json', TOKENS_FILE, null, e.message, 'Fix the JSON (kaloko tokens validate).') }
+    if (!usesVars) add('tokens-unused', TOKENS_FILE, null, 'no var(--…) in any stylesheet', 'Write token values as CSS custom properties (--color-accent) and use var(--color-accent), so the inspector and kaloko tokens check see them.')
+  } else add('no-tokens', '.', null, 'no tokens.json in the folder', 'Add a W3C DTCG token set (kaloko tokens pull, or write tokens.json).')
+  // per step: everything under its folder plus the shared files (an upper bound of what a revision carries)
+  const tops = [...new Set([...files.keys()].filter((p) => p.includes('/')).map((p) => p.split('/')[0]))].filter((d) => d !== SHARED_DIR)
+  const shared = [...files].filter(([p]) => p.startsWith(`${SHARED_DIR}/`)).reduce((s, [, f]) => s + f.bytes, 0)
+  for (const d of tops) {
+    const own = [...files].filter(([p]) => p.startsWith(`${d}/`)).reduce((s, [, f]) => s + f.bytes, 0)
+    if (own + shared > BUNDLE_LIMITS.max_revision_bytes) add('too-large', `${d}/`, null, `${kb(own + shared)} with the shared files: over the ${Math.round(BUNDLE_LIMITS.max_revision_bytes / 1048576)} MB limit of a step`, 'Move big media out or compress it.')
+    else if (own + shared > BUDGET.step_bytes) add('large-file', `${d}/`, null, `${kb(own + shared)} with the shared files: over the ${kb(BUDGET.step_bytes)} budget of a step`, 'Compress images and fonts; drop unused files from _shared/.')
+    if (steps && !steps.includes(d)) add('stray-folder', `${d}/`, null, `${d}/ is not a step of the scenario`, 'Rename it to a step id, or move shared files into _shared/.')
+  }
+  if (steps) for (const s of steps) if (!has(`${s}/index.html`) && ![...files.keys()].some((p) => p.startsWith(`${s}/`) && p.endsWith('/index.html'))) add('missing-step', `${s}/`, null, `step ${s} has no ${s}/index.html`, `Add ${s}/index.html.`)
+  const order = { error: 0, warn: 1, info: 2 }
+  return out.sort((a, b) => order[a.level] - order[b.level] || a.file.localeCompare(b.file) || (a.line || 0) - (b.line || 0))
+}
+
+/** Reads a design folder (hidden files and .qawalk/ left out) into the shape lintFiles takes. */
+export async function readDesignFolder (dir) {
+  const files = new Map()
+  const walk = async (d) => {
+    let entries = []
+    try { entries = await readdir(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue
+      const full = join(d, e.name)
+      if (e.isDirectory()) { await walk(full); continue }
+      const path = relative(dir, full).split(sep).join('/')
+      const bytes = (await stat(full)).size
+      files.set(path, { bytes, ...(TEXT_TYPES.has(extOf(path)) && bytes <= BUNDLE_LIMITS.max_file_bytes ? { text: await readFile(full, 'utf8') } : {}) })
+    }
+  }
+  await walk(dir)
+  return files
+}
+
+/** Lints a design folder; `scenario` (optional) names the steps. */
+export async function lintDesign ({ dir, scenario = null }) {
+  const files = await readDesignFolder(dir)
+  const steps = scenario ? scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external').map((n) => n.id) : null
+  const findings = lintFiles(files, { steps })
+  return { dir, files: files.size, findings, errors: findings.filter((f) => f.level === 'error').length, warnings: findings.filter((f) => f.level === 'warn').length }
+}
+
+/** Human report: errors and warnings (info with `all`), grouped like a compiler, at most `max` lines. */
+export function formatLint (report, { all = false, max = 40, cwd = process.cwd() } = {}) {
+  const shown = report.findings.filter((f) => all || f.level !== 'info')
+  const where = relative(cwd, report.dir) || '.'
+  if (!shown.length) return `✓ ${where}: ${report.files} file(s) follow the portable HTML rules.`
+  const mark = { error: '✕', warn: '!', info: '·' }
+  const lines = shown.slice(0, max).map((f) => `  ${mark[f.level]} ${f.file}${f.line ? `:${f.line}` : ''}  ${f.message} [${f.rule}]${f.fix ? `\n      fix: ${f.fix}` : ''}`)
+  return `${where}: ${report.errors} error(s), ${report.warnings} warning(s)\n${lines.join('\n')}${shown.length > max ? `\n  … ${shown.length - max} more (kaloko design lint --json lists them all)` : ''}`
+}

package/src/lib/design.mjs

@@ -115,6 +115,13 @@ export async function copyLive (runDir, dir, rev) {
     await mkdir(dirname(to), { recursive: true })
     await copyFile(join(dir, path), to)
   }
+  // and one merged tree of the run (live/site/<path>, the design folder layout): plain links between steps work from
+  // disk there, so the local preview and an offline export present the prototype like the live origin does
+  for (const path of Object.keys(rev.files)) {
+    const to = join(runDir, 'live', 'site', path)
+    await mkdir(dirname(to), { recursive: true })
+    await copyFile(join(dir, path), to)
+  }
 }
 
 // ---- render cache: a capture is reused when the same revision was rendered in the same viewport ----

package/src/lib/evaluate.mjs

@@ -23,7 +23,7 @@ export function combine ({ node, capture, jev, thresholds }) {
     if (c.check.type === 'deterministic') {
       const r = capture.checks?.[c.id]
       const verdict = r == null || r.ok == null ? 'not_evaluated' : r.ok ? 'pass' : 'fail'
-      const live = c.check.assert === 'no_console_errors' || c.check.assert === 'no_overflow' || c.check.assert === 'http_status' || /^perf_/.test(c.check.assert || '')
+      const live = c.check.assert === 'no_console_errors' || c.check.assert === 'no_overflow' || c.check.assert === 'http_status' || c.check.assert === 'links_ok' || c.check.assert === 'hreflang_pairs' || /^perf_/.test(c.check.assert || '')
       return { id: c.id, type: 'deterministic', verdict, evidence: r?.evidence ?? null, ...(capture.rechecked_at && !live ? { rechecked: true } : {}) }
     }
     if (c.check.type === 'semantic' && c.check.about === 'console' && !(capture.console_errors || []).length && capture.checks) {

package/src/lib/linkcheck.mjs

@@ -0,0 +1,149 @@
+// Checks that need the network, evaluated next to the capture (not inside the page):
+//   links_ok        every same-origin link on the page answers below 400 (after redirects)
+//   hreflang_pairs  the page's hreflang alternates name the page itself for its own language, and every other
+//                   language version answers and links back (reciprocal pairs, as search engines require)
+// Requests are GETs (pages often do not implement HEAD) from a separate request context that starts with a copy of
+// the page's cookies and the environment's gate, and never writes back: following a link (or fetching /?lang=en for
+// hreflang) must not change the language, session or anything else the walk sees next. Links that look like they act
+// (log out, unsubscribe, delete, tokens, switching organization) are never followed, and links_ok follows links only
+// on readonly environments or scenarios unless the check opts in (follow: true). Results are cached per environment,
+// locale and sign-in state for the walk, so shared navigation is fetched once.
+
+const DEFAULT_MAX_LINKS = 100
+/** Links that may act when followed with a session: never fetched by the checks. */
+export const SKIP_LINK = /(?:^|[/?&=_.-])(?:token|unsubscribe|delete|remove|log-?out|sign-?out|switch)/i
+const actionLink = (u) => SKIP_LINK.test(u.pathname + u.search)
+
+/** Comparable form of a URL: origin, path without a trailing slash (except the root), sorted query, no hash. */
+export function normUrl (href, base) {
+  try {
+    const u = new URL(href, base)
+    u.hash = ''
+    const params = [...u.searchParams.entries()].sort(([a, x], [b, y]) => (a === b ? (x < y ? -1 : 1) : a < b ? -1 : 1))
+    const path = u.pathname.length > 1 ? u.pathname.replace(/\/+$/, '') : '/'
+    return `${u.origin}${path}${params.length ? '?' + new URLSearchParams(params).toString() : ''}`
+  } catch { return null }
+}
+
+/** `<link rel="alternate" hreflang href>` entries of an HTML document (attributes in any order). */
+export function parseAlternates (html, base) {
+  const out = []
+  for (const tag of String(html || '').match(/<link\b[^>]*>/gi) || []) {
+    const attr = (name) => tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'))?.slice(1).find((v) => v != null)
+    if (!/(^|\s)alternate(\s|$)/i.test(attr('rel') || '')) continue
+    const hreflang = attr('hreflang'); const href = attr('href')
+    if (hreflang && href) out.push({ hreflang: hreflang.toLowerCase(), href: new URL(href.replace(/&amp;/g, '&'), base).href })
+  }
+  return out
+}
+
+const short = (u, origin) => { try { const x = new URL(u); return x.origin === origin ? x.pathname + x.search : x.href } catch { return u } }
+
+/**
+ * links_ok: { links: [href], pageUrl, get(url) → { status, url, error? }, max?, exclude? } → { ok, evidence }.
+ * Only same-origin http(s) links count; fragments and the page itself are skipped.
+ */
+export async function checkLinks ({ links, pageUrl, get, max = DEFAULT_MAX_LINKS, exclude = null }) {
+  const origin = new URL(pageUrl).origin
+  const self = normUrl(pageUrl)
+  const skip = exclude ? new RegExp(exclude) : null
+  const targets = [...new Set(links.map((h) => { try { const u = new URL(h, pageUrl); u.hash = ''; return u.href } catch { return null } }).filter((h) => h && /^https?:/.test(h)))]
+    .filter((h) => new URL(h).origin === origin && normUrl(h) !== self && !actionLink(new URL(h)) && !(skip && skip.test(short(h, origin))))
+  const checked = targets.slice(0, max)
+  const broken = []; const redirected = []
+  for (const url of checked) {
+    const r = await get(url)
+    if (r.error || !(r.status < 400)) broken.push(`${short(url, origin)} → ${r.error || `HTTP ${r.status}`}`)
+    else if (r.url && normUrl(r.url) !== normUrl(url)) redirected.push(short(url, origin))
+  }
+  if (!checked.length) return { ok: true, evidence: 'no internal links on the page' }
+  const more = targets.length > checked.length ? ` (first ${checked.length} of ${targets.length})` : ''
+  const note = redirected.length ? `; ${redirected.length} redirect: ${redirected.slice(0, 3).join(', ')}` : ''
+  return broken.length
+    ? { ok: false, evidence: `${broken.length} of ${checked.length} internal links broken${more}: ${broken.slice(0, 5).join('; ')}${note}` }
+    : { ok: true, evidence: `${checked.length} internal links answer below 400${more}${note}` }
+}
+
+/**
+ * hreflang_pairs: { alternates: [{ hreflang, href }], pageUrl, lang, get(url) → { status, url, html?, error? }, min? }.
+ * Fails when there are fewer than `min` languages, when the page's own language does not point to the page, or
+ * when another language version does not answer 200 or does not link back to the page.
+ */
+export async function checkHreflang ({ alternates, pageUrl, lang, get, min = 2 }) {
+  const problems = []
+  const langs = alternates.filter((a) => a.hreflang !== 'x-default')
+  if (new Set(langs.map((a) => a.hreflang)).size < min) problems.push(`${new Set(langs.map((a) => a.hreflang)).size} hreflang language(s), expected ${min}`)
+  const self = normUrl(pageUrl)
+  const primary = String(lang || '').toLowerCase().split('-')[0]
+  const own = langs.find((a) => a.hreflang === String(lang || '').toLowerCase()) || langs.find((a) => a.hreflang.split('-')[0] === primary)
+  if (!primary) problems.push('html lang is not set, so the page\'s own hreflang cannot be identified')
+  else if (!own) problems.push(`no hreflang for the page's own language "${lang}"`)
+  else if (normUrl(own.href) !== self) problems.push(`hreflang ${own.hreflang} points to ${own.href}, not to this page (${pageUrl})`)
+  for (const alt of langs) {
+    if (alt === own) continue
+    if (actionLink(new URL(alt.href))) { problems.push(`${alt.hreflang} version ${alt.href} looks like an action link; not fetched`); continue }
+    const r = await get(alt.href, { html: true })
+    if (r.error || r.status !== 200) { problems.push(`${alt.hreflang} version ${alt.href} → ${r.error || `HTTP ${r.status}`}`); continue }
+    if (r.url && normUrl(r.url) !== normUrl(alt.href)) problems.push(`${alt.hreflang} version ${alt.href} redirects to ${r.url}`)
+    const back = parseAlternates(r.html, r.url || alt.href)
+    const mine = own ? own.hreflang : primary
+    const ret = back.find((b) => b.hreflang === mine) || back.find((b) => b.hreflang.split('-')[0] === primary)
+    if (!ret) problems.push(`${alt.hreflang} version does not link back with hreflang ${mine}`)
+    else if (normUrl(ret.href) !== self) problems.push(`${alt.hreflang} version links back to ${ret.href}, not to this page`)
+  }
+  return problems.length
+    ? { ok: false, evidence: problems.slice(0, 5).join('; ') }
+    : { ok: true, evidence: `${langs.map((a) => a.hreflang).join(', ')}: reciprocal, the own language points to this page` }
+}
+
+/**
+ * The environment's gate for the checks' own requests (set once per walk by the CLI): headers for the gate's origins
+ * only (third parties never see them), HTTP Basic credentials and client certificates.
+ */
+const GATE = { headers: {}, toGate: () => false, httpCredentials: null, clientCertificates: [] }
+export function configureGate ({ headers = {}, toGate = () => false, httpCredentials = null, clientCertificates = [] } = {}) {
+  Object.assign(GATE, { headers, toGate, httpCredentials, clientCertificates })
+}
+
+/**
+ * A request context of its own for the checks: a copy of the browser context's cookies and storage (so pages behind
+ * a sign-in answer as they do for the walker) that never writes back to the browser context.
+ * `factory` is Playwright's `request` (injectable for tests).
+ */
+export async function isolatedRequest (context, { factory = null } = {}) {
+  const storageState = await context.storageState()
+  const pw = factory || (await import('playwright')).request
+  return pw.newContext({
+    storageState,
+    ...(GATE.httpCredentials ? { httpCredentials: GATE.httpCredentials } : {}),
+    ...(GATE.clientCertificates?.length ? { clientCertificates: GATE.clientCertificates } : {})
+  })
+}
+
+/** Cache scope of a page: environment, locale and sign-in state (a digest of the cookies, never the cookies). */
+export function cacheScope ({ environment = '', locale = '', cookies = [] } = {}) {
+  const jar = cookies.map((c) => `${c.domain}|${c.path}|${c.name}=${c.value}`).sort().join(';')
+  let h = 0
+  for (let i = 0; i < jar.length; i++) h = (Math.imul(h, 31) + jar.charCodeAt(i)) | 0
+  return `${environment}|${locale}|${jar ? (h >>> 0).toString(36) : 'anonymous'}`
+}
+
+/** Cached GETs through a Playwright APIRequestContext (an isolated one, see isolatedRequest). */
+export function requester (request, cache = new Map(), scope = '') {
+  return async (url, { html = false } = {}) => {
+    const key = `${scope} ${html ? 'html' : 'status'} ${url}`
+    if (cache.has(key)) return cache.get(key)
+    const job = (async () => {
+      try {
+        const res = await request.get(url, { maxRedirects: 5, timeout: 15000, failOnStatusCode: false, ...(GATE.toGate(url) ? { headers: GATE.headers } : {}) })
+        return { status: res.status(), url: res.url(), ...(html ? { html: (await res.text()).slice(0, 500000) } : {}) }
+      } catch (error) { return { status: 0, error: String(error.message || error).split('\n')[0].slice(0, 120) } }
+    })()
+    cache.set(key, job)
+    return job
+  }
+}
+
+/** One cache per walk process: navigation links shared by hundreds of stack pages are fetched once. */
+export const walkCache = new Map()
+export const NETWORK_ASSERTS = new Set(['links_ok', 'hreflang_pairs'])

package/src/lib/recheck.mjs

@@ -13,7 +13,7 @@ import { contextOptions, prepareContext } from './access.mjs'
 import { launchEphemeral } from './browser.mjs'
 import { treeChecks } from './apps/tree.mjs'
 
-export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || /^perf_/.test(assert)
+export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || assert === 'links_ok' || assert === 'hreflang_pairs' || /^perf_/.test(assert)
 
 const withBase = (html, url) => {
   if (!url || /<base\s/i.test(html)) return html

package/src/lib/run.mjs

@@ -36,7 +36,7 @@ export async function createRun ({ output, scenario, scenarioFile, env, scope, g
     id,
     short,
     scenario_file: relative(root, scenarioFile),
-    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}) },
+    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.readonly ? { readonly: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}) },
     environment: { name: env.name, base_url: env.base_url, readonly: env.readonly, ...(env.kind === 'design' ? { kind: 'design' } : {}) },
     scope,
     git,

package/src/lib/zip.mjs

@@ -0,0 +1,58 @@
+// Streaming ZIP writer (method "store", data descriptors) for run and design exports, shared by the service and the CLI.
+// Files are appended as they are read from R2; nothing is buffered beyond one chunk.
+
+const CRC_TABLE = (() => { const t = new Uint32Array(256); for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0 } return t })()
+export function crc32 (crc, bytes) { crc = ~crc; for (let i = 0; i < bytes.length; i++) crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8); return ~crc >>> 0 }
+
+const enc = new TextEncoder()
+const u16 = (v, out, o) => { out[o] = v & 0xff; out[o + 1] = (v >>> 8) & 0xff }
+const u32 = (v, out, o) => { out[o] = v & 0xff; out[o + 1] = (v >>> 8) & 0xff; out[o + 2] = (v >>> 16) & 0xff; out[o + 3] = (v >>> 24) & 0xff }
+const dosTime = (d) => ({ time: (d.getUTCHours() << 11) | (d.getUTCMinutes() << 5) | (d.getUTCSeconds() >> 1), date: ((d.getUTCFullYear() - 1980) << 9) | ((d.getUTCMonth() + 1) << 5) | d.getUTCDate() })
+
+/**
+ * @param {Array<{ name: string, body: ReadableStream|Uint8Array|string, modified?: Date }>} entries lazily opened: `body` may be a function returning a promise of the stream
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function zipStream (entries) {
+  const central = []
+  let offset = 0
+  let i = 0
+  const now = new Date()
+  return new ReadableStream({
+    async pull (controller) {
+      const push = (bytes) => { controller.enqueue(bytes); offset += bytes.length }
+      if (i < entries.length) {
+        const e = entries[i++]
+        const name = enc.encode(e.name)
+        const { time, date } = dosTime(e.modified || now)
+        const local = new Uint8Array(30 + name.length)
+        u32(0x04034b50, local, 0); u16(20, local, 4); u16(0x0808, local, 6) /* bit 3: sizes in the descriptor, bit 11: UTF-8 */; u16(0, local, 8); u16(time, local, 10); u16(date, local, 12)
+        u32(0, local, 14); u32(0, local, 18); u32(0, local, 22); u16(name.length, local, 26); u16(0, local, 28); local.set(name, 30)
+        const start = offset
+        push(local)
+        let body = typeof e.body === 'function' ? await e.body() : e.body
+        let crc = 0, size = 0
+        if (typeof body === 'string') body = enc.encode(body)
+        if (body instanceof Uint8Array) { crc = crc32(crc, body); size = body.length; push(body) } else if (body) {
+          const reader = body.getReader()
+          for (;;) { const { done, value } = await reader.read(); if (done) break; crc = crc32(crc, value); size += value.length; push(value) }
+        }
+        const desc = new Uint8Array(16); u32(0x08074b50, desc, 0); u32(crc, desc, 4); u32(size, desc, 8); u32(size, desc, 12); push(desc)
+        central.push({ name, crc, size, time, date, start })
+        return
+      }
+      // central directory
+      const cdStart = offset
+      for (const c of central) {
+        const h = new Uint8Array(46 + c.name.length)
+        u32(0x02014b50, h, 0); u16(20, h, 4); u16(20, h, 6); u16(0x0808, h, 8); u16(0, h, 10); u16(c.time, h, 12); u16(c.date, h, 14)
+        u32(c.crc, h, 16); u32(c.size, h, 20); u32(c.size, h, 24); u16(c.name.length, h, 28); u16(0, h, 30); u16(0, h, 32); u16(0, h, 34); u16(0, h, 36); u32(0, h, 38); u32(c.start, h, 42); h.set(c.name, 46)
+        push(h)
+      }
+      const end = new Uint8Array(22)
+      u32(0x06054b50, end, 0); u16(0, end, 4); u16(0, end, 6); u16(central.length, end, 8); u16(central.length, end, 10); u32(offset - cdStart, end, 12); u32(cdStart, end, 16); u16(0, end, 20)
+      push(end)
+      controller.close()
+    }
+  })
+}