@agent-native/core 0.79.27 → 0.80.0

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)

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

@@ -0,0 +1,215 @@
+import { IconArrowsHorizontal } from "@tabler/icons-react";
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ComponentType,
+  type KeyboardEvent,
+  type PointerEvent,
+} from "react";
+
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+
+import {
+  formatScrubValue,
+  getScrubStepFromEvent,
+  normalizeScrubNumber,
+  parseScrubExpression,
+  type ScrubExpressionOptions,
+} from "./scrub-input-utils";
+
+type ScrubInputIcon = ComponentType<{ className?: string }>;
+
+export interface ScrubInputChangeMeta {
+  source: "commit" | "keyboard" | "scrub";
+  expression?: string;
+}
+
+export interface ScrubInputProps extends ScrubExpressionOptions {
+  label: string;
+  value: number;
+  onChange: (value: number, meta: ScrubInputChangeMeta) => void;
+  id?: string;
+  step?: number;
+  icon?: ScrubInputIcon;
+  disabled?: boolean;
+  placeholder?: string;
+  className?: string;
+  inputClassName?: string;
+  labelClassName?: string;
+  ariaLabel?: string;
+}
+
+export function ScrubInput({
+  label,
+  value,
+  onChange,
+  id,
+  step = 1,
+  unit,
+  min,
+  max,
+  precision,
+  icon: Icon = IconArrowsHorizontal,
+  disabled = false,
+  placeholder,
+  className,
+  inputClassName,
+  labelClassName,
+  ariaLabel,
+}: ScrubInputProps) {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const [draft, setDraft] = useState(() =>
+    formatScrubValue(value, { unit, precision }),
+  );
+  const [focused, setFocused] = useState(false);
+  const [dragging, setDragging] = useState(false);
+  const skipNextBlurCommitRef = useRef(false);
+  const dragRef = useRef({
+    pointerId: -1,
+    startX: 0,
+    startValue: value,
+  });
+
+  useEffect(() => {
+    if (!focused) setDraft(formatScrubValue(value, { unit, precision }));
+  }, [focused, precision, unit, value]);
+
+  const options = { unit, min, max, precision };
+
+  const setNextValue = (nextValue: number, meta: ScrubInputChangeMeta) => {
+    const normalized = normalizeScrubNumber(nextValue, options);
+    onChange(normalized, meta);
+    setDraft(formatScrubValue(normalized, options));
+  };
+
+  const commitDraft = () => {
+    const parsed = parseScrubExpression(draft, value, options);
+    if (!parsed) {
+      setDraft(formatScrubValue(value, options));
+      return;
+    }
+
+    setDraft(parsed.normalized);
+    if (parsed.value !== value) {
+      onChange(parsed.value, { source: "commit", expression: draft });
+    }
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+      event.preventDefault();
+      const direction = event.key === "ArrowUp" ? 1 : -1;
+      setNextValue(value + direction * getScrubStepFromEvent(event, step), {
+        source: "keyboard",
+      });
+      return;
+    }
+
+    if (event.key === "Enter") {
+      event.preventDefault();
+      commitDraft();
+      skipNextBlurCommitRef.current = true;
+      event.currentTarget.blur();
+      return;
+    }
+
+    if (event.key === "Escape") {
+      event.preventDefault();
+      setDraft(formatScrubValue(value, options));
+      skipNextBlurCommitRef.current = true;
+      event.currentTarget.blur();
+    }
+  };
+
+  const handlePointerDown = (event: PointerEvent<HTMLLabelElement>) => {
+    if (disabled || event.button !== 0) return;
+    event.preventDefault();
+    dragRef.current = {
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startValue: value,
+    };
+    event.currentTarget.setPointerCapture(event.pointerId);
+    setDragging(true);
+  };
+
+  const handlePointerMove = (event: PointerEvent<HTMLLabelElement>) => {
+    if (!dragging || dragRef.current.pointerId !== event.pointerId) return;
+    const delta = event.clientX - dragRef.current.startX;
+    if (delta === 0) return;
+    const next =
+      dragRef.current.startValue +
+      delta *
+        getScrubStepFromEvent(
+          { altKey: event.altKey, shiftKey: event.shiftKey },
+          step,
+        );
+    setNextValue(next, { source: "scrub" });
+  };
+
+  const endDrag = (event: PointerEvent<HTMLLabelElement>) => {
+    if (dragRef.current.pointerId !== event.pointerId) return;
+    event.currentTarget.releasePointerCapture(event.pointerId);
+    setDragging(false);
+  };
+
+  return (
+    <div className={cn("flex items-center gap-1.5", className)}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Label
+            htmlFor={inputId}
+            onPointerDown={handlePointerDown}
+            onPointerMove={handlePointerMove}
+            onPointerUp={endDrag}
+            onPointerCancel={endDrag}
+            className={cn(
+              "flex h-6 w-20 shrink-0 cursor-ew-resize select-none items-center gap-1 text-[11px] text-muted-foreground",
+              "hover:bg-[var(--design-editor-control-bg)] hover:rounded-sm",
+              dragging && "text-foreground",
+              disabled && "pointer-events-none cursor-not-allowed opacity-50",
+              labelClassName,
+            )}
+          >
+            <Icon className="size-3 shrink-0" />
+            <span className="truncate">{label}</span>
+          </Label>
+        </TooltipTrigger>
+        <TooltipContent>{`${label}. Drag to scrub, use arrows to step.`}</TooltipContent>
+      </Tooltip>
+      <Input
+        id={inputId}
+        value={draft}
+        disabled={disabled}
+        placeholder={placeholder}
+        inputMode="decimal"
+        aria-label={ariaLabel ?? label}
+        onFocus={(event) => {
+          setFocused(true);
+          event.target.select();
+        }}
+        onBlur={() => {
+          setFocused(false);
+          if (skipNextBlurCommitRef.current) {
+            skipNextBlurCommitRef.current = false;
+            return;
+          }
+          commitDraft();
+        }}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={handleKeyDown}
+        className={cn("h-6 text-[11px] tabular-nums", inputClassName)}
+      />
+    </div>
+  );
+}

