@agent-native/core 0.90.1 → 0.90.2

package/corpus/templates/content/app/root.tsx

@@ -38,6 +38,7 @@ import {
   useLoaderData,
   useLocation,
   useNavigate,
+  useNavigation,
   useRouteLoaderData,
   useRouteError,
 } from "react-router";
@@ -209,6 +210,26 @@ function AppSetup() {
   return null;
 }
 
+function RouteTransitionIndicator() {
+  const navigation = useNavigation();
+  const pending = navigation.state !== "idle";
+
+  return (
+    <div
+      className="pointer-events-none fixed inset-x-0 top-0 z-[100] h-0.5 overflow-hidden"
+      aria-hidden={!pending}
+      role="progressbar"
+      data-pending={pending ? "true" : undefined}
+    >
+      <div
+        className={`h-full bg-primary shadow-[0_0_12px_hsl(var(--primary)/0.45)] transition-all duration-200 ${
+          pending ? "w-2/3 opacity-100" : "w-0 opacity-0"
+        }`}
+      />
+    </div>
+  );
+}
+
 function ThemeToggleItem() {
   const { theme, setTheme } = useTheme();
   const t = useT();
@@ -585,6 +606,7 @@ export default function Root() {
       >
         <AppSetup />
         <Toaster />
+        <RouteTransitionIndicator />
         <ContentCommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} />
         <Outlet />
       </AppProviders>

package/corpus/templates/content/changelog/2026-07-01-builder-database-sources-keep-loading-rows-in-the-background.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-01
+---
+
+Builder database sources keep loading rows in the background with clearer progress and page-opening feedback.

package/corpus/templates/content/changelog/2026-07-01-builder-source-attach-starts-with-usable-rows.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-01
+---
+
+Builder source attachment now starts with a usable first batch of rows while larger docs/blog collections continue loading.

package/corpus/templates/content/changelog/2026-07-01-builder-source-attachment-now-stays-connected-after-large.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-01
+---
+
+Builder source attachment now stays connected after large collections finish attaching.

package/corpus/templates/content/changelog/2026-07-01-builder-source-refreshes-now-show-progress-for-large-docs-blog.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-01
+---
+
+Builder source refreshes now show progress and keep large docs/blog databases usable while large row sets load incrementally.

package/corpus/templates/content/changelog/2026-07-01-database-pages-now-delete-to-trash-without-route-errors.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-01
+---
+
+Database pages now delete to Trash without leaving the app on a failed page route.

package/corpus/templates/content/changelog/2026-07-02-builder-source-refreshes-recover-from-stalled-background-row.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-02
+---
+
+Builder source refreshes recover from stalled background row loading.

package/corpus/templates/content/changelog/2026-07-02-builder-sourced-rows-open-with-sync-protection.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-02
+---
+
+Builder-sourced database rows now open with sync protection immediately and keep source-field columns stable during background refreshes.

package/corpus/templates/content/changelog/2026-07-02-database-rows-and-pages-open-faster-from-recently-loaded-dat.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-02
+---
+
+Database rows and pages open faster from recently loaded data.

package/corpus/templates/content/changelog/2026-07-02-preview-panels-close-reliably-narrow-sidebar-row-actions-sta.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-02
+---
+
+Preview panels close reliably, narrow sidebar row actions stay reachable, and adding properties now shows progress.

package/corpus/templates/content/changelog/2026-07-06-builder-sync-progress-no-longer-shows-continue.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-06
+---
+
+Builder sync progress no longer shows a Continue button while loading is already continuing automatically.

package/corpus/templates/content/shared/api.ts

@@ -98,6 +98,8 @@ export interface DocumentUpdateRequest {
   content?: string;
   icon?: string | null;
   isFavorite?: boolean;
+  loadedUpdatedAt?: string;
+  loadedContentWasEmpty?: boolean;
 }
 
 export interface DocumentUpdateResponse extends Document {
@@ -587,6 +589,12 @@ export interface ContentDatabaseSource {
     liveReadConfigured?: boolean;
     lastReadEntryCount?: number;
     lastReadMatchedRowCount?: number;
+    lastReadLimit?: number;
+    lastReadFetchedEntryCount?: number;
+    lastReadPartial?: boolean;
+    lastReadHasMore?: boolean;
+    lastReadNextOffset?: number;
+    sourceFetchState?: "idle" | "fetching" | "error";
     allowDraftWrites?: boolean;
     allowPublishWrites?: boolean;
     allowedWriteModes?: ContentDatabaseSourcePushMode[];
@@ -814,6 +822,7 @@ export interface RefreshContentDatabaseSourceRequest {
   databaseId?: string;
   documentId?: string;
   sourceId?: string;
+  fullRefresh?: boolean;
 }
 
 export interface DisconnectContentDatabaseSourceRequest {
@@ -826,6 +835,8 @@ export interface AddContentDatabaseSourceFieldPropertyRequest {
   databaseId?: string;
   documentId?: string;
   sourceFieldId: string;
+  sourceId?: string;
+  sourceFieldKey?: string;
 }
 
 export interface BindContentDatabaseSourceFieldRequest {
@@ -962,6 +973,8 @@ export interface ContentDatabaseSourceReviewPayload {
   summary: string;
   sourceName: string;
   sourceTable: string;
+  totalRowCount?: number;
+  preparedRowLimit?: number;
   pushMode: ContentDatabaseSourcePushMode;
   dryRunOnly: boolean;
   liveWritesEnabled: boolean;

package/corpus/templates/content/shared/builder-mdx.ts

@@ -929,6 +929,16 @@ function rawRefData(args: {
   };
 }
 
+function escapeBuilderMdxText(value: string) {
+  return value.replace(/(^|[^\\])([<{}])/g, (_match, prefix, character) => {
+    return `${prefix}\\${character}`;
+  });
+}
+
+function unescapeBuilderMdxText(value: string) {
+  return value.replace(/\\([<{}])/g, "$1");
+}
+
 interface BlocksToMdxContext {
   rawRoot: string;
   files: Record<string, string>;
@@ -988,7 +998,9 @@ async function builderBlockToMdx(
   if (name === "Text") {
     const data: BuilderTextData = {
       ...raw,
-      body: htmlToMarkdown(String(options.text ?? "")).trim(),
+      body: escapeBuilderMdxText(
+        htmlToMarkdown(String(options.text ?? "")).trim(),
+      ),
     };
     return serializeRegistryBlockToMdx("builder-text", {
       id,
@@ -1831,14 +1843,15 @@ function applyTextData(
   const block = rawBlockForData(data, sidecars);
   const rawOptions = componentOptions(block);
   const originalBody = htmlToMarkdown(String(rawOptions.text ?? ""));
+  const body = unescapeBuilderMdxText(data.body);
   if (
-    normalizeMarkdownForCompare(data.body) ===
+    normalizeMarkdownForCompare(body) ===
     normalizeMarkdownForCompare(originalBody)
   ) {
     return block;
   }
   const options = ensureComponentOptions(block, data.componentName ?? "Text");
-  options.text = markdownToBuilderTextHtml(data.body);
+  options.text = markdownToBuilderTextHtml(body);
   return block;
 }
 

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,9 +245,12 @@ 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.
@@ -661,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

@@ -259,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,
@@ -338,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