@agent-native/core 0.124.2 → 0.124.3

package/corpus/README.md

@@ -30,4 +30,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 - core files: 1736
 - toolkit files: 160
-- template files: 6787
+- template files: 6791

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.124.3
+
+### Patch Changes
+
+- c385fed: Keep emoji and other multi-code-point grapheme clusters intact while streaming text. The incremental segmentation cache re-segmented from a fixed character offset, so a cluster straddling that offset was cut in half and characters were silently dropped from the smoothed output. The re-segmentation window now starts on a grapheme boundary.
+
 ## 0.124.2
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.124.2",
+  "version": "0.124.3",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/shared/streaming-text-smoothing.ts

@@ -70,25 +70,26 @@ export function splitStreamingTextGraphemes(text: string): string[] {
   // Incremental path: new text extends the cached text
   if (_segCache && text.startsWith(_segCache.text)) {
     const prevLen = _segCache.text.length;
-    // Re-segment from (prevLen - OVERLAP) to include the overlap so any
-    // grapheme that was split across the boundary is correctly re-assembled.
-    const overlapStart = Math.max(0, prevLen - SEGMENTER_OVERLAP);
+    const cached = _segCache.graphemes;
+    // Walk back over cached graphemes until at least OVERLAP characters have
+    // been released, so the re-segmented suffix starts on a known grapheme
+    // boundary. Slicing at a fixed character offset instead would cut a
+    // cluster (surrogate pair, ZWJ sequence) in half, and segmenting that
+    // partial cluster in isolation yields a different grapheme count than the
+    // cache holds for the same region — which silently drops characters.
+    let stableCount = cached.length;
+    let releasedChars = 0;
+    while (stableCount > 0 && releasedChars < SEGMENTER_OVERLAP) {
+      stableCount--;
+      releasedChars += cached[stableCount]!.length;
+    }
+    const overlapStart = prevLen - releasedChars;
     const suffix = text.slice(overlapStart);
     const newGraphemes = Array.from(
       segmenter.segment(suffix),
       (entry) => entry.segment,
     );
-    // Drop graphemes that correspond to the overlap region from the cache so
-    // we don't double-count them.
-    const overlapGraphemes = Array.from(
-      segmenter.segment(text.slice(overlapStart, prevLen)),
-      (entry) => entry.segment,
-    );
-    const stableGraphemes = _segCache.graphemes.slice(
-      0,
-      _segCache.graphemes.length - overlapGraphemes.length,
-    );
-    const merged = stableGraphemes.concat(newGraphemes);
+    const merged = cached.slice(0, stableCount).concat(newGraphemes);
     _segCache = { text, graphemes: merged };
     return merged;
   }

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

@@ -249,7 +249,12 @@ Favor choice-first questions (2-5 concrete options, `allowOther: true`, and a
 combining multiple answers — stacking multi-select questions multiplies
 follow-up ambiguity instead of resolving it.
 
-**Carry the form-factor answer through to generation — do not just ask and discard it.** A "Desktop web app" answer means the generated screen's canvas frame must be desktop-sized (~1440×1024), not left at whatever a screen with no placement falls back to. Map the answer to real frame geometry: pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen to `generate-screens`, explicit `width`/`height` per variant to `present-design-variants`, or an explicit `canvasFrames` entry to `generate-design` — see Phase 2 and Phase 3 below. For "Both / responsive," generate at desktop width and rely on the responsive breakpoint system (see `responsive-breakpoints` skill) rather than guessing a size.
+**Carry the form-factor answer through to generation — do not just ask and discard it.** Map the answer to the design's device SET, not to separate per-device screen files. Device widths of the SAME page are breakpoint frames of one document (see the `responsive-breakpoints` skill), never a `mobile.html` + `desktop.html` pair. Pass the answer through `generate-design`'s `devices` param — `("mobile"|"tablet"|"desktop")[]`, default `["desktop","mobile"]`:
+
+- If the prompt/answer names specific devices, generate EXACTLY those, deduped ("mobile" only → one mobile frame; "mobile, tablet, desktop" → all three).
+- If nothing about form factor is specified — or the answer is "Both / responsive" or "Decide for me" — default to `["desktop","mobile"]`: a Desktop base + a Mobile frame only. Never auto-add a tablet, a redundant desktop, or a stray duplicate frame.
+
+The WIDEST requested device is the base/primary frame; narrower devices become breakpoint frames (never at the primary width). Device frame sizes: mobile 390×844, tablet 768×1024, desktop 1440×900. `present-design-variants` still takes explicit `width`/`height` per variant to size its exploration screens (see Phase 2).
 
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)
 
@@ -264,16 +269,16 @@ screen name.
   "designId": "<the design id>",
   "prompt": "Pick a direction",
   "variants": [
-    { "id": "a", "label": "Editorial Serif", "width": 1440, "height": 1024, "content": "<!DOCTYPE html>...full self-contained HTML..." },
-    { "id": "b", "label": "Bold Brutalist", "width": 1440, "height": 1024, "content": "<!DOCTYPE html>..." },
-    { "id": "c", "label": "Soft & Spacious", "width": 1440, "height": 1024, "content": "<!DOCTYPE html>..." }
+    { "id": "a", "label": "Editorial Serif", "width": 1440, "height": 900, "content": "<!DOCTYPE html>...full self-contained HTML..." },
+    { "id": "b", "label": "Bold Brutalist", "width": 1440, "height": 900, "content": "<!DOCTYPE html>..." },
+    { "id": "c", "label": "Soft & Spacious", "width": 1440, "height": 900, "content": "<!DOCTYPE html>..." }
   ]
 }
 ```
 
 Each `content` is a complete, self-contained document (Alpine.js + Tailwind via CDN, full `<head>`, CSS variables in `:root`). Variations should be **stylistically/structurally distinct** — different typography schools, layout grammars, color moods — never just color swaps. Label them with concrete style names ("Editorial Serif", not "Variant A").
 
-Pass `width`/`height` on every variant to match the form-factor answer (mobile ≈ 390×844, tablet ≈ 768×1024, desktop ≈ 1440×1024) — the example above is desktop-sized. When `content` is omitted, `present-design-variants` infers a size from the prompt/label/description text and the width/height you pass still wins when given.
+Pass `width`/`height` on every variant to match the form-factor answer (mobile ≈ 390×844, tablet ≈ 768×1024, desktop ≈ 1440×900) — the example above is desktop-sized. When `content` is omitted, `present-design-variants` infers a size from the prompt/label/description text and the width/height you pass still wins when given.
 
 Wait for the user's pick before refining. Once they choose, keep the selected
 screen, delete the unchosen variant screens with `delete-file`, and continue
@@ -299,10 +304,11 @@ pnpm action generate-design \
   --prompt "Description of the design" \
   --files '[{"filename":"index.html","content":"<full HTML>","fileType":"html"}]' \
   --tweaks '[{"id":"accent","label":"Accent","type":"color-swatch","options":[...],"defaultValue":"#0EA5E9","cssVar":"--color-accent"}]' \
-  --canvasFrames '[{"filename":"index.html","x":0,"y":0,"width":1440,"height":1024}]'
+  --devices '["desktop","mobile"]' \
+  --canvasFrames '[{"filename":"index.html","x":0,"y":0,"width":1440,"height":900}]'
 ```
 
