native-effects

---
name: native-effects
description: >-
  Use when creating, applying, inspecting, editing, or exporting native WebGPU effects in a Design inline HTML screen.
---

# Native WebGPU effects

The native shader catalog returned by `get-shader` (`format: "native-v2"`) contains the exact definition versions available in Design. Each entry is one original shader with useful default properties the user can customize; do not create visual variants as preset entries. Previously saved GLSL blocks remain renderable and removable; new shader authoring uses native WGSL.

Read the definitions and their full property schemas with `get-shader`, then read the selected file with `get-shader` or `read-source-file`. Keep its `versionHash` and call `edit-native-shader` with `expectedVersionHash`. Apply a definition by its exact `definitionId` and `definitionVersion`; omit `params` to use all declared defaults or pass property-keyed overrides. For example, `an-native-mesh-anchors` version `5` has a `palette` color-ramp property. To shift it from blue to teal, apply with `params: { palette: [{ position: 0, color: { space: "srgb", components: [0.145, 0.388, 0.922], alpha: 1 } }, { position: 1, color: { space: "srgb", components: [0.078, 0.722, 0.651], alpha: 1 } }] }`. Stop positions run from 0 to 1; color components are normalized sRGB values from 0 to 1. For a selected element without a stable authored `data-agent-native-node-id`, pass a unique same-file `targetSelector`; the action stamps its stable ID and applies the effect in one guarded write. Do not copy generated runtime scripts into source. Fill apply appends another native Fill on the same authored layer, preserving existing Fill instances and CSS paints. Target authored `nodeId` values from the source or projection, rather than layer display names. The manifest `instances` array orders native Fills from bottom to top; the inspector lists the frontmost first. Only one enabled native Layer can be newly applied per target; Backdrop uses its own placement.

## Create with AI

The Shader fill and effect pickers open the existing AgentSidebar with a draft request. Let the user describe the appearance, then use the supplied designId, fileId, authored nodeId or targetSelector, and placement. Create native WebGPU WGSL with declared editable properties; this workflow creates native WGSL rather than historical GLSL blocks. Read `get-shader` and the selected source first so the definition uses the current native manifest, uniform, pass, and resource contracts.

Save the validated custom definition with `edit-native-shader` operation `define-definition` and the current `expectedVersionHash`. Read back with `get-shader` to obtain the saved definition's exact execution hash, approve that version with `approve-definition` and `expectedExecutionHash`, then apply its ID/version to the selected target. Re-read the source hash after each write. Approval is scoped to the current Design and caller; changed executable content needs its own exact-hash approval. Preserve built-in IDs and versions. For a revision, save a new version, approve its execution hash, and use `revise-definition` for the intended instances.

Folded Mesh uses the native indexed-mesh render contract: set `mesh: { columns, rows }` on the render pass, with safe-integer dimensions from 16 to 256 and at most 32,768 cells; omit `draw` and `dispatch` on that pass. WGSL vertex stages address the runtime's shared grid with `@builtin(vertex_index)`. Version `3` retains the 28 numeric controls from version `2` and adds up to four editable lights and four noise bands through shared record-array controls. Light records contain normalized position and direction, color, intensity, amount, and normalized focus; noise-band records contain left/right/top/bottom bounds, feather, strength, frequency, color fade, and normalized focus. Child field units and display scales are part of the returned schema; frequency is cycles per UV axis and displays with `×`. The native record-array contract uses ordered rows, exact field keys, and at most four rows. Angles display in degrees, time offset in seconds, and normalized values in percent; line density displays as a count. Compact packing places scalar properties in consecutive float lanes, aligns `vec2` values to two lanes, and aligns structured paint/color blocks to `vec4`. Folded Mesh versions `1` and `2` use the legacy 128-float (32-`vec4`) capacity; version `3` opts into 256 floats (64 `vec4`s). Read `get-shader` for exact property keys, defaults, units, and WGSL before creating or editing a definition.

Custom definitions saved in the file appear in the existing picker for their supported Fill, Layer, or Backdrop placement, and their declared properties use the shared controls. Verify the actual GPU preview and persistence after reload before reporting a created shader working; schema validation and a thumbnail alone do not establish the user's requested appearance.

