@agent-native/core 0.84.53 → 0.84.54

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2044
-- template files: 5001
+- template files: 5003

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @agent-native/core
 
+## 0.84.54
+
+### Patch Changes
+
+- a259f96: Keep centered chat composers stable when the Connect AI setup card appears.
+- df3fcfd: Allow wireframe and diagram blocks to opt in or out of their outer visual frame.
+
 ## 0.84.53
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.53",
+  "version": "0.84.54",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/cli/skills.ts

@@ -858,15 +858,26 @@ occurrence. The result is re-sanitized. In local-files privacy mode, do not call
 hosted Plan tools; edit the local MDX source directly and rerun the local
 check/serve or verify command for \`<plan-dir>\`.
 
-**Treat the wireframe border as part of the visible design.** Always wrap HTML
-wireframe content in a root container with real inner padding before drawing
-cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows on the
-root node itself so the first row never sits flush against the screen border. Do
-not rely on padding on a nested page section as the first visible inset; the
-outermost element must create the breathing room. Keep text away from borders:
-every container, field, button, menu item, and annotation needs enough padding
-and line-height to read cleanly in the rendered Plan view.
+**Choose the outer frame deliberately.** Wireframe and diagram data accept
+\`frame: "auto" | "show" | "hide"\` in block data (\`<Screen frame="hide">\` in
+MDX wireframes, \`<Diagram frame="hide">\` for MDX diagrams). Leave it unset or
+\`auto\` when the host context should decide: Plan and recap surfaces default to a
+drawn outer frame; docs surfaces default to no outer frame. Use \`show\` for
+standalone product screens, before/after recap comparisons, screenshot-like
+artifacts, and visuals that need containment from surrounding prose. Use \`hide\`
+when a docs page, tab, column, card, canvas artboard, or the visual's own
+internal chrome already supplies the boundary. Do not use \`hide\` to compensate
+for cramped content; fix the layout instead.
+
+**Inner padding and borders still matter.** Always wrap HTML wireframe content
+in a root container with real inner padding before drawing cards, fields, pills,
+labels, or controls. Use at least 14-16px of padding, \`box-sizing: border-box\`,
+\`height: 100%\`, and \`gap\` between child rows on the root node itself so the
+first row never sits flush against the screen edge. Do not rely on padding on a
+nested page section as the first visible inset; the outermost element must
+create the breathing room. Keep text away from borders: every container, field,
+button, menu item, and annotation needs enough padding and line-height to read
+cleanly in the rendered Plan view.
 
 **For feature-cloud or abundance visuals, optimize the composition over line-by-line
 reading.** Some marketing/product sections need to feel like a large surface area
@@ -1244,12 +1255,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
@@ -2426,7 +2441,10 @@ tags — resolve every conceptual name to its exact tag + prop schema with the
   Author diagram HTML/CSS with the renderer-owned \`.diagram-*\` primitives
   (\`.diagram-panel\`, \`.diagram-node\`, \`.diagram-pill\`, \`[data-rough]\`, …) and
   the same \`--wf-*\` theme tokens \`references/wireframe.md\` defines — never
-  \`font-family\`, hex, rgb/hsl literals, or one-off dark/light palettes.
+  \`font-family\`, hex, rgb/hsl literals, or one-off dark/light palettes. Choose
+  the outer \`frame\` intentionally: recap diagrams usually benefit from
+  \`frame: "show"\` when they stand alone, but use \`frame: "hide"\` when columns,
+  tabs, a card, or the diagram's own panels already provide the boundary.
 - **Outcome-first narrative** → \`rich-text\` for the "what changed and why" prose:
   the objective the diff served, the key decisions visible in it, and the risks a
   reviewer should weigh. This is the only place the model writes freely.

package/corpus/core/src/client/AssistantChat.tsx

@@ -3452,6 +3452,15 @@ const AssistantChatInner = forwardRef<
     queryKey: ["guided-questions"],
     ...(browserTabId ? { browserTabId } : {}),
   });
+  const hasComposerAccessoryAboveStack = Boolean(
+    composerError ||
+    showComposerSlot ||
+    showCenteredEmptyThreadFooterSlot ||
+    (guidedQuestions && guidedQuestions.length > 0) ||
+    showScrollToBottom ||
+    composerContextItems.length > 0 ||
+    showPlanModeCallout,
+  );
 
   // Human-in-the-loop approvals: when the user approves a paused `needsApproval`
   // tool call, re-issue the turn carrying the call's approval key so the server
@@ -3877,7 +3886,6 @@ const AssistantChatInner = forwardRef<
                     onSwitchToAct={handleSwitchToAct}
                   />
                 )}
-                <SelectionAttachedPill />
                 {/* Inline attachment / body-size error */}
                 {composerError && (
                   <div
@@ -3896,124 +3904,142 @@ const AssistantChatInner = forwardRef<
                     </button>
                   </div>
                 )}
-                {missingApiKey &&
-                !authError &&
-                missingApiKeySetupAboveComposer ? (
-                  <BuilderSetupCard
-                    onConnected={handleBuilderConnected}
-                    bouncePulse={missingKeyBouncePulse}
-                    layout={missingApiKeySetupLayout}
-                  />
-                ) : null}
-                {/* Input area */}
-                <AgentComposerFrame
-                  layoutVariant={composerLayoutVariant}
-                  className={cn(
-                    composerAreaClassName,
-                    missingApiKey && "cursor-pointer",
-                    isComposerDisabled && "opacity-70",
-                  )}
-                  onClick={
-                    missingApiKey
-                      ? () => setMissingKeyBouncePulse((p) => p + 1)
-                      : undefined
+                <div
+                  className="agent-composer-stack"
+                  data-agent-composer-adjacent-ui={
+                    hasComposerAccessoryAboveStack ? "true" : undefined
                   }
                 >
-                  <ComposerAttachmentPreviewStrip />
-                  <TiptapComposer
-                    focusRef={tiptapRef}
-                    disabled={isComposerDisabled}
-                    placeholder={
+                  <SelectionAttachedPill />
+                  {missingApiKey &&
+                  !authError &&
+                  missingApiKeySetupAboveComposer ? (
+                    <div
+                      className="agent-composer-setup-card"
+                      data-agent-composer-setup-position="above"
+                    >
+                      <BuilderSetupCard
+                        onConnected={handleBuilderConnected}
+                        bouncePulse={missingKeyBouncePulse}
+                        layout={missingApiKeySetupLayout}
+                      />
+                    </div>
+                  ) : null}
+                  {/* Input area */}
+                  <AgentComposerFrame
+                    layoutVariant={composerLayoutVariant}
+                    className={cn(
+                      composerAreaClassName,
+                      missingApiKey && "cursor-pointer",
+                      isComposerDisabled && "opacity-70",
+                    )}
+                    onClick={
                       missingApiKey
-                        ? missingApiKeySetupAboveComposer
-                          ? "Connect AI above to start chatting..."
-                          : "Connect AI below to start chatting..."
-                        : composerDisabled
-                          ? (composerDisabledPlaceholder ??
-                            "Open Desktop to use this chat.")
-                          : isRunning
-                            ? queuedMessages.length > 0
-                              ? `${queuedMessages.length} queued — send a follow-up...`
-                              : "Send a follow-up..."
-                            : composerPlaceholder
-                    }
-                    onSubmit={
-                      isRunning || composerContextItems.length > 0
-                        ? (text, references, attachments, options) =>
-                            void addToQueue(
-                              text,
-                              undefined,
-                              references.length > 0 ? references : undefined,
-                              attachments,
-                              undefined,
-                              resolveAssistantChatSubmitIntent({
-                                isRunning,
-                                requestedIntent: options?.intent,
-                              }),
-                              undefined,
-                              true,
-                            )
+                        ? () => setMissingKeyBouncePulse((p) => p + 1)
                         : undefined
                     }
-                    onSlashCommand={onSlashCommand}
-                    onBeforeSubmit={ensureAgentEngineReadyForSubmit}
-                    execMode={execMode}
-                    onExecModeChange={onExecModeChange}
-                    planModeDisabled={planModeDisabled}
-                    planModeDisabledReason={planModeDisabledReason}
-                    selectedModel={selectedModel ?? defaultModel}
-                    selectedEffort={selectedEffort}
-                    availableModels={availableModels}
-                    onModelChange={onModelChange}
-                    onEffortChange={onEffortChange}
-                    imageModelMenu={imageModelMenu}
-                    onConnectProvider={onConnectProvider}
-                    toolbarSlot={composerToolbarSlot}
-                    contextItems={composerContextItems}
-                    onRemoveContextItem={removeComposerContextItem}
-                    plusMenuMode={plusMenuMode}
-                    layoutVariant={composerLayoutVariant}
-                    providerConnectStatusEnabled={providerStatusChecksEnabled}
-                    draftScope={threadId || tabId}
-                    interceptBuildRequestsForBuilder
-                    onAttachmentError={setComposerError}
-                    extraActionButton={
-                      contextXRayEnabled ||
-                      composerExtraActionButton ||
-                      showRunningInUI ? (
-                        <>
-                          {contextXRayEnabled && (
-                            <ContextMeter threadId={threadId} />
-                          )}
-                          {composerExtraActionButton}
-                          {showRunningInUI && (
-                            <Tooltip>
-                              <TooltipTrigger asChild>
-                                <button
-                                  type="button"
-                                  onClick={stopActiveRun}
-                                  className="shrink-0 flex h-7 w-7 items-center justify-center rounded-md bg-muted text-foreground hover:bg-muted/80"
-                                >
-                                  <IconPlayerStop className="h-3.5 w-3.5" />
-                                </button>
-                              </TooltipTrigger>
-                              <TooltipContent>Stop generating</TooltipContent>
-                            </Tooltip>
-                          )}
-                        </>
-                      ) : undefined
-                    }
-                  />
-                </AgentComposerFrame>
-                {missingApiKey &&
-                !authError &&
-                !missingApiKeySetupAboveComposer ? (
-                  <BuilderSetupCard
-                    onConnected={handleBuilderConnected}
-                    bouncePulse={missingKeyBouncePulse}
-                    layout={missingApiKeySetupLayout}
-                  />
-                ) : null}
+                  >
+                    <ComposerAttachmentPreviewStrip />
+                    <TiptapComposer
+                      focusRef={tiptapRef}
+                      disabled={isComposerDisabled}
+                      placeholder={
+                        missingApiKey
+                          ? missingApiKeySetupAboveComposer
+                            ? "Connect AI above to start chatting..."
+                            : "Connect AI below to start chatting..."
+                          : composerDisabled
+                            ? (composerDisabledPlaceholder ??
+                              "Open Desktop to use this chat.")
+                            : isRunning
+                              ? queuedMessages.length > 0
+                                ? `${queuedMessages.length} queued — send a follow-up...`
+                                : "Send a follow-up..."
+                              : composerPlaceholder
+                      }
+                      onSubmit={
+                        isRunning || composerContextItems.length > 0
+                          ? (text, references, attachments, options) =>
+                              void addToQueue(
+                                text,
+                                undefined,
+                                references.length > 0 ? references : undefined,
+                                attachments,
+                                undefined,
+                                resolveAssistantChatSubmitIntent({
+                                  isRunning,
+                                  requestedIntent: options?.intent,
+                                }),
+                                undefined,
+                                true,
+                              )
+                          : undefined
+                      }
+                      onSlashCommand={onSlashCommand}
+                      onBeforeSubmit={ensureAgentEngineReadyForSubmit}
+                      execMode={execMode}
+                      onExecModeChange={onExecModeChange}
+                      planModeDisabled={planModeDisabled}
+                      planModeDisabledReason={planModeDisabledReason}
+                      selectedModel={selectedModel ?? defaultModel}
+                      selectedEffort={selectedEffort}
+                      availableModels={availableModels}
+                      onModelChange={onModelChange}
+                      onEffortChange={onEffortChange}
+                      imageModelMenu={imageModelMenu}
+                      onConnectProvider={onConnectProvider}
+                      toolbarSlot={composerToolbarSlot}
+                      contextItems={composerContextItems}
+                      onRemoveContextItem={removeComposerContextItem}
+                      plusMenuMode={plusMenuMode}
+                      layoutVariant={composerLayoutVariant}
+                      providerConnectStatusEnabled={providerStatusChecksEnabled}
+                      draftScope={threadId || tabId}
+                      interceptBuildRequestsForBuilder
+                      onAttachmentError={setComposerError}
+                      extraActionButton={
+                        contextXRayEnabled ||
+                        composerExtraActionButton ||
+                        showRunningInUI ? (
+                          <>
+                            {contextXRayEnabled && (
+                              <ContextMeter threadId={threadId} />
+                            )}
+                            {composerExtraActionButton}
+                            {showRunningInUI && (
+                              <Tooltip>
+                                <TooltipTrigger asChild>
+                                  <button
+                                    type="button"
+                                    onClick={stopActiveRun}
+                                    className="shrink-0 flex h-7 w-7 items-center justify-center rounded-md bg-muted text-foreground hover:bg-muted/80"
+                                  >
+                                    <IconPlayerStop className="h-3.5 w-3.5" />
+                                  </button>
+                                </TooltipTrigger>
+                                <TooltipContent>Stop generating</TooltipContent>
+                              </Tooltip>
+                            )}
+                          </>
+                        ) : undefined
+                      }
+                    />
+                  </AgentComposerFrame>
+                  {missingApiKey &&
+                  !authError &&
+                  !missingApiKeySetupAboveComposer ? (
+                    <div
+                      className="agent-composer-setup-card"
+                      data-agent-composer-setup-position="below"
+                    >
+                      <BuilderSetupCard
+                        onConnected={handleBuilderConnected}
+                        bouncePulse={missingKeyBouncePulse}
+                        layout={missingApiKeySetupLayout}
+                      />
+                    </div>
+                  ) : null}
+                </div>
               </div>
             </TextStreamingContext.Provider>
           </ChatRunningContext.Provider>

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 import { childCodeFenceFields, serializeChildCodeFenceFields } from "../mdx.js";
-import type { BlockMdxConfig } from "../types.js";
+import type { BlockMdxConfig, BlockVisualFrame } from "../types.js";
 
 /**
  * Pure (React-free) part of the shared `diagram` block: its data schema and MDX
@@ -45,6 +45,8 @@ export interface DiagramData {
   html?: string;
   css?: string;
   caption?: string;
+  /** Outer surface frame. `auto` lets the host choose the right default. */
+  frame?: BlockVisualFrame;
   /**
    * Legacy compatibility path for older/simple node graphs. New plans should use
    * `html`/`css` when layout quality matters.
@@ -120,6 +122,8 @@ const diagramNoteSchema = z.object({
   y: z.number().min(0).max(100).optional(),
 }) as z.ZodType<DiagramNote>;
 
+const visualFrameSchema = z.enum(["auto", "show", "hide"]);
+
 /**
  * The block can be a flexible HTML/SVG fragment or a legacy positional
  * node/edge/note graph, so it ships a custom `Edit` rather than relying on the
@@ -144,6 +148,7 @@ export const diagramSchema = z
       })
       .optional(),
     caption: z.string().trim().max(600).optional(),
+    frame: visualFrameSchema.optional(),
     nodes: z.array(diagramNodeSchema).max(80).optional(),
     edges: z.array(diagramEdgeSchema).max(120).optional(),
     notes: z.array(diagramNoteSchema).max(40).optional(),
@@ -167,7 +172,9 @@ function graphDataForAttr(data: DiagramData): DiagramData | undefined {
   if (data.edges?.length) graph.edges = data.edges;
   if (data.notes?.length) graph.notes = data.notes;
   if (Object.keys(graph).length > 0) return graph;
-  return hasChildFenceData(data) ? undefined : data;
+  if (hasChildFenceData(data)) return undefined;
+  const { frame: _frame, ...dataForAttr } = data;
+  return Object.keys(dataForAttr).length > 0 ? dataForAttr : undefined;
 }
 
 /**
@@ -185,12 +192,16 @@ export const diagramMdx: BlockMdxConfig<DiagramData> = {
       | Record<string, unknown>
       | undefined,
     caption: data.caption,
+    frame: data.frame,
   }),
   fromAttrs: (attrs) => ({
     ...(attrs.object<DiagramData>("data") ?? {}),
     ...(attrs.string("caption") !== undefined
       ? { caption: attrs.string("caption") }
       : {}),
+    ...(attrs.string("frame") !== undefined
+      ? { frame: attrs.string("frame") as BlockVisualFrame }
+      : {}),
   }),
   serializeChildren: (data) =>
     serializeChildCodeFenceFields(data, { html: "html", css: "css" }),

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"),