@ai-matrx/chat 0.7.12 → 0.7.14

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ai-matrx/chat
 
+## 0.7.14
+### Unreleased
+### An answer never paints header-first (spend register item 32, cold-load CLS at 1280/1440/1920)
+
+- **`AgentAssistantMessage`** renders nothing until the markdown engine chunk has settled (`useMarkdownEngineSettled`, new internal
+  `ui/markdown-stream/markdown-engine`), so every message of a conversation appears in the same commit. A chunk that fails to load is a
+  `console.error` and the message renders anyway. 0.7.12 preloaded the chunk but a message could still render before it landed
+  (a 82 px header-only block growing to 385 px: CLS up to 0.32 on a cold load).
+- `MarkdownStream` keeps the loaded engine and renders it synchronously on a new instance's first render.
+- Test: `ui/markdown-stream/__tests__/markdown-engine-first-paint.test.tsx`.
+- **Consumer action:** none.
+
+## 0.7.13
+### Unreleased
+### a refused answer fails the run's own row (lane F13)
+
+- **`recordRunOutputRefused(runRowId, reason, requestId?)`** writes against the `chat.user_request` row id the server announced
+  (`record_reserved`), read with the new **`runRowIdOf(state, requestId)`**. 0.7.10 wrote against the client's Redux key
+  (`req_<uuid>`), which no row has: every refused run on Make stayed `completed`, error null (live 2026-10-09). A refusal with
+  no row id is a `console.error`, never a silent no-op.
+- Tests: `a-refused-answer-fails-the-servers-run-row.test.ts`.
+- **Consumer action:** none (`useHeadlessAgentJson` is the only caller).
+
 ## 0.7.12
 ### Unreleased
 ### The variables a run used (Agent Factory R59)

package/dist/agents/components/messages-display/assistant/AgentAssistantMessage.d.ts

@@ -41,4 +41,9 @@ export interface AgentAssistantMessageProps {
      */
     isTurnAnswer?: boolean;
 }
-export declare function AgentAssistantMessage({ conversationId, requestId, messageId, isStreamActive, recordMessageIds, streamSlotStart, streamSlotEnd, surfaceKey, hideActionBar, canRetry, isTurnAnswer, }: AgentAssistantMessageProps): import("react").JSX.Element;
+/**
+ * First-paint rule (item 32): an answer never paints as a header-only block that grows when the
+ * markdown engine lands, so a message renders nothing until the engine has settled. Every message of
+ * a conversation waits on the same flag, so they appear in the same commit.
+ */
+export declare function AgentAssistantMessage(props: AgentAssistantMessageProps): import("react").JSX.Element | null;

package/dist/agents/components/messages-display/assistant/AgentAssistantMessage.js

@@ -6,7 +6,8 @@ import {
   useState,
   useEffect
 } from "react";
-import MarkdownStream, { preloadMarkdownStream } from "../../../../ui/markdown-stream/MarkdownStream.js";
+import MarkdownStream from "../../../../ui/markdown-stream/MarkdownStream.js";
+import { preloadMarkdownStream, useMarkdownEngineSettled } from "../../../../ui/markdown-stream/markdown-engine.js";
 import "../rich-document/chat-message-source.js";
 import { RecordAnnotations, annotationRecordOf } from "@ai-matrx/rich-content/host/app-bindings";
 import { useAppDispatch, useAppSelector } from "../../../../store/hooks.js";
@@ -106,7 +107,12 @@ function providerControlErrorMessage(err) {
   if (err instanceof Error) return err.message;
   return "Provider control failed";
 }