Liquid Metal version `12` has independent `tint` and `fill` properties. Tint is a normalized RGBA color. Fill defaults to a solid gray paint: `{ kind: "solid", color: { space: "srgb", components: [0.667, 0.667, 0.675], alpha: 1 } }`. A gradient Fill has `kind` (`linear`, `radial`, `angular`, or `diamond`), a CSS-degree `angle`, and 2–8 `stops` with normalized `position` and `color` values. Gradients use the shared picker’s centered geometry and may include `opacity` from 0 to 1. Supported `interpolation` values are `in srgb`, `in srgb-linear`, `in oklab`, and `in display-p3`; omitted or empty interpolation uses sRGB for all-sRGB stops and Oklab when a stop uses Display P3. The internal reflection profile is independent of Fill. Liquid Metal wraps its reflections around painted SVG shapes and uses the element box on HTML layers.

Liquid Glass version `3` (`an-native-liquid-glass`) is the current Backdrop material. It refracts content behind an HTML element or an outer SVG logo with edge falloff that tapers into the center. Apply it through the existing Effects picker or `edit-native-shader`; its declared properties use the shared controls and color picker. HTML receivers inherit their authored corner radii. SVG receivers follow their complete painted silhouette, including holes and transparent paint. Target the outer SVG with an HTML parent, or the whole editable SVG group created by a new file drop. Imported groups retain their painted silhouette and holes. Existing ordinary frames retain box coverage. Standalone child paths, SVG child groups, nested SVG targets, text clipping, and SVG content rejected by the native source serializer remain unsupported. Versions `1` and `2` remain executable for existing designs. Liquid Metal remains a separate Fill/Layer material.

Pulsing Border version `5` (`an-native-pulsing-border`) supports Fill and Layer placement; versions `3` and `4` remain executable for existing designs. It follows authored HTML corner radii or painted SVG silhouettes, including holes; its Fill is transparent beyond the contour and its Layer preserves the receiver's center. Default roundness `.25` preserves the authored outline; other values adjust corner curvature through a bounded symmetric distance-field kernel while keeping straight edges anchored. Colors is a spatial Linear or Angular paint with up to eight editable stops in the standard gradient picker; moving light stations illuminate that paint. Background remains a separate color. Thickness controls the bright edge width, Softness feathers that edge, Bloom controls glow brightness, and Glow spread controls glow radius independently. Intensity, pulse, smoke, and sizing controls remain editable; `get-shader` exposes the full property schema and defaults. The shared `margin` supplies each side's value unless that side has an explicit override, including an explicit zero. Playback speed and frame use the ordinary native instance controls. The light and smoke patterns are generated in WGSL without an image input.

Editor, presentation, board overview, template, and catalog previews use the shared native preview surface and runtime. Interactive surfaces follow the document's 60 or 120 fps target. Compact thumbnails animate at 15 fps while visible and pause when offscreen; they retain the same shader execution, geometry, and input assets.
Board live, static, and over-screen previews share one host animation epoch across iframe remounts, so panning or zooming does not restart the effect phase. Capped over-screen previews use a bounded logical viewport while retaining the authored board transform.

`set-params` updates only the supplied properties on the selected stable `instanceId`. Use `set-instance` with that ID for independent `enabled` visibility, `opacity`, and other instance settings. `playback`, `duplicate`, `reorder`, and `remove` use the same action and current source hash. `remove` deletes only the addressed instance. For native Fill ordering, use same-node Fill instance IDs: `reorder` puts an instance before `beforeInstanceId` in the bottom-to-top manifest, or at the top with `beforeInstanceId: null`. Native Fill ordering does not interleave with CSS paint rows. On a stale-source error, re-read before retrying. A CPU-valid action result does not prove a GPU frame; inspect the Design preview. PNG preparation pins the saved file, unchanged layout viewport, and optional output region. Selected-region PNG rerenders at the pinned live clock and requested density, isolating the selected authored subtrees while preserving full backdrop sampling context. Capture without an output region retains the last committed native-frame path. External agents can call `get-native-render-contexts`, request a local foreground PNG with `request-native-local-export` and the exact source version, then poll `get-native-local-export`. After the editor claims the request, it captures the requested frame or isolated region, stores an owner-scoped PNG attachment, and marks the request completed. `get-native-local-export` then returns a protected same-origin download URL and opaque attachment reference. A pending request or browser download initiation is not completion. `export-png` rejects enabled native effects rather than returning headless pixels without them. A source mismatch, missing frame, or unsupported definition is a failure, not a blank export.