@agent-native/core 0.85.5 → 0.85.7

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -110,6 +110,50 @@ Pick a preset by `projectType`:
   `:root` CSS variable. Never hardcode `text-white` / `bg-black` / hex literals
   in the markup — that's what keeps brand + multi-screen consistency automatic.
 
+### Type-scale recipe
+
+Use this as a starting scale, then adjust to the chosen Aesthetic:
+
+- Display: 56-96px · H1: 40-64px · H2: 28-36px · Body: 16-18px · Caption: 12-13px.
+- Each adjacent step should be at least 1.25× the one below it — smaller jumps
+  read as "almost the same size" rather than a deliberate hierarchy.
+- A hero/display line should be at least 3× the body size.
+- Line-heights: display/H1 tight at 1.05-1.15, H2/H3 at 1.2-1.3, body relaxed
+  at 1.5-1.7.
+- Measure (line length) for body copy: 60-75 characters; constrain with
+  `max-width` in `ch` units, not a raw pixel guess.
+
+### Section rhythm
+
+Pick one section padding value and repeat it for every top-level section on
+the page/screen: 96-128px on desktop, 48-64px on mobile. Don't let each
+section invent its own padding — that's what makes a page feel unplanned.
+Use spacing to encode grouping: gaps *inside* a card or cluster should be
+visibly smaller than the gap *between* cards/sections — if inside-group and
+between-group spacing match, the eye can't tell where one group ends and the
+next begins.
+
+### Verifiable contrast pairs
+
+Don't just assert "WCAG AA" — check the actual token pairs the design ships.
+The most common real failure is muted text (`--color-text-muted`) directly on
+a card/surface background rather than the page background; verify that pair
+specifically, not just text-on-page. If an accent color doubles as text (a
+link, an active nav item, a price), it usually fails 4.5:1 against typical
+surfaces — add a separate `--color-accent-text` variant tuned for text-on-
+background contrast rather than reusing the decorative accent for copy.
+
+### Richer tokens
+
+Go beyond the minimal `:root` block in the HTML Structure Requirements below
+when the design needs it — add `--space-section` (see Section rhythm),
+`--color-border`, `--color-accent-text` (see contrast pairs above),
+`--shadow-card`, and a success/warning/danger trio
+(`--color-success` / `--color-warning` / `--color-danger`) once the design has
+status states, alerts, or form validation to express. Keep font tokens as
+placeholders you fill per design (see HTML Structure Requirements) rather than
+hardcoding a concrete family in a shared template.
+
 ## Building on existing code, screens, or a design system
 
 When a design system, tokens, current screens, or a connected codebase already
@@ -127,7 +171,7 @@ defaults. The banned-defaults list above still applies, plus:
   your colors". Keep structure and layout genuinely varied per screen while the
   palette, type, and components stay on-brand.
 
-## Generation Workflow — the canonical 4-phase flow
+## Generation Workflow — the canonical 5-phase flow
 
 This flow mirrors Claude Design's UX: ask → show variants → user picks → refine. Don't skip phases for new designs.
 
@@ -204,12 +248,21 @@ pnpm action generate-design \
 
 `generate-design` accepts a `--tweaks` array — pass 3-6 of the most impactful knobs bound to CSS custom properties the design's `:root` block actually defines. Surface controls users will actually want to adjust (accent color, density, radius, dark-mode toggle, font choice). Don't ship a generic preset; let the design's structure pick the knobs.
 
-### Phase 5 — Review before calling it ready
+### Phase 5 — Audit, fix, and eyeball before calling it ready
+
+Run `run-design-audit` against each screen (`designId` + `fileId`/`filename`).
+It returns `A11yFinding[]` covering missing alt/labels, tap-target size,
+focus-visibility, reduced-motion coverage, and a contrast hint. For every
+`error`-severity finding with `fixAvailable: true`, call `apply-a11y-fix`;
+for findings that aren't auto-fixable (missing alt text, structural issues),
+fix them directly with `edit-design`. **A design with audit errors is not
+ready** — don't report a design as done while `run-design-audit` still
+returns unresolved errors.
 