-function AgentAssistantMessage({
+function AgentAssistantMessage(props) {
+  const engineSettled = useMarkdownEngineSettled();
+  if (!engineSettled) return null;
+  return /* @__PURE__ */ jsx(AgentAssistantMessageBody, { ...props });
+}
+function AgentAssistantMessageBody({
   conversationId,
   requestId,
   messageId,

package/dist/agents/hooks/useFloatingAgentRun.d.ts

@@ -1,4 +1,4 @@
-import { type LiveAgentRunOptions } from "./useLiveAgentRun.js";
+import { type LiveAgentReattachOptions, type LiveAgentRunOptions } from "./useLiveAgentRun.js";
 /**
  * The words a failed launch shows in its window: the server's own reason when
  * the run carried one (a Mandate with no Holder names the rungs it checked),
@@ -83,6 +83,16 @@ export interface UseFloatingAgentRun {
     run: <T = unknown>(opts: LiveAgentRunOptions<T> & {
         label?: string;
     }) => Promise<T>;
+    /**
+     * Pick an EXISTING run back up — a reload or a paused tab must never start a
+     * second one. The conversation id is what `onConversationCreated` handed out
+     * at launch. Resolves with the finished result when the run is done, or
+     * follows it to the end when it is still going, in the same window. No run is
+     * started.
+     */
+    reattach: <T = unknown>(conversationId: string, opts: LiveAgentReattachOptions<T> & {
+        label?: string;
+    }) => Promise<T>;
     isRunning: boolean;
     error: string | null;
     conversationId: string | null;

package/dist/agents/hooks/useFloatingAgentRun.js

@@ -123,8 +123,20 @@ function useFloatingAgentRun(options = {}) {
       throw error;
     }
   }
+  async function reattach(existingConversationId, opts) {
+    const { label, ...reattachOptions } = opts;
+    const bound = floating.start(label ?? options.label ?? "AI is working");
+    bound.bind(existingConversationId);
+    try {
+      return await live.reattach(existingConversationId, reattachOptions);
+    } catch (error) {
+      bound.fail(floatingFailureReason(error));
+      throw error;
+    }
+  }
   return {
     run,
+    reattach,
     isRunning: live.isRunning,
     error: live.error,
     conversationId: live.conversationId,

package/dist/agents/hooks/useHeadlessAgentJson.d.ts

@@ -1,3 +1,4 @@
+import { type ReattachHeadlessAgentJsonOptions } from "../redux/execution-system/thunks/reattach-headless-agent-json.js";
 import { type HeadlessAgentJsonOptions, type HeadlessAgentJsonResult } from "../redux/execution-system/thunks/run-headless-agent-json.js";
 /**
  * What `run()` throws. It carries the run's TECHNICAL reason (when the run
@@ -27,8 +28,21 @@ export interface HeadlessAgentJsonRunOptions<T> extends HeadlessAgentJsonOptions
      */
     coerce?: (value: unknown, result: HeadlessAgentJsonResult) => T;
 }
+/**
+ * Reopen a run that ALREADY exists (running or finished) — never starts one.
+ * `conversationId` is what `onConversationCreated` handed out at launch.
+ */
+export interface HeadlessAgentJsonReattachOptions<T> extends Omit<ReattachHeadlessAgentJsonOptions, "conversationId"> {
+    coerce?: (value: unknown, result: HeadlessAgentJsonResult) => T;
+}
 export interface UseHeadlessAgentJson {
     run: <T = unknown>(opts: HeadlessAgentJsonRunOptions<T>) => Promise<T>;
+    /**
+     * Pick an existing run back up: its finished result when it is done, or
+     * follow it to the end when it is still going. No new run is ever started.
+     * Throws exactly like `run`.
+     */
+    reattach: <T = unknown>(conversationId: string, opts: HeadlessAgentJsonReattachOptions<T>) => Promise<T>;
     isRunning: boolean;
     error: string | null;
     /** Conversation id of the in-flight run — set BEFORE the stream starts. */

package/dist/agents/hooks/useHeadlessAgentJson.js

@@ -3,7 +3,10 @@ import { useCallback, useState } from "react";
 import { useAppDispatch, useAppSelector, useAppStore } from "../../store/hooks.js";
 import { selectConversationRequestIds } from "../redux/execution-system/active-requests/active-requests.selectors.js";
 import { useRetainRequestForViewer } from "../redux/execution-system/active-requests/useRetainRequestForViewer.js";
-import { recordRunOutputRefused } from "../redux/execution-system/thunks/record-run-output-refused.js";
+import { recordRunOutputRefused, runRowIdOf } from "../redux/execution-system/thunks/record-run-output-refused.js";
+import {
+  reattachHeadlessAgentJson
+} from "../redux/execution-system/thunks/reattach-headless-agent-json.js";
 import {
   runHeadlessAgentJson
 } from "../redux/execution-system/thunks/run-headless-agent-json.js";
@@ -31,33 +34,29 @@ function useHeadlessAgentJson() {
     return ids.length > 0 ? ids[ids.length - 1] : null;
   });
   useRetainRequestForViewer(activeRequestId, "useHeadlessAgentJson");
-  async function run(opts) {
+  async function settle(result, coerce) {
+    if (!result.success) {
+      throw new HeadlessAgentRunError(result.error ?? "The agent run failed", {
+        ...result.errorDetail ? { detail: result.errorDetail } : {},
+        ...result.requestId ? { requestId: result.requestId } : {},
+        ...result.conversationId ? { conversationId: result.conversationId } : {}
+      });
+    }
+    if (!coerce) return result.data;
+    try {
+      return coerce(result.data, result);
+    } catch (refused) {
+      const why = refused instanceof Error ? refused.message : String(refused);
+      const rowId = result.requestId ? runRowIdOf(store.getState(), result.requestId) : null;
+      void recordRunOutputRefused(rowId, why, result.requestId);
+      throw refused;
+    }
+  }
+  async function guarded(work) {
     setIsRunning(true);
     setError(null);
-    setConversationId(null);
     try {
-      const result = await runHeadlessAgentJson(dispatch, store.getState, {
-        ...opts,
-        onConversationCreated: (cid) => {
-          setConversationId(cid);
-          opts.onConversationCreated?.(cid);
-        }
-      });
-      if (!result.success) {
-        throw new HeadlessAgentRunError(result.error ?? "The agent run failed", {
-          ...result.errorDetail ? { detail: result.errorDetail } : {},
-          ...result.requestId ? { requestId: result.requestId } : {},
-          ...result.conversationId ? { conversationId: result.conversationId } : {}
-        });
-      }
-      if (!opts.coerce) return result.data;
-      try {
-        return opts.coerce(result.data, result);
-      } catch (refused) {
-        const why = refused instanceof Error ? refused.message : String(refused);
-        if (result.requestId) void recordRunOutputRefused(result.requestId, why);
-        throw refused;
-      }
+      return await work();
     } catch (e) {
       const message = e instanceof Error ? e.message : "Failed to run the agent";
       setError(message);
@@ -66,11 +65,34 @@ function useHeadlessAgentJson() {
       setIsRunning(false);
     }
   }
+  async function run(opts) {
+    setConversationId(null);
+    return guarded(async () => {
+      const result = await runHeadlessAgentJson(dispatch, store.getState, {
+        ...opts,
+        onConversationCreated: (cid) => {
+          setConversationId(cid);
+          opts.onConversationCreated?.(cid);
+        }
+      });
+      return settle(result, opts.coerce);
+    });
+  }
+  async function reattach(existingConversationId, opts) {
+    setConversationId(existingConversationId);
+    return guarded(async () => {
+      const result = await reattachHeadlessAgentJson(dispatch, store.getState, {
+        ...opts,
+        conversationId: existingConversationId
+      });
+      return settle(result, opts.coerce);
+    });
+  }
   const reset = useCallback(() => {
     setError(null);
     setConversationId(null);
   }, []);
-  return { run, isRunning, error, conversationId, activeRequestId, reset };
+  return { run, reattach, isRunning, error, conversationId, activeRequestId, reset };
 }
 export {
   HeadlessAgentRunError,

package/dist/agents/hooks/useLiveAgentRun.d.ts

@@ -1,6 +1,13 @@
-import { type HeadlessAgentJsonRunOptions } from "./useHeadlessAgentJson.js";
+import { type HeadlessAgentJsonReattachOptions, type HeadlessAgentJsonRunOptions } from "./useHeadlessAgentJson.js";
 export type LiveAgentRunOptions<T> = Omit<HeadlessAgentJsonRunOptions<T>, "displayMode" | "keepInstance">;
+export type LiveAgentReattachOptions<T> = Omit<HeadlessAgentJsonReattachOptions<T>, "keepInstance">;
 export interface UseLiveAgentRun {
+    /**
+     * Pick an EXISTING run back up (a reload, a paused tab) — its finished
+     * result, or follow it to the end. Never starts a run; the live handle
+     * (`conversationId`) is set before anything is read.
+     */
+    reattach: <T = unknown>(conversationId: string, opts: LiveAgentReattachOptions<T>) => Promise<T>;
     /** Run the agent; the live handle (`conversationId`) is set before the stream. */
     run: <T = unknown>(opts: LiveAgentRunOptions<T>) => Promise<T>;
     isRunning: boolean;

package/dist/agents/hooks/useLiveAgentRun.js

@@ -38,6 +38,20 @@ function useLiveAgentRun() {
       }
     }
   }
+  async function reattach(existingConversationId, opts) {
+    if (ownedConversationRef.current !== existingConversationId) releaseOwned();
+    setDismissed(false);
+    dismissedRef.current = false;
+    ownedConversationRef.current = existingConversationId;
+    try {
+      return await headless.reattach(existingConversationId, {
+        ...opts,
+        keepInstance: true
+      });
+    } finally {
+      if (dismissedRef.current) releaseOwned();
+    }
+  }
   const dismiss = () => {
     setDismissed(true);
     dismissedRef.current = true;
@@ -58,6 +72,7 @@ function useLiveAgentRun() {
   );
   return {
     run,
+    reattach,
     dismiss,
     isRunning: headless.isRunning,
     error: headless.error,

package/dist/agents/redux/execution-system/thunks/reattach-headless-agent-json.d.ts

@@ -0,0 +1,29 @@
+/**
+ * reattachHeadlessAgentJson — the sibling of `runHeadlessAgentJson` for a run
+ * that is ALREADY running or finished: a reload or a paused tab must never
+ * start a second paid run, it picks the first one back up.
+ *
+ * It owns no run path of its own. Every step is an existing primitive:
+ *
+ *  1. `loadConversation`             — the saved conversation (a finished run's
+ *                                      last message is read from it)
+ *  2. `surfaceColdPendingCalls`      — a delegated tool prompt nobody answered
+ *  3. `reconnectServerOperation`     — `/runtime/operations/by-link/conversation`:
+ *                                      if the server is still working, rejoin
+ *                                      and follow it to terminal through the
+ *                                      canonical stream pipeline (so the same
+ *                                      LiveRunWindow bound to this conversation
+ *                                      streams it), then reload the saved turn
+ *  4. `adoptHeadlessAgentJson`       — THE result-resolution rule, over the
+ *                                      request that is now in Redux
+ *
+ * A stream this very page still owns (`hasAbortController`) is never re-read:
+ * a reload would clobber it, so steps 1–3 are skipped and the live request is
+ * simply waited on. Never throws — resolves a structured result.
+ */
+import type { ChatDispatch, ChatRootState } from "../../../../store/root-state.js";
+import { type AdoptedAgentJsonOptions, type HeadlessAgentJsonResult } from "./run-headless-agent-json.js";
+export interface ReattachHeadlessAgentJsonOptions extends Omit<AdoptedAgentJsonOptions, "requestId" | "conversationId"> {
+    conversationId: string;
+}
+export declare function reattachHeadlessAgentJson(dispatch: ChatDispatch, getState: () => ChatRootState, opts: ReattachHeadlessAgentJsonOptions): Promise<HeadlessAgentJsonResult>;

package/dist/agents/redux/execution-system/thunks/reattach-headless-agent-json.js

@@ -0,0 +1,89 @@
+import { extractErrorMessage } from "@ai-matrx/data/net";
+import { extractFirstJson } from "@ai-matrx/content-ir/json-extract";
+import { captureError } from "../../../../host/diagnostics.js";
+import { reconnectServerOperation } from "../../../runtime-reconnect/reconnect-server-operation.thunk.js";
+import { selectRequestStatus } from "../active-requests/active-requests.selectors.js";
+import { selectLatestAnswerText as selectCommittedAnswerText } from "../messages/messages.selectors.js";
+import { selectLatestRequestId } from "../selectors/aggregate.selectors.js";
+import { hasAbortController } from "./abort-registry.js";
+import { loadConversation } from "./load-conversation.thunk.js";
+import { surfaceColdPendingCalls } from "./surface-cold-pending-calls.thunk.js";
+import {
+  adoptHeadlessAgentJson
+} from "./run-headless-agent-json.js";
+const REATTACH_SETTLE_MS = 300;
+async function reattachHeadlessAgentJson(dispatch, getState, opts) {
+  const { conversationId } = opts;
+  const failure = (error, errorDetail) => ({
+    success: false,
+    data: null,
+    fullResponse: selectCommittedAnswerText(conversationId)(getState()),
+    error,
+    errorDetail,
+    conversationId
+  });
+  if (!hasAbortController(conversationId)) {
+    try {
+      await dispatch(loadConversation({ conversationId })).unwrap();
+    } catch (err) {
+      const detail = extractErrorMessage(err);
+      captureError({
+        source: "agent-json-result",
+        message: `Reattach could not read conversation ${conversationId}: ${detail}`,
+        conversationId,
+        raw: { surfaceKey: opts.surfaceKey, detail }
+      });
+      return failure("That run could not be opened again.", detail);
+    }
+    void dispatch(surfaceColdPendingCalls(conversationId));
+    try {
+      await dispatch(
+        reconnectServerOperation({ conversationId, source: "cold-load" })
+      ).unwrap();
+    } catch (err) {
+      const detail = extractErrorMessage(err);
+      captureError({
+        source: "agent-json-result",
+        message: `Reattach could not follow conversation ${conversationId}: ${detail}`,
+        conversationId,
+        raw: { surfaceKey: opts.surfaceKey, detail }
+      });
+      return failure("That run could not be followed to its end.", detail);
+    }
+  }
+  const requestId = selectLatestRequestId(conversationId)(getState());
+  const status = requestId ? selectRequestStatus(requestId)(getState()) : void 0;
+  const fullResponse = selectCommittedAnswerText(conversationId)(getState());
+  const finished = status === void 0 || status === "complete";
+  if (fullResponse.trim() && finished && !hasAbortController(conversationId)) {
+    const expect = opts.expect ?? "json";
+    const data = expect === "text" ? fullResponse.trim() : extractFirstJson(fullResponse, { allowFuzzy: true })?.value ?? null;
+    if (data != null) {
+      const result = {
+        success: true,
+        data,
+        fullResponse,
+        conversationId,
+        ...requestId ? { requestId } : {}
+      };
+      await opts.onResult?.(result);
+      return result;
+    }
+  }
+  if (requestId) {
+    return adoptHeadlessAgentJson(dispatch, getState, {
+      ...opts,
+      requestId,
+      settleMs: opts.settleMs ?? REATTACH_SETTLE_MS,
+      // The window keeps showing the finished run; the hook owns teardown.
+      keepInstance: opts.keepInstance ?? true
+    });
+  }
+  return failure(
+    "That run has no saved result to open.",
+    "reattach: the conversation holds no request and no readable answer"
+  );
+}
+export {
+  reattachHeadlessAgentJson
+};

package/dist/agents/redux/execution-system/thunks/record-run-output-refused.d.ts

@@ -10,5 +10,14 @@
  *
  * Never silent: a write that does not land is a `console.error` naming the run.
  */
+import type { ChatRootState } from "../../../../store/root-state.js";
 export declare const OUTPUT_REFUSED_METADATA_KEY = "output_refused";
-export declare function recordRunOutputRefused(requestId: string, reason: string): Promise<boolean>;
+/**
+ * The run's own `chat.user_request` row id, as the server announced it (`record_reserved` for the
+ * `user_request` table, or a message reservation's `parent_refs.user_request_id`). The client's
+ * `requestId` (`req_<uuid>`) is a Redux key the database has never seen — writing against it matched
+ * no row, so every refusal before 0.7.12 left the run `completed` (Make's describe box, 2026-10-09).
+ * Null when the stream announced no row.
+ */
+export declare function runRowIdOf(state: ChatRootState, requestId: string): string | null;
+export declare function recordRunOutputRefused(runRowId: string | null, reason: string, requestId?: string): Promise<boolean>;

package/dist/agents/redux/execution-system/thunks/record-run-output-refused.js

@@ -2,17 +2,34 @@ import { mergeJsonColumn } from "@ai-matrx/data/db";
 import { supabase } from "../../../../host/db.js";
 import { hasBrowserSession } from "../../../../host/identity.js";
 const OUTPUT_REFUSED_METADATA_KEY = "output_refused";
-async function recordRunOutputRefused(requestId, reason) {
-  if (!requestId || !await hasBrowserSession()) return false;
+const ROW_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function runRowIdOf(state, requestId) {
+  const reservations = state.activeRequests.byRequestId[requestId]?.reservations;
+  if (!reservations) return null;
+  const all = Object.values(reservations);
+  const own = all.find((r) => r.table === "user_request" && ROW_ID.test(r.recordId));
+  if (own) return own.recordId;
+  const parent = all.map((r) => r.parentRefs?.user_request_id).find((id) => typeof id === "string" && ROW_ID.test(id));
+  return parent ?? null;
+}
+async function recordRunOutputRefused(runRowId, reason, requestId) {
+  if (!runRowId || !ROW_ID.test(runRowId)) {
+    console.error(
+      `[run-output-refused] Run ${requestId ?? "?"} announced no chat.user_request row id (got ${runRowId ?? "none"}); the refusal cannot be recorded and the run still reads as completed. Reason: ${reason}`
+    );
+    return false;
+  }
+  const requestRow = runRowId;
+  if (!await hasBrowserSession()) return false;
   const result = await mergeJsonColumn({
-    fetchCurrent: () => supabase.schema("chat").from("user_request").select("id, version, metadata").eq("id", requestId).maybeSingle(),
+    fetchCurrent: () => supabase.schema("chat").from("user_request").select("id, version, metadata").eq("id", requestRow).maybeSingle(),
     readColumn: (row) => row.metadata,
     merge: (current) => ({ ...current, [OUTPUT_REFUSED_METADATA_KEY]: { reason, at: (/* @__PURE__ */ new Date()).toISOString() } }),
-    applyUpdate: ({ value, expectedVersion, nextVersion }) => supabase.schema("chat").from("user_request").update({ metadata: value, version: nextVersion, status: "failed", error: reason.slice(0, 500) }).eq("id", requestId).eq("version", expectedVersion).select("id, version, metadata").maybeSingle()
+    applyUpdate: ({ value, expectedVersion, nextVersion }) => supabase.schema("chat").from("user_request").update({ metadata: value, version: nextVersion, status: "failed", error: reason.slice(0, 500) }).eq("id", requestRow).eq("version", expectedVersion).select("id, version, metadata").maybeSingle()
   });
   if (result.status !== "saved") {
     console.error(
-      `[run-output-refused] Could not record the refusal on run ${requestId}: ` + (result.status === "error" ? String(result.error) : `write ${result.status}`) + `. The run still reads as completed. Reason: ${reason}`
+      `[run-output-refused] Could not record the refusal on run ${requestRow}: ` + (result.status === "error" ? String(result.error) : `write ${result.status}`) + `. The run still reads as completed. Reason: ${reason}`
     );
     return false;
   }
@@ -20,5 +37,6 @@ async function recordRunOutputRefused(requestId, reason) {
 }
 export {
   OUTPUT_REFUSED_METADATA_KEY,
-  recordRunOutputRefused
+  recordRunOutputRefused,
+  runRowIdOf
 };

package/dist/ui/markdown-stream/MarkdownStream.d.ts

@@ -1,4 +1,5 @@
 import type { AnswerEditRemarkMeta } from "../../agents/redux/execution-system/instance-resources/remarks.js";
+import { preloadMarkdownStream } from "./markdown-engine.js";
 import { TypedStreamEvent } from "@ai-matrx/rich-content/display/chat-markdown/types";
 import type { ServerProcessedBlock } from "./EnhancedChatMarkdown.js";
 /**
@@ -83,7 +84,7 @@ export interface MarkdownStreamProps {
      */
     imagePolicy?: "self" | "other" | "ai" | "inherit";
 }
-export declare function preloadMarkdownStream(): Promise<void>;
 declare function MarkdownStream(props: MarkdownStreamProps): import("react").FunctionComponentElement<import("react").SuspenseProps> | import("react").ReactElement<MarkdownStreamProps, string | import("react").JSXElementConstructor<any>> | null;
+export { preloadMarkdownStream };
 export { MarkdownStream };
 export default MarkdownStream;

package/dist/ui/markdown-stream/MarkdownStream.js

@@ -1,27 +1,12 @@
 "use client";
-import { createElement, lazy, Suspense, useSyncExternalStore } from "react";
+import { createElement, lazy, Suspense } from "react";
+import { loadedMarkdownImpl, preloadMarkdownStream, useIsMarkdownClient } from "./markdown-engine.js";
 const MarkdownStreamImpl = lazy(() => import("./MarkdownStreamImpl.js"));
-let loadedImpl = null;
-let loading = null;
-const readyListeners = /* @__PURE__ */ new Set();
-function preloadMarkdownStream() {
-  if (typeof window === "undefined") return Promise.resolve();
-  loading ??= import("./MarkdownStreamImpl.js").then((m) => {
-    loadedImpl = m.default;
-    for (const notify of readyListeners) notify();
-  });
-  return loading;
-}
-const subscribeReady = (notify) => {
-  readyListeners.add(notify);
-  return () => readyListeners.delete(notify);
-};
-const clientReady = () => true;
-const serverNotReady = () => false;
 function MarkdownStream(props) {
-  const client = useSyncExternalStore(subscribeReady, clientReady, serverNotReady);
+  const client = useIsMarkdownClient();
   if (!client) return null;
-  if (loadedImpl) return createElement(loadedImpl, props);
+  const Loaded = loadedMarkdownImpl();
+  if (Loaded) return createElement(Loaded, props);
   void preloadMarkdownStream();
   return createElement(Suspense, { fallback: null }, createElement(MarkdownStreamImpl, props));
 }

package/dist/ui/markdown-stream/markdown-engine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The markdown engine's load state (spend register item 32 — first-paint rule).
+ *
+ * A persisted answer must paint WITH its markdown, never as an empty block that grows once the engine
+ * chunk lands (a measured CLS of 0.06-0.32 on the run page). So:
+ *  - `preloadMarkdownStream()` starts the chunk when a conversation surface's module evaluates;
+ *  - the resolved component is kept here and rendered synchronously by `MarkdownStream`;
+ *  - `useMarkdownEngineSettled()` lets an assistant message render NOTHING until the engine has loaded
+ *    (or failed — a failure is logged and the message renders, never hangs), so every message of a
+ *    conversation appears in the same commit instead of header-first.
+ * Client-only: the server snapshot is "not ready", so a server render never pulls the engine in.
+ */
+import { type ComponentType } from "react";
+export declare function preloadMarkdownStream(): Promise<void>;
+export declare const loadedMarkdownImpl: () => ComponentType<any> | null;
+/** False on the server and during hydration; true on the client. */
+export declare function useIsMarkdownClient(): boolean;
+/** True once the engine chunk has loaded (or failed). False on the server and until then. */
+export declare function useMarkdownEngineSettled(): boolean;

package/dist/ui/markdown-stream/markdown-engine.js

@@ -0,0 +1,44 @@
+"use client";
+import { useSyncExternalStore } from "react";
+let loadedImpl = null;
+let settled = false;
+let loading = null;
+const listeners = /* @__PURE__ */ new Set();
+const notify = () => {
+  for (const listener of listeners) listener();
+};
+function preloadMarkdownStream() {
+  if (typeof window === "undefined") return Promise.resolve();
+  loading ??= import("./MarkdownStreamImpl.js").then(
+    (m) => {
+      loadedImpl = m.default;
+      settled = true;
+      notify();
+    },
+    (error) => {
+      console.error("[chat] the markdown engine chunk failed to load; messages render without waiting for it", error);
+      settled = true;
+      notify();
+    }
+  );
+  return loading;
+}
+const loadedMarkdownImpl = () => loadedImpl;
+const subscribe = (onChange) => {
+  listeners.add(onChange);
+  return () => {
+    listeners.delete(onChange);
+  };
+};
+function useIsMarkdownClient() {
+  return useSyncExternalStore(subscribe, () => true, () => false);
+}
+function useMarkdownEngineSettled() {
+  return useSyncExternalStore(subscribe, () => settled, () => false);
+}
+export {
+  loadedMarkdownImpl,
+  preloadMarkdownStream,
+  useIsMarkdownClient,
+  useMarkdownEngineSettled
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "description": "THE one AI Matrx person-to-agent chat system: the full chat (running agents, conversations, tool calls, streaming, context, surfaces, voice) as explicit per-module subpaths @ai-matrx/chat/<domain>/<module> (no wildcards: scripts/public-modules.json) over a host contract (/host, /host/react) whose only required value is a db. One chat, one renderer: the old kernel entries (., /external-store, /matrx, /react, /tools, styles.css, tokens.css) are retired.",
   "type": "module",
   "license": "MIT",
@@ -4681,25 +4681,25 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@ai-matrx/associations": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/browser-audio": "latest",
-    "@ai-matrx/canvas": "latest",
     "@ai-matrx/agents": "latest",
+    "@ai-matrx/content-ir": "latest",
     "@ai-matrx/content-ir-react": "latest",
-    "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/associations": "latest",
     "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest",
-    "@ai-matrx/media": "latest",
     "@ai-matrx/print": "latest",
     "@ai-matrx/realtime": "latest",
     "@ai-matrx/records": "latest",
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/content-ir": "latest",
-    "@ai-matrx/diff": "latest"
+    "@ai-matrx/diff": "latest",
+    "@ai-matrx/canvas": "latest",
+    "@ai-matrx/media": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
@@ -4818,5 +4818,5 @@
     "check:side-effects": "node ../scripts/check-side-effects-listed.mjs . && node ../scripts/check-side-effects-listed.mjs --self-test",
     "check:public-surface": "node ./scripts/sync-public-surface.mjs --check && node ./scripts/sync-public-surface.mjs --self-test"
   },
-  "gitHead": "24ad46786a0c433cb3773b270bf74c9eb32898bc"
+  "gitHead": "0e5372354ec84ed85b1779e1d99b6922a20f1798"
 }