@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/dev.mjs

@@ -1,459 +1,459 @@
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { createServer } from 'node:http';
-import { join } from 'node:path';
-import { TEMPLATES } from './create.mjs';
-
-const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
-export const DEFAULT_APP_URL = 'http://localhost:3100/';
-export const DEFAULT_PORT = 3200;
-const DEFAULT_HAWKSEARCH_DOMAIN = 'https://dev.hawksearch.net';
-/** Tokens are reused until this close to expiry. */
-const TOKEN_SKEW_MS = 60_000;
-const MAX_PROXY_BODY = 10 * 1024 * 1024;
-
-/**
- * `hawk-app dev`: a local stand-in for the HawkSearch host. Serves a page that embeds the app (its dev server) with the
- * bridge's own `<hawk-app-frame>`, gets real app tokens from the platform with the publisher key
- * (`POST /publish/apps/{slug}/dev-token`, any client), and proxies the app's platform calls (so no CORS setup is needed,
- * on dev or prod). Nothing is written to disk; the HawkSearch API key, if any, comes from the environment.
- */
-export async function devCommand({ client, manifest, flags = {}, projectDir = process.cwd(), env = process.env, log = console.log, signal, startDev = npmRunDev, waitForApp = waitForUrl }) {
-    const clientId = flags.client ?? env.HAWK_APPS_DEV_CLIENT;
-    if (!clientId || clientId === true) {
-        throw new Error('Usage: hawk-app dev --client <client id> [--engine <id>] [--url http://localhost:3100] [--port 3200] [--client-user] [--no-start]\n'
-            + '  (or set HAWK_APPS_DEV_CLIENT in .env.local)');
-    }
-    const engineId = flags.engine ?? env.HAWK_APPS_DEV_ENGINE ?? null;
-    const appUrl = normalizeAppUrl(typeof flags.url === 'string' ? flags.url : defaultAppUrl(projectDir, manifest));
-    const port = Number(flags.port ?? DEFAULT_PORT);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port must be a port number.');
-    const hawkSearch = env.HAWKSEARCH_API_KEY
-        ? { domain: (env.HAWKSEARCH_DOMAIN || DEFAULT_HAWKSEARCH_DOMAIN).replace(/\/+$/, ''), apiKey: env.HAWKSEARCH_API_KEY, isGroupKey: env.HAWKSEARCH_GROUP_KEY === 'true' }
-        : null;
-
-    const hostScript = await bundleHost(projectDir);
-    const tokens = tokenBroker({ client, slug: manifest.slug, hawkSearch });
-    const settings = { slug: manifest.slug, name: manifest.name ?? manifest.slug, appUrl, clientId: String(clientId), engineId: engineId ? String(engineId) : null, internal: !flags['client-user'] };
-
-    // The app's dev server, unless it runs already (--url) or --no-start.
-    let child = null;
-    if (!flags.url && !flags['no-start']) {
-        log(`› Starting the app: npm run dev (in ${projectDir})`);
-        child = startDev({ cwd: projectDir });
-    }
-
-    const server = createHostServer({ settings, hostScript, tokens, platformBase: client.base, log });
-    await new Promise((resolve, reject) => {
-        server.once('error', (error) => reject(error.code === 'EADDRINUSE' ? new Error(`Port ${port} is in use: pick another with --port.`) : error));
-        server.listen(port, '127.0.0.1', resolve);
-    });
-
-    log(`› Waiting for the app at ${appUrl} …`);
-    const ready = await waitForApp(appUrl, { signal });
-    if (!ready) log(`! ${appUrl} didn't answer yet; the page will load it when it does.`);
-    log('');
-    log(`✔ Local host: http://localhost:${port}/`);
-    log(`  app ${settings.slug} from ${appUrl}, client ${settings.clientId}${settings.engineId ? `, site ${settings.engineId}` : ''}, as a ${settings.internal ? 'Bridgeline' : 'client'} user`);
-    log(`  platform ${client.base} (real data)${hawkSearch ? `; HawkSearch ${hawkSearch.domain} with HAWKSEARCH_API_KEY` : '; no HawkSearch key (set HAWKSEARCH_API_KEY for the dashboard API)'}`);
-    log('  Change the client, site, user, dates and theme in the page. Ctrl+C to stop.');
-
-    await new Promise((resolve) => {
-        const stop = () => resolve();
-        signal?.addEventListener('abort', stop, { once: true });
-        process.once('SIGINT', stop);
-    });
-    server.close();
-    child?.kill();
-    return 0;
-}
-
-/**
- * Where the app's dev server serves it: the template's URL (Next.js serves the app under /<slug>/ only), else
- * /<slug>/ for a Next.js app, else the root (Vite redirects it to its base).
- */
-export function defaultAppUrl(projectDir, manifest) {
-    const template = TEMPLATES[manifest.template];
-    if (template) return template.devUrl(manifest.slug);
-    try {
-        const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
-        if ({ ...pkg.dependencies, ...pkg.devDependencies }.next) return `http://localhost:3100/${manifest.slug}/`;
-    } catch {
-        // No package.json: the root.
-    }
-    return DEFAULT_APP_URL;
-}
-
-/** `http://localhost:3100` → `http://localhost:3100/`; only http(s) URLs. */
-export function normalizeAppUrl(value) {
-    let url;
-    try {
-        url = new URL(value);
-    } catch {
-        throw new Error(`--url must be the app's dev server URL, e.g. ${DEFAULT_APP_URL}`);
-    }
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('--url must be an http(s) URL.');
-    return url.toString();
-}
-
-/** App tokens from the platform, cached per client, site and user kind until a minute before they expire. */
-export function tokenBroker({ client, slug, hawkSearch, now = () => Date.now() }) {
-    const cache = new Map();
-    return async ({ clientId, engineId, internal, forceRefresh = false }) => {
-        const key = `${clientId}|${engineId ?? ''}|${internal}`;
-        const cached = cache.get(key);
-        if (!forceRefresh && cached && Date.parse(cached.expiresAt) - TOKEN_SKEW_MS > now()) return cached;
-        const issued = await client.devToken(slug, { clientId, engineId: engineId || null, internal, ...(hawkSearch ? { hawkSearch } : {}) });
-        cache.set(key, issued);
-        return issued;
-    };
-}
-
-/** The bridge's host side (`<hawk-app-frame>`) from the app's own bridge, bundled for the browser. */
-export async function bundleHost(projectDir) {
-    const esbuild = await import('esbuild');
-    try {
-        // esbuild resolves the package the way the browser build would (its "import" export).
-        const result = await esbuild.build({
-            stdin: { contents: `export { defineHawkAppFrame } from '${BRIDGE_PACKAGE}/host';`, resolveDir: projectDir, loader: 'js' },
-            bundle: true,
-            format: 'esm',
-            platform: 'browser',
-            target: 'es2020',
-            write: false,
-            logLevel: 'silent',
-        });
-        return result.outputFiles[0].text;
-    } catch {
-        throw new Error(`hawk-app dev needs ${BRIDGE_PACKAGE} (0.4.0 or later) in the app: run \`npm install ${BRIDGE_PACKAGE}\`.`);
-    }
-}
-
-/**
- * The local host: `/` (the page), `/host.js` (the bridge's host side), `POST /token` (from the page only), `/api/*`
- * (the platform, for the app; CORS for the app's origin only) and `POST /ai-stream` (the AI stream, see `proxyAiStream`).
- */
-export function createHostServer({ settings, hostScript, tokens, platformBase, log = console.log, fetchImpl = fetch }) {
-    const appOrigin = new URL(settings.appUrl).origin;
-    // The real AI stream URL from the platform's last `GET ai` answer, which the app is told is `/ai-stream` here.
-    const ai = { streamUrl: null };
-    const server = createServer(async (req, res) => {
-        try {
-            const port = server.address().port;
-            // Only requests to this machine by name (a DNS-rebound site has its own host name).
-            if (![`localhost:${port}`, `127.0.0.1:${port}`].includes(req.headers.host ?? '')) return send(res, 421, 'text/plain', 'Misdirected request');
-            const hostOrigin = `http://${req.headers.host}`;
-            const url = new URL(req.url ?? '/', hostOrigin);
-            if (req.method === 'GET' && url.pathname === '/') {
-                return send(res, 200, 'text/html; charset=utf-8', hostPage(settings));
-            }
-            if (req.method === 'GET' && url.pathname === '/host.js') {
-                return send(res, 200, 'text/javascript; charset=utf-8', hostScript);
-            }
-            if (url.pathname === '/token') {
-                // Only the local page may ask for tokens (a page on another site can't, even from this machine).
-                if (req.method !== 'POST' || !sameOrigin(req, hostOrigin)) return send(res, 403, 'application/json', JSON.stringify({ error: 'forbidden' }));
-                const body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}');
-                const issued = await tokens({ clientId: String(body.clientId ?? ''), engineId: body.engineId ? String(body.engineId) : null, internal: body.internal !== false, forceRefresh: !!body.forceRefresh });
-                return send(res, 200, 'application/json', JSON.stringify(issued));
-            }
-            if (url.pathname.startsWith('/api/')) {
-                return proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, fetchImpl });
-            }
-            if (url.pathname === '/ai-stream') {
-                return proxyAiStream(req, res, { appOrigin, ai, fetchImpl });
-            }
-            send(res, 404, 'text/plain', 'Not found');
-        } catch (error) {
-            log(`! ${error.message.split('\n')[0]}`);
-            send(res, error.status ?? 500, 'application/json', JSON.stringify({ error: error.message, ...(error.data?.code ? { code: error.data.code } : {}) }));
-        }
-    });
-    return server;
-}
-
-function sameOrigin(req, hostOrigin) {
-    return req.headers.origin === hostOrigin;
-}
-
-function corsHeaders(appOrigin, methods) {
-    return {
-        'Access-Control-Allow-Origin': appOrigin,
-        'Access-Control-Allow-Methods': methods,
-        'Access-Control-Allow-Headers': 'Authorization, Accept, Content-Type',
-        'Access-Control-Expose-Headers': 'Retry-After',
-        'Access-Control-Max-Age': '600',
-        Vary: 'Origin',
-    };
-}
-
-/** Only the headers the platform needs: Authorization, Content-Type and Accept. */
-function forwardHeaders(req, accept) {
-    const headers = { Accept: req.headers.accept ?? accept };
-    if (req.headers.authorization) headers.Authorization = req.headers.authorization;
-    if (req.headers['content-type']) headers['Content-Type'] = req.headers['content-type'];
-    return headers;
-}
-
-/**
- * The app's platform calls, sent on with only the headers the platform needs. The answer to `GET ai` has its
- * `streamUrl` (a Lambda function URL, whose CORS doesn't allow this page) replaced with this host's `/ai-stream`.
- */
-async function proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, fetchImpl }) {
-    const cors = corsHeaders(appOrigin, 'GET, POST, PUT, DELETE');
-    if (req.method === 'OPTIONS') {
-        res.writeHead(204, cors);
-        return res.end();
-    }
-    const body = ['GET', 'HEAD'].includes(req.method) ? undefined : await readBody(req, MAX_PROXY_BODY);
-    const target = `${platformBase}${url.pathname.slice('/api'.length)}${url.search}`;
-    const response = await fetchImpl(target, { method: req.method, headers: forwardHeaders(req, 'application/json'), body });
-    const out = { ...cors, 'Content-Type': response.headers.get('content-type') ?? 'application/json', 'Cache-Control': 'no-store' };
-    if (response.headers.has('retry-after')) out['Retry-After'] = response.headers.get('retry-after');
-    let payload = Buffer.from(await response.arrayBuffer());
-    if (req.method === 'GET' && response.ok && /^\/api\/v\d+\/ai$/.test(url.pathname)) {
-        payload = rewriteAiDiscovery(payload, `${hostOrigin}/ai-stream`, ai);
-    }
-    res.writeHead(response.status, out);
-    res.end(payload);
-}
-
-/** A real AI stream URL: https on a Lambda function URL host (`*.on.aws`), path `/v1/ai/messages`, nothing else. */
-export function isAiStreamUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && url.hostname.endsWith('.on.aws') && !url.port && !url.username && !url.password
-            && url.pathname === '/v1/ai/messages' && !url.search && !url.hash;
-    } catch {
-        return false;
-    }
-}
-
-/**
- * Remembers the `streamUrl` of a `GET ai` answer and points the app at `localStream` instead. Any other stream URL
- * (e.g. a local platform's own) is left as it is and never proxied.
- */
-function rewriteAiDiscovery(payload, localStream, ai) {
-    let body;
-    try {
-        body = JSON.parse(payload.toString('utf8'));
-    } catch {
-        return payload;
-    }
-    if (!body || !isAiStreamUrl(body.streamUrl)) return payload;
-    ai.streamUrl = body.streamUrl;
-    return Buffer.from(JSON.stringify({ ...body, streamUrl: localStream }));
-}
-
-/**
- * `POST /ai-stream`: the app's AI request, sent on to the stream URL remembered from `GET ai`, with the event stream
- * piped back as it arrives (not buffered). Stops the upstream request when the app goes away.
- */
-async function proxyAiStream(req, res, { appOrigin, ai, fetchImpl }) {
-    const cors = corsHeaders(appOrigin, 'POST');
-    if (req.method === 'OPTIONS') {
-        res.writeHead(204, cors);
-        return res.end();
-    }
-    if (req.method !== 'POST') {
-        res.writeHead(405, { ...cors, Allow: 'POST', 'Content-Type': 'text/plain' });
-        return res.end('Method not allowed');
-    }
-    if (!ai.streamUrl) {
-        res.writeHead(503, { ...cors, 'Content-Type': 'application/problem+json', 'Cache-Control': 'no-store' });
-        return res.end(JSON.stringify({ status: 503, code: 'ai_not_configured', detail: 'No AI stream URL yet: the app must call GET ai first.' }));
-    }
-    const body = await readBody(req, MAX_PROXY_BODY);
-    const upstream = new AbortController();
-    res.on('close', () => {
-        if (!res.writableFinished) upstream.abort();
-    });
-    const response = await fetchImpl(ai.streamUrl, { method: 'POST', headers: forwardHeaders(req, 'text/event-stream'), body, signal: upstream.signal });
-    const out = { ...cors, 'Content-Type': response.headers.get('content-type') ?? 'text/event-stream', 'Cache-Control': 'no-store' };
-    if (response.headers.has('retry-after')) out['Retry-After'] = response.headers.get('retry-after');
-    res.writeHead(response.status, out);
-    res.flushHeaders();
-    try {
-        for await (const chunk of response.body ?? []) {
-            res.write(chunk);
-        }
-    } catch {
-        // The app went away (or the stream broke): nothing more to send.
-    }
-    res.end();
-}
-
-function readBody(req, limit) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let size = 0;
-        req.on('data', (chunk) => {
-            size += chunk.length;
-            if (size > limit) {
-                reject(Object.assign(new Error('Request body too large.'), { status: 413 }));
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => resolve(Buffer.concat(chunks)));
-        req.on('error', reject);
-    });
-}
-
-function send(res, status, type, body) {
-    res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
-    res.end(body);
-}
-
-/** Runs the app's `npm run dev` (its own output stays visible). */
-export function npmRunDev({ cwd }) {
-    return spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'dev'], { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
-}
-
-/** Polls the URL until it answers (any status), up to `timeoutMs`. */
-export async function waitForUrl(url, { timeoutMs = 60_000, intervalMs = 500, signal, fetchImpl = fetch } = {}) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline && !signal?.aborted) {
-        try {
-            await fetchImpl(url, { method: 'GET', signal: AbortSignal.timeout(2000) });
-            return true;
-        } catch {
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
-        }
-    }
-    return false;
-}
-
-const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
-
-/** The host page: a toolbar (client, site, user, dates, theme), the app, and panels for toasts, events and the token. */
-export function hostPage(settings) {
-    const today = new Date();
-    const from = new Date(today.getTime() - 29 * 86_400_000);
-    const initial = { ...settings, from: from.toISOString().slice(0, 10), to: today.toISOString().slice(0, 10), theme: 'light' };
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(settings.name)} · hawk-app dev</title>
-<style>
-  :root { --bg: #f6f7f9; --panel: #fff; --text: #1d2330; --muted: #667085; --border: #d0d5dd; --accent: #f26b1d; }
-  body { margin: 0; font: 14px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--text); }
-  body.dark { --bg: #14171c; --panel: #1d2128; --text: #e6e8eb; --muted: #98a2b3; --border: #343a46; }
-  header { display: flex; flex-wrap: wrap; gap: 10px; align-items: end; padding: 10px 16px; background: var(--panel); border-bottom: 1px solid var(--border); }
-  header h1 { font-size: 16px; margin: 0 16px 6px 0; }
-  header h1 small { color: var(--muted); font-weight: normal; }
-  label { display: flex; flex-direction: column; font-size: 12px; color: var(--muted); gap: 2px; }
-  input, select, button { font: inherit; padding: 4px 8px; border: 1px solid var(--border); border-radius: 4px; background: var(--panel); color: var(--text); }
-  button { cursor: pointer; } button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
-  main { display: grid; grid-template-columns: 1fr 340px; gap: 12px; padding: 12px 16px; }
-  #title { font-size: 18px; margin: 0 0 8px; }
-  hawk-app-frame { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; min-height: 400px; }
-  aside section { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; margin-bottom: 12px; }
-  aside h2 { font-size: 13px; margin: 0 0 6px; }
-  aside pre { white-space: pre-wrap; word-break: break-all; font-size: 11px; margin: 0; max-height: 260px; overflow: auto; }
-  #events div { font-size: 12px; border-top: 1px solid var(--border); padding: 3px 0; }
-  #toasts { position: fixed; right: 16px; bottom: 16px; display: flex; flex-direction: column; gap: 8px; }
-  .toast { padding: 8px 12px; border-radius: 4px; color: #fff; background: #344054; box-shadow: 0 2px 6px rgba(0,0,0,.2); }
-  .toast.success { background: #12b76a; } .toast.warning { background: #f79009; } .toast.error { background: #f04438; }
-  @media (max-width: 900px) { main { grid-template-columns: 1fr; } }
-</style>
-</head>
-<body>
-<header>
-  <h1>${escapeHtml(settings.name)} <small>hawk-app dev</small></h1>
-  <label>Client <input id="clientId" size="10"></label>
-  <label>Site (engine) <input id="engineId" size="8" placeholder="none"></label>
-  <label>User <select id="internal"><option value="true">Bridgeline user</option><option value="false">Client user</option></select></label>
-  <label>From <input id="from" type="date"></label>
-  <label>To <input id="to" type="date"></label>
-  <label>Theme <select id="theme"><option>light</option><option>dark</option></select></label>
-  <button class="primary" id="apply">Apply</button>
-  <button id="reload">Reload app</button>
-</header>
-<main>
-  <div>
-    <p id="title"></p>
-    <hawk-app-frame id="frame" title="${escapeHtml(settings.name)}"></hawk-app-frame>
-  </div>
-  <aside>
-    <section><h2>Token</h2><pre id="token">—</pre></section>
-    <section><h2>Messages from the app</h2><div id="events"></div></section>
-  </aside>
-</main>
-<div id="toasts"></div>
-<script type="module">
-  import { defineHawkAppFrame } from '/host.js';
-  defineHawkAppFrame();
-  const initial = ${JSON.stringify(initial).replace(/</g, '\\u003c')};
-  const $ = (id) => document.getElementById(id);
-  const frame = $('frame');
-  let state = { ...initial };
-  for (const key of ['clientId', 'engineId', 'from', 'to', 'theme']) $(key).value = state[key] ?? '';
-  $('internal').value = String(state.internal);
-
-  const event = (text) => { const row = document.createElement('div'); row.textContent = new Date().toLocaleTimeString() + '  ' + text; $('events').prepend(row); };
-  const claims = (token) => JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
-
-  function context(token) {
-    const c = claims(token);
-    return {
-      protocolVersion: 1,
-      app: { slug: state.slug },
-      tenant: { clientId: state.clientId },
-      user: { id: c.sub, roles: [] },
-      engine: state.engineId ? { id: state.engineId } : null,
-      site: state.engineId ? { id: state.engineId } : null,
-      dateRange: { from: state.from, to: state.to },
-      locale: navigator.language || 'en-US',
-      theme: { mode: state.theme, tokens: {} },
-      apiBaseUrl: location.origin + '/api/v1/',
-    };
-  }
-
-  async function token(forceRefresh) {
-    const res = await fetch('/token', { method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ clientId: state.clientId, engineId: state.engineId || null, internal: state.internal, forceRefresh }) });
-    const body = await res.json();
-    if (!res.ok) { event('token: ' + (body.error || res.status)); throw new Error(body.error || 'No token'); }
-    const c = claims(body.token);
-    $('token').textContent = JSON.stringify({ expiresAt: body.expiresAt, version: body.version, user: c.sub, client: c.client_id, engine: c.engine ?? null,
-      internal: c.internal, scopes: c.scope, hawksearch: body.hawkSearch }, null, 2);
-    return body;
-  }
-
-  frame.tokenProvider = async ({ forceRefresh }) => { const t = await token(forceRefresh); return { token: t.token, expiresAt: t.expiresAt }; };
-  frame.addEventListener('hawk-ready', () => event('ready'));
-  frame.addEventListener('hawk-title', (e) => { $('title').textContent = e.detail.title; document.title = e.detail.title + ' · hawk-app dev'; event('setTitle: ' + e.detail.title); });
-  frame.addEventListener('hawk-navigate', (e) => event('navigate: ' + JSON.stringify(e.detail)));
-  frame.addEventListener('hawk-toast', (e) => {
-    const t = document.createElement('div'); t.className = 'toast ' + (e.detail.variant || 'info'); t.textContent = e.detail.message;
-    $('toasts').append(t); setTimeout(() => t.remove(), 5000); event('toast (' + (e.detail.variant || 'info') + '): ' + e.detail.message);
-  });
-
-  async function load(reloadApp) {
-    document.body.classList.toggle('dark', state.theme === 'dark');
-    const t = await token(false).catch(() => null);
-    if (!t) return;
-    frame.context = context(t.token);
-    if (reloadApp) { frame.removeAttribute('src'); frame.setAttribute('src', initial.appUrl); }
-  }
-
-  $('apply').addEventListener('click', () => {
-    const before = state;
-    state = { ...state, clientId: $('clientId').value.trim(), engineId: $('engineId').value.trim(), internal: $('internal').value === 'true',
-      from: $('from').value, to: $('to').value, theme: $('theme').value };
-    // A new client, site or user needs a new token: reload the app; dates and theme are context changes.
-    const identity = (s) => s.clientId + '|' + s.engineId + '|' + s.internal;
-    load(identity(before) !== identity(state));
-    event('context: ' + state.clientId + (state.engineId ? ' / site ' + state.engineId : '') + ' · ' + state.from + '..' + state.to + ' · ' + state.theme);
-  });
-  $('reload').addEventListener('click', () => load(true));
-  load(true);
-</script>
-</body>
-</html>
-`;
-}
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { TEMPLATES } from './create.mjs';
+
+const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
+export const DEFAULT_APP_URL = 'http://localhost:3100/';
+export const DEFAULT_PORT = 3200;
+const DEFAULT_HAWKSEARCH_DOMAIN = 'https://dev.hawksearch.net';
+/** Tokens are reused until this close to expiry. */
+const TOKEN_SKEW_MS = 60_000;
+const MAX_PROXY_BODY = 10 * 1024 * 1024;
+
+/**
+ * `hawk-app dev`: a local stand-in for the HawkSearch host. Serves a page that embeds the app (its dev server) with the
+ * bridge's own `<hawk-app-frame>`, gets real app tokens from the platform with the publisher key
+ * (`POST /publish/apps/{slug}/dev-token`, any client), and proxies the app's platform calls (so no CORS setup is needed,
+ * on dev or prod). Nothing is written to disk; the HawkSearch API key, if any, comes from the environment.
+ */
+export async function devCommand({ client, manifest, flags = {}, projectDir = process.cwd(), env = process.env, log = console.log, signal, startDev = npmRunDev, waitForApp = waitForUrl }) {
+    const clientId = flags.client ?? env.HAWK_APPS_DEV_CLIENT;
+    if (!clientId || clientId === true) {
+        throw new Error('Usage: hawk-app dev --client <client id> [--engine <id>] [--url http://localhost:3100] [--port 3200] [--client-user] [--no-start]\n'
+            + '  (or set HAWK_APPS_DEV_CLIENT in .env.local)');
+    }
+    const engineId = flags.engine ?? env.HAWK_APPS_DEV_ENGINE ?? null;
+    const appUrl = normalizeAppUrl(typeof flags.url === 'string' ? flags.url : defaultAppUrl(projectDir, manifest));
+    const port = Number(flags.port ?? DEFAULT_PORT);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port must be a port number.');
+    const hawkSearch = env.HAWKSEARCH_API_KEY
+        ? { domain: (env.HAWKSEARCH_DOMAIN || DEFAULT_HAWKSEARCH_DOMAIN).replace(/\/+$/, ''), apiKey: env.HAWKSEARCH_API_KEY, isGroupKey: env.HAWKSEARCH_GROUP_KEY === 'true' }
+        : null;
+
+    const hostScript = await bundleHost(projectDir);
+    const tokens = tokenBroker({ client, slug: manifest.slug, hawkSearch });
+    const settings = { slug: manifest.slug, name: manifest.name ?? manifest.slug, appUrl, clientId: String(clientId), engineId: engineId ? String(engineId) : null, internal: !flags['client-user'] };
+
+    // The app's dev server, unless it runs already (--url) or --no-start.
+    let child = null;
+    if (!flags.url && !flags['no-start']) {
+        log(`› Starting the app: npm run dev (in ${projectDir})`);
+        child = startDev({ cwd: projectDir });
+    }
+
+    const server = createHostServer({ settings, hostScript, tokens, platformBase: client.base, log });
+    await new Promise((resolve, reject) => {
+        server.once('error', (error) => reject(error.code === 'EADDRINUSE' ? new Error(`Port ${port} is in use: pick another with --port.`) : error));
+        server.listen(port, '127.0.0.1', resolve);
+    });
+
+    log(`› Waiting for the app at ${appUrl} …`);
+    const ready = await waitForApp(appUrl, { signal });
+    if (!ready) log(`! ${appUrl} didn't answer yet; the page will load it when it does.`);
+    log('');
+    log(`✔ Local host: http://localhost:${port}/`);
+    log(`  app ${settings.slug} from ${appUrl}, client ${settings.clientId}${settings.engineId ? `, site ${settings.engineId}` : ''}, as a ${settings.internal ? 'Bridgeline' : 'client'} user`);
+    log(`  platform ${client.base} (real data)${hawkSearch ? `; HawkSearch ${hawkSearch.domain} with HAWKSEARCH_API_KEY` : '; no HawkSearch key (set HAWKSEARCH_API_KEY for the dashboard API)'}`);
+    log('  Change the client, site, user, dates and theme in the page. Ctrl+C to stop.');
+
+    await new Promise((resolve) => {
+        const stop = () => resolve();
+        signal?.addEventListener('abort', stop, { once: true });
+        process.once('SIGINT', stop);
+    });
+    server.close();
+    child?.kill();
+    return 0;
+}
+
+/**
+ * Where the app's dev server serves it: the template's URL (Next.js serves the app under /<slug>/ only), else
+ * /<slug>/ for a Next.js app, else the root (Vite redirects it to its base).
+ */
+export function defaultAppUrl(projectDir, manifest) {
+    const template = TEMPLATES[manifest.template];
+    if (template) return template.devUrl(manifest.slug);
+    try {
+        const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+        if ({ ...pkg.dependencies, ...pkg.devDependencies }.next) return `http://localhost:3100/${manifest.slug}/`;
+    } catch {
+        // No package.json: the root.
+    }
+    return DEFAULT_APP_URL;
+}
+
+/** `http://localhost:3100` → `http://localhost:3100/`; only http(s) URLs. */
+export function normalizeAppUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new Error(`--url must be the app's dev server URL, e.g. ${DEFAULT_APP_URL}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('--url must be an http(s) URL.');
+    return url.toString();
+}
+
+/** App tokens from the platform, cached per client, site and user kind until a minute before they expire. */
+export function tokenBroker({ client, slug, hawkSearch, now = () => Date.now() }) {
+    const cache = new Map();
+    return async ({ clientId, engineId, internal, forceRefresh = false }) => {
+        const key = `${clientId}|${engineId ?? ''}|${internal}`;
+        const cached = cache.get(key);
+        if (!forceRefresh && cached && Date.parse(cached.expiresAt) - TOKEN_SKEW_MS > now()) return cached;
+        const issued = await client.devToken(slug, { clientId, engineId: engineId || null, internal, ...(hawkSearch ? { hawkSearch } : {}) });
+        cache.set(key, issued);
+        return issued;
+    };
+}
+
+/** The bridge's host side (`<hawk-app-frame>`) from the app's own bridge, bundled for the browser. */
+export async function bundleHost(projectDir) {
+    const esbuild = await import('esbuild');
+    try {
+        // esbuild resolves the package the way the browser build would (its "import" export).
+        const result = await esbuild.build({
+            stdin: { contents: `export { defineHawkAppFrame } from '${BRIDGE_PACKAGE}/host';`, resolveDir: projectDir, loader: 'js' },
+            bundle: true,
+            format: 'esm',
+            platform: 'browser',
+            target: 'es2020',
+            write: false,
+            logLevel: 'silent',
+        });
+        return result.outputFiles[0].text;
+    } catch {
+        throw new Error(`hawk-app dev needs ${BRIDGE_PACKAGE} (0.4.0 or later) in the app: run \`npm install ${BRIDGE_PACKAGE}\`.`);
+    }
+}
+
+/**
+ * The local host: `/` (the page), `/host.js` (the bridge's host side), `POST /token` (from the page only), `/api/*`
+ * (the platform, for the app; CORS for the app's origin only) and `POST /ai-stream` (the AI stream, see `proxyAiStream`).
+ */
+export function createHostServer({ settings, hostScript, tokens, platformBase, log = console.log, fetchImpl = fetch }) {
+    const appOrigin = new URL(settings.appUrl).origin;
+    // The real AI stream URL from the platform's last `GET ai` answer, which the app is told is `/ai-stream` here.
+    const ai = { streamUrl: null };
+    const server = createServer(async (req, res) => {
+        try {
+            const port = server.address().port;
+            // Only requests to this machine by name (a DNS-rebound site has its own host name).
+            if (![`localhost:${port}`, `127.0.0.1:${port}`].includes(req.headers.host ?? '')) return send(res, 421, 'text/plain', 'Misdirected request');
+            const hostOrigin = `http://${req.headers.host}`;
+            const url = new URL(req.url ?? '/', hostOrigin);
+            if (req.method === 'GET' && url.pathname === '/') {
+                return send(res, 200, 'text/html; charset=utf-8', hostPage(settings));
+            }
+            if (req.method === 'GET' && url.pathname === '/host.js') {
+                return send(res, 200, 'text/javascript; charset=utf-8', hostScript);
+            }
+            if (url.pathname === '/token') {
+                // Only the local page may ask for tokens (a page on another site can't, even from this machine).
+                if (req.method !== 'POST' || !sameOrigin(req, hostOrigin)) return send(res, 403, 'application/json', JSON.stringify({ error: 'forbidden' }));
+                const body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}');
+                const issued = await tokens({ clientId: String(body.clientId ?? ''), engineId: body.engineId ? String(body.engineId) : null, internal: body.internal !== false, forceRefresh: !!body.forceRefresh });
+                return send(res, 200, 'application/json', JSON.stringify(issued));
+            }
+            if (url.pathname.startsWith('/api/')) {
+                return proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, fetchImpl });
+            }
+            if (url.pathname === '/ai-stream') {
+                return proxyAiStream(req, res, { appOrigin, ai, fetchImpl });
+            }
+            send(res, 404, 'text/plain', 'Not found');
+        } catch (error) {
+            log(`! ${error.message.split('\n')[0]}`);
+            send(res, error.status ?? 500, 'application/json', JSON.stringify({ error: error.message, ...(error.data?.code ? { code: error.data.code } : {}) }));
+        }
+    });
+    return server;
+}
+
+function sameOrigin(req, hostOrigin) {
+    return req.headers.origin === hostOrigin;
+}
+
+function corsHeaders(appOrigin, methods) {
+    return {
+        'Access-Control-Allow-Origin': appOrigin,
+        'Access-Control-Allow-Methods': methods,
+        'Access-Control-Allow-Headers': 'Authorization, Accept, Content-Type',
+        'Access-Control-Expose-Headers': 'Retry-After',
+        'Access-Control-Max-Age': '600',
+        Vary: 'Origin',
+    };
+}
+
+/** Only the headers the platform needs: Authorization, Content-Type and Accept. */
+function forwardHeaders(req, accept) {
+    const headers = { Accept: req.headers.accept ?? accept };
+    if (req.headers.authorization) headers.Authorization = req.headers.authorization;
+    if (req.headers['content-type']) headers['Content-Type'] = req.headers['content-type'];
+    return headers;
+}
+
+/**
+ * The app's platform calls, sent on with only the headers the platform needs. The answer to `GET ai` has its
+ * `streamUrl` (a Lambda function URL, whose CORS doesn't allow this page) replaced with this host's `/ai-stream`.
+ */
+async function proxy(req, res, url, { platformBase, appOrigin, hostOrigin, ai, fetchImpl }) {
+    const cors = corsHeaders(appOrigin, 'GET, POST, PUT, DELETE');
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, cors);
+        return res.end();
+    }
+    const body = ['GET', 'HEAD'].includes(req.method) ? undefined : await readBody(req, MAX_PROXY_BODY);
+    const target = `${platformBase}${url.pathname.slice('/api'.length)}${url.search}`;
+    const response = await fetchImpl(target, { method: req.method, headers: forwardHeaders(req, 'application/json'), body });
+    const out = { ...cors, 'Content-Type': response.headers.get('content-type') ?? 'application/json', 'Cache-Control': 'no-store' };
+    if (response.headers.has('retry-after')) out['Retry-After'] = response.headers.get('retry-after');
+    let payload = Buffer.from(await response.arrayBuffer());
+    if (req.method === 'GET' && response.ok && /^\/api\/v\d+\/ai$/.test(url.pathname)) {
+        payload = rewriteAiDiscovery(payload, `${hostOrigin}/ai-stream`, ai);
+    }
+    res.writeHead(response.status, out);
+    res.end(payload);
+}
+
+/** A real AI stream URL: https on a Lambda function URL host (`*.on.aws`), path `/v1/ai/messages`, nothing else. */
+export function isAiStreamUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.hostname.endsWith('.on.aws') && !url.port && !url.username && !url.password
+            && url.pathname === '/v1/ai/messages' && !url.search && !url.hash;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Remembers the `streamUrl` of a `GET ai` answer and points the app at `localStream` instead. Any other stream URL
+ * (e.g. a local platform's own) is left as it is and never proxied.
+ */
+function rewriteAiDiscovery(payload, localStream, ai) {
+    let body;
+    try {
+        body = JSON.parse(payload.toString('utf8'));
+    } catch {
+        return payload;
+    }
+    if (!body || !isAiStreamUrl(body.streamUrl)) return payload;
+    ai.streamUrl = body.streamUrl;
+    return Buffer.from(JSON.stringify({ ...body, streamUrl: localStream }));
+}
+
+/**
+ * `POST /ai-stream`: the app's AI request, sent on to the stream URL remembered from `GET ai`, with the event stream
+ * piped back as it arrives (not buffered). Stops the upstream request when the app goes away.
+ */
+async function proxyAiStream(req, res, { appOrigin, ai, fetchImpl }) {
+    const cors = corsHeaders(appOrigin, 'POST');
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, cors);
+        return res.end();
+    }
+    if (req.method !== 'POST') {
+        res.writeHead(405, { ...cors, Allow: 'POST', 'Content-Type': 'text/plain' });
+        return res.end('Method not allowed');
+    }
+    if (!ai.streamUrl) {
+        res.writeHead(503, { ...cors, 'Content-Type': 'application/problem+json', 'Cache-Control': 'no-store' });
+        return res.end(JSON.stringify({ status: 503, code: 'ai_not_configured', detail: 'No AI stream URL yet: the app must call GET ai first.' }));
+    }
+    const body = await readBody(req, MAX_PROXY_BODY);
+    const upstream = new AbortController();
+    res.on('close', () => {
+        if (!res.writableFinished) upstream.abort();
+    });
+    const response = await fetchImpl(ai.streamUrl, { method: 'POST', headers: forwardHeaders(req, 'text/event-stream'), body, signal: upstream.signal });
+    const out = { ...cors, 'Content-Type': response.headers.get('content-type') ?? 'text/event-stream', 'Cache-Control': 'no-store' };
+    if (response.headers.has('retry-after')) out['Retry-After'] = response.headers.get('retry-after');
+    res.writeHead(response.status, out);
+    res.flushHeaders();
+    try {
+        for await (const chunk of response.body ?? []) {
+            res.write(chunk);
+        }
+    } catch {
+        // The app went away (or the stream broke): nothing more to send.
+    }
+    res.end();
+}
+
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(Object.assign(new Error('Request body too large.'), { status: 413 }));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+
+function send(res, status, type, body) {
+    res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+    res.end(body);
+}
+
+/** Runs the app's `npm run dev` (its own output stays visible). */
+export function npmRunDev({ cwd }) {
+    return spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'dev'], { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+}
+
+/** Polls the URL until it answers (any status), up to `timeoutMs`. */
+export async function waitForUrl(url, { timeoutMs = 60_000, intervalMs = 500, signal, fetchImpl = fetch } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && !signal?.aborted) {
+        try {
+            await fetchImpl(url, { method: 'GET', signal: AbortSignal.timeout(2000) });
+            return true;
+        } catch {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    return false;
+}
+
+const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+/** The host page: a toolbar (client, site, user, dates, theme), the app, and panels for toasts, events and the token. */
+export function hostPage(settings) {
+    const today = new Date();
+    const from = new Date(today.getTime() - 29 * 86_400_000);
+    const initial = { ...settings, from: from.toISOString().slice(0, 10), to: today.toISOString().slice(0, 10), theme: 'light' };
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(settings.name)} · hawk-app dev</title>
+<style>
+  :root { --bg: #f6f7f9; --panel: #fff; --text: #1d2330; --muted: #667085; --border: #d0d5dd; --accent: #f26b1d; }
+  body { margin: 0; font: 14px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--text); }
+  body.dark { --bg: #14171c; --panel: #1d2128; --text: #e6e8eb; --muted: #98a2b3; --border: #343a46; }
+  header { display: flex; flex-wrap: wrap; gap: 10px; align-items: end; padding: 10px 16px; background: var(--panel); border-bottom: 1px solid var(--border); }
+  header h1 { font-size: 16px; margin: 0 16px 6px 0; }
+  header h1 small { color: var(--muted); font-weight: normal; }
+  label { display: flex; flex-direction: column; font-size: 12px; color: var(--muted); gap: 2px; }
+  input, select, button { font: inherit; padding: 4px 8px; border: 1px solid var(--border); border-radius: 4px; background: var(--panel); color: var(--text); }
+  button { cursor: pointer; } button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+  main { display: grid; grid-template-columns: 1fr 340px; gap: 12px; padding: 12px 16px; }
+  #title { font-size: 18px; margin: 0 0 8px; }
+  hawk-app-frame { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; min-height: 400px; }
+  aside section { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; margin-bottom: 12px; }
+  aside h2 { font-size: 13px; margin: 0 0 6px; }
+  aside pre { white-space: pre-wrap; word-break: break-all; font-size: 11px; margin: 0; max-height: 260px; overflow: auto; }
+  #events div { font-size: 12px; border-top: 1px solid var(--border); padding: 3px 0; }
+  #toasts { position: fixed; right: 16px; bottom: 16px; display: flex; flex-direction: column; gap: 8px; }
+  .toast { padding: 8px 12px; border-radius: 4px; color: #fff; background: #344054; box-shadow: 0 2px 6px rgba(0,0,0,.2); }
+  .toast.success { background: #12b76a; } .toast.warning { background: #f79009; } .toast.error { background: #f04438; }
+  @media (max-width: 900px) { main { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<header>
+  <h1>${escapeHtml(settings.name)} <small>hawk-app dev</small></h1>
+  <label>Client <input id="clientId" size="10"></label>
+  <label>Site (engine) <input id="engineId" size="8" placeholder="none"></label>
+  <label>User <select id="internal"><option value="true">Bridgeline user</option><option value="false">Client user</option></select></label>
+  <label>From <input id="from" type="date"></label>
+  <label>To <input id="to" type="date"></label>
+  <label>Theme <select id="theme"><option>light</option><option>dark</option></select></label>
+  <button class="primary" id="apply">Apply</button>
+  <button id="reload">Reload app</button>
+</header>
+<main>
+  <div>
+    <p id="title"></p>
+    <hawk-app-frame id="frame" title="${escapeHtml(settings.name)}"></hawk-app-frame>
+  </div>
+  <aside>
+    <section><h2>Token</h2><pre id="token">—</pre></section>
+    <section><h2>Messages from the app</h2><div id="events"></div></section>
+  </aside>
+</main>
+<div id="toasts"></div>
+<script type="module">
+  import { defineHawkAppFrame } from '/host.js';
+  defineHawkAppFrame();
+  const initial = ${JSON.stringify(initial).replace(/</g, '\\u003c')};
+  const $ = (id) => document.getElementById(id);
+  const frame = $('frame');
+  let state = { ...initial };
+  for (const key of ['clientId', 'engineId', 'from', 'to', 'theme']) $(key).value = state[key] ?? '';
+  $('internal').value = String(state.internal);
+
+  const event = (text) => { const row = document.createElement('div'); row.textContent = new Date().toLocaleTimeString() + '  ' + text; $('events').prepend(row); };
+  const claims = (token) => JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
+
+  function context(token) {
+    const c = claims(token);
+    return {
+      protocolVersion: 1,
+      app: { slug: state.slug },
+      tenant: { clientId: state.clientId },
+      user: { id: c.sub, roles: [] },
+      engine: state.engineId ? { id: state.engineId } : null,
+      site: state.engineId ? { id: state.engineId } : null,
+      dateRange: { from: state.from, to: state.to },
+      locale: navigator.language || 'en-US',
+      theme: { mode: state.theme, tokens: {} },
+      apiBaseUrl: location.origin + '/api/v1/',
+    };
+  }
+
+  async function token(forceRefresh) {
+    const res = await fetch('/token', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientId: state.clientId, engineId: state.engineId || null, internal: state.internal, forceRefresh }) });
+    const body = await res.json();
+    if (!res.ok) { event('token: ' + (body.error || res.status)); throw new Error(body.error || 'No token'); }
+    const c = claims(body.token);
+    $('token').textContent = JSON.stringify({ expiresAt: body.expiresAt, version: body.version, user: c.sub, client: c.client_id, engine: c.engine ?? null,
+      internal: c.internal, scopes: c.scope, hawksearch: body.hawkSearch }, null, 2);
+    return body;
+  }
+
+  frame.tokenProvider = async ({ forceRefresh }) => { const t = await token(forceRefresh); return { token: t.token, expiresAt: t.expiresAt }; };
+  frame.addEventListener('hawk-ready', () => event('ready'));
+  frame.addEventListener('hawk-title', (e) => { $('title').textContent = e.detail.title; document.title = e.detail.title + ' · hawk-app dev'; event('setTitle: ' + e.detail.title); });
+  frame.addEventListener('hawk-navigate', (e) => event('navigate: ' + JSON.stringify(e.detail)));
+  frame.addEventListener('hawk-toast', (e) => {
+    const t = document.createElement('div'); t.className = 'toast ' + (e.detail.variant || 'info'); t.textContent = e.detail.message;
+    $('toasts').append(t); setTimeout(() => t.remove(), 5000); event('toast (' + (e.detail.variant || 'info') + '): ' + e.detail.message);
+  });
+
+  async function load(reloadApp) {
+    document.body.classList.toggle('dark', state.theme === 'dark');
+    const t = await token(false).catch(() => null);
+    if (!t) return;
+    frame.context = context(t.token);
+    if (reloadApp) { frame.removeAttribute('src'); frame.setAttribute('src', initial.appUrl); }
+  }
+
+  $('apply').addEventListener('click', () => {
+    const before = state;
+    state = { ...state, clientId: $('clientId').value.trim(), engineId: $('engineId').value.trim(), internal: $('internal').value === 'true',
+      from: $('from').value, to: $('to').value, theme: $('theme').value };
+    // A new client, site or user needs a new token: reload the app; dates and theme are context changes.
+    const identity = (s) => s.clientId + '|' + s.engineId + '|' + s.internal;
+    load(identity(before) !== identity(state));
+    event('context: ' + state.clientId + (state.engineId ? ' / site ' + state.engineId : '') + ' · ' + state.from + '..' + state.to + ' · ' + state.theme);
+  });
+  $('reload').addEventListener('click', () => load(true));
+  load(true);
+</script>
+</body>
+</html>
+`;
+}