@agent-native/core 0.80.8 → 0.80.10

package/corpus/templates/design/app/components/design/inspector/DesignColorPicker.tsx

@@ -14,6 +14,7 @@ import type { ShaderDescriptor } from "@shared/shader-presets";
 import { IconChevronDown, IconColorPicker } from "@tabler/icons-react";
 import {
   useEffect,
+  useMemo,
   useRef,
   useState,
   type JSX,
@@ -27,6 +28,13 @@ import {
   PopoverContent,
   PopoverTrigger,
 } from "@/components/ui/popover";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
 import {
   Tooltip,
   TooltipContent,
@@ -130,6 +138,7 @@ export interface DesignColorPickerProps {
   value: string;
   onChange: (value: string) => void;
   onPaintValueChange?: (value: string) => void;
+  onImageFillChange?: (value: ImageFillValue) => void;
   label?: string;
   opacity?: number;
   onOpacityChange?: (opacity: number) => void;
@@ -191,6 +200,87 @@ interface HsvaColor {
 
 const FALLBACK_COLOR: RgbaColor = { r: 0, g: 0, b: 0, a: 1 };
 
+// ─── Extended CSS color parser ──────────────────────────────────────────────────
+//
+// `parseCssColor` from color-utils handles hex, comma-separated rgb/rgba, and
+// hsl/hsla. Browsers increasingly emit modern CSS Level 4 formats from
+// getComputedStyle: space-separated `rgb(R G B)`, `rgb(R G B / A)`, and
+// opaque formats like `oklch(...)` or `color(display-p3 ...)`.
+//
+// This local wrapper extends the parser to cover those cases so that colors
+// arriving from the canvas's computed-style bridge are always usable.
+
+const MODERN_RGB_PATTERN =
+  /^rgba?\(\s*([0-9.]+)\s+([0-9.]+)\s+([0-9.]+)(?:\s*\/\s*([0-9.]+%?))?\s*\)$/i;
+
+/** Canvas element reused across calls for DOM-based color resolution. */
+let _resolverCanvas: HTMLCanvasElement | null = null;
+let _resolverCtx: CanvasRenderingContext2D | null = null;
+
+/**
+ * Parses a CSS color string into RgbaColor, extending the base parser with:
+ *   - Modern space-separated `rgb(R G B)` / `rgb(R G B / A)` syntax
+ *   - Opaque formats (oklch, color, etc.) resolved via a hidden canvas
+ *
+ * Falls back to null if the value is unparseable and the DOM is unavailable.
+ */
+function parseCssColorExtended(value: string): RgbaColor | null {
+  // 1. Try the standard parser first (handles hex, comma rgb/rgba, hsl/hsla).
+  const standard = parseCssColor(value);
+  if (standard) return standard;
+
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === "transparent" || trimmed === "none") return null;
+
+  // 2. Modern space-separated rgb/rgba — CSS Level 4.
+  const modernRgb = trimmed.match(MODERN_RGB_PATTERN);
+  if (modernRgb) {
+    const parseAlphaLocal = (v: string | undefined): number => {
+      if (!v) return 1;
+      if (v.endsWith("%"))
+        return Math.max(0, Math.min(1, Number(v.slice(0, -1)) / 100));
+      return Math.max(0, Math.min(1, Number(v)));
+    };
+    return {
+      r: Math.round(Math.max(0, Math.min(255, Number(modernRgb[1])))),
+      g: Math.round(Math.max(0, Math.min(255, Number(modernRgb[2])))),
+      b: Math.round(Math.max(0, Math.min(255, Number(modernRgb[3])))),
+      a: parseAlphaLocal(modernRgb[4]),
+    };
+  }
+
+  // 3. DOM-based resolver for oklch, color(display-p3 ...), hsl (modern), etc.
+  //    Uses a hidden 1×1 canvas to resolve any valid CSS color to rgb().
+  if (typeof document === "undefined") return null;
+  try {
+    if (!_resolverCanvas) {
+      _resolverCanvas = document.createElement("canvas");
+      _resolverCanvas.width = 1;
+      _resolverCanvas.height = 1;
+    }
+    if (!_resolverCtx) {
+      _resolverCtx = _resolverCanvas.getContext("2d", {
+        willReadFrequently: true,
+      });
+    }
+    const ctx = _resolverCtx;
+    if (!ctx) return null;
+    // Detect invalid color values: save fillStyle before and after assignment.
+    // If the browser rejects the value, fillStyle won't change.
+    const prev = ctx.fillStyle;
+    ctx.fillStyle = trimmed;
+    const next = ctx.fillStyle; // browser normalises to rgb/hex on accept
+    // If the value was rejected, fillStyle stays at the previous value.
+    if (next === prev) return null;
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    return { r, g, b, a: a / 255 };
+  } catch {
+    return null;
+  }
+}
+
 const DEFAULT_LABELS: DesignColorPickerLabels = {
   trigger: "Open color picker", // i18n-ignore fallback component label
   hex: "Hex", // i18n-ignore fallback component label
@@ -568,6 +658,24 @@ const NOISE_FALLBACK_CSS =
   "repeating-conic-gradient(#0000 0% 25%, #00000010 0% 50%) 0 0 / 6px 6px, #8a8a8a";
 const PATTERN_FALLBACK_CSS =
   "repeating-linear-gradient(45deg, #00000014 0 6px, #ffffff14 6px 12px), #9aa0a6";
+const BLEND_MODE_OPTIONS = [
+  { value: "normal", label: "Normal" },
+  { value: "multiply", label: "Multiply" },
+  { value: "screen", label: "Screen" },
+  { value: "overlay", label: "Overlay" },
+  { value: "darken", label: "Darken" },
+  { value: "lighten", label: "Lighten" },
+  { value: "color-dodge", label: "Color dodge" }, // i18n-ignore design blend mode label
+  { value: "color-burn", label: "Color burn" }, // i18n-ignore design blend mode label
+  { value: "hard-light", label: "Hard light" }, // i18n-ignore design blend mode label
+  { value: "soft-light", label: "Soft light" }, // i18n-ignore design blend mode label
+  { value: "difference", label: "Difference" },
+  { value: "exclusion", label: "Exclusion" },
+  { value: "hue", label: "Hue" },
+  { value: "saturation", label: "Saturation" },
+  { value: "color", label: "Color" },
+  { value: "luminosity", label: "Luminosity" },
+] as const;
 
 // ─── Main component ────────────────────────────────────────────────────────────
 
@@ -575,12 +683,13 @@ export function DesignColorPicker({
   value,
   onChange,
   onPaintValueChange,
+  onImageFillChange,
   label: _label,
   opacity,
   onOpacityChange,
-  blendMode: _blendMode,
-  onBlendModeChange: _onBlendModeChange,
-  showBlendMode: _showBlendMode,
+  blendMode,
+  onBlendModeChange,
+  showBlendMode = false,
   fillRows: _fillRows,
   selectedFillId: _selectedFillId,
   onFillSelect: _onFillSelect,
@@ -605,10 +714,15 @@ export function DesignColorPicker({
   className,
 }: DesignColorPickerProps) {
   const copy = { ...DEFAULT_LABELS, ...labels };
-  const color = parseCssColor(value) ?? FALLBACK_COLOR;
+  const color = parseCssColorExtended(value) ?? FALLBACK_COLOR;
   const hsv = rgbaToHsv(color);
   const hsl = rgbaToHsl(color);
   const effectiveOpacity = opacity ?? alphaToOpacity(color.a);
+  const blendModeValue = BLEND_MODE_OPTIONS.some(
+    (option) => option.value === blendMode,
+  )
+    ? blendMode
+    : "normal";
 
   const [mode, setMode] = useState<DesignColorMode>("hex");
   const [hexDraft, setHexDraft] = useState(() => toDisplayHex(color));
@@ -651,16 +765,24 @@ export function DesignColorPicker({
 
   // Resolve the active gradient: prefer EditPanel-driven props; otherwise parse
   // the live CSS value, falling back to local edit state.
-  const parsedGradient = parseGradientCss(value, gradientType ?? "linear");
+  const parsedGradient = useMemo(
+    () => parseGradientCss(value, gradientType ?? "linear"),
+    [gradientType, value],
+  );
+  const fallbackGradient = useMemo(
+    () =>
+      GRADIENT_TYPES.has(effectivePaintType)
+        ? defaultGradient(
+            effectivePaintType as GradientKind,
+            toCssColor(color) || "#000000",
+          )
+        : null,
+    [color.r, color.g, color.b, color.a, effectivePaintType],
+  );
   const activeGradient: GradientValue | null = GRADIENT_TYPES.has(
     effectivePaintType,
   )
-    ? (localGradient ??
-      parsedGradient ??
-      defaultGradient(
-        effectivePaintType as GradientKind,
-        toCssColor(color) || "#000000",
-      ))
+    ? (localGradient ?? parsedGradient ?? fallbackGradient)
     : null;
 
   useEffect(() => {
@@ -754,7 +876,8 @@ export function DesignColorPicker({
 
   // The 2D field edits the selected gradient stop's color when in gradient mode.
   const fieldColor: RgbaColor = activeGradient
-    ? (parseCssColor(selectedStop?.color ?? "#000000") ?? FALLBACK_COLOR)
+    ? (parseCssColorExtended(selectedStop?.color ?? "#000000") ??
+      FALLBACK_COLOR)
     : color;
   const rawFieldHsv = rgbaToHsv(fieldColor);
   // Preserve the last non-zero hue so dragging through gray doesn't lose it.
@@ -771,7 +894,7 @@ export function DesignColorPicker({
   const selectedStopColor = selectedStop?.color;
   useEffect(() => {
     if (!activeGradient || !selectedStopColor) return;
-    const parsed = parseCssColor(selectedStopColor);
+    const parsed = parseCssColorExtended(selectedStopColor);
     if (parsed) setHexDraft(toDisplayHex(parsed));
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [selectedStopColor, selectedStopId]);
@@ -807,6 +930,10 @@ export function DesignColorPicker({
 
   const emitImageFill = (next: ImageFillValue) => {
     setImageFill(next);
+    if (onImageFillChange) {
+      onImageFillChange(next);
+      return;
+    }
     emitPaintValue(imageFillToCss(next));
   };
 
@@ -860,6 +987,10 @@ export function DesignColorPicker({
       return;
     }
     if (nextType === "image") {
+      if (onImageFillChange && imageFill.url) {
+        onImageFillChange(imageFill);
+        return;
+      }
       emitPaintValue(imageFill.url ? imageFillToCss(imageFill) : "transparent");
       return;
     }
@@ -1060,8 +1191,18 @@ export function DesignColorPicker({
           align="start"
           sideOffset={8}
           className="z-[10000] w-[252px] p-0 shadow-xl"
+          // Keep the picker open when the style change triggered by a paint-type
+          // switch causes the canvas to re-project the element. Without this,
+          // Radix treats the resulting focus shift as an "interact outside" event
+          // and closes the popover before the type switch is visible.
+          onInteractOutside={(e) => {
+            // Allow closing only for genuine pointer clicks on the canvas area
+            // (the user clicked somewhere else). Programmatic focus changes from
+            // the canvas bridge (element re-projection) should not close the picker.
+            if (e.type === "focusoutside") e.preventDefault();
+          }}
         >
-          <div className="overflow-hidden rounded-md bg-popover text-popover-foreground">
+          <div className="rounded-md bg-popover text-popover-foreground">
             {view === "shader" ? (
               <ShaderFillsPanel
                 descriptor={shaderDescriptor ?? undefined}
@@ -1395,6 +1536,39 @@ export function DesignColorPicker({
                   </div>
                 )}
 
+                {showBlendMode && onBlendModeChange && (
+                  <div className="border-t border-border/70 px-3 py-2.5">
+                    <div className="flex items-center gap-1.5">
+                      <span className="min-w-0 flex-1 text-[11px] text-muted-foreground">
+                        {copy.blendMode}
+                      </span>
+                      <Select
+                        value={blendModeValue}
+                        disabled={disabled}
+                        onValueChange={onBlendModeChange}
+                      >
+                        <SelectTrigger
+                          aria-label={copy.blendMode}
+                          className="h-6 min-w-0 flex-1 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-[11px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)]"
+                        >
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          {BLEND_MODE_OPTIONS.map((option) => (
+                            <SelectItem
+                              key={option.value}
+                              value={option.value}
+                              className="text-[11px]"
+                            >
+                              {option.label}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                    </div>
+                  </div>
+                )}
+
                 {/* ── Document colors ──────────────────────────────────────── */}
                 {/* Renders the palette of colors already used in the design.
                     When `documentColors` is provided, those swatches are shown;

package/corpus/templates/design/app/components/design/inspector/ExportSettingsPanel.tsx

@@ -57,6 +57,9 @@ const DEFAULT_LABELS: ExportSettingsPanelLabels = {
 
 const DEFAULT_FORMATS: ExportFormat[] = ["png", "jpg", "svg", "pdf", "webp"];
 
+const controlChromeClass =
+  "border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-foreground shadow-none hover:bg-[var(--design-editor-panel-raised-bg)] hover:text-foreground focus:ring-1 focus:ring-[var(--design-editor-accent-color)] focus:ring-offset-0 focus-visible:ring-1 focus-visible:ring-[var(--design-editor-accent-color)] focus-visible:ring-offset-0";
+
 // Export scale bounds — must match the clamp in DesignEditor's PNG/SVG export
 // handlers so the panel never promises a range the exporter won't render.
 const MIN_EXPORT_SCALE = 0.1;
@@ -135,7 +138,12 @@ function ScaleSelect({
         }
       }}
     >
-      <SelectTrigger className="h-6 w-14 shrink-0 px-1.5 text-[11px]">
+      <SelectTrigger
+        className={cn(
+          "h-6 w-14 shrink-0 px-1.5 text-[11px]",
+          controlChromeClass,
+        )}
+      >
         <SelectValue />
       </SelectTrigger>
       <SelectContent>
@@ -267,7 +275,7 @@ export function ExportSettingsPanel({
         variant="outline"
         disabled={isDisabled}
         onClick={handleExport}
-        className="h-6 w-full px-2 text-[11px]"
+        className={cn("h-6 w-full px-2 text-[11px]", controlChromeClass)}
       >
         <IconDownload className="size-3.5" />
         {copy.export}
@@ -324,7 +332,10 @@ function ExportRow({
               onPatchRow(row.id, { customScale: false });
             }
           }}
-          className="h-6 w-14 shrink-0 px-1.5 text-[11px] tabular-nums"
+          className={cn(
+            "h-6 w-14 shrink-0 px-1.5 text-[11px] tabular-nums",
+            controlChromeClass,
+          )}
           aria-label="Scale"
           // eslint-disable-next-line jsx-a11y/no-autofocus
           autoFocus
@@ -352,7 +363,12 @@ function ExportRow({
           onPatchRow(row.id, { format: format as ExportFormat })
         }
       >
-        <SelectTrigger className="h-6 min-w-0 flex-1 px-1.5 text-[11px]">
+        <SelectTrigger
+          className={cn(
+            "h-6 min-w-0 flex-1 px-1.5 text-[11px]",
+            controlChromeClass,
+          )}
+        >
           <SelectValue />
         </SelectTrigger>
         <SelectContent>
@@ -376,7 +392,10 @@ function ExportRow({
         disabled={isDisabled}
         onChange={(e) => onPatchRow(row.id, { suffix: e.target.value })}
         placeholder={labels.suffix}
-        className="h-6 min-w-0 flex-1 px-1.5 text-[11px]"
+        className={cn(
+          "h-6 min-w-0 flex-1 px-1.5 text-[11px]",
+          controlChromeClass,
+        )}
         aria-label={labels.suffix}
       />
 

package/corpus/templates/design/app/components/design/inspector/ImageFillControls.tsx

@@ -80,6 +80,59 @@ export function imageFillToCss(value: ImageFillValue): string {
   }
 }
 
+export function imageFillToBackgroundStyles(
+  value: ImageFillValue,
+): Record<
+  | "backgroundImage"
+  | "backgroundSize"
+  | "backgroundRepeat"
+  | "backgroundPosition",
+  string
+> {
+  const url = value.url.trim();
+  if (!url) {
+    return {
+      backgroundImage: "none",
+      backgroundSize: "auto",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "center",
+    };
+  }
+  const safeUrl = url.replace(/["')]/g, encodeURIComponent);
+  const backgroundImage = `url("${safeUrl}")`;
+  switch (value.fit) {
+    case "fit":
+      return {
+        backgroundImage,
+        backgroundSize: "contain",
+        backgroundRepeat: "no-repeat",
+        backgroundPosition: "center",
+      };
+    case "tile":
+      return {
+        backgroundImage,
+        backgroundSize: "auto",
+        backgroundRepeat: "repeat",
+        backgroundPosition: "top left",
+      };
+    case "crop":
+      return {
+        backgroundImage,
+        backgroundSize: "cover",
+        backgroundRepeat: "no-repeat",
+        backgroundPosition: "center",
+      };
+    case "fill":
+    default:
+      return {
+        backgroundImage,
+        backgroundSize: "cover",
+        backgroundRepeat: "no-repeat",
+        backgroundPosition: "center",
+      };
+  }
+}
+
 // Matches url() in three forms:
 //   group 1 — double-quoted:  url("...anything...")
 //   group 2 — single-quoted:  url('...anything...')
@@ -249,7 +302,10 @@ export function ImageFillControls({
         onValueChange={(v) => onChange({ ...value, fit: v as ImageFitMode })}
         disabled={disabled}
       >
-        <SelectTrigger className="h-6 w-full rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-2 text-[11px] shadow-none focus:ring-0 focus:ring-offset-0 focus-visible:ring-2 focus-visible:ring-ring [&>svg]:size-3 [&>svg]:shrink-0">
+        <SelectTrigger
+          aria-label={"Fill" /* i18n-ignore image fit selector */}
+          className="h-6 w-full rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-2 text-[11px] shadow-none focus:ring-0 focus:ring-offset-0 focus-visible:ring-2 focus-visible:ring-ring [&>svg]:size-3 [&>svg]:shrink-0"
+        >
           <SelectValue />
         </SelectTrigger>
         <SelectContent className="text-[11px]">

package/corpus/templates/design/app/components/design/inspector/InspectorAiActions.tsx

@@ -0,0 +1,145 @@
+import { useT } from "@agent-native/core/client";
+import {
+  IconClipboard,
+  IconChevronDown,
+  IconSparkles,
+} from "@tabler/icons-react";
+import { useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { Textarea } from "@/components/ui/textarea";
+import { useAgentEditRequest } from "@/hooks/useAgentEditRequest";
+import { cn } from "@/lib/utils";
+
+export interface InspectorAiActionsProps {
+  /** CSS selector for the currently-selected element, if any. */
+  selector?: string;
+  /** Source id (data-code-layer-id) of the selected element, if any. */
+  sourceId?: string;
+  /** Active file id. */
+  fileId?: string;
+  /** Active file name (e.g. "index.html"). */
+  filename?: string;
+  /** The design id. */
+  designId?: string;
+  /** When false, the controls are disabled. */
+  canEdit: boolean;
+}
+
+/**
+ * Compact inspector block that lets the user type a freeform AI edit request
+ * and either route it to the agent chat sidebar ("Apply with AI") or copy the
+ * prompt to the clipboard ("Copy prompt").
+ *
+ * Collapsed by default to keep the inspector clean.
+ */
+export function InspectorAiActions({
+  selector,
+  sourceId,
+  fileId,
+  filename,
+  designId,
+  canEdit,
+}: InspectorAiActionsProps) {
+  const t = useT();
+  const { sendEdit, copyPrompt } = useAgentEditRequest();
+  const [open, setOpen] = useState(false);
+  const [request, setRequest] = useState("");
+
+  const args = {
+    message: request,
+    selector,
+    sourceId,
+    fileId,
+    filename,
+    designId,
+  };
+  const disabled = !canEdit || !request.trim();
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="w-full">
+      <CollapsibleTrigger asChild>
+        <button
+          type="button"
+          className={cn(
+            "flex w-full items-center justify-between gap-1 rounded px-2 py-1.5 text-xs font-medium text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
+          )}
+        >
+          <span className="flex items-center gap-1.5">
+            <IconSparkles className="size-3.5 shrink-0" />
+            {t("designEditor.localSourceEdit.askAi")}
+          </span>
+          <IconChevronDown
+            className={cn(
+              "size-3.5 shrink-0 transition-transform duration-150",
+              open && "rotate-180",
+            )}
+          />
+        </button>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-none">
+        <div className="flex flex-col gap-2 px-1 pb-2 pt-1">
+          <Textarea
+            value={request}
+            onChange={(e) => setRequest(e.target.value)}
+            placeholder={
+              selector
+                ? t("designEditor.localSourceEdit.describeElementChange")
+                : t("designEditor.localSourceEdit.describeChange")
+            }
+            className="min-h-[64px] resize-none text-xs"
+            disabled={!canEdit}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey) && !disabled) {
+                e.preventDefault();
+                void sendEdit(args);
+                setRequest("");
+                setOpen(false);
+              }
+            }}
+          />
+          <div className="flex gap-1.5">
+            <Button
+              size="sm"
+              variant="default"
+              className="flex-1 gap-1.5 text-xs"
+              disabled={disabled}
+              onClick={() => {
+                void sendEdit(args);
+                setRequest("");
+                setOpen(false);
+              }}
+            >
+              <IconSparkles className="size-3.5 shrink-0" />
+              {t("designEditor.localSourceEdit.applyWithAi")}
+            </Button>
+            <Button
+              size="sm"
+              variant="outline"
+              className="gap-1.5 text-xs"
+              disabled={disabled}
+              onClick={() => {
+                void copyPrompt(args);
+              }}
+              title={t("designEditor.localSourceEdit.copyPromptTooltip")}
+            >
+              <IconClipboard className="size-3.5 shrink-0" />
+              {t("designEditor.localSourceEdit.copyPrompt")}
+            </Button>
+          </div>
+          {selector && (
+            <p className="text-[10px] leading-tight text-muted-foreground truncate">
+              {t("designEditor.localSourceEdit.targeting")}{" "}
+              <code className="font-mono">{selector}</code>
+            </p>
+          )}
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}

package/corpus/templates/design/app/components/design/inspector/SHADER_INTEGRATION.md

@@ -6,6 +6,30 @@ right spot plus copy-pasteable code to insert or replace.
 
 Do NOT rely on line numbers — they drift. Use the search strings instead.
 
+## Status: shader fills are user-reachable and applyable
+
+The **Shader Fills** card in `DesignExtensionsPanel.tsx` (inspector slot
+`design.editor.inspector`) is the live entry point: open it, **Browse Shaders**,
+pick a preset, tune it with `ShaderControls`, and the iframe previews the fill as
+a CSS gradient (`preview-shader-fill`). With an element selected on the canvas, the
+card's **Apply fill** button persists that fill via the `apply-shader-fill` action.
+
+`apply-shader-fill` is **no longer gated** — it is SAFETY-gated, not Builder-gated:
+
+- It asserts **editor** access on the target design (`accessFilter` read +
+  `assertAccess("design", id, "editor")`) before any write.
+- It only persists **HTML design-file** sources. localhost / fusion / inline-html
+  sources return the preview value and write nothing.
+- It writes a single inline-style `background` onto the target node through the
+  deterministic HTML editor (`applyVisualEdit`, the same persist path as
+  `apply-visual-edit`), reusing the strict CSS-colour allowlist from
+  `shared/shader-fill.ts` so `descriptor.colors` can never inject CSS.
+
+Sections (a), (b), (d), and (f) below remain optional ways to surface shaders in
+_other_ inspector seams (the colour picker fill type, the effects panel, the
+artboard WebGL bridge, design-system tokens) and are not required for the
+card-based apply path that ships today.
+
 ---
 
 ## (a) DesignColorPicker.tsx — Add `"shader"` fill type
@@ -351,20 +375,17 @@ if (fill.type === "shader") {
 
 ---
 
-## (e) Changelog entry (DEFERRED)
-
-The shader feature is not yet user-reachable — it still needs all seam files wired.
-Do NOT add a changelog entry yet.
+## (e) Changelog entry
 
-Once the seam files are integrated and the feature is accessible from the UI (a user
-can apply a shader fill from the fill picker or add a shader effect from the effects
-panel), run:
+The shader-fills card is now user-reachable and the apply path persists, so a
+user-facing changelog entry is warranted. From the `templates/design/` directory:
 
 ```bash
-agent-native changelog add "Add GPU shader fills and effects — 8 presets (MeshGradient, GrainGradient, Voronoi, Metaballs, Warp, GodRays, Dithering, PaperTexture) with live preview and agent-tunable params" --type added
+agent-native changelog add "Add GPU shader fills — 8 presets (MeshGradient, GrainGradient, Voronoi, Metaballs, Warp, GodRays, Dithering, PaperTexture) with live preview and one-click apply to the selected element" --type added
 ```
 
-from the `templates/design/` directory.
+(The effects-panel surface from section (b) is still optional; scope the changelog
+line to what actually ships.)
 
 ---
 
@@ -407,14 +428,23 @@ shader token picker.
 
 ## Integration Checklist
 
+Shipped (card-based preview + apply path):
+
+- [x] `DesignExtensionsPanel.tsx` — Shader Fills card opens `ShaderFillsPanel`
+- [x] `DesignExtensionsPanel.tsx` — "Apply fill" persists via `apply-shader-fill`
+- [x] `actions/apply-shader-fill.ts` — persists fill as CSS background (editor-gated)
+- [x] `actions/preview-shader-fill.ts` — preview-only CSS (unchanged)
+- [x] `actions/apply-shader.ts` exists (planning/codegen snippet)
+- [x] `actions/get-shader.ts` exists
+
+Optional follow-ups (other inspector seams):
+
 - [ ] `DesignColorPicker.tsx` — `DesignFillType` includes `"shader"`
 - [ ] `DesignColorPicker.tsx` — `DesignPaintType` includes `"shader"`
 - [ ] `DesignColorPicker.tsx` — shader button renders in paint-type row
 - [ ] `DesignColorPicker.tsx` — `ShaderControls` renders when `paintType === "shader"`
 - [ ] `EditPanel.tsx` — `ShaderEffectRow` renders in `EffectsProperties`
 - [ ] `EditPanel.tsx` — "Add Shader" option in effects dropdown
-- [ ] `actions/apply-shader.ts` exists
-- [ ] `actions/get-shader.ts` exists
 - [ ] `DesignCanvas.tsx` — shader bridge script injected into artboard
 - [ ] `DesignCanvas.tsx` — `data-shader` attribute serialized for shader fills
-- [ ] Changelog entry added (after feature is user-reachable)
+- [ ] Changelog entry added (see section (e))