@agent-native/core 0.82.0 → 0.84.0

package/corpus/templates/design/changelog/2026-06-30-the-design-editor-loading-skeleton-is-simpler-and-its-bottom.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-30
+---
+
+The Design editor loading skeleton is simpler and its bottom toolbar uses one consistent surface.

package/corpus/templates/design/changelog/2026-06-30-the-design-editor-loading-skeleton-now-follows-the-current-t.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The design editor loading skeleton now follows the current theme while designs load.

package/corpus/templates/design/changelog/2026-06-30-the-design-inspector-no-longer-shows-child-layout-controls-o.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The Design inspector no longer shows child layout controls for empty layers or conversion prompts in Auto layout.

package/corpus/templates/design/changelog/2026-06-30-the-design-inspector-no-longer-shows-the-ask-ai-section-abov.md

@@ -0,0 +1,6 @@
+---
+type: removed
+date: 2026-06-30
+---
+
+The design inspector no longer shows the Ask AI section above Export.

package/corpus/templates/design/changelog/2026-06-30-the-design-review-panel-no-longer-shows-a-separate-inline-au.md

@@ -0,0 +1,6 @@
+---
+type: removed
+date: 2026-06-30
+---
+
+The Design review panel no longer shows a separate inline audit run button.

package/corpus/templates/design/changelog/2026-06-30-the-empty-designs-page-now-focuses-on-a-single-primary-new-d.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-30
+---
+
+The empty Designs page now focuses on a single primary New Design action.

package/corpus/templates/design/changelog/2026-06-30-the-layers-panel-header-stays-as-layers-while-multiple-items.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The Layers panel header stays as Layers while multiple items are selected.

package/corpus/templates/design/changelog/2026-06-30-the-missing-design-screen-now-uses-a-neutral-back-button.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The missing design screen now uses a neutral back button.

package/corpus/templates/design/changelog/2026-06-30-the-motion-timeline-now-closes-without-squeezing-the-canvas-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The motion timeline now closes without squeezing the canvas and saves animation edits with lighter responses.

package/corpus/templates/design/changelog/2026-06-30-the-new-design-connect-ai-setup-now-lines-up-with-the-compos.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The new-design Connect AI setup now lines up with the composer and keeps its actions compact.

package/corpus/templates/design/changelog/2026-06-30-the-screen-overview-board-now-blends-into-the-canvas-and-new.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+The screen overview board now blends into the canvas and new rectangles use neutral gray defaults.

package/corpus/templates/design/changelog/2026-06-30-top-level-canvas-drops-now-show-screen-guides.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+Top-level canvas layers now show screen drop guides before moving into a screen.

package/corpus/templates/design/changelog/2026-06-30-top-level-canvas-layers-now-keep-a-transparent-backdrop-and-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+Top-level canvas layers now keep a transparent backdrop and drop into screens reliably.

package/corpus/templates/design/changelog/2026-06-30-top-level-canvas-layers-now-select-reliably-from-all-screens.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-30
+---
+
+Top-level canvas layers now select reliably from All screens.

package/corpus/templates/design/changelog/2026-06-30-visual-edit-can-open-and-refresh-localhost-screens-in-one-au.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-30
+---
+
+Visual edit can open and refresh localhost screens in one authenticated step for faster chat-driven canvas updates.

package/corpus/templates/design/e2e/helpers.ts