-Always pass `canvasFrames` with an explicit `width`/`height` matching the form-factor answer (mobile ≈ 390×844, tablet ≈ 768×1024, desktop ≈ 1440×1024 as above) — a screen saved without a placement falls back to a generic default that won't match a desktop-intended design. For multiple screens generated together, call `generate-screens` first and pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen; it returns the matching `canvasFrame` to forward to each `generate-design` call.
+Pass the `devices` param (`("mobile"|"tablet"|"desktop")[]`, default `["desktop","mobile"]`) so a new design renders the right device frames: the widest device becomes the primary `canvasFrames` placement and each narrower device is added as a breakpoint frame of the SAME document — not an extra file. Default to Desktop + Mobile when the form factor is unspecified; never auto-add a tablet or a redundant desktop. When you also pass `canvasFrames` explicitly, size the primary to the widest device (mobile ≈ 390×844, tablet ≈ 768×1024, desktop ≈ 1440×900) — a screen saved without a placement falls back to a generic default that won't match the intended device. For genuinely distinct screens generated together (Home / Dashboard / Checkout — NOT per-device copies of one page), call `generate-screens` first; it returns the matching `canvasFrame` to forward to each `generate-design` call.
 
 #### Non-web sizes — ad units, print one-pagers, social sizes
 
