export declare const DESIGN_VISUAL_EDIT_SKILL_MD = "---\nname: visual-edit\ndescription: >-\n  Open a running local app in Design overview mode as URL-backed iframe screens\n  for visual editing, flow review, duplication, and route-state exploration.\n  Use when the user asks to inspect, compare, or edit a real local app visually\n  in Design.\nmetadata:\n  visibility: exported\n---\n\n# Visual Edit\n\nUse `/visual-edit` when the user wants to inspect or edit a real local app\nvisually instead of generating standalone Alpine HTML. The source of truth is\nthe running localhost app plus its route URLs. Design shows those routes as\niframe-backed screens on the infinite canvas.\n\n## Installing this skill for an external MCP host\n\nThe hosted install path\n(`npx @agent-native/core@latest skills add visual-edit`, or `design` for the\nfull Design bundle) installs the exported instructions and registers the\nhosted Design MCP connector together. The open Skills CLI path\n(`npx skills@latest add BuilderIO/agent-native --skill visual-edit`) installs\nexported instructions only, with no MCP connector registration.\n\n## Core Model\n\n- Each screen is a URL-backed iframe, not copied HTML.\n- Each screen keeps URL metadata: `connectionId`, `routeId`, `path`,\n  `url`, `bridgeUrl`, title, and viewport size.\n- Localhost Edit mode renders the running app through the local bridge as a live\n  iframe with the same editor bridge used by HTML designs. It is not a frozen\n  static DOM snapshot.\n- The live editor is same-origin through the local bridge proxy. This boots\n  CSR apps and root-relative assets, but it is still a localhost editing proxy:\n  app-origin cookies, WebSockets/HMR, SSE, and non-GET app API calls may need a\n  future dev-server/plugin integration for perfect parity with the app's own\n  origin.\n- Interact mode renders the app's normal URL so app navigation, scrolling,\n  links, and form controls behave as they would in the browser.\n- While a localhost screen has pending live visual edits, do not switch back to\n  Interact until the user either applies the edits to source or explicitly\n  aborts/discards the preview.\n- Start in Design's screen overview mode. In overview, screens are static\n  design frames; full-screen focus is for scrolling and app interaction.\n- Alt-drag duplicates a screen. For localhost screens, duplication copies the\n  iframe frame and URL metadata; change the copy's path/query for a new state.\n- Flow visualization is multiple URL states: `/checkout?step=shipping`,\n  `/checkout?step=payment`, `/checkout?step=done`, etc.\n- When the user gives a named flow or numbered screen list, preserve that order\n  and create one screen per URL/path. Shorthand like\n  `localhost:1234/onboarding/1` means\n  `http://localhost:1234/onboarding/1`.\n\n## Select And Reprompt\n\nWhen a chat message begins with `[Reprompt selection]`, the selected subtree is\na hard write boundary. The only mutation path is `propose-node-rewrite` with\nthe exact `repromptId`, target, and `baseVersionHash` captured in\n`design-reprompt-pending:<designId>:<fileId>`. Never use `apply-visual-edit`,\n`apply-source-edit`, `write-source`, `write-local-file`, `edit-design`, or any\nother content-writing action for that request. Clarifying questions are allowed,\nbut a requested change must remain a proposal.\n\nProduce one variant by default. Produce two or three only when the instruction\nasks for options. A retry includes `priorProposalId`; keep the same target and\nbase version, incorporate the feedback, and call `propose-node-rewrite` again.\nThe UI previews the returned subtree without persisting it.\n\nUse `resolve-node-rewrite` for the accept/reject lifecycle. Accept applies the\nchosen variant as one version-checked inline/Yjs content transaction so one\nundo restores the prior structure; reject clears the proposal without changing\ncontent. For conversational resolution such as \"apply the second one,\" call\n`view-screen`, read the active `design.reprompt.proposal`, and pass its\n`proposalId` plus the zero-based `variantIndex` to `resolve-node-rewrite`.\n\n## Review Quality\n\n- Treat the running app as the truth. Preserve its component language, tokens,\n  route state, and real content unless the user explicitly asks for a new visual\n  direction.\n- Use multiple URL states to reveal meaningful UX moments: empty/loading/error\n  states, focused panels, modals, responsive breakpoints, and completed flow\n  steps when those matter to the review.\n- For visual edits, compare before/after at the relevant viewport sizes and\n  check key hover/focus/scroll states when the app exposes them.\n\n## Account And Sharing Model\n\n- The `/visual-edit` entry route can open before the viewer signs in. Public\n  `/design/:id` editor links can also render read-only public designs without a\n  session.\n- Prefer links returned by Design actions or `/_agent-native/open` deep links.\n  Do not surface URLs with `_session=` tokens. Query sessions are only a\n  fallback after normal cookie resolution, so an existing browser session can\n  still open the design as a different user and show \"Design not found\".\n- Do not attempt anonymous write actions. Bridge registration, design creation,\n  screen placement, generation, saving, and sharing are account-backed. If a\n  signed-out visitor wants to save or share, send them through the framework\n  sign-in return flow, then save or copy the design into that account before\n  opening the share dialog.\n\n## Required Local Bridge\n\nThe live-edit bridge is unlocked by a shared secret (the \"bridge token\") that\nmust match on two sides: the local bridge process, and the user's connection row\nin Design (which the browser reads to authorize `/live-edit-bridge`,\n`/read-file`, `/write-file`). Get them to match by letting the\n**authenticated** `open-visual-edit` action mint the token, then starting the\nbridge with it. This is the only ordering that works for the remote-MCP flow \u2014\nthe bridge cannot push its own token to the server without a CLI auth token, so\nthe server mints instead and the bridge adopts.\n\nFrom the target app repo, make sure its dev server is running, then:\n\n**1. Discover routes without starting a durable bridge** (one-shot, exits):\n\n```bash\nnpx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json\n```\n\nThis prints the manifest (routes + capabilities). Parse it to build\n`routeManifest` for the next step. (Skip this if the user already gave explicit\npaths/URLs to place.)\n\nInside the agent-native monorepo itself, use the workspace CLI instead of\n`npx` \u2014 `npx` installs the last published `@agent-native/core`, which will not\ncontain local changes and costs a slow install on every call:\n\n```bash\npnpm dev:cli design connect --url http://localhost:5173 --root templates/<app> --json\n```\n\n**2. Call `open-visual-edit`** (see Action Flow below) with NO `bridgeToken`.\nThe server mints one, stores it on the user's connection row, copies it into the\nplaced screens' metadata, and returns it to you as `bridgeToken`. Capture it.\n\n**3. Start the persistent bridge adopting that token** (single line; prefer the\nenv var so the secret does not appear in `ps`):\n\n```bash\nAGENT_NATIVE_BRIDGE_TOKEN=\"<bridgeToken from step 2>\" npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon\n```\n\n(Equivalently, pass `--bridge-token <token>`.) This starts a detached bridge on\n`http://127.0.0.1:7331`, adopts the server-minted token \u2014 so bridge and row\nagree and live-edit authorizes with no self-registration \u2014 and stays alive after\nthe command exits.\n\nFor a manual health/manifest check on the running bridge:\n\n```bash\ncurl http://127.0.0.1:7331/health\n```\n\n`/health` needs no token. The full manifest at `/manifest.json` is\npreview-token protected, so an unauthenticated `curl` of it returns\n`{\"ok\":false,\"error\":\"invalid or missing preview token\"}` \u2014 that response means\nthe bridge is up, not that it is broken.\n\nOnly use `--json` for the step-1 route probe. Never use `--json`, `--once`,\nor `--dry-run` for the durable step-3 bridge: they print the manifest and exit,\nso Design falls back to a non-editable live iframe.\n\nThe bridge listens on a single fixed port (7331) and refuses to start for a\nsecond, different app. It is detached with no log file, so if `--daemon` reports\na timeout, check for a stale process (`lsof -ti:7331`) before retrying.\n\n## Action Flow\n\nPrefer the single authenticated `open-visual-edit` action. It registers or\nrefreshes the localhost bridge connection, mints and stores the bridge token,\ncreates or reuses a Design project, places URL-backed screens, stores the active\nvisual-edit context, and navigates to overview mode in one call. This avoids\ncreating a private design under a synthetic CLI user and then handing the browser\na tokenized URL that may be shadowed by an existing session.\n\nCall it BEFORE starting the durable bridge (step 3 above): it does not contact\nthe bridge, so the bridge need not be running yet, and you need its returned\n`bridgeToken` to start the bridge with a matching secret. Omit `bridgeToken`\non the call so the server mints one.\n\n```bash\npnpm action open-visual-edit '{\n  \"title\": \"Docs homepage visual edit\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"bridgeUrl\": \"http://127.0.0.1:7331\",\n  \"rootPath\": \"/absolute/path/to/app\",\n  \"routeManifest\": { \"...\": \"from /manifest.json\" },\n  \"paths\": [\"/\", \"/pricing\", \"/checkout?step=payment\"]\n}'\n```\n\nThe action returns `designId`, `connectionId`, `bridgeToken`, `screens`,\n`urlPath`, and `openUrl`. Keep `designId`/`connectionId` in the chat context\nfor follow-ups, and pass `bridgeToken` to `design connect` (step 3) to start\nthe bridge. On follow-up calls reusing an existing `connectionId`, the same\ntoken is returned (it is minted once and reused), so the running bridge stays\nvalid.\n\n### Desktop and mobile side by side\n\nPass `viewports` to place every requested route once per viewport. Frames lay\nout as a grid: one row per route, one column per viewport. Presets are\n`desktop` (1280x900), `laptop` (1440x900), `tablet` (834x1112), and `mobile`\n(390x844); an explicit `{ \"label\": \"...\", \"width\": N, \"height\": N }` also works.\n\n```bash\npnpm action open-visual-edit '{\n  \"title\": \"Tasks responsive visual edit\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"bridgeUrl\": \"http://127.0.0.1:7331\",\n  \"rootPath\": \"/absolute/path/to/app\",\n  \"paths\": [\"/tasks\", \"/inbox\"],\n  \"viewports\": [\"desktop\", \"mobile\"]\n}'\n```\n\nPrefer this over two separate calls with `defaultWidth`/`defaultHeight`: it\nkeeps each route's viewports aligned in a row and titles them\n`Tasks \u2014 Desktop` / `Tasks \u2014 Mobile` so the canvas reads clearly. `viewports`\noverrides `defaultWidth`/`defaultHeight`. With no `routes`/`paths`, it expands\nevery route in the localhost manifest, which is usually far more frames than\nthe user wants \u2014 name the paths.\n\n### Adding more page frames later\n\nCall `open-visual-edit` again with the same `designId` and `connectionId` and\nonly the new paths. Existing frames for the same route and viewport are\nrefreshed in place rather than duplicated, and a frame the user has dragged or\nresized keeps its position unless you explicitly pass `x`/`y`/`width`/`height`.\n\n```bash\npnpm action open-visual-edit '{\n  \"designId\": \"<existing-design-id>\",\n  \"connectionId\": \"<existing-connection-id>\",\n  \"devServerUrl\": \"http://localhost:5173\",\n  \"paths\": [\"/settings\", \"/team\"],\n  \"startY\": 2200\n}'\n```\n\nDo NOT add `defaultWidth`/`defaultHeight` just to restate the default size:\nsupplying either one marks the viewport as explicitly requested, which\noverwrites frame sizes the user has already adjusted on the canvas.\n\nFor a numbered flow the user describes in chat, keep the labels and order:\n\n```bash\npnpm action open-visual-edit '{\n  \"designId\": \"<existing-design-id>\",\n  \"connectionId\": \"<existing-connection-id>\",\n  \"devServerUrl\": \"http://localhost:1234\",\n  \"routes\": [\n    { \"url\": \"localhost:1234/onboarding/1\", \"title\": \"Screen 1\" },\n    { \"url\": \"localhost:1234/onboarding/2\", \"title\": \"Screen 2\" },\n    { \"url\": \"localhost:1234/onboarding/3\", \"title\": \"Screen 3\" }\n  ]\n}'\n```\n\nIf no `routes` or `paths` are supplied, `open-visual-edit` uses every route\nfrom the localhost manifest.\n\nFallback, only when `open-visual-edit` is unavailable:\n\n1. Register or refresh the bridge with `connect-localhost`, passing the\n   `/manifest.json` result as `routeManifest` and `capabilities`.\n2. Create or reuse a Design project with `create-design`.\n3. Place URL-backed screens with `add-localhost-screens`.\n4. Navigate to overview mode with `navigate`.\n\n## Open The Design Surface\n\n- Use the `link`, `deepLink`, or MCP App embed returned by Design actions so\n  the user sees the canvas. In Codex Desktop or VS Code, prefer opening that\n  Design URL in the available preview/webview panel; otherwise surface the\n  \"Open design\" link.\n- Return or open the `openUrl` / action link, not a hand-built\n  `/design/:id?_session=...` URL.\n- If the user is working in VS Code, the Agent Native extension can open the\n  same URL via\n  `vscode://builder.agent-native/open?url=<encoded-design-url>`. Its\n  `Agent Native: Open Design Canvas` command also starts the local bridge and\n  opens hosted Design in the VS Code side panel.\n- After `open-visual-edit`, confirm the Design editor is in overview mode\n  with the requested URL-backed frames visible, and that they render the app\n  rather than a spinner. Do not stop at \"screens added\" when the user asked to\n  inspect or edit visually.\n\n## Applying Visual Edits Back To Source\n\nCanvas edits on a localhost screen do not write source as you make them. They\naccumulate as pending edits and the editor shows an \"Apply with Design agent\"\nbutton in the bottom-right corner of the canvas. Clicking it hands a structured\nprompt to the Design agent chat, which performs the real source write.\n\n- Style, text, and drag/drop structure edits all collect into the same pending\n  batch, so the user can make several changes and apply once.\n- After the write lands, the target app's own dev-server HMR refreshes the\n  frames \u2014 no manual reload. If frames do not refresh, the write did not land;\n  say so rather than assuming.\n- The separate disk-icon \"Apply to source\" button is the deterministic\n  whole-file HTML/CSS writer. It is intentionally disabled for compiled\n  `.jsx`/`.tsx` routes \u2014 those must go through the agent path above.\n\n## Editing URLs\n\nKeep localhost screens as URL files plus `screenMetadata[fileId]`. Do not\nreplace them with copied `srcdoc` HTML unless the user explicitly asks for a\nfrozen snapshot. To change a state, rerun `open-visual-edit` with the new\npath/query or duplicate the screen and update the copy's URL metadata.\n\n## Local Files in the Code Tab\n\nOnce a connection is registered, the design editor's Code panel (left rail \u2192\nCode, or `navigate --view editor --designId <id> --leftPanel code`) shows a\nlocal-files workspace root for that connection next to the design's own files.\nTreat that root like VS Code opened at the connected project directory: file\ntree, search, open/edit, and save are backed by the real local files. It lists\nthe connected app's text/code files through the bridge\n(`list-local-files` / `read-local-file`); build output, `node_modules`,\n`.git`, and secret-looking paths (`.env*`, key files) are always excluded.\n\n- Browsing and reading need only editor access on the design plus the running\n  bridge.\n- Saving goes through `write-local-file`: the first save opens the\n  write-consent dialog (an 8-hour, folder-scoped grant) and retries\n  automatically once granted. Only text/code files are writable; secret paths\n  are always blocked.\n- If the agent calls `write-local-file` directly (not through a UI save) and it\n  fails with \"no write-consent grant\", call `request-localhost-write-consent`.\n  It opens the write-consent dialog in the editor, or reports `alreadyGranted`\n  if one already exists. Granting is human-only \u2014\n  `grant-localhost-write-consent` is hidden from agents, so you cannot approve\n  it yourself. Tell the user to click \"Allow writes\", then retry\n  `write-local-file` once. Do not keep retrying blindly: the write stays\n  blocked until the user approves.\n- Saves are conflict-checked against the file's on-disk version \u2014 a file that\n  changed since it was read fails with a version conflict instead of being\n  overwritten.\n\n## React Source Writeback\n\n- Use compiler/debug provenance (project-relative file, line, column,\n  component, and runtime multiplicity) to locate React/TSX source. Treat it as\n  evidence, not as permission for a generic AST structural transform.\n- A single-instance leaf text edit, literal `className`/`class` edit, or flat\n  literal `style={{ ... }}` property may use `apply-visual-edit` with a\n  `local-file` source and exact `target.sourceAnchor`. Preview first (omit\n  `persist`), inspect `proposedDiff`, then call with `persist: true`.\n- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated\n  `.map()` instances, shared components, breakpoint-scoped edits, and\n  cross-file changes go through the coding agent with exact subject/target\n  anchors and their runtime relationship. `apply-visual-edit` refuses these\n  with `status: \"needsAgent\"` rather than guessing.\n- Before each write, read the file and pass its exact `versionHash` to\n  `write-local-file` with `requireExpectedVersionHash: true`; on conflict,\n  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms\n  the result. Human write consent remains mandatory and agents cannot grant it.\n\n## Verification\n\n- `list-localhost-connections` returns the expected connection and routes.\n- The Design editor opens in overview mode.\n- Every requested screen renders the intended localhost URL, showing real app\n  content rather than an endless loading spinner.\n- Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.\n- A query/path edit changes only the target screen's URL metadata and iframe.\n- The Code tab shows a local-files root for the connection and opens its files.\n";
//# sourceMappingURL=design-visual-edit-skill.d.ts.map