@ambitresearch/genie 1.3.1

package/dist/ui/grid-resource.d.ts

@@ -0,0 +1,252 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Manifest, type ManifestCard } from "../manifest/index.js";
+import type { CardAssetBroker, CardAssetKit } from "./card-asset-broker.js";
+/**
+ * The embedded preview resource URI. `v` identifies the wire contract while
+ * the process-scoped nonce prevents hosts from reusing a stale app document
+ * after the MCP server restarts. It remains stable for every read in one
+ * process, so resource registration and tool metadata always agree.
+ */
+export declare const GRID_RESOURCE_URI: string;
+/** The spec-mandated MCP-Apps MIME (stable spec 2026-01-26; RFC §6.5). */
+export declare const GRID_RESOURCE_MIME = "text/html;profile=mcp-app";
+/** The DOM id `viewer.js` reads the inlined manifest from (must match it). */
+export declare const MANIFEST_ELEMENT_ID = "manifest";
+export declare const TOOL_RESULT_SHELL_META = "genie-tool-result-shell";
+/** Legacy sibling asset URIs retained for older experimental hosts. */
+export declare const VIEWER_JS_URI = "ui://genie/viewer.js";
+export declare const VIEWER_CSS_URI = "ui://genie/viewer.css";
+/** Compiles the on-disk kit at `kitDir` to a manifest (default: M3-03). */
+export type ManifestCompiler = (kitDir: string) => Promise<Manifest>;
+/** The three static assets the embedded shell is assembled from. */
+export type ViewerAssetName = "index.html" | "viewer.js" | "viewer.css";
+/** Reads one `@ambitresearch/genie-viewer` static asset's text (default: from disk). */
+export type AssetReader = (name: ViewerAssetName) => Promise<string>;
+/** Reads a preview file's raw bytes for the `data:` fallback, or null. */
+export type PreviewReader = (kitDir: string, relPath: string) => Promise<Buffer | null>;
+/** Embedded transport card: stable kit identity plus its vehicle-specific URL. */
+export interface EmbeddedManifestCard extends ManifestCard {
+    sourcePath: string;
+}
+/** Manifest shape inlined into the embedded viewer document. */
+export interface EmbeddedManifest extends Omit<Manifest, "components"> {
+    components: EmbeddedManifestCard[];
+}
+/** Exact CSP hashes for trusted inline executable/style blocks. */
+export interface InlineCspHashes {
+    scriptHashes: string[];
+    styleHashes: string[];
+}
+/** Options for {@link registerGridResource}. Every collaborator is injectable. */
+export interface GridResourceOptions {
+    /** Kits root — the same value the kit verbs + `preview` resolve against. */
+    kitsRoot: string;
+    /** Manifest compiler seam (default wraps M3-03 `compileManifest`). */
+    compile?: ManifestCompiler;
+    /** Static-asset reader seam (default reads `@ambitresearch/genie-viewer/static`). */
+    readAsset?: AssetReader;
+    /** Preview-bytes reader for the `data:` fallback (default reads from disk). */
+    readPreviewBytes?: PreviewReader;
+    /**
+     * Separate-origin previews host base URL for AC4 (e.g.
+     * `https://previews.example.com`). When set, each card iframe `src` becomes
+     * `${base}/${kitId}/${card.path}`. When absent (solo dev), the handler falls
+     * back to a `data:text/html;base64,…` inline URL built from the preview's
+     * bytes. Defaults to `process.env.GENIE_PREVIEWS_BASE_URL`.
+     */
+    previewsBaseUrl?: string;
+    /**
+     * Lazily resolves the process-scoped local card broker used by UI-capable
+     * hosts. Omit this seam for legacy/unit callers that require the self-
+     * contained `data:` fallback.
+     */
+    getCardAssetBroker?: () => Promise<CardAssetBroker>;
+}
+/**
+ * Resolve `kitId` to its on-disk dir under `kitsRoot`, or `null` when the id is
+ * absent or fails {@link KIT_ID_PATTERN}. Returning `null` (rather than
+ * throwing) lets the handler degrade to an EMPTY grid instead of erroring a
+ * host's `resources/read` — a hostile or malformed `kitId` can never escape the
+ * kits root (RFC §10 T-13, the same guard `preview`/`read_file` apply).
+ */
+export declare function resolveKitDir(kitsRoot: string, kitId: string | undefined): string | null;
+/**
+ * Narrow a manifest to an optional single component and/or group (the
+ * `componentName` / `group` query params `preview` forwards). Exact,
+ * case-sensitive matches — the fuzzy substring search is the viewer's job
+ * (`#q`); this pre-filter is deterministic so the inlined payload is stable for
+ * a given URI. `groups` is recomputed from what survives so no empty section is
+ * inlined. A filter that matches nothing yields an empty-but-valid manifest
+ * (the viewer renders its empty state).
+ */
+export declare function filterManifest(manifest: Manifest, filter: {
+    componentName?: string;
+    group?: string;
+}): Manifest;
+/**
+ * Validate + normalise a configured previews base URL. Returns the parsed
+ * `URL` (its `href` forced to end in `/` so a later relative-join appends
+ * rather than replacing the last path segment) when `raw` is a well-formed
+ * ABSOLUTE `http(s)` URL, else `undefined`. A malformed value (a bare host, a
+ * typo, a non-http scheme) degrades to `undefined` — the caller then falls
+ * back to the solo-dev `data:` transport instead of throwing. Centralising the
+ * one `new URL()` parse here is what keeps `rewriteCardPaths` /`buildCspMeta`
+ * from crashing `resources/read` or server startup on bad config (the exact
+ * failure the reviewer flagged): validate once, branch on the result.
+ */
+export declare function normalizePreviewsBaseUrl(raw: string | undefined): URL | undefined;
+/**
+ * Preserve every card's kit-relative identity as `sourcePath`, then rewrite
+ * `path` to the URL the EMBEDDED tier's iframe should load (AC4). With a valid
+ * `previewsBaseUrl`, that's an absolute `https://` URL on
+ * the separate previews origin (`${base}/${kitId}/${path}`) — the cross-origin
+ * isolation the RFC §6/T-09 recommends. Without one — OR when the configured
+ * base URL is malformed (see {@link normalizePreviewsBaseUrl}) — the preview's
+ * bytes are read and encoded as a `data:text/html;base64,…` URL so the grid is
+ * fully self-contained. A preview whose bytes can't be read keeps its relative
+ * `path` (harmless: that card simply won't resolve in the embedded tier — a
+ * strictly better degradation than dropping the card).
+ *
+ * Card CONTENT is never altered here — only the URL the iframe points at — so
+ * the card stays byte-identical to the `file://`/localhost vehicles (G-5).
+ */
+export declare function rewriteCardPaths(manifest: Manifest, opts: {
+    kitId: string;
+    kitDir: string;
+    previewsBaseUrl?: string;
+    readPreviewBytes: PreviewReader;
+    cardAssetKit?: CardAssetKit;
+    onPreviewHtml?: (html: string) => void;
+}): Promise<EmbeddedManifest>;
+/**
+ * Escape a JSON string for safe embedding inside `<script type="application/
+ * json">`. In JSON, `<`/`>`/`&` only ever occur INSIDE string literals, so
+ * replacing them with their `\uXXXX` escapes yields equivalent, still-valid
+ * JSON that no HTML parser can misread as a `</script>` terminator or a comment
+ * (`<!--`). U+2028/U+2029 are escaped too (defensive; they're legal in JSON but
+ * not in JS string literals, and some embedders re-parse). This is the
+ * canonical safe-embedding transform.
+ */
+export declare function escapeJsonForScript(json: string): string;
+/**
+ * Inject the compiled manifest into the viewer's `index.html` as an inline
+ * `<script type="application/json" id="manifest">` (AC2), placed just before
+ * `</head>` so it parses before `viewer.js` runs. If no `</head>` is present
+ * (defensive — the shipped shell always has one) the script is prepended, which
+ * still parses before the body script. The manifest is JSON-escaped so a
+ * hostile component name/path can't break out of the script element.
+ */
+export declare function inlineManifest(indexHtml: string, manifest: Manifest): string;
+/**
+ * Parse HTML and hash its trusted inline `<script>` / `<style>` text exactly as
+ * the browser sees it. External scripts have no inline bytes and are ignored.
+ */
+export declare function collectInlineCspHashes(html: string): InlineCspHashes;
+/**
+ * Make the MCP App document self-contained. A host receives one raw HTML
+ * resource; browser-relative `ui://` siblings are not additional resources/read
+ * calls, so the exact viewer JS/CSS bytes must travel inside that document.
+ */
+export declare function inlineViewerAssets(indexHtml: string, viewerJs: string, viewerCss: string): {
+    html: string;
+    hashes: InlineCspHashes;
+};
+/**
+ * MCP Apps domain declarations plus genie's stricter in-document CSP.
+ * Resources/read cannot deliver an HTTP response header; compliant hosts build
+ * their sandbox CSP from the domain arrays under `_meta.ui.csp`.
+ */
+export interface GridCspMeta {
+    /** `fetch()`/XHR targets — empty: the manifest is inlined, nothing to fetch. */
+    connectDomains: string[];
+    /** External static-resource origins; empty because the document is self-contained. */
+    resourceDomains: string[];
+    /** Origins allowed as per-card iframe sources (the previews host or `data:`). */
+    frameDomains: string[];
+    /** Strict hash-based policy injected into the self-contained HTML document. */
+    metaPolicy: string;
+}
+/**
+ * Build the AC5 domain allow-list and strict hash-based document policy.
+ *
+ * The card iframes load from the previews origin when configured, else from
+ * `data:` (solo dev). `connectDomains` is always empty — `connect-src 'none'`
+ * — because the manifest travels inline (AC2); there is nothing to fetch.
+ * `img-src` permits `data:`/`https:` for card thumbnails. The domain shape
+ * matches the stable MCP Apps 2026-01-26 `_meta.ui.csp` contract.
+ *
+ * Hardening applied vs the pre-M4-07 policy:
+ *   • Removed `'unsafe-inline'` / `'unsafe-eval'` (AC3). The exact inlined
+ *     viewer assets and legitimate inline blocks inside data-backed cards are
+ *     allow-listed by SHA-256. Event-handler attributes remain blocked because
+ *     the policy does not opt into `'unsafe-hashes'`.
+ *   • Added `base-uri 'none'` — no `<base href>` can redirect URLs.
+ *   • Added `form-action 'none'` and `object-src 'none'` — deny `<form>` /
+ *     `<object>` / `<embed>` per AC1's "deny form/object/embed" line.
+ * Resources/read has no HTTP-header channel, so no raw header policy or
+ * `frame-ancestors` claim is advertised.
+ */
+export declare function buildCspMeta(previewsBaseUrl: string | undefined, inlineHashes?: InlineCspHashes, exactFrameDomains?: readonly string[]): GridCspMeta;
+/**
+ * Render a `<meta http-equiv="Content-Security-Policy" content="…">` tag for
+ * the given policy meta. Uses {@link GridCspMeta.metaPolicy}.
+ *
+ * The `content` attribute value is HTML-attribute-escaped (`&`, `"`, `<`, `>`)
+ * defensively. In current use the policy string is server-authored with no
+ * user input, so the escape is defence-in-depth against a future change that
+ * accidentally embeds a `"` — without it the attribute would terminate early
+ * and the policy would silently degrade.
+ */
+export declare function cspMetaTag(meta: GridCspMeta): string;
+/**
+ * Inject the enforced CSP meta into an assembled document. Placed at the very
+ * top of `<head>` so every subsequent element — the manifest data island,
+ * inlined `viewer.js`/`viewer.css`, any inline attributes — is parsed under
+ * the policy. If the shell has no `<head>` (defensive; every shipped shell
+ * does) the tag is prepended so it still parses first.
+ */
+export declare function injectCspMeta(html: string, meta: GridCspMeta): string;
+/** Canonical MCP Apps resource metadata (stable 2026-01-26 shape). */
+export declare function gridResourceMeta(previewsBaseUrl: string | undefined, exactFrameDomains?: readonly string[]): Record<string, unknown>;
+/** Fully-resolved dependencies for {@link buildGridDocument}. */
+interface ResolvedDeps {
+    kitsRoot: string;
+    compile: ManifestCompiler;
+    readAsset: AssetReader;
+    readPreviewBytes: PreviewReader;
+    previewsBaseUrl: string | undefined;
+    getCardAssetBroker?: () => Promise<CardAssetBroker>;
+    cardAssetKit?: CardAssetKit;
+    exactFrameDomains?: readonly string[];
+    denyRequestedKit?: boolean;
+}
+/**
+ * Produce the embedded grid HTML for a resource URI's query params. Resolves
+ * the kit (path-guarded), compiles + filters the manifest, rewrites card paths
+ * for the embedded tier (AC4), inlines the result into the viewer shell
+ * (AC2/AC3), and injects the enforced CSP meta (M4-07 AC1) so browsers apply
+ * the hardened policy at parse time. Every failure mode degrades to a still-
+ * valid, still-hardened document: an absent/invalid `kitId` or an
+ * uncompilable kit yields an EMPTY manifest (the viewer's empty state);
+ * unreadable viewer assets yield the {@link fallbackShell} (also CSP-injected).
+ */
+export declare function buildGridDocument(deps: ResolvedDeps, params: {
+    kitId?: string;
+    componentName?: string;
+    group?: string;
+}): Promise<string>;
+/**
+ * Register `ui://genie/grid` and its sibling assets on `server`.
+ *
+ * Routing (verified against the installed SDK): the SDK matches a static
+ * resource by EXACT `uri.toString()` and a template via `UriTemplate.match`.
+ * `preview` emits `ui://genie/grid?kitId=…` with optional extra params, so a
+ * single static registration (no query) or a rigid `{?kitId,…}` template (all-
+ * or-nothing) would miss most real URIs. We therefore register BOTH a static
+ * `ui://genie/grid` (the bare URI) and a `{+rest}` catch-all template that
+ * matches any query-bearing URI; both dispatch to the same handler, which reads
+ * its params off the full `URL`. Legacy sibling assets remain plain statics.
+ */
+export declare function registerGridResource(server: McpServer, options: GridResourceOptions): void;
+export {};
+//# sourceMappingURL=grid-resource.d.ts.map

package/dist/ui/grid-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-resource.d.ts","sourceRoot":"","sources":["../../src/ui/grid-resource.ts"],"names":[],"mappings":"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"}