-Open the generated screen or overview and inspect it like a design review:
-hierarchy, overflow, mobile fit, contrast, keyboard focus, empty/loading/error
-states for app UI, and whether the copy/content still sounds real. Fix obvious
-issues before reporting the design as ready.
+After the audit is clean, do one visual pass by eye at both a mobile width
+(375px) and a desktop width (1280px): check for overflow/clipping, broken
+hierarchy, empty/loading/error states for app UI, and whether the copy/content
+still sounds real. Fix obvious issues before reporting the design as ready.
 
 ## HTML Structure Requirements
 
@@ -247,8 +300,8 @@ Every `index.html` must include:
       --color-surface: #1E293B;
       --color-text: #F8FAFC;
       --color-text-muted: #94A3B8;
-      --font-heading: 'Space Grotesk', sans-serif;
-      --font-body: 'DM Sans', sans-serif;
+      --font-heading: '<HEADING_FONT>', sans-serif; /* pick per Font Recommendations below — do not default to Space Grotesk */
+      --font-body: '<BODY_FONT>', sans-serif; /* pick a pairing, not a repeat of every other generation */
       --radius: 12px;
     }
 
@@ -484,11 +537,20 @@ to the chosen Aesthetic layer is what keeps designs from sharing a fingerprint:
 | Space Grotesk | DM Sans | Modern tech |
 | Playfair Display | Source Sans 3 | Editorial luxury |
 | Sora | Outfit | Clean geometric |
-| Cabinet Grotesk | Satoshi | Contemporary startup |
+| Bricolage Grotesque | Schibsted Grotesk | Contemporary startup |
 | Fraunces | Work Sans | Warm editorial |
 | JetBrains Mono | IBM Plex Sans | Developer tool |
-| Clash Display | General Sans | Bold statement |
+| Unbounded | Sora | Bold statement |
 | Archivo | Nunito Sans | Friendly SaaS |
+| Instrument Serif | Schibsted Grotesk | Editorial minimal |
+
+All of the above are served by Google Fonts (`fonts.googleapis.com/css2`). The
+mandatory `<head>` only loads the Google Fonts CDN (see HTML Structure
+Requirements) — Fontshare-only families (Cabinet Grotesk, Satoshi, Clash
+Display, General Sans) are not on Google Fonts and will silently fail to load,
+so the browser falls back to a system sans and quietly reintroduces the exact
+slop this skill bans. Only use a Fontshare family if you also add its
+Fontshare `<link>`/`@import` and confirm it renders.
 
 ## Multi-screen prototypes & navigation
 
@@ -569,7 +631,122 @@ regeneration is slow, expensive, and regresses unrelated parts.
 - Never use `<script>` blocks with raw DOM manipulation — use Alpine.js directives
 - Never inline `onclick="..."` handlers — use `@click`
 - Never use `!important` except in `[x-cloak]`
-- Never use position: fixed for modals — wrap in a portal-like pattern with Alpine.js
 - Never forget `cursor-pointer` on interactive elements
