@agent-native/core 0.79.27 → 0.80.1

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`.