@ai-matrx/chat 0.6.6 → 0.7.1

package/dist/host/composer-extensions.d.ts

@@ -0,0 +1,75 @@
+/**
+ * host/composer-extensions — what a host adds AROUND a conversation's composer, never inside the
+ * package's required pieces. Two optional registrations; with nothing registered both draw
+ * NOTHING (no stand-in text, no empty row) and the package behaves exactly as before.
+ *
+ *  1. ATTACHMENT SOURCES — a host-owned thing the person attaches to the next message (a page
+ *     highlight, a connected-drive file). A source contributes
+ *       - `Chip`: its chip, drawn in the composer's EXISTING attachment rail (never a new row;
+ *         the chip decides for itself whether it renders anything), and
+ *       - `contribute`: the payload that rides the outgoing turn as `context` keys, through the
+ *         same door the host's pre-send gate uses (`execute-instance` merges it onto the request).
+ *
+ *  2. CONVERSATION COMPANION PANELS — a host panel keyed by conversation id (a task panel, notes).
+ *     The rail draws one small pill per registered companion; the pill opens/closes the host's
+ *     `Panel`, which the host draws however it likes (a drawer, a sheet).
+ *
+ * Both are plain host registrations (like `registerChatUi`): `register…` returns the release.
+ */
+import { type ComponentType, type ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+export interface ComposerAttachmentSourceInput {
+    conversationId: string;
+}
+export interface ComposerAttachmentSource {
+    /** Stable id; registering the same id again replaces the earlier registration. */
+    id: string;
+    /** The chip, drawn inline in the composer's attachment rail. Return null to draw nothing. */
+    Chip: ComponentType<ComposerAttachmentSourceInput>;
+    /**
+     * Context keys this source puts on the outgoing turn. Return null/undefined/{} to add nothing.
+     * Runs once per send, just before the request is assembled; a throw is reported and skipped
+     * (the turn still goes — a broken optional source never blocks a message).
+     */
+    contribute?: (input: ComposerAttachmentSourceInput) => Record<string, unknown> | null | undefined | Promise<Record<string, unknown> | null | undefined>;
+}
+export interface ConversationCompanionPanelProps {
+    conversationId: string;
+    open: boolean;
+    onClose: () => void;
+}
+export interface ConversationCompanionPanel {
+    id: string;
+    /** Full name — the pill's tooltip and the overflow-menu row. */
+    label: string;
+    /** ONE word on the pill face. */
+    word: string;
+    icon: LucideIcon;
+    /** Optional live state for the pill; `hidden` removes it for this conversation. */
+    usePill?: (conversationId: string) => {
+        detail?: string;
+        hidden?: boolean;
+    } | null | undefined;
+    /** The host's panel. Drawn always (so it can animate); it draws nothing itself while `open` is false. */
+    Panel: ComponentType<ConversationCompanionPanelProps>;
+}
+/** Register a composer attachment source. Returns the release. */
+export declare const registerComposerAttachmentSource: (item: ComposerAttachmentSource) => () => void;
+/** Register a conversation companion panel. Returns the release. */
+export declare const registerConversationCompanion: (item: ConversationCompanionPanel) => () => void;
+export declare function listComposerAttachmentSources(): readonly ComposerAttachmentSource[];
+export declare function listConversationCompanions(): readonly ConversationCompanionPanel[];
+/** Tests only. */
+export declare function resetComposerExtensionsForTests(): void;
+export declare function useComposerAttachmentSources(): readonly ComposerAttachmentSource[];
+export declare function useConversationCompanions(): readonly ConversationCompanionPanel[];
+/**
+ * Every registered source's chip, in registration order. Draws NOTHING when none is registered.
+ * Chips are expected to be inline pills sized like the rail's own (they sit in its row).
+ */
+export declare function ComposerAttachmentSourceChips({ conversationId }: ComposerAttachmentSourceInput): ReactNode;
+/**
+ * The context every registered source puts on this turn, merged in registration order. A source
+ * that throws or rejects is skipped and reported through `onError`; the others still contribute.
+ */
+export declare function collectAttachmentSourceContext(conversationId: string, onError?: (sourceId: string, error: unknown) => void): Promise<Record<string, unknown> | null>;

package/dist/host/composer-extensions.js

@@ -0,0 +1,92 @@
+"use client";
+import {
+  Fragment,
+  useSyncExternalStore
+} from "react";
+import { createElement } from "react";
+const EMPTY = [];
+function createRegistry() {
+  let items = EMPTY;
+  const listeners = /* @__PURE__ */ new Set();
+  const emit = () => {
+    for (const l of [...listeners]) l();
+  };
+  return {
+    register(item) {
+      items = [...items.filter((i) => i.id !== item.id), item];
+      emit();
+      return () => {
+        if (items.includes(item)) {
+          items = items.filter((i) => i !== item);
+          emit();
+        }
+      };
+    },
+    list: () => items,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    clear() {
+      items = EMPTY;
+      emit();
+    }
+  };
+}
+const sources = createRegistry();
+const companions = createRegistry();
+const registerComposerAttachmentSource = sources.register;
+const registerConversationCompanion = companions.register;
+function listComposerAttachmentSources() {
+  return sources.list();
+}
+function listConversationCompanions() {
+  return companions.list();
+}
+function resetComposerExtensionsForTests() {
+  sources.clear();
+  companions.clear();
+}
+function useComposerAttachmentSources() {
+  return useSyncExternalStore(sources.subscribe, sources.list, sources.list);
+}
+function useConversationCompanions() {
+  return useSyncExternalStore(companions.subscribe, companions.list, companions.list);
+}
+function ComposerAttachmentSourceChips({ conversationId }) {
+  const list = useComposerAttachmentSources();
+  if (list.length === 0) return null;
+  return createElement(
+    Fragment,
+    null,
+    list.map((source) => createElement(source.Chip, { key: source.id, conversationId }))
+  );
+}
+async function collectAttachmentSourceContext(conversationId, onError) {
+  const list = sources.list();
+  if (list.length === 0) return null;
+  const merged = {};
+  for (const source of list) {
+    if (!source.contribute) continue;
+    try {
+      const part = await source.contribute({ conversationId });
+      if (part) Object.assign(merged, part);
+    } catch (error) {
+      onError?.(source.id, error);
+    }
+  }
+  return Object.keys(merged).length > 0 ? merged : null;
+}
+export {
+  ComposerAttachmentSourceChips,
+  collectAttachmentSourceContext,
+  listComposerAttachmentSources,
+  listConversationCompanions,
+  registerComposerAttachmentSource,
+  registerConversationCompanion,
+  resetComposerExtensionsForTests,
+  useComposerAttachmentSources,
+  useConversationCompanions
+};

package/dist/host/configure.js

@@ -146,6 +146,7 @@ function resolveChatHost(host) {
     canvas: host.canvas ?? createUnhostedCanvas(() => ref.diagnostics),
     routing: host.routing ?? ANY_ROUTING,
     deviceTools: host.deviceTools ?? null,
+    microphone: host.microphone ?? null,
     engineHeldTools: new Set(host.engineHeldTools ?? []),
     overridden
   });