package/corpus/templates/design/app/components/design/inspector/ShaderControls.stories.tsx

@@ -0,0 +1,71 @@
+import type { ShaderDescriptor } from "@shared/shader-presets";
+import React, { useState } from "react";
+
+import { ShaderControls } from "./ShaderControls";
+
+const defaultMesh: ShaderDescriptor = {
+  preset: "MeshGradient",
+  params: { distortion: 0.8, swirl: 0.1 },
+  colors: ["#e0eaff", "#241d9a", "#f75092", "#9f50d3"],
+  speed: 1,
+  frame: 0,
+  fit: "contain",
+};
+
+const defaultGrain: ShaderDescriptor = {
+  preset: "GrainGradient",
+  params: { softness: 0.5, intensity: 0.5, noise: 0.25, shape: "corners" },
+  colors: ["#7300ff", "#eba8ff", "#00bfff"],
+  speed: 0,
+  frame: 0,
+  fit: "contain",
+};
+
+export function ShaderControlsDemo() {
+  const [mesh, setMesh] = useState<ShaderDescriptor>(defaultMesh);
+  const [grain, setGrain] = useState<ShaderDescriptor>(defaultGrain);
+  return (
+    <div
+      style={{
+        display: "flex",
+        gap: 24,
+        padding: 24,
+        background: "#111",
+        minHeight: "100vh",
+      }}
+    >
+      <div style={{ width: 280 }}>
+        <h3 style={{ color: "white", marginBottom: 12, fontSize: 12 }}>
+          MeshGradient
+        </h3>
+        <ShaderControls descriptor={mesh} onChange={setMesh} />
+        <pre
+          style={{
+            color: "#888",
+            fontSize: 10,
+            marginTop: 8,
+            overflow: "auto",
+          }}
+        >
+          {JSON.stringify(mesh, null, 2)}
+        </pre>
+      </div>
+      <div style={{ width: 280 }}>
+        <h3 style={{ color: "white", marginBottom: 12, fontSize: 12 }}>
+          GrainGradient
+        </h3>
+        <ShaderControls descriptor={grain} onChange={setGrain} />
+        <pre
+          style={{
+            color: "#888",
+            fontSize: 10,
+            marginTop: 8,
+            overflow: "auto",
+          }}
+        >
+          {JSON.stringify(grain, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}