@agent-native/core 0.88.0 → 0.90.2

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

@@ -5,12 +5,56 @@ import {
 } from "@agent-native/core/blocks/server";
 import { z } from "zod";
 
+export type SourceComponentEditState =
+  | "safe-to-edit"
+  | "needs-review"
+  | "preserved-only";
+
+export type SourceComponentMappingStatus = "mapped" | "preserved" | "unknown";
+
+const sourceComponentMappingStatuses = [
+  "mapped",
+  "preserved",
+  "unknown",
+] as const satisfies readonly SourceComponentMappingStatus[];
+
+const sourceComponentEditStates = [
+  "safe-to-edit",
+  "needs-review",
+  "preserved-only",
+] as const satisfies readonly SourceComponentEditState[];
+
+const sourceComponentPreviewStatuses = [
+  "available",
+  "unavailable",
+  "warning",
+] as const satisfies readonly SourceComponentData["previewStatus"][];
+
+const sourceComponentPreviewKinds = [
+  "summary",
+  "table",
+  "embed",
+  "symbol",
+  "component",
+] as const satisfies readonly SourceComponentData["previewKind"][];
+
+function enumAttr<T extends string>(
+  value: string | undefined,
+  allowed: readonly T[],
+): T | undefined {
+  return allowed.includes(value as T) ? (value as T) : undefined;
+}
+
 export interface SourceComponentData {
   provider: string;
   componentName: string;
   rawRef: string;
   rawHash: string;
   sourceLabel?: string;
+  mappingId?: string;
+  mappingStatus?: SourceComponentMappingStatus;
+  mappingReason?: string;
+  sourceEditState?: SourceComponentEditState;
   previewStatus?: "available" | "unavailable" | "warning";
   previewKind?: "summary" | "table" | "embed" | "symbol" | "component";
   previewUrl?: string;
@@ -78,6 +122,12 @@ export const sourceComponentSchema = z.object({
   rawRef: z.string().trim().min(1),
   rawHash: z.string().trim().min(1),
   sourceLabel: z.string().trim().max(200).optional(),
+  mappingId: z.string().trim().max(120).optional(),
+  mappingStatus: z.enum(["mapped", "preserved", "unknown"]).optional(),
+  mappingReason: z.string().trim().max(1_000).optional(),
+  sourceEditState: z
+    .enum(["safe-to-edit", "needs-review", "preserved-only"])
+    .optional(),
   previewStatus: z.enum(["available", "unavailable", "warning"]).optional(),
   previewKind: z
     .enum(["summary", "table", "embed", "symbol", "component"])
@@ -97,6 +147,10 @@ export const sourceComponentMdx: BlockMdxConfig<SourceComponentData> = {
     rawRef: data.rawRef,
     rawHash: data.rawHash,
     sourceLabel: data.sourceLabel,
+    mappingId: data.mappingId,
+    mappingStatus: data.mappingStatus,
+    mappingReason: data.mappingReason,
+    sourceEditState: data.sourceEditState,
     previewStatus: data.previewStatus,
     previewKind: data.previewKind,
     previewUrl: data.previewUrl,
@@ -111,12 +165,24 @@ export const sourceComponentMdx: BlockMdxConfig<SourceComponentData> = {
     rawRef: attrs.string("rawRef") ?? "",
     rawHash: attrs.string("rawHash") ?? "",
     sourceLabel: attrs.string("sourceLabel"),
-    previewStatus: attrs.string("previewStatus") as
-      | SourceComponentData["previewStatus"]
-      | undefined,
-    previewKind: attrs.string("previewKind") as
-      | SourceComponentData["previewKind"]
-      | undefined,
+    mappingId: attrs.string("mappingId"),
+    mappingStatus: enumAttr(
+      attrs.string("mappingStatus"),
+      sourceComponentMappingStatuses,
+    ),
+    mappingReason: attrs.string("mappingReason"),
+    sourceEditState: enumAttr(
+      attrs.string("sourceEditState"),
+      sourceComponentEditStates,
+    ),
+    previewStatus: enumAttr(
+      attrs.string("previewStatus"),
+      sourceComponentPreviewStatuses,
+    ),
+    previewKind: enumAttr(
+      attrs.string("previewKind"),
+      sourceComponentPreviewKinds,
+    ),
     previewUrl: attrs.string("previewUrl"),
     previewItems: attrs.array<string>("previewItems"),
     preview: attrs.object<SourceComponentPreview>("preview"),

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

@@ -317,12 +317,28 @@ function contentLocalComponentsPlugin(): Plugin {
         });
         return refreshPromise;
       };
+      // Coalesce rapid successive component-file writes (agents and editor
+      // atomic saves fire several add/unlink events per logical change) into
+      // a single full reload. Module invalidation stays immediate so the next
+      // request always sees fresh content.
+      let fullReloadTimer: ReturnType<typeof setTimeout> | null = null;
+      const scheduleFullReload = () => {
+        if (fullReloadTimer) clearTimeout(fullReloadTimer);
+        fullReloadTimer = setTimeout(() => {
+          fullReloadTimer = null;
+          server.ws.send({ type: "full-reload" });
+        }, 500);
+      };
+      server.httpServer?.once("close", () => {
+        if (fullReloadTimer) clearTimeout(fullReloadTimer);
+        fullReloadTimer = null;
+      });
       const invalidateComponents = (fullReload = false) => {
         const mod = server.moduleGraph.getModuleById(
           RESOLVED_LOCAL_COMPONENTS_MODULE_ID,
         );
         if (mod) server.moduleGraph.invalidateModule(mod);
-        if (fullReload) server.ws.send({ type: "full-reload" });
+        if (fullReload) scheduleFullReload();
       };
 
       await fs.promises.mkdir(registryDir, { recursive: true });

package/corpus/templates/design/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

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

@@ -196,6 +196,8 @@ pnpm action show-design-questions \
   --questions '[{"id":"form_factor","type":"text-options","question":"What form factor?","options":[{"label":"Desktop web app","value":"desktop"},{"label":"Mobile app","value":"mobile"},{"label":"Both / responsive","value":"responsive"},{"label":"Decide for me","value":"decide"}],"allowOther":true}]'
 ```
 
+**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.
+
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)
 
 For new designs, default to **three** variations (`present-design-variants`
@@ -209,15 +211,17 @@ screen name.
   "designId": "<the design id>",
   "prompt": "Pick a direction",
   "variants": [
-    { "id": "a", "label": "Editorial Serif", "content": "<!DOCTYPE html>...full self-contained HTML..." },
-    { "id": "b", "label": "Bold Brutalist", "content": "<!DOCTYPE html>..." },
-    { "id": "c", "label": "Soft & Spacious", "content": "<!DOCTYPE html>..." }
+    { "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>..." }
   ]
 }
 ```
 
 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.
+
 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
 from the kept screen by calling `get-design-snapshot` with the selected
@@ -241,28 +245,40 @@ pnpm action generate-design \
   --designId "<id>" \
   --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"}]'
+  --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}]'
 ```
 
+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.
+
 ### Phase 4 — Always ship tweaks with the 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 — Audit, fix, and eyeball before calling it ready
+### Phase 5 — Audit, screenshot, 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.
-
-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.
+focus-visibility, reduced-motion coverage, a contrast hint, and — for
+multi-screen designs — token drift against `index.html`'s `:root` block. For
+every `error`-severity finding with `fixAvailable: true`, call
+`apply-a11y-fix`; for findings that aren't auto-fixable (missing alt text,
+structural issues, token drift), 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.
+
+After the audit is clean, call `take-design-screenshot` on each changed screen
+(default: 1280px desktop + 375px mobile). Fix everything its `diagnostics`
+report flags — real computed contrast ratios, horizontal/container overflow,
+broken images, zero-size or off-screen text, console errors — before reporting
+the design as ready; this is the same "visually inspect the result" pass, done
+against the real rendered DOM/CSS instead of by eye. If Chromium isn't
+available in the current environment, it returns `{ ok: false, reason }`
+instead — fall back to a careful read of the HTML plus the audit findings. The
+returned screenshot `url` is for human review (embed it as `![...](url)` in
+your reply); also still scan the rendered output yourself for anything the
+diagnostics don't catch — broken hierarchy, empty/loading/error states for app
+UI, and whether the copy/content still sounds real.
 
 ## HTML Structure Requirements
 
@@ -652,15 +668,18 @@ 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.
+- **Breakpoints**: `add-breakpoint` adds a device-width frame (Framer
+  defaults Phone 390 / Tablet 810 / Desktop 1200, or a custom width) to the
+  design's breakpoint set stored in `designs.data`; duplicate widths are
+  ignored. `remove-breakpoint` removes one by id. `set-active-breakpoint`
+  sets which frame is the current edit scope. Breakpoint frames are ONE
+  document rendered at different widths with a Framer-style cascade: the
+  primary (widest) frame is the base, and edits at a narrower active
+  breakpoint persist as width-scoped overrides (`max-[<bound>px]:` classes
+  or managed `@media` rules) that cascade down. Always check the active
+  breakpoint before a responsive-only edit, and pass `activeFrameWidthPx`
+  to `apply-visual-edit` so the write lands at the right scope. Read the
+  `responsive-breakpoints` skill for the full model.
 - **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

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

@@ -0,0 +1,98 @@
+---
+name: responsive-breakpoints
+description: >-
+  Framer-style responsive breakpoint editing in Design: one DOM tree per
+  screen with cascading width-scoped overrides. Use when adding/removing
+  breakpoints, editing a design at a specific device width, resolving which
+  value renders at a width, or persisting responsive style changes.
+---
+
+# Responsive Breakpoints
+
+Design uses the **Framer model**: every screen is ONE document (one DOM
+tree). Breakpoint frames are the SAME document rendered at different
+viewport widths — never separate copies. Edits cascade:
+
+- The **base** is the primary (widest) frame. Base edits are plain
+  unprefixed classes / inline styles and cascade down to every narrower
+  breakpoint unless overridden there.
+- Edits made while a **narrower breakpoint is active** persist as
+  width-scoped overrides that apply from just below the next-wider frame
+  down to zero. Narrower breakpoints layer their own overrides on top.
+
+The bound for an override is `next-wider frame width - 1` (e.g. breakpoints
+390/810 with a 1280 primary: editing 810 scopes to `≤ 1279px`, editing 390
+scopes to `≤ 809px`). `breakpointUpperBoundPx` in
+`shared/responsive-classes.ts` is the canonical implementation.
+
+## Managing breakpoints
+
+- `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.
+- `remove-breakpoint` — removes one by id (overrides already written stay in
+  the document until removed).
+- `set-active-breakpoint` — persists the active edit scope to application
+  state (`design-active-breakpoint:<designId>`); the UI mirrors it in the
+  `design-selection` state (`activeBreakpointId`). Check the active
+  breakpoint via `view-screen` before making responsive-only edits.
+
+The UI's breakpoint bar (chips above the focused screen) and the overview's
+side-by-side linked frames drive the same state — a chip click changes the
+iframe viewport width AND calls `set-active-breakpoint`.
+
+## Editing responsively (agent parity)
+
+Use `apply-visual-edit` with `activeFrameWidthPx` set to the ACTIVE
+breakpoint frame width. This scopes BOTH `class` and `style` intents
+uniformly through one class-vs-media decision:
+
+- Values that are Tailwind utilities (`text-lg`, `p-4`) become width-scoped
+  classes: `max-[809px]:text-lg` (arbitrary max-width variants the Tailwind
+  CDN JIT compiles to `@media (max-width: 809px)`).
+- Raw CSS values (`137px`, `rgb(...)`, `calc(...)`) persist into the managed
+  `<style data-agent-native-breakpoints>` block as
+  `@media (max-width: <bound>px)` rules targeting the element's
+  `data-agent-native-node-id`. The block is deterministic (wider buckets
+  first so narrower ranges win by source order) and readable/editable in the
+  Code panel.
+
+Other targeting options:
+
+- `maxWidthPx` — explicit desktop-down bound, overrides derivation.
+- `intent.kind: "breakpoint-style"` — direct managed-media write/remove:
+  `{ target, maxWidthPx, property, value, operation: "set" | "remove" }`.
+- `activeBreakpoint: "md"` etc. — LEGACY min-width prefix scoping for class
+  edits only (mobile-first `md:text-lg`). Still supported for documents
+  authored mobile-first; prefer `activeFrameWidthPx` for breakpoint-bar
+  parity.
+
+When the design has no breakpoint set, `activeFrameWidthPx` falls back to
+the legacy min-width prefix behaviour for class edits. When the active frame
+IS the widest context, edits are base writes (correct — the widest frame is
+the base).
+
+## Resolving and inspecting overrides
+
+- `effectiveUtilityAtWidth(className, stem, widthPx)` — which utility
+  renders at a width (narrowest applicable max-width scope wins, then
+  min-width prefixes, then base).
+- `getBreakpointOverrideState({ className, html, nodeId, property,
+  breakpointWidths, baseWidthPx, activeWidthPx })` from
+  `shared/breakpoint-media.ts` — aggregates class + media overrides for the
+  inspector's overridden-at-this-breakpoint indicators.
+- To RESET an override: remove the scoped class
+  (`responsive-class` remove with `maxWidthPx` + stem) or the media rule
+  (`breakpoint-style` with `operation: "remove"`); the base value cascades
+  back down.
+
+## Cautions
+
+- Managed media rules anchor on `data-agent-native-node-id`. Inline (SQL)
+  designs keep these ids; localhost write-back strips them — for local-file
+  sources prefer scoped classes.
+- Never rewrite the managed block wholesale by hand; use the edit intents so
+  same-property writes replace instead of accumulate. The parser tolerates
+  Code-panel edits but unknown selectors are ignored.
+- Adding a breakpoint between two existing widths changes the bound for NEW
+  overrides only; previously written overrides keep their original bounds.

package/corpus/templates/design/.agents/skills/shader-fills/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: shader-fills
+description: >-
+  Code-backed GLSL shader fills and shader effects: authoring WGSL-free,
+  WebGL1 GLSL fragment shaders that persist as readable source in the screen
+  HTML with uniform knobs in the inspector. Use when the user asks for a
+  shader fill or shader effect, sends "Create a custom shader fill." from the
+  fill picker, wants an animated/procedural background (waves, noise, mesh
+  gradients, caustics, grain, halftone), or wants to edit an existing
+  shader's GLSL or uniforms.
+---
+
+# Code-Backed Shader Fills & Effects
+
+Shaders in Design are **code, not opaque assets**. Each shader is a GLSL
+fragment source + JSON uniforms manifest persisted directly in the screen
+HTML, rendered live by a self-contained WebGL runtime that is embedded in the
+same HTML — so shaders work in the editor, in shared links, and in exported
+standalone files. Users see and edit the GLSL in the Code panel; uniform
+knobs appear automatically in the inspector (Fill → Shader paint type, and
+Effects → Shader).
+
+The canonical format module is `shared/shader-fills.ts`. Always prefer its
+helpers over hand-assembling markup.
+
+## Persisted format (v1)
+
+One definition block per shader (place before `</body>`):
+
+```html
+<script type="application/x-agent-native-shader"
+        data-shader-id="an-shader-x1y2z3ab"
+        data-shader-name="Aurora Drift"
+        data-shader-mode="fill">
+/*! an-shader v1
+{
+  "uniforms": {
+    "u_speed":   { "type": "float", "value": 1, "min": 0, "max": 4, "step": 0.01, "label": "Speed" },
+    "u_color_a": { "type": "color", "value": "#4f2d8f", "label": "Base" },
+    "u_center":  { "type": "vec2",  "value": [0.5, 0.5], "label": "Center" }
+  }
+}
+*/
+precision highp float;
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform float u_speed;
+uniform vec3 u_color_a;
+uniform vec2 u_center;
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution;
+  gl_FragColor = vec4(u_color_a * (0.6 + 0.4 * sin(u_time * u_speed + distance(uv, u_center) * 8.0)), 1.0);
+}
+</script>
+```
+
+Element references (both can coexist on one element, like Figma):
+
+```html
+<!-- Fill: canvas rendered BEHIND the element's content. Keep a static
+     fallback background so the artifact renders without JS/WebGL. -->
+<div data-agent-native-node-id="hero"
+     data-an-shader-fill="an-shader-x1y2z3ab"
+     data-an-shader-uniforms='{"u_speed":2}'
+     style="background: #4f2d8f">…</div>
+
+<!-- Effect: transparent overlay canvas ABOVE the content. Per-element
+     overrides live in a separate attribute. -->
+<div data-an-shader-effect="an-shader-grain001"
+     data-an-shader-effect-uniforms='{"u_intensity":0.2}'>…</div>
+```
+
+The runtime must be embedded once per document as
+`<script data-agent-native-shader-runtime data-runtime-version="1">…` —
+`ensureShaderRuntime()` / `applyShaderToHtml()` handle this.
+
+## Applying a shader (preferred path)
+
+Use the pure helpers + the source-edit actions. From `templates/design/`:
+
+```ts
+// script: apply-shader.ts — run with: pnpm exec tsx apply-shader.ts
+import { applyShaderToHtml, newShaderId } from "./shared/shader-fills";
+import { getGlslShaderPreset } from "./shared/shader-presets";
+
+const preset = getGlslShaderPreset("water-caustics")!;
+const result = applyShaderToHtml(currentHtml /* from read-source-file */, {
+  nodeId: "hero", // the element's data-agent-native-node-id
+  def: {
+    id: newShaderId(),
+    name: preset.label,
+    mode: preset.mode, // "fill" | "effect"
+    glsl: preset.glsl,
+    uniforms: preset.uniforms,
+  },
+  fallbackColor: "#06283d", // fills only — static no-JS fallback
+});
+if (result.errors.length) throw new Error(result.errors.join("; "));
+// result.html → write back via apply-source-edit (full-replace) with the
+// versionHash you got from read-source-file.
+```
+
+Action flow: `read-source-file` → transform → `apply-source-edit`
+(`edit: { kind: "full-replace", content }`, pass `expectedVersionHash`).
+For a small hand-edit (e.g. tweaking one uniform value in the manifest),
+`edit-design` search/replace on the exact block text is also fine.
+
+To remove: `removeShaderFromNode(html, nodeId, mode?)` — clears the
+annotation and garbage-collects unreferenced definition blocks.
+
+## Handling "Create a custom shader fill." from the picker
+
+The fill picker's **Create new (AI)** tile prefills this prompt with hidden
+context lines (`designId`, `fileId`, `target nodeId`, `mode`). Then:
+
+1. Ask what look they want only if the user gave no description at all.
+2. Write ORIGINAL GLSL for the request (do not just re-apply a preset), with
+   2–5 well-chosen uniforms exposed as knobs. Name the knobs the way the
+   user described the controls.
+3. Apply it via the helper flow above, targeting the provided nodeId.
+4. Report the shader name, its knobs, and that the GLSL is editable in the
+   Code panel.
+
+## GLSL rules (WebGL1 / GLSL ES 1.00)
+
+- Start with `precision highp float;`. Write to `gl_FragColor`.
+- Declare `uniform vec2 u_resolution;` and `uniform float u_time;` when used
+  — the runtime drives them automatically (`u_time` is seconds; it stays 0
+  under `prefers-reduced-motion`). Never put builtins in the manifest.
+- Every manifest uniform MUST be declared in the GLSL with the mapped type:
+  `float` → `uniform float`, `vec2` → `uniform vec2`, `color` → `uniform
+  vec3` (colors arrive normalized 0–1 RGB). Validation rejects unused knobs.
+- Uniform names match `u_[A-Za-z0-9_]+`; ≤ 16 uniforms; float knobs need
+  `min`/`max`/`step`; color values are `#rrggbb` hex.
+- Loop bounds must be compile-time constant (`for (int i = 0; i < 5; i++)`).
+- Effects are composited over content: output premultiplication is off, so
+  `gl_FragColor = vec4(color, alpha)` with alpha < 1 overlays cleanly.
+- Never include `</script`, `<script`, or `*/`-breaking sequences in GLSL,
+  names, or labels — `validateShaderDef()` enforces this; run it (or
+  `applyShaderToHtml`, which calls it) before writing.
+
+## Preset library
+
+`GLSL_SHADER_PRESETS` in `shared/shader-presets.ts` ships 12 curated
+presets — fills: `mesh-gradient`, `glowing-wave`, `water-caustics`,
+`fractal-noise`, `clouds`, `nebula`, `moire`, `concentric-rings`,
+`pattern-grid`; effects: `film-grain`, `halftone`, `scanlines`. Applying a
+preset stamps a fresh copy (new id) into the design; after that it is the
+user's code to edit.
+
+## Fills vs effects
+
+| | Fill (`data-an-shader-fill`) | Effect (`data-an-shader-effect`) |
+|---|---|---|
+| Canvas position | Behind content (negative z-index in an isolated stacking context, above the element's own background) | Overlay above content, `pointer-events: none` |
+| Output | Opaque pixels (a material) | Transparent overlay (alpha compositing) |
+| Fallback | Element keeps a static `background` color | Degrades to no overlay |
+| Overrides attr | `data-an-shader-uniforms` | `data-an-shader-effect-uniforms` |
+
+Failures (no WebGL, compile error, > 8 mounts per screen) remove the canvas
+and record the reason in `data-an-shader-error` on the element — check that
+attribute when a shader "isn't showing".

package/corpus/templates/design/AGENTS.md

@@ -30,8 +30,9 @@ patterns live in `.agents/skills/`.
   screens, linked design systems, tokens, and component language before
   inventing a new direction. Use realistic content/copy and one signature choice
   per direction; avoid lorem ipsum, generic SaaS filler, and decorative
-  placeholders. Include expected responsive/accessibility states and visually
-  inspect the result before calling it ready.
+  placeholders. Include expected responsive/accessibility states, run
+  `run-design-audit`, and call `take-design-screenshot` on each changed screen
+  before calling it ready — see the `design-generation` skill's Phase 5.
 - For editable reusable building blocks inside Design, use
   `list-design-native-assets` first, then `insert-design-native-asset` with the
   chosen kind. These are Design-native HTML primitives/components, not external
@@ -258,8 +259,10 @@ patterns live in `.agents/skills/`.
   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.
+  frame new edits target. Breakpoint frames are one document with a
+  Framer-style cascade (base = widest frame; narrower-frame edits persist as
+  width-scoped overrides via `apply-visual-edit` + `activeFrameWidthPx`).
+  Read the `responsive-breakpoints` skill before responsive edits.
 - **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,
@@ -337,9 +340,14 @@ and requires Builder connected. See `full-app-build` skill for the full flow.
 Read the relevant skill before deeper work:
 
 - `design-generation` for creating/editing prototype HTML and variant flows.
+- `responsive-breakpoints` for Framer-style breakpoint editing (single DOM,
+  cascading width-scoped overrides, the managed breakpoints media block).
 - `design-systems` for tokens, brand extraction, and linked systems.
 - `export-handoff` for HTML/PNG/SVG/ZIP/code handoff.
 - `full-app-build` for flag-gated fusion-backed full app building.
+- `shader-fills` for code-backed GLSL shader fills/effects (editable source
+  in screen HTML, uniform knobs, preset library, and the picker's "Create a
+  custom shader fill." prompt).
 - `frontend-design` and `shadcn-ui` for app UI changes.
 - `actions`, `delegate-to-agent`, `security`, and `self-modifying-code` for
   framework patterns.

package/corpus/templates/design/actions/add-breakpoint.ts

@@ -63,9 +63,12 @@ export default defineAction({
   description:
     "Add a breakpoint frame to the design's breakpoint set. " +
     "The breakpoint set is stored in designs.data and controls which side-by-side " +
-    "device widths are shown in the overview canvas (Mobile 390 / Tablet 768 / Desktop 1280, " +
-    "or a custom width). The Tailwind prefix is derived automatically from the width. " +
-    "Duplicate widths are silently ignored.",
+    "device widths are shown in the overview canvas and the editor's breakpoint bar " +
+    "(Framer defaults: Phone 390 / Tablet 810 / Desktop 1200, or a custom width). " +
+    "Every frame renders the SAME document at its own viewport width (Framer model); " +
+    "edits made at a narrower active frame persist as width-scoped overrides that " +
+    "cascade down (see the responsive-breakpoints skill). The legacy Tailwind prefix " +
+    "is derived automatically from the width. Duplicate widths are silently ignored.",
   schema: z.object({
     designId: z.string().describe("Design project ID"),
     label: z