@agent-native/core 0.79.27 → 0.80.1

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

@@ -0,0 +1,242 @@
+import { IconPhotoPlus, IconX } from "@tabler/icons-react";
+import { useRef, useState } from "react";
+
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type ImageFitMode = "fill" | "fit" | "crop" | "tile";
+
+export interface ImageFillValue {
+  url: string;
+  fit: ImageFitMode;
+}
+
+const FIT_MODES: Array<{ mode: ImageFitMode; label: string }> = [
+  { mode: "fill", label: "Fill" }, // i18n-ignore image fit mode
+  { mode: "fit", label: "Fit" }, // i18n-ignore image fit mode
+  { mode: "crop", label: "Crop" }, // i18n-ignore image fit mode
+  { mode: "tile", label: "Tile" }, // i18n-ignore image fit mode
+];
+
+// ─── CSS serialization ─────────────────────────────────────────────────────────
+
+const CHECKER_A = "#d4d4d4";
+const CHECKERBOARD_IMAGE = `linear-gradient(45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(-45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(45deg, transparent 75%, ${CHECKER_A} 75%), linear-gradient(-45deg, transparent 75%, ${CHECKER_A} 75%)`;
+const FIT_MARKER_RE =
+  /\/\*\s*agent-native-image-fit:(fill|fit|crop|tile)\s*\*\//i;
+
+function imageFitMarker(fit: ImageFitMode): string {
+  return `/* agent-native-image-fit:${fit} */`;
+}
+
+/**
+ * Build the CSS `background` shorthand for an image fill.
+ * Maps Figma's fit semantics onto background-size / background-repeat:
+ *  - Fill → cover, no-repeat
+ *  - Fit  → contain, no-repeat
+ *  - Crop → cover, no-repeat (cropped to the box; identical CSS to Fill but
+ *           kept distinct so the selection round-trips)
+ *  - Tile → auto, repeat
+ */
+export function imageFillToCss(value: ImageFillValue): string {
+  const url = value.url.trim();
+  if (!url) return "transparent";
+  const safeUrl = url.replace(/["')]/g, encodeURIComponent);
+  const image = `url("${safeUrl}")`;
+  switch (value.fit) {
+    case "fit":
+      return `${image} center / contain no-repeat ${imageFitMarker("fit")}`;
+    case "tile":
+      return `${image} top left / auto repeat ${imageFitMarker("tile")}`;
+    case "crop":
+      return `${image} center / cover no-repeat ${imageFitMarker("crop")}`;
+    case "fill":
+    default:
+      return `${image} center / cover no-repeat ${imageFitMarker("fill")}`;
+  }
+}
+
+const URL_RE = /url\((['"]?)([^'")]+)\1\)/i;
+
+/** Extract the URL + fit mode from a CSS background value, if present. */
+export function parseImageFillCss(value: string): ImageFillValue | null {
+  const match = value.match(URL_RE);
+  if (!match) return null;
+  const url = match[2];
+  const marker = value.match(FIT_MARKER_RE)?.[1] as ImageFitMode | undefined;
+  if (marker) return { url, fit: marker };
+  let fit: ImageFitMode = "fill";
+  if (/contain/i.test(value)) fit = "fit";
+  else if (/repeat(?!\s+no)/i.test(value) && !/no-repeat/i.test(value))
+    fit = "tile";
+  else if (/cover/i.test(value)) fit = "fill";
+  return { url, fit };
+}
+
+// ─── Component ─────────────────────────────────────────────────────────────────
+
+export interface ImageFillControlsProps {
+  value: ImageFillValue;
+  onChange: (value: ImageFillValue) => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+export function ImageFillControls({
+  value,
+  onChange,
+  disabled = false,
+  className,
+}: ImageFillControlsProps) {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [urlDraft, setUrlDraft] = useState(value.url);
+
+  const commitUrl = () => {
+    onChange({ ...value, url: urlDraft.trim() });
+  };
+
+  const handleFilePick = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = () => {
+      const dataUrl = typeof reader.result === "string" ? reader.result : "";
+      if (dataUrl) {
+        setUrlDraft(dataUrl);
+        onChange({ ...value, url: dataUrl });
+      }
+    };
+    reader.readAsDataURL(file);
+    // Allow re-selecting the same file later.
+    event.target.value = "";
+  };
+
+  return (
+    <div className={cn("space-y-1.5 px-3 pt-2 pb-2", className)}>
+      {/* ── Preview / drop target ─────────────────────────────────────────── */}
+      <div
+        className="relative h-24 w-full overflow-hidden rounded-md border border-border/60"
+        style={{
+          backgroundImage: value.url
+            ? `url("${value.url}")`
+            : CHECKERBOARD_IMAGE,
+          backgroundSize: value.url
+            ? value.fit === "fit"
+              ? "contain"
+              : value.fit === "tile"
+                ? "auto"
+                : "cover"
+            : "8px 8px, 8px 8px, 8px 8px, 8px 8px",
+          backgroundRepeat: value.fit === "tile" ? "repeat" : "no-repeat",
+          backgroundPosition: "center",
+        }}
+      >
+        {!value.url && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-1 text-muted-foreground">
+            <IconPhotoPlus className="size-5" />
+            <span className="text-[10px]">
+              {"Upload or paste a URL" /* i18n-ignore */}
+            </span>
+          </div>
+        )}
+        {value.url && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                aria-label={"Remove image" /* i18n-ignore */}
+                disabled={disabled}
+                onClick={() => {
+                  setUrlDraft("");
+                  onChange({ ...value, url: "" });
+                }}
+                className="absolute right-1 top-1 flex size-5 items-center justify-center rounded bg-black/50 text-white hover:bg-black/70 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                <IconX className="size-3" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>{"Remove image" /* i18n-ignore */}</TooltipContent>
+          </Tooltip>
+        )}
+      </div>
+
+      {/* ── URL input + upload ────────────────────────────────────────────── */}
+      <div className="flex items-center gap-1">
+        <Input
+          value={urlDraft}
+          disabled={disabled}
+          placeholder={"Image URL" /* i18n-ignore */}
+          aria-label={"Image URL" /* i18n-ignore */}
+          spellCheck={false}
+          className="h-6 min-w-0 flex-1 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-2 text-[11px]"
+          onChange={(event) => setUrlDraft(event.target.value)}
+          onBlur={commitUrl}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              commitUrl();
+              event.currentTarget.blur();
+            }
+          }}
+        />
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              disabled={disabled}
+              aria-label={"Upload image" /* i18n-ignore */}
+              onClick={() => fileInputRef.current?.click()}
+              className={cn(
+                "flex size-6 shrink-0 items-center justify-center rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-muted-foreground hover:text-foreground",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                disabled && "pointer-events-none opacity-40",
+              )}
+            >
+              <IconPhotoPlus className="size-3.5" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent>{"Upload image" /* i18n-ignore */}</TooltipContent>
+        </Tooltip>
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept="image/*"
+          className="hidden"
+          onChange={handleFilePick}
+        />
+      </div>
+
+      {/* ── Fit mode dropdown ─────────────────────────────────────────────── */}
+      <Select
+        value={value.fit}
+        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">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent className="text-[11px]">
+          {FIT_MODES.map(({ mode, label }) => (
+            <SelectItem key={mode} value={mode} className="text-[11px]">
+              {label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}

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

@@ -0,0 +1,420 @@
+# Shader Feature Integration Guide
+
+This guide covers the five seam files that need edits to wire the GPU shader feature
+into the design template. Each section gives the exact search string to locate the
+right spot plus copy-pasteable code to insert or replace.
+
+Do NOT rely on line numbers — they drift. Use the search strings instead.
+
+---
+
+## (a) FigmaColorPicker.tsx — Add `"shader"` fill type
+
+**File:** `app/components/design/inspector/FigmaColorPicker.tsx`
+
+### 1. Extend `FigmaFillType`
+
+Search for:
+
+```ts
+export type FigmaFillType = "solid" | "gradient" | "image";
+```
+
+Replace with:
+
+```ts
+export type FigmaFillType = "solid" | "gradient" | "image" | "shader";
+```
+
+### 2. Extend `FigmaPaintType`
+
+Search for:
+
+```ts
+export type FigmaPaintType =
+  | "solid"
+  | "linear"
+  | "radial"
+  | "angular"
+  | "diamond"
+  | "none";
+```
+
+Replace with:
+
+```ts
+export type FigmaPaintType =
+  | "solid"
+  | "linear"
+  | "radial"
+  | "angular"
+  | "diamond"
+  | "none"
+  | "shader";
+```
+
+### 3. Add `canUseShaders` prop to `FigmaColorPickerProps`
+
+Search for:
+
+```ts
+canUseGradients?: boolean
+```
+
+After that line, add:
+
+```ts
+canUseShaders?: boolean
+```
+
+### 4. Add shader button to the paint-type button row
+
+Search for:
+
+```tsx
+{canUseGradients && (
+```
+
+After the closing `)}` of that block, add:
+
+```tsx
+{
+  canUseShaders && (
+    <button
+      type="button"
+      className={cn(
+        "flex h-6 w-6 items-center justify-center rounded transition-colors",
+        paintType === "shader"
+          ? "bg-white/20 text-white"
+          : "text-white/50 hover:text-white",
+      )}
+      onClick={() => onPaintTypeChange?.("shader")}
+      title="Shader"
+    >
+      <IconSparkles size={14} />
+    </button>
+  );
+}
+```
+
+Add the import at the top of the file alongside the existing Tabler icon imports:
+
+```ts
+import { IconSparkles } from "@tabler/icons-react";
+```
+
+### 5. Render `ShaderControls` when `paintType === "shader"`
+
+Search for the block that renders gradient or color controls based on `paintType`.
+It will look something like:
+
+```tsx
+{paintType === "gradient" ? (
+  // gradient controls
+) : (
+  // solid color controls
+)}
+```
+
+Extend it to a three-way branch:
+
+```tsx
+{paintType === "shader" ? (
+  <ShaderControls
+    descriptor={
+      (() => {
+        try {
+          return JSON.parse(value ?? "{}");
+        } catch {
+          return { preset: "MeshGradient", params: {}, colors: [], speed: 1, frame: 0, fit: "contain" };
+        }
+      })()
+    }
+    onChange={(descriptor) => {
+      onValueChange?.(JSON.stringify(descriptor));
+    }}
+  />
+) : paintType === "gradient" ? (
+  // existing gradient controls
+) : (
+  // existing solid color controls
+)}
+```
+
+Add the import near the other local inspector imports:
+
+```ts
+import { ShaderControls } from "./ShaderControls";
+```
+
+The fill row's `value` field holds the serialized `ShaderDescriptor` JSON when
+`type === "shader"`. No schema change is needed — it reuses the existing `value: string`
+slot.
+
+---
+
+## (b) EditPanel.tsx — Add `ShaderEffectRow` to `EffectsProperties`
+
+**File:** `app/components/design/inspector/EditPanel.tsx`
+
+### 1. Add imports
+
+Search for the block that imports `ShadowEffectRow` (or the effects-related imports).
+Add alongside those:
+
+```ts
+import { ShaderEffectRow } from "./inspector/ShaderEffectRow";
+import type { ShaderDescriptor } from "../../shared/shader-presets";
+```
+
+If `EditPanel.tsx` is itself inside the `inspector/` folder, drop the `inspector/` prefix:
+
+```ts
+import { ShaderEffectRow } from "./ShaderEffectRow";
+```
+
+### 2. Extend `EffectsProperties` props
+
+Search for the `EffectsProperties` function signature. It will include props like
+`shadowLayers` and `blurLayers`. Add:
+
+```ts
+shaderLayers?: ShaderDescriptor[];
+onShaderLayersChange?: (layers: ShaderDescriptor[]) => void;
+```
+
+### 3. Render shader effect rows
+
+Search for:
+
+```tsx
+{shadowLayers.map(
+```
+
+After the `shadowLayers.map(...)` block and the `blurLayers.map(...)` block
+(whichever comes last), add:
+
+```tsx
+{
+  (shaderLayers ?? []).map((layer, i) => (
+    <ShaderEffectRow
+      key={layer.id ?? i}
+      descriptor={layer}
+      onChange={(updated) => {
+        const next = [...(shaderLayers ?? [])];
+        next[i] = updated;
+        onShaderLayersChange?.(next);
+      }}
+      onRemove={() => {
+        const next = (shaderLayers ?? []).filter((_, j) => j !== i);
+        onShaderLayersChange?.(next);
+      }}
+    />
+  ));
+}
+```
+
+### 4. Add "Add Shader" option to the effects dropdown
+
+Search for the "Add effect" button or the dropdown that lets users add shadow/blur.
+It will contain strings like `"Drop Shadow"` or `"Add Shadow"`. Add a shader option:
+
+```tsx
+<DropdownMenuItem
+  onSelect={() => {
+    onShaderLayersChange?.([
+      ...(shaderLayers ?? []),
+      {
+        preset: "MeshGradient",
+        params: { distortion: 0.8, swirl: 0.1 },
+        colors: ["#e0eaff", "#241d9a", "#f75092", "#9f50d3"],
+        speed: 1,
+        frame: 0,
+        fit: "contain",
+      },
+    ]);
+  }}
+>
+  Shader
+</DropdownMenuItem>
+```
+
+---
+
+## (c) Register apply-shader and get-shader actions
+
+No registration step is required. The actions directory is auto-discovered by the
+framework at startup. Confirm both files exist:
+
+```
+templates/design/actions/apply-shader.ts   ✓
+templates/design/actions/get-shader.ts     ✓
+```
+
+If either is missing, the agent won't have access to shader tools. The `defineAction`
+export at the top of each file is all that's needed for automatic discovery.
+
+---
+
+## (d) DesignCanvas.tsx — Alpine/inline artboard shader bridge
+
+**File:** `app/components/design/canvas/DesignCanvas.tsx` (or similar canvas file)
+
+### 1. Locate the bridge scripts injection point
+
+Search for:
+
+```
+// === BRIDGE SCRIPTS ===
+```
+
+Or search for the injected HTML string that wires up the Alpine bridge. It will
+contain `<script` tags being concatenated into a string that gets injected into the
+artboard iframe.
+
+### 2. Add the shader mount script
+
+Append the following after the existing bridge scripts (inside the same injected
+content string):
+
+```js
+const shaderBridgeScript = `
+<script type="module">
+  import { ShaderMount } from 'https://esm.sh/@paper-design/shaders@0.0.76/dist/index.js';
+
+  function mountShaders() {
+    document.querySelectorAll('[data-shader]').forEach(el => {
+      if (el.__shaderMounted) return;
+      el.__shaderMounted = true;
+      try {
+        const descriptor = JSON.parse(el.getAttribute('data-shader') || '{}');
+        if (!descriptor.preset) return;
+        const canvas = document.createElement('canvas');
+        canvas.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none;';
+        el.style.position = 'relative';
+        el.prepend(canvas);
+        // ShaderMount takes { canvas, preset, uniforms } — map descriptor.params to uniforms:
+        new ShaderMount({
+          canvas,
+          preset: descriptor.preset,
+          uniforms: {
+            ...(descriptor.params ?? {}),
+            colors: descriptor.colors ?? [],
+            speed: descriptor.speed ?? 1,
+          },
+        });
+        console.log('[shader bridge] mounted', descriptor.preset, 'on', el);
+      } catch (e) {
+        console.warn('[shader bridge] mount failed:', e);
+      }
+    });
+  }
+
+  document.addEventListener('DOMContentLoaded', mountShaders);
+  // Re-run on mutations (new elements added dynamically):
+  new MutationObserver(mountShaders).observe(document.body, { childList: true, subtree: true });
+<\/script>
+`;
+```
+
+Concatenate `shaderBridgeScript` into the injected HTML alongside the other bridge
+scripts. The exact concatenation point depends on how the existing bridge is assembled
+— look for where the other `<script>` strings are joined.
+
+### 3. Add vanilla shaders package dependency
+
+The bridge imports from `esm.sh` at runtime, so no local dep is strictly required
+for the iframe bridge. However, if you want type-safe access in the canvas component
+itself, add:
+
+```bash
+pnpm add @paper-design/shaders
+```
+
+in the `templates/design/` directory. The package provides both the React components
+(already used via `@paper-design/shaders-react`) and the vanilla `ShaderMount` class.
+
+### 4. Ensure artboard elements carry `data-shader`
+
+When the canvas renders an element whose fill type is `"shader"`, it must serialize
+the `ShaderDescriptor` onto the DOM element as `data-shader`. Search for the artboard
+render path (likely a function that serializes fills to inline styles or HTML
+attributes) and add:
+
+```ts
+if (fill.type === "shader") {
+  attrs["data-shader"] = JSON.stringify(fill.descriptor);
+  // Optionally set a placeholder background so the element is visible before mount:
+  styles["background"] = fill.descriptor.colors?.[0] ?? "transparent";
+}
+```
+
+---
+
+## (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.
+
+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:
+
+```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
+```
+
+from the `templates/design/` directory.
+
+---
+
+## (f) Design-system token shape (for Phase 6)
+
+The design system `data` blob (returned by the `get-design-system` action) can be
+extended to store shader tokens without any migration — `data` is already an untyped
+JSON blob.
+
+Search for `update-design-system.ts` and locate the `DesignSystemData` interface (or
+wherever the `data` field is typed). Add:
+
+```ts
+interface DesignSystemData {
+  // ... existing fields (colors, typography, spacing, etc.) ...
+  tokens?: {
+    shaders?: Array<{
+      id: string;
+      name: string;
+      descriptor: ShaderDescriptor;
+    }>;
+  };
+}
+```
+
+Import `ShaderDescriptor` from:
+
+```ts
+import type { ShaderDescriptor } from "../shared/shader-presets";
+```
+
+(Adjust the relative path based on where `update-design-system.ts` lives relative to
+the `shared/` folder — typically `../../shared/shader-presets` from inside `actions/`.)
+
+This shape lets the agent call `update-design-system` to persist named shader presets
+as reusable design tokens, and `get-design-system` to retrieve them for display in a
+shader token picker.
+
+---
+
+## Integration Checklist
+
+- [ ] `FigmaColorPicker.tsx` — `FigmaFillType` includes `"shader"`
+- [ ] `FigmaColorPicker.tsx` — `FigmaPaintType` includes `"shader"`
+- [ ] `FigmaColorPicker.tsx` — shader button renders in paint-type row
+- [ ] `FigmaColorPicker.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)