@agent-native/core 0.79.26 → 0.80.0

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

@@ -0,0 +1,51 @@
+# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by `/visual-plan` and `/visual-recap`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (`references/local-files.md`) is the one exception.
+
+**The connector is usually the `plan` server**, but older installed agents may
+expose the same hosted connector as `agent-native-plans` — both names are valid,
+so never report the connector as missing just because it is named
+`agent-native-plans` instead of `plan`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (`tool_search` when available) for `create_visual_plan`,
+`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** The usual cause is a connector that did not finish connecting this
+session (it registers zero tools), NOT necessarily an auth problem — so do not
+assume the user must re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+  and start a new Codex session.
+- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same
+  reconnect command with `--client claude-code` and restart Claude.
+
+The same applies when a Plan tool returns `needs auth`, `Unauthorized`, or
+`Session terminated`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. `--client all` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->

package/corpus/templates/plan/.agents/skills/visual-recap/references/local-files.md

@@ -0,0 +1,85 @@
+# Local-files privacy mode — single source of truth
+
+This file is the canonical contract for fully local, no-database planning and
+recaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it
+in full before using local-files mode; do not call any hosted Plan tool for a
+local plan/recap except the schema-only block-catalog lookup described below.
+
+<!-- SHARED-CORE:local-files START -->
+
+**When to use it.** Use local-files privacy mode when the user explicitly asks
+for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
+files, offline/private work, or repo-owned/source-controlled artifacts, or when
+`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
+policy says the work must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan/recap data must never be sent to the Plan
+MCP server or the Plan app action surface. This is the only exception to the
+always-publish rule in `references/connection.md`.
+
+The local-files contract:
+
+- **Read context locally.** Read source, diff, and stat context from local files
+  and shell commands only. For recaps, the
+  `npx @agent-native/core@latest recap collect-diff`, `scan`, and
+  `build-prompt --local-files` helpers are safe — they operate on local files and
+  do not write to the Plan database.
+- **Fetch the block catalog first** (it sends no plan content). Use the MCP
+  `get-plan-blocks` tool if it is already available, or run
+  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.
+  Use `--format schema` when you need exact nested fields. If network access is
+  unavailable, use the bundled `references/*.md` and rely on `plan local check` to
+  catch invalid tags. Copy the catalog examples verbatim for the fields the
+  registry table cannot encode: `checklist` items need `id` and `label`;
+  `question-form` questions need `id`, `title`, and `mode`, and each option needs
+  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
+  — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
+  (a static template literal is accepted only when it has no `${...}`
+  interpolation). `plan local check` validates these required fields against the
+  renderer schema.
+- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
+  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
+  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
+  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and
+  optional `.plan-state.json`. For a recap, set `kind: "recap"` and
+  `localOnly: true` in the frontmatter/state. Use that exact folder as
+  `<plan-dir>` in every command below.
+- **Check, then serve.** Run
+  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any
+  preview, then
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`
+  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
+  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
+  token file and do not commit it. The URL opens the hosted Plan UI but reads from
+  the localhost bridge on this machine, so it is not shareable across machines. On
+  macOS `--open` prefers Chromium browsers; if Safari opens, switch to
+  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
+  HTTP localhost bridge. If the Plan app itself is running locally with the same
+  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly
+  offline environment, hand off the `<plan-dir>` path after `plan local check` and
+  note that interactive preview requires network access to the hosted Plan UI or a
+  running local Plan app.
+- **Headless verify.** Run
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
+  It starts the bridge, checks the private-network preflight and JSON payload,
+  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the
+  `bridgeUrl` from the verify/serve JSON to read the concrete validation error.
+- **Never call hosted tools for that plan/recap.** Do not call
+  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
+  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,
+  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,
+  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any
+  other hosted Plan tool — except the schema-only block-catalog lookup above.
+- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
+  `plan local check`, and rerun `serve` or `verify` when that preview path is
+  available. Summarize the new local URL when one exists; otherwise summarize the
+  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage
+  attachment, and publish/export receipts are unavailable until the user
+  explicitly opts into publishing.
+
+Local-files mode only prevents plan/recap content from reaching the Agent-Native
+Plan database. It does not by itself make the coding agent's language model local;
+for that stronger boundary the host agent/model must also be local or otherwise
+approved by the user.
+
+<!-- SHARED-CORE:local-files END -->

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

@@ -64,6 +64,27 @@ themes. For any inline border, background, or text color, reference a token:
 and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
 renderer owns the sketch/clean font.
 
+**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
+`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,
+`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,
+or arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the
+mockup and can make dark-mode canvas frames unreadable. Use bare semantic
+elements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before
+publishing, scan every wireframe `class` and `style` attribute: if a class sets
+background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
+or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
+are still discouraged; inline flex/grid styles are safer and easier to review.
+
+**Keep Rough.js sparse.** `.wf-card` and `.wf-box` already render with
+theme-safe filled backgrounds (`--wf-card`) and soft tokenized borders that work
+in both light and dark mode. Do not add `data-rough` to broad root wrappers,
+dialog shells, page panels, grid cells, or nested containers unless that single
+container is the visual point. The renderer sketches the outer frame and
+standard controls by default; use `data-rough` only for a deliberate one-off
+shape. If a mockup starts looking like stacked/overlapping sketch lines, remove
+rough targets from parent containers and let backgrounds plus spacing separate
+the surfaces.
+
 **Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
 renderer-owned visual styling, not layout spacing. Do not use guessed spacing
 tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing

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

@@ -146,7 +146,7 @@ export default defineAction({
     readOnly: false,
     requiresAuth: true,
     isConsequential: true,
-    title: "Create Visual Plan",
+    title: "Create Prototype Plan",
     description:
       "Create a plan whose primary review surface is a functional prototype.",
   },

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

@@ -60,7 +60,7 @@ async function assertPlanOwner(planId: string) {
 }
 
 function collabPrefixPattern(planId: string) {
-  return `${`plan:${planId}:`.replace(/[\\%_]/g, (value) => `\\${value}`)}%`;
+  return `${`plan:${planId}:`.replace(/[!%_]/g, (value) => `!${value}`)}%`;
 }
 
 function isMissingCollabTableError(error: unknown) {
@@ -71,7 +71,7 @@ async function deletePlanCollabState(planId: string) {
   await deleteCollabState(`plan:${planId}`);
   try {
     await getDbExec().execute({
-      sql: `DELETE FROM _collab_docs WHERE doc_id LIKE ? ESCAPE '\\'`,
+      sql: `DELETE FROM _collab_docs WHERE doc_id LIKE ? ESCAPE '!'`,
       args: [collabPrefixPattern(planId)],
     });
   } catch (error) {

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

@@ -39,6 +39,8 @@ const AUTHORING_RULES_NOTE = `
 
 **MDX prose and component syntax**: write ordinary top-level prose as normal Markdown; it imports as rich-text automatically. Use \`<RichText id="...">…</RichText>\` only when prose needs explicit metadata such as \`title\`, \`summary\`, or \`editable\`, or when preserving a referenced block id. Every capitalized block component must be self-closing (\`<Diagram id="..." data={{ ... }} />\`) or have a matching closing tag around children (\`<RichText id="...">…</RichText>\`). Never write a bare opening tag like \`<RichText ...>\` as a paragraph; the MDX parser treats it as unclosed JSX and import fails before the plan can render.
 
+**Code-bearing blocks**: \`code\`, \`annotated-code\`, and \`diff\` are whitespace-sensitive. Prefer the exact MDX form emitted by the authoring examples / source exporter, where multiline code is encoded as JSON string attributes such as \`code={\"const x =\\\\n  y\"}\`. Static template literals are accepted and preserve indentation, but they must be static strings with no \`\${...}\` interpolation.
+
 **File maps**: prefer \`annotated-code\` blocks (real code + line-anchored notes) grouped in a vertical \`tabs\` block, one tab per key file. Drop to a plain \`code\` block only for throwaway snippets with nothing to call out.
 
 **Tabs grouping**: use horizontal \`TabsBlock\` groups for multiple related diffs so each split diff gets full document width.

package/corpus/templates/plan/app/components/layout/Sidebar.tsx

@@ -666,7 +666,7 @@ export function Sidebar({
     <aside
       data-collapsed={collapsed ? "true" : "false"}
       className={cn(
-        "flex h-full min-w-0 shrink-0 flex-col overflow-hidden border-e border-border bg-sidebar text-sidebar-foreground transition-[width] duration-150",
+        "flex h-full min-w-0 shrink-0 flex-col overflow-hidden border-e border-border bg-sidebar text-sidebar-foreground transition-[width] duration-200 ease-out",
         collapsed ? "w-14" : "w-60",
       )}
     >
@@ -752,11 +752,11 @@ export function Sidebar({
 
       {!collapsed && session && (
         <>
-          <div className="border-t border-border px-2 py-2">
+          <div className="px-2 py-2">
             <ExtensionsSidebarSection />
           </div>
 
-          <div className="space-y-2 border-t border-border px-3 py-2">
+          <div className="space-y-2 px-3 py-2">
             <DevDatabaseLink />
             <FeedbackButton />
             <OrgSwitcher />
@@ -765,7 +765,7 @@ export function Sidebar({
       )}
 
       {!collapsed && !sessionLoading && !session && (
-        <div className="space-y-2 border-t border-border px-3 py-2">
+        <div className="space-y-2 px-3 py-2">
           <DevDatabaseLink />
           <FeedbackButton />
           <div className="flex items-center justify-between gap-2">
@@ -786,7 +786,7 @@ export function Sidebar({
       {collapsed && collapsible ? (
         <div
           className={cn(
-            "border-t border-border px-2 py-2",
+            "px-2 py-2",
             collapsed ? "flex justify-center" : "flex justify-end",
           )}
         >
@@ -795,9 +795,7 @@ export function Sidebar({
       ) : null}
 
       {!collapsed && (session || sessionLoading) && collapsible ? (
-        <div className="flex justify-end border-t border-border px-2 py-2">
-          {collapseButton}
-        </div>
+        <div className="flex justify-end px-2 py-2">{collapseButton}</div>
       ) : null}
     </aside>
   );

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

@@ -43,8 +43,8 @@ const WHEEL_ZOOM_STEP = 0.16;
 const PINCH_ZOOM_SENSITIVITY = 0.01;
 /** Base CSS grid cell, scaled by zoom. */
 const GRID_CELL = 28;
-/** Extra world-space grid on each side so the grid still fills overscrolled pans. */
-const GRID_PADDING = 5000;
+/** Extra world-space pan range on each side of the board. */
+const CANVAS_OVERSCROLL_PADDING = 5000;
 
 type CanvasView = typeof DEFAULT_VIEW;
 export type CanvasViewport = CanvasView;
@@ -395,7 +395,15 @@ export function CanvasArea({
   }, [frameLayoutKey, frames, hasSavedViewport, updateView]);
 
   const { zoom, pan } = view;
-  const worldTransform = `translate3d(${pan.x}px, ${pan.y}px, 0) scale(${zoom})`;
+  const worldTransform = `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`;
+  const scaledGridCell = GRID_CELL * zoom;
+  const gridStyle = useMemo<CSSProperties>(
+    () => ({
+      backgroundPosition: `${pan.x % scaledGridCell}px ${pan.y % scaledGridCell}px`,
+      backgroundSize: `${scaledGridCell}px ${scaledGridCell}px`,
+    }),
+    [pan.x, pan.y, scaledGridCell],
+  );
   useEffect(() => {
     queueViewportChange(view);
   }, [queueViewportChange, view]);
@@ -727,6 +735,12 @@ export function CanvasArea({
           setDrag(null);
         }}
       >
+        <div
+          aria-hidden="true"
+          className="plan-canvas-grid absolute inset-0"
+          data-plan-canvas-grid
+          style={gridStyle}
+        />
         <div
           data-plan-canvas-world
           className="plan-canvas-world relative origin-top-left"
@@ -735,23 +749,8 @@ export function CanvasArea({
             height: board.height,
             transform: worldTransform,
             transformOrigin: "0 0",
-            willChange: "transform",
-            backfaceVisibility: "hidden",
           }}
         >
-          <div
-            aria-hidden="true"
-            className="plan-canvas-grid absolute"
-            data-plan-canvas-grid
-            style={{
-              left: -GRID_PADDING,
-              top: -GRID_PADDING,
-              width: board.width + GRID_PADDING * 2,
-              height: board.height + GRID_PADDING * 2,
-              backgroundSize: `${GRID_CELL}px ${GRID_CELL}px`,
-            }}
-          />
-
           {/* Section containers sit BEHIND the frames (lowest layer) so each
               group reads as one bounded region the artboards rest inside. */}
           {sectionRects.map(({ section, rect }) => (
@@ -2318,13 +2317,9 @@ function clamp(value: number, min: number, max: number) {
 }
 
 /**
- * Keep the visible viewport inside the rendered grid. The grid is a fixed-size
- * child of the transformed world (board + GRID_PADDING on every side), so it is
- * large but finite; without this clamp a far-enough pan scrolls past the grid
- * edge into a blank void. Screen = pan + world * zoom, and the grid spans world
- * [-GRID_PADDING, board + GRID_PADDING], so bounding pan to the range below
- * guarantees the grid always fills the viewport while still allowing the full
- * GRID_PADDING of overscroll. A no-op until the viewport has been measured.
+ * Keep the visible viewport close to the board while still allowing generous
+ * overscroll. The grid is viewport-painted, so this is about keeping artboards
+ * discoverable rather than avoiding a finite grid edge.
  */
 function clampPanToGrid(
   view: CanvasView,
@@ -2333,10 +2328,11 @@ function clampPanToGrid(
 ): CanvasView {
   if (!rect) return view;
   const { zoom } = view;
-  const minPanX = rect.width - (board.width + GRID_PADDING) * zoom;
-  const maxPanX = GRID_PADDING * zoom;
-  const minPanY = rect.height - (board.height + GRID_PADDING) * zoom;
-  const maxPanY = GRID_PADDING * zoom;
+  const minPanX = rect.width - (board.width + CANVAS_OVERSCROLL_PADDING) * zoom;
+  const maxPanX = CANVAS_OVERSCROLL_PADDING * zoom;
+  const minPanY =
+    rect.height - (board.height + CANVAS_OVERSCROLL_PADDING) * zoom;
+  const maxPanY = CANVAS_OVERSCROLL_PADDING * zoom;
   return {
     zoom,
     pan: {

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

@@ -316,7 +316,7 @@ function WireframeStyleToggleButton() {
         event.stopPropagation();
         toggleWireframeStyle();
       }}
-      className="absolute right-2 top-2 z-30 inline-flex h-7 items-center gap-1 rounded-md border border-border/60 bg-background/90 px-2 text-xs font-medium text-muted-foreground opacity-0 shadow-sm backdrop-blur transition-[color,opacity] hover:text-foreground focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring group-hover/wireframe-artboard:opacity-100"
+      className="absolute right-2 top-2 z-30 inline-flex h-7 items-center gap-1 rounded-md border border-border/60 bg-background px-2 text-xs font-medium text-muted-foreground opacity-0 shadow-sm transition-[color,opacity] hover:text-foreground focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring group-hover/wireframe-artboard:opacity-100"
     >
       <IconPencil className="size-3.5" aria-hidden="true" />
       <span>{label}</span>
@@ -352,12 +352,17 @@ function HtmlArtboard({
   // Sanitize model-authored HTML at the render point (defense-in-depth against
   // stored XSS) — see sanitize-html.ts. Memoized so it only re-runs when the
   // html changes, not on every theme/zoom re-render.
-  const safeHtml = useMemo(
-    () => renderWireframeIconHtml(sanitizeWireframeHtml(data.html)),
-    [data.html],
-  );
   const renderMode = data.renderMode ?? "wireframe";
   const designMode = renderMode === "design";
+  const safeHtml = useMemo(
+    () =>
+      renderWireframeIconHtml(
+        sanitizeWireframeHtml(data.html, {
+          preserveThemeClasses: designMode,
+        }),
+      ),
+    [data.html, designMode],
+  );
   const scopeId = useId().replace(/[^a-zA-Z0-9_-]/g, "");
   const scopeSelector = `[data-plan-design-scope="${scopeId}"]`;
   const scopedCss = useMemo(() => {

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

@@ -225,6 +225,10 @@
   border-radius: var(--wf-radius);
   padding: 12px;
 }
+.plan-html-frame[data-style="sketchy"]:not([data-render-mode="design"])
+  :is(.wf-card, .wf-box) {
+  border-color: color-mix(in srgb, var(--wf-line) 72%, transparent);
+}
 .plan-html-frame:not([data-render-mode="design"]) .wf-pill,
 .plan-html-frame:not([data-render-mode="design"]) .wf-chip {
   display: inline-flex;
@@ -241,10 +245,18 @@
   background: var(--wf-accent-soft);
 }
 
-/* Once rough has drawn, hide the crisp borders so there's no doubling. Pills
-   keep their rounded crisp border (the rough overlay rounds them too). */
+/* Once rough has drawn, hide crisp borders only on elements rough.js actually
+   redraws. Broad helper containers keep theme-safe filled backgrounds and soft
+   borders so nested cards do not become a pile of overlapping sketch strokes. */
 .plan-html-frame[data-rough-ready]
-  :is(button, input, textarea, select, .wf-card, .wf-box, hr, [data-rough]) {
+  :is(
+    button,
+    input,
+    textarea,
+    select,
+    hr,
+    [data-rough]:not([data-rough="none"])
+  ) {
   border-color: transparent !important;
 }
 

package/corpus/templates/plan/app/components/plan/wireframe/kit/rough.tsx

@@ -6,10 +6,10 @@ import rough from "roughjs";
  *
  * The content is laid out with crisp flex/HTML (real labels, legible). The
  * hand-drawn look comes from rough.js: this overlay MEASURES the laid-out
- * elements (the kit's `[data-rough]` nodes, or — for HTML mockups — a broader
- * selector of bordered boxes) and redraws their outline as a hand-drawn stroke
- * into one SVG per frame. The element's own CSS border is hidden once we're
- * ready (`data-rough-ready`), so there is never a doubled border.
+ * elements (the kit's `[data-rough]` nodes, or — for HTML mockups — controls
+ * plus explicit `data-rough` opt-ins) and redraws their outline as a hand-drawn
+ * stroke into one SVG per frame. The element's own CSS border is hidden once
+ * we're ready (`data-rough-ready`), so there is never a doubled border.
  *
  * Crucially this works on ANY rendered DOM, not just the kit — which is what
  * lets HTML/Tailwind mockups get the same sketch treatment as the kit.
@@ -19,9 +19,9 @@ const gen = rough.generator();
 
 type RoughPath = { d: string; stroke: string; strokeWidth: number };
 
-/** The default selector used for HTML mockups: bordered/box-like elements. */
+/** The default selector used for HTML mockups: controls plus explicit opt-ins. */
 export const HTML_ROUGH_SELECTOR =
-  "[data-rough],button,input,textarea,select,.wf-card,.wf-box,hr,.wf-frame-target";
+  "[data-rough],button,input,textarea,select,hr";
 
 /** Stable per-element seed so a frame doesn't re-wobble on every measure. */
 function seedFrom(...parts: Array<string | number>): number {

package/corpus/templates/plan/app/components/plan/wireframe/sanitize-html.ts

@@ -91,8 +91,48 @@ function cssSafetyText(value: string): string {
     .replace(/[\u0000-\u0020]+/g, "");
 }
 
+type SanitizeElementOptions = {
+  stripRuntimeDirectives?: boolean;
+  stripWireframeThemeClasses?: boolean;
+};
+
+const TAILWIND_THEME_COLORS =
+  /^(?:bg|text|border|ring|outline|divide|placeholder|from|via|to|accent|caret|decoration|fill|stroke)-(?:inherit|current|transparent|black|white|slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)(?:-\d{2,3})?(?:\/[\d.]+)?$/;
+const TAILWIND_ARBITRARY_THEME_COLOR =
+  /^(?:bg|text|border|ring|outline|divide|placeholder|from|via|to|accent|caret|decoration|fill|stroke)-\[/;
+const TAILWIND_SHADOW = /^shadow(?:$|-)/;
+
+function baseClassName(className: string): string {
+  let bracketDepth = 0;
+  let lastVariantSeparator = -1;
+  for (let index = 0; index < className.length; index += 1) {
+    const char = className[index];
+    if (char === "[") bracketDepth += 1;
+    if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    if (char === ":" && bracketDepth === 0) lastVariantSeparator = index;
+  }
+  return className.slice(lastVariantSeparator + 1);
+}
+
+function isWireframeThemeClass(className: string): boolean {
+  const base = baseClassName(className);
+  return (
+    TAILWIND_THEME_COLORS.test(base) ||
+    TAILWIND_ARBITRARY_THEME_COLOR.test(base) ||
+    TAILWIND_SHADOW.test(base)
+  );
+}
+
+function stripWireframeThemeClasses(value: string): string {
+  return value
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((className) => !isWireframeThemeClass(className))
+    .join(" ");
+}
+
 /** Conservative no-DOM fallback for any non-browser code path (SSR). */
-function fallbackStrip(html: string): string {
+function fallbackStrip(html: string, options?: SanitizeElementOptions): string {
   // Drop the whole url attribute if its value (whitespace/control-stripped)
   // carries a dangerous scheme. Mirrors the DOM path for the rare no-DOMParser
   // case; entity-obfuscation isn't decoded here (the live DOM path handles it).
@@ -100,7 +140,7 @@ function fallbackStrip(html: string): string {
     const v = (dq ?? sq ?? uq ?? "").replace(/[\s\u0000-\u001f]+/g, "");
     return /^(?:javascript|vbscript):|^data:text\/html/i.test(v) ? "" : m;
   };
-  return html
+  let out = html
     .replace(
       /<\/?(?:script|style|iframe|object|embed|link|meta|base|form|noscript|frame|frameset|applet|marquee|portal)\b[^>]*>/gi,
       "",
@@ -113,16 +153,32 @@ function fallbackStrip(html: string): string {
     .replace(/\sstyle\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, (m) =>
       DANGEROUS_STYLE.test(m) ? "" : m,
     );
+  if (options?.stripWireframeThemeClasses) {
+    out = out.replace(
+      /\sclass\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi,
+      (_match, doubleQuoted, singleQuoted, bare) => {
+        const next = stripWireframeThemeClasses(
+          doubleQuoted ?? singleQuoted ?? bare ?? "",
+        );
+        return next ? ` class="${next}"` : "";
+      },
+    );
+  }
+  return out;
 }
 
-export function sanitizeWireframeHtml(html: string | undefined): string {
+export function sanitizeWireframeHtml(
+  html: string | undefined,
+  options?: { preserveThemeClasses?: boolean },
+): string {
   if (!html) return "";
+  const stripWireframeThemeClasses = !options?.preserveThemeClasses;
   if (typeof DOMParser === "undefined" || typeof document === "undefined") {
-    return fallbackStrip(html);
+    return fallbackStrip(html, { stripWireframeThemeClasses });
   }
   const doc = new DOMParser().parseFromString(html, "text/html");
   doc.querySelectorAll(BLOCKED_TAGS).forEach((el) => el.remove());
-  sanitizeElementAttributes(doc.body);
+  sanitizeElementAttributes(doc.body, { stripWireframeThemeClasses });
   return doc.body.innerHTML;
 }
 
@@ -242,7 +298,7 @@ function splitSelectorList(selectors: string): string[] {
 
 function sanitizeElementAttributes(
   root: ParentNode,
-  options?: { stripRuntimeDirectives?: boolean },
+  options?: SanitizeElementOptions,
 ) {
   root.querySelectorAll<HTMLElement>("*").forEach((el) => {
     for (const attr of Array.from(el.attributes)) {
@@ -269,6 +325,15 @@ function sanitizeElementAttributes(
       }
       if (name === "style" && DANGEROUS_STYLE.test(attr.value)) {
         el.removeAttribute(attr.name);
+        continue;
+      }
+      if (name === "class" && options?.stripWireframeThemeClasses) {
+        const next = stripWireframeThemeClasses(attr.value);
+        if (next) {
+          el.setAttribute(attr.name, next);
+        } else {
+          el.removeAttribute(attr.name);
+        }
       }
     }
     if (el instanceof HTMLTemplateElement) {