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

package/docs/showcase/src/App.tsx

@@ -1,1436 +1,1436 @@
-import {
-    FunctionJobError,
-    HawkApiError,
-    type AiInfo,
-    type AiModel,
-    type AiResult,
-    type AppSchedule,
-    type FunctionJob,
-    type HawkApp,
-    type HawkAppContext,
-    type IndexItemsResult,
-    type IndexRun,
-    type SearchRequest,
-    type SearchResponse,
-    type StorageFileEntry,
-    type StorageListEntry,
-    type StorageUsage,
-    type SystemParameter,
-} from '@bridgeline-digital/hawk-app-bridge/client';
-import { useRef, useState, type ReactNode } from 'react';
-import { useHawkApp } from './useHawkApp';
-
-/**
- * Internal test app for the Hawk Apps platform. One tab per feature; every call shows its outcome, timing and error
- * code, so a failing platform change is easy to spot. Not a product: keep it small and keep it working.
- */
-const TABS = ['Context', 'Analytics', 'Dashboard', 'Search', 'Recommendations', 'Index', 'Storage', 'Config', 'Queries', 'Functions', 'Jobs', 'System parameters', 'AI', 'Host'] as const;
-type Tab = (typeof TABS)[number];
-
-export function App() {
-    const hawk = useHawkApp();
-    const [tab, setTab] = useState<Tab>('Context');
-
-    if (hawk.status === 'connecting') return <p className="muted">Connecting…</p>;
-    if (hawk.status === 'error') return <p className="error">{hawk.message}</p>;
-
-    return (
-        <main>
-            <h2>Hawk Apps Showcase</h2>
-            <nav className="tabs">
-                {TABS.map((t) => (
-                    <button key={t} className={t === tab ? 'active' : ''} onClick={() => setTab(t)}>
-                        {t}
-                    </button>
-                ))}
-            </nav>
-            {tab === 'Context' && <ContextTab context={hawk.context} />}
-            {tab === 'Analytics' && <AnalyticsTab app={hawk.app} context={hawk.context} />}
-            {tab === 'Dashboard' && <DashboardTab app={hawk.app} />}
-            {tab === 'Search' && <SearchTab app={hawk.app} context={hawk.context} />}
-            {tab === 'Recommendations' && <RecommendationsTab app={hawk.app} />}
-            {tab === 'Index' && <IndexTab app={hawk.app} />}
-            {tab === 'Storage' && <StorageTab app={hawk.app} />}
-            {tab === 'Config' && <ConfigTab app={hawk.app} />}
-            {tab === 'Queries' && <QueriesTab app={hawk.app} context={hawk.context} />}
-            {tab === 'Functions' && <FunctionsTab app={hawk.app} context={hawk.context} />}
-            {tab === 'Jobs' && <JobsTab app={hawk.app} />}
-            {tab === 'System parameters' && <SystemParametersTab app={hawk.app} context={hawk.context} />}
-            {tab === 'AI' && <AiTab app={hawk.app} />}
-            {tab === 'Host' && <HostTab app={hawk.app} />}
-        </main>
-    );
-}
-
-// ---------- shared ----------
-
-interface Outcome {
-    label: string;
-    ok: boolean;
-    ms: number;
-    summary: string;
-    detail?: unknown;
-}
-
-/** Runs a call and records how it went: never throws, so one failure doesn't hide the others. */
-async function measure(label: string, call: () => Promise<{ summary: string; detail?: unknown }>): Promise<Outcome> {
-    const started = performance.now();
-    try {
-        const { summary, detail } = await call();
-        return { label, ok: true, ms: Math.round(performance.now() - started), summary, detail };
-    } catch (e) {
-        return { label, ok: false, ms: Math.round(performance.now() - started), summary: describe(e) };
-    }
-}
-
-function describe(e: unknown): string {
-    if (e instanceof HawkApiError) return `${e.status}${e.code ? ` ${e.code}` : ''}: ${e.message}`;
-    return e instanceof Error ? e.message : String(e);
-}
-
-function Results({ outcomes }: { outcomes: Outcome[] }) {
-    if (!outcomes.length) return null;
-    return (
-        <div className="results">
-            {outcomes.map((o, i) => {
-                const line = (
-                    <>
-                        <span className="badge">{o.ok ? 'OK' : 'FAIL'}</span> {o.label} · {o.ms} ms · {o.summary}
-                    </>
-                );
-                // Only results with something to show expand; the rest are a plain line (no empty arrow).
-                return o.detail === undefined || o.detail === null ? (
-                    <div key={i} className={`result ${o.ok ? 'ok' : 'fail'}`}>
-                        {line}
-                    </div>
-                ) : (
-                    <details key={i} className={o.ok ? 'ok' : 'fail'}>
-                        <summary>{line}</summary>
-                        <pre>{typeof o.detail === 'string' ? o.detail : JSON.stringify(o.detail, null, 2)}</pre>
-                    </details>
-                );
-            })}
-        </div>
-    );
-}
-
-function Card({ title, children }: { title: string; children: ReactNode }) {
-    return (
-        <section className="card">
-            <h3>{title}</h3>
-            {children}
-        </section>
-    );
-}
-
-/** The host's date range as YYYY-MM-DD (the last 30 days when the host sends none). */
-function range(context: HawkAppContext): { from: string; to: string } {
-    if (context.dateRange) return { from: context.dateRange.from.slice(0, 10), to: context.dateRange.to.slice(0, 10) };
-    const to = new Date();
-    const from = new Date(to.getTime() - 29 * 86_400_000);
-    return { from: from.toISOString().slice(0, 10), to: to.toISOString().slice(0, 10) };
-}
-
-/** The rows shown under a result: all of them up to 100, so a result can be checked in full. */
-const PREVIEW_ROWS = 100;
-const preview = <T,>(rows: T[]) => rows.slice(0, PREVIEW_ROWS);
-const shown = (rows: unknown[]) => (rows.length > PREVIEW_ROWS ? ` (showing ${PREVIEW_ROWS})` : '');
-
-// ---------- tabs ----------
-
-function ContextTab({ context }: { context: HawkAppContext }) {
-    return (
-        <Card title="Context from the host">
-            <p className="muted">Everything the host sent in the handshake (and later context changes).</p>
-            <pre>{JSON.stringify(context, null, 2)}</pre>
-        </Card>
-    );
-}
-
-function AnalyticsTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-    const reports = ['searches', 'queries', 'assistant-prompts'];
-
-    const run = async () => {
-        setBusy(true);
-        const results = await Promise.all(
-            reports.map((name) =>
-                measure(`analytics.report('${name}')`, async () => {
-                    const report = await app.analytics.report(name, { limit: 10 });
-                    return { summary: `${report.data.length} rows (total ${report.totalRecords ?? '?'})${shown(report.data)}`, detail: preview(report.data) };
-                }),
-            ),
-        );
-        setOutcomes(results);
-        setBusy(false);
-    };
-
-    return (
-        <Card title="Analytics API (reports:read)">
-            <p className="muted">
-                Dates default to the host range ({range(context).from} – {range(context).to}). Reports: {reports.join(', ')}.
-            </p>
-            <button disabled={busy} onClick={run}>
-                Run reports
-            </button>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-function DashboardTab({ app }: { app: HawkApp }) {
-    const [path, setPath] = useState('Synonym');
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-
-    const run = async () =>
-        setOutcomes([
-            await measure(`dashboard.get('${path}')`, async () => {
-                const data = await app.dashboard.get<unknown>(path);
-                const rows = Array.isArray(data) ? data : null;
-                return { summary: rows ? `${rows.length} items${shown(rows)}` : 'object', detail: rows ? preview(rows) : data };
-            }),
-            // Versioned paths must be rejected: the platform picks the API version.
-            await measure(`dashboard.get('v11/${path}') (expect 400)`, async () => {
-                await app.dashboard.get(`v11/${path}`);
-                return { summary: 'unexpectedly allowed' };
-            }),
-        ]);
-
-    return (
-        <>
-            <Card title="HawkSearch dashboard API (hawksearch:read)">
-                <label>
-                    Path <input value={path} onChange={(e) => setPath(e.target.value)} />
-                </label>{' '}
-                <button onClick={run}>GET</button>
-                <Results outcomes={outcomes} />
-            </Card>
-            <DashboardWriteTest app={app} />
-        </>
-    );
-}
-
-/** HawkSearch's Synonym model (HawkSearch.Contracts.Api.Synonym). */
-interface Synonym {
-    Id: number;
-    SearchTerm: string;
-    SynonymGroup: string;
-    MultiWay: boolean;
-    Comments?: string | null;
-}
-
-/** Expects the call to fail with `status` (and `code`, when given); anything else, including success, is a failure. */
-async function expectError(label: string, status: number, code: string | undefined, call: () => Promise<unknown>): Promise<Outcome> {
-    return measure(`${label} (expect ${status}${code ? ` ${code}` : ''})`, async () => {
-        try {
-            await call();
-        } catch (e) {
-            if (e instanceof HawkApiError && e.status === status && (!code || e.code === code)) return { summary: `${describe(e)} (as expected)` };
-            throw e;
-        }
-        throw new Error('unexpectedly allowed');
-    });
-}
-
-/**
- * hawksearch:write round trip on a throwaway synonym: create, read back, delete, check it's gone. The synonym is
- * clearly marked as a test and deleted in the same run (also when the read-back fails).
- */
-function DashboardWriteTest({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    const roundTrip = async (): Promise<Outcome[]> => {
-        const marker = `hawk-apps-showcase-${Date.now()}`;
-        const body = {
-            SearchTerm: marker,
-            SynonymGroup: `${marker}-a,${marker}-b`,
-            MultiWay: false,
-            Comments: 'Created by the Hawk Apps showcase app (write test); deleted right away. Safe to delete.',
-        };
-        const results: Outcome[] = [];
-        let id: number | undefined;
-
-        results.push(
-            await measure("dashboard.post('Synonym')", async () => {
-                const created = await app.dashboard.post<Synonym>('Synonym', body);
-                id = created?.Id;
-                if (!id) throw new Error(`no Id in the response: ${JSON.stringify(created)}`);
-                return { summary: `created synonym ${id} (${marker})`, detail: created };
-            }),
-        );
-        if (!id) return results;
-
-        results.push(
-            await measure(`dashboard.get('Synonym/${id}')`, async () => {
-                const synonym = await app.dashboard.get<Synonym>(`Synonym/${id}`);
-                if (synonym?.SearchTerm !== marker) throw new Error(`read back ${JSON.stringify(synonym?.SearchTerm)}, expected ${marker}`);
-                return { summary: `read back: ${synonym.SearchTerm} → ${synonym.SynonymGroup}`, detail: synonym };
-            }),
-        );
-        results.push(
-            await measure(`dashboard.delete('Synonym/${id}')`, async () => {
-                const removed = await app.dashboard.delete<Synonym | undefined>(`Synonym/${id}`);
-                return { summary: 'deleted', detail: removed };
-            }),
-        );
-        // HawkSearch answers 404 for a deleted synonym (its own error body, no platform code).
-        results.push(await expectError(`dashboard.get('Synonym/${id}') after delete`, 404, undefined, () => app.dashboard.get(`Synonym/${id}`)));
-        return results;
-    };
-
-    // Field isn't a writable resource. The body is empty, so even a wrongly allowed call couldn't create a field.
-    const notAllowed = () => expectError("dashboard.post('Field')", 403, 'path_not_allowed', () => app.dashboard.post('Field', {}));
-
-    return (
-        <Card title="Write test (hawksearch:write)">
-            <p className="muted">
-                Creates a synonym marked <code>hawk-apps-showcase-…</code> in the current client, reads it back and deletes it. Writes are
-                audit-logged and never retried; 120 per minute per app and client.
-            </p>
-            <div className="buttons">
-                <button disabled={busy} onClick={() => go(roundTrip)}>
-                    Create, read, delete synonym
-                </button>
-                <button disabled={busy} onClick={() => go(async () => [await notAllowed()])}>
-                    Error case
-                </button>
-            </div>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-/** The part of a search result the tab shows. */
-function searchSummary(result: SearchResponse): { summary: string; detail: unknown } {
-    const results = result.Results ?? [];
-    const total = result.Pagination?.NofResults ?? results.length;
-    const redirect = result.Redirect?.Location ? ` · redirect ${result.Redirect.Location}` : '';
-    return { summary: `${total} results${redirect}`, detail: { total, firstDocIds: results.slice(0, 10).map((r) => r.DocId), response: result } };
-}
-
-/** Runs `work` over `items`, at most `limit` at a time (the platform allows 600 searches per minute per app and client). */
-async function pool<T, R>(items: T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
-    const results: R[] = new Array(items.length);
-    let next = 0;
-    await Promise.all(
-        Array.from({ length: Math.min(limit, items.length) }, async () => {
-            while (next < items.length) {
-                const i = next++;
-                results[i] = await work(items[i]);
-            }
-        }),
-    );
-    return results;
-}
-
-function SearchTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-    const [keyword, setKeyword] = useState('boots');
-    const [previewDate, setPreviewDate] = useState('');
-    const [keywords, setKeywords] = useState('boots\njacket\nzzz-no-such-product');
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    const search = (label: string, request: SearchRequest) =>
-        measure(label, async () => searchSummary(await app.hawksearch.search(request)));
-
-    const previewRequest = (): SearchRequest => ({
-        Keyword: keyword,
-        IsInPreview: true,
-        ...(previewDate ? { SmartBar: { PreviewDate: `${previewDate}T00:00:00` } } : {}),
-    });
-
-    const autocomplete = () =>
-        measure(`hawksearch.autocomplete({ Keyword: ${JSON.stringify(keyword)} })`, async () => {
-            const result = await app.hawksearch.autocomplete<Record<string, unknown>>({ Keyword: keyword, ProductCount: 5 });
-            const counts = Object.entries(result)
-                .filter(([, v]) => Array.isArray(v))
-                .map(([k, v]) => `${k} ${(v as unknown[]).length}`);
-            return { summary: counts.join(' · ') || 'no lists', detail: result };
-        });
-
-    // Every keyword, 5 at a time; zero-result keywords fail so they stand out.
-    const zeroResults = async (): Promise<Outcome[]> => {
-        const list = [...new Set(keywords.split('\n').map((k) => k.trim()).filter(Boolean))].slice(0, 100);
-        return pool(list, 5, (k) =>
-            measure(`"${k}"`, async () => {
-                const { summary, detail } = searchSummary(await app.hawksearch.search({ Keyword: k, MaxPerPage: 1 }));
-                if (summary.startsWith('0 results')) throw new Error('0 results');
-                return { summary, detail };
-            }),
-        );
-    };
-
-    // The analytics "queries" report (reports:read): the keyword column is the first one named like keyword/query/term.
-    const loadTopQueries = async (): Promise<Outcome[]> => [
-        await measure("analytics.report('queries') → keywords", async () => {
-            const report = await app.analytics.report<Record<string, unknown>>('queries', { limit: 100 });
-            const column = Object.keys(report.data[0] ?? {}).find((c) => /keyword|query|term/i.test(c));
-            if (!column) throw new Error(`no keyword column in ${JSON.stringify(Object.keys(report.data[0] ?? {}))}`);
-            const found = report.data.map((row) => String(row[column] ?? '').trim()).filter(Boolean);
-            setKeywords(found.join('\n'));
-            return { summary: `${found.length} keywords from column "${column}"` };
-        }),
-    ];
-
-    return (
-        <>
-            <Card title="Search (hawksearch:search)">
-                <p className="muted">
-                    HawkSearch v2 search and autocomplete for engine{' '}
-                    {context.engine ? `${context.engine.id}${context.engine.name ? ` (${context.engine.name})` : ''}` : '(none: expect 400 engine_required)'}. The platform
-                    sets the ClientGuid; preview uses the engine's preview search API.
-                </p>
-                <div className="buttons">
-                    <label>
-                        Keyword <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
-                    </label>
-                    <label>
-                        Preview date <input type="date" value={previewDate} onChange={(e) => setPreviewDate(e.target.value)} />
-                    </label>
-                </div>
-                <div className="buttons">
-                    <button disabled={busy} onClick={() => go(async () => [await search(`hawksearch.search({ Keyword: ${JSON.stringify(keyword)} })`, { Keyword: keyword })])}>
-                        Search
-                    </button>
-                    <button
-                        disabled={busy}
-                        onClick={() =>
-                            go(() => Promise.all([search('live', { Keyword: keyword }), search(`preview${previewDate ? ` as of ${previewDate}` : ''}`, previewRequest())]))
-                        }
-                    >
-                        Live vs preview
-                    </button>
-                    <button disabled={busy} onClick={() => go(async () => [await autocomplete()])}>
-                        Autocomplete
-                    </button>
-                    <button
-                        disabled={busy}
-                        onClick={() =>
-                            go(async () => [
-                                await search('ClientGuid in the request is replaced (expect normal results)', { Keyword: keyword, ClientGuid: 'not-this-engine' }),
-                                await measure('hawksearch.search(null) (expect TypeError, no call)', async () => {
-                                    try {
-                                        await app.hawksearch.search(null as never);
-                                    } catch (e) {
-                                        if (e instanceof TypeError) return { summary: `${e.message} (as expected)` };
-                                        throw e;
-                                    }
-                                    throw new Error('unexpectedly allowed');
-                                }),
-                            ])
-                        }
-                    >
-                        Error cases
-                    </button>
-                </div>
-                <Results outcomes={outcomes} />
-            </Card>
-            <Card title="Zero-result check">
-                <p className="muted">One keyword per line (up to 100), 5 searches at a time. Keywords with 0 results show as FAIL.</p>
-                <textarea rows={6} value={keywords} onChange={(e) => setKeywords(e.target.value)} />
-                <div className="buttons">
-                    <button disabled={busy} onClick={() => go(loadTopQueries)}>
-                        Load top queries (analytics)
-                    </button>
-                    <button disabled={busy} onClick={() => go(zeroResults)}>
-                        Check keywords
-                    </button>
-                </div>
-            </Card>
-        </>
-    );
-}
-
-function QueriesTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-    const { from, to } = range(context);
-
-    const query = (label: string, name: string, params: Record<string, unknown>) =>
-        measure(label, async () => {
-            const result = await app.data.query(name, params as never);
-            return {
-                summary: `${result.rowCount} rows · ${result.bytesScanned} B scanned${result.cached ? ' · cached' : ''}${shown(result.rows)}`,
-                detail: preview(result.rows),
-            };
-        });
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    return (
-        <Card title="Queries (data:read)">
-            <p className="muted">
-                Range {from} – {to}. Queries ship in <code>queries/</code> with each version.
-            </p>
-            <div className="buttons">
-                <button disabled={busy} onClick={() => go(async () => [await query('searches-by-day (allowed table)', 'searches-by-day', { from, to })])}>
-                    Allowed table
-                </button>
-                <button disabled={busy} onClick={() => go(async () => [await query('searches-by-day again (expect cached)', 'searches-by-day', { from, to })])}>
-                    Repeat (cached)
-                </button>
-                <button
-                    disabled={busy}
-                    onClick={() => go(async () => [await query('assistant-prompts-by-day (sensitive: needs the app opt-in, else TABLE_NOT_FOUND)', 'assistant-prompts-by-day', { from, to })])}
-                >
-                    Sensitive table
-                </button>
-                <button
-                    disabled={busy}
-                    onClick={() =>
-                        go(() =>
-                            // Different ranges so each is a new execution: more than 2 at once per app and client
-                            // hits the limit (429), which the bridge retries until a slot frees up.
-                            Promise.all(
-                                [1, 2, 3, 4, 5].map((n) => {
-                                    const end = new Date(new Date(`${to}T00:00:00Z`).getTime() - n * 86_400_000).toISOString().slice(0, 10);
-                                    return query(`burst #${n} (to ${end})`, 'searches-by-day', { from, to: end });
-                                }),
-                            ),
-                        )
-                    }
-                >
-                    Burst ×5 (concurrency)
-                </button>
-                <button
-                    disabled={busy}
-                    onClick={() =>
-                        go(async () => [
-                            await query('invalid params (expect 400 invalid_params)', 'searches-by-day', { from: 'not-a-date', to }),
-                            await query('unknown query (expect 404 query_not_found)', 'does-not-exist', {}),
-                        ])
-                    }
-                >
-                    Error cases
-                </button>
-            </div>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-interface ShowcaseStep {
-    name: string;
-    ok: boolean;
-    ms: number;
-    summary: string;
-    detail?: unknown;
-}
-
-function FunctionsTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-    const [text, setText] = useState('hello');
-
-    const call = (label: string, name: string, input: unknown) =>
-        measure(label, async () => {
-            const result = await app.functions.call<Record<string, unknown>>(name, input);
-            const facts = ['client', 'user', 'version', 'hasSecret', 'searches'].map((key) => `${key} ${JSON.stringify(result?.[key])}`);
-            return { summary: facts.join(' · '), detail: result };
-        });
-
-    // The showcase reports its own steps: show each as a result row, after a row for the call itself.
-    const showcase = async (): Promise<Outcome[]> => {
-        const started = performance.now();
-        try {
-            const result = await app.functions.call<{ steps: ShowcaseStep[]; totalMs: number; runtime: Record<string, unknown> }>(
-                'showcase',
-                range(context),
-                { timeoutMs: 40_000 },
-            );
-            const passed = result.steps.filter((s) => s.ok).length;
-            return [
-                {
-                    label: 'showcase (round trip)',
-                    ok: passed === result.steps.length,
-                    ms: Math.round(performance.now() - started),
-                    summary: `${passed}/${result.steps.length} steps ok · ${result.totalMs} ms in the function`,
-                    detail: result.runtime,
-                },
-                ...result.steps.map((s) => ({ label: s.name, ok: s.ok, ms: s.ms, summary: s.summary, detail: s.detail })),
-            ];
-        } catch (e) {
-            return [{ label: 'showcase', ok: false, ms: Math.round(performance.now() - started), summary: describe(e) }];
-        }
-    };
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    return (
-        <Card title="Functions (functions:invoke)">
-            <p className="muted">
-                <code>functions/showcase.ts</code> runs every function capability (input validation with an npm package, context, secrets, the
-                analytics and dashboard APIs, an app query, Athena directly with client-scoped credentials, outbound HTTP, and its own logic)
-                and reports each step; <code>functions/echo.ts</code> is the minimal one. Both ship with each version. Needs functions enabled for the app (else 403 functions_not_enabled) and the
-                <code> TEST_SECRET</code> secret (<code>npx hawk-app secrets set TEST_SECRET</code>; else 500 secret_missing).
-            </p>
-            <label>
-                Input <input value={text} onChange={(e) => setText(e.target.value)} />
-            </label>{' '}
-            <div className="buttons">
-                <button disabled={busy} onClick={() => go(showcase)}>
-                    Run showcase
-                </button>
-                <button disabled={busy} onClick={() => go(async () => [await call('echo', 'echo', { text, at: new Date().toISOString() })])}>
-                    Call echo
-                </button>
-                <button disabled={busy} onClick={() => go(() => Promise.all([1, 2, 3, 4, 5, 6, 7].map((n) => call(`echo burst #${n}`, 'echo', { n }))))}>
-                    Burst ×7 (concurrency)
-                </button>
-                <button disabled={busy} onClick={() => go(async () => [await call('missing function (expect 404 function_not_found)', 'does-not-exist', {})])}>
-                    Error case
-                </button>
-            </div>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-/** A job as one result row. */
-function jobOutcome(label: string, job: FunctionJob<Record<string, unknown>>, ms: number): Outcome {
-    const progress = job.progress ? ` · ${job.progress.percent ?? '?'}% ${job.progress.message ?? ''}` : '';
-    return {
-        label,
-        ok: job.status === 'succeeded',
-        ms,
-        summary: `${job.status}${progress}${job.error ? ` · ${job.error.type}${job.error.message ? `: ${job.error.message}` : ''}` : ''}`,
-        detail: job,
-    };
-}
-
-function JobsTab({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [live, setLive] = useState<FunctionJob | null>(null);
-    const [schedules, setSchedules] = useState<AppSchedule[] | null>(null);
-    const [busy, setBusy] = useState(false);
-    const [steps, setSteps] = useState(10);
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    // Start, then wait while showing progress live.
-    const runJob = async (input: Record<string, unknown>, label: string): Promise<Outcome[]> => {
-        const started = performance.now();
-        try {
-            const { jobId } = await app.functions.start('long-task', input);
-            const job = await app.functions.wait<Record<string, unknown>>(jobId, { intervalMs: 2000, onProgress: (j) => setLive(j) });
-            setLive(null);
-            return [jobOutcome(label, job, Math.round(performance.now() - started))];
-        } catch (e) {
-            setLive(null);
-            if (e instanceof FunctionJobError) {
-                return [jobOutcome(`${label} (failed as a job)`, e.job as FunctionJob<Record<string, unknown>>, Math.round(performance.now() - started))];
-            }
-            return [{ label, ok: false, ms: Math.round(performance.now() - started), summary: describe(e) }];
-        }
-    };
-
-    const listSchedules = () =>
-        measure('schedules.list()', async () => {
-            const list = await app.schedules.list();
-            setSchedules(list);
-            return { summary: `${list.length} schedules · ${list.filter((s) => s.enabled).length} on for this client`, detail: list };
-        });
-
-    const toggle = (schedule: AppSchedule) =>
-        measure(`schedules.${schedule.enabled ? 'disable' : 'enable'}('${schedule.name}')`, async () => {
-            const updated = schedule.enabled ? await app.schedules.disable(schedule.name) : await app.schedules.enable(schedule.name);
-            return { summary: updated.enabled ? 'on' : 'off', detail: updated };
-        });
-
-    return (
-        <>
-            <Card title="Background jobs (functions:invoke, &quot;job&quot;: true)">
-                <p className="muted">
-                    <code>functions/long-task.ts</code> counts through steps (3 s each), reporting progress, and returns what it knows about the run.
-                    Jobs run up to 15 minutes; 3 at once per app and client.
-                </p>
-                <div className="buttons">
-                    <label>
-                        Steps <input type="number" min={1} max={60} value={steps} onChange={(e) => setSteps(Number(e.target.value))} />
-                    </label>
-                    <button disabled={busy} onClick={() => go(() => runJob({ steps }, `long-task (${steps} steps)`))}>
-                        Start and wait
-                    </button>
-                    <button disabled={busy} onClick={() => go(() => runJob({ steps: 2, fail: true }, 'long-task failing (expect failed)'))}>
-                        Failing job
-                    </button>
-                    <button
-                        disabled={busy}
-                        onClick={() =>
-                            go(async () => [
-                                await expectError("functions.call('long-task') (expect 409 function_is_job)", 409, 'function_is_job', () => app.functions.call('long-task', {})),
-                                await expectError("functions.start('echo') (expect 409 function_not_job)", 409, 'function_not_job', () => app.functions.start('echo', {})),
-                            ])
-                        }
-                    >
-                        Error cases
-                    </button>
-                </div>
-                {live && (
-                    <p>
-                        <progress max={100} value={live.progress?.percent ?? 0} /> {live.status} · {live.progress?.percent ?? 0}% {live.progress?.message ?? ''}
-                    </p>
-                )}
-                <Results outcomes={outcomes} />
-            </Card>
-            <Card title="Schedules">
-                <p className="muted">
-                    <code>daily-check</code> runs long-task at 13:00 America/Chicago for each client where it is on (as <code>schedule:daily-check</code>, on this
-                    site, with this client&apos;s HawkSearch connection). Approved schedules only.
-                </p>
-                <div className="buttons">
-                    <button disabled={busy} onClick={() => go(async () => [await listSchedules()])}>
-                        List
-                    </button>
-                </div>
-                {schedules && (
-                    <table className="params">
-                        <thead>
-                            <tr>
-                                <th>Name</th>
-                                <th>Runs</th>
-                                <th>For this client</th>
-                                <th>Last run</th>
-                                <th />
-                            </tr>
-                        </thead>
-                        <tbody>
-                            {schedules.map((s) => (
-                                <tr key={s.name}>
-                                    <td>{s.name}</td>
-                                    <td>
-                                        {s.function} · <code>{s.cron}</code> ({s.timezone})
-                                    </td>
-                                    <td>{s.enabled ? `on (by ${s.enabledBy?.email ?? s.enabledBy?.id ?? '?'})` : 'off'}</td>
-                                    <td>{s.lastRun ? `${new Date(s.lastRun.at).toLocaleString()} · ${s.lastRun.status}${s.lastRun.reason ? ` (${s.lastRun.reason})` : ''}` : '—'}</td>
-                                    <td>
-                                        <button disabled={busy} onClick={() => go(async () => [await toggle(s), await listSchedules()])}>
-                                            {s.enabled ? 'Turn off' : 'Turn on'}
-                                        </button>
-                                    </td>
-                                </tr>
-                            ))}
-                        </tbody>
-                    </table>
-                )}
-            </Card>
-        </>
-    );
-}
-
-/** The names declared in hawk-app.json "systemParameters" (only these can be read or set). */
-const DECLARED_SYSTEM_PARAMETERS = ['Timezone', 'SearchPreviewURL'];
-
-function SystemParametersTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [parameters, setParameters] = useState<SystemParameter[] | null>(null);
-    const [busy, setBusy] = useState(false);
-    const [name, setName] = useState(DECLARED_SYSTEM_PARAMETERS[0]);
-    const [value, setValue] = useState('');
-
-    const go = async (runs: () => Promise<Outcome[]>) => {
-        setBusy(true);
-        setOutcomes(await runs());
-        setBusy(false);
-    };
-
-    const list = () =>
-        measure('hawksearch.systemParameters.list()', async () => {
-            const result = await app.hawksearch.systemParameters.list();
-            setParameters(result.parameters);
-            return { summary: `engine ${result.engineId} · ${result.parameters.length} parameters`, detail: result };
-        });
-
-    const set = () =>
-        measure(`hawksearch.systemParameters.set('${name}', ${JSON.stringify(value)})`, async () => {
-            const result = await app.hawksearch.systemParameters.set(name, value === '' ? null : value);
-            return {
-                summary: `${JSON.stringify(result.previous)} → ${JSON.stringify(result.value)} · applies within ${result.appliesWithinSeconds} s`,
-                detail: result,
-            };
-        });
-
-    const undeclared = () =>
-        measure("hawksearch.systemParameters.set('WebsiteUrl') (undeclared: expect 404 parameter_not_found)", async () => {
-            await app.hawksearch.systemParameters.set('WebsiteUrl', 'https://example.com');
-            return { summary: 'unexpectedly allowed' };
-        });
-
-    return (
-        <Card title="HawkSearch system parameters (hawksearch:sysparams:write)">
-            <p className="muted">
-                Engine {context.engine ? `${context.engine.id}${context.engine.name ? ` (${context.engine.name})` : ''}` : '(none: expect 400 engine_required)'}. Declared in{' '}
-                <code>hawk-app.json</code>: {DECLARED_SYSTEM_PARAMETERS.join(', ')}. Changes apply in HawkSearch within about 3 minutes.
-            </p>
-            <div className="buttons">
-                <button disabled={busy} onClick={() => go(async () => [await list()])}>
-                    List
-                </button>
-            </div>
-            {parameters && (
-                <table className="params">
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>Label</th>
-                            <th>Type</th>
-                            <th>Value</th>
-                            <th>Read-only</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        {parameters.map((p) => (
-                            <tr key={p.name}>
-                                <td>{p.name}</td>
-                                <td>{p.label ?? ''}</td>
-                                <td>{p.type}</td>
-                                <td>{p.encrypted ? '(encrypted)' : p.value ?? <span className="muted">(not set)</span>}</td>
-                                <td>{p.readOnly ? 'yes' : 'no'}</td>
-                            </tr>
-                        ))}
-                    </tbody>
-                </table>
-            )}
-            <div className="buttons">
-                <select value={name} onChange={(e) => setName(e.target.value)}>
-                    {DECLARED_SYSTEM_PARAMETERS.map((n) => (
-                        <option key={n}>{n}</option>
-                    ))}
-                </select>
-                <input placeholder="value (empty clears it)" value={value} onChange={(e) => setValue(e.target.value)} />
-                <button disabled={busy} onClick={() => go(async () => [await set(), await list()])}>
-                    Set
-                </button>
-                <button disabled={busy} onClick={() => go(async () => [await undeclared()])}>
-                    Error case
-                </button>
-            </div>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-function AiTab({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [busy, setBusy] = useState(false);
-    const [model, setModel] = useState<AiModel>('fast');
-    const [system, setSystem] = useState('');
-    const [prompt, setPrompt] = useState('In two sentences, what is site search merchandising?');
-    const [output, setOutput] = useState('');
-    const [info, setInfo] = useState<AiInfo | null>(null);
-    // Stops the running call (the stream's abort(), or generate's AbortSignal).
-    const stop = useRef<(() => void) | null>(null);
-
-    const request = () => ({ model, prompt, ...(system.trim() ? { system } : {}) });
-    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 10));
-    const summarize = (result: AiResult) => `${result.model} · ${result.stopReason} · ${result.usage.inputTokens} in / ${result.usage.outputTokens} out · id ${result.id}`;
-
-    const stream = async () => {
-        setBusy(true);
-        setOutput('');
-        const s = app.ai.stream(request());
-        stop.current = () => s.abort();
-        record(
-            await measure(`ai.stream({ model: '${model}' })`, async () => {
-                let chunks = 0;
-                for await (const text of s) {
-                    chunks++;
-                    setOutput((previous) => previous + text);
-                }
-                const result = await s.result;
-                return { summary: `${chunks} chunks · ${summarize(result)}`, detail: result };
-            }),
-        );
-        stop.current = null;
-        setBusy(false);
-    };
-
-    const generate = async () => {
-        setBusy(true);
-        setOutput('');
-        const controller = new AbortController();
-        stop.current = () => controller.abort();
-        record(
-            await measure(`ai.generate({ model: '${model}' })`, async () => {
-                const result = await app.ai.generate(request(), { signal: controller.signal });
-                setOutput(result.text);
-                return { summary: summarize(result), detail: result };
-            }),
-        );
-        stop.current = null;
-        setBusy(false);
-    };
-
-    const loadInfo = async () =>
-        record(
-            await measure('ai.info()', async () => {
-                const result = await app.ai.info();
-                setInfo(result);
-                return { summary: result.tiers.map((t) => `${t.name} ${t.usedTokens}/${t.dailyTokens}`).join(' · '), detail: result };
-            }),
-        );
-
-    return (
-        <Card title="AI (ai:invoke)">
-            <p className="muted">
-                Claude through the platform: <code>fast</code> (Haiku) or <code>smart</code> (Sonnet). Every call costs tokens from the tier's daily budget
-                for this client; nothing is retried.
-            </p>
-            <div className="buttons">
-                <select value={model} onChange={(e) => setModel(e.target.value as AiModel)}>
-                    <option value="fast">fast</option>
-                    <option value="smart">smart</option>
-                </select>
-                <button onClick={loadInfo}>Info</button>
-            </div>
-            {info && (
-                <table className="params">
-                    <thead>
-                        <tr>
-                            <th>Tier</th>
-                            <th>Used today</th>
-                            <th>Daily tokens</th>
-                            <th>Max output tokens</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        {info.tiers.map((t) => (
-                            <tr key={t.name}>
-                                <td>{t.name}</td>
-                                <td>{t.usedTokens.toLocaleString()}</td>
-                                <td>{t.dailyTokens.toLocaleString()}</td>
-                                <td>{t.maxOutputTokens.toLocaleString()}</td>
-                            </tr>
-                        ))}
-                    </tbody>
-                </table>
-            )}
-            {info && (
-                <p className="muted">
-                    Max input {info.maxInputBytes.toLocaleString()} bytes · {info.requestsPerMinute} requests per minute.
-                </p>
-            )}
-            <textarea rows={2} placeholder="System prompt (optional)" value={system} onChange={(e) => setSystem(e.target.value)} />
-            <textarea rows={4} placeholder="Prompt" value={prompt} onChange={(e) => setPrompt(e.target.value)} />
-            <div className="buttons">
-                <button disabled={busy || !prompt.trim()} onClick={stream}>
-                    Stream
-                </button>
-                <button disabled={busy || !prompt.trim()} onClick={generate}>
-                    Generate
-                </button>
-                <button disabled={!busy} onClick={() => stop.current?.()}>
-                    Stop
-                </button>
-            </div>
-            <textarea rows={10} readOnly value={output} placeholder="The answer appears here as it arrives." />
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-/** Index rebuilds (hawksearch:index): the latest run, and a full rebuild followed to the end. */
-function IndexTab({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [progress, setProgress] = useState('');
-    const add = (o: Outcome) => setOutcomes((current) => [...current, o]);
-    const describeRun = (r: IndexRun) => `${r.status}${r.done ? ' (done)' : ''} · ${r.count ?? 0} items${r.durationSeconds !== null ? ` · ${r.durationSeconds} s` : ''}`;
-
-    const status = async () => {
-        setOutcomes([]);
-        add(await measure('index.status()', async () => {
-            const run = await app.hawksearch.index.status();
-            return { summary: describeRun(run), detail: run };
-        }));
-    };
-
-    // The Indexing API's reads (engines with their own indexes; others answer 503 indexing_api_not_available).
-    const indexes = async () => {
-        setOutcomes([]);
-        add(await measure('index.indexes()', async () => {
-            const names = await app.hawksearch.index.indexes();
-            return { summary: `${names.length} indexes`, detail: names };
-        }));
-        add(await measure('index.current()', async () => ({ summary: (await app.hawksearch.index.current()) ?? 'none' })));
-    };
-
-    const rebuild = async () => {
-        setOutcomes([]);
-        setProgress('');
-        let id: number | null = null;
-        add(await measure('index.rebuild()', async () => {
-            const started = await app.hawksearch.index.rebuild();
-            id = started.notificationId;
-            return { summary: `#${started.notificationId} ${describeRun(started)}`, detail: started };
-        }));
-        const runId = id as number | null; // set inside the callback above
-        if (runId !== null) {
-            add(await measure(`index.wait(${runId})`, async () => {
-                const final = await app.hawksearch.index.wait(runId, { intervalMs: 10_000, onProgress: (r) => setProgress(describeRun(r)) });
-                return { summary: describeRun(final), detail: final };
-            }));
-        }
-    };
-
-    return (
-        <>
-            <Card title="Index rebuilds (hawksearch:index)">
-                <p className="muted">
-                    A rebuild reloads this engine&apos;s live search from its feed. It needs the engine&apos;s EnableRebuildIndex on, and one runs at a time.
-                </p>
-                <button onClick={indexes}>Indexes</button> <button onClick={status}>Latest rebuild</button>{' '}
-                <button onClick={rebuild}>Rebuild now and wait</button>
-                {progress && <p className="muted">Now: {progress}</p>}
-                <Results outcomes={outcomes} />
-            </Card>
-            <IndexItemsCard app={app} />
-        </>
-    );
-}
-
-/**
- * Item writes (hawksearch:index:items): one field of one item, updated and read back through search, then put back to
- * the value it had. The Indexing API applies writes at once: on the current index, that's the engine's live search.
- */
-function IndexItemsCard({ app }: { app: HawkApp }) {
-    const [indexNames, setIndexNames] = useState<string[]>([]);
-    const [indexName, setIndexName] = useState('');
-    const [primaryKey, setPrimaryKey] = useState('id');
-    const [itemId, setItemId] = useState('');
-    const [field, setField] = useState('');
-    const [value, setValue] = useState('');
-    const [understood, setUnderstood] = useState(false);
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const add = (o: Outcome) => setOutcomes((current) => [...current, o]);
-    const ready = understood && indexName && primaryKey.trim() && itemId.trim() && field.trim();
-
-    const load = async () => {
-        setOutcomes([]);
-        add(await measure('index.indexes() + current()', async () => {
-            const [names, current] = await Promise.all([app.hawksearch.index.indexes(), app.hawksearch.index.current()]);
-            setIndexNames(names);
-            setIndexName(current ?? names[0] ?? '');
-            return { summary: `${names.length} indexes, current: ${current ?? 'none'}`, detail: { names, current } };
-        }));
-    };
-
-    // Each field is an array of values; the item is named by the engine's primary key (set in HawkSearch's fields).
-    const item = (fields: Record<string, unknown[]>) => ({ [primaryKey.trim()]: [itemId.trim()], ...fields });
-
-    // The field's values before the first change, read through search (the live index), to put back afterwards.
-    const [previous, setPrevious] = useState<unknown[] | null>(null);
-
-    /** The item's field as search sees it now (only the current index is searched). */
-    const read = (label: string) =>
-        measure(label, async () => {
-            const found = await app.hawksearch.search({ Keyword: itemId.trim(), MaxPerPage: 1 });
-            const values = found.Results?.[0]?.Document?.[field.trim()];
-            return { summary: `${found.Pagination?.NofResults ?? 0} results · ${field}: ${JSON.stringify(values ?? null)}`, detail: { values, values_raw: found.Results?.[0] } };
-        });
-
-    const write = (values: unknown[]) =>
-        measure(`index.items.update(${itemId}: ${field} = ${JSON.stringify(values)})`, async () => {
-            const result: IndexItemsResult = await app.hawksearch.index.items.update([item({ [field.trim()]: values })], { indexName });
-            return { summary: `${result.Status ?? '?'} · ${result.Summary?.Succeeded ?? 0} of ${result.Summary?.Total ?? 0} updated`, detail: result };
-        });
-
-    const update = async () => {
-        setOutcomes([]);
-        if (previous === null) {
-            const before = await app.hawksearch.search({ Keyword: itemId.trim(), MaxPerPage: 1 }).catch(() => null);
-            const values = before?.Results?.[0]?.Document?.[field.trim()];
-            setPrevious(Array.isArray(values) ? values : []);
-        }
-        add(await write([value]));
-        add(await read(`search for ${itemId} (after)`));
-    };
-
-    const restore = async () => {
-        setOutcomes([]);
-        add(await write(previous ?? []));
-        add(await read(`search for ${itemId} (restored)`));
-        setPrevious(null);
-    };
-
-    // Expected to be refused: the platform never deletes the current index (needs hawksearch:index:manage, which this
-    // app doesn't ask for, so it shows the scope check instead).
-    const deleteCurrent = async () => {
-        setOutcomes([]);
-        add(await measure('index.deleteIndex(current) (expect 403 scope_missing)', async () => {
-            await app.hawksearch.index.deleteIndex(indexName || 'x');
-            return { summary: 'unexpectedly allowed' };
-        }));
-    };
-
-    return (
-        <Card title="Item writes (hawksearch:index:items)">
-            <p className="muted">
-                Writes go straight into the chosen index. On the current index that&apos;s this engine&apos;s live search: use a test engine and a test item.
-            </p>
-            <div className="buttons">
-                <button onClick={load}>Load indexes</button>
-                <select value={indexName} onChange={(e) => setIndexName(e.target.value)} disabled={!indexNames.length}>
-                    {indexNames.map((n) => (
-                        <option key={n}>{n}</option>
-                    ))}
-                </select>
-            </div>
-            <div className="buttons">
-                <label>
-                    Primary key <input value={primaryKey} onChange={(e) => setPrimaryKey(e.target.value)} size={8} />
-                </label>
-                <label>
-                    Item <input value={itemId} onChange={(e) => setItemId(e.target.value)} placeholder="e.g. sku-1" />
-                </label>
-                <label>
-                    Field <input value={field} onChange={(e) => setField(e.target.value)} placeholder="a field defined in HawkSearch" />
-                </label>
-                <label>
-                    Value <input value={value} onChange={(e) => setValue(e.target.value)} />
-                </label>
-            </div>
-            <label>
-                <input type="checkbox" checked={understood} onChange={(e) => setUnderstood(e.target.checked)} /> I&apos;m on a test engine: change this item now
-            </label>
-            <div className="buttons">
-                <button onClick={update} disabled={!ready}>
-                    Update the field
-                </button>
-                <button onClick={restore} disabled={!ready || previous === null}>
-                    Put the old value back{previous !== null ? ` (${JSON.stringify(previous)})` : ''}
-                </button>
-                <button onClick={deleteCurrent}>Try deleting the index</button>
-            </div>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-/** Recommendations (hawksearch:recommendations): one widget, for an optional product. */
-/** app.config: the values declared in "config" in hawk-app.json, set with `hawk-app config set` or in the portal. */
-function ConfigTab({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-
-    const check = async () => {
-        const results: Outcome[] = [];
-        results.push(
-            await measure('config.all()', async () => {
-                const all = await app.config.all();
-                return { summary: `${Object.keys(all).length} keys: ${Object.keys(all).join(', ') || '(none declared)'}`, detail: all };
-            }),
-        );
-        results.push(
-            await measure("config.get('showcaseGreeting')", async () => {
-                const greeting = await app.config.get<string>('showcaseGreeting');
-                return { summary: greeting === null ? 'null (not set, no default)' : JSON.stringify(greeting) };
-            }),
-        );
-        results.push(
-            await measure("config.get('showcaseNotifyEmails')", async () => {
-                const emails = await app.config.get<string[]>('showcaseNotifyEmails');
-                return { summary: emails === null ? 'null (set it with hawk-app config set showcaseNotifyEmails a@b.com)' : `${emails.length} addresses`, detail: emails };
-            }),
-        );
-        results.push(
-            await measure("config.get('notDeclared')", async () => {
-                const value = await app.config.get('notDeclared');
-                if (value !== null) throw new Error(`expected null, got ${JSON.stringify(value)}`);
-                return { summary: 'null, as expected' };
-            }),
-        );
-        results.push(
-            await measure("config.get('') (refused before calling)", async () => {
-                let refused = false;
-                try {
-                    await app.config.get('');
-                } catch (e) {
-                    refused = e instanceof TypeError;
-                }
-                if (!refused) throw new Error('unexpectedly allowed');
-                return { summary: 'TypeError, as expected' };
-            }),
-        );
-        results.push(
-            await measure("functions.call('echo').config", async () => {
-                const echoed = await app.functions.call<{ config?: Record<string, unknown> }>('echo', { from: 'config tab' });
-                return { summary: `${Object.keys(echoed.config ?? {}).length} keys in ctx.config`, detail: echoed.config };
-            }),
-        );
-        setOutcomes(results);
-    };
-
-    return (
-        <Card title="App config">
-            <p className="muted">
-                Values for the keys in "config" in hawk-app.json: this client's value, else the global one, else the default. Set them with{' '}
-                <code>npx hawk-app config set showcaseGreeting "Hi" [--client &lt;id&gt;]</code> or in the Hawk Analytics portal; they apply within about 30
-                seconds. Not secret: they reach the browser.
-            </p>
-            <button onClick={check}>Run</button>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-function StorageTab({ app }: { app: HawkApp }) {
-    const [notes, setNotes] = useState<StorageListEntry<{ text: string; at: string }>[]>([]);
-    const [text, setText] = useState('');
-    const [usage, setUsage] = useState<StorageUsage | null>(null);
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 20));
-
-    // Notes are shared by everyone at this client who opens the showcase: keys note#<time>, so they list in order.
-    const refresh = async () =>
-        record(
-            await measure('storage.list(note#) + usage()', async () => {
-                const page = await app.storage.list<{ text: string; at: string }>({ prefix: 'note#', values: true, limit: 50 });
-                setNotes(page.items);
-                setUsage(await app.storage.usage());
-                return { summary: `${page.items.length} notes${page.cursor ? ' (more)' : ''}`, detail: page };
-            }),
-        );
-
-    const add = async () => {
-        const at = new Date().toISOString();
-        record(
-            await measure('storage.put(note#…, ttlDays 7)', async () => {
-                const result = await app.storage.put(`note#${at}`, { text: text.trim(), at }, { ttlDays: 7, ifVersion: 0 });
-                return { summary: `v${result.version}, expires ${result.expiresAt?.slice(0, 10)}`, detail: result };
-            }),
-        );
-        setText('');
-        await refresh();
-    };
-
-    const remove = async (key: string, version: number) => {
-        record(await measure(`storage.delete(${key})`, async () => (await app.storage.delete(key, { ifVersion: version }), { summary: 'deleted' })));
-        await refresh();
-    };
-
-    /** Every storage call once, on keys of its own (check#…), cleaned up afterwards. */
-    const check = async () => {
-        const key = `check#${Date.now()}`;
-        const results: Outcome[] = [];
-        results.push(await measure('put (new, ifVersion 0)', async () => ({ summary: `v${(await app.storage.put(key, { n: 1 }, { ifVersion: 0 })).version}` })));
-        results.push(await measure('get', async () => ({ summary: JSON.stringify((await app.storage.get(key))?.value) })));
-        results.push(await expectError('put with a stale ifVersion', 409, 'version_conflict', () => app.storage.put(key, { n: 2 }, { ifVersion: 0 })));
-        results.push(await measure('put (ifVersion 1)', async () => ({ summary: `v${(await app.storage.put(key, { n: 2 }, { ifVersion: 1 })).version}` })));
-        results.push(
-            await measure('batch (get, put, delete)', async () => {
-                const batch = await app.storage.batch({ get: [key, `${key}-missing`], put: [{ key: `${key}-b`, value: 'b' }], delete: [`${key}-b`] });
-                return { summary: `get ${batch.get.map((g) => (g.item ? 'found' : 'missing')).join('/')}, put ${batch.put[0].status}, delete ${batch.delete[0].status}`, detail: batch };
-            }),
-        );
-        results.push(await measure('list (prefix)', async () => ({ summary: `${(await app.storage.list({ prefix: key })).items.length} item` })));
-        results.push(await measure('delete', async () => (await app.storage.delete(key), { summary: 'deleted' })));
-        results.push(await measure('get (deleted)', async () => ({ summary: (await app.storage.get(key)) === null ? 'null, as expected' : 'still there!' })));
-        results.push(
-            await measure('invalid key #usage (refused before calling)', async () => {
-                const refused = await app.storage.get('#usage').then(() => false, (e) => e instanceof TypeError);
-                if (!refused) throw new Error('unexpectedly allowed');
-                return { summary: 'TypeError, as expected' };
-            }),
-        );
-        setOutcomes(results);
-        setUsage(await app.storage.usage());
-    };
-
-    return (
-        <>
-            <Card title="Notes (storage)">
-                <p className="muted">Shared by everyone at this client using the showcase. Each note expires after 7 days.</p>
-                <input value={text} onChange={(e) => setText(e.target.value)} placeholder="A note" />{' '}
-                <button onClick={add} disabled={!text.trim()}>
-                    Add
-                </button>{' '}
-                <button onClick={refresh}>Refresh</button>
-                <ul>
-                    {notes.map((n) => (
-                        <li key={n.key}>
-                            {n.value?.text} <span className="muted">· {n.value?.at.slice(0, 16).replace('T', ' ')} · v{n.version}</span>{' '}
-                            <button onClick={() => remove(n.key, n.version)}>Delete</button>
-                        </li>
-                    ))}
-                </ul>
-                {usage && (
-                    <p className="muted">
-                        Usage: {usage.items} / {usage.maxItems} items, {(usage.bytes / 1024).toFixed(1)} KB / {Math.round(usage.maxBytes / 1048576)} MB
-                    </p>
-                )}
-            </Card>
-            <Card title="Check every call">
-                <button onClick={check}>Run</button>
-                <Results outcomes={outcomes} />
-            </Card>
-            <StorageFilesCard app={app} />
-        </>
-    );
-}
-
-/** storage.files: upload a file (kept 7 days), open or delete it, and a round trip through every call. */
-function StorageFilesCard({ app }: { app: HawkApp }) {
-    const [files, setFiles] = useState<StorageFileEntry[]>([]);
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 20));
-
-    const refresh = async () =>
-        record(
-            await measure('files.list(uploads/)', async () => {
-                const page = await app.storage.files.list({ prefix: 'uploads/' });
-                setFiles(page.files);
-                return { summary: `${page.files.length} files${page.cursor ? ' (more)' : ''}`, detail: page };
-            }),
-        );
-
-    const upload = async (file: File) => {
-        // Paths allow A–Z a–z 0–9 . _ - only.
-        const path = `uploads/${Date.now()}-${file.name.replace(/[^A-Za-z0-9._-]/g, '_')}`;
-        record(
-            await measure(`files.upload(${path})`, async () => {
-                const result = await app.storage.files.upload(path, file, { ttlDays: 7 });
-                return { summary: `${result.size} bytes, ${result.contentType}`, detail: result };
-            }),
-        );
-        await refresh();
-    };
-
-    const open = async (path: string) =>
-        record(
-            await measure(`files.url(${path})`, async () => {
-                const { url, expiresAt } = await app.storage.files.url(path, { download: path.split('/').pop() });
-                await app.navigate({ intent: 'external', url });
-                return { summary: `opened, link works until ${expiresAt.slice(11, 16)} UTC` };
-            }),
-        );
-
-    const remove = async (path: string) => {
-        record(await measure(`files.delete(${path})`, async () => (await app.storage.files.delete(path), { summary: 'deleted' })));
-        await refresh();
-    };
-
-    /** upload → url → download (same bytes back) → list → delete → url is 404, on a path of its own. */
-    const check = async () => {
-        const path = `checks/${Date.now()}.txt`;
-        const text = `showcase check ${new Date().toISOString()}`;
-        const results: Outcome[] = [];
-        results.push(await measure('upload (text, ttlDays 1)', async () => ({ summary: `${(await app.storage.files.upload(path, text, { ttlDays: 1 })).size} bytes` })));
-        results.push(await measure('url', async () => ({ summary: `expires ${(await app.storage.files.url(path)).expiresAt}` })));
-        results.push(
-            await measure('download (same bytes back)', async () => {
-                const back = await (await app.storage.files.download(path)).text();
-                if (back !== text) throw new Error(`got ${JSON.stringify(back)}`);
-                return { summary: 'matches' };
-            }),
-        );
-        results.push(await measure('list (prefix)', async () => ({ summary: `${(await app.storage.files.list({ prefix: path })).files.length} file` })));
-        results.push(await measure('delete', async () => (await app.storage.files.delete(path), { summary: 'deleted' })));
-        results.push(await expectError('url after delete', 404, 'not_found', () => app.storage.files.url(path)));
-        results.push(
-            await measure('usage', async () => {
-                const usage = await app.storage.usage();
-                return { summary: `${usage.files} files, ${(usage.fileBytes / 1024).toFixed(1)} KB of ${Math.round(usage.maxFileBytes / 1073741824)} GB` };
-            }),
-        );
-        setOutcomes(results);
-    };
-
-    return (
-        <Card title="Files (storage.files)">
-            <p className="muted">Uploads are shared by everyone at this client and deleted after 7 days.</p>
-            <input type="file" onChange={(e) => e.target.files?.[0] && upload(e.target.files[0])} /> <button onClick={refresh}>Refresh</button>{' '}
-            <button onClick={check}>Check every call</button>
-            <ul>
-                {files.map((f) => (
-                    <li key={f.path}>
-                        {f.path} <span className="muted">· {(f.size / 1024).toFixed(1)} KB</span> <button onClick={() => open(f.path)}>Open</button>{' '}
-                        <button onClick={() => remove(f.path)}>Delete</button>
-                    </li>
-                ))}
-            </ul>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-function RecommendationsTab({ app }: { app: HawkApp }) {
-    const [widgetGuid, setWidgetGuid] = useState('');
-    const [uniqueId, setUniqueId] = useState('');
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-
-    const run = async () =>
-        setOutcomes([
-            await measure('hawksearch.recommendations()', async () => {
-                const response = await app.hawksearch.recommendations({ widgetUids: [{ widgetGuid: widgetGuid.trim(), uniqueId: uniqueId.trim() || null }] });
-                const items = response.widgetItems?.flatMap((w) => w.recommendationItems ?? []) ?? [];
-                return { summary: `${response.widgetItems?.length ?? 0} widgets, ${items.length} items`, detail: response };
-            }),
-        ]);
-
-    return (
-        <Card title="Recommendations (hawksearch:recommendations)">
-            <label>
-                Widget guid <input value={widgetGuid} onChange={(e) => setWidgetGuid(e.target.value)} placeholder="from HawkSearch's Recommendations page" />
-            </label>{' '}
-            <label>
-                Product id <input value={uniqueId} onChange={(e) => setUniqueId(e.target.value)} placeholder="optional" />
-            </label>{' '}
-            <button onClick={run} disabled={!widgetGuid.trim()}>
-                Get
-            </button>
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
-
-function HostTab({ app }: { app: HawkApp }) {
-    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
-    const [tall, setTall] = useState(false);
-    const record = async (label: string, call: () => Promise<void>) =>
-        setOutcomes([await measure(label, async () => (await call(), { summary: 'sent' })), ...outcomes].slice(0, 10));
-
-    return (
-        <Card title="Host messages">
-            <div className="buttons">
-                {(['info', 'success', 'warning', 'error'] as const).map((variant) => (
-                    <button key={variant} onClick={() => record(`toast ${variant}`, () => app.toast(`Showcase: ${variant} toast`, variant))}>
-                        Toast {variant}
-                    </button>
-                ))}
-                <button onClick={() => record('setTitle', () => app.setTitle(`Showcase · ${new Date().toLocaleTimeString()}`))}>Set title</button>
-                <button onClick={() => record('navigate settings', () => app.navigate({ intent: 'settings' }))}>Navigate: settings</button>
-                <button onClick={() => record('navigate external', () => app.navigate({ intent: 'external', url: 'https://www.hawksearch.com/' }))}>
-                    Navigate: external
-                </button>
-                <button onClick={() => setTall(!tall)}>{tall ? 'Shrink' : 'Grow'} (auto-resize)</button>
-            </div>
-            {tall && <div className="tall">Tall content: the frame should grow to fit.</div>}
-            <Results outcomes={outcomes} />
-        </Card>
-    );
-}
+import {
+    FunctionJobError,
+    HawkApiError,
+    type AiInfo,
+    type AiModel,
+    type AiResult,
+    type AppSchedule,
+    type FunctionJob,
+    type HawkApp,
+    type HawkAppContext,
+    type IndexItemsResult,
+    type IndexRun,
+    type SearchRequest,
+    type SearchResponse,
+    type StorageFileEntry,
+    type StorageListEntry,
+    type StorageUsage,
+    type SystemParameter,
+} from '@bridgeline-digital/hawk-app-bridge/client';
+import { useRef, useState, type ReactNode } from 'react';
+import { useHawkApp } from './useHawkApp';
+
+/**
+ * Internal test app for the Hawk Apps platform. One tab per feature; every call shows its outcome, timing and error
+ * code, so a failing platform change is easy to spot. Not a product: keep it small and keep it working.
+ */
+const TABS = ['Context', 'Analytics', 'Dashboard', 'Search', 'Recommendations', 'Index', 'Storage', 'Config', 'Queries', 'Functions', 'Jobs', 'System parameters', 'AI', 'Host'] as const;
+type Tab = (typeof TABS)[number];
+
+export function App() {
+    const hawk = useHawkApp();
+    const [tab, setTab] = useState<Tab>('Context');
+
+    if (hawk.status === 'connecting') return <p className="muted">Connecting…</p>;
+    if (hawk.status === 'error') return <p className="error">{hawk.message}</p>;
+
+    return (
+        <main>
+            <h2>Hawk Apps Showcase</h2>
+            <nav className="tabs">
+                {TABS.map((t) => (
+                    <button key={t} className={t === tab ? 'active' : ''} onClick={() => setTab(t)}>
+                        {t}
+                    </button>
+                ))}
+            </nav>
+            {tab === 'Context' && <ContextTab context={hawk.context} />}
+            {tab === 'Analytics' && <AnalyticsTab app={hawk.app} context={hawk.context} />}
+            {tab === 'Dashboard' && <DashboardTab app={hawk.app} />}
+            {tab === 'Search' && <SearchTab app={hawk.app} context={hawk.context} />}
+            {tab === 'Recommendations' && <RecommendationsTab app={hawk.app} />}
+            {tab === 'Index' && <IndexTab app={hawk.app} />}
+            {tab === 'Storage' && <StorageTab app={hawk.app} />}
+            {tab === 'Config' && <ConfigTab app={hawk.app} />}
+            {tab === 'Queries' && <QueriesTab app={hawk.app} context={hawk.context} />}
+            {tab === 'Functions' && <FunctionsTab app={hawk.app} context={hawk.context} />}
+            {tab === 'Jobs' && <JobsTab app={hawk.app} />}
+            {tab === 'System parameters' && <SystemParametersTab app={hawk.app} context={hawk.context} />}
+            {tab === 'AI' && <AiTab app={hawk.app} />}
+            {tab === 'Host' && <HostTab app={hawk.app} />}
+        </main>
+    );
+}
+
+// ---------- shared ----------
+
+interface Outcome {
+    label: string;
+    ok: boolean;
+    ms: number;
+    summary: string;
+    detail?: unknown;
+}
+
+/** Runs a call and records how it went: never throws, so one failure doesn't hide the others. */
+async function measure(label: string, call: () => Promise<{ summary: string; detail?: unknown }>): Promise<Outcome> {
+    const started = performance.now();
+    try {
+        const { summary, detail } = await call();
+        return { label, ok: true, ms: Math.round(performance.now() - started), summary, detail };
+    } catch (e) {
+        return { label, ok: false, ms: Math.round(performance.now() - started), summary: describe(e) };
+    }
+}
+
+function describe(e: unknown): string {
+    if (e instanceof HawkApiError) return `${e.status}${e.code ? ` ${e.code}` : ''}: ${e.message}`;
+    return e instanceof Error ? e.message : String(e);
+}
+
+function Results({ outcomes }: { outcomes: Outcome[] }) {
+    if (!outcomes.length) return null;
+    return (
+        <div className="results">
+            {outcomes.map((o, i) => {
+                const line = (
+                    <>
+                        <span className="badge">{o.ok ? 'OK' : 'FAIL'}</span> {o.label} · {o.ms} ms · {o.summary}
+                    </>
+                );
+                // Only results with something to show expand; the rest are a plain line (no empty arrow).
+                return o.detail === undefined || o.detail === null ? (
+                    <div key={i} className={`result ${o.ok ? 'ok' : 'fail'}`}>
+                        {line}
+                    </div>
+                ) : (
+                    <details key={i} className={o.ok ? 'ok' : 'fail'}>
+                        <summary>{line}</summary>
+                        <pre>{typeof o.detail === 'string' ? o.detail : JSON.stringify(o.detail, null, 2)}</pre>
+                    </details>
+                );
+            })}
+        </div>
+    );
+}
+
+function Card({ title, children }: { title: string; children: ReactNode }) {
+    return (
+        <section className="card">
+            <h3>{title}</h3>
+            {children}
+        </section>
+    );
+}
+
+/** The host's date range as YYYY-MM-DD (the last 30 days when the host sends none). */
+function range(context: HawkAppContext): { from: string; to: string } {
+    if (context.dateRange) return { from: context.dateRange.from.slice(0, 10), to: context.dateRange.to.slice(0, 10) };
+    const to = new Date();
+    const from = new Date(to.getTime() - 29 * 86_400_000);
+    return { from: from.toISOString().slice(0, 10), to: to.toISOString().slice(0, 10) };
+}
+
+/** The rows shown under a result: all of them up to 100, so a result can be checked in full. */
+const PREVIEW_ROWS = 100;
+const preview = <T,>(rows: T[]) => rows.slice(0, PREVIEW_ROWS);
+const shown = (rows: unknown[]) => (rows.length > PREVIEW_ROWS ? ` (showing ${PREVIEW_ROWS})` : '');
+
+// ---------- tabs ----------
+
+function ContextTab({ context }: { context: HawkAppContext }) {
+    return (
+        <Card title="Context from the host">
+            <p className="muted">Everything the host sent in the handshake (and later context changes).</p>
+            <pre>{JSON.stringify(context, null, 2)}</pre>
+        </Card>
+    );
+}
+
+function AnalyticsTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const reports = ['searches', 'queries', 'assistant-prompts'];
+
+    const run = async () => {
+        setBusy(true);
+        const results = await Promise.all(
+            reports.map((name) =>
+                measure(`analytics.report('${name}')`, async () => {
+                    const report = await app.analytics.report(name, { limit: 10 });
+                    return { summary: `${report.data.length} rows (total ${report.totalRecords ?? '?'})${shown(report.data)}`, detail: preview(report.data) };
+                }),
+            ),
+        );
+        setOutcomes(results);
+        setBusy(false);
+    };
+
+    return (
+        <Card title="Analytics API (reports:read)">
+            <p className="muted">
+                Dates default to the host range ({range(context).from} – {range(context).to}). Reports: {reports.join(', ')}.
+            </p>
+            <button disabled={busy} onClick={run}>
+                Run reports
+            </button>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+function DashboardTab({ app }: { app: HawkApp }) {
+    const [path, setPath] = useState('Synonym');
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+
+    const run = async () =>
+        setOutcomes([
+            await measure(`dashboard.get('${path}')`, async () => {
+                const data = await app.dashboard.get<unknown>(path);
+                const rows = Array.isArray(data) ? data : null;
+                return { summary: rows ? `${rows.length} items${shown(rows)}` : 'object', detail: rows ? preview(rows) : data };
+            }),
+            // Versioned paths must be rejected: the platform picks the API version.
+            await measure(`dashboard.get('v11/${path}') (expect 400)`, async () => {
+                await app.dashboard.get(`v11/${path}`);
+                return { summary: 'unexpectedly allowed' };
+            }),
+        ]);
+
+    return (
+        <>
+            <Card title="HawkSearch dashboard API (hawksearch:read)">
+                <label>
+                    Path <input value={path} onChange={(e) => setPath(e.target.value)} />
+                </label>{' '}
+                <button onClick={run}>GET</button>
+                <Results outcomes={outcomes} />
+            </Card>
+            <DashboardWriteTest app={app} />
+        </>
+    );
+}
+
+/** HawkSearch's Synonym model (HawkSearch.Contracts.Api.Synonym). */
+interface Synonym {
+    Id: number;
+    SearchTerm: string;
+    SynonymGroup: string;
+    MultiWay: boolean;
+    Comments?: string | null;
+}
+
+/** Expects the call to fail with `status` (and `code`, when given); anything else, including success, is a failure. */
+async function expectError(label: string, status: number, code: string | undefined, call: () => Promise<unknown>): Promise<Outcome> {
+    return measure(`${label} (expect ${status}${code ? ` ${code}` : ''})`, async () => {
+        try {
+            await call();
+        } catch (e) {
+            if (e instanceof HawkApiError && e.status === status && (!code || e.code === code)) return { summary: `${describe(e)} (as expected)` };
+            throw e;
+        }
+        throw new Error('unexpectedly allowed');
+    });
+}
+
+/**
+ * hawksearch:write round trip on a throwaway synonym: create, read back, delete, check it's gone. The synonym is
+ * clearly marked as a test and deleted in the same run (also when the read-back fails).
+ */
+function DashboardWriteTest({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    const roundTrip = async (): Promise<Outcome[]> => {
+        const marker = `hawk-apps-showcase-${Date.now()}`;
+        const body = {
+            SearchTerm: marker,
+            SynonymGroup: `${marker}-a,${marker}-b`,
+            MultiWay: false,
+            Comments: 'Created by the Hawk Apps showcase app (write test); deleted right away. Safe to delete.',
+        };
+        const results: Outcome[] = [];
+        let id: number | undefined;
+
+        results.push(
+            await measure("dashboard.post('Synonym')", async () => {
+                const created = await app.dashboard.post<Synonym>('Synonym', body);
+                id = created?.Id;
+                if (!id) throw new Error(`no Id in the response: ${JSON.stringify(created)}`);
+                return { summary: `created synonym ${id} (${marker})`, detail: created };
+            }),
+        );
+        if (!id) return results;
+
+        results.push(
+            await measure(`dashboard.get('Synonym/${id}')`, async () => {
+                const synonym = await app.dashboard.get<Synonym>(`Synonym/${id}`);
+                if (synonym?.SearchTerm !== marker) throw new Error(`read back ${JSON.stringify(synonym?.SearchTerm)}, expected ${marker}`);
+                return { summary: `read back: ${synonym.SearchTerm} → ${synonym.SynonymGroup}`, detail: synonym };
+            }),
+        );
+        results.push(
+            await measure(`dashboard.delete('Synonym/${id}')`, async () => {
+                const removed = await app.dashboard.delete<Synonym | undefined>(`Synonym/${id}`);
+                return { summary: 'deleted', detail: removed };
+            }),
+        );
+        // HawkSearch answers 404 for a deleted synonym (its own error body, no platform code).
+        results.push(await expectError(`dashboard.get('Synonym/${id}') after delete`, 404, undefined, () => app.dashboard.get(`Synonym/${id}`)));
+        return results;
+    };
+
+    // Field isn't a writable resource. The body is empty, so even a wrongly allowed call couldn't create a field.
+    const notAllowed = () => expectError("dashboard.post('Field')", 403, 'path_not_allowed', () => app.dashboard.post('Field', {}));
+
+    return (
+        <Card title="Write test (hawksearch:write)">
+            <p className="muted">
+                Creates a synonym marked <code>hawk-apps-showcase-…</code> in the current client, reads it back and deletes it. Writes are
+                audit-logged and never retried; 120 per minute per app and client.
+            </p>
+            <div className="buttons">
+                <button disabled={busy} onClick={() => go(roundTrip)}>
+                    Create, read, delete synonym
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await notAllowed()])}>
+                    Error case
+                </button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+/** The part of a search result the tab shows. */
+function searchSummary(result: SearchResponse): { summary: string; detail: unknown } {
+    const results = result.Results ?? [];
+    const total = result.Pagination?.NofResults ?? results.length;
+    const redirect = result.Redirect?.Location ? ` · redirect ${result.Redirect.Location}` : '';
+    return { summary: `${total} results${redirect}`, detail: { total, firstDocIds: results.slice(0, 10).map((r) => r.DocId), response: result } };
+}
+
+/** Runs `work` over `items`, at most `limit` at a time (the platform allows 600 searches per minute per app and client). */
+async function pool<T, R>(items: T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
+    const results: R[] = new Array(items.length);
+    let next = 0;
+    await Promise.all(
+        Array.from({ length: Math.min(limit, items.length) }, async () => {
+            while (next < items.length) {
+                const i = next++;
+                results[i] = await work(items[i]);
+            }
+        }),
+    );
+    return results;
+}
+
+function SearchTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const [keyword, setKeyword] = useState('boots');
+    const [previewDate, setPreviewDate] = useState('');
+    const [keywords, setKeywords] = useState('boots\njacket\nzzz-no-such-product');
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    const search = (label: string, request: SearchRequest) =>
+        measure(label, async () => searchSummary(await app.hawksearch.search(request)));
+
+    const previewRequest = (): SearchRequest => ({
+        Keyword: keyword,
+        IsInPreview: true,
+        ...(previewDate ? { SmartBar: { PreviewDate: `${previewDate}T00:00:00` } } : {}),
+    });
+
+    const autocomplete = () =>
+        measure(`hawksearch.autocomplete({ Keyword: ${JSON.stringify(keyword)} })`, async () => {
+            const result = await app.hawksearch.autocomplete<Record<string, unknown>>({ Keyword: keyword, ProductCount: 5 });
+            const counts = Object.entries(result)
+                .filter(([, v]) => Array.isArray(v))
+                .map(([k, v]) => `${k} ${(v as unknown[]).length}`);
+            return { summary: counts.join(' · ') || 'no lists', detail: result };
+        });
+
+    // Every keyword, 5 at a time; zero-result keywords fail so they stand out.
+    const zeroResults = async (): Promise<Outcome[]> => {
+        const list = [...new Set(keywords.split('\n').map((k) => k.trim()).filter(Boolean))].slice(0, 100);
+        return pool(list, 5, (k) =>
+            measure(`"${k}"`, async () => {
+                const { summary, detail } = searchSummary(await app.hawksearch.search({ Keyword: k, MaxPerPage: 1 }));
+                if (summary.startsWith('0 results')) throw new Error('0 results');
+                return { summary, detail };
+            }),
+        );
+    };
+
+    // The analytics "queries" report (reports:read): the keyword column is the first one named like keyword/query/term.
+    const loadTopQueries = async (): Promise<Outcome[]> => [
+        await measure("analytics.report('queries') → keywords", async () => {
+            const report = await app.analytics.report<Record<string, unknown>>('queries', { limit: 100 });
+            const column = Object.keys(report.data[0] ?? {}).find((c) => /keyword|query|term/i.test(c));
+            if (!column) throw new Error(`no keyword column in ${JSON.stringify(Object.keys(report.data[0] ?? {}))}`);
+            const found = report.data.map((row) => String(row[column] ?? '').trim()).filter(Boolean);
+            setKeywords(found.join('\n'));
+            return { summary: `${found.length} keywords from column "${column}"` };
+        }),
+    ];
+
+    return (
+        <>
+            <Card title="Search (hawksearch:search)">
+                <p className="muted">
+                    HawkSearch v2 search and autocomplete for engine{' '}
+                    {context.engine ? `${context.engine.id}${context.engine.name ? ` (${context.engine.name})` : ''}` : '(none: expect 400 engine_required)'}. The platform
+                    sets the ClientGuid; preview uses the engine's preview search API.
+                </p>
+                <div className="buttons">
+                    <label>
+                        Keyword <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+                    </label>
+                    <label>
+                        Preview date <input type="date" value={previewDate} onChange={(e) => setPreviewDate(e.target.value)} />
+                    </label>
+                </div>
+                <div className="buttons">
+                    <button disabled={busy} onClick={() => go(async () => [await search(`hawksearch.search({ Keyword: ${JSON.stringify(keyword)} })`, { Keyword: keyword })])}>
+                        Search
+                    </button>
+                    <button
+                        disabled={busy}
+                        onClick={() =>
+                            go(() => Promise.all([search('live', { Keyword: keyword }), search(`preview${previewDate ? ` as of ${previewDate}` : ''}`, previewRequest())]))
+                        }
+                    >
+                        Live vs preview
+                    </button>
+                    <button disabled={busy} onClick={() => go(async () => [await autocomplete()])}>
+                        Autocomplete
+                    </button>
+                    <button
+                        disabled={busy}
+                        onClick={() =>
+                            go(async () => [
+                                await search('ClientGuid in the request is replaced (expect normal results)', { Keyword: keyword, ClientGuid: 'not-this-engine' }),
+                                await measure('hawksearch.search(null) (expect TypeError, no call)', async () => {
+                                    try {
+                                        await app.hawksearch.search(null as never);
+                                    } catch (e) {
+                                        if (e instanceof TypeError) return { summary: `${e.message} (as expected)` };
+                                        throw e;
+                                    }
+                                    throw new Error('unexpectedly allowed');
+                                }),
+                            ])
+                        }
+                    >
+                        Error cases
+                    </button>
+                </div>
+                <Results outcomes={outcomes} />
+            </Card>
+            <Card title="Zero-result check">
+                <p className="muted">One keyword per line (up to 100), 5 searches at a time. Keywords with 0 results show as FAIL.</p>
+                <textarea rows={6} value={keywords} onChange={(e) => setKeywords(e.target.value)} />
+                <div className="buttons">
+                    <button disabled={busy} onClick={() => go(loadTopQueries)}>
+                        Load top queries (analytics)
+                    </button>
+                    <button disabled={busy} onClick={() => go(zeroResults)}>
+                        Check keywords
+                    </button>
+                </div>
+            </Card>
+        </>
+    );
+}
+
+function QueriesTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const { from, to } = range(context);
+
+    const query = (label: string, name: string, params: Record<string, unknown>) =>
+        measure(label, async () => {
+            const result = await app.data.query(name, params as never);
+            return {
+                summary: `${result.rowCount} rows · ${result.bytesScanned} B scanned${result.cached ? ' · cached' : ''}${shown(result.rows)}`,
+                detail: preview(result.rows),
+            };
+        });
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    return (
+        <Card title="Queries (data:read)">
+            <p className="muted">
+                Range {from} – {to}. Queries ship in <code>queries/</code> with each version.
+            </p>
+            <div className="buttons">
+                <button disabled={busy} onClick={() => go(async () => [await query('searches-by-day (allowed table)', 'searches-by-day', { from, to })])}>
+                    Allowed table
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await query('searches-by-day again (expect cached)', 'searches-by-day', { from, to })])}>
+                    Repeat (cached)
+                </button>
+                <button
+                    disabled={busy}
+                    onClick={() => go(async () => [await query('assistant-prompts-by-day (sensitive: needs the app opt-in, else TABLE_NOT_FOUND)', 'assistant-prompts-by-day', { from, to })])}
+                >
+                    Sensitive table
+                </button>
+                <button
+                    disabled={busy}
+                    onClick={() =>
+                        go(() =>
+                            // Different ranges so each is a new execution: more than 2 at once per app and client
+                            // hits the limit (429), which the bridge retries until a slot frees up.
+                            Promise.all(
+                                [1, 2, 3, 4, 5].map((n) => {
+                                    const end = new Date(new Date(`${to}T00:00:00Z`).getTime() - n * 86_400_000).toISOString().slice(0, 10);
+                                    return query(`burst #${n} (to ${end})`, 'searches-by-day', { from, to: end });
+                                }),
+                            ),
+                        )
+                    }
+                >
+                    Burst ×5 (concurrency)
+                </button>
+                <button
+                    disabled={busy}
+                    onClick={() =>
+                        go(async () => [
+                            await query('invalid params (expect 400 invalid_params)', 'searches-by-day', { from: 'not-a-date', to }),
+                            await query('unknown query (expect 404 query_not_found)', 'does-not-exist', {}),
+                        ])
+                    }
+                >
+                    Error cases
+                </button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+interface ShowcaseStep {
+    name: string;
+    ok: boolean;
+    ms: number;
+    summary: string;
+    detail?: unknown;
+}
+
+function FunctionsTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const [text, setText] = useState('hello');
+
+    const call = (label: string, name: string, input: unknown) =>
+        measure(label, async () => {
+            const result = await app.functions.call<Record<string, unknown>>(name, input);
+            const facts = ['client', 'user', 'version', 'hasSecret', 'searches'].map((key) => `${key} ${JSON.stringify(result?.[key])}`);
+            return { summary: facts.join(' · '), detail: result };
+        });
+
+    // The showcase reports its own steps: show each as a result row, after a row for the call itself.
+    const showcase = async (): Promise<Outcome[]> => {
+        const started = performance.now();
+        try {
+            const result = await app.functions.call<{ steps: ShowcaseStep[]; totalMs: number; runtime: Record<string, unknown> }>(
+                'showcase',
+                range(context),
+                { timeoutMs: 40_000 },
+            );
+            const passed = result.steps.filter((s) => s.ok).length;
+            return [
+                {
+                    label: 'showcase (round trip)',
+                    ok: passed === result.steps.length,
+                    ms: Math.round(performance.now() - started),
+                    summary: `${passed}/${result.steps.length} steps ok · ${result.totalMs} ms in the function`,
+                    detail: result.runtime,
+                },
+                ...result.steps.map((s) => ({ label: s.name, ok: s.ok, ms: s.ms, summary: s.summary, detail: s.detail })),
+            ];
+        } catch (e) {
+            return [{ label: 'showcase', ok: false, ms: Math.round(performance.now() - started), summary: describe(e) }];
+        }
+    };
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    return (
+        <Card title="Functions (functions:invoke)">
+            <p className="muted">
+                <code>functions/showcase.ts</code> runs every function capability (input validation with an npm package, context, secrets, the
+                analytics and dashboard APIs, an app query, Athena directly with client-scoped credentials, outbound HTTP, and its own logic)
+                and reports each step; <code>functions/echo.ts</code> is the minimal one. Both ship with each version. Needs functions enabled for the app (else 403 functions_not_enabled) and the
+                <code> TEST_SECRET</code> secret (<code>npx hawk-app secrets set TEST_SECRET</code>; else 500 secret_missing).
+            </p>
+            <label>
+                Input <input value={text} onChange={(e) => setText(e.target.value)} />
+            </label>{' '}
+            <div className="buttons">
+                <button disabled={busy} onClick={() => go(showcase)}>
+                    Run showcase
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await call('echo', 'echo', { text, at: new Date().toISOString() })])}>
+                    Call echo
+                </button>
+                <button disabled={busy} onClick={() => go(() => Promise.all([1, 2, 3, 4, 5, 6, 7].map((n) => call(`echo burst #${n}`, 'echo', { n }))))}>
+                    Burst ×7 (concurrency)
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await call('missing function (expect 404 function_not_found)', 'does-not-exist', {})])}>
+                    Error case
+                </button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+/** A job as one result row. */
+function jobOutcome(label: string, job: FunctionJob<Record<string, unknown>>, ms: number): Outcome {
+    const progress = job.progress ? ` · ${job.progress.percent ?? '?'}% ${job.progress.message ?? ''}` : '';
+    return {
+        label,
+        ok: job.status === 'succeeded',
+        ms,
+        summary: `${job.status}${progress}${job.error ? ` · ${job.error.type}${job.error.message ? `: ${job.error.message}` : ''}` : ''}`,
+        detail: job,
+    };
+}
+
+function JobsTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [live, setLive] = useState<FunctionJob | null>(null);
+    const [schedules, setSchedules] = useState<AppSchedule[] | null>(null);
+    const [busy, setBusy] = useState(false);
+    const [steps, setSteps] = useState(10);
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    // Start, then wait while showing progress live.
+    const runJob = async (input: Record<string, unknown>, label: string): Promise<Outcome[]> => {
+        const started = performance.now();
+        try {
+            const { jobId } = await app.functions.start('long-task', input);
+            const job = await app.functions.wait<Record<string, unknown>>(jobId, { intervalMs: 2000, onProgress: (j) => setLive(j) });
+            setLive(null);
+            return [jobOutcome(label, job, Math.round(performance.now() - started))];
+        } catch (e) {
+            setLive(null);
+            if (e instanceof FunctionJobError) {
+                return [jobOutcome(`${label} (failed as a job)`, e.job as FunctionJob<Record<string, unknown>>, Math.round(performance.now() - started))];
+            }
+            return [{ label, ok: false, ms: Math.round(performance.now() - started), summary: describe(e) }];
+        }
+    };
+
+    const listSchedules = () =>
+        measure('schedules.list()', async () => {
+            const list = await app.schedules.list();
+            setSchedules(list);
+            return { summary: `${list.length} schedules · ${list.filter((s) => s.enabled).length} on for this client`, detail: list };
+        });
+
+    const toggle = (schedule: AppSchedule) =>
+        measure(`schedules.${schedule.enabled ? 'disable' : 'enable'}('${schedule.name}')`, async () => {
+            const updated = schedule.enabled ? await app.schedules.disable(schedule.name) : await app.schedules.enable(schedule.name);
+            return { summary: updated.enabled ? 'on' : 'off', detail: updated };
+        });
+
+    return (
+        <>
+            <Card title="Background jobs (functions:invoke, &quot;job&quot;: true)">
+                <p className="muted">
+                    <code>functions/long-task.ts</code> counts through steps (3 s each), reporting progress, and returns what it knows about the run.
+                    Jobs run up to 15 minutes; 3 at once per app and client.
+                </p>
+                <div className="buttons">
+                    <label>
+                        Steps <input type="number" min={1} max={60} value={steps} onChange={(e) => setSteps(Number(e.target.value))} />
+                    </label>
+                    <button disabled={busy} onClick={() => go(() => runJob({ steps }, `long-task (${steps} steps)`))}>
+                        Start and wait
+                    </button>
+                    <button disabled={busy} onClick={() => go(() => runJob({ steps: 2, fail: true }, 'long-task failing (expect failed)'))}>
+                        Failing job
+                    </button>
+                    <button
+                        disabled={busy}
+                        onClick={() =>
+                            go(async () => [
+                                await expectError("functions.call('long-task') (expect 409 function_is_job)", 409, 'function_is_job', () => app.functions.call('long-task', {})),
+                                await expectError("functions.start('echo') (expect 409 function_not_job)", 409, 'function_not_job', () => app.functions.start('echo', {})),
+                            ])
+                        }
+                    >
+                        Error cases
+                    </button>
+                </div>
+                {live && (
+                    <p>
+                        <progress max={100} value={live.progress?.percent ?? 0} /> {live.status} · {live.progress?.percent ?? 0}% {live.progress?.message ?? ''}
+                    </p>
+                )}
+                <Results outcomes={outcomes} />
+            </Card>
+            <Card title="Schedules">
+                <p className="muted">
+                    <code>daily-check</code> runs long-task at 13:00 America/Chicago for each client where it is on (as <code>schedule:daily-check</code>, on this
+                    site, with this client&apos;s HawkSearch connection). Approved schedules only.
+                </p>
+                <div className="buttons">
+                    <button disabled={busy} onClick={() => go(async () => [await listSchedules()])}>
+                        List
+                    </button>
+                </div>
+                {schedules && (
+                    <table className="params">
+                        <thead>
+                            <tr>
+                                <th>Name</th>
+                                <th>Runs</th>
+                                <th>For this client</th>
+                                <th>Last run</th>
+                                <th />
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {schedules.map((s) => (
+                                <tr key={s.name}>
+                                    <td>{s.name}</td>
+                                    <td>
+                                        {s.function} · <code>{s.cron}</code> ({s.timezone})
+                                    </td>
+                                    <td>{s.enabled ? `on (by ${s.enabledBy?.email ?? s.enabledBy?.id ?? '?'})` : 'off'}</td>
+                                    <td>{s.lastRun ? `${new Date(s.lastRun.at).toLocaleString()} · ${s.lastRun.status}${s.lastRun.reason ? ` (${s.lastRun.reason})` : ''}` : '—'}</td>
+                                    <td>
+                                        <button disabled={busy} onClick={() => go(async () => [await toggle(s), await listSchedules()])}>
+                                            {s.enabled ? 'Turn off' : 'Turn on'}
+                                        </button>
+                                    </td>
+                                </tr>
+                            ))}
+                        </tbody>
+                    </table>
+                )}
+            </Card>
+        </>
+    );
+}
+
+/** The names declared in hawk-app.json "systemParameters" (only these can be read or set). */
+const DECLARED_SYSTEM_PARAMETERS = ['Timezone', 'SearchPreviewURL'];
+
+function SystemParametersTab({ app, context }: { app: HawkApp; context: HawkAppContext }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [parameters, setParameters] = useState<SystemParameter[] | null>(null);
+    const [busy, setBusy] = useState(false);
+    const [name, setName] = useState(DECLARED_SYSTEM_PARAMETERS[0]);
+    const [value, setValue] = useState('');
+
+    const go = async (runs: () => Promise<Outcome[]>) => {
+        setBusy(true);
+        setOutcomes(await runs());
+        setBusy(false);
+    };
+
+    const list = () =>
+        measure('hawksearch.systemParameters.list()', async () => {
+            const result = await app.hawksearch.systemParameters.list();
+            setParameters(result.parameters);
+            return { summary: `engine ${result.engineId} · ${result.parameters.length} parameters`, detail: result };
+        });
+
+    const set = () =>
+        measure(`hawksearch.systemParameters.set('${name}', ${JSON.stringify(value)})`, async () => {
+            const result = await app.hawksearch.systemParameters.set(name, value === '' ? null : value);
+            return {
+                summary: `${JSON.stringify(result.previous)} → ${JSON.stringify(result.value)} · applies within ${result.appliesWithinSeconds} s`,
+                detail: result,
+            };
+        });
+
+    const undeclared = () =>
+        measure("hawksearch.systemParameters.set('WebsiteUrl') (undeclared: expect 404 parameter_not_found)", async () => {
+            await app.hawksearch.systemParameters.set('WebsiteUrl', 'https://example.com');
+            return { summary: 'unexpectedly allowed' };
+        });
+
+    return (
+        <Card title="HawkSearch system parameters (hawksearch:sysparams:write)">
+            <p className="muted">
+                Engine {context.engine ? `${context.engine.id}${context.engine.name ? ` (${context.engine.name})` : ''}` : '(none: expect 400 engine_required)'}. Declared in{' '}
+                <code>hawk-app.json</code>: {DECLARED_SYSTEM_PARAMETERS.join(', ')}. Changes apply in HawkSearch within about 3 minutes.
+            </p>
+            <div className="buttons">
+                <button disabled={busy} onClick={() => go(async () => [await list()])}>
+                    List
+                </button>
+            </div>
+            {parameters && (
+                <table className="params">
+                    <thead>
+                        <tr>
+                            <th>Name</th>
+                            <th>Label</th>
+                            <th>Type</th>
+                            <th>Value</th>
+                            <th>Read-only</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {parameters.map((p) => (
+                            <tr key={p.name}>
+                                <td>{p.name}</td>
+                                <td>{p.label ?? ''}</td>
+                                <td>{p.type}</td>
+                                <td>{p.encrypted ? '(encrypted)' : p.value ?? <span className="muted">(not set)</span>}</td>
+                                <td>{p.readOnly ? 'yes' : 'no'}</td>
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            )}
+            <div className="buttons">
+                <select value={name} onChange={(e) => setName(e.target.value)}>
+                    {DECLARED_SYSTEM_PARAMETERS.map((n) => (
+                        <option key={n}>{n}</option>
+                    ))}
+                </select>
+                <input placeholder="value (empty clears it)" value={value} onChange={(e) => setValue(e.target.value)} />
+                <button disabled={busy} onClick={() => go(async () => [await set(), await list()])}>
+                    Set
+                </button>
+                <button disabled={busy} onClick={() => go(async () => [await undeclared()])}>
+                    Error case
+                </button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+function AiTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [busy, setBusy] = useState(false);
+    const [model, setModel] = useState<AiModel>('fast');
+    const [system, setSystem] = useState('');
+    const [prompt, setPrompt] = useState('In two sentences, what is site search merchandising?');
+    const [output, setOutput] = useState('');
+    const [info, setInfo] = useState<AiInfo | null>(null);
+    // Stops the running call (the stream's abort(), or generate's AbortSignal).
+    const stop = useRef<(() => void) | null>(null);
+
+    const request = () => ({ model, prompt, ...(system.trim() ? { system } : {}) });
+    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 10));
+    const summarize = (result: AiResult) => `${result.model} · ${result.stopReason} · ${result.usage.inputTokens} in / ${result.usage.outputTokens} out · id ${result.id}`;
+
+    const stream = async () => {
+        setBusy(true);
+        setOutput('');
+        const s = app.ai.stream(request());
+        stop.current = () => s.abort();
+        record(
+            await measure(`ai.stream({ model: '${model}' })`, async () => {
+                let chunks = 0;
+                for await (const text of s) {
+                    chunks++;
+                    setOutput((previous) => previous + text);
+                }
+                const result = await s.result;
+                return { summary: `${chunks} chunks · ${summarize(result)}`, detail: result };
+            }),
+        );
+        stop.current = null;
+        setBusy(false);
+    };
+
+    const generate = async () => {
+        setBusy(true);
+        setOutput('');
+        const controller = new AbortController();
+        stop.current = () => controller.abort();
+        record(
+            await measure(`ai.generate({ model: '${model}' })`, async () => {
+                const result = await app.ai.generate(request(), { signal: controller.signal });
+                setOutput(result.text);
+                return { summary: summarize(result), detail: result };
+            }),
+        );
+        stop.current = null;
+        setBusy(false);
+    };
+
+    const loadInfo = async () =>
+        record(
+            await measure('ai.info()', async () => {
+                const result = await app.ai.info();
+                setInfo(result);
+                return { summary: result.tiers.map((t) => `${t.name} ${t.usedTokens}/${t.dailyTokens}`).join(' · '), detail: result };
+            }),
+        );
+
+    return (
+        <Card title="AI (ai:invoke)">
+            <p className="muted">
+                Claude through the platform: <code>fast</code> (Haiku) or <code>smart</code> (Sonnet). Every call costs tokens from the tier's daily budget
+                for this client; nothing is retried.
+            </p>
+            <div className="buttons">
+                <select value={model} onChange={(e) => setModel(e.target.value as AiModel)}>
+                    <option value="fast">fast</option>
+                    <option value="smart">smart</option>
+                </select>
+                <button onClick={loadInfo}>Info</button>
+            </div>
+            {info && (
+                <table className="params">
+                    <thead>
+                        <tr>
+                            <th>Tier</th>
+                            <th>Used today</th>
+                            <th>Daily tokens</th>
+                            <th>Max output tokens</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {info.tiers.map((t) => (
+                            <tr key={t.name}>
+                                <td>{t.name}</td>
+                                <td>{t.usedTokens.toLocaleString()}</td>
+                                <td>{t.dailyTokens.toLocaleString()}</td>
+                                <td>{t.maxOutputTokens.toLocaleString()}</td>
+                            </tr>
+                        ))}
+                    </tbody>
+                </table>
+            )}
+            {info && (
+                <p className="muted">
+                    Max input {info.maxInputBytes.toLocaleString()} bytes · {info.requestsPerMinute} requests per minute.
+                </p>
+            )}
+            <textarea rows={2} placeholder="System prompt (optional)" value={system} onChange={(e) => setSystem(e.target.value)} />
+            <textarea rows={4} placeholder="Prompt" value={prompt} onChange={(e) => setPrompt(e.target.value)} />
+            <div className="buttons">
+                <button disabled={busy || !prompt.trim()} onClick={stream}>
+                    Stream
+                </button>
+                <button disabled={busy || !prompt.trim()} onClick={generate}>
+                    Generate
+                </button>
+                <button disabled={!busy} onClick={() => stop.current?.()}>
+                    Stop
+                </button>
+            </div>
+            <textarea rows={10} readOnly value={output} placeholder="The answer appears here as it arrives." />
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+/** Index rebuilds (hawksearch:index): the latest run, and a full rebuild followed to the end. */
+function IndexTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [progress, setProgress] = useState('');
+    const add = (o: Outcome) => setOutcomes((current) => [...current, o]);
+    const describeRun = (r: IndexRun) => `${r.status}${r.done ? ' (done)' : ''} · ${r.count ?? 0} items${r.durationSeconds !== null ? ` · ${r.durationSeconds} s` : ''}`;
+
+    const status = async () => {
+        setOutcomes([]);
+        add(await measure('index.status()', async () => {
+            const run = await app.hawksearch.index.status();
+            return { summary: describeRun(run), detail: run };
+        }));
+    };
+
+    // The Indexing API's reads (engines with their own indexes; others answer 503 indexing_api_not_available).
+    const indexes = async () => {
+        setOutcomes([]);
+        add(await measure('index.indexes()', async () => {
+            const names = await app.hawksearch.index.indexes();
+            return { summary: `${names.length} indexes`, detail: names };
+        }));
+        add(await measure('index.current()', async () => ({ summary: (await app.hawksearch.index.current()) ?? 'none' })));
+    };
+
+    const rebuild = async () => {
+        setOutcomes([]);
+        setProgress('');
+        let id: number | null = null;
+        add(await measure('index.rebuild()', async () => {
+            const started = await app.hawksearch.index.rebuild();
+            id = started.notificationId;
+            return { summary: `#${started.notificationId} ${describeRun(started)}`, detail: started };
+        }));
+        const runId = id as number | null; // set inside the callback above
+        if (runId !== null) {
+            add(await measure(`index.wait(${runId})`, async () => {
+                const final = await app.hawksearch.index.wait(runId, { intervalMs: 10_000, onProgress: (r) => setProgress(describeRun(r)) });
+                return { summary: describeRun(final), detail: final };
+            }));
+        }
+    };
+
+    return (
+        <>
+            <Card title="Index rebuilds (hawksearch:index)">
+                <p className="muted">
+                    A rebuild reloads this engine&apos;s live search from its feed. It needs the engine&apos;s EnableRebuildIndex on, and one runs at a time.
+                </p>
+                <button onClick={indexes}>Indexes</button> <button onClick={status}>Latest rebuild</button>{' '}
+                <button onClick={rebuild}>Rebuild now and wait</button>
+                {progress && <p className="muted">Now: {progress}</p>}
+                <Results outcomes={outcomes} />
+            </Card>
+            <IndexItemsCard app={app} />
+        </>
+    );
+}
+
+/**
+ * Item writes (hawksearch:index:items): one field of one item, updated and read back through search, then put back to
+ * the value it had. The Indexing API applies writes at once: on the current index, that's the engine's live search.
+ */
+function IndexItemsCard({ app }: { app: HawkApp }) {
+    const [indexNames, setIndexNames] = useState<string[]>([]);
+    const [indexName, setIndexName] = useState('');
+    const [primaryKey, setPrimaryKey] = useState('id');
+    const [itemId, setItemId] = useState('');
+    const [field, setField] = useState('');
+    const [value, setValue] = useState('');
+    const [understood, setUnderstood] = useState(false);
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const add = (o: Outcome) => setOutcomes((current) => [...current, o]);
+    const ready = understood && indexName && primaryKey.trim() && itemId.trim() && field.trim();
+
+    const load = async () => {
+        setOutcomes([]);
+        add(await measure('index.indexes() + current()', async () => {
+            const [names, current] = await Promise.all([app.hawksearch.index.indexes(), app.hawksearch.index.current()]);
+            setIndexNames(names);
+            setIndexName(current ?? names[0] ?? '');
+            return { summary: `${names.length} indexes, current: ${current ?? 'none'}`, detail: { names, current } };
+        }));
+    };
+
+    // Each field is an array of values; the item is named by the engine's primary key (set in HawkSearch's fields).
+    const item = (fields: Record<string, unknown[]>) => ({ [primaryKey.trim()]: [itemId.trim()], ...fields });
+
+    // The field's values before the first change, read through search (the live index), to put back afterwards.
+    const [previous, setPrevious] = useState<unknown[] | null>(null);
+
+    /** The item's field as search sees it now (only the current index is searched). */
+    const read = (label: string) =>
+        measure(label, async () => {
+            const found = await app.hawksearch.search({ Keyword: itemId.trim(), MaxPerPage: 1 });
+            const values = found.Results?.[0]?.Document?.[field.trim()];
+            return { summary: `${found.Pagination?.NofResults ?? 0} results · ${field}: ${JSON.stringify(values ?? null)}`, detail: { values, values_raw: found.Results?.[0] } };
+        });
+
+    const write = (values: unknown[]) =>
+        measure(`index.items.update(${itemId}: ${field} = ${JSON.stringify(values)})`, async () => {
+            const result: IndexItemsResult = await app.hawksearch.index.items.update([item({ [field.trim()]: values })], { indexName });
+            return { summary: `${result.Status ?? '?'} · ${result.Summary?.Succeeded ?? 0} of ${result.Summary?.Total ?? 0} updated`, detail: result };
+        });
+
+    const update = async () => {
+        setOutcomes([]);
+        if (previous === null) {
+            const before = await app.hawksearch.search({ Keyword: itemId.trim(), MaxPerPage: 1 }).catch(() => null);
+            const values = before?.Results?.[0]?.Document?.[field.trim()];
+            setPrevious(Array.isArray(values) ? values : []);
+        }
+        add(await write([value]));
+        add(await read(`search for ${itemId} (after)`));
+    };
+
+    const restore = async () => {
+        setOutcomes([]);
+        add(await write(previous ?? []));
+        add(await read(`search for ${itemId} (restored)`));
+        setPrevious(null);
+    };
+
+    // Expected to be refused: the platform never deletes the current index (needs hawksearch:index:manage, which this
+    // app doesn't ask for, so it shows the scope check instead).
+    const deleteCurrent = async () => {
+        setOutcomes([]);
+        add(await measure('index.deleteIndex(current) (expect 403 scope_missing)', async () => {
+            await app.hawksearch.index.deleteIndex(indexName || 'x');
+            return { summary: 'unexpectedly allowed' };
+        }));
+    };
+
+    return (
+        <Card title="Item writes (hawksearch:index:items)">
+            <p className="muted">
+                Writes go straight into the chosen index. On the current index that&apos;s this engine&apos;s live search: use a test engine and a test item.
+            </p>
+            <div className="buttons">
+                <button onClick={load}>Load indexes</button>
+                <select value={indexName} onChange={(e) => setIndexName(e.target.value)} disabled={!indexNames.length}>
+                    {indexNames.map((n) => (
+                        <option key={n}>{n}</option>
+                    ))}
+                </select>
+            </div>
+            <div className="buttons">
+                <label>
+                    Primary key <input value={primaryKey} onChange={(e) => setPrimaryKey(e.target.value)} size={8} />
+                </label>
+                <label>
+                    Item <input value={itemId} onChange={(e) => setItemId(e.target.value)} placeholder="e.g. sku-1" />
+                </label>
+                <label>
+                    Field <input value={field} onChange={(e) => setField(e.target.value)} placeholder="a field defined in HawkSearch" />
+                </label>
+                <label>
+                    Value <input value={value} onChange={(e) => setValue(e.target.value)} />
+                </label>
+            </div>
+            <label>
+                <input type="checkbox" checked={understood} onChange={(e) => setUnderstood(e.target.checked)} /> I&apos;m on a test engine: change this item now
+            </label>
+            <div className="buttons">
+                <button onClick={update} disabled={!ready}>
+                    Update the field
+                </button>
+                <button onClick={restore} disabled={!ready || previous === null}>
+                    Put the old value back{previous !== null ? ` (${JSON.stringify(previous)})` : ''}
+                </button>
+                <button onClick={deleteCurrent}>Try deleting the index</button>
+            </div>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+/** Recommendations (hawksearch:recommendations): one widget, for an optional product. */
+/** app.config: the values declared in "config" in hawk-app.json, set with `hawk-app config set` or in the portal. */
+function ConfigTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+
+    const check = async () => {
+        const results: Outcome[] = [];
+        results.push(
+            await measure('config.all()', async () => {
+                const all = await app.config.all();
+                return { summary: `${Object.keys(all).length} keys: ${Object.keys(all).join(', ') || '(none declared)'}`, detail: all };
+            }),
+        );
+        results.push(
+            await measure("config.get('showcaseGreeting')", async () => {
+                const greeting = await app.config.get<string>('showcaseGreeting');
+                return { summary: greeting === null ? 'null (not set, no default)' : JSON.stringify(greeting) };
+            }),
+        );
+        results.push(
+            await measure("config.get('showcaseNotifyEmails')", async () => {
+                const emails = await app.config.get<string[]>('showcaseNotifyEmails');
+                return { summary: emails === null ? 'null (set it with hawk-app config set showcaseNotifyEmails a@b.com)' : `${emails.length} addresses`, detail: emails };
+            }),
+        );
+        results.push(
+            await measure("config.get('notDeclared')", async () => {
+                const value = await app.config.get('notDeclared');
+                if (value !== null) throw new Error(`expected null, got ${JSON.stringify(value)}`);
+                return { summary: 'null, as expected' };
+            }),
+        );
+        results.push(
+            await measure("config.get('') (refused before calling)", async () => {
+                let refused = false;
+                try {
+                    await app.config.get('');
+                } catch (e) {
+                    refused = e instanceof TypeError;
+                }
+                if (!refused) throw new Error('unexpectedly allowed');
+                return { summary: 'TypeError, as expected' };
+            }),
+        );
+        results.push(
+            await measure("functions.call('echo').config", async () => {
+                const echoed = await app.functions.call<{ config?: Record<string, unknown> }>('echo', { from: 'config tab' });
+                return { summary: `${Object.keys(echoed.config ?? {}).length} keys in ctx.config`, detail: echoed.config };
+            }),
+        );
+        setOutcomes(results);
+    };
+
+    return (
+        <Card title="App config">
+            <p className="muted">
+                Values for the keys in "config" in hawk-app.json: this client's value, else the global one, else the default. Set them with{' '}
+                <code>npx hawk-app config set showcaseGreeting "Hi" [--client &lt;id&gt;]</code> or in the Hawk Analytics portal; they apply within about 30
+                seconds. Not secret: they reach the browser.
+            </p>
+            <button onClick={check}>Run</button>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+function StorageTab({ app }: { app: HawkApp }) {
+    const [notes, setNotes] = useState<StorageListEntry<{ text: string; at: string }>[]>([]);
+    const [text, setText] = useState('');
+    const [usage, setUsage] = useState<StorageUsage | null>(null);
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 20));
+
+    // Notes are shared by everyone at this client who opens the showcase: keys note#<time>, so they list in order.
+    const refresh = async () =>
+        record(
+            await measure('storage.list(note#) + usage()', async () => {
+                const page = await app.storage.list<{ text: string; at: string }>({ prefix: 'note#', values: true, limit: 50 });
+                setNotes(page.items);
+                setUsage(await app.storage.usage());
+                return { summary: `${page.items.length} notes${page.cursor ? ' (more)' : ''}`, detail: page };
+            }),
+        );
+
+    const add = async () => {
+        const at = new Date().toISOString();
+        record(
+            await measure('storage.put(note#…, ttlDays 7)', async () => {
+                const result = await app.storage.put(`note#${at}`, { text: text.trim(), at }, { ttlDays: 7, ifVersion: 0 });
+                return { summary: `v${result.version}, expires ${result.expiresAt?.slice(0, 10)}`, detail: result };
+            }),
+        );
+        setText('');
+        await refresh();
+    };
+
+    const remove = async (key: string, version: number) => {
+        record(await measure(`storage.delete(${key})`, async () => (await app.storage.delete(key, { ifVersion: version }), { summary: 'deleted' })));
+        await refresh();
+    };
+
+    /** Every storage call once, on keys of its own (check#…), cleaned up afterwards. */
+    const check = async () => {
+        const key = `check#${Date.now()}`;
+        const results: Outcome[] = [];
+        results.push(await measure('put (new, ifVersion 0)', async () => ({ summary: `v${(await app.storage.put(key, { n: 1 }, { ifVersion: 0 })).version}` })));
+        results.push(await measure('get', async () => ({ summary: JSON.stringify((await app.storage.get(key))?.value) })));
+        results.push(await expectError('put with a stale ifVersion', 409, 'version_conflict', () => app.storage.put(key, { n: 2 }, { ifVersion: 0 })));
+        results.push(await measure('put (ifVersion 1)', async () => ({ summary: `v${(await app.storage.put(key, { n: 2 }, { ifVersion: 1 })).version}` })));
+        results.push(
+            await measure('batch (get, put, delete)', async () => {
+                const batch = await app.storage.batch({ get: [key, `${key}-missing`], put: [{ key: `${key}-b`, value: 'b' }], delete: [`${key}-b`] });
+                return { summary: `get ${batch.get.map((g) => (g.item ? 'found' : 'missing')).join('/')}, put ${batch.put[0].status}, delete ${batch.delete[0].status}`, detail: batch };
+            }),
+        );
+        results.push(await measure('list (prefix)', async () => ({ summary: `${(await app.storage.list({ prefix: key })).items.length} item` })));
+        results.push(await measure('delete', async () => (await app.storage.delete(key), { summary: 'deleted' })));
+        results.push(await measure('get (deleted)', async () => ({ summary: (await app.storage.get(key)) === null ? 'null, as expected' : 'still there!' })));
+        results.push(
+            await measure('invalid key #usage (refused before calling)', async () => {
+                const refused = await app.storage.get('#usage').then(() => false, (e) => e instanceof TypeError);
+                if (!refused) throw new Error('unexpectedly allowed');
+                return { summary: 'TypeError, as expected' };
+            }),
+        );
+        setOutcomes(results);
+        setUsage(await app.storage.usage());
+    };
+
+    return (
+        <>
+            <Card title="Notes (storage)">
+                <p className="muted">Shared by everyone at this client using the showcase. Each note expires after 7 days.</p>
+                <input value={text} onChange={(e) => setText(e.target.value)} placeholder="A note" />{' '}
+                <button onClick={add} disabled={!text.trim()}>
+                    Add
+                </button>{' '}
+                <button onClick={refresh}>Refresh</button>
+                <ul>
+                    {notes.map((n) => (
+                        <li key={n.key}>
+                            {n.value?.text} <span className="muted">· {n.value?.at.slice(0, 16).replace('T', ' ')} · v{n.version}</span>{' '}
+                            <button onClick={() => remove(n.key, n.version)}>Delete</button>
+                        </li>
+                    ))}
+                </ul>
+                {usage && (
+                    <p className="muted">
+                        Usage: {usage.items} / {usage.maxItems} items, {(usage.bytes / 1024).toFixed(1)} KB / {Math.round(usage.maxBytes / 1048576)} MB
+                    </p>
+                )}
+            </Card>
+            <Card title="Check every call">
+                <button onClick={check}>Run</button>
+                <Results outcomes={outcomes} />
+            </Card>
+            <StorageFilesCard app={app} />
+        </>
+    );
+}
+
+/** storage.files: upload a file (kept 7 days), open or delete it, and a round trip through every call. */
+function StorageFilesCard({ app }: { app: HawkApp }) {
+    const [files, setFiles] = useState<StorageFileEntry[]>([]);
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const record = (outcome: Outcome) => setOutcomes((previous) => [outcome, ...previous].slice(0, 20));
+
+    const refresh = async () =>
+        record(
+            await measure('files.list(uploads/)', async () => {
+                const page = await app.storage.files.list({ prefix: 'uploads/' });
+                setFiles(page.files);
+                return { summary: `${page.files.length} files${page.cursor ? ' (more)' : ''}`, detail: page };
+            }),
+        );
+
+    const upload = async (file: File) => {
+        // Paths allow A–Z a–z 0–9 . _ - only.
+        const path = `uploads/${Date.now()}-${file.name.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+        record(
+            await measure(`files.upload(${path})`, async () => {
+                const result = await app.storage.files.upload(path, file, { ttlDays: 7 });
+                return { summary: `${result.size} bytes, ${result.contentType}`, detail: result };
+            }),
+        );
+        await refresh();
+    };
+
+    const open = async (path: string) =>
+        record(
+            await measure(`files.url(${path})`, async () => {
+                const { url, expiresAt } = await app.storage.files.url(path, { download: path.split('/').pop() });
+                await app.navigate({ intent: 'external', url });
+                return { summary: `opened, link works until ${expiresAt.slice(11, 16)} UTC` };
+            }),
+        );
+
+    const remove = async (path: string) => {
+        record(await measure(`files.delete(${path})`, async () => (await app.storage.files.delete(path), { summary: 'deleted' })));
+        await refresh();
+    };
+
+    /** upload → url → download (same bytes back) → list → delete → url is 404, on a path of its own. */
+    const check = async () => {
+        const path = `checks/${Date.now()}.txt`;
+        const text = `showcase check ${new Date().toISOString()}`;
+        const results: Outcome[] = [];
+        results.push(await measure('upload (text, ttlDays 1)', async () => ({ summary: `${(await app.storage.files.upload(path, text, { ttlDays: 1 })).size} bytes` })));
+        results.push(await measure('url', async () => ({ summary: `expires ${(await app.storage.files.url(path)).expiresAt}` })));
+        results.push(
+            await measure('download (same bytes back)', async () => {
+                const back = await (await app.storage.files.download(path)).text();
+                if (back !== text) throw new Error(`got ${JSON.stringify(back)}`);
+                return { summary: 'matches' };
+            }),
+        );
+        results.push(await measure('list (prefix)', async () => ({ summary: `${(await app.storage.files.list({ prefix: path })).files.length} file` })));
+        results.push(await measure('delete', async () => (await app.storage.files.delete(path), { summary: 'deleted' })));
+        results.push(await expectError('url after delete', 404, 'not_found', () => app.storage.files.url(path)));
+        results.push(
+            await measure('usage', async () => {
+                const usage = await app.storage.usage();
+                return { summary: `${usage.files} files, ${(usage.fileBytes / 1024).toFixed(1)} KB of ${Math.round(usage.maxFileBytes / 1073741824)} GB` };
+            }),
+        );
+        setOutcomes(results);
+    };
+
+    return (
+        <Card title="Files (storage.files)">
+            <p className="muted">Uploads are shared by everyone at this client and deleted after 7 days.</p>
+            <input type="file" onChange={(e) => e.target.files?.[0] && upload(e.target.files[0])} /> <button onClick={refresh}>Refresh</button>{' '}
+            <button onClick={check}>Check every call</button>
+            <ul>
+                {files.map((f) => (
+                    <li key={f.path}>
+                        {f.path} <span className="muted">· {(f.size / 1024).toFixed(1)} KB</span> <button onClick={() => open(f.path)}>Open</button>{' '}
+                        <button onClick={() => remove(f.path)}>Delete</button>
+                    </li>
+                ))}
+            </ul>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+function RecommendationsTab({ app }: { app: HawkApp }) {
+    const [widgetGuid, setWidgetGuid] = useState('');
+    const [uniqueId, setUniqueId] = useState('');
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+
+    const run = async () =>
+        setOutcomes([
+            await measure('hawksearch.recommendations()', async () => {
+                const response = await app.hawksearch.recommendations({ widgetUids: [{ widgetGuid: widgetGuid.trim(), uniqueId: uniqueId.trim() || null }] });
+                const items = response.widgetItems?.flatMap((w) => w.recommendationItems ?? []) ?? [];
+                return { summary: `${response.widgetItems?.length ?? 0} widgets, ${items.length} items`, detail: response };
+            }),
+        ]);
+
+    return (
+        <Card title="Recommendations (hawksearch:recommendations)">
+            <label>
+                Widget guid <input value={widgetGuid} onChange={(e) => setWidgetGuid(e.target.value)} placeholder="from HawkSearch's Recommendations page" />
+            </label>{' '}
+            <label>
+                Product id <input value={uniqueId} onChange={(e) => setUniqueId(e.target.value)} placeholder="optional" />
+            </label>{' '}
+            <button onClick={run} disabled={!widgetGuid.trim()}>
+                Get
+            </button>
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}
+
+function HostTab({ app }: { app: HawkApp }) {
+    const [outcomes, setOutcomes] = useState<Outcome[]>([]);
+    const [tall, setTall] = useState(false);
+    const record = async (label: string, call: () => Promise<void>) =>
+        setOutcomes([await measure(label, async () => (await call(), { summary: 'sent' })), ...outcomes].slice(0, 10));
+
+    return (
+        <Card title="Host messages">
+            <div className="buttons">
+                {(['info', 'success', 'warning', 'error'] as const).map((variant) => (
+                    <button key={variant} onClick={() => record(`toast ${variant}`, () => app.toast(`Showcase: ${variant} toast`, variant))}>
+                        Toast {variant}
+                    </button>
+                ))}
+                <button onClick={() => record('setTitle', () => app.setTitle(`Showcase · ${new Date().toLocaleTimeString()}`))}>Set title</button>
+                <button onClick={() => record('navigate settings', () => app.navigate({ intent: 'settings' }))}>Navigate: settings</button>
+                <button onClick={() => record('navigate external', () => app.navigate({ intent: 'external', url: 'https://www.hawksearch.com/' }))}>
+                    Navigate: external
+                </button>
+                <button onClick={() => setTall(!tall)}>{tall ? 'Shrink' : 'Grow'} (auto-resize)</button>
+            </div>
+            {tall && <div className="tall">Tall content: the frame should grow to fit.</div>}
+            <Results outcomes={outcomes} />
+        </Card>
+    );
+}