-- Never use `<img>` with placeholder URLs — use colored divs or gradients
-- Never set font-size below 14px for body text or 12px for labels
+- Never use `<img>` with placeholder/stock URLs — generate real imagery (see
+  Imagery below) or use tokened colored divs/gradients only for pure UI
+  chrome (icons, avatars-as-initials, decorative fills), never as a stand-in
+  for a hero, product shot, or portrait that should be a generated image
+- Never set font-size below 16px for body text or 12px for labels
+
+## Multi-screen consistency contract
+
+When a design has more than one screen, the shared system must be
+byte-identical across every screen file, not just similar: the `:root` token
+block, the Google Fonts `<link>`, the nav, and the footer should match exactly
+between `index.html` and every other screen. Before saving a new or edited
+screen, diff its `:root` block against `index.html`'s (or the design system's
+tokens) and reconcile any drift instead of letting each screen accumulate its
+own slightly-different palette. Consistency is not sameness — keep structure
+and layout varied per screen (see "Building on existing code" above) while the
+token layer, typography, nav, and footer stay identical.
+
+## Breakpoints & screen states
+
+- **Breakpoints**: `add-breakpoint` adds a device-width frame (Mobile 390 /
+  Tablet 768 / Desktop 1280, or a custom width) to the design's breakpoint set
+  stored in `designs.data`; the Tailwind prefix is derived from the width and
+  duplicate widths are ignored. `remove-breakpoint` removes one by id.
+  `set-active-breakpoint` sets which frame is the current edit scope — editing
+  a layer while `base` is active writes unprefixed Tailwind classes, editing
+  while `md` is active writes `md:`-prefixed classes. Always check the active
+  breakpoint before making a responsive-only edit so the class lands at the
+  right prefix.
+- **Design states**: `create-design-state` creates a named alternate
+  DOM/Alpine snapshot (`kind: "state"` — Loading, Empty, Error), a static data
+  fixture (`kind: "fixture"`), or a placeholder for a live capture
+  (`kind: "capture"`). `apply-design-state` updates an existing state row
+  (rename, change breakpoint, update fixture/capture data, set the preview
+  reference). `capture-design-state` records a running app's current route,
+  props, and API data into a `capture` row — it requires the design's source
+  to advertise the `captureState` bridge capability (localhost/fusion); for
+  inline designs without a live bridge, use `create-design-state` instead.
+  `list-design-states` lists all states/fixtures/captures for a design, and
+  `delete-design-state` removes one (irreversible; the design itself is
+  unaffected).
+
+## Component reuse
+
+Before hand-rolling another near-duplicate card/button/nav item, check
+whether the pattern already exists as a recognised component. Once a visual
+pattern repeats 3+ times in a design, promote it: call `create-component` on
+the selected root element to stamp deterministic
+`data-agent-native-component="<Name>"` and `data-agent-native-prop-*`
+annotations, so it becomes a recognised component instance for the canvas
+outline and the Component inspector section. Use `index-components` to scan a
+design's HTML for existing `data-agent-native-component` annotations and
+persist the discovered component list before inventing something that may
+already exist. `get-component-details` returns a selected instance's name,
+props, variants, and source info. `preview-component-prop-edit` previews a
+prop/class change on the canvas without saving; `apply-component-prop-edit`
+persists it. `open-component-source` navigates to the component's source
+location (the design file for inline/Alpine designs, or the resolved external
+file for localhost/fusion sources).
+
+## Realistic app-state content
+
+For app/product UI (not marketing pages), populate lists and tables with
+plausible mid-life data — not a pristine "just signed up" empty account and
+not obviously fake placeholder rows (avoid "Lorem Ipsum User", "Item 1", "Item
+2"). Include at least one realistically long name/title/label so truncation
+and wrapping behavior is visible. Always design the empty state and a loading
+skeleton for the screen's primary data surface — don't only show the
+happy-path populated state.
+
+## Motion craft
+
+Push motion the same way you push type and color: on purpose, not as a
+uniform default. Duration bands: 150-250ms for micro-interactions (hover,
+toggle, button press), 300-500ms for panel/sheet/modal transitions, and
+500-800ms reserved for exactly one orchestrated page-load reveal (stagger
+individual elements 60-100ms apart, capped at about 6 staggered elements —
+more than that reads as sluggish, not polished). Ease functions: `ease-out`
+for elements entering, `ease-in` for elements leaving. Animate only
+`transform` and `opacity` for performance; avoid animating `width`/`height`/
+`top`/`left`. Every non-essential animation must respect
+`prefers-reduced-motion` (see the mandatory `<style>` block below). For
+inline/Alpine screens, persist motion as durable timeline metadata: inspect
+the current file's timeline with `get-motion-timeline`, then write changes
+with `apply-motion-edit` using the same `sourceRef`/`fileId` — this is not a
+one-way export, edits stay editable.
+
+## Imagery
+
+Generate real images for anything a real product would photograph or
+illustrate: hero backgrounds, product shots, portraits/avatars, testimonial
+photos, marketing/editorial imagery. Don't generate images for utility UI —
+icons, data tables, form chrome, and dashboard widgets should stay as
+tokened SVG/CSS, not photos.
+
+- **Use the Assets generation tool** (`generate-asset`, or `insert-asset` once
+  an asset is chosen) instead of `<img>` placeholder URLs or colored-div
+  stand-ins. See the Core Rules image-generation bullet in `AGENTS.md` for the
+  full calling convention (default `tier: "fast"`, `callerAppId: "design"`,
+  matching `aspectRatio`).
+- **Write image prompts as art direction, not a one-line label.** Specify
+  subject, composition, lens/framing, lighting, and palette, and tie the
+  palette/mood back to the design's own `:root` tokens so the image reads as
+  part of the same system rather than a stock photo dropped in. If a design
+  system is linked, fold its `imageStyle.styleDescription` into the prompt
+  (see `design-systems` skill) so generated imagery matches the brand's
+  established photographic/illustration style.
+- **Default to `tier: "fast"`** (the cheap Gemini Flash "nanobanana"-class
+  model) for exploration and every non-final variant. Only request
+  `tier: "best"` for the final, user-approved hero image — not for every pass.
+- **Match `aspectRatio` to the layout slot**: `21:9` for a full-bleed hero,
+  `4:3` for a card/feature image, `1:1` for an avatar or square thumbnail.
+  Mismatched aspect ratios force ugly crops in the browser.
+- **Always write real `alt` text** describing the image's content — never
+  leave `alt=""` on a meaningful (non-decorative) image.
+- **Placement is a two-step pass**: call `insert-asset` to place the chosen
+  image, then do one `edit-design` pass to adjust surrounding layout/spacing
+  if the inserted figure doesn't sit flush with the rest of the design.

package/corpus/templates/design/.agents/skills/design-systems/SKILL.md

@@ -73,6 +73,12 @@ interface DesignSystemData {
 }
 ```
 
+`imageStyle.styleDescription` is not just metadata — fold it into every
+`generate-asset` prompt for a design linked to this system, alongside the
+subject/composition/lighting direction described in the design-generation
+skill's Imagery section. This is what keeps generated photography/illustration
+on-brand instead of drifting to a generic stock look each time.
+
 ## Actions
 
 ### Creating a Design System
@@ -92,8 +98,8 @@ pnpm action create-design-system \
       "textMuted": "#94A3B8"
     },
     "typography": {
-      "headingFont": "Space Grotesk",
-      "bodyFont": "DM Sans",
+      "headingFont": "<HEADING_FONT>",
+      "bodyFont": "<BODY_FONT>",
       "headingWeight": "700",
       "bodyWeight": "400",
       "headingSizes": { "h1": "64px", "h2": "40px", "h3": "28px" }
@@ -105,6 +111,12 @@ pnpm action create-design-system \
   }'
 ```
 
+`<HEADING_FONT>` / `<BODY_FONT>` are placeholders — pick a real Google Fonts
+pairing per the design-generation skill's Font Recommendations table (or the
+brand's actual extracted fonts) rather than defaulting to Space Grotesk/DM
+Sans every time; that pairing is this skill's own most common convergence
+fingerprint.
+
 If this is the user's first design system, it is automatically set as the default.
 
 ### Reading a Design System
@@ -257,8 +269,8 @@ When the user provides multiple sources, call all applicable import actions in p
 4. **Documents supplement** — presentations may reveal brand colors not in code
 5. **Images inform mood** — color temperature, density, visual style
 6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve conflicts
-6. **Call `create-design-system`** with the combined result
-7. **Link to design** via `update-design --designSystemId`
+7. **Call `create-design-system`** with the combined result
+8. **Link to design** via `update-design --designSystemId`
 
 ## Applying Design System to Generated HTML
 

package/corpus/templates/design/.agents/skills/export-handoff/SKILL.md

@@ -10,6 +10,24 @@ description: >-
 
 How to export designs and generate handoff documentation for developers converting prototypes to production code.
 
+## Other export actions
+
+- **SVG**: `export-svg` exports a design project as an SVG document (a
+  `foreignObject` wrapper around the standalone HTML), giving agent parity
+  with the editor's Download SVG command. The editor's own Download SVG
+  command captures the live browser DOM for the most faithful snapshot; use
+  the action when you need agent-side SVG export without a live browser.
+- **PNG**: there is no PNG export action. Point the user to the editor's
+  download menu (Download PNG) — PNG export is a client-side rasterization of
+  the live canvas and is not exposed as an agent action.
+- **Deploy preview**: `deploy-design-preview` triggers a preview deploy for a
+  fusion-backed design branch. It requires the design's source to advertise
+  the `deployPreview` capability (fusion tier) and Builder.io to be connected;
+  a branch must already exist via `create-design-branch`. For inline/localhost
+  designs it returns `ctaRequired: true` with a Make-it-real CTA instead of
+  faking a deploy. This triggers a *preview* deploy only — production
+  publishing goes through the Builder Visual Editor's Publish flow.
+
 ## Export Formats
 
 ### HTML Export
@@ -70,9 +88,30 @@ pnpm action export-pdf --id <designId>
 
 Returns all design data and files needed for the client to render a PDF.
 
-## Claude Code Handoff
+## Coding Handoff
+
+When a user wants to convert an Alpine.js + Tailwind prototype into production
+code, use the canonical `export-coding-handoff` action instead of hand-writing
+a handoff message:
+
+```bash
+pnpm action export-coding-handoff --id <designId>
+```
+
+This returns tokenized raw and ZIP URLs any external coding agent can fetch,
+plus a ready-to-copy prompt. The bundle reflects the design's **current**
+state — live editor (collab) content plus the user's applied visual tweaks
+resolved into the HTML `:root` — so the generated code matches what the user
+actually tuned, not the original generated tokens. Pass `format: "json"` if the
+receiving agent wants structured data instead of markdown, and `origin` to get
+an absolute raw-code URL for a specific app origin. This is the canonical
+design-to-code tool; prefer it over composing a handoff message by hand.
+
+### Manual handoff template (fallback)
 
-When a user wants to convert an Alpine.js + Tailwind prototype into production code, generate a detailed handoff prompt. This is not an action — it is a structured message you compose based on the design.
+Use the template below only when `export-coding-handoff` isn't available or
+the user explicitly wants a hand-composed summary instead of the action's
+bundle. Compose it based on the design's actual HTML/tokens.
 
 ### Handoff Prompt Template
 
@@ -159,7 +198,11 @@ pnpm action export-html --id [designId]
 
 ### Generating the Handoff
 
-When the user asks to "hand off" or "convert to production code":
+When the user asks to "hand off" or "convert to production code", call
+`export-coding-handoff --id <designId>` first (see Coding Handoff above) — it
+already extracts tokens, resolves applied tweaks, and returns a ready-to-copy
+prompt plus fetchable URLs. Only fall back to composing the manual template
+by hand if that action is unavailable:
 
 1. Read the design: `get-design --id <designId>`
 2. Extract all CSS custom properties from the HTML

package/corpus/templates/design/AGENTS.md

@@ -39,7 +39,12 @@ patterns live in `.agents/skills/`.
   supports our own primitives.
 - For raster image generation, restyling, or editing existing screenshots/photos,
   use the available first-party Assets MCP tool such as `generate-asset` instead
-  of placeholders or generic stock imagery. When the Assets picker returns a
+  of placeholders or generic stock imagery. Default to `tier: "fast"` (the cheap
+  Gemini flash "nanobanana"-class model) unless the user explicitly asks for
+  best quality; pass `aspectRatio` matching the layout slot (e.g. `21:9` hero,
+  `4:3` card, `1:1` avatar); include the linked design system's
+  `imageStyle.styleDescription` in the prompt when one is linked; and always
+  pass `callerAppId: "design"`. When the Assets picker returns a
   selected asset, preserve `assetId`, `runId`, and URLs verbatim; if a design is
   open, call `insert-asset` with the chosen URL/id, then refine placement with
   `get-design-snapshot` and `edit-design` as needed. If no Assets MCP tool is
@@ -223,6 +228,33 @@ patterns live in `.agents/skills/`.
   with `path`/`url` when visualizing a flow; pass `paths` for a concise route
   list. Then call `navigate --view editor --designId <id> --editorView overview`.
 
+## Review, Breakpoints, Screen States & Components
+
+- **Review**: `run-design-audit` runs a read-only accessibility audit over a
+  design's rendered HTML (missing alt/labels, tap-target size,
+  focus-visibility, reduced-motion coverage, a contrast hint) and returns
+  `A11yFinding[]`. `apply-a11y-fix` applies one deterministic inline fix for a
+  finding (contrast, tap-target size, focus ring) when `fixAvailable: true`.
+  `get-design-review` compares two design snapshots/branches and returns a
+  file-level visual diff (added/removed/modified). See the `design-generation`
+  skill's Phase 5 for when to run these.
+- **Breakpoints**: `add-breakpoint`, `remove-breakpoint`, and
+  `set-active-breakpoint` manage the design's device-width frame set and which
+  frame new edits target. See the `design-generation` skill's "Breakpoints &
+  screen states" section.
+- **Design states**: `create-design-state`, `apply-design-state`,
+  `capture-design-state`, `list-design-states`, and `delete-design-state`
+  manage named DOM/Alpine states (Loading/Empty/Error), static data fixtures,
+  and live app captures. See the same skill section.
+- **Components**: `create-component` promotes a selected element into a
+  recognised reusable component; `index-components` scans a design's HTML for
+  existing component annotations; `get-component-details`,
+  `preview-component-prop-edit`, `apply-component-prop-edit`, and
+  `open-component-source` inspect, preview, persist, and navigate to a
+  component instance. See the `design-generation` skill's "Component reuse"
+  section — promote a 3+ times repeated pattern instead of inventing another
+  near-duplicate.
+
 ## App-Backed Skill Distribution
 
 - The preferred hosted install path is
