@ai-matrx/chat 0.7.13 → 0.7.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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)

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/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.13",
+  "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",
@@ -4682,24 +4682,24 @@
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
     "@ai-matrx/alchemy": "latest",
-    "@ai-matrx/associations": "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/agents": "latest",
+    "@ai-matrx/associations": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/diff": "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/data": "latest",
+    "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
-    "@ai-matrx/print": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/records-ui": "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": "b49e03c743ac750bc1615fd9635bdc5a4796a241"
+  "gitHead": "0e5372354ec84ed85b1779e1d99b6922a20f1798"
 }