@ambitresearch/genie 1.3.1

package/dist/tools/preview.js

@@ -0,0 +1,672 @@
+/**
+ * MCP tool: preview (M4-05 / DRO-267).
+ *
+ * Returns a human-readable summary — the live viewer URL plus a local-only
+ * `file://` fallback — as `content`. The tool advertises the static
+ * `ui://genie/grid` app shell in tools/list for standards-compliant discovery;
+ * the host then delivers this call's input/result to that shell. The result
+ * also retains its query-bearing resource URI for legacy/result-level hosts.
+ *
+ * ── Contract (RFC §6.2.3 / §8.3; this issue's AC1–AC7) ───────────────────────
+ *   input : { kitId, componentName?, group? }                          (AC2)
+ *   output: { content: [{ type:"text", text }],
+ *             _meta: { ui: { resourceUri: "ui://genie/grid?…" } } }     (AC3/AC4)
+ * The `ui://genie/grid` RESOURCE itself is registered by M4-06. The static
+ * tools/list association and query-bearing result URI are emitted
+ * unconditionally; a host without MCP Apps support simply renders the text.
+ *
+ * ── Viewer boot seam (AC5/AC6) ───────────────────────────────────────────────
+ * Booting the Vite dev server is behind an injectable `ViewerBooter` so the
+ * tool has NO hard dependency on `@ambitresearch/genie-viewer` or Vite — the server core
+ * stays independent of the preview framework (CLAUDE.md; RFC §4). The default
+ * booter lazily `import()`s `@ambitresearch/genie-viewer` through a NON-LITERAL specifier
+ * (so `tsc` never hard-resolves it) and degrades gracefully when it is absent —
+ * exactly the OPTIONAL-peer-dependency pattern `refine` uses for Playwright.
+ * A failed boot (Vite missing, port unbindable, kit dir invalid) is caught and
+ * turned into AC6's local `file://<kitDir>/index.html` fallback; MCP Apps can
+ * instead receive a CSP-safe embedded manifest when a previews origin is
+ * configured. `_meta` is still emitted. A `ViewerRegistry` caches one running
+ * viewer per kit dir (AC5).
+ */
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { ensureManifest } from "../manifest/index.js";
+import { getServerTransportKind } from "../transport.js";
+import { filterManifest, GRID_RESOURCE_URI, normalizePreviewsBaseUrl, rewriteCardPaths, } from "../ui/grid-resource.js";
+import { KIT_ID_PATTERN } from "./get_kit.js";
+export const PREVIEW_TOOL_NAME = "mcp__genie__preview";
+/**
+ * Vite dev-server default port. Duplicated as a local literal (rather than
+ * imported from `@ambitresearch/genie-viewer`) so this module carries no build-time edge to
+ * the viewer package — the whole point of the lazy boot seam below. Kept in
+ * sync with `@ambitresearch/genie-viewer`'s `DEFAULT_VIEWER_PORT` (RFC §6.9/§14).
+ */
+export const DEFAULT_VIEWER_PORT = 5173;
+/**
+ * The MCP Apps extension identifier (ext-apps spec 2026-01-26, "Client<>Server
+ * Capability Negotiation"): a host that renders `ui://` app resources
+ * advertises `capabilities.extensions["io.modelcontextprotocol/ui"]` in its
+ * `initialize` request, with `mimeTypes` naming the profiles it can render.
+ */
+export const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** The MCP-Apps HTML profile the grid resource serves (spec §Resource Discovery). */
+export const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** Widget-only tool-result metadata carrying CSP-authorized card routes. */
+export const PREVIEW_EMBEDDED_MANIFEST_META_KEY = "genie/embeddedManifest";
+/**
+ * Authoritative `ui://` capability check: true when the client's `initialize`
+ * capabilities carry the MCP Apps extension with a `mimeTypes` array that
+ * includes {@link MCP_APP_MIME}. This is the spec-defined negotiation. `caps`
+ * is typed `unknown` because the SDK's `ClientCapabilities` models
+ * `extensions` as a passthrough bag — every level is checked defensively.
+ */
+export function hasUiExtensionCapability(caps) {
+    return getUiExtensionCapability(caps) === true;
+}
+/**
+ * Resolve MCP Apps negotiation without collapsing "not advertised" and
+ * "explicitly not supported." A missing `extensions` mechanism returns
+ * `undefined`. This is distinct from an explicit negative because metadata-linked
+ * MCP Apps hosts may omit the extension capability even when they advertise
+ * unrelated extensions. Only a present UI extension with a malformed or
+ * unsupported MIME declaration is a negotiated negative.
+ */
+export function getUiExtensionCapability(caps) {
+    if (typeof caps !== "object" || caps === null)
+        return undefined;
+    if (!Object.prototype.hasOwnProperty.call(caps, "extensions"))
+        return undefined;
+    const extensions = caps.extensions;
+    if (typeof extensions !== "object" || extensions === null)
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(extensions, UI_EXTENSION_ID))
+        return undefined;
+    const ext = extensions[UI_EXTENSION_ID];
+    if (typeof ext !== "object" || ext === null)
+        return false;
+    const mimeTypes = ext.mimeTypes;
+    return Array.isArray(mimeTypes) && mimeTypes.includes(MCP_APP_MIME);
+}
+// ─── Structured stderr log (never stdout — it IS the stdio JSON-RPC stream) ───
+/**
+ * Emit one structured audit/telemetry line to stderr. On the stdio transport
+ * stdout carries the JSON-RPC frames, so any diagnostic MUST go to stderr —
+ * the same convention `plan-guard`, `plan`, and the LLM verbs follow.
+ */
+function logStderr(payload) {
+    process.stderr.write(JSON.stringify(payload) + "\n");
+}
+/**
+ * Build the `ui://genie/grid?…` resource URI (AC3/AC4). The query string always
+ * carries `kitId` and appends the optional `componentName` / `group` filters in
+ * a STABLE order (kitId → componentName → group) so the URI — and thus the
+ * resource M4-06 resolves and any cache keyed on it — is deterministic for a
+ * given argument set. Values are percent-encoded via `URLSearchParams`.
+ */
+export function buildResourceUri(params) {
+    const uri = new URL(GRID_RESOURCE_URI);
+    uri.searchParams.set("kitId", params.kitId);
+    if (params.componentName !== undefined)
+        uri.searchParams.set("componentName", params.componentName);
+    if (params.group !== undefined)
+        uri.searchParams.set("group", params.group);
+    return uri.toString();
+}
+// ─── kitId → kit dir (path safety) ───────────────────────────────────────────
+/** A `kitId` that fails the shared `KIT_ID_PATTERN` shape (traversal guard). */
+export class InvalidKitIdError extends Error {
+    kitId;
+    code = "InvalidKitIdError";
+    constructor(kitId) {
+        super(`Invalid kitId "${kitId}": must be a 3-64 char lowercase slug ([a-z0-9-]). ` +
+            "This guards against path traversal into the kits root.");
+        this.kitId = kitId;
+        this.name = "InvalidKitIdError";
+    }
+}
+/** A well-formed kitId that does not identify an existing kit directory. */
+export class KitNotFoundError extends Error {
+    kitId;
+    code = "KitNotFoundError";
+    constructor(kitId) {
+        super(`Kit "${kitId}" does not exist. Call list_kits or create_kit first.`);
+        this.kitId = kitId;
+        this.name = "KitNotFoundError";
+    }
+}
+/**
+ * Resolve a `kitId` to its on-disk kit directory under `kitsRoot`, rejecting
+ * any id that isn't a well-formed slug BEFORE the `join` — an unvalidated id
+ * like `../../etc` would otherwise escape the kits root (RFC §10 T-13, the same
+ * traversal class `write_files`/`read_file` guard). Only shape is checked here;
+ * Existence is checked by {@link runPreview} before compilation so a missing
+ * slug cannot create a phantom kit through manifest persistence.
+ */
+export function resolveKitDir(kitsRoot, kitId) {
+    if (!KIT_ID_PATTERN.test(kitId)) {
+        throw new InvalidKitIdError(kitId);
+    }
+    return join(kitsRoot, kitId);
+}
+/**
+ * Caches one running viewer per kit directory so repeated `preview` calls reuse
+ * it instead of booting a fresh Vite each time (AC5). Keyed on the resolved kit
+ * dir; concurrent calls for the same dir share ONE in-flight boot (the promise
+ * is cached, not just the resolved value). A boot that REJECTS is evicted so a
+ * later call retries rather than replaying the dead promise forever.
+ */
+export class ViewerRegistry {
+    booter;
+    viewers = new Map();
+    constructor(booter) {
+        this.booter = booter;
+    }
+    queueBrowserOpen(entry, kitDir, target) {
+        const previous = entry.browserOpen?.promise ?? Promise.resolve();
+        const promise = Promise.all([entry.viewer, previous]).then(async ([viewer]) => {
+            try {
+                await viewer.open(target ?? undefined);
+            }
+            catch (error) {
+                logStderr({
+                    event: "preview.browser.open-failed",
+                    kitDir,
+                    ...(target !== null ? { target } : {}),
+                    error: String(error),
+                });
+            }
+        });
+        entry.browserOpen = { target, promise };
+        return promise;
+    }
+    /**
+     * Return the viewer for `kitDir`, booting it on first request. Subsequent
+     * calls for the same dir return the cached (in-flight or resolved) promise.
+     *
+     * Booting and browser opening are tracked separately. Direct callers can use
+     * `open:true` for the base URL, while {@link runPreview}'s local path boots or
+     * reuses headlessly and calls {@link ViewerRegistry.open} after constructing
+     * its filtered target. Repeated requests for the same target share one
+     * promise; a changed filter target is opened again so the requested component
+     * is not hidden behind an older tab.
+     */
+    ensure(kitDir, port = DEFAULT_VIEWER_PORT, open = false) {
+        const existing = this.viewers.get(kitDir);
+        if (existing !== undefined) {
+            if (open) {
+                const browserOpen = existing.browserOpen?.target === null
+                    ? existing.browserOpen.promise
+                    : this.queueBrowserOpen(existing, kitDir, null);
+                return Promise.all([existing.viewer, browserOpen]).then(([viewer]) => viewer);
+            }
+            return existing.viewer;
+        }
+        const booting = this.booter({ kitDir, port, open }).catch((error) => {
+            // Evict the failed boot so the next call retries with a fresh attempt
+            // rather than being handed this same rejected promise (AC5 durability).
+            this.viewers.delete(kitDir);
+            throw error;
+        });
+        const entry = { viewer: booting };
+        if (open) {
+            entry.browserOpen = { target: null, promise: booting.then(() => undefined) };
+        }
+        this.viewers.set(kitDir, entry);
+        return booting;
+    }
+    async open(kitDir, target) {
+        const entry = this.viewers.get(kitDir);
+        if (entry === undefined) {
+            throw new Error(`Viewer for "${kitDir}" must be booted before it can be opened.`);
+        }
+        const browserOpen = entry.browserOpen?.target === target
+            ? entry.browserOpen.promise
+            : this.queueBrowserOpen(entry, kitDir, target);
+        await browserOpen;
+    }
+    /** Tear down every booted viewer (best-effort). For clean shutdown/tests. */
+    async closeAll() {
+        const entries = Array.from(this.viewers.values());
+        this.viewers.clear();
+        await Promise.allSettled(entries.map(async ({ viewer: viewerPromise, browserOpen }) => {
+            const viewer = await viewerPromise;
+            try {
+                await browserOpen?.promise;
+            }
+            finally {
+                await viewer.close();
+            }
+        }));
+    }
+}
+/**
+ * The default `ViewerBooter`. Lazily loads `@ambitresearch/genie-viewer` and boots its Vite
+ * dev server against the kit dir and honors {@link BootRequest.open} for direct
+ * callers. On its local path, {@link runPreview} deliberately passes `false`,
+ * constructs the filter-bearing viewer URL, and invokes
+ * {@link ViewerRegistry.open} separately so browser fallback never opens the
+ * unfiltered base URL. Absent → `false` (never opens), preserving the safe
+ * headless default.
+ * ALL of the viewer's own stdout is routed to STDERR — on the stdio transport
+ * the tool's stdout is the JSON-RPC stream, so the viewer's `Preview:` banner
+ * would corrupt framing if left on stdout.
+ */
+export const defaultViewerBooter = async ({ kitDir, port, open }) => {
+    // Non-literal specifier: keeps `tsc` from resolving the optional dep at build.
+    const specifier = "@ambitresearch/genie-viewer";
+    let mod;
+    try {
+        mod = (await import(specifier));
+    }
+    catch (error) {
+        logStderr({
+            event: "preview.viewer.unavailable",
+            reason: "viewer-package-not-installed",
+            error: String(error),
+        });
+        throw error;
+    }
+    // Route the viewer's stdout to stderr; keep its stderr on stderr.
+    const io = {
+        stdout: (chunk) => process.stderr.write(chunk),
+        stderr: (chunk) => process.stderr.write(chunk),
+    };
+    const handle = await mod.bootViewer({ root: kitDir, port: port ?? DEFAULT_VIEWER_PORT, open: open ?? false }, io);
+    return {
+        url: handle.url,
+        port: handle.port,
+        open: async (target) => {
+            if (handle.open === undefined) {
+                logStderr({
+                    event: "preview.browser.open-unavailable",
+                    reason: "viewer-handle-does-not-support-open",
+                    url: handle.url,
+                });
+                return;
+            }
+            await handle.open(target);
+        },
+        close: () => handle.close(),
+    };
+};
+/** Point filtered cards at one broker-owned kit origin without changing bytes. */
+function rewriteCardPathsForBroker(manifest, registeredKit) {
+    return {
+        ...manifest,
+        components: manifest.components.map((card) => ({
+            ...card,
+            sourcePath: card.path,
+            path: registeredKit.urlFor(card.path),
+        })),
+    };
+}
+/**
+ * True when the operator has opted OUT of preview's server-side browser
+ * auto-open by setting `GENIE_PREVIEW_NO_OPEN` to a truthy value (design
+ * 2026-07-05, piece B — auto-open is opt-OUT, on by default for non-`ui://`
+ * hosts). Any non-empty value other than `0`/`false` (case-insensitive) counts
+ * as set, so `GENIE_PREVIEW_NO_OPEN=1`, `=true`, `=yes` all disable it.
+ */
+export function autoOpenDisabledByEnv(env = process.env) {
+    const raw = env.GENIE_PREVIEW_NO_OPEN;
+    if (raw === undefined)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+/**
+ * Decide whether {@link runPreview} should ask the booter to open a browser.
+ * Only an explicit negotiated negative authorizes auto-open. An omitted
+ * capability is ambiguous (Codex Desktop and tools-only Codex currently look
+ * identical to a custom MCP server), so it receives a viewer URL but never a
+ * surprise system-browser launch.
+ */
+export function shouldAutoOpen(uiCapable, env = process.env, transportKind) {
+    if (uiCapable !== false)
+        return false;
+    if (transportKind !== "stdio")
+        return false;
+    return !autoOpenDisabledByEnv(env);
+}
+/**
+ * Core `preview` logic (exported for direct unit testing without the MCP
+ * transport). Compiles + persists the kit's manifest (piece A) so all three
+ * vehicles render real cards, resolves the kit dir, tries to boot/reuse the
+ * viewer — opening a browser server-side for non-`ui://` hosts (piece B) — and
+ * builds the text summary: the live URL when the viewer is up (AC5), else a
+ * `file://` fallback (AC6). `_meta.ui.resourceUri` is emitted either way
+ * (AC3/AC4), and one `preview.request` line is logged recording the client and
+ * its `ui://` support (AC7). Remote results never expose server-local file
+ * paths; a failed local viewer can deliver a CSP-safe manifest to an MCP App
+ * when a previews origin is configured.
+ */
+export async function runPreview(deps, args, ctx) {
+    // Path-safety BEFORE anything touches the filesystem or boots a server.
+    const kitDir = resolveKitDir(deps.kitsRoot, args.kitId);
+    let kitStat;
+    try {
+        kitStat = await lstat(kitDir);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            throw new KitNotFoundError(args.kitId);
+        }
+        throw error;
+    }
+    if (!kitStat.isDirectory()) {
+        throw new KitNotFoundError(args.kitId);
+    }
+    // Piece A — compile + persist `.genie/manifest.json` at request time so the
+    // Vite / file:// / ui:// vehicles all render real cards (and list_components
+    // sees them) without depending on a prior resource read. An existing empty
+    // kit compiles to an empty manifest; genuine read/write failures propagate.
+    const compile = deps.ensureManifest ?? ensureManifest;
+    const manifest = await compile(kitDir);
+    const filteredManifest = filterManifest(manifest, {
+        componentName: args.componentName,
+        group: args.group,
+    });
+    const env = deps.env ?? process.env;
+    const locality = ctx.locality ?? (ctx.transportKind === "stdio" ? "local" : "remote");
+    const previewsBaseUrl = deps.previewsBaseUrl ?? env.GENIE_PREVIEWS_BASE_URL;
+    const normalizedPreviewsBaseUrl = normalizePreviewsBaseUrl(previewsBaseUrl);
+    const canDeliverEmbeddedManifest = normalizedPreviewsBaseUrl !== undefined || filteredManifest.components.length === 0;
+    // Keep the handshake tri-state. Explicit support is inline-only, explicit
+    // rejection is viewer-only, and omission gets BOTH so metadata-linked hosts
+    // can mount the canvas while tools-only hosts still have a usable URL.
+    const prepareInline = ctx.uiCapable !== false;
+    const prepareViewerFallback = ctx.uiCapable !== true;
+    const getCardAssetBroker = deps.getCardAssetBroker;
+    const useLocalCardBroker = locality === "local" &&
+        ctx.transportKind === "stdio" &&
+        prepareInline &&
+        normalizedPreviewsBaseUrl === undefined &&
+        getCardAssetBroker !== undefined;
+    const useConfiguredPreviewsOrigin = locality === "local" && prepareInline && normalizedPreviewsBaseUrl !== undefined;
+    const readPreviewBytes = deps.readPreviewBytes ??
+        (async (root, path) => {
+            try {
+                return await readFile(join(root, path));
+            }
+            catch {
+                return null;
+            }
+        });
+    let embeddedManifest;
+    let embeddedError;
+    if (locality === "remote") {
+        if (!prepareInline) {
+            embeddedError =
+                "Client does not support MCP Apps; remote-locality previews have no server-side browser fallback.";
+        }
+        else if (canDeliverEmbeddedManifest) {
+            embeddedManifest = await rewriteCardPaths(filteredManifest, {
+                kitId: args.kitId,
+                kitDir,
+                previewsBaseUrl: normalizedPreviewsBaseUrl?.toString(),
+                readPreviewBytes,
+            });
+        }
+        else {
+            embeddedError =
+                previewsBaseUrl !== undefined && previewsBaseUrl !== ""
+                    ? "Invalid GENIE_PREVIEWS_BASE_URL; remote embedded previews require an absolute http(s) origin."
+                    : "Remote embedded previews require GENIE_PREVIEWS_BASE_URL; " +
+                        "the query-bearing resource remains available to result-level hosts.";
+        }
+    }
+    const resourceUri = buildResourceUri({
+        kitId: args.kitId,
+        componentName: args.componentName,
+        group: args.group,
+    });
+    const autoOpen = locality === "local" && shouldAutoOpen(ctx.uiCapable, deps.env, ctx.transportKind);
+    // AC7 — one structured line per request; the sniffed client + its ui:// support.
+    logStderr({
+        event: "preview.request",
+        kitId: args.kitId,
+        client: ctx.clientName ?? null,
+        uiCapable: ctx.uiCapable ?? null,
+        uiCapability: ctx.uiCapable === true ? "supported" : ctx.uiCapable === false ? "unsupported" : "unknown",
+        inlineDelivery: prepareInline,
+        viewerFallback: prepareViewerFallback,
+        localCardBroker: useLocalCardBroker,
+        autoOpen,
+        transport: ctx.transportKind ?? null,
+        ...(args.group !== undefined ? { group: args.group } : {}),
+        ...(args.componentName !== undefined ? { componentName: args.componentName } : {}),
+    });
+    let text;
+    let viewerUrl;
+    let fileUrl;
+    if (locality === "remote") {
+        text =
+            embeddedManifest !== undefined
+                ? "Preview ready in the inline MCP App."
+                : `Remote preview unavailable: ${embeddedError ?? "no declared previews origin"}`;
+    }
+    else {
+        fileUrl = pathToFileURL(join(kitDir, "index.html")).href;
+        if (prepareInline) {
+            if (useConfiguredPreviewsOrigin) {
+                embeddedManifest = await rewriteCardPaths(filteredManifest, {
+                    kitId: args.kitId,
+                    kitDir,
+                    previewsBaseUrl: normalizedPreviewsBaseUrl.toString(),
+                    readPreviewBytes,
+                });
+            }
+            else if (useLocalCardBroker) {
+                // A local UI host already owns the visible MCP App canvas. Give it the
+                // filtered manifest with exact broker origins instead of nesting the
+                // dynamic Vite viewer (which the host's fixed CSP cannot authorize).
+                try {
+                    const broker = await getCardAssetBroker();
+                    const registeredKit = await broker.registerKit(args.kitId, kitDir);
+                    embeddedManifest = rewriteCardPathsForBroker(filteredManifest, registeredKit);
+                }
+                catch (error) {
+                    logStderr({
+                        event: "preview.fallback",
+                        kitId: args.kitId,
+                        reason: "card-asset-broker-failed",
+                        error: String(error),
+                    });
+                    embeddedError = "The local card asset broker could not start.";
+                }
+            }
+            else if (canDeliverEmbeddedManifest) {
+                // An empty result has no card bytes or child-script hashes to authorize,
+                // so it is safe to deliver through an already-mounted tool-result shell.
+                embeddedManifest = await rewriteCardPaths(filteredManifest, {
+                    kitId: args.kitId,
+                    kitDir,
+                    previewsBaseUrl: normalizedPreviewsBaseUrl?.toString(),
+                    readPreviewBytes,
+                });
+            }
+            else {
+                embeddedError =
+                    "No CSP-safe inline card origin is available; configure GENIE_PREVIEWS_BASE_URL.";
+            }
+        }
+        if (prepareViewerFallback) {
+            try {
+                const viewer = await deps.registry.ensure(kitDir, DEFAULT_VIEWER_PORT, false); // AC5 + piece B
+                const url = new URL(viewer.url);
+                if (args.componentName !== undefined)
+                    url.searchParams.set("componentName", args.componentName);
+                if (args.group !== undefined)
+                    url.searchParams.set("group", args.group);
+                viewerUrl = url.toString();
+                if (autoOpen)
+                    await deps.registry.open(kitDir, viewerUrl);
+            }
+            catch (error) {
+                // AC6 — the local viewer could not boot (Vite/@ambitresearch/genie-viewer absent,
+                // port unbindable, …). Preserve any independently prepared inline
+                // manifest, otherwise degrade to the file:// vehicle.
+                logStderr({
+                    event: "preview.fallback",
+                    kitId: args.kitId,
+                    reason: "viewer-boot-failed",
+                    error: String(error),
+                });
+                if (embeddedManifest === undefined && embeddedError === undefined) {
+                    embeddedError =
+                        "The local preview viewer could not start; use the returned file URL or start it manually.";
+                }
+            }
+        }
+        if (embeddedManifest !== undefined && viewerUrl !== undefined) {
+            text =
+                `Preview ready in the inline MCP App.\n` +
+                    `Tools-only fallback running at ${viewerUrl}\n` +
+                    `Or open the kit directly: ${fileUrl}`;
+        }
+        else if (embeddedManifest !== undefined) {
+            text = `Preview ready in the inline MCP App.\nOr open the kit directly: ${fileUrl}`;
+        }
+        else if (viewerUrl !== undefined) {
+            text =
+                (embeddedError === undefined ? "" : `Inline preview unavailable: ${embeddedError}\n`) +
+                    `Preview running at ${viewerUrl}\n` +
+                    `Or open the kit directly: ${fileUrl}`;
+        }
+        else {
+            text =
+                `Preview unavailable: ${embeddedError ?? "no supported delivery path"}\n` +
+                    `Open the kit directly: ${fileUrl}`;
+        }
+    }
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            kitId: args.kitId,
+            ...(args.componentName !== undefined ? { componentName: args.componentName } : {}),
+            ...(args.group !== undefined ? { group: args.group } : {}),
+            ...(viewerUrl !== undefined ? { viewerUrl } : {}),
+            ...(fileUrl !== undefined ? { fileUrl } : {}),
+            ...(ctx.transportKind !== undefined ? { transportKind: ctx.transportKind } : {}),
+            locality,
+            ...(embeddedError !== undefined ? { embeddedError } : {}),
+        },
+        // Same resourceUri under both the MCP-Apps key (`ui.resourceUri`) and the
+        // ChatGPT Apps SDK key (`openai/outputTemplate`, AC6) — cross-vendor link.
+        _meta: {
+            ui: { resourceUri },
+            "openai/outputTemplate": resourceUri,
+            ...(embeddedManifest !== undefined
+                ? { [PREVIEW_EMBEDDED_MANIFEST_META_KEY]: embeddedManifest }
+                : {}),
+        },
+    };
+}
+// ─── MCP registration ────────────────────────────────────────────────────────
+const previewInputSchema = {
+    kitId: z
+        .string()
+        .regex(KIT_ID_PATTERN)
+        .describe("The kit to preview (a genie kitId — lowercase slug)."),
+    componentName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional single-component focus; carried into the ui:// resource query."),
+    group: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional group filter; carried into the ui:// resource query. Empty string rejected."),
+};
+const previewOutputSchema = {
+    kitId: z.string(),
+    componentName: z.string().optional(),
+    group: z.string().optional(),
+    viewerUrl: z.string().optional(),
+    fileUrl: z.string().optional(),
+    transportKind: z.enum(["stdio", "http"]).optional(),
+    locality: z.enum(["local", "remote"]),
+    embeddedError: z.string().optional(),
+};
+/**
+ * Extract the requesting harness's client name from `params._meta.client.name`
+ * (AC7). MCP's `RequestMeta` is a loose object, so this custom key survives to
+ * the handler's `extra._meta`. Defensive about shape — any missing/oddly-typed
+ * level yields `undefined` (→ treated as a non-ui:// host).
+ */
+function sniffClientName(meta) {
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const client = meta.client;
+    if (typeof client !== "object" || client === null)
+        return undefined;
+    const name = client.name;
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * Register `mcp__genie__preview`. One {@link ViewerRegistry} is created per
+ * registration and shared across every call so viewers are reused (AC5). The
+ * handler resolves the client's identity (per-request `_meta` escape hatch,
+ * else the initialize handshake) and its MCP Apps capability, then delegates
+ * to {@link runPreview}.
+ */
+export function registerPreviewTool(server, options) {
+    const registry = new ViewerRegistry(options.booter ?? defaultViewerBooter);
+    const deps = {
+        kitsRoot: options.kitsRoot,
+        registry,
+        env: options.env,
+        ensureManifest: options.ensureManifest,
+        readPreviewBytes: options.readPreviewBytes,
+        previewsBaseUrl: options.previewsBaseUrl,
+        getCardAssetBroker: options.getCardAssetBroker,
+    };
+    server.registerTool(PREVIEW_TOOL_NAME, {
+        title: "Preview kit",
+        description: "Preview a UI kit as a live card grid — call this to SHOW the user a component " +
+            "(typically right after write_files persists one). Compiles + persists the kit " +
+            "manifest so the grid always reflects what's on disk, then returns the viewer URL " +
+            "(booting the Vite viewer on demand and reusing it across calls) plus a local-only " +
+            "file:// fallback. MCP Apps-capable hosts get the inline grid via _meta.ui.resourceUri. " +
+            "Local stdio clients that explicitly negotiate no UI support get a server-opened browser " +
+            "tab (disable with GENIE_PREVIEW_NO_OPEN=1); HTTP deployments never auto-open on " +
+            "the server machine. Optionally focus one component or group.",
+        inputSchema: previewInputSchema,
+        outputSchema: previewOutputSchema,
+        // Standards-compliant discovery happens in tools/list through this static
+        // app shell. The host sends tool input/result to the shell, which renders
+        // the invocation's viewer URL. Keep the query-bearing result URI below for
+        // legacy/result-level hosts and the self-contained embedded resource path.
+        _meta: {
+            ui: { resourceUri: GRID_RESOURCE_URI },
+            "openai/outputTemplate": GRID_RESOURCE_URI,
+        },
+    }, async (args, extra) => {
+        // Client identity: prefer the per-request `_meta.client.name` escape
+        // hatch (tests, exotic proxies), else the `initialize` handshake's
+        // clientInfo — what real hosts actually send (the per-request key was
+        // the original AC7 sniff's blind spot: no production host populates it).
+        const clientName = sniffClientName(extra._meta) ?? server.server.getClientVersion()?.name;
+        // Authoritative MCP Apps capability from the same handshake.
+        const uiCapable = getUiExtensionCapability(server.server.getClientCapabilities());
+        const transportKind = options.transportKind ?? getServerTransportKind(server);
+        const locality = options.locality ?? (transportKind === "stdio" ? "local" : "remote");
+        const result = await runPreview(deps, args, {
+            clientName,
+            uiCapable,
+            transportKind,
+            locality,
+        });
+        return {
+            content: result.content,
+            structuredContent: result.structuredContent,
+            _meta: result._meta,
+        };
+    });
+    return registry;
+}
+//# sourceMappingURL=preview.js.map