@vantageos/mosaic 0.4.0 → 0.5.0

package/dist/host.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Compile-time mirror of `@vantageos/mosaic-i18n` EN/FR locales for all
+ * Mosaic components (v0.3.0). Inlined here so that `<Comp>` renderers can
+ * resolve `t(key, locale)` without dragging react-i18next into the component
+ * runtime (keeps bundle small and tests provider-free). Drift is gated by
+ * `mosaic-registry-drift-check.mjs` which validates the canonical
+ * `packages/mosaic-i18n/src/locales/{en,fr}.json` against `registry.yaml`.
+ *
+ * Mosaic standard §8: production JSX MUST resolve user-facing strings via
+ * `t()` — no hardcoded English literals.
+ *
+ * Forms keys added — v0.3.0-C-PR1 (Axis 5/6 i18n pass).
+ * Convention: Forms.<Component>.<context>.<id>
+ */
+type MosaicLocale = "en" | "fr";
+
+/**
+ * Typed `ui/update-model-context` content blocks (H03) and the `openai/modelContext` reader.
+ *
+ * Spec: openai/mcp-extensions docs/spec.md, "ui/update-model-context Extensions"
+ * (local copy openai-mcp-ext-spec.md):
+ *   l.1022  `_meta["openai/title"]`: non-empty string on `text` and `image` blocks.
+ *   l.1042  `_meta["openai/thumbnail"]`: an `MCP.Icon` on `text` blocks (not yet on iOS, l.1046).
+ *   l.1070  `annotations.audience: ["assistant"]` hides a block from the user (the model still
+ *           receives it).
+ *   l.1072  serialized `structuredContent` in a text block SHOULD set audience `["assistant"]`.
+ *   l.945   `ui/update-model-context` is idempotent: each call replaces the app's previous context,
+ *           so an empty `content` array is how a cleared selection is expressed.
+ *   l.962-975 `hostContext["openai/modelContext"]` = `{ updateId, content?, structuredContent? }`
+ *           or `null` once the user removed it.
+ * Everything here is additive: a host that ignores `_meta` loses only the label.
+ */
+
+/** `MCP.Icon` (the fields a thumbnail needs). */
+interface IconLike {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+}
+type ModelContextBlock = {
+    type: string;
+    [key: string]: unknown;
+};
+interface TextBlockOptions {
+    /** `_meta["openai/title"]`: a human-readable label for the attachment. */
+    title?: string;
+    /** `_meta["openai/thumbnail"]`. */
+    thumbnail?: IconLike;
+    /** `annotations.audience: ["assistant"]`: context for the model, no composer attachment. */
+    background?: boolean;
+}
+type ModelContextHostState = {
+    updateId: string;
+    content?: ModelContextBlock[];
+    structuredContent?: Record<string, unknown>;
+} | null;
+declare function textBlock(text: string, options?: TextBlockOptions): ModelContextBlock;
+/** Backward-compatible serialization of `structuredContent`, hidden from the user (spec l.1072). */
+declare function structuredContentBlock(value: Record<string, unknown>): ModelContextBlock;
+declare function buildModelContext(input: {
+    blocks?: ModelContextBlock[];
+    structuredContent?: Record<string, unknown>;
+}): ModelContextParams;
+/**
+ * Reads `hostContext["openai/modelContext"]`. `undefined`: key absent or malformed; `null`:
+ * the host reports the context cleared.
+ */
+declare function readModelContextState(raw: unknown): ModelContextHostState | undefined;
+/**
+ * What the model should know about a table selection: one titled block listing each selected row
+ * as `header: value` pairs. An empty selection yields an empty `content`, which replaces (clears)
+ * the previous context because the call is idempotent per app instance.
+ */
+declare function selectionModelContext(rows: Array<Record<string, unknown>>, columns: Array<{
+    key: string;
+    header: string;
+}>, locale?: MosaicLocale): ModelContextParams;
+
+/**
+ * Safe-area insets (H01).
+ *
+ * Spec: MCP Apps 2026-01-26 (ext-apps-spec.mdx l.582-587) `HostContext.safeAreaInsets`
+ * = `{ top, right, bottom, left }` in pixels. Claude design guidelines: apply them as padding on
+ * the root container (or as `scroll-padding` on scroll-snap containers). Pure and DOM-free
+ * except `applySafeAreaInsets`, which takes its target element explicitly.
+ */
+interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Reads `hostContext.safeAreaInsets`; `undefined` unless all four sides are finite px >= 0. */
+declare function readSafeAreaInsets(raw: unknown): SafeAreaInsets | undefined;
+/** CSS padding shorthand (top right bottom left). */
+declare function safeAreaPadding(insets: SafeAreaInsets): string;
+/**
+ * Applies the insets as padding on `root` and exposes them as `--mosaic-safe-area-<side>` for
+ * scroll-padding. `undefined` clears both (the host reported none).
+ */
+declare function applySafeAreaInsets(insets: SafeAreaInsets | undefined, root: HTMLElement): void;
+
+/**
+ * Host style variables and fonts (H02) — framework-agnostic, structural (no ext-apps import).
+ *
+ * Spec: MCP Apps 2026-01-26 (ext-apps-spec.mdx):
+ *   l.547-555  `HostContext.styles = { variables?: Record<McpUiStyleVariableKey, string|undefined>,
+ *              css?: { fonts?: string } }`
+ *   l.799-888  `McpUiStyleVariableKey`, the 76 standardized keys below (extracted from the spec
+ *              block by command, not retyped)
+ *   l.895-905  "Views should set default fallback values ... to account for hosts who don't pass
+ *              some or all style variables": here the mosaic-tokens defaults are the fallback,
+ *              because only the variables the host passes are written.
+ * Claude transparent-theming page: fonts need `https://assets.claude.ai` in `resourceDomains`;
+ * html and body backgrounds are set to `transparent`.
+ * Composes with ext-apps `applyHostStyleVariables` / `applyDocumentTheme` structurally; either can
+ * be used instead, nothing here imports them.
+ */
+declare const MCP_STYLE_VARIABLE_KEYS: readonly ["--color-background-primary", "--color-background-secondary", "--color-background-tertiary", "--color-background-inverse", "--color-background-ghost", "--color-background-info", "--color-background-danger", "--color-background-success", "--color-background-warning", "--color-background-disabled", "--color-text-primary", "--color-text-secondary", "--color-text-tertiary", "--color-text-inverse", "--color-text-info", "--color-text-danger", "--color-text-success", "--color-text-warning", "--color-text-disabled", "--color-text-ghost", "--color-border-primary", "--color-border-secondary", "--color-border-tertiary", "--color-border-inverse", "--color-border-ghost", "--color-border-info", "--color-border-danger", "--color-border-success", "--color-border-warning", "--color-border-disabled", "--color-ring-primary", "--color-ring-secondary", "--color-ring-inverse", "--color-ring-info", "--color-ring-danger", "--color-ring-success", "--color-ring-warning", "--font-sans", "--font-mono", "--font-weight-normal", "--font-weight-medium", "--font-weight-semibold", "--font-weight-bold", "--font-text-xs-size", "--font-text-sm-size", "--font-text-md-size", "--font-text-lg-size", "--font-heading-xs-size", "--font-heading-sm-size", "--font-heading-md-size", "--font-heading-lg-size", "--font-heading-xl-size", "--font-heading-2xl-size", "--font-heading-3xl-size", "--font-text-xs-line-height", "--font-text-sm-line-height", "--font-text-md-line-height", "--font-text-lg-line-height", "--font-heading-xs-line-height", "--font-heading-sm-line-height", "--font-heading-md-line-height", "--font-heading-lg-line-height", "--font-heading-xl-line-height", "--font-heading-2xl-line-height", "--font-heading-3xl-line-height", "--border-radius-xs", "--border-radius-sm", "--border-radius-md", "--border-radius-lg", "--border-radius-xl", "--border-radius-full", "--border-width-regular", "--shadow-hairline", "--shadow-sm", "--shadow-md", "--shadow-lg"];
+type McpStyleVariableKey = (typeof MCP_STYLE_VARIABLE_KEYS)[number];
+interface HostStyles {
+    variables: Partial<Record<McpStyleVariableKey, string>>;
+    fonts: string | undefined;
+}
+/**
+ * Host variable -> mosaic-tokens custom properties it drives. Declared mapping (a design
+ * decision, not a spec fact); `style-variables.test.ts` asserts every target exists in
+ * `mosaic-tokens/src/tokens.css`.
+ */
+declare const HOST_TO_MOSAIC_TOKENS: Partial<Record<McpStyleVariableKey, readonly string[]>>;
+/** Origin Claude serves host fonts from; add it to `resourceDomains` to load `styles.css.fonts`. */
+declare const CLAUDE_HOST_FONT_ORIGIN = "https://assets.claude.ai";
+/** Reads `hostContext.styles`; unknown keys and non-string values are dropped. */
+declare function readHostStyles(raw: unknown): HostStyles | undefined;
+/**
+ * Writes the host variables on `root`, and the mosaic-tokens custom properties they drive.
+ * Variables a previous call set and this one no longer carries are cleared; `undefined` clears
+ * all. Variables the host never passed are not written, so mosaic-tokens defaults remain.
+ */
+declare function applyHostStyleVariables(styles: HostStyles | undefined, root: HTMLElement): void;
+/** Injects `styles.css.fonts` as one `<style>` in `<head>`; replaced on change, removed when absent. */
+declare function applyHostFonts(css: string | undefined, doc: Document): void;
+/** Claude transparent theming: html and body backgrounds are explicitly `transparent`. */
+declare function applyTransparentBackground(doc: Document): void;
+
+/** Failure of a host request (`ui/message`, `ui/open-link`): carries the method and the reason. */
+declare class HostRequestError extends Error {
+    readonly method: string;
+    readonly reason: string;
+    constructor(method: string, reason: string);
+}
+interface SendMessageOptions {
+    target?: "active" | "new";
+    send?: boolean;
+}
+type MessagingAppLike = Pick<HostAppLike, "getHostContext" | "getHostCapabilities" | "sendMessage" | "openLink">;
+/** Sends `text` as a user message. Options need `openai/message` and a non-mobile platform. */
+declare function sendMessage(app: MessagingAppLike, text: string, options?: SendMessageOptions): Promise<void>;
+/** Asks the host to open an http(s) URL. A denial is thrown with the host's own reason. */
+declare function openLink(app: MessagingAppLike, url: string): Promise<void>;
+
+/**
+ * Host-context layer — framework-agnostic core.
+ *
+ * Reads the MCP Apps host context (spec 2026-01-26, `ui/notifications/host-context-changed`)
+ * through the `@modelcontextprotocol/ext-apps` `App` API, and layers the OpenAI Apps SDK
+ * additions on top, strictly additive: a view works with no `openai/*` key at all.
+ *
+ * The `App` is typed STRUCTURALLY (`HostAppLike`): this module imports nothing at runtime, so
+ * mosaic takes no dependency on ext-apps and any `App` instance satisfies the shape. No DOM
+ * access happens at import time; `applyMosaicTheme` takes the target element explicitly.
+ */
+
+type HostDisplayMode = "inline" | "fullscreen" | "pip";
+/** Display modes a mosaic view may request. `pip` is typed out: it is never requested. */
+type RequestableDisplayMode = "inline" | "fullscreen";
+/** The two themes mosaic-tokens styles (`[data-theme="dark"]` overrides the light `:root`). */
+type MosaicTheme = "light" | "dark";
+type HostContainerDimensions = {
+    height?: number;
+    maxHeight?: number;
+    width?: number;
+    maxWidth?: number;
+};
+/** Raw host context: the spec's open `[key: string]: unknown` record. */
+type RawHostContext = Record<string, unknown>;
+interface MosaicHostContext {
+    theme: MosaicTheme;
+    displayMode: HostDisplayMode;
+    availableDisplayModes: HostDisplayMode[];
+    locale: string | undefined;
+    containerDimensions: HostContainerDimensions | undefined;
+    /**
+     * `hostContext["openai/deepLink"]` when the host provides it: `{ url }`, an app-relative URL
+     * (openai/mcp-extensions docs/spec.md l.149-210, `DeepLinkHostState`).
+     */
+    deepLink: {
+        url: string;
+    } | undefined;
+    /** `hostContext.safeAreaInsets` (MCP Apps spec l.582-587), pixels; undefined when absent. */
+    safeAreaInsets: SafeAreaInsets | undefined;
+    /** `hostContext.styles` (MCP Apps spec l.547-555); undefined when the host passes none. */
+    styles: HostStyles | undefined;
+    /** `hostContext["openai/modelContext"]`: the attached context; null = cleared, undefined = absent. */
+    modelContext: ModelContextHostState | undefined;
+    isChatGpt: boolean;
+    raw: RawHostContext;
+}
+interface ModelContextParams {
+    content?: Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}
+type HostCapabilitiesLike = {
+    experimental?: Record<string, unknown>;
+};
+/** The slice of the ext-apps `App` this layer uses. */
+interface HostAppLike {
+    getHostContext(): RawHostContext | undefined;
+    requestDisplayMode(params: {
+        mode: HostDisplayMode;
+    }): Promise<{
+        mode: HostDisplayMode;
+    }>;
+    updateModelContext(params: ModelContextParams): Promise<unknown>;
+    getHostCapabilities?(): HostCapabilitiesLike | undefined;
+    /** ext-apps `App.sendMessage` (`ui/message`, spec l.998-1030). */
+    sendMessage?(params: {
+        role: "user";
+        content: Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+        _meta?: Record<string, unknown>;
+    }): Promise<{
+        isError?: boolean;
+    }>;
+    /** ext-apps `App.openLink` (`ui/open-link`, spec l.965-995). */
+    openLink?(params: {
+        url: string;
+    }): Promise<{
+        isError?: boolean;
+    }>;
+    onhostcontextchanged?: ((params: RawHostContext) => void) | undefined;
+}
+/** Thrown when a display mode is requested that mosaic refuses for the current host. */
+declare class DisplayModeRefusedError extends Error {
+    readonly mode: string;
+    constructor(mode: string);
+}
+/** host theme -> mosaic-tokens theme. Anything that is not "dark" renders light. */
+declare function mapHostTheme(theme: unknown): MosaicTheme;
+/**
+ * ChatGPT host detection.
+ *
+ * DECLARED DIVERGENCE: the OpenAI spec defines no host-identification value (`hostInfo.name` is
+ * free-form, e.g. "example-host"), so there is no spec signal to read. The best available
+ * evidence is the vendor namespace the spec reserves for ChatGPT: any `openai/*` key in the
+ * host context (e.g. `openai/deepLink`, `openai/modelContext`) or in
+ * `hostCapabilities.experimental` (e.g. `openai/files`, `openai/message`). No user-agent
+ * sniffing. A ChatGPT host that sends neither is not detected; `pip` is typed out regardless,
+ * so the runtime refusal is a second line, not the only one.
+ */
+declare function isChatGptHost(raw: unknown, capabilities?: HostCapabilitiesLike | null): boolean;
+declare function readHostContext(raw: unknown, capabilities?: HostCapabilitiesLike | null): MosaicHostContext;
+/** Sets `data-theme` on `root`: the attribute mosaic-tokens' dark overrides key on. */
+declare function applyMosaicTheme(theme: MosaicTheme, root: Element): void;
+/**
+ * Request a display mode. `pip` is excluded by the type and refused at runtime for a ChatGPT
+ * host (a caller that casts past the type still cannot reach the host with it).
+ */
+declare function requestDisplayMode(app: HostAppLike, mode: RequestableDisplayMode): Promise<{
+    mode: HostDisplayMode;
+}>;
+/** `ui/update-model-context`: tell the model what the user is looking at. */
+declare function updateModelContext(app: HostAppLike, params: ModelContextParams): Promise<unknown>;
+/** Read the live context of an app, with the same ChatGPT detection `requestDisplayMode` uses. */
+declare function readAppHostContext(app: HostAppLike): MosaicHostContext;
+/**
+ * Subscribe to host context changes. Any number of subscribers, unsubscribed in any order.
+ * Notifications carry a partial context, merged over what the app already holds.
+ */
+declare function subscribeHostContext(app: HostAppLike, listener: (ctx: MosaicHostContext) => void): () => void;
+
+export { CLAUDE_HOST_FONT_ORIGIN, DisplayModeRefusedError, HOST_TO_MOSAIC_TOKENS, type HostAppLike, type HostCapabilitiesLike, type HostContainerDimensions, type HostDisplayMode, HostRequestError, type HostStyles, type IconLike, MCP_STYLE_VARIABLE_KEYS, type McpStyleVariableKey, type MessagingAppLike, type ModelContextBlock, type ModelContextHostState, type ModelContextParams, type MosaicHostContext, type MosaicTheme, type RawHostContext, type RequestableDisplayMode, type SafeAreaInsets, type SendMessageOptions, type TextBlockOptions, applyHostFonts, applyHostStyleVariables, applyMosaicTheme, applySafeAreaInsets, applyTransparentBackground, buildModelContext, isChatGptHost, mapHostTheme, openLink, readAppHostContext, readHostContext, readHostStyles, readModelContextState, readSafeAreaInsets, requestDisplayMode, safeAreaPadding, selectionModelContext, sendMessage, structuredContentBlock, subscribeHostContext, textBlock, updateModelContext };