@@ -246,9 +278,13 @@ patterns live in `.agents/skills/`.
   on that same `fileId` for follow-up refinement. The kept variant screen is a
   representative direction, not the final deliverable: use `mode:
 "replace-file"` to replace it with the actual requested app/product UI in the
-  chosen visual style. Do not leave a direction board, variant brief, summary
-  card, or prose description as the final screen. Do not repeat delete/snapshot
-  cycles, and do not call `generate-design` after a variant pick.
+  chosen visual style. Keep the replacement complete but compact: prioritize
+  the primary workflow, and if the requested feature list is too large for one
+  reliable edit, represent secondary details as visible controls, states, or
+  affordances instead of expanding the action input. Do not leave a direction
+  board, variant brief, summary card, or prose description as the final screen.
+  Do not repeat delete/snapshot cycles, and do not call `generate-design` after
+  a variant pick.
 - If inline chat choice buttons are unavailable, the user can tell you the
   preferred screen name. Do not show a separate variant picker or ask them to
   paste a copyable handoff summary.

package/corpus/templates/design/actions/apply-component-prop-edit.ts

@@ -13,8 +13,10 @@
  * - `classReplace` — replaces one Tailwind class with another on the root node.
  *
  * **Tier B (real-app, localhost / fusion):**  prop writes require the
