shaders 2.5.114 → 2.5.115

package/dist/react/engine/Preview.d.ts

@@ -15,6 +15,16 @@ export interface ShaderDefinition {
     colorSpace?: 'p3-linear' | 'srgb';
     devicePreview?: string;
 }
+export interface KeyPropTarget {
+    component_id: string;
+    prop: string;
+}
+export interface KeyProp {
+    label: string;
+    type: 'color' | 'range' | 'logo' | 'image';
+    category?: string;
+    targets: KeyPropTarget[];
+}
 export interface PreviewProps {
     shader?: string;
     presetId?: string;
@@ -24,6 +34,25 @@ export interface PreviewProps {
     watermarkLink?: string;
     style?: CSSProperties | string;
     className?: string;
+    /**
+     * Map of camelCase key_prop identifier → user value, layered on top of the
+     * preset's authored defaults. Identifiers are derived from `key_prop.label`
+     * via the same slugify rules the Pro Framer exporter uses, so identifiers
+     * generated by codegen and identifiers expected here always match.
+     *
+     * Only applies on the `presetId` path — `shader` token previews don't carry
+     * key_props and silently ignore this prop.
+     */
+    configuration?: Record<string, unknown>;
+    /**
+     * Lock the preview to a specific snapshot of the preset, addressed by
+     * content hash. Customized snippets pin a version so subsequent upstream
+     * edits (label renames, key_prop regenerations) don't silently break the
+     * configuration. Server falls back to latest with the
+     * `X-Shaders-Version-Fallback` header when the requested snapshot is
+     * missing. Only meaningful on the `presetId` path.
+     */
+    version?: string;
     [key: string]: any;
 }
 export declare const Preview: FC<PreviewProps>;

package/dist/react/engine/Preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Preview.d.ts","sourceRoot":"","sources":["../../src/engine/Preview.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4E,KAAK,aAAa,EAAE,KAAK,EAAE,EAA4B,MAAM,OAAO,CAAA;AAKvJ,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,eAAe,EAAE,CAAA;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,UAAU,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IACjC,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAqKD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AA6BD,eAAO,MAAM,OAAO,EAAE,EAAE,CAAC,YAAY,CA+HpC,CAAA;AAED,eAAe,OAAO,CAAA"}
+{"version":3,"file":"Preview.d.ts","sourceRoot":"","sources":["../../src/engine/Preview.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4E,KAAK,aAAa,EAAE,KAAK,EAAE,EAA4B,MAAM,OAAO,CAAA;AAKvJ,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,eAAe,EAAE,CAAA;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,UAAU,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IACjC,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAA;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB;AAgPD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AA6BD,eAAO,MAAM,OAAO,EAAE,EAAE,CAAC,YAAY,CAwIpC,CAAA;AAED,eAAe,OAAO,CAAA"}

package/dist/solid/engine/Preview.d.ts

@@ -8,6 +8,24 @@ export interface PreviewProps {
     class?: string;
     watermarkText?: string;
     watermarkLink?: string;
+    /**
+     * Map of camelCase key_prop identifier → user value, layered on top of the
+     * preset's authored defaults. Identifiers are derived from `key_prop.label`
+     * via the same slugify rules the Pro Framer exporter uses, so identifiers
+     * generated by codegen and identifiers expected here always match.
+     *
+     * Only applies on the `presetId` path — `shader` token previews don't carry
+     * key_props and silently ignore this prop.
+     */
+    configuration?: Record<string, unknown>;
+    /**
+     * Lock the preview to a specific snapshot of the preset, addressed by
+     * content hash. Customized snippets pin a version so subsequent upstream
+     * edits don't silently break the configuration. Server falls back to
+     * latest with the `X-Shaders-Version-Fallback` header when the requested
+     * snapshot is missing. Only meaningful on the `presetId` path.
+     */
+    version?: string;
 }
 export default function Preview(props: PreviewProps): JSX.Element;
 //# sourceMappingURL=Preview.d.ts.map

package/dist/solid/engine/Preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Preview.d.ts","sourceRoot":"","sources":["../../src/engine/Preview.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,GAAG,EAAoC,MAAM,UAAU,CAAA;AAsUlH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,MAAM,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAID,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,YAAY,eAmHlD"}
+{"version":3,"file":"Preview.d.ts","sourceRoot":"","sources":["../../src/engine/Preview.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,GAAG,EAAoC,MAAM,UAAU,CAAA;AA6ZlH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,MAAM,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,YAAY,eA6HlD"}

package/dist/solid/engine/Preview.js

@@ -243,6 +243,64 @@ function decodePreviewDefinition(encoded, key) {
     throw new Error("Failed to decode shader definition: invalid data or incorrect key");
   }
 }
+const RESERVED_IDENTIFIERS = /* @__PURE__ */ new Set(["break", "case", "catch", "class", "const", "continue", "default", "delete", "do", "else", "export", "extends", "finally", "for", "function", "if", "import", "in", "instanceof", "new", "return", "super", "switch", "this", "throw", "try", "typeof", "var", "void", "while", "with", "yield"]);
+function slugifyIdentifier(label, fallback) {
+  const cleaned = label.replace(/[^A-Za-z0-9]+/g, " ").trim();
+  if (!cleaned) return fallback;
+  const parts = cleaned.split(/\s+/);
+  const camel = parts.map((part, i) => i === 0 ? part.charAt(0).toLowerCase() + part.slice(1) : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  const safe = /^[A-Za-z_$]/.test(camel) ? camel : `_${camel}`;
+  return RESERVED_IDENTIFIERS.has(safe) ? `_${safe}` : safe;
+}
+function buildKeyPropIdentifierMap(keyProps) {
+  const used = /* @__PURE__ */ new Set(["style"]);
+  const map = /* @__PURE__ */ new Map();
+  if (!(keyProps == null ? void 0 : keyProps.length)) return map;
+  keyProps.forEach((kp, i) => {
+    var _a;
+    if (!((_a = kp.targets) == null ? void 0 : _a.length)) return;
+    const base = slugifyIdentifier(kp.label, `keyProp${i}`);
+    let ident = base;
+    let suffix = 1;
+    while (used.has(ident)) {
+      suffix++;
+      ident = `${base}${suffix}`;
+    }
+    used.add(ident);
+    map.set(ident, kp);
+  });
+  return map;
+}
+function findInTree(id, list) {
+  var _a;
+  for (const c of list) {
+    if (c.id === id) return c;
+    if ((_a = c.children) == null ? void 0 : _a.length) {
+      const hit = findInTree(id, c.children);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+function applyConfiguration(definition, configuration, keyProps) {
+  if (!configuration || !(keyProps == null ? void 0 : keyProps.length)) return definition;
+  const entries = Object.entries(configuration);
+  if (entries.length === 0) return definition;
+  const identMap = buildKeyPropIdentifierMap(keyProps);
+  const cloned = JSON.parse(JSON.stringify(definition.components));
+  for (const [ident, value] of entries) {
+    const kp = identMap.get(ident);
+    if (!kp) continue;
+    for (const t of kp.targets ?? []) {
+      const comp = findInTree(t.component_id, cloned);
+      if ((comp == null ? void 0 : comp.props) && t.prop in comp.props) comp.props[t.prop] = value;
+    }
+  }
+  return {
+    ...definition,
+    components: cloned
+  };
+}
 function RenderComponent(props) {
   const Component = componentMap[props.config.type];
   if (!Component) return null;
@@ -297,9 +355,11 @@ function Preview(props) {
     console.warn("[Shaders] The Preview component requires a Shaders license for production use. Visit https://shaders.com for more information.");
   }
   const [fetchedDefinition, setFetchedDefinition] = createSignal(null);
+  const [fetchedKeyProps, setFetchedKeyProps] = createSignal(null);
   function fetchAndDecode(url) {
     const key = props.obfuscationKey || DEFAULT_KEY;
     setFetchedDefinition(null);
+    setFetchedKeyProps(null);
     fetch(url).then((res) => {
       if (!res.ok) throw new Error(`Failed to fetch: ${res.status}`);
       return res.json();
@@ -307,6 +367,7 @@ function Preview(props) {
       const item = data.preset || data.shader;
       if ((item == null ? void 0 : item.definition) && typeof item.definition === "string") {
         setFetchedDefinition(decodePreviewDefinition(item.definition, key));
+        setFetchedKeyProps(Array.isArray(item.key_props) ? item.key_props : null);
       }
     }).catch((err) => {
       console.error("[Shaders Preview] Failed to fetch preview:", err);
@@ -319,19 +380,25 @@ function Preview(props) {
       fetchAndDecode(`${baseUrl}/api/preview/shader/${token}`);
     } else if (!props.presetId) {
       setFetchedDefinition(null);
+      setFetchedKeyProps(null);
     }
   });
   createEffect(() => {
     const id = props.presetId;
+    const version = props.version;
     const baseUrl = props.apiBaseUrl || "https://shaders.com";
     if (id) {
-      fetchAndDecode(`${baseUrl}/api/preview/preset/${id}`);
+      const versionParam = version ? `?version=${encodeURIComponent(version)}` : "";
+      fetchAndDecode(`${baseUrl}/api/preview/preset/${id}${versionParam}`);
     } else if (!props.shader) {
       setFetchedDefinition(null);
+      setFetchedKeyProps(null);
     }
   });
   const definition = createMemo(() => {
-    return fetchedDefinition() ?? null;
+    const def = fetchedDefinition();
+    if (!def) return null;
+    return applyConfiguration(def, props.configuration, fetchedKeyProps());
   });
   const watermarkText = () => props.watermarkText || "Unlock your Shaders Pro license";
   const watermarkLink = () => props.watermarkLink || "https://shaders.com/dashboard?pricing=true";

package/dist/solid/engine/Shader.js

@@ -67,7 +67,7 @@ function Shader(allProps) {
     const checkRendering = () => {
       const stats = rendererInstance.getPerformanceStats();
       if (stats.fps > 0) {
-        const version = "2.5.114";
+        const version = "2.5.115";
         telemetryCollector = startTelemetry(rendererInstance, version, props.disableTelemetry, props.isPreview);
         if (telemetryCollector) {
           telemetryCollector.start();

package/dist/svelte/engine/Preview.svelte.d.ts

@@ -6,6 +6,24 @@ interface Props {
     watermarkText?: string;
     watermarkLink?: string;
     style?: string;
+    /**
+     * Map of camelCase key_prop identifier → user value, layered on top of the
+     * preset's authored defaults. Identifiers are derived from `key_prop.label`
+     * via the same slugify rules the Pro Framer exporter uses, so identifiers
+     * generated by codegen and identifiers expected here always match.
+     *
+     * Only applies on the `presetId` path — `shader` token previews don't carry
+     * key_props and silently ignore this prop.
+     */
+    configuration?: Record<string, unknown>;
+    /**
+     * Lock the preview to a specific snapshot of the preset, addressed by
+     * content hash. Customized snippets pin a version so subsequent upstream
+     * edits don't silently break the configuration. Server falls back to
+     * latest with the `X-Shaders-Version-Fallback` header when the requested
+     * snapshot is missing. Only meaningful on the `presetId` path.
+     */
+    version?: string;
     [key: string]: any;
 }
 declare const Preview: import("svelte").Component<Props, {}, "">;

package/dist/svelte/index.js

@@ -21540,7 +21540,7 @@ function Shader($$anchor, $$props) {
 		const checkRendering = () => {
 			if (!rendererInstance) return;
 			if (rendererInstance.getPerformanceStats().fps > 0) {
-				telemetryCollector = startTelemetry(rendererInstance, "2.5.114", disableTelemetry(), isPreview());
+				telemetryCollector = startTelemetry(rendererInstance, "2.5.115", disableTelemetry(), isPreview());
 				if (telemetryCollector) telemetryCollector.start();
 				telemetryStartTimeout = null;
 			} else telemetryStartTimeout = window.setTimeout(checkRendering, 500);
@@ -21855,14 +21855,111 @@ function Preview($$anchor, $$props) {
 			return res.json();
 		}).then((data) => {
 			const item = data.preset || data.shader;
-			if (item?.definition && typeof item.definition === "string") return decodePreviewDefinition(item.definition, key);
-			return null;
+			if (item?.definition && typeof item.definition === "string") return {
+				definition: decodePreviewDefinition(item.definition, key),
+				keyProps: Array.isArray(item.key_props) ? item.key_props : null
+			};
+			return {
+				definition: null,
+				keyProps: null
+			};
 		}).catch((err) => {
 			console.error("[Shaders Preview] Failed to fetch preview:", err);
-			return null;
+			return {
+				definition: null,
+				keyProps: null
+			};
+		});
+	}
+	const RESERVED_IDENTIFIERS = new Set([
+		"break",
+		"case",
+		"catch",
+		"class",
+		"const",
+		"continue",
+		"default",
+		"delete",
+		"do",
+		"else",
+		"export",
+		"extends",
+		"finally",
+		"for",
+		"function",
+		"if",
+		"import",
+		"in",
+		"instanceof",
+		"new",
+		"return",
+		"super",
+		"switch",
+		"this",
+		"throw",
+		"try",
+		"typeof",
+		"var",
+		"void",
+		"while",
+		"with",
+		"yield"
+	]);
+	function slugifyIdentifier(label, fallback) {
+		const cleaned = label.replace(/[^A-Za-z0-9]+/g, " ").trim();
+		if (!cleaned) return fallback;
+		const camel = cleaned.split(/\s+/).map((part, i) => i === 0 ? part.charAt(0).toLowerCase() + part.slice(1) : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+		const safe = /^[A-Za-z_$]/.test(camel) ? camel : `_${camel}`;
+		return RESERVED_IDENTIFIERS.has(safe) ? `_${safe}` : safe;
+	}
+	function buildKeyPropIdentifierMap(keyProps) {
+		const used = new Set(["style"]);
+		const map = /* @__PURE__ */ new Map();
+		if (!keyProps?.length) return map;
+		keyProps.forEach((kp, i) => {
+			if (!kp.targets?.length) return;
+			const base = slugifyIdentifier(kp.label, `keyProp${i}`);
+			let ident = base;
+			let suffix = 1;
+			while (used.has(ident)) {
+				suffix++;
+				ident = `${base}${suffix}`;
+			}
+			used.add(ident);
+			map.set(ident, kp);
 		});
+		return map;
+	}
+	function findInTree(id, list) {
+		for (const c of list) {
+			if (c.id === id) return c;
+			if (c.children?.length) {
+				const hit = findInTree(id, c.children);
+				if (hit) return hit;
+			}
+		}
+		return null;
+	}
+	function applyConfiguration(definition, configuration$1, keyProps) {
+		if (!configuration$1 || !keyProps?.length) return definition;
+		const entries = Object.entries(configuration$1);
+		if (entries.length === 0) return definition;
+		const identMap = buildKeyPropIdentifierMap(keyProps);
+		const cloned = JSON.parse(JSON.stringify(definition.components));
+		for (const [ident, value] of entries) {
+			const kp = identMap.get(ident);
+			if (!kp) continue;
+			for (const t of kp.targets ?? []) {
+				const comp = findInTree(t.component_id, cloned);
+				if (comp?.props && t.prop in comp.props) comp.props[t.prop] = value;
+			}
+		}
+		return {
+			...definition,
+			components: cloned
+		};
 	}
-	const shader = $.prop($$props, "shader", 3, void 0), presetId = $.prop($$props, "presetId", 3, void 0), apiBaseUrl = $.prop($$props, "apiBaseUrl", 3, "https://shaders.com"), obfuscationKey = $.prop($$props, "obfuscationKey", 3, "shaders-preview-key"), watermarkText = $.prop($$props, "watermarkText", 3, "Unlock your Shaders Pro license"), watermarkLink = $.prop($$props, "watermarkLink", 3, "https://shaders.com/dashboard?pricing=true"), style = $.prop($$props, "style", 3, void 0), restProps = $.rest_props($$props, [
+	const shader = $.prop($$props, "shader", 3, void 0), presetId = $.prop($$props, "presetId", 3, void 0), apiBaseUrl = $.prop($$props, "apiBaseUrl", 3, "https://shaders.com"), obfuscationKey = $.prop($$props, "obfuscationKey", 3, "shaders-preview-key"), watermarkText = $.prop($$props, "watermarkText", 3, "Unlock your Shaders Pro license"), watermarkLink = $.prop($$props, "watermarkLink", 3, "https://shaders.com/dashboard?pricing=true"), style = $.prop($$props, "style", 3, void 0), configuration = $.prop($$props, "configuration", 3, void 0), version = $.prop($$props, "version", 3, void 0), restProps = $.rest_props($$props, [
 		"$$slots",
 		"$$events",
 		"$$legacy",
@@ -21872,26 +21969,40 @@ function Preview($$anchor, $$props) {
 		"obfuscationKey",
 		"watermarkText",
 		"watermarkLink",
-		"style"
+		"style",
+		"configuration",
+		"version"
 	]);
 	let fetchedDefinition = $.state(null);
+	let fetchedKeyProps = $.state(null);
 	let watermarkHovered = $.state(false);
-	let resolvedDefinition = $.derived(() => $.get(fetchedDefinition) ?? null);
+	let resolvedDefinition = $.derived(() => $.get(fetchedDefinition) ? applyConfiguration($.get(fetchedDefinition), configuration(), $.get(fetchedKeyProps)) : null);
 	$.user_effect(() => {
 		if (shader()) {
 			$.set(fetchedDefinition, null);
-			fetchAndDecode(`${apiBaseUrl()}/api/preview/shader/${shader()}`, obfuscationKey()).then((def) => {
-				$.set(fetchedDefinition, def, true);
+			$.set(fetchedKeyProps, null);
+			fetchAndDecode(`${apiBaseUrl()}/api/preview/shader/${shader()}`, obfuscationKey()).then((result) => {
+				$.set(fetchedDefinition, result.definition, true);
+				$.set(fetchedKeyProps, result.keyProps, true);
 			});
-		} else if (!presetId()) $.set(fetchedDefinition, null);
+		} else if (!presetId()) {
+			$.set(fetchedDefinition, null);
+			$.set(fetchedKeyProps, null);
+		}
 	});
 	$.user_effect(() => {
 		if (presetId()) {
 			$.set(fetchedDefinition, null);
-			fetchAndDecode(`${apiBaseUrl()}/api/preview/preset/${presetId()}`, obfuscationKey()).then((def) => {
-				$.set(fetchedDefinition, def, true);
+			$.set(fetchedKeyProps, null);
+			const versionParam = version() ? `?version=${encodeURIComponent(version())}` : "";
+			fetchAndDecode(`${apiBaseUrl()}/api/preview/preset/${presetId()}${versionParam}`, obfuscationKey()).then((result) => {
+				$.set(fetchedDefinition, result.definition, true);
+				$.set(fetchedKeyProps, result.keyProps, true);
 			});
-		} else if (!shader()) $.set(fetchedDefinition, null);
+		} else if (!shader()) {
+			$.set(fetchedDefinition, null);
+			$.set(fetchedKeyProps, null);
+		}
 	});
 	onMount(() => {
 		console.warn("[Shaders] Preview component is intended for use with a Shaders license. Visit https://shaders.com for more information.");

package/dist/svelte/source/engine/Preview.svelte

@@ -247,6 +247,18 @@ interface ShaderDefinition {
   devicePreview?: string
 }
 
+interface KeyPropTarget {
+  component_id: string
+  prop: string
+}
+
+interface KeyProp {
+  label: string
+  type: 'color' | 'range' | 'logo' | 'image'
+  category?: string
+  targets: KeyPropTarget[]
+}
+
 // --- Preview Decode Logic ---
 // No name mapping — preview definitions contain readable JSON.
 
@@ -274,8 +286,13 @@ function decodePreviewDefinition(encoded: string, key: string): ShaderDefinition
   }
 }
 
-// Fetch from API and decode response
-function fetchAndDecode(url: string, key: string): Promise<ShaderDefinition | null> {
+// Fetch from API and decode response, returning both the definition and key_props
+interface FetchResult {
+  definition: ShaderDefinition | null
+  keyProps: KeyProp[] | null
+}
+
+function fetchAndDecode(url: string, key: string): Promise<FetchResult> {
   return fetch(url)
     .then(res => {
       if (!res.ok) throw new Error(`Failed to fetch: ${res.status}`)
@@ -284,16 +301,94 @@ function fetchAndDecode(url: string, key: string): Promise<ShaderDefinition | nu
     .then(data => {
       const item = data.preset || data.shader
       if (item?.definition && typeof item.definition === 'string') {
-        return decodePreviewDefinition(item.definition, key)
+        return {
+          definition: decodePreviewDefinition(item.definition, key),
+          keyProps: Array.isArray(item.key_props) ? item.key_props : null,
+        }
       }
-      return null
+      return { definition: null, keyProps: null }
     })
     .catch(err => {
       console.error('[Shaders Preview] Failed to fetch preview:', err)
-      return null
+      return { definition: null, keyProps: null }
     })
 }
 
+// --- Configuration apply ---
+// Source of truth: dotcom/utils/keyPropsIdentifier.ts. Inlined per framework
+// because the build pipeline copies framework dist into the published npm
+// package and won't carry a cross-package import.
+
+const RESERVED_IDENTIFIERS = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'default',
+  'delete', 'do', 'else', 'export', 'extends', 'finally', 'for',
+  'function', 'if', 'import', 'in', 'instanceof', 'new', 'return',
+  'super', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void',
+  'while', 'with', 'yield',
+])
+
+function slugifyIdentifier(label: string, fallback: string): string {
+  const cleaned = label.replace(/[^A-Za-z0-9]+/g, ' ').trim()
+  if (!cleaned) return fallback
+  const parts = cleaned.split(/\s+/)
+  const camel = parts
+    .map((part, i) => i === 0 ? part.charAt(0).toLowerCase() + part.slice(1) : part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  const safe = /^[A-Za-z_$]/.test(camel) ? camel : `_${camel}`
+  return RESERVED_IDENTIFIERS.has(safe) ? `_${safe}` : safe
+}
+
+function buildKeyPropIdentifierMap(keyProps: KeyProp[] | null | undefined): Map<string, KeyProp> {
+  const used = new Set<string>(['style'])
+  const map = new Map<string, KeyProp>()
+  if (!keyProps?.length) return map
+  keyProps.forEach((kp, i) => {
+    if (!kp.targets?.length) return
+    const base = slugifyIdentifier(kp.label, `keyProp${i}`)
+    let ident = base
+    let suffix = 1
+    while (used.has(ident)) {
+      suffix++
+      ident = `${base}${suffix}`
+    }
+    used.add(ident)
+    map.set(ident, kp)
+  })
+  return map
+}
+
+function findInTree(id: string, list: ShaderComponent[]): ShaderComponent | null {
+  for (const c of list) {
+    if (c.id === id) return c
+    if (c.children?.length) {
+      const hit = findInTree(id, c.children)
+      if (hit) return hit
+    }
+  }
+  return null
+}
+
+function applyConfiguration(
+  definition: ShaderDefinition,
+  configuration: Record<string, unknown> | null | undefined,
+  keyProps: KeyProp[] | null | undefined
+): ShaderDefinition {
+  if (!configuration || !keyProps?.length) return definition
+  const entries = Object.entries(configuration)
+  if (entries.length === 0) return definition
+  const identMap = buildKeyPropIdentifierMap(keyProps)
+  const cloned = JSON.parse(JSON.stringify(definition.components)) as ShaderComponent[]
+  for (const [ident, value] of entries) {
+    const kp = identMap.get(ident)
+    if (!kp) continue
+    for (const t of kp.targets ?? []) {
+      const comp = findInTree(t.component_id, cloned)
+      if (comp?.props && t.prop in comp.props) comp.props[t.prop] = value
+    }
+  }
+  return { ...definition, components: cloned }
+}
+
 // --- Props ---
 
 interface Props {
@@ -304,6 +399,24 @@ interface Props {
   watermarkText?: string
   watermarkLink?: string
   style?: string
+  /**
+   * Map of camelCase key_prop identifier → user value, layered on top of the
+   * preset's authored defaults. Identifiers are derived from `key_prop.label`
+   * via the same slugify rules the Pro Framer exporter uses, so identifiers
+   * generated by codegen and identifiers expected here always match.
+   *
+   * Only applies on the `presetId` path — `shader` token previews don't carry
+   * key_props and silently ignore this prop.
+   */
+  configuration?: Record<string, unknown>
+  /**
+   * Lock the preview to a specific snapshot of the preset, addressed by
+   * content hash. Customized snippets pin a version so subsequent upstream
+   * edits don't silently break the configuration. Server falls back to
+   * latest with the `X-Shaders-Version-Fallback` header when the requested
+   * snapshot is missing. Only meaningful on the `presetId` path.
+   */
+  version?: string
   [key: string]: any
 }
 
@@ -315,35 +428,46 @@ const {
   watermarkText = 'Unlock your Shaders Pro license',
   watermarkLink = 'https://shaders.com/dashboard?pricing=true',
   style = undefined,
+  configuration = undefined,
+  version = undefined,
   ...restProps
 }: Props = $props()
 
 // --- Decode & Resolve ---
 
 let fetchedDefinition: ShaderDefinition | null = $state(null)
+let fetchedKeyProps: KeyProp[] | null = $state(null)
 let watermarkHovered = $state(false)
 
-let resolvedDefinition: ShaderDefinition | null = $derived(fetchedDefinition ?? null)
+let resolvedDefinition: ShaderDefinition | null = $derived(
+  fetchedDefinition ? applyConfiguration(fetchedDefinition, configuration, fetchedKeyProps) : null
+)
 
 // Fetch shader by token
 $effect(() => {
   if (shader) {
     fetchedDefinition = null
+    fetchedKeyProps = null
     fetchAndDecode(`${apiBaseUrl}/api/preview/shader/${shader}`, obfuscationKey)
-      .then(def => { fetchedDefinition = def })
+      .then(result => { fetchedDefinition = result.definition; fetchedKeyProps = result.keyProps })
   } else if (!presetId) {
     fetchedDefinition = null
+    fetchedKeyProps = null
   }
 })
 
-// Fetch preset by ID
+// Fetch preset by ID. Version pins the preview to a snapshot; when omitted,
+// the server returns latest.
 $effect(() => {
   if (presetId) {
     fetchedDefinition = null
-    fetchAndDecode(`${apiBaseUrl}/api/preview/preset/${presetId}`, obfuscationKey)
-      .then(def => { fetchedDefinition = def })
+    fetchedKeyProps = null
+    const versionParam = version ? `?version=${encodeURIComponent(version)}` : ''
+    fetchAndDecode(`${apiBaseUrl}/api/preview/preset/${presetId}${versionParam}`, obfuscationKey)
+      .then(result => { fetchedDefinition = result.definition; fetchedKeyProps = result.keyProps })
   } else if (!shader) {
     fetchedDefinition = null
+    fetchedKeyProps = null
   }
 })