package/dist/host/contract.d.ts

@@ -522,17 +522,17 @@ export interface ChatWindowsPort {
     Shell?: ComponentType<ChatWindowShellProps>;
 }
 /**
- * Host registrations (R5). All optional. Each family is keyed by the id the
- * package looks up; P20/P21/P19 narrow the value types per family.
+ * Host registrations (R5). Only what the package reads: tool renderers, context-item bodies,
+ * message widgets, surface manifests and compute targets register through their own doors
+ * (`registerToolRenderer`, `registerChatUi`, `registerSurfaceManifests`, ...), never here.
  */
 export interface ChatRegistrations {
-    toolRenderers?: Readonly<Record<string, unknown>>;
-    contextItemBodies?: Readonly<Record<string, unknown>>;
-    messageWidgets?: Readonly<Record<string, unknown>>;
-    surfaceManifests?: readonly unknown[];
-    contextSources?: readonly unknown[];
-    computeTargets?: readonly unknown[];
-    builderDoors?: Readonly<Record<string, unknown>>;
+    /**
+     * The host's per-turn context sources (`ChatContextSource`): each adds capabilities + state,
+     * context entries and/or the turn's device reference to every request, start and resume.
+     * Absent or empty: requests are exactly what the package builds.
+     */
+    contextSources?: readonly ChatContextSource[];
 }
 export interface ChatHeaderPortalProps {
     desktop?: ReactNode;
@@ -780,11 +780,99 @@ export type ChatDeviceToolInvocation = {
  * wedge). Absent: delegated device tools go to the installed browser extension through the server
  * port (`invokeMatrxExtendTool`), as on the web.
  */
+export interface ChatMicrophonePort {
+    /**
+     * Obtain microphone permission where the host CAN show the browser's prompt (an extension side
+     * panel cannot; its host opens a small window that can). Called by package code that opens the
+     * microphone when the browser refused it (`NotAllowedError`). Resolve `true` once the person
+     * allowed it — the package then retries the capture once — `false` if they did not.
+     */
+    requestPermission(): Promise<boolean>;
+}
 export interface ChatDeviceToolsPort {
-    invoke(toolName: string, args: Record<string, unknown>, context: {
-        conversationId: string;
-        callId: string;
-    }): Promise<ChatDeviceToolInvocation>;
+    invoke(toolName: string, args: Record<string, unknown>, context: ChatDeviceToolContext): Promise<ChatDeviceToolInvocation>;
+    /**
+     * The document is going away (`pagehide`) with delegated device-tool calls still awaiting their
+     * answer (running, or waiting on the person's approval). The package will NOT submit those
+     * results — this document is dying — so the host owns each handed-off call from here: finish it
+     * (the run it already started, or start it if it never began), submit the result to the server
+     * durably (with replay if the network is down), and let the run continue. On reopen the package
+     * rejoins the conversation as usual. Optional: absent = the call stays pending on the server and
+     * the package re-surfaces it on reopen (cold resume), as before. Must not throw; return fast.
+     */
+    handOff?(calls: readonly ChatDeviceToolHandOff[]): void;
+}
+/** A delegated device-tool call handed to the host as the document goes away (`ChatDeviceToolsPort.handOff`). */
+export interface ChatDeviceToolHandOff {
+    conversationId: string;
+    /** The package's request key for the turn the call belongs to. */
+    requestId: string;
+    callId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Whether a device tool that changes something asks the person first (`"ask"`) or just acts
+ * (`"act"`). Chosen per agent in the composer (shown only when the host has `deviceTools`), stored
+ * through the prefs port, latched when the person sends, and handed to every call of that turn.
+ * The host's own gate enforces it; privileged tools always ask.
+ */
+export type ChatDevicePermissionMode = "ask" | "act";
+/** What every device-tool call carries besides its name and arguments. */
+export interface ChatDeviceToolContext {
+    conversationId: string;
+    callId: string;
+    /** The conversation's agent, when known. */
+    agentId: string | null;
+    /** The person's ask/act choice for this agent, latched at send time. */
+    permissionMode: ChatDevicePermissionMode;
+    /**
+     * The host's opaque reference for the device state the person sent from (a browser host: the
+     * tab), as its context sources returned it when the turn started. Undefined when the host gave none.
+     */
+    deviceRef?: unknown;
+}
+/** Which moment of a turn the package is building a request for. */
+export type ChatHostTurnPhase = "start" | "resume";
+export interface ChatHostTurnInput {
+    conversationId: string;
+    agentId: string | null;
+    phase: ChatHostTurnPhase;
+}
+/**
+ * What a host adds to one turn's request. Every member is optional; an empty contribution adds
+ * nothing.
+ */
+export interface ChatHostTurnContribution {
+    /**
+     * Server-registered client capabilities this host offers, by name, each with its
+     * `client.state` payload — or `null` for a stateless capability (declared, no state entry).
+     * A name the package's own providers already declared is left to them.
+     */
+    capabilities?: Readonly<Record<string, Record<string, unknown> | null>>;
+    /**
+     * Entries merged into the request's `context`. Never overwrites a key the person or the agent
+     * already set.
+     */
+    context?: Readonly<Record<string, unknown>>;
+    /**
+     * An opaque reference captured when the person sends (a browser host: the tab they sent
+     * from). Handed back to `deviceTools.invoke` for every call of that turn, resumes included.
+     */
+    deviceRef?: unknown;
+}
+/**
+ * One host context source (registered in `ChatRegistrations.contextSources`): the page the
+ * person is on, the browser's tool capability, an auto-attach rule… Asked on BOTH turn start and
+ * resume — the package's one envelope builder serves both. Every source runs in parallel under a
+ * bounded wait; one that answers too late or throws is skipped for that request and the skip is
+ * announced through diagnostics. Sources merge in registration order: the first to name a
+ * capability, a context key or a device reference keeps it.
+ */
+export interface ChatContextSource {
+    /** Stable id, for diagnostics. */
+    id: string;
+    contribute(input: ChatHostTurnInput): Promise<ChatHostTurnContribution | null>;
 }
 export interface ChatRoutingPort {
     policy(conversationId: string): ChatRoutingPolicy;
@@ -870,6 +958,8 @@ export interface ChatHost {
     routing?: ChatRoutingPort;
     /** Default: none — delegated device tools go to the browser extension via the server port. */
     deviceTools?: ChatDeviceToolsPort;
+    /** Default: none — a refused microphone stays refused (see `ChatMicrophonePort`). */
+    microphone?: ChatMicrophonePort;
     /**
      * Delegated tools THIS HOST'S OWN ENGINE holds and answers, so the package must not: Matrx Local's
      * engine parks `google_email_send` for the person's review (it survives a reload or a closed
@@ -908,6 +998,8 @@ export interface ResolvedChatHost {
     routing: ChatRoutingPort;
     /** The host's on-device tool executor, or null. */
     deviceTools: ChatDeviceToolsPort | null;
+    /** The host's microphone grant flow, or null. */
+    microphone: ChatMicrophonePort | null;
     /** Delegated tool names the host's own engine answers (`ChatHost.engineHeldTools`). */
     engineHeldTools: ReadonlySet<string>;
     overridden: ReadonlySet<ChatPortName>;

package/dist/host/defaults/confirm.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The package's own confirm (gap 4, AUDIT-C): a bare host asks the person for real.
+ *
+ * `confirm({...})` is kit's imperative opener (`@ai-matrx/kit/confirm-opener`) and the dialog body
+ * is design-system's `ConfirmDialogHost`, which `BareHostChrome` mounts. A host that registers its
+ * own `confirm` (matrx-frontend: its `ConfirmDialogHost` wrapper) is used instead.
+ *
+ * It always settles: the person answers; or no dialog host appeared within the wait, and then the
+ * host's notifier says the question could not be asked and the answer is `false` (nothing is done,
+ * and the person is told why — never a button that silently does nothing).
+ */
+import { type ConfirmOptions } from "@ai-matrx/kit/confirm-opener";
+/** How long a call waits for a dialog host to register (it mounts with the chat provider). */
+export declare const CONFIRM_HOST_WAIT_MS = 5000;
+export declare function defaultConfirm(options: ConfirmOptions, waitMs?: number): Promise<boolean>;

package/dist/host/defaults/confirm.js

@@ -0,0 +1,25 @@
+import { confirm as openConfirm, confirmOpener } from "@ai-matrx/kit/confirm-opener";
+import { getChatHost, isChatHostConfigured } from "../configure.js";
+const CONFIRM_HOST_WAIT_MS = 5e3;
+async function waitForConfirmHost(timeoutMs) {
+  if (confirmOpener._hasHost()) return true;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    if (confirmOpener._hasHost()) return true;
+  }
+  return false;
+}
+async function defaultConfirm(options, waitMs = CONFIRM_HOST_WAIT_MS) {
+  if (!await waitForConfirmHost(waitMs)) {
+    const sentence = "The question could not be shown, so nothing was done. Reload and try again.";
+    if (isChatHostConfigured()) getChatHost().notify.error(sentence);
+    console.error(`[chat confirm] no confirm dialog is mounted. ${sentence}`);
+    return false;
+  }
+  return openConfirm(options);
+}
+export {
+  CONFIRM_HOST_WAIT_MS,
+  defaultConfirm
+};

package/dist/host/defaults/files-ui.d.ts

@@ -0,0 +1,85 @@
+export declare function useDefaultFileActions(fileId: string): {
+    download: () => Promise<void>;
+};
+export interface DefaultFileDocument {
+    processed_document_id: string;
+    derivation_kind: string;
+    total_pages: number | null;
+    chunk_count: number | null;
+    has_clean_content: boolean;
+    updated_at: string;
+}
+export type DefaultFileDocumentState = {
+    status: "idle";
+} | {
+    status: "loading";
+} | {
+    status: "found";
+    doc: DefaultFileDocument;
+} | {
+    status: "absent";
+} | {
+    status: "unavailable";
+    reason: string;
+};
+/** The newest live processed document whose source is this file (the same read the website makes). */
+export declare function lookupDefaultFileDocument(fileId: string): Promise<DefaultFileDocumentState>;
+export declare function useDefaultFileDocument(fileId: string | null): {
+    state: DefaultFileDocumentState;
+    refresh: () => void;
+};
+export interface DefaultFileFamilyRepresentation {
+    key: string;
+    label: string;
+    category: string;
+    count: number;
+    promotable: boolean;
+    fetch_tool: string;
+}
+export interface DefaultFileResourceFamily {
+    schema_version: number;
+    resource_type: "file";
+    requested_file_id: string;
+    root_file_id: string | null;
+    files: ReadonlyArray<Record<string, unknown>>;
+    processed_documents: ReadonlyArray<Record<string, unknown>>;
+    representations: DefaultFileFamilyRepresentation[];
+    capabilities: string[];
+    counts: Record<string, number>;
+}
+export declare function parseDefaultFileResourceFamily(value: unknown): DefaultFileResourceFamily;
+export declare function useDefaultFileResourceFamily(fileId: string | null): {
+    data: DefaultFileResourceFamily | null;
+    loading: boolean;
+    error: string | null;
+};
+export interface DefaultFileResourceChipProps {
+    fileId: string | null | undefined;
+    fileHint?: {
+        fileName?: string | null;
+        mimeType?: string | null;
+    } | null;
+    nameOverride?: string | null;
+    badge?: string | null;
+    size?: "xs" | "sm" | "md";
+    onOpen?: () => void;
+    onRemove?: () => void;
+    className?: string;
+}
+/** One attached file as a chip: its icon and name (read from the files engine), open and remove. */
+export declare function DefaultFileResourceChip({ fileId, fileHint, nameOverride, badge, onOpen, onRemove, className }: DefaultFileResourceChipProps): import("react").JSX.Element;
+export interface DefaultMediaAttachmentThumbnailProps {
+    mediaRef: {
+        file_id?: string | null;
+        url?: string | null;
+        mime_type?: string | null;
+        file_name?: string | null;
+    } | string;
+    status?: "pending" | "error" | "ready";
+    title?: string;
+    onOpen?: () => void;
+    onRemove?: () => void;
+    className?: string;
+}
+/** An attached image or file as a small thumbnail (the files engine resolves its bytes). */
+export declare function DefaultMediaAttachmentThumbnail({ mediaRef, status, title, onOpen, onRemove, className }: DefaultMediaAttachmentThumbnailProps): import("react").JSX.Element;

package/dist/host/defaults/files-ui.js

@@ -0,0 +1,158 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { X } from "lucide-react";
+import { downloadFile as saveBlob } from "@ai-matrx/kit/download";
+import { FileIcon, MediaThumbnail } from "@ai-matrx/media/react";
+import { downloadFile } from "@ai-matrx/media/files/engine/api/files";
+import { useFile } from "@ai-matrx/media/files/engine/handler/hooks/useFile";
+import { getChatHost, isChatHostConfigured } from "../configure.js";
+const isSyntheticId = (id) => id.startsWith("vfs:");
+function rpc() {
+  if (!isChatHostConfigured()) return null;
+  const db = getChatHost().db;
+  return (name, args) => db.rpc(name, args);
+}
+function useDefaultFileActions(fileId) {
+  const download = useCallback(async () => {
+    if (!fileId || isSyntheticId(fileId)) throw new Error("This file has no stored bytes to download.");
+    const { blob, filename } = await downloadFile(fileId);
+    saveBlob(filename ?? "download", blob, blob.type);
+  }, [fileId]);
+  return { download };
+}
+const DOC_COLUMNS = "id, derivation_kind, total_pages, updated_at, clean_content_completed_at";
+async function lookupDefaultFileDocument(fileId) {
+  if (!isChatHostConfigured()) return { status: "unavailable", reason: "no chat host" };
+  const db = getChatHost().db;
+  try {
+    const { data, error } = await db.schema("docproc").from("processed_documents").select(DOC_COLUMNS).is("deleted_at", null).is("archived_at", null).eq("source_kind", "cld_file").eq("source_id", fileId).order("updated_at", { ascending: false }).limit(1).maybeSingle();
+    if (error) return { status: "unavailable", reason: error.message };
+    if (!data) return { status: "absent" };
+    return {
+      status: "found",
+      doc: {
+        processed_document_id: data.id,
+        derivation_kind: data.derivation_kind,
+        total_pages: data.total_pages,
+        chunk_count: null,
+        has_clean_content: data.clean_content_completed_at != null,
+        updated_at: data.updated_at
+      }
+    };
+  } catch (cause) {
+    return { status: "unavailable", reason: cause instanceof Error ? cause.message : String(cause) };
+  }
+}
+function useDefaultFileDocument(fileId) {
+  const [state, setState] = useState({ status: "idle" });
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    if (!fileId) {
+      setState({ status: "idle" });
+      return void 0;
+    }
+    if (isSyntheticId(fileId)) {
+      setState({ status: "absent" });
+      return void 0;
+    }
+    let live = true;
+    setState({ status: "loading" });
+    void lookupDefaultFileDocument(fileId).then((next) => live && setState(next));
+    return () => {
+      live = false;
+    };
+  }, [fileId, tick]);
+  return { state, refresh: () => setTick((t) => t + 1) };
+}
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function parseDefaultFileResourceFamily(value) {
+  if (!isRecord(value) || value.resource_type !== "file") throw new Error("The file-family RPC returned an invalid resource envelope.");
+  const list = (v) => Array.isArray(v) ? v.filter(isRecord) : [];
+  return {
+    schema_version: typeof value.schema_version === "number" ? value.schema_version : 1,
+    resource_type: "file",
+    requested_file_id: typeof value.requested_file_id === "string" ? value.requested_file_id : "",
+    root_file_id: typeof value.root_file_id === "string" ? value.root_file_id : null,
+    files: list(value.files),
+    processed_documents: list(value.processed_documents),
+    representations: list(value.representations).filter((r) => typeof r.key === "string" && typeof r.label === "string").map((r) => ({
+      key: r.key,
+      label: r.label,
+      category: typeof r.category === "string" ? r.category : "other",
+      count: typeof r.count === "number" ? r.count : 0,
+      promotable: r.promotable === true,
+      fetch_tool: typeof r.fetch_tool === "string" ? r.fetch_tool : "context"
+    })),
+    capabilities: Array.isArray(value.capabilities) ? value.capabilities.filter((c) => typeof c === "string") : [],
+    counts: isRecord(value.counts) ? Object.fromEntries(Object.entries(value.counts).filter((e) => typeof e[1] === "number")) : {}
+  };
+}
+function useDefaultFileResourceFamily(fileId) {
+  const [state, setState] = useState({
+    fileId: null,
+    data: null,
+    error: null
+  });
+  useEffect(() => {
+    if (!fileId) return void 0;
+    let live = true;
+    const call = rpc();
+    if (!call) {
+      setState({ fileId, data: null, error: "No chat host to read the file family from." });
+      return void 0;
+    }
+    void call("get_file_resource_family", { p_file_id: fileId }).then(({ data, error }) => {
+      if (!live) return;
+      if (error) setState({ fileId, data: null, error: error.message });
+      else setState({ fileId, data: parseDefaultFileResourceFamily(data), error: null });
+    }).catch((cause) => live && setState({ fileId, data: null, error: cause instanceof Error ? cause.message : "Unable to load file family" }));
+    return () => {
+      live = false;
+    };
+  }, [fileId]);
+  if (!fileId) return { data: null, loading: false, error: null };
+  if (state.fileId !== fileId) return { data: null, loading: true, error: null };
+  return { data: state.data, loading: false, error: state.error };
+}
+const formatBytes = (n) => n == null ? null : n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(0)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`;
+function DefaultFileResourceChip({ fileId, fileHint, nameOverride, badge, onOpen, onRemove, className }) {
+  const { file, status } = useFile(fileId && !isSyntheticId(fileId) ? { kind: "file_id", fileId } : null);
+  const name = nameOverride || file?.meta.fileName || fileHint?.fileName || (status === "resolving" ? "Loading\u2026" : "File");
+  const mime = file?.meta.mime ?? fileHint?.mimeType ?? null;
+  const size = formatBytes(file?.meta.sizeBytes);
+  const body = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(FileIcon, { fileName: name, mimeType: mime, size: 14 }),
+    /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: name }),
+    badge || size ? /* @__PURE__ */ jsx("span", { className: "shrink-0 text-muted-foreground", children: badge ?? size }) : null
+  ] });
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      className: `inline-flex max-w-64 items-center gap-1.5 rounded-md border border-border bg-card px-2 py-1 text-xs ${className ?? ""}`,
+      "data-chat-default": "file-chip",
+      title: name,
+      children: [
+        onOpen ? /* @__PURE__ */ jsx("button", { type: "button", className: "inline-flex min-w-0 items-center gap-1.5", onClick: onOpen, children: body }) : body,
+        onRemove ? /* @__PURE__ */ jsx("button", { type: "button", "aria-label": `Remove ${name}`, className: "shrink-0 text-muted-foreground hover:text-foreground", onClick: onRemove, children: /* @__PURE__ */ jsx(X, { className: "h-3 w-3" }) }) : null
+      ]
+    }
+  );
+}
+function DefaultMediaAttachmentThumbnail({ mediaRef, status = "ready", title, onOpen, onRemove, className }) {
+  const ref = typeof mediaRef === "string" ? { file_id: mediaRef } : mediaRef;
+  const name = title || ref.file_name || "Attachment";
+  return /* @__PURE__ */ jsxs("span", { className: `relative inline-flex h-12 w-12 overflow-hidden rounded-md border border-border ${status === "pending" ? "opacity-60" : ""} ${className ?? ""}`, "data-chat-default": "media-thumbnail", title: name, children: [
+    /* @__PURE__ */ jsx("button", { type: "button", className: "h-full w-full", onClick: onOpen, disabled: !onOpen, "aria-label": `Open ${name}`, children: /* @__PURE__ */ jsx(MediaThumbnail, { mediaRef, fileName: name, mimeType: ref.mime_type ?? null, iconSize: 20, className: "h-full w-full" }) }),
+    onRemove ? /* @__PURE__ */ jsx("button", { type: "button", "aria-label": `Remove ${name}`, className: "absolute right-0.5 top-0.5 rounded bg-background/80 p-0.5", onClick: onRemove, children: /* @__PURE__ */ jsx(X, { className: "h-3 w-3" }) }) : null
+  ] });
+}
+export {
+  DefaultFileResourceChip,
+  DefaultMediaAttachmentThumbnail,
+  lookupDefaultFileDocument,
+  parseDefaultFileResourceFamily,
+  useDefaultFileActions,
+  useDefaultFileDocument,
+  useDefaultFileResourceFamily
+};

package/dist/host/defaults/gates.d.ts

@@ -0,0 +1,27 @@
+import { type ResourceAccess } from "../../ui/access-core.js";
+import { type PermissionLevel } from "../../ui/permission-levels.js";
+export declare function useDefaultAccess(resourceType: string | undefined, resourceId: string | undefined): ResourceAccess & {
+    loading: boolean;
+    refresh: () => Promise<void>;
+};
+export type DefaultOrganizationState = "resolving" | "required" | "ready" | "unavailable" | "signed_out";
+export declare function useDefaultOrganizationRequired(): {
+    organizationId: string | null;
+    canLoad: boolean;
+    organizationRequired: boolean;
+    resolving: boolean;
+    organizationState: "ready" | "required" | "signed_out" | "unavailable";
+    unavailableReason: string | null;
+    retry: () => void;
+};
+export interface DefaultOrgAvailabilityOptions {
+    resourceType: string;
+    resourceId: string;
+    organizationId: string;
+    permissionLevel?: PermissionLevel;
+}
+export declare function defaultEnsureOrgAvailability(options: DefaultOrgAvailabilityOptions): Promise<{
+    success: boolean;
+    error?: string;
+    message?: string;
+}>;