@agent-native/core 0.79.26 → 0.80.0

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

@@ -125,11 +125,17 @@ function normalizeSourcePath(filePath: string): string | null {
 export function isContentSourcePath(filePath: string): boolean {
   const normalized = normalizeSourcePath(filePath);
   if (!normalized) return false;
+  if (isBuilderMdxSourcePath(normalized)) return false;
   return CONTENT_SOURCE_EXTENSIONS.some((ext) =>
     normalized.toLowerCase().endsWith(ext),
   );
 }
 
+export function isBuilderMdxSourcePath(filePath: string): boolean {
+  const normalized = normalizeSourcePath(filePath);
+  return !!normalized && normalized.toLowerCase().endsWith(".builder.mdx");
+}
+
 export function isValidContentSourceId(id: string | null | undefined): boolean {
   return !!id && VALID_SOURCE_ID_RE.test(id);
 }

package/corpus/templates/content/shared/nfm-registry.ts

@@ -34,6 +34,7 @@ import {
   type SerializableBlock,
 } from "@agent-native/core/blocks/server";
 
+import { builderDocsBlockConfigs } from "./builder-docs-blocks";
 import { inlineDatabaseBlockConfig } from "./inline-database-block";
 
 /**
@@ -58,6 +59,9 @@ export function registerContentBlocks(registry: BlockRegistry): void {
   registerLibraryBlockConfigs(registry, {
     overrides: { table: { type: "table-block" } },
   });
+  for (const block of builderDocsBlockConfigs) {
+    registry.register(block);
+  }
   registry.register(inlineDatabaseBlockConfig);
 }
 

package/corpus/templates/content/vite.config.ts

@@ -31,6 +31,8 @@ const LOCAL_COMPONENTS_STUB_IMPORTS = new Set([
   "./local-components.generated.ts",
 ]);
 const COMPONENT_EXTENSIONS = new Set([".tsx", ".jsx", ".ts", ".js"]);
+const ALLOW_PRODUCTION_LOCAL_FILES_ENV =
+  "AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION";
 const CONTENT_LOCAL_DEFAULTS: LocalArtifactOptions["defaults"] = {
   roots: [
     { name: "Docs", path: "docs", kind: "docs", extensions: [".md", ".mdx"] },
@@ -64,6 +66,14 @@ function envManifestPath() {
   );
 }
 
+function localFilesAllowedForBuild() {
+  if (process.env.NODE_ENV !== "production") return true;
+  const value = process.env[ALLOW_PRODUCTION_LOCAL_FILES_ENV]
+    ?.trim()
+    .toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
 function localWorkspaceRootSync() {
   const manifestPath = envManifestPath() || findAgentNativeManifest();
   if (!manifestPath) return null;
@@ -339,6 +349,9 @@ function contentLocalComponentsPlugin(): Plugin {
     },
     async load(id) {
       if (id !== RESOLVED_LOCAL_COMPONENTS_MODULE_ID) return null;
+      if (!localFilesAllowedForBuild()) {
+        return renderLocalComponentsModule([]);
+      }
       return renderLocalComponentsModule(await loadLocalComponentFiles());
     },
   };

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: visual-edit
+description: >-
+  Open a running local app in Design overview mode as URL-backed iframe screens
+  for visual editing, flow review, duplication, and route-state exploration.
+metadata:
+  visibility: exported
+---
+
+# Visual Edit
+
+Use `/visual-edit` when the user wants to inspect or edit a real local app
+visually instead of generating standalone Alpine HTML. The source of truth is
+the running localhost app plus its route URLs. Design shows those routes as
+iframe-backed screens on the infinite canvas.
+
+## Core Model
+
+- Each screen is a URL-backed iframe, not copied HTML.
+- Each screen keeps its own URL metadata: `connectionId`, `routeId`, `path`,
+  `url`, `bridgeUrl`, title, and viewport size.
+- Start in Design's screen overview mode. The user can edit/select/drop on any
+  visible screen from the overview canvas.
+- In overview, screens are static like Figma frames: no iframe scrolling or app
+  interaction. Full-screen focus is for scrolling and app interaction.
+- Alt-drag duplicates a screen. For localhost screens, duplication copies the
+  iframe frame and URL metadata; change the copy's path/query when you need a
+  new flow state.
+- Flow visualization is just multiple URL states: `/checkout?step=shipping`,
+  `/checkout?step=payment`, `/checkout?step=done`, etc.
+
+## Required Local Bridge
+
+From the target app repo, make sure its dev server is running, then run the
+Design bridge with `npx`:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+```
+
+Use the app's real port. The command starts a local bridge on
+`http://127.0.0.1:7331` by default and exposes:
+
+- `GET /manifest.json` — dev server URL, bridge URL, discovered routes, root.
+- `GET /routes.json` — route manifest only.
+- `GET /health` — bridge liveness.
+
+For one-shot agent setup, ask for JSON and keep the long-running bridge open in
+a second terminal if the user needs live updates:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+```
+
+## Action Flow
+
+1. Register or refresh the bridge in Design:
+
+```bash
+pnpm action connect-localhost '{
+  "devServerUrl": "http://localhost:5173",
+  "bridgeUrl": "http://127.0.0.1:7331",
+  "rootPath": ".",
+  "routeManifest": { "version": 1, "sourceType": "localhost", "routes": [] }
+}'
+```
+
+Prefer passing the actual `/manifest.json` result as `routeManifest` and
+`capabilities`. Keep any local filesystem paths out of user-facing summaries
+unless the user asks.
+
+2. Create or reuse a Design project:
+
+```bash
+pnpm action create-design --title "Local app visual edit" --projectType prototype
+```
+
+3. Place URL-backed screens on the overview canvas:
+
+```bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "connectionId": "<connection-id>",
+  "routes": [
+    { "path": "/", "title": "Home", "width": 1280, "height": 900 },
+    { "path": "/pricing", "title": "Pricing", "width": 1280, "height": 900 },
+    { "path": "/checkout?step=payment", "title": "Checkout payment", "width": 1280, "height": 900 }
+  ],
+  "startX": 0,
+  "startY": 0,
+  "gap": 160
+}'
+```
+
+If no `routes` or `paths` are supplied, `add-localhost-screens` uses every route
+from the latest localhost manifest. Use `paths` for a concise flow:
+
+```bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "paths": ["/", "/pricing", "/checkout?step=payment"]
+}'
+```
+
+4. Navigate the user to overview mode:
+
+```bash
+pnpm action navigate --view editor --designId "<design-id>" --editorView overview
+```
+
+## Editing URLs
+
+To change a localhost screen's URL, update that screen through
+`add-localhost-screens` again using the same route-derived filename/path or use
+normal Design screen duplication followed by a route/path update. Keep the file
+content as the absolute URL and keep `screenMetadata[fileId]` aligned:
+
+```json
+{
+  "sourceType": "localhost",
+  "previewState": "live",
+  "url": "http://localhost:5173/checkout?step=done",
+  "previewUrl": "http://localhost:5173/checkout?step=done",
+  "path": "/checkout?step=done"
+}
+```
+
+Do not replace localhost screens with copied `srcdoc` HTML unless the user
+explicitly asks to freeze a snapshot.
+
+## Verification
+
+- `list-localhost-connections` returns the expected connection and routes.
+- The Design editor opens in overview mode.
+- Every requested screen renders the intended localhost URL.
+- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
+- A query/path edit changes only the target screen's URL metadata and iframe.

package/corpus/templates/design/AGENTS.md

@@ -50,6 +50,19 @@ patterns live in `.agents/skills/`.
   is backed by a CSS custom property the rendered file actually uses. If source
   edits are needed, use `get-design-snapshot` first and persist the complete
   updated tweak definition list through `generate-design`.
+- Design editor extensions render in the right inspector slot
+  `design.editor.inspector`. When creating an extension for that panel, call
+  `create-extension`, then `add-extension-slot-target` with that slot id, then
+  `install-extension` so it appears inline. Extensions receive
+  `window.slotContext` with the current design id, active screen, selected
+  element, zoom, mode, tool, and tweak values. For AI-driven style/artboard
+  changes, extension HTML should call `agentNative.chat.send(...)` with the
+  selected element selector/sourceId and request; the agent should call
+  `view-screen` first, prefer `apply-visual-edit` for element style/class/text
+  changes, and use `update-design` or `generate-design` with `canvasFrames` for
+  overview artboard placement changes. If creating the extension opens the
+  standalone extension editor, return to the same design with `navigate` and
+  `inspectorTab: "extensions"` after installing it.
 - Follow linked design-system tokens and `customInstructions` whenever present;
   explicit user instructions in the current turn still win.
 - Persist useful work early: create/update the design and files as soon as a
@@ -57,31 +70,108 @@ patterns live in `.agents/skills/`.
 - For non-trivial new design prompts, ask before generating: create/open the
   design shell, call `show-design-questions`, stop while the main canvas shows
   the questions, then continue from the user's answers.
+- For multiple screens/states, call `generate-screens` first. It opens the
+  infinite screen overview and returns target filenames plus `canvasFrame`
+  placements. Then call `generate-design` with those files and pass the matching
+  `canvasFrames` entries so screens appear in the overview instead of only in
+  the file list.
+- After generation or broad updates, leave the user in the screen overview when
+  the work involves multiple screens or artboard placement. Overview is the
+  primary editing surface: users can select screens, move/resize/drop static
+  frames and canvas primitives, edit layers in place, and use the frame's
+  full-view button to enter focused editing.
+- To move the user's editor, call `navigate` with `view: "editor"` and
+  `editorView: "overview"` for the screen overview, or `editorView: "single"`
+  plus `fileId`, `filename`, or `screen` to focus one screen.
+- Single-screen mode is for scrolling, interacting with prototype behavior, and
+  editing the DOM/code layers inside one screen. Do not use it as the default
+  landing mode for multi-screen generation unless the user asks to focus a
+  specific screen.
+- The layers panel shows screens as top-level frames and nests DOM/code layers
+  beneath the active screen. Rename DOM/code layers by safely editing source to
+  set `data-agent-native-layer-name`; this is the stable human-readable layer
+  name. `data-code-layer-id` and similar ids are for selection stability, not
+  display naming.
+- For inline/Alpine screens, stamp and preserve unique
+  `data-agent-native-node-id` attributes on selectable DOM nodes. Treat
+  generated CSS selectors as a compatibility fallback only. For localhost React
+  screens, resolve through build-time source/debug metadata (stable generated
+  ids, component name, file, and line) before falling back to selectors.
 - For multi-variant work, write candidates incrementally so the UI can preview
   progress. External MCP hosts should use `present-design-variants` so the same
   picker opens inline instead of writing `application_state` directly.
 - Use framework sharing actions for design and design-system visibility/grants.
 - When the user asks to download/export, use export actions or point to the
   editor download menu.
+- Design source modes are `inline`, `localhost`, and `fusion`. Inline is the
+  current SQL-backed prototype mode. Localhost connections come from
+  `npx @agent-native/core@latest design connect` and are persisted with
+  `connect-localhost`; list them with `list-localhost-connections` before
+  creating or resolving local-code artboards. Fusion is a future source type and
+  should be preserved when present but not invented for inline/local work.
+- Localhost route manifests are scaffolding for URL-backed Flow Canvas
+  artboards. Use `add-localhost-screens` to place routes or path/query states as
+  iframe screens in overview mode. Preserve route ids, paths, `sourceType`,
+  bridge URL, and snapshot/state references when moving between actions so later
+  flow-edge derivation has stable anchors.
 
 ## Application State
 
 - `navigation` tells you the current view, design id, file id, and related UI
   state.
 - `navigate` moves the UI and is auto-deleted after the client consumes it.
+- `design-selection` includes active screen, selected element, overview mode,
+  inspector tab, zoom, and screen list for the current tab.
+- `design-generation-session:<designId>` contains visible multi-screen
+  generation frames created by `generate-screens`.
 - `show-design-questions` opens focused pre-generation questions in the main
   design canvas (`show-questions` application state).
 - `design-variants` contains in-progress candidates for the variant picker.
 
+## Code Layers
+
+- `get-code-layer-projection` reads inline HTML/JSX and returns selectable layer
+  nodes, selectors, names, and edit intents for agent and UI workflows.
+- `apply-visual-edit` supports deterministic local edits for HTML-backed code
+  layers: text, classes, styles, attributes, source order, and small structural
+  changes. Use it for selected-element edits before falling back to full
+  `update-design` / `generate-design` rewrites.
+- Prefer `data-agent-native-layer-name="Readable name"` on meaningful elements.
+  The projection uses it before semantic/text fallbacks, and layer renames should
+  persist by updating that attribute.
+- Current limitation: visual code-layer edits are HTML-only. Localhost source
+  mode can list and resolve local routes now, but file reads/writes remain a
+  bridge contract until explicit permission controls are hardened.
+
+## Localhost Source Actions
+
+- `connect-localhost`: registers or refreshes a localhost source connection
+  emitted by `npx @agent-native/core@latest design connect`. Pass
+  `devServerUrl`, optional `bridgeUrl`, optional `rootPath`, and either `routes`
+  or a full `routeManifest`.
+- `list-localhost-connections`: lists the current user's saved localhost
+  connections and route manifests. Use this before referring to local-code
+  artboards.
+- `add-localhost-screens`: creates or refreshes URL-backed iframe screens from
+  the latest localhost connection or a specific `connectionId`. Pass `routes`
+  with `path`/`url` when visualizing a flow; pass `paths` for a concise route
+  list. Then call `navigate --view editor --designId <id> --editorView overview`.
+
 ## App-Backed Skill Distribution
 
 - The preferred hosted install path is
-  `npx @agent-native/core@latest skills add design-exploration` (or `design`).
-  It installs the exported Design exploration instructions and registers the
-  hosted Design MCP connector together.
+  `npx @agent-native/core@latest skills add design-exploration`,
+  `npx @agent-native/core@latest skills add visual-edit`, or `design` for the
+  full Design bundle. It installs the exported Design instructions and registers
+  the hosted Design MCP connector together.
 - The open Skills CLI path
-  `npx skills@latest add BuilderIO/agent-native --skill design-exploration` installs
-  the exported instructions only.
+  `npx skills@latest add BuilderIO/agent-native --skill visual-edit` installs
+  exported instructions only.
+- For local-code visual editing, `/visual-edit` should run the target app dev
+  server, run
+  `npx @agent-native/core@latest design connect --url http://localhost:<port> --root .`,
+  register that manifest with `connect-localhost`, call `add-localhost-screens`,
+  and open the editor in overview mode.
 - For human-in-the-loop UI exploration, create a design shell, call
   `present-design-variants` with 2-5 complete HTML directions (three by
   default), wait for the user to pick one, then use `get-design-snapshot` and

package/corpus/templates/design/DESIGN.md

@@ -0,0 +1,82 @@
+# Design System Contract
+
+This file is the source-control scaffold for Design projects that point at real
+code. The app can keep inline prototypes in SQL today, connect to localhost next,
+and later blend hosted/fusion sources without changing the artboard model.
+
+## Editor Contract
+
+Design is overview-first for multi-screen work. Generation and broad updates
+should land in the screen overview: an infinite canvas where each screen is a
+static frame that can be selected, moved, resized, dropped, or duplicated.
+Use the frame's full-view button when a screen needs focused scrolling or
+prototype interaction.
+
+Single-screen mode is the scroll/interact/edit surface for one rendered file. It
+is where prototype behavior runs, iframe scrolling happens, and local DOM/code
+layer edits are applied.
+
+The layers panel mirrors that model: screens are top-level frames, with nested
+DOM/code layers for the active screen. Stable human-readable layer names should
+be stored in `data-agent-native-layer-name`; selector ids such as
+`data-code-layer-id` remain implementation anchors.
+
+## Source Modes
+
+- `inline`: the current SQL-backed Design files and deterministic HTML swaps.
+- `localhost`: a running app dev server exposed through
+  `npx @agent-native/core@latest design connect`.
+- `fusion`: future hosted or hybrid sources that can provide snapshots and code
+  context through the same bridge contract.
+
+Every artboard should carry `sourceType`, a source descriptor, stable route/path
+identity, and a snapshot reference when available. Flow edges should be durable
+objects even when they are derived later from captured state.
+
+## Localhost Bridge
+
+Run this from the app/repo root while the app dev server is running:
+
+```bash
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+```
+
+The command starts a local bridge and prints a manifest URL. It also creates
+`.agent-native/design-routes.json` only when that file does not already exist.
+That manifest is non-authoritative scaffolding; the live bridge response and the
+Design `connect-localhost` action are the durable app contract.
+
+For agent-launched visual editing, install or invoke `/visual-edit`. The skill
+registers the bridge with `connect-localhost`, uses `add-localhost-screens` to
+place each route or path/query state as a URL-backed iframe screen, then
+navigates the editor to overview mode. Keep these screens as URL sources; do not
+copy localhost HTML into inline files unless intentionally freezing a snapshot.
+
+Current bridge operations:
+
+- `select`
+- `resolveNodeToFile`
+- `readFile`
+- `applyEdit`
+- `writeFile`
+- `captureSnapshot`
+- `captureState`
+
+`select`, route listing, and capture contracts are foundations now. Local file
+reads/writes and LLM-backed instructions remain planned until the bridge has
+permission hardening and explicit user controls.
+
+## Code-Layer Editing
+
+Inline HTML supports local code-layer projection and deterministic visual edits:
+text, classes, styles, attributes, source order, and small structural changes.
+`data-agent-native-layer-name` is the preferred naming surface because renames
+can persist as safe source edits without changing selection ids.
+Use durable `data-agent-native-node-id` values for Alpine/inline HTML whenever a
+layer may be selected, reordered, duplicated, or patched; CSS selectors are only
+a fallback. React/localhost targets should prefer build-time source metadata
+(component/file/line and generated stable ids) over DOM path selectors.
+
+Current limitation: visual code-layer edits only support HTML files. Localhost
+artboards can be registered and resolved today, but local file reads/writes stay
+behind the bridge permission model until explicit user controls are in place.

package/corpus/templates/design/DEVELOPING.md

@@ -15,6 +15,12 @@ This guide is for development-mode agents editing this app's source code. For ap
 - **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
 - **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
 - **Start:** `node .output/server/index.mjs` (production)
+- **Design local bridge:** `npx @agent-native/core@latest design connect --url http://localhost:5173 --root .`
+  exposes a local manifest for Design's localhost source mode and scaffolds
+  `.agent-native/design-routes.json` without overwriting an existing file.
+- **Visual edit local apps:** `/visual-edit` registers that bridge with
+  `connect-localhost`, adds URL-backed iframe screens with
+  `add-localhost-screens`, and opens the editor in overview mode.
 
 ## Directory Structure
 
@@ -92,6 +98,43 @@ export default function MyPageRoute() {
 
 Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
 
+## Design Source Modes
+
+The shared source model lives in `shared/source-mode.ts`. Use `inline` for
+SQL-backed prototype files, `localhost` for local dev-server artboards, and
+`fusion` only for future hybrid/hosted sources. Bridge operations are named
+`select`, `resolveNodeToFile`, `readFile`, `applyEdit`, `writeFile`,
+`captureSnapshot`, and `captureState`; current localhost writes are contract-only
+until the bridge adds explicit permission hardening.
+
+## Editor Model
+
+Design has two editor views:
+
+- **Overview** is the default multi-screen canvas after generation or broad
+  updates. It renders every screen as a static, movable frame on an infinite
+  surface. Users can select screens, move/resize/drop frames and primitives,
+  edit layers in place, and use a frame's full-view button to focus it.
+- **Single screen** renders one file in the iframe editor. Use it for scrolling,
+  interacting with prototype behavior, text/DOM selection, and local visual
+  edits inside that screen.
+
+The layers panel treats screens/files as top-level frames and nests projected
+DOM/code layers under the active screen. Layer display names come from
+`data-agent-native-layer-name` first, then semantic/text fallbacks. Persist user
+renames by editing that attribute in the source; ids such as
+`data-code-layer-id` are for stable selection targets.
+Inline/Alpine HTML should also carry durable `data-agent-native-node-id`
+attributes for any layer the editor can select, reorder, duplicate, or patch.
+Selectors are fallback aliases, not the primary identity. Localhost React mode
+should resolve through build-time source/debug metadata (generated stable id,
+component, file, and line) before using selector fallbacks.
+
+Inline source mode supports local code-layer projection and deterministic HTML
+edits through `get-code-layer-projection` and `apply-visual-edit`. Current
+limitations: visual code-layer edits are HTML-only, and localhost reads/writes
+are still bridge-contract scaffolding until permission controls are hardened.
+
 ## Adding a Route-Only Endpoint
 
 Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.