@@ -411,7 +417,11 @@ Every `index.html` must include:
     }
 
     /* Base styles */
-    body { font-family: var(--font-body); }
+    body {
+      font-family: var(--font-body);
+      min-height: 100vh;
+      min-height: 100dvh; /* fill the frame — see Full-height frames below */
+    }
     h1, h2, h3, h4, h5, h6 {
       font-family: var(--font-heading);
       text-wrap: balance;
@@ -430,14 +440,24 @@ Every `index.html` must include:
   </style>
 </head>
 <body class="bg-[var(--color-primary)] text-[var(--color-text)]">
-  <!-- All interactive state goes on a root x-data -->
-  <div x-data="{ /* component state */ }">
+  <!-- Root wrapper fills the device viewport: prefer min-h-screen over inline height:100vh -->
+  <div x-data="{ /* component state */ }" class="min-h-screen">
     <!-- Content -->
   </div>
 </body>
 </html>
 ```
 
+**Full-height frames.** Overview frames now default to at least the device
+viewport height and grow to fit their own content at their own width
+(Framer-style), so a short page must still fill its frame instead of leaving a
+stubby box. The mandatory `body` rule above sets `min-height: 100dvh` (with a
+`100vh` fallback) for exactly this. Put full-height intent on the top-level
+wrapper with Tailwind's `min-h-screen` rather than raw inline `height: 100vh` —
+the editor keeps device-anchored full-height utilities pinned to the device
+viewport, so a full-height hero fills the frame without triggering runaway
+growth.
+
 ### Alpine.js Patterns
 
 **State management** — use `x-data` on the highest-level container:
@@ -661,7 +681,10 @@ Fontshare `<link>`/`@import` and confirm it renders.
 
 A prototype with more than one screen is **multiple files** in the same design
 (e.g. `index.html`, `dashboard.html`, `checkout.html`). The editor shows them
-all in the artboard/overview and as screen tabs.
+all in the artboard/overview and as screen tabs. This is only for genuinely
+distinct screens — the mobile and desktop views of the *same* page are
+breakpoint frames of ONE document (the `devices` param + the
+`responsive-breakpoints` model), never a second file.
 
 The preview renders each file in a sandboxed `srcdoc` iframe. A real
 `<a href="/pricing">` or `<a href="page.html">` resolves against the *app* URL

package/corpus/templates/design/.agents/skills/responsive-breakpoints/SKILL.md

@@ -27,6 +27,14 @@ scopes to `≤ 809px`). `breakpointUpperBoundPx` in
 
 ## Managing breakpoints
 
+A newly generated design's frame set comes from `generate-design`'s `devices`
+param (`("mobile"|"tablet"|"desktop")[]`, default `["desktop","mobile"]`). The
+cascade is **desktop-base**: the widest requested device is the primary/base
+frame and each narrower device is a breakpoint frame. The default injected set
+is therefore a Desktop base plus a single Mobile (390) breakpoint frame — the
+narrower frame(s) only, never a frame at the primary desktop width and never an
+auto-added tablet.
+
 - `add-breakpoint` — adds a device-width frame to `designs.data.breakpointSet`
   (Framer defaults: Desktop 1200 / Tablet 810 / Phone 390, or custom 320-3840).
   Duplicate widths are ignored.

package/corpus/templates/design/actions/generate-design.ts

@@ -77,15 +77,66 @@ const GENERATION_VIEWPORT_SIZES: Record<
 > = {
   mobile: { width: 390, height: 844 },
   tablet: { width: 768, height: 1024 },
-  desktop: { width: 1440, height: 1024 },
+  desktop: { width: 1440, height: 900 },
 };
+const GENERATION_VIEWPORT_LABELS: Record<GenerationViewport, string> = {
+  mobile: "Mobile",
+  tablet: "Tablet",
+  desktop: "Desktop",
+};
+// Widest → narrowest. The widest requested device seeds the primary/base
+// frame; only the narrower devices become breakpoint frames.
+const DEVICE_WIDTH_ORDER: readonly GenerationViewport[] = [
+  "desktop",
+  "tablet",
+  "mobile",
+];
 const GENERATED_FRAME_GAP = 96;
-const DEFAULT_RESPONSIVE_BREAKPOINTS = [390, 768, 1440].map((widthPx) => ({
-  id: `generated-${widthPx}`,
-  label: widthPx === 390 ? "Mobile" : widthPx === 768 ? "Tablet" : "Desktop",
-  widthPx,
-  prefix: widthToPrefix(widthPx),
-}));
+
+function widestGenerationDevice(
+  devices: readonly GenerationViewport[],
+): GenerationViewport {
+  return (
+    DEVICE_WIDTH_ORDER.find((device) => devices.includes(device)) ??
+    DEFAULT_GENERATION_VIEWPORT
+  );
+}
+
+// Devices used when the caller omits `devices`: the requested primary form
+// factor as the base plus Mobile, unless the primary already is Mobile. The
+// default (desktop primary) therefore yields a Desktop base + Mobile
+// breakpoint, matching the two-screen default.
+function devicesForPrimaryViewport(
+  primaryViewport: GenerationViewport,
+): GenerationViewport[] {
+  return primaryViewport === "mobile"
+    ? ["mobile"]
+    : [primaryViewport, "mobile"];
+}
+
+// Breakpoint frames = every requested device NARROWER than the primary
+// (widest) one, ascending by width. The primary/widest width is never emitted,
+// so a single-device request produces an empty set (one frame, no sub-frames)
+// and no redundant frame ever lands at the base canvas width.
+function breakpointSetForDevices(devices: readonly GenerationViewport[]) {
+  const primaryWidth =
+    GENERATION_VIEWPORT_SIZES[widestGenerationDevice(devices)].width;
+  return Array.from(new Set(devices))
+    .filter((device) => GENERATION_VIEWPORT_SIZES[device].width < primaryWidth)
+    .sort(
+      (a, b) =>
+        GENERATION_VIEWPORT_SIZES[a].width - GENERATION_VIEWPORT_SIZES[b].width,
+    )
+    .map((device) => {
+      const widthPx = GENERATION_VIEWPORT_SIZES[device].width;
+      return {
+        id: `generated-${widthPx}`,
+        label: GENERATION_VIEWPORT_LABELS[device],
+        widthPx,
+        prefix: widthToPrefix(widthPx),
+      };
+    });
+}
 
 const reuseLabelSchema = z
   .object({
@@ -123,16 +174,6 @@ function hasBreakpointSet(value: unknown): boolean {
   return Array.isArray(breakpoints) && breakpoints.length > 0;
 }
 
-function nextGeneratedFrameX(
-  frames: ReturnType<typeof parseCanvasFrameGeometryById>,
-): number {
-  return Object.values(frames).reduce((furthestRight, frame) => {
-    const x = frame.x ?? 0;
-    const width = frame.width ?? 0;
-    return Math.max(furthestRight, x + width + GENERATED_FRAME_GAP);
-  }, 0);
-}
-
 function jsonValuesEqual(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
@@ -393,7 +434,7 @@ const generateDesignAgentParameters = {
       type: "string",
       description:
         "Optional JSON array of overview-canvas placements keyed by filename or fileId. " +
-        "Pass explicit x/y/width/height for every generated screen; desktop is 1440x1024.",
+        "Pass explicit x/y/width/height for every generated screen; desktop is 1440x900.",
     },
     contextPackId: {
       type: "string",
@@ -415,8 +456,20 @@ const generateDesignAgentParameters = {
       type: "string",
       enum: ["mobile", "tablet", "desktop"],
       description:
-        "The requested primary form factor. Defaults to desktop (1440x1024). " +
-        "Set this from the intake answer when no explicit canvasFrames placement is supplied.",
+        "The requested primary form factor. Defaults to desktop (1440x900). " +
+        "Set this from the intake answer when no explicit canvasFrames placement is supplied. " +
+        "Ignored when `devices` is provided (the widest device becomes primary).",
+    },
+    devices: {
+      type: "array",
+      items: { type: "string", enum: ["mobile", "tablet", "desktop"] },
+      description:
+        "Device set for responsive frames. Honor the devices the prompt " +
+        'explicitly names; omit to default to ["desktop","mobile"]. The widest ' +
+        "device becomes the primary/base frame and the narrower devices become " +
+        "breakpoint frames — never a duplicate of the base width and never an " +
+        "auto-added tablet. A single device yields one frame with no breakpoints. " +
+        "When provided, this overrides primaryViewport.",
     },
   },
   required: ["designId", "prompt", "files"],
@@ -438,9 +491,12 @@ const generateDesignAction = defineAction({
     "When `designSystemId` is provided, first use `get-design-system` and apply " +
     "its `agentContext` tokens/docs before writing the file content; do not " +
     "treat the id alone as enough design-system context. " +
-    "Every web design must be responsive. Use a desktop 1440x1024 primary " +
-    "canvas by default, or set `primaryViewport` for an explicitly mobile- or " +
-    "tablet-primary design; this action adds responsive editor breakpoints. " +
+    "Every web design must be responsive. This action adds responsive editor " +
+    "breakpoints: by default a Desktop 1440x900 base frame plus a Mobile " +
+    "breakpoint (no auto tablet, no duplicate desktop). Pass `devices` to honor " +
+    "the form factors the prompt explicitly names — the widest becomes the base " +
+    "frame and the narrower ones become breakpoint frames. Set `primaryViewport` " +
+    "for a mobile- or tablet-primary design when not passing `devices`. " +
     "Do not report a design as ready until this action succeeds. " +
     "When adding multiple screens or states, pass canvasFrames with filenames " +
     "and x/y/width/height so the new screens appear placed on the overview canvas.",
@@ -599,8 +655,20 @@ const generateDesignAction = defineAction({
       .optional()
       .default(DEFAULT_GENERATION_VIEWPORT)
       .describe(
-        "Primary generated viewport. Defaults to desktop (1440x1024); set " +
-          "mobile or tablet only when that is the requested form factor.",
+        "Primary generated viewport. Defaults to desktop (1440x900); set " +
+          "mobile or tablet only when that is the requested form factor. " +
+          "Ignored when `devices` is provided (the widest device wins).",
+      ),
+    devices: z
+      .array(z.enum(["mobile", "tablet", "desktop"]))
+      .optional()
+      .describe(
+        "Explicit device set for responsive frames. Honor the devices the " +
+          'prompt names; omit to default to ["desktop","mobile"]. Widest ' +
+          "device = primary/base frame; narrower devices = breakpoint frames " +
+          "(never the base width, never an auto tablet). One device = a single " +
+          "frame with no breakpoints. When provided, this overrides " +
+          "primaryViewport.",
       ),
   }),
   mcpApp: {
@@ -622,6 +690,7 @@ const generateDesignAction = defineAction({
     tweaks,
     canvasFrames,
     primaryViewport,
+    devices,
     contextPackId,
     contextModeOverride,
     reuseLabels,
@@ -827,6 +896,15 @@ const generateDesignAction = defineAction({
       ...tweak,
       type: tweak.type === "color-swatches" ? "color-swatch" : tweak.type,
     }));
+    // An explicit `devices` list wins over primaryViewport; otherwise derive
+    // the device set from primaryViewport so the default stays Desktop base +
+    // Mobile breakpoint. The widest resolved device seeds the primary frame.
+    const resolvedDevices =
+      devices && devices.length > 0
+        ? devices
+        : devicesForPrimaryViewport(primaryViewport);
+    const resolvedPrimaryViewport = widestGenerationDevice(resolvedDevices);
+    const generatedBreakpointSet = breakpointSetForDevices(resolvedDevices);
     await mutateDesignData({
       designId,
       mutate: (prevData, { updatedAt }) => {
@@ -865,9 +943,77 @@ const generateDesignAction = defineAction({
               : undefined;
           },
         });
-        const viewport = GENERATION_VIEWPORT_SIZES[primaryViewport];
-        let nextX = nextGeneratedFrameX(merged.canvasFrames);
-        const generationFrames = [...merged.placedFrames];
+        const viewport = GENERATION_VIEWPORT_SIZES[resolvedPrimaryViewport];
+        // Frames placed by an earlier call: never moved, and counted as
+        // occupied so a new screen is never dropped on top of one.
+        const preExistingFrameIds = new Set(
+          prevData.canvasFrames && typeof prevData.canvasFrames === "object"
+            ? Object.keys(prevData.canvasFrames as Record<string, unknown>)
+            : [],
+        );
+        const rectOf = (frame: {
+          x?: number;
+          y?: number;
+          width?: number;
+          height?: number;
+          rotation?: number;
+        }) => {
+          const x = frame.x ?? 0;
+          const y = frame.y ?? 0;
+          const width = frame.width ?? 0;
+          const height = frame.height ?? 0;
+          const rotation = frame.rotation ?? 0;
+          if (!rotation || width <= 0 || height <= 0) {
+            return { x, y, width, height };
+          }
+          // Existing frames render rotated about their center; use the rotated
+          // rect's axis-aligned bounding box so a new screen isn't dropped over
+          // a rotated frame's real footprint.
+          const radians = (rotation * Math.PI) / 180;
+          const cos = Math.abs(Math.cos(radians));
+          const sin = Math.abs(Math.sin(radians));
+          const aabbWidth = width * cos + height * sin;
+          const aabbHeight = width * sin + height * cos;
+          return {
+            x: x + width / 2 - aabbWidth / 2,
+            y: y + height / 2 - aabbHeight / 2,
+            width: aabbWidth,
+            height: aabbHeight,
+          };
+        };
+        const framesOverlap = (
+          a: ReturnType<typeof rectOf>,
+          b: ReturnType<typeof rectOf>,
+        ) =>
+          a.width > 0 &&
+          a.height > 0 &&
+          b.width > 0 &&
+          b.height > 0 &&
+          a.x < b.x + b.width &&
+          a.x + a.width > b.x &&
+          a.y < b.y + b.height &&
+          a.y + a.height > b.y;
+        const occupiedRects: Array<ReturnType<typeof rectOf>> = [];
+        for (const id of preExistingFrameIds) {
+          const frame = merged.canvasFrames[id];
+          if (frame) occupiedRects.push(rectOf(frame));
+        }
+        // Keep arg placements for files we're not regenerating; the regenerated
+        // ones are (re)placed below, so rebuild their entries here rather than
+        // carry a pre-relocation position that would fail the isApplied check.
+        const regeneratedFileIds = new Set(savedFiles.map((file) => file.id));
+        const generationFrames = merged.placedFrames.filter(
+          (placed) => !regeneratedFileIds.has(placed.fileId),
+        );
+        for (const placed of generationFrames) {
+          occupiedRects.push(rectOf(placed.frame));
+        }
+        // Relocate target: right of every occupied (rotation-aware) rect.
+        let nextX = occupiedRects.reduce(
+          (right, rect) =>
+            Math.max(right, rect.x + rect.width + GENERATED_FRAME_GAP),
+          0,
+        );
         for (const file of savedFiles) {
           const source = files.find(
             (candidate) => candidate.filename === file.filename,
@@ -875,18 +1021,50 @@ const generateDesignAction = defineAction({
           if (!source || !isRenderableDesignFile(source)) continue;
           const current = merged.canvasFrames[file.id] ?? {};
           if (
+            preExistingFrameIds.has(file.id) &&
             current.x !== undefined &&
             current.y !== undefined &&
             current.width !== undefined &&
             current.height !== undefined
           ) {
+            // An explicit device request resizes the primary frame to the
+            // requested viewport (preserving position/rotation); otherwise a
+            // regenerated screen keeps its exact stored geometry.
+            if (devices && devices.length > 0) {
+              merged.canvasFrames[file.id] = {
+                ...current,
+                width: viewport.width,
+                height: viewport.height,
+              };
+            }
             continue;
           }
+          const width = current.width ?? viewport.width;
+          const height = current.height ?? viewport.height;
+          let x = current.x ?? nextX;
+          let y = current.y ?? 0;
+          // Bump a new screen clear of everything if its requested/default spot
+          // overlaps (e.g. a second screen defaulting to the same origin). The
+          // candidate carries its own rotation so a rotated placement is tested
+          // by its real footprint, not its unrotated rectangle.
+          const candidateRect = rectOf({
+            x,
+            y,
+            width,
+            height,
+            rotation: current.rotation,
+          });
+          if (
+            occupiedRects.some((rect) => framesOverlap(candidateRect, rect))
+          ) {
+            x = nextX;
+            y = 0;
+          }
           const frame = {
-            x: current.x ?? nextX,
-            y: current.y ?? 0,
-            width: current.width ?? viewport.width,
-            height: current.height ?? viewport.height,
+            x,
+            y,
+            width,
+            height,
             z: current.z ?? generationFrames.length,
             ...(current.rotation === undefined
               ? {}
@@ -898,14 +1076,34 @@ const generateDesignAction = defineAction({
             filename: file.filename,
             frame,
           });
-          nextX = frame.x + frame.width + GENERATED_FRAME_GAP;
+          occupiedRects.push(rectOf(frame));
+          nextX = Math.max(nextX, frame.x + frame.width + GENERATED_FRAME_GAP);
         }
         mergedData.canvasFrames = merged.canvasFrames;
         placedFrames = generationFrames;
-        if (!hasBreakpointSet(mergedData.breakpointSet)) {
+        // An explicit `devices` request is authoritative: replace the design's
+        // breakpoint set with the derived one (or drop it for a single device),
+        // so regenerating e.g. as [mobile,tablet,desktop] can't silently retain
+        // a stale narrower set. Without explicit devices, only seed a default
+        // set when none exists — a plain content regen never clobbers the
+        // user's own breakpoints.
+        if (devices && devices.length > 0) {
+          if (generatedBreakpointSet.length > 0) {
+            mergedData.breakpointSet = {
+              id: "generated-responsive",
+              breakpoints: generatedBreakpointSet,
+            };
+          } else {
+            delete mergedData.breakpointSet;
+          }
+          mergedData.breakpointSetUpdatedAt = updatedAt;
+        } else if (
+          generatedBreakpointSet.length > 0 &&
+          !hasBreakpointSet(mergedData.breakpointSet)
+        ) {
           mergedData.breakpointSet = {
             id: "generated-responsive",
-            breakpoints: DEFAULT_RESPONSIVE_BREAKPOINTS,
+            breakpoints: generatedBreakpointSet,
           };
           mergedData.breakpointSetUpdatedAt = updatedAt;
         }
@@ -940,7 +1138,32 @@ const generateDesignAction = defineAction({
             );
           }),
         );
-        return framesApplied && hasBreakpointSet(current.breakpointSet);
+        // For an explicit `devices` request, verify the persisted breakpoint
+        // widths actually match the requested set (not merely that some set
+        // exists), so a partial/stale write is retried rather than accepted.
+        const currentBreakpointWidths = (
+          Array.isArray(
+            (current.breakpointSet as { breakpoints?: unknown })?.breakpoints,
+          )
+            ? (
+                current.breakpointSet as {
+                  breakpoints: Array<{ widthPx?: number }>;
+                }
+              ).breakpoints
+            : []
+        )
+          .map((bp) => bp.widthPx)
+          .filter((w): w is number => typeof w === "number")
+          .sort((a, b) => a - b);
+        const expectedBreakpointWidths = generatedBreakpointSet
+          .map((bp) => bp.widthPx)
+          .sort((a, b) => a - b);
+        const breakpointSetApplied =
+          devices && devices.length > 0
+            ? jsonValuesEqual(currentBreakpointWidths, expectedBreakpointWidths)
+            : generatedBreakpointSet.length === 0 ||
+              hasBreakpointSet(current.breakpointSet);
+        return framesApplied && breakpointSetApplied;
       },
     });