- * `applyEdit` source capability (bridge write hardening).  Until that lands the
- * action returns a `ctaRequired: true` response and does not modify any source.
+ * `applyEdit` source capability.  Localhost sources have it (design bridge +
+ * user write consent); fusion sources gain it after bridge hardening.  For
+ * sources without it the action returns a `ctaRequired: true` response and
+ * does not modify any source.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1, §7 (preview/apply contract), §11 phase 2.
  */
@@ -43,11 +45,7 @@ import {
   applyVisualEdit,
   buildCodeLayerProjection,
 } from "../shared/code-layer.js";
-import type {
-  CodeLayerSource,
-  ClassEditIntent,
-  StyleEditIntent,
-} from "../shared/code-layer.js";
+import type { CodeLayerSource, ClassEditIntent } from "../shared/code-layer.js";
 import {
   componentNameFor,
   componentNodeIdMatches,
@@ -342,70 +340,12 @@ export default defineAction({
       );
     }
 
-    // ── Build edit intent ────────────────────────────────────────────────────
-    // Map the component prop edit kind to an EditIntent that apply-visual-edit
-    // understands.  We use the same deterministic patch path for all kinds.
-
-    const target = { nodeId };
-
-    let intent: ClassEditIntent | StyleEditIntent;
-
-    if (edit.kind === "alpineData") {
-      // x-data is not a standard CSS property or Tailwind class — we write it
-      // as a style-like "attribute" edit by embedding it in the class edit path
-      // via the `set` operation on a synthetic class string.  Because the HTML
-      // patcher writes raw attribute values we use the attribute-set approach
-      // that `apply-visual-edit` already supports through the `style` path
-      // (targeting `x-data` as a custom property in an inline `style`
-      // attribute would corrupt the DOM, so instead we encode the value in a
-      // `data-agent-native-alpine-data` attribute and let the bridge pick it
-      // up).  For maximum compatibility with the existing apply-visual-edit
-      // path we use a class operation to manipulate the x-data value through a
-      // well-known pattern the bridge understands.
-      //
-      // The cleanest path is to write `data-agent-native-alpine-data` as an
-      // attribute so the iframe bridge can relay it to Alpine as the effective
-      // x-data — but since the bridge postMessage layer handles x-data edits
-      // on preview, for the persist path we do a direct HTML attribute patch.
-      // We accomplish this by treating it as a `style` edit on a sentinel
-      // property that the patcher will place as an attribute.  However the
-      // current patcher only handles CSS properties, so we write the x-data
-      // value through the attribute approach: stamp `data-agent-native-prop-x-data`.
-      intent = {
-        kind: "class",
-        target,
-        // Use the `set` operation with a minimal token list to mark the node's
-        // Alpine data without touching real layout classes.  The actual x-data
-        // attribute is written below via a direct HTML splice.
-        operation: "add",
-        className: `data-[x-data=${JSON.stringify(edit.value)}]:hidden`, // sentinel (will not apply visually)
-      } as ClassEditIntent;
-      // Fall through to the direct HTML splice below.
-    } else if (edit.kind === "classReplace") {
-      intent = {
-        kind: "class",
-        target,
-        operation: "replace",
-        from: edit.from,
-        to: edit.to,
-      } as ClassEditIntent;
-    } else {
-      // attribute kind — write as a class add of a data-attribute sentinel so
-      // the existing patcher path handles it, then fall through to the direct
-      // splice for the actual attribute patch.
-      intent = {
-        kind: "class",
-        target,
-        operation: "add",
-        className: `data-[prop-${edit.attribute}]:hidden`, // sentinel
-      } as ClassEditIntent;
-    }
-
-    // ── Direct HTML splice for attribute edits (alpineData + attribute) ──────
-    // The existing apply-visual-edit patcher is class/style/text focused.  For
-    // attribute mutations on the component root we splice the raw HTML directly
-    // using the node's source span (the same technique the patcher uses for
-    // attribute stamping).
+    // ── Apply the edit ───────────────────────────────────────────────────────
+    // - alpineData / attribute: attribute mutations on the component root are
+    //   applied with a direct HTML splice using the node's source span — the
+    //   deterministic patcher is class/style/text focused.
+    // - classReplace: routed through the deterministic apply-visual-edit
+    //   patcher (same seam as all other class edits).
 
     let patchedContent = html;
     let changed = false;
@@ -420,8 +360,15 @@ export default defineAction({
       );
       patchedContent = result.content;
       changed = result.changed;
-    } else if (edit.kind === "classReplace") {
-      // Use the deterministic patcher for class edits.
+    } else {
+      // classReplace — use the deterministic patcher for class edits.
+      const intent: ClassEditIntent = {
+        kind: "class",
+        target: { nodeId },
+        operation: "replace",
+        from: edit.from,
+        to: edit.to,
+      };
       const patch = applyVisualEdit(html, intent, { source: codeLayerSource });
       if (patch.result.status === "applied" && patch.result.changed) {
         patchedContent = patch.content;

package/corpus/templates/design/actions/apply-motion-edit.ts

@@ -97,6 +97,18 @@ export function canPatchManagedMotionCss(content: string): boolean {
   return /<\s*(?:!doctype|[a-z][a-z0-9:-]*(?:\s|>|\/>))/i.test(content);
 }
 
+// Composite key for detecting duplicate (targetNodeId, property) track pairs.
+// Uses the ASCII Unit Separator (U+001F) — an escape in source, so the file
+// stays plain text (a literal NUL made tooling treat it as binary). U+001F
+// cannot appear in a valid data-agent-native-node-id or CSS property name
+// (both are validated to CSS-safe identifiers), so it can never collide with
+// real content and remains an unambiguous field delimiter.
+const MOTION_TRACK_KEY_SEPARATOR = "\x1f";
+
+export function motionTrackKey(targetNodeId: string, property: string): string {
+  return `${targetNodeId}${MOTION_TRACK_KEY_SEPARATOR}${property}`;
+}
+
 async function persistFileContent(
   fileId: string,
   designId: string,
@@ -168,7 +180,10 @@ export default defineAction({
       .number()
       .int()
       .positive()
-      .default(300)
+      // Keep in sync with the MotionDock default (DesignEditor
+      // motionDurationMs) and get-motion-timeline's CSS-recovery fallback so
+      // an omitted duration means the same thing on every surface.
+      .default(1000)
       .describe("Total animation duration in milliseconds."),
     defaultEase: z
       .string()
@@ -254,9 +269,21 @@ export default defineAction({
 
     // Reject CSS-injection vectors in caller-supplied track properties,
     // keyframe values, and easing strings before they are compiled into the
-    // managed <style> block.
+    // managed <style> block. Also reject duplicate (targetNodeId, property)
+    // pairs: the compiler derives the animation name from that pair, so a
+    // duplicate would silently overwrite the earlier track's keyframes.
+    const seenTrackKeys = new Set<string>();
     for (const track of typedTracks) {
       assertSafeMotionCssProperty(track.property, "track.property");
+      const trackKey = motionTrackKey(track.targetNodeId, track.property);
+      if (seenTrackKeys.has(trackKey)) {
+        throw new Error(
+          `Duplicate motion track for targetNodeId "${track.targetNodeId}" ` +
+            `and property "${track.property}". Each (targetNodeId, property) ` +
+            "pair may appear at most once — merge the keyframes into a single track.",
+        );
+      }
+      seenTrackKeys.add(trackKey);
       for (const kf of track.keyframes) {
         assertSafeMotionCssToken(kf.value, "keyframe value");
         if (kf.ease !== undefined) {

package/corpus/templates/design/actions/apply-visual-edit.ts

@@ -106,6 +106,7 @@ function scopeClassIntentToBreakpoint(
       prefix,
       operation: "replace",
       utility: intent.to,
+      from: intent.from,
     };
   }
 
@@ -474,11 +475,12 @@ export default defineAction({
       const patch = applyVisualEdit("", editIntent, {
         source: codeLayerSource,
       });
+      // local-file / remote-url sources are not editable here (the engine
+      // reports "unsupported"), so no byte counts are returned — a 0/0 pair
+      // would misleadingly suggest an empty file was measured.
       return {
         result: patch.result,
         projection: patch.projection,
-        bytesBefore: 0,
-        bytesAfter: 0,
       };
     }