@@ -174,10 +174,21 @@ async function waitForDesignBridgeReady(page: Page): Promise<void> {
   // Wait for the iframe bridge to stamp at least one selectable node.
   await expect
     .poll(
-      async () =>
-        designFrame(page)
-          .locator("[data-agent-native-node-id], h1, h2, p, button")
-          .count(),
+      async () => {
+        const previewIframes = await page
+          .locator(DESIGN_PREVIEW_IFRAME_SELECTOR)
+          .elementHandles();
+        let selectableNodeCount = 0;
+        for (const iframe of previewIframes) {
+          const frame = await iframe.contentFrame();
+          if (!frame) continue;
+          selectableNodeCount += await frame
+            .locator("[data-agent-native-node-id], h1, h2, p, button")
+            .count()
+            .catch(() => 0);
+        }
+        return selectableNodeCount;
+      },
       { timeout: 20_000 },
     )
     .toBeGreaterThan(0);

package/corpus/templates/design/server/db/index.ts

@@ -6,6 +6,56 @@ import * as schema from "./schema.js";
 export const getDb = createGetDb(schema);
 export { schema };
 
+function isLocalDevRuntime(): boolean {
+  return (
+    process.env.NODE_ENV !== "production" &&
+    !process.env.NETLIFY &&
+    !process.env.VERCEL &&
+    !process.env.AWS_LAMBDA_FUNCTION_NAME &&
+    !process.env.CF_PAGES
+  );
+}
+
+function isLoopbackHttpUrl(value: unknown): boolean {
+  if (typeof value !== "string" || !value.trim()) return false;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    const host = url.hostname.toLowerCase();
+    return (
+      host === "localhost" ||
+      host === "::1" ||
+      host === "[::1]" ||
+      /^127(?:\.\d{1,3}){3}$/.test(host)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isLoopbackLocalhostDesign(design: any): boolean {
+  if (!isLocalDevRuntime()) return false;
+  let data: any;
+  try {
+    data = typeof design?.data === "string" ? JSON.parse(design.data) : null;
+  } catch {
+    return false;
+  }
+  if (!data || data.sourceMode !== "localhost") return false;
+
+  const metadataEntries = Object.values(
+    data.localhostScreens ?? data.screenMetadata ?? {},
+  ) as any[];
+  if (metadataEntries.length === 0) return false;
+
+  return metadataEntries.every((entry) => {
+    if (!entry || entry.sourceType !== "localhost") return false;
+    const previewUrl = entry.previewUrl ?? entry.url;
+    if (!isLoopbackHttpUrl(previewUrl)) return false;
+    return !entry.bridgeUrl || isLoopbackHttpUrl(entry.bridgeUrl);
+  });
+}
+
 registerShareableResource({
   type: "design",
   resourceTable: schema.designs,
@@ -14,6 +64,8 @@ registerShareableResource({
   titleColumn: "title",
   getResourcePath: (design) => `/design/${design.id}`,
   getDb,
+  publicAccessRole: (design) =>
+    isLoopbackLocalhostDesign(design) ? "editor" : "viewer",
 });
 
 registerShareableResource({

package/corpus/templates/design/server/plugins/agent-chat.ts

@@ -15,6 +15,9 @@ const INITIAL_TOOL_NAMES = [
   "get-design",
   "get-design-snapshot",
   "create-design",
+  "open-visual-edit",
+  "add-localhost-screens",
+  "list-localhost-connections",
   "edit-design",
   "generate-design",
   "present-design-variants",
@@ -46,6 +49,8 @@ export default createAgentChatPlugin({
 
 When the user asks you to refine an existing design, call view-screen if the open design is unclear, then read the live current file with get-design-snapshot before editing. For small localized changes, call edit-design with exact search/replace edits. For broad copy-only changes such as translating all visible text, call edit-design in replace-file mode with the complete updated file content from the snapshot so the HTML structure, scripts, styles, and tweaks are preserved without dozens of fragile search blocks. Do not claim the design is updated until the mutating action succeeds.
 
+When the user asks to visually inspect or edit a running local app, use open-visual-edit. It registers the localhost bridge, creates or reuses the Design project, places URL-backed iframe screens, stores the active visual-edit context, and navigates to overview mode in one authenticated step. For follow-ups like adding a mobile viewport or another route state, reuse the current designId and connectionId and call open-visual-edit or add-localhost-screens with explicit routes/paths and viewport sizes.
+
 Provider-specific Design actions are shortcuts, not limits. If a first-class action cannot express the exact GitHub endpoint, repository tree query, code search, issue or pull request query, request body, pagination mode, payload shape, metadata field, or API version needed, call provider-api-catalog and provider-api-docs as needed, then call provider-api-request against the real GitHub API. Use the raw provider API escape hatch instead of weakening the answer or claiming Design cannot do something the underlying GitHub API can do.
 
 Design's GitHub provider API uses the saved GITHUB_TOKEN secret when present. Never ask the user to paste tokens into chat. For large GitHub search results or repository scans, pass stageAs and pagination options to provider-api-request, then use query-staged-dataset to count, filter, group, or project the staged rows.

package/corpus/templates/design/server/plugins/auth.ts

@@ -28,5 +28,6 @@ export default createAuthPlugin({
     "/api/design-handoff",
     "/__manifest",
     "/_agent-native/actions/get-design",
+    "/_agent-native/actions/list-design-native-assets",
   ],
 });

package/corpus/templates/design/server/plugins/core-routes.ts

@@ -16,4 +16,8 @@ export default createCoreRoutesPlugin({
     if (view === "editor") return "/";
     return null;
   },
+  allowUnauthenticatedOpen: ({ target }) => {
+    const path = target.split(/[?#]/, 1)[0] ?? "/";
+    return path.startsWith("/design/");
+  },
 });

package/corpus/templates/design/shared/board-file.ts

@@ -21,6 +21,9 @@ import type { BoardObjectEntry } from "./board-objects.js";
 /** Reserved filename for the board overlay file. */
 export const BOARD_FILENAME = "__board__.html";
 
+const DEFAULT_SHAPE_FILL = "rgb(218 218 218)";
+const DEFAULT_SHAPE_STROKE = "rgb(168 168 168)";
+
 // ---------------------------------------------------------------------------
 // isBoardFile
 // ---------------------------------------------------------------------------
@@ -54,7 +57,8 @@ export function emptyBoardHtml(): string {
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <style>
   *, *::before, *::after { box-sizing: border-box; }
-  body { margin: 0; position: relative; background: transparent; overflow: visible; }
+  html, body { background: transparent; }
+  body { margin: 0; position: relative; overflow: visible; }
 </style>
 </head>
 <body>
@@ -153,10 +157,10 @@ export function boardObjectEntryToHtmlFragment(
 
   // Ellipse kind uses a <div> with border-radius.
   if (kind === "ellipse") {
-    const bgColor = fill ?? "var(--primary, #2563eb)";
+    const bgColor = fill ?? DEFAULT_SHAPE_FILL;
     const borderStyle = stroke
       ? `border:${strokeWidth ?? 1}px solid ${stroke};`
-      : "";
+      : `border:1px solid ${DEFAULT_SHAPE_STROKE};`;
     const style = `${baseStyle};background:${bgColor};border-radius:50%;${borderStyle}`;
     return `<div style="${style}" ${dataAttrs}></div>`;
   }
@@ -170,10 +174,12 @@ export function boardObjectEntryToHtmlFragment(
 
   // Frame / rectangle / polygon / star / default — basic colored <div>.
   const bgColor =
-    fill ?? (kind === "frame" ? "transparent" : "var(--primary, #2563eb)");
+    fill ?? (kind === "frame" ? "transparent" : DEFAULT_SHAPE_FILL);
   const borderStyle = stroke
     ? `border:${strokeWidth ?? 1}px solid ${stroke};`
-    : "";
+    : kind === "frame"
+      ? ""
+      : `border:1px solid ${DEFAULT_SHAPE_STROKE};`;
   const style = `${baseStyle};background:${bgColor};${borderStyle}`;
 
   if (kind === "frame") {
@@ -212,6 +218,375 @@ function kindToLayerName(kind: BoardObjectEntry["kind"]): string {
   }
 }
 
+// ---------------------------------------------------------------------------
+// backfillBoardPrimitiveMarkers
+// ---------------------------------------------------------------------------
+
+/**
+ * Adds `data-an-primitive="<kind>"` to board primitive elements that are
+ * missing the marker.
+ *
+ * ## Scope
+ *
+ * Only elements that look like top-level board primitives are touched:
+ * - Must be a direct `<body>` child (depth-1 element)
+ * - Must carry `data-agent-native-node-id` (the bridge id stamp)
+ * - Must NOT already have `data-an-primitive`
+ *
+ * ## Kind inference (conservative)
+ *
+ * | Condition                                              | Inferred kind |
+ * |--------------------------------------------------------|---------------|
+ * | `<svg>` whose path carries `marker-end`                | `"arrow"`     |
+ * | `<svg>` containing a `<polygon>`                        | `"polygon"`   |
+ * | `<svg>` containing exactly one `<path>` and no other shape | `"path"`  |
+ * | `<svg>` with no reliable vector signal                  | *(skip — left unmarked, still classifies as a generic shape via tag)* |
+ * | Inline style contains `border-radius:50%`              | `"ellipse"`   |
+ * | Inline style contains `background:transparent` or no background, but has `data-agent-native-layer-name` starting with "Frame" | `"frame"` |
+ * | Element has non-empty text content and no background color in style | `"text"` |
+ * | Otherwise                                              | `"rectangle"` |
+ *
+ * The function is:
+ * - **Pure** — returns a new string, never mutates.
+ * - **Additive** — only inserts `data-an-primitive`; never alters geometry,
+ *   structure, or any other attributes.
+ * - **Idempotent** — if the marker is already present on an element, that
+ *   element is skipped.
+ *
+ * The implementation uses string-level parsing to remain dependency-free
+ * (no DOM parser, no JSDOM).  It is intentionally conservative: when in doubt,
+ * an element is left as-is rather than mis-classified.
+ */
+export function backfillBoardPrimitiveMarkers(html: string): string {
+  // Quick exit: if every node-id-bearing element already has the marker we
+  // have nothing to do.
+  if (!html.includes("data-agent-native-node-id=")) return html;
+
+  // We need to find direct <body> children only.  We walk the raw HTML string
+  // looking for the opening of the <body> element, then iterate sibling-level
+  // opening tags until </body>.
+
+  const bodyStart = html.indexOf("<body");
+  if (bodyStart === -1) return html;
+  const bodyTagEnd = html.indexOf(">", bodyStart);
+  if (bodyTagEnd === -1) return html;
+
+  const bodyClose = html.lastIndexOf("</body>");
+  if (bodyClose === -1) return html;
+
+  // The direct-child region.
+  const before = html.slice(0, bodyTagEnd + 1);
+  const children = html.slice(bodyTagEnd + 1, bodyClose);
+  const after = html.slice(bodyClose);
+
+  const patched = _patchDirectChildren(children);
+  if (patched === children) return html; // nothing changed
+  return before + patched + after;
+}
+
+/**
+ * Walk the HTML fragment that represents the direct children of <body> and
+ * insert `data-an-primitive` on qualifying elements that lack it.
+ *
+ * We do NOT recurse into children — only sibling-level (depth-1) tags are
+ * touched.
+ */
+function _patchDirectChildren(fragment: string): string {
+  let result = "";
+  let pos = 0;
+
+  while (pos < fragment.length) {
+    // Find the next '<'.
+    const tagStart = fragment.indexOf("<", pos);
+    if (tagStart === -1) {
+      result += fragment.slice(pos);
+      break;
+    }
+
+    // Copy any text / whitespace before this tag verbatim.
+    result += fragment.slice(pos, tagStart);
+    pos = tagStart;
+
+    // Peek: is this a comment, closing tag, or doctype?  Copy verbatim.
+    const rest = fragment.slice(pos);
+    if (
+      rest.startsWith("<!--") ||
+      rest.startsWith("</") ||
+      rest.startsWith("<!") ||
+      rest.startsWith("<?")
+    ) {
+      const end = fragment.indexOf(">", pos);
+      if (end === -1) {
+        result += fragment.slice(pos);
+        pos = fragment.length;
+      } else {
+        result += fragment.slice(pos, end + 1);
+        pos = end + 1;
+      }
+      continue;
+    }
+
+    // Find the end of this opening tag (handling quoted attributes).
+    const tagEnd = _findTagEnd(fragment, pos);
+    if (tagEnd === -1) {
+      // Malformed — copy rest verbatim.
+      result += fragment.slice(pos);
+      break;
+    }
+
+    const openTag = fragment.slice(pos, tagEnd + 1);
+
+    // Skip the tag body + nested content and get to the matching close tag so
+    // we can copy the whole element and move past it.
+    // We need the tag name first.
+    const tagNameMatch = openTag.match(/^<([a-zA-Z][a-zA-Z0-9-]*)/);
+    if (!tagNameMatch) {
+      // Not an element tag — copy verbatim and advance.
+      result += openTag;
+      pos = tagEnd + 1;
+      continue;
+    }
+    const tagName = tagNameMatch[1].toLowerCase();
+
+    // SVG elements: vector primitives (line/path/arrow/polygon/star) render as
+    // <svg>.  When the marker is missing we conservatively infer the kind from
+    // the SVG's inner geometry so the layers panel shows the right vector icon
+    // instead of the generic shape glyph.  Geometry is never altered — only the
+    // marker attribute is inserted on the opening <svg> tag.
+    if (tagName === "svg") {
+      const closeTag = `</svg>`;
+      const closeIdx = fragment.indexOf(closeTag, tagEnd + 1);
+      if (closeIdx === -1) {
+        result += fragment.slice(pos);
+        pos = fragment.length;
+        continue;
+      }
+      const inner = fragment.slice(tagEnd + 1, closeIdx);
+      const shouldPatchSvg =
+        openTag.includes("data-agent-native-node-id=") &&
+        !openTag.includes("data-an-primitive=");
+      let patchedSvgOpenTag = openTag;
+      if (shouldPatchSvg) {
+        const kind = _inferSvgPrimitiveKind(inner);
+        if (kind) {
+          patchedSvgOpenTag = openTag.replace(
+            /(\s*\/?>)$/,
+            ` data-an-primitive="${kind}"$1`,
+          );
+        }
+      }
+      result += patchedSvgOpenTag + inner + closeTag;
+      pos = closeIdx + closeTag.length;
+      continue;
+    }
+
+    // For all other elements: decide whether to patch.
+    const shouldPatch =
+      openTag.includes("data-agent-native-node-id=") &&
+      !openTag.includes("data-an-primitive=");
+
+    let patchedOpenTag = openTag;
+    if (shouldPatch) {
+      const kind = _inferPrimitiveKind(openTag);
+      // Insert marker just before the closing `>` or `/>` of the opening tag.
+      patchedOpenTag = openTag.replace(
+        /(\s*\/?>)$/,
+        ` data-an-primitive="${kind}"$1`,
+      );
+    }
+
+    // Find the matching close tag (skip self-closing tags).
+    const isSelfClosing = openTag.endsWith("/>") || VOID_ELEMENTS.has(tagName);
+    if (isSelfClosing) {
+      result += patchedOpenTag;
+      pos = tagEnd + 1;
+      continue;
+    }
+
+    const closeTag = `</${tagName}>`;
+    const closeIdx = _findMatchingClose(fragment, tagEnd + 1, tagName);
+    if (closeIdx === -1) {
+      // Unmatched open tag — copy rest verbatim.
+      result += patchedOpenTag + fragment.slice(tagEnd + 1);
+      pos = fragment.length;
+      continue;
+    }
+
+    const innerContent = fragment.slice(tagEnd + 1, closeIdx);
+    result += patchedOpenTag + innerContent + closeTag;
+    pos = closeIdx + closeTag.length;
+  }
+
+  return result;
+}
+
+/** Void elements that have no closing tag. */
+const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+/**
+ * Find the index of the `>` that closes the opening tag starting at `start`
+ * in `html`, skipping over quoted attribute values.
+ */
+function _findTagEnd(html: string, start: number): number {
+  let i = start + 1; // Skip '<'
+  while (i < html.length) {
+    const ch = html[i];
+    if (ch === ">") return i;
+    if (ch === '"' || ch === "'") {
+      // Skip quoted attribute value.
+      const quote = ch;
+      i++;
+      while (i < html.length && html[i] !== quote) i++;
+      if (i < html.length) i++; // skip closing quote
+      continue;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Find the index of the matching `</tagName>` for an element whose opening tag
+ * ended at `afterOpen`.  Handles nesting by counting open/close pairs.
+ */
+function _findMatchingClose(
+  html: string,
+  afterOpen: number,
+  tagName: string,
+): number {
+  const openRe = new RegExp(`<${tagName}[\\s/>]`, "gi");
+  const closeTag = `</${tagName}>`;
+  let depth = 1;
+  let pos = afterOpen;
+
+  while (pos < html.length && depth > 0) {
+    // Find the next candidate: open or close tag.
+    openRe.lastIndex = pos;
+    const nextOpen = openRe.exec(html);
+    const nextClose = html.indexOf(closeTag, pos);
+
+    if (nextClose === -1) return -1; // unmatched
+
+    if (nextOpen && nextOpen.index < nextClose) {
+      depth++;
+      pos = nextOpen.index + nextOpen[0].length;
+    } else {
+      depth--;
+      if (depth === 0) return nextClose;
+      pos = nextClose + closeTag.length;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Infer the `data-an-primitive` kind value for a board element whose opening
+ * tag is `openTag` and which is known to lack the marker.
+ *
+ * Inference is conservative — only clear signals produce a non-"rectangle"
+ * kind.
+ */
+function _inferPrimitiveKind(openTag: string): string {
+  // Extract the inline style value (first style="..." attribute).
+  const styleMatch = openTag.match(/\bstyle="([^"]*)"/i);
+  const style = styleMatch ? styleMatch[1] : "";
+
+  // Ellipse: CSS border-radius:50% (or border-radius: 50%).
+  if (/border-radius\s*:\s*50%/.test(style)) {
+    return "ellipse";
+  }
+
+  // Frame: transparent background.
+  if (/background\s*:\s*transparent/.test(style)) {
+    return "frame";
+  }
+
+  // Extract the layer name for additional hints.
+  const layerNameMatch = openTag.match(
+    /\bdata-agent-native-layer-name="([^"]*)"/i,
+  );
+  const layerName = layerNameMatch ? layerNameMatch[1] : "";
+
+  // Frame: layer name starts with "Frame".
+  if (/^frame/i.test(layerName)) {
+    return "frame";
+  }
+
+  // Text: the element has no background-color-like value in the style, yet has
+  // a color property — we detect this via the presence of "color:" without a
+  // "background:" in the style.  Also check for the white-space:pre-wrap
+  // pattern that text nodes emit.
+  if (
+    /white-space\s*:\s*pre-wrap/.test(style) ||
+    (/\bcolor\s*:/.test(style) && !/\bbackground\s*:/.test(style))
+  ) {
+    return "text";
+  }
+
+  // Default: rectangle.
+  return "rectangle";
+}
+
+/**
+ * Infer the `data-an-primitive` kind value for a marker-less board `<svg>`
+ * primitive from its inner geometry.  Returns `null` when no reliable signal
+ * is present, in which case the SVG is left unmarked (it still classifies as a
+ * generic shape via tag heuristics) rather than mis-classified.
+ *
+ * Conservative signals (in priority order):
+ * - The path carries `marker-end` (the arrowhead reference)  → `"arrow"`
+ * - The SVG contains a `<polygon>` element                   → `"polygon"`
+ * - The SVG contains exactly a single `<path>` and nothing
+ *   else shape-like                                          → `"path"`
+ *
+ * Geometry (points, path data, polygon points) is never inspected for sizing
+ * and never altered — only the presence/type of child elements is consulted.
+ */
+function _inferSvgPrimitiveKind(inner: string): string | null {
+  // Arrow: a path with a marker-end reference (the arrowhead).  The arrowhead
+  // marker itself lives in <defs> as a separate path, so detect the consuming
+  // `marker-end="url(...)"` attribute rather than the marker definition.
+  if (/marker-end\s*=/.test(inner)) {
+    return "arrow";
+  }
+
+  // Polygon / star: rendered with a <polygon> element.  Both kinds use the same
+  // SVG element, so we conservatively report "polygon" (star geometry is a
+  // polygon at the markup level and cannot be distinguished without sizing).
+  if (/<polygon\b/i.test(inner)) {
+    return "polygon";
+  }
+
+  // Pen-tool vector: a single <path> and no other shape elements.
+  const pathCount = (inner.match(/<path\b/gi) ?? []).length;
+  const hasOtherShape = /<(rect|circle|ellipse|line|polyline)\b/i.test(inner);
+  if (pathCount === 1 && !hasOtherShape) {
+    return "path";
+  }
+
+  // No reliable signal — leave unmarked.
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
 function escapeAttr(value: string): string {
   return value
     .replace(/&/g, "&amp;")