@agent-native/core 0.84.53 → 0.84.55

package/corpus/core/src/client/blocks/library/diagram.tsx

@@ -89,6 +89,7 @@ function HtmlDiagram({
   const ref = useRef<HTMLDivElement>(null);
   const isDark = useIsDark();
   const style = useWireframeStyle();
+  const showFrame = resolveVisualFrame(data.frame, ctx);
   const scopeId = useId().replace(/[^a-zA-Z0-9_-]/g, "");
   // Sanitize author HTML/CSS at the render point (defense-in-depth against
   // stored XSS). Self-contained in core via the shared block sanitizer (DOM-based
@@ -114,6 +115,7 @@ function HtmlDiagram({
         dir={ctx.textDirection}
         data-theme={isDark ? "dark" : "light"}
         data-style={style}
+        data-frame={showFrame ? "show" : "hide"}
         data-text-direction={ctx.textDirection}
         data-plan-diagram-scope={scopeId}
       >
@@ -126,7 +128,7 @@ function HtmlDiagram({
       <RoughOverlay
         scopeRef={ref}
         enabled={style === "sketchy"}
-        drawFrame={false}
+        drawFrame={showFrame}
         selector={DIAGRAM_ROUGH_SELECTOR}
       />
       {data.caption && !compact && (
@@ -138,6 +140,15 @@ function HtmlDiagram({
   );
 }
 
+function resolveVisualFrame(
+  frame: DiagramData["frame"],
+  ctx: BlockRenderContext,
+): boolean {
+  const resolved =
+    frame && frame !== "auto" ? frame : (ctx.visualFrame ?? "show");
+  return resolved !== "hide";
+}
+
 /* -------------------------------------------------------------------------- */
 /* Legacy node-graph paths                                                     */
 /* -------------------------------------------------------------------------- */
@@ -186,11 +197,13 @@ function PositionedDiagram({
   compact,
   markerId,
   direction,
+  showFrame,
 }: {
   data: DiagramData;
   compact?: boolean;
   markerId: string;
   direction?: BlockRenderContext["textDirection"];
+  showFrame: boolean;
 }) {
   const nodes = (data.nodes ?? []).map((node) => ({
     ...node,
@@ -228,7 +241,10 @@ function PositionedDiagram({
 
   return (
     <div
-      className="plan-sketch rounded-[16px] border border-border bg-muted p-5"
+      className={cn(
+        "plan-sketch",
+        showFrame ? "rounded-[16px] border border-border bg-muted p-5" : "p-0",
+      )}
       dir={direction}
       data-text-direction={direction}
     >
@@ -426,10 +442,12 @@ function SequenceDiagram({
   data,
   compact,
   direction,
+  showFrame,
 }: {
   data: DiagramData;
   compact?: boolean;
   direction?: BlockRenderContext["textDirection"];
+  showFrame: boolean;
 }) {
   const edges = data.edges ?? [];
   const nodes = orderDiagramNodes(data.nodes ?? [], edges);
@@ -443,7 +461,10 @@ function SequenceDiagram({
   const visualNodes = direction === "rtl" ? [...nodes].reverse() : nodes;
   return (
     <div
-      className="plan-sketch rounded-[16px] border border-border bg-muted p-5"
+      className={cn(
+        "plan-sketch",
+        showFrame ? "rounded-[16px] border border-border bg-muted p-5" : "p-0",
+      )}
       dir={direction}
       data-text-direction={direction}
     >
@@ -524,6 +545,7 @@ function DiagramBody({
   compact?: boolean;
 }) {
   const markerId = useId().replace(/:/g, "");
+  const showFrame = resolveVisualFrame(data.frame, ctx);
   if (data.html?.trim()) {
     return <HtmlDiagram data={data} ctx={ctx} compact={compact} />;
   }
@@ -534,6 +556,7 @@ function DiagramBody({
         compact={compact}
         markerId={markerId}
         direction={ctx.textDirection}
+        showFrame={showFrame}
       />
     );
   }
@@ -542,6 +565,7 @@ function DiagramBody({
       data={data}
       compact={compact}
       direction={ctx.textDirection}
+      showFrame={showFrame}
     />
   );
 }

package/corpus/core/src/client/blocks/library/server-specs.ts

@@ -211,7 +211,7 @@ export const libraryBlockConfigs: BlockSpec<any>[] = [
     placement: ["block"],
     label: "Diagram",
     description:
-      "A flexible inline architecture/code diagram. Prefer html/css with SVG or semantic HTML for polished two-dimensional layouts; use .diagram-* primitives and --wf-* tokens for theme/sketch compatibility. Legacy nodes/edges are only for simple previews.",
+      "A flexible inline architecture/code diagram. Prefer html/css with SVG or semantic HTML for polished two-dimensional layouts; use .diagram-* primitives and --wf-* tokens for theme/sketch compatibility. Set frame to show for standalone artifacts that need containment, hide when surrounding docs/canvas chrome already supplies the boundary. Legacy nodes/edges are only for simple previews.",
   }),
   defineBlock<WireframeData>({
     type: "wireframe",
@@ -221,7 +221,7 @@ export const libraryBlockConfigs: BlockSpec<any>[] = [
     placement: ["block"],
     label: "Wireframe",
     description:
-      "A sketch wireframe of one screen built from kit primitives (or an HTML mockup), rendered in a chosen surface frame (desktop/mobile/popover/panel/browser).",
+      "A sketch wireframe of one screen built from kit primitives (or an HTML mockup), rendered in a chosen surface (desktop/mobile/popover/panel/browser). Set frame to show for standalone screens and recap comparisons, hide only when surrounding chrome already supplies the boundary.",
   }),
   defineBlock<MermaidData>({
     type: "mermaid",

package/corpus/core/src/client/blocks/library/wireframe.config.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 import { prop, attributeValue } from "../mdx.js";
-import type { BlockMdxConfig } from "../types.js";
+import type { BlockMdxConfig, BlockVisualFrame } from "../types.js";
 
 /**
  * Pure (React-free) part of the shared `wireframe` block: its data shape, zod
@@ -138,6 +138,8 @@ export interface WireframeData {
   /** `design` renders full-fidelity branded HTML/CSS instead of a sketch. */
   renderMode?: WireframeRenderMode;
   caption?: string;
+  /** Outer surface frame. `auto` lets the host choose the right default. */
+  frame?: BlockVisualFrame;
   /**
    * Neutral, textless loading register. The renderer drops borders, the sketch
    * outline, and color, rendering soft placeholder geometry only.
@@ -205,6 +207,7 @@ const elNameSchema = z.enum(
   WIREFRAME_EL_NAMES as [WireframeElName, ...WireframeElName[]],
 );
 const idSchema = z.string().trim().min(1).max(120);
+const visualFrameSchema = z.enum(["auto", "show", "hide"]);
 
 /**
  * Reject full-document HTML (html/head/body/script/style tags) in the `html` /
@@ -281,6 +284,7 @@ export const wireframeSchema = z
     surface: z.enum(["desktop", "mobile", "popover", "panel", "browser"]),
     renderMode: z.enum(["wireframe", "design"]).optional(),
     caption: z.string().trim().max(400).optional(),
+    frame: visualFrameSchema.optional(),
     skeleton: z.boolean().optional(),
     html: z
       .string()
@@ -387,6 +391,7 @@ function serializeScreen(data: WireframeData): string {
     prop("surface", data.surface),
     prop("renderMode", data.renderMode),
     prop("caption", data.caption),
+    prop("frame", data.frame),
     prop("html", data.html),
     prop("css", data.css),
     prop("skeleton", data.skeleton),
@@ -494,6 +499,7 @@ function parseScreen(node: WireframeMdxNode, idContext: string): WireframeData {
       (stringAttr(node, "surface") as WireframeData["surface"]) ?? "desktop",
     renderMode: stringAttr(node, "renderMode") as WireframeData["renderMode"],
     caption: stringAttr(node, "caption"),
+    frame: stringAttr(node, "frame") as WireframeData["frame"],
     html: requiredStringAttr(node, "html"),
     css: requiredStringAttr(node, "css"),
     skeleton: boolAttr(node, "skeleton"),

package/corpus/core/src/client/blocks/library/wireframe.tsx

@@ -113,6 +113,7 @@ function ArtboardFrame({
   skeleton,
   renderMode,
   roughOverlay = true,
+  showFrame = true,
   selector,
   caption,
   render,
@@ -129,6 +130,7 @@ function ArtboardFrame({
   skeleton?: boolean;
   renderMode?: "wireframe" | "design";
   roughOverlay?: boolean;
+  showFrame?: boolean;
   selector: string;
   caption?: string;
   render: (ctx: {
@@ -164,6 +166,9 @@ function ArtboardFrame({
   const designMode = renderMode === "design";
   const sketchy = !designMode && style === "sketchy" && !skeleton;
   const roughEnabled = sketchy && roughOverlay;
+  const frameBorder = skeleton
+    ? "var(--plan-placeholder-line, var(--plan-line, hsl(var(--border))))"
+    : "var(--plan-line, hsl(var(--border)))";
 
   useEffect(() => {
     const element = fitRef.current;
@@ -231,6 +236,7 @@ function ArtboardFrame({
           ref={ref}
           className="plan-kit-artboard relative"
           data-rough-scope="wireframe"
+          data-frame={showFrame ? "show" : "hide"}
           style={{
             width,
             // Auto-height by default (content-driven, floored at `minHeight`);
@@ -259,10 +265,19 @@ function ArtboardFrame({
           >
             {render({ theme, style })}
           </div>
+          {!roughEnabled && showFrame && (
+            <div
+              className="pointer-events-none absolute inset-0"
+              style={{
+                borderRadius: preset.radius,
+                border: `1.5px solid ${frameBorder}`,
+              }}
+            />
+          )}
           <RoughOverlay
             scopeRef={ref}
             enabled={roughEnabled}
-            drawFrame={false}
+            drawFrame={showFrame}
             frameRadius={preset.radius}
             selector={selector}
           />
@@ -313,10 +328,12 @@ function WireframeStyleToggleButton() {
 function HtmlArtboard({
   data,
   ctx: _ctx,
+  showFrame,
   compact,
 }: {
   data: WireframeData;
   ctx: BlockRenderContext;
+  showFrame: boolean;
   compact?: boolean;
 }) {
   const renderMode = data.renderMode ?? "wireframe";
@@ -350,6 +367,7 @@ function HtmlArtboard({
       compact={compact}
       skeleton={data.skeleton}
       renderMode={renderMode}
+      showFrame={showFrame}
       selector={HTML_ROUGH_SELECTOR}
       caption={data.caption}
       render={({ theme, style }) => (
@@ -357,6 +375,7 @@ function HtmlArtboard({
           className="plan-html-frame"
           data-theme={theme}
           data-style={style}
+          data-frame={showFrame ? "show" : "hide"}
           data-render-mode={renderMode}
           data-plan-design-scope={scopeId}
           data-skeleton={data.skeleton ? "true" : undefined}
@@ -378,9 +397,11 @@ function HtmlArtboard({
 
 function KitArtboard({
   data,
+  showFrame,
   compact,
 }: {
   data: WireframeData;
+  showFrame: boolean;
   compact?: boolean;
 }) {
   return (
@@ -388,6 +409,7 @@ function KitArtboard({
       surface={data.surface}
       compact={compact}
       skeleton={data.skeleton}
+      showFrame={showFrame}
       selector="[data-rough]"
       caption={data.caption}
       render={({ theme, style }) => (
@@ -430,10 +452,27 @@ function WireframeSurfaceView({
   ctx: BlockRenderContext;
   compact?: boolean;
 }) {
+  const showFrame = resolveVisualFrame(data.frame, ctx);
   if (isHtmlData(data)) {
-    return <HtmlArtboard data={data} ctx={ctx} compact={compact} />;
+    return (
+      <HtmlArtboard
+        data={data}
+        ctx={ctx}
+        showFrame={showFrame}
+        compact={compact}
+      />
+    );
   }
-  return <KitArtboard data={data} compact={compact} />;
+  return <KitArtboard data={data} showFrame={showFrame} compact={compact} />;
+}
+
+function resolveVisualFrame(
+  frame: WireframeData["frame"],
+  ctx: BlockRenderContext,
+): boolean {
+  const resolved =
+    frame && frame !== "auto" ? frame : (ctx.visualFrame ?? "show");
+  return resolved !== "hide";
 }
 
 /* -------------------------------------------------------------------------- */

package/corpus/core/src/client/blocks/types.ts

@@ -19,6 +19,9 @@ import type { ZodType } from "zod";
 /** Where a block can be placed in a document. */
 export type BlockPlacement = "block" | "inline";
 
+/** How visual blocks decide whether to draw an outer surface frame. */
+export type BlockVisualFrame = "auto" | "show" | "hide";
+
 /**
  * A serialized MDX/NFM attribute value before the shared `prop()` encoder runs.
  * `prop()` decides string-vs-JSON encoding; this is just the value domain.
@@ -96,6 +99,12 @@ export interface BlockRenderContext {
   dialect?: "gfm" | "nfm";
   /** Document text direction inferred by the host app. */
   textDirection?: "ltr" | "rtl";
+  /**
+   * Host default for visual wireframe/diagram frames when block data leaves
+   * `frame` unset or set to `auto`. Plans/recaps usually show a frame; docs can
+   * hide it by default and let individual blocks opt back in.
+   */
+  visualFrame?: Exclude<BlockVisualFrame, "auto">;
   /** Resolve an asset id → displayable URL. */
   resolveAssetSrc?: (assetId: string) => string | undefined;
   /** Open the shared asset picker (returns the chosen asset). */

package/corpus/core/src/client/chat/message-components.tsx

@@ -75,7 +75,11 @@ const PENDING_SELECTION_KEY = "pending-selection-context";
 // ─── displayableUserMessageText ───────────────────────────────────────────────
 
 export function displayableUserMessageText(text: string): string {
-  return text.replace(/<context>[\s\S]*?<\/context>\n?/g, "").trim();
+  return text
+    .replace(/<context\b[^>]*>[\s\S]*?<\/context>\n?/gi, "")
+    .replace(/<context\b[^>]*>[\s\S]*$/gi, "")
+    .replace(/<\/context>/gi, "")
+    .trim();
 }
 
 // ─── Message timestamp helpers ────────────────────────────────────────────────
@@ -214,7 +218,7 @@ export function SelectionAttachedPill() {
   if (length === null || length === 0) return null;
 
   return (
-    <div className="shrink-0 px-3 pt-1.5 -mb-1">
+    <div className="agent-selection-attached-pill shrink-0 px-3 pt-1.5 -mb-1">
       <div className="inline-flex items-center gap-1.5 rounded-full border border-border bg-muted/50 px-2 py-0.5 text-[11px] text-muted-foreground">
         <IconQuote size={11} />
         <span>{length.toLocaleString()} chars of selection attached</span>

package/corpus/core/src/client/sse-event-processor.ts

@@ -601,6 +601,15 @@ function dispatchActivityClear(tabId: string | undefined) {
   );
 }
 
+function dispatchMissingApiKey(tabId: string | undefined) {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(
+    new CustomEvent("agent-chat:missing-api-key", {
+      detail: { tabId },
+    }),
+  );
+}
+
 function pendingToolNames(content: ContentPart[]): {
   activity: string[];
   running: string[];
@@ -1056,7 +1065,7 @@ export function processEvent(
       errorCode,
     };
     if (typeof window !== "undefined") {
-      window.dispatchEvent(new Event("agent-chat:missing-api-key"));
+      dispatchMissingApiKey(tabId);
       window.dispatchEvent(
         new CustomEvent("agent-chat:run-error", {
           detail: { ...runError, tabId },
@@ -1156,9 +1165,7 @@ export function processEvent(
     }
     const normalized = normalizeChatError(errMsg, ev.errorCode);
     if (isMissingCredentialText(errMsg, ev.errorCode)) {
-      if (typeof window !== "undefined") {
-        window.dispatchEvent(new Event("agent-chat:missing-api-key"));
-      }
+      dispatchMissingApiKey(tabId);
     }
     const runError = {
       message: normalized.message,

package/corpus/core/src/client/use-agent-engine-configured.ts

@@ -15,10 +15,20 @@ export interface UseAgentEngineConfiguredResult {
 }
 
 export interface FetchAgentEngineConfiguredStateOptions {
+  /**
+   * Legacy hint from explicit missing-key stream events. Kept for API
+   * compatibility, but missing state still requires authoritative status
+   * responses so transient endpoint failures do not clobber connected state.
+   */
   missingFallback?: boolean;
   timeoutMs?: number;
 }
 
+export interface UseAgentEngineConfiguredOptions {
+  tabId?: string | null;
+  threadId?: string | null;
+}
+
 const DEFAULT_STATUS_CHECK_TIMEOUT_MS = 2500;
 
 async function fetchStatusJson(
@@ -60,6 +70,27 @@ function hasConfiguredFlag(value: unknown): value is { configured: boolean } {
   );
 }
 
+function missingKeyEventMatchesScope(
+  event: Event,
+  options: UseAgentEngineConfiguredOptions | undefined,
+): boolean {
+  const detail = (event as CustomEvent).detail as
+    | { tabId?: unknown; threadId?: unknown }
+    | undefined;
+  const eventTabId = typeof detail?.tabId === "string" ? detail.tabId : null;
+  const eventThreadId =
+    typeof detail?.threadId === "string" ? detail.threadId : null;
+  if (!eventTabId && !eventThreadId) return true;
+
+  const tabId = options?.tabId ?? null;
+  const threadId = options?.threadId ?? null;
+  if (!tabId && !threadId) return true;
+  return (
+    (eventTabId != null && eventTabId === tabId) ||
+    (eventThreadId != null && eventThreadId === threadId)
+  );
+}
+
 export async function fetchAgentEngineConfiguredState(
   enabled = true,
   options?: FetchAgentEngineConfiguredStateOptions,
@@ -76,22 +107,31 @@ export async function fetchAgentEngineConfiguredState(
     fetchStatusJson("/_agent-native/agent-engine/status", timeoutMs),
   ]);
 
-  // All three failed — likely a flaky network; keep the caller in unknown
-  // unless this check is reacting to an explicit missing-key stream event.
+  // All three failed — likely a flaky network; keep the caller in unknown.
+  // Even an explicit missing-key stream event should not pin the composer into
+  // setup without a fresh authoritative status response.
   if (envKeys == null && builderStatus == null && engineStatus == null) {
-    return options?.missingFallback ? "missing" : "unknown";
+    return "unknown";
   }
 
-  const keys = (envKeys ?? []) as Array<{
-    key: string;
-    configured: boolean;
-  }>;
+  const envKeysKnown = Array.isArray(envKeys);
+  const builderStatusKnown = hasConfiguredFlag(builderStatus);
+  const engineStatusKnown = hasConfiguredFlag(engineStatus);
+  const keys = envKeysKnown
+    ? (envKeys as Array<{
+        key: string;
+        configured: boolean;
+      }>)
+    : [];
   const llmKeys = keys.filter((k) => PROVIDER_ENV_VAR_SET.has(k.key));
   const anyConfigured =
     llmKeys.some((k) => k.configured) ||
-    (hasConfiguredFlag(builderStatus) && builderStatus.configured) ||
-    (hasConfiguredFlag(engineStatus) && engineStatus.configured);
-  return anyConfigured ? "configured" : "missing";
+    (builderStatusKnown && builderStatus.configured) ||
+    (engineStatusKnown && engineStatus.configured);
+  if (anyConfigured) return "configured";
+  return envKeysKnown && builderStatusKnown && engineStatusKnown
+    ? "missing"
+    : "unknown";
 }
 
 /**
@@ -103,6 +143,7 @@ export async function fetchAgentEngineConfiguredState(
  */
 export function useAgentEngineConfigured(
   enabled = true,
+  options?: UseAgentEngineConfiguredOptions,
 ): UseAgentEngineConfiguredResult {
   const [state, setState] = useState<AgentEngineConfiguredState>("unknown");
 
@@ -119,7 +160,8 @@ export function useAgentEngineConfigured(
     const onConfiguredChanged = () => {
       void check();
     };
-    const onMissing = () => {
+    const onMissing = (event: Event) => {
+      if (!missingKeyEventMatchesScope(event, options)) return;
       if (!enabled) {
         setState("configured");
         return;
@@ -143,7 +185,7 @@ export function useAgentEngineConfigured(
       );
       window.removeEventListener("agent-chat:missing-api-key", onMissing);
     };
-  }, [enabled]);
+  }, [enabled, options?.tabId, options?.threadId]);
 
   return { missing: state === "missing", state };
 }

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -7124,11 +7124,15 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             setResponseStatus(event, 400);
             return { error: "message is required" };
           }
-          // Strip mention markup: @[Name|type] → @Name
-          const cleanMessage = message.replace(
-            /@\[([^\]|]+)\|[^\]]*\]/g,
-            "@$1",
-          );
+          // Strip hidden context and mention markup before title generation.
+          // Fallback titles are often direct truncations, so never let injected
+          // prompt context become a visible tab label.
+          const cleanMessage = message
+            .replace(/<context\b[^>]*>[\s\S]*?<\/context>\n?/gi, "")
+            .replace(/<context\b[^>]*>[\s\S]*$/gi, "")
+            .replace(/<\/context>/gi, "")
+            .replace(/@\[([^\]|]+)\|[^\]]*\]/g, "@$1")
+            .trim();
           // Mirror the chat-run resolution so BYO-key users have title
           // generation billed to their own key instead of the platform key.
           const { getOwnerActiveApiKey } =

package/corpus/core/src/styles/agent-native.css

@@ -682,6 +682,23 @@
   line-height: 1.75rem;
 }
 
+.agent-composer-stack {
+  position: relative;
+  flex-shrink: 0;
+  width: 100%;
+}
+
+.agent-composer-stack[data-agent-composer-adjacent-ui="true"],
+.agent-composer-stack:has(.agent-selection-attached-pill) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.agent-composer-setup-card {
+  width: 100%;
+}
+
 [data-agent-empty-state="centered"] {
   justify-content: center;
 }
@@ -691,6 +708,33 @@
   overflow: visible;
 }
 
+[data-agent-empty-state="centered"]
+  > .agent-composer-stack:not([data-agent-composer-adjacent-ui="true"]):not(
+    :has(.agent-selection-attached-pill)
+  )
+  > .agent-composer-setup-card {
+  position: absolute;
+  left: 0;
+  right: 0;
+  z-index: 3;
+}
+
+[data-agent-empty-state="centered"]
+  > .agent-composer-stack:not([data-agent-composer-adjacent-ui="true"]):not(
+    :has(.agent-selection-attached-pill)
+  )
+  > .agent-composer-setup-card[data-agent-composer-setup-position="above"] {
+  bottom: calc(100% + 0.5rem);
+}
+
+[data-agent-empty-state="centered"]
+  > .agent-composer-stack:not([data-agent-composer-adjacent-ui="true"]):not(
+    :has(.agent-selection-attached-pill)
+  )
+  > .agent-composer-setup-card[data-agent-composer-setup-position="below"] {
+  top: calc(100% + 0.5rem);
+}
+
 [data-agent-empty-state="compact-setup"] > .agent-chat-scroll {
   flex: 0 0 auto;
   overflow: visible;

package/corpus/core/src/styles/blocks.css

@@ -1290,6 +1290,20 @@
   line-height: 1.4;
 }
 
+.plan-diagram-frame[data-frame="show"] {
+  border: 1px solid var(--wf-diagram-line);
+  padding: 10px;
+}
+
+.plan-diagram-frame[data-frame="show"][data-rough-ready] {
+  border-color: transparent;
+}
+
+.plan-diagram-frame[data-frame="hide"] {
+  border: 0;
+  background: transparent;
+}
+
 .plan-diagram-frame[data-theme="dark"] {
   --wf-diagram-line: color-mix(in srgb, var(--wf-sketch) 72%, var(--wf-line));
 }
@@ -1312,6 +1326,10 @@
   direction: inherit;
 }
 
+.plan-diagram-frame[data-frame="show"] .plan-diagram-frame-content {
+  padding: 0;
+}
+
 .plan-diagram-frame-content
   > .diagram-panel:not([data-rough]):not([data-diagram-frame]) {
   --rough-skip: 1;

package/corpus/templates/plan/.agents/skills/visual-plan/references/document-quality.md

@@ -109,12 +109,16 @@ so you never emit a block the editor cannot render or round-trip:
   `--wf-paper`, `--wf-card`, `--wf-accent`, `--wf-accent-soft`, `--wf-warn`, and
   `--wf-ok`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
   set `font-family` and do not hard-code hex, rgb, or hsl colors in diagram HTML
-  or CSS. Leave room for the sketch font: keep labels short, give nodes generous
-  width, and place boundary/annotation labels in unused space instead of over
-  nodes; labels must not overlap nodes, connectors, or each other. For small
-  text/SVG changes to an existing HTML diagram, use `patch-diagram-html` with a
-  unique `find`/`replace` snippet instead of resending the whole `data.html`
-  string. Use legacy `nodes` / `edges` only for small previews or truly
+  or CSS. Choose the outer `frame` intentionally: use `show` when the diagram
+  stands alone in a recap, comparison, or prose section; use `hide` when the
+  diagram sits inside docs chrome, columns, tabs, cards, a canvas surface, or
+  already has visible `.diagram-panel` / `.diagram-box` structure. Leave room
+  for the sketch font: keep labels short, give nodes generous width, and place
+  boundary/annotation labels in unused space instead of over nodes; labels must
+  not overlap nodes, connectors, or each other. For small text/SVG changes to an
+  existing HTML diagram, use `patch-diagram-html` with a unique
+  `find`/`replace` snippet instead of resending the whole `data.html` string.
+  Use legacy `nodes` / `edges` only for small previews or truly
   sequential flows. In architecture/code plans, prefer a repeated section rhythm:
   recommendation title, confidence and category badges, code-path evidence, a
   local before/after or current/target spatial diagram, then concise