@agent-native/core 0.84.53 → 0.84.55

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

@@ -171,15 +171,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

package/corpus/templates/plan/.agents/skills/visual-recap/SKILL.md

@@ -377,7 +377,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/templates/plan/.agents/skills/visual-recap/references/wireframe.md

@@ -171,15 +171,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

package/corpus/templates/plan/actions/create-ui-plan.ts

@@ -72,7 +72,7 @@ export default defineAction({
       content: planContentSchema
         .optional()
         .describe(
-          "Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe's data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.",
+          'Structured editable UI plan content. Prefer this for app-owned top canvas wireframes (HTML mockups: set the wireframe\'s data.html to a semantic HTML fragment of the screen and pick a surface — the renderer owns the theme, footprint/aspect, hand-drawn font, and sketch overlay; use --wf-* CSS tokens for any custom color, never hex). Call get-plan-blocks first for visual frame guidance before choosing frame: "show" or frame: "hide". Do not use legacy kit-tree screen arrays or nested FrameScreen/Card/Row/Btn-style children for new canvas artboards. Use sketch diagrams, rich text, code blocks (grouped in a vertical tabs block for a file map), annotated code for key files, validation checklists, and bounded custom HTML fragments. Diagram data.html/data.css should use renderer-owned .diagram-* primitives plus --wf-* tokens, not custom fonts or hard-coded hex/rgb/hsl colors, so light/dark and sketchy Excalifont/rough.js modes remain correct. The canvas should carry Claude-style flex/grid wireframe artboards and designer annotations; the document should add implementation substance instead of duplicating the same wireframes. The renderer owns all visual styling; emit lean content, not pixels.',
         ),
       markdown: z
         .string()

package/corpus/templates/plan/actions/create-visual-plan.ts

@@ -84,7 +84,7 @@ export default defineAction({
       content: planContentSchema
         .optional()
         .describe(
-          "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.",
+          "Structured editable plan content. Prefer this for rich text, inline diagrams, annotated code, question-form open questions, and optional canvas/prototype UI surfaces. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: canvas frames use wireframe data.html/html semantic HTML, not legacy kit-tree screen arrays; use diagram blocks with .diagram-* primitives and --wf-* tokens (no hex/rgb/hsl, no custom fonts); for file maps use annotated-code blocks in a vertical tabs block; put unresolved decisions in a bottom question-form block.",
         ),
       markdown: z
         .string()

package/corpus/templates/plan/actions/create-visual-recap.ts

@@ -245,7 +245,7 @@ export default defineAction({
       .describe("Current focus for the review surface."),
     status: planStatusSchema.optional().default("review"),
     mdx: planMdxFileSchema.describe(
-      "Recap source files. Call the get-plan-blocks tool FIRST for the authoritative block catalog, authoring rules, and style tokens — do not author from memory. Key rules: derive all blocks from the real diff only; use diff blocks with line-anchored annotations on key hunks; for UI changes include realistic, non-empty WireframeBlock before/after in a Columns block (labels: Before / After) with visible product text/controls; if canvas.mdx is present, DesignBoard artboards must use Screen html/data.html wireframes, never fresh nested kit-tree children such as FrameScreen/Card/Row/Btn; use .diagram-* primitives and --wf-* tokens in diagrams (no hex/rgb/hsl, no custom fonts); keep API endpoint blocks in single-column flow unless it is an explicit before/after contract comparison.",
+      "Recap source files. Call the get-plan-blocks tool FIRST for the authoritative block catalog, visual frame guidance, authoring rules, and style tokens — do not author from memory. Key rules: derive all blocks from the real diff only; use diff blocks with line-anchored annotations on key hunks; for UI changes include realistic, non-empty WireframeBlock before/after in a Columns block (labels: Before / After) with visible product text/controls; if canvas.mdx is present, DesignBoard artboards must use Screen html/data.html wireframes, never fresh nested kit-tree children such as FrameScreen/Card/Row/Btn; use .diagram-* primitives and --wf-* tokens in diagrams (no hex/rgb/hsl, no custom fonts); keep API endpoint blocks in single-column flow unless it is an explicit before/after contract comparison.",
     ),
   }),
   publicAgent: {

package/corpus/templates/plan/actions/get-plan-blocks.ts

@@ -33,6 +33,8 @@ const AUTHORING_RULES_NOTE = `
 
 **Wireframes**: set \`data.html\` to a semantic HTML fragment; pick a surface (desktop/mobile/popover/panel/browser). The renderer owns theme, footprint/aspect, Excalifont, and rough.js sketch overlay. Use \`--wf-*\` CSS tokens for any custom color (never hex). Prototype screens use semantic HTML with \`data-goto\` attributes for navigation.
 
+**Visual frames**: \`wireframe\` and \`diagram\` data accept \`frame: "auto" | "show" | "hide"\`. Leave it unset/\`auto\` when the host context should decide: Plan and recap surfaces default to framed; docs default to unframed. Use \`frame: "show"\` for standalone product screens, before/after recap comparisons, screenshot-like artifacts, and visuals that need containment from surrounding prose. Use \`frame: "hide"\` when a docs page, tab, column, card, canvas artboard, or the visual's own internal chrome already supplies the boundary. Hiding the outer frame must not remove inner padding, meaningful card/field/button borders, or the visual's readable structure.
+
 **Canvas storyboards**: if the user asks for a canvas, storyboard, wireframe, light storyboard, UI flow, screen flow, product flow, mockup, or visual comparison, the primary artifact must be \`content.canvas\` / \`canvas.mdx\` with \`DesignBoard\` artboards containing \`Screen\` HTML wireframes. Each canvas \`Screen\` must carry \`html\` / \`data.html\`; never author fresh nested kit-tree children such as \`<FrameScreen>\`, \`<Card>\`, \`<Row>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags. Kit trees are old-plan compatibility only and often render worse on the pan/zoom canvas than HTML wireframes. Do not use document-body \`diagram\` blocks for the primary UI story. Use \`diagram\` only for architecture, data flow, or implementation mechanics below the canvas, and only after the UI storyboard exists.
 
 **Before/After columns**: compose a \`columns\` block from \`<Column>\` CHILDREN — never a \`columns=\` attribute or inline JSON array. Author it as \`<Columns><Column label="Before">…child block(s)…</Column><Column label="After">…child block(s)…</Column></Columns>\`. Each \`<Column>\` wraps real nested blocks (e.g. a \`Wireframe\`); the parser fills in column ids and child-block \`data\` from that markup, whereas a \`columns=\` attribute array leaves them missing and FAILS schema validation. For UI state comparisons put one \`wireframe\` block in each side and label the columns \`Before\` and \`After\`; the renderer draws labels as headings and lays narrow surfaces side by side. Never bake Before/After labels inside the wireframe HTML or hand-stack the pair.

package/corpus/templates/plan/app/components/plan/planBlocks.tsx

@@ -165,10 +165,12 @@ export function createPlanBlockRenderContext(options: {
   editingDisabled?: boolean;
   showCodeAnnotationOverlays?: boolean;
   codeAnnotationLayout?: BlockRenderContext["codeAnnotationLayout"];
+  visualFrame?: BlockRenderContext["visualFrame"];
 }): BlockRenderContext {
   const ctx: BlockRenderContext & PlanBlockRenderContextExtras = {
     dialect: "gfm",
     textDirection: options.textDirection,
+    visualFrame: options.visualFrame ?? "show",
     showCodeAnnotationOverlays: options.showCodeAnnotationOverlays,
     codeAnnotationLayout: options.codeAnnotationLayout,
     onQuestionFormSubmit: options.onVisualQuestionsSubmit,

package/corpus/templates/plan/app/components/plan/wireframe/Wireframe.tsx

@@ -121,10 +121,12 @@ export function Wireframe({
   selectedDesignElementKey?: string | null;
   onDesignElementSelect?: (selection: DesignElementSelection) => void;
 }) {
+  const showFrame = "frame" in data && data.frame === "hide" ? false : true;
   if (isHtmlData(data)) {
     return (
       <HtmlArtboard
         data={data}
+        showFrame={showFrame}
         compact={compact}
         canvasSize={canvasSize}
         canvasWidth={canvasWidth}
@@ -140,6 +142,7 @@ export function Wireframe({
     return (
       <KitWireframe
         data={data}
+        showFrame={showFrame}
         compact={compact}
         canvasSize={canvasSize}
         canvasWidth={canvasWidth}
@@ -167,6 +170,7 @@ function ArtboardFrame({
   skeleton,
   renderMode,
   roughOverlay = true,
+  showFrame = true,
   selector,
   caption,
   render,
@@ -178,6 +182,7 @@ function ArtboardFrame({
   skeleton?: boolean;
   renderMode?: "wireframe" | "design";
   roughOverlay?: boolean;
+  showFrame?: boolean;
   selector: string;
   caption?: string;
   render: (ctx: {
@@ -250,6 +255,7 @@ function ArtboardFrame({
           ref={ref}
           className="plan-kit-artboard relative"
           data-rough-scope="wireframe"
+          data-frame={showFrame ? "show" : "hide"}
           style={{
             width,
             height,
@@ -273,7 +279,7 @@ function ArtboardFrame({
               are never cut, and a skeleton frame still reads as a frame). Sketchy
               mode gets its frame from the rough overlay unless the caller needs
               all borders to stay in the normal scrolling DOM. */}
-          {!roughEnabled && (
+          {!roughEnabled && showFrame && (
             <div
               className="pointer-events-none absolute inset-0"
               style={{
@@ -285,6 +291,7 @@ function ArtboardFrame({
           <RoughOverlay
             scopeRef={ref}
             enabled={roughEnabled}
+            drawFrame={showFrame}
             frameRadius={preset.radius}
             selector={selector}
           />
@@ -330,6 +337,7 @@ function WireframeStyleToggleButton() {
 
 function HtmlArtboard({
   data,
+  showFrame,
   compact,
   canvasSize,
   canvasWidth,
@@ -340,6 +348,7 @@ function HtmlArtboard({
   onDesignElementSelect,
 }: {
   data: PlanWireframeBlock["data"];
+  showFrame: boolean;
   compact?: boolean;
   canvasSize?: number;
   canvasWidth?: number;
@@ -478,6 +487,7 @@ function HtmlArtboard({
       skeleton={data.skeleton}
       renderMode={renderMode}
       roughOverlay={!interactive}
+      showFrame={showFrame}
       selector={HTML_ROUGH_SELECTOR}
       caption={data.caption}
       render={({ theme, style }) => (
@@ -486,6 +496,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}
@@ -531,11 +542,13 @@ export function KitWireframePreview({
 
 function KitWireframe({
   data,
+  showFrame = data.frame !== "hide",
   compact,
   canvasSize,
   canvasWidth,
 }: {
   data: PlanWireframeBlock["data"];
+  showFrame?: boolean;
   compact?: boolean;
   canvasSize?: number;
   canvasWidth?: number;
@@ -547,6 +560,7 @@ function KitWireframe({
       canvasSize={canvasSize}
       canvasWidth={canvasWidth}
       skeleton={data.skeleton}
+      showFrame={showFrame}
       selector="[data-rough]"
       caption={data.caption}
       render={({ theme, style }) => (
@@ -588,6 +602,7 @@ export function SketchDiagram({
   compact?: boolean;
 }) {
   const t = useT();
+  const showFrame = data.frame !== "hide";
   if (data.html?.trim()) {
     return <HtmlDiagram data={data} compact={compact} />;
   }
@@ -599,6 +614,7 @@ export function SketchDiagram({
         data={data}
         compact={compact}
         markerId={markerId}
+        showFrame={showFrame}
       />
     );
   }
@@ -613,7 +629,14 @@ export function SketchDiagram({
     );
   }
   return (
-    <div className="plan-sketch rounded-[16px] border border-plan-line bg-plan-wireframe p-5">
+    <div
+      className={cn(
+        "plan-sketch",
+        showFrame
+          ? "rounded-[16px] border border-plan-line bg-plan-wireframe p-5"
+          : "p-0",
+      )}
+    >
       <div
         className={cn(
           "flex gap-3 overflow-x-auto pb-2",
@@ -684,6 +707,7 @@ function HtmlDiagram({
   const { resolvedTheme } = useTheme();
   const theme: "light" | "dark" = resolvedTheme === "dark" ? "dark" : "light";
   const style = useWireframeStyle();
+  const showFrame = data.frame !== "hide";
   const scopeId = useId().replace(/[^a-zA-Z0-9_-]/g, "");
   const scopeSelector = `[data-plan-diagram-scope="${scopeId}"]`;
   const safeHtml = useMemo(() => sanitizeDiagramHtml(data.html), [data.html]);
@@ -701,6 +725,7 @@ function HtmlDiagram({
         className="plan-diagram-frame"
         data-theme={theme}
         data-style={style}
+        data-frame={showFrame ? "show" : "hide"}
         data-plan-diagram-scope={scopeId}
       >
         {scopedCss && <style>{scopedCss}</style>}
@@ -712,7 +737,7 @@ function HtmlDiagram({
       <RoughOverlay
         scopeRef={ref}
         enabled={style === "sketchy"}
-        drawFrame={false}
+        drawFrame={showFrame}
         selector={DIAGRAM_ROUGH_SELECTOR}
       />
       {data.caption && !compact && (
@@ -726,10 +751,12 @@ function PositionedSketchDiagram({
   data,
   compact,
   markerId,
+  showFrame,
 }: {
   data: PlanDiagramBlock["data"];
   compact?: boolean;
   markerId: string;
+  showFrame: boolean;
 }) {
   const nodes = (data.nodes ?? []).map((node) => ({
     ...node,
@@ -743,7 +770,14 @@ function PositionedSketchDiagram({
   const canvasHeight = compact ? 280 : 430;
 
   return (
-    <div className="plan-sketch rounded-[16px] border border-plan-line bg-plan-wireframe p-5">
+    <div
+      className={cn(
+        "plan-sketch",
+        showFrame
+          ? "rounded-[16px] border border-plan-line bg-plan-wireframe p-5"
+          : "p-0",
+      )}
+    >
       <div
         className="relative overflow-hidden rounded-xl border border-plan-line bg-plan-document"
         style={{ minHeight: canvasHeight }}

package/corpus/templates/plan/app/components/plan/wireframe/html-artboard.css

@@ -319,6 +319,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));
 }
@@ -341,6 +355,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/app/global.css

@@ -503,8 +503,7 @@
 }
 
 .plan-document-toc__link.is-active {
-  color: hsl(var(--ring));
-  font-weight: 550;
+  color: var(--plan-text);
 }
 
 .plan-document-toc__link.is-nested {

package/corpus/templates/plan/changelog/2026-07-02-plan-chat-keeps-the-composer-anchored-when-connect-ai-appears.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-02
+---
+
+Plan chat keeps the composer anchored when Connect AI appears, and recap contents highlight the current section more clearly.

package/corpus/templates/plan/changelog/2026-07-02-wireframe-and-diagram-blocks-can-now-show-or-hide-their-outer-frame.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-02
+---
+
+Wireframe and diagram blocks can now show or hide their outer frame based on the surface they appear in.

package/corpus/templates/plan/server/plan-mdx.ts

@@ -435,6 +435,7 @@ function serializeScreen(
     surface: string;
     renderMode?: string;
     caption?: string;
+    frame?: string;
     html?: string;
     css?: string;
     skeleton?: boolean;
@@ -446,6 +447,7 @@ function serializeScreen(
     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),
@@ -1662,6 +1664,7 @@ function parseScreen(
       "renderMode",
     ) as PlanWireframeBlock["data"]["renderMode"],
     caption: stringAttr(node, "caption"),
+    frame: stringAttr(node, "frame") as PlanWireframeBlock["data"]["frame"],
     html: requiredStringAttr(node, "html"),
     css: requiredStringAttr(node, "css"),
     skeleton: boolAttr(node, "skeleton"),

package/corpus/templates/plan/shared/plan-content.ts

@@ -148,6 +148,7 @@ export type PlanWireframeSurface =
   | "browser";
 
 export type PlanVisualCanvasMode = "wireframe" | "design";
+export type PlanVisualFrame = "auto" | "show" | "hide";
 
 /** Tone keyword reused across screen primitives. The renderer maps to color. */
 export type PlanWireframeTone = "default" | "accent" | "warn" | "ok" | "muted";
@@ -259,6 +260,8 @@ export type PlanWireframeBlock = PlanBlockBase & {
     /** `design` renders full-fidelity branded HTML/CSS instead of a sketch. */
     renderMode?: PlanVisualCanvasMode;
     caption?: string;
+    /** Outer surface frame. `auto` lets the host choose the right default. */
+    frame?: PlanVisualFrame;
     /**
      * Neutral, textless loading register. The renderer drops borders, the sketch
      * outline, and color, rendering soft placeholder geometry only — a real
@@ -365,6 +368,8 @@ export type PlanDiagramBlock = PlanBlockBase & {
     html?: string;
     css?: string;
     caption?: string;
+    /** Outer surface frame. `auto` lets the host choose the right default. */
+    frame?: PlanVisualFrame;
     nodes?: PlanDiagramNode[];
     edges?: PlanDiagramEdge[];
     notes?: Array<{
@@ -1215,12 +1220,14 @@ const wireframeSurfaceSchema = z.enum([
 ]);
 
 const visualCanvasModeSchema = z.enum(["wireframe", "design"]);
+const visualFrameSchema = z.enum(["auto", "show", "hide"]);
 
 export const wireframeDataSchema: z.ZodType<PlanWireframeBlock["data"]> = z
   .object({
     surface: wireframeSurfaceSchema,
     renderMode: visualCanvasModeSchema.optional(),
     caption: z.string().trim().max(400).optional(),
+    frame: visualFrameSchema.optional(),
     skeleton: z.boolean().optional(),
     html: z
       .string()
@@ -1357,6 +1364,7 @@ const diagramDataSchema: z.ZodType<PlanDiagramBlock["data"]> = 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