fundus 0.25.0 → 0.27.0

package/dist/core/figma-tag-script.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Plugin-API code that reads and writes Fundus tags inside a Figma document.
+ * Two runtimes execute it: the Fundus Figma plugin imports these functions
+ * directly, and the CLI serializes them (via `Function.prototype.toString`)
+ * into a script an agent runs through Figma's MCP `use_figma` tool. The Figma
+ * REST API cannot write plugin data, so a script is the only headless write
+ * path.
+ *
+ * Serialization constrains every function listed in `SCRIPT_FUNCTIONS`: it
+ * may reference only its parameters, the other listed functions, and the
+ * constants in `SCRIPT_CONSTANTS` — never imports or other module scope. The
+ * `figma` global is passed in as a parameter so tests can drive the same code
+ * against a fake document.
+ */
+/** Shared-plugin-data namespace; the REST API returns it under `sharedPluginData`. */
+export declare const FIGMA_TAG_NAMESPACE = "fundus";
+/** Key holding the node's Fundus asset id (the tag). */
+export declare const FIGMA_TAG_KEY = "assetId";
+/**
+ * Key holding the exact label of the annotation Fundus owns on the node; empty
+ * when it owns none. Tracking ownership out-of-band keeps the visible label
+ * exactly equal to the tag and leaves the user's own annotations untouched.
+ */
+export declare const FIGMA_ANNOTATION_LABEL_KEY = "annotationLabel";
+/**
+ * Visible prefix earlier plugin builds used as the ownership marker. Still
+ * recognized so those annotations are migrated or stripped instead of
+ * duplicated.
+ */
+export declare const LEGACY_ANNOTATION_PREFIX = "Fundus asset: ";
+/** The annotation fields Fundus reads and writes (a subset of Figma's `Annotation`). */
+export interface FigmaAnnotation {
+    readonly label?: string;
+    readonly labelMarkdown?: string;
+    readonly properties?: ReadonlyArray<{
+        readonly type: string;
+    }>;
+    readonly categoryId?: string;
+}
+/** The node surface Fundus uses (a structural subset of Figma's `BaseNode`). */
+export interface FigmaTagNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly parent: FigmaTagNode | null;
+    getSharedPluginData(namespace: string, key: string): string;
+    setSharedPluginData(namespace: string, key: string, value: string): void;
+}
+export interface FigmaAnnotatableNode extends FigmaTagNode {
+    annotations: ReadonlyArray<FigmaAnnotation>;
+}
+export interface FigmaTagPage extends FigmaTagNode {
+    loadAsync(): Promise<void>;
+    findAll(predicate: (node: FigmaTagNode) => boolean): FigmaTagNode[];
+}
+/** The `figma` global surface the tag scripts use. */
+export interface FigmaTagApi {
+    readonly root: {
+        readonly children: ReadonlyArray<FigmaTagPage>;
+    };
+    getNodeByIdAsync(id: string): Promise<FigmaTagNode | null>;
+}
+export interface SetFigmaTagInput {
+    nodeId: string;
+    tag: string;
+    /** Replace a different tag on the node, or rewrite the same one. */
+    force: boolean;
+}
+export interface SetFigmaTagResult {
+    ok: true;
+    nodeId: string;
+    nodeName: string;
+    tag: string;
+    previousTag: string | null;
+    /** False for node types without annotation support (e.g. Group, Section). */
+    annotated: boolean;
+}
+export interface DeleteFigmaTagInput {
+    nodeId: string;
+    /** The tag the node is expected to carry; guards against a stale plan. */
+    tag: string;
+}
+export interface DeleteFigmaTagResult {
+    ok: true;
+    nodeId: string;
+    nodeName: string;
+    removedTag: string;
+    annotationRemoved: boolean;
+}
+/**
+ * Whether the id names a node inside an instance (`I<instance>;<source>`).
+ * Such nodes inherit the shared plugin data of the main component's node, so
+ * they report its tag without being a separate taggable node.
+ */
+export declare function isInstanceSublayerId(id: string): boolean;
+export declare function supportsAnnotations(node: FigmaTagNode): node is FigmaAnnotatableNode;
+/**
+ * The annotation's shown text. Figma reports a plain-label annotation with
+ * `labelMarkdown: ""`, so an empty markdown field falls back to `label`.
+ */
+export declare function annotationText(annotation: FigmaAnnotation): string;
+/**
+ * Figma returns BOTH `label` and `labelMarkdown` when reading annotations, but
+ * the setter rejects an annotation that carries both. Re-emit a single-field
+ * copy (non-empty markdown first), preserving `properties`/`categoryId`, so
+ * preserved annotations can be written back without failing validation.
+ */
+export declare function writableAnnotation(annotation: FigmaAnnotation): FigmaAnnotation;
+/** Whether this annotation is one Fundus owns — by the stored label or the legacy prefix. */
+export declare function isFundusAnnotation(annotation: FigmaAnnotation, ownedLabel: string): boolean;
+/**
+ * Ensure the node carries exactly one Fundus annotation whose label is the tag,
+ * preserving all others. Writes only when not already in sync, so a steady
+ * state neither dirties the file nor adds undo steps.
+ */
+export declare function writeFundusAnnotation(node: FigmaAnnotatableNode, tag: string): void;
+/** Remove the Fundus annotation (incl. legacy), preserving all others. */
+export declare function stripFundusAnnotation(node: FigmaAnnotatableNode): void;
+export declare function pageOfNode(node: FigmaTagNode): FigmaTagPage | null;
+/**
+ * Resolve a scene node and load its page. `loadAsync` loads without
+ * navigating, so running a script never moves anyone's canvas.
+ */
+export declare function loadTaggableNode(figma: FigmaTagApi, nodeId: string): Promise<FigmaTagNode>;
+/**
+ * The first other node carrying `tag`, across every page. Scripts start with
+ * only the first page loaded, and `findAll` on an unloaded page silently
+ * misses content, so each page is loaded first.
+ */
+export declare function findTagHolder(figma: FigmaTagApi, tag: string, exceptNodeId: string): Promise<{
+    node: FigmaTagNode;
+    page: FigmaTagPage;
+} | null>;
+/**
+ * Tag a node, re-checking the live document right before writing: the CLI's
+ * REST snapshot can lag behind edits made since it ran.
+ */
+export declare function setFundusTag(figma: FigmaTagApi, input: SetFigmaTagInput): Promise<SetFigmaTagResult>;
+export declare function deleteFundusTag(figma: FigmaTagApi, input: DeleteFigmaTagInput): Promise<DeleteFigmaTagResult>;
+export declare function buildSetTagScript(input: SetFigmaTagInput): string;
+export declare function buildDeleteTagScript(input: DeleteFigmaTagInput): string;

package/dist/core/figma-tag-script.js

@@ -0,0 +1,236 @@
+/**
+ * Plugin-API code that reads and writes Fundus tags inside a Figma document.
+ * Two runtimes execute it: the Fundus Figma plugin imports these functions
+ * directly, and the CLI serializes them (via `Function.prototype.toString`)
+ * into a script an agent runs through Figma's MCP `use_figma` tool. The Figma
+ * REST API cannot write plugin data, so a script is the only headless write
+ * path.
+ *
+ * Serialization constrains every function listed in `SCRIPT_FUNCTIONS`: it
+ * may reference only its parameters, the other listed functions, and the
+ * constants in `SCRIPT_CONSTANTS` — never imports or other module scope. The
+ * `figma` global is passed in as a parameter so tests can drive the same code
+ * against a fake document.
+ */
+/** Shared-plugin-data namespace; the REST API returns it under `sharedPluginData`. */
+export const FIGMA_TAG_NAMESPACE = 'fundus';
+/** Key holding the node's Fundus asset id (the tag). */
+export const FIGMA_TAG_KEY = 'assetId';
+/**
+ * Key holding the exact label of the annotation Fundus owns on the node; empty
+ * when it owns none. Tracking ownership out-of-band keeps the visible label
+ * exactly equal to the tag and leaves the user's own annotations untouched.
+ */
+export const FIGMA_ANNOTATION_LABEL_KEY = 'annotationLabel';
+/**
+ * Visible prefix earlier plugin builds used as the ownership marker. Still
+ * recognized so those annotations are migrated or stripped instead of
+ * duplicated.
+ */
+export const LEGACY_ANNOTATION_PREFIX = 'Fundus asset: ';
+/**
+ * Whether the id names a node inside an instance (`I<instance>;<source>`).
+ * Such nodes inherit the shared plugin data of the main component's node, so
+ * they report its tag without being a separate taggable node.
+ */
+export function isInstanceSublayerId(id) {
+    return id.startsWith('I');
+}
+export function supportsAnnotations(node) {
+    return 'annotations' in node;
+}
+/**
+ * The annotation's shown text. Figma reports a plain-label annotation with
+ * `labelMarkdown: ""`, so an empty markdown field falls back to `label`.
+ */
+export function annotationText(annotation) {
+    return annotation.labelMarkdown || annotation.label || '';
+}
+/**
+ * Figma returns BOTH `label` and `labelMarkdown` when reading annotations, but
+ * the setter rejects an annotation that carries both. Re-emit a single-field
+ * copy (non-empty markdown first), preserving `properties`/`categoryId`, so
+ * preserved annotations can be written back without failing validation.
+ */
+export function writableAnnotation(annotation) {
+    const copy = {};
+    if (annotation.labelMarkdown)
+        copy.labelMarkdown = annotation.labelMarkdown;
+    else if (annotation.label !== undefined)
+        copy.label = annotation.label;
+    if (annotation.properties)
+        copy.properties = annotation.properties;
+    if (annotation.categoryId)
+        copy.categoryId = annotation.categoryId;
+    return copy;
+}
+/** Whether this annotation is one Fundus owns — by the stored label or the legacy prefix. */
+export function isFundusAnnotation(annotation, ownedLabel) {
+    const text = annotationText(annotation);
+    return (ownedLabel !== '' && text === ownedLabel) || text.startsWith(LEGACY_ANNOTATION_PREFIX);
+}
+/**
+ * Ensure the node carries exactly one Fundus annotation whose label is the tag,
+ * preserving all others. Writes only when not already in sync, so a steady
+ * state neither dirties the file nor adds undo steps.
+ */
+export function writeFundusAnnotation(node, tag) {
+    const owned = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY);
+    const current = node.annotations;
+    const ours = current.filter((annotation) => isFundusAnnotation(annotation, owned));
+    const inSync = owned === tag && ours.length === 1 && annotationText(ours[0]) === tag;
+    if (inSync)
+        return;
+    const kept = current
+        .filter((annotation) => !isFundusAnnotation(annotation, owned) && annotationText(annotation) !== tag)
+        .map(writableAnnotation);
+    node.annotations = [...kept, { label: tag }];
+    if (owned !== tag) {
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, tag);
+    }
+}
+/** Remove the Fundus annotation (incl. legacy), preserving all others. */
+export function stripFundusAnnotation(node) {
+    const owned = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY);
+    const current = node.annotations;
+    const kept = current
+        .filter((annotation) => !isFundusAnnotation(annotation, owned))
+        .map(writableAnnotation);
+    if (kept.length !== current.length)
+        node.annotations = kept;
+    if (owned !== '')
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, '');
+}
+export function pageOfNode(node) {
+    let current = node;
+    while (current && current.type !== 'PAGE')
+        current = current.parent;
+    return current ? current : null;
+}
+/**
+ * Resolve a scene node and load its page. `loadAsync` loads without
+ * navigating, so running a script never moves anyone's canvas.
+ */
+export async function loadTaggableNode(figma, nodeId) {
+    const node = await figma.getNodeByIdAsync(nodeId);
+    const page = node ? pageOfNode(node) : null;
+    if (!node || !page || node.type === 'PAGE') {
+        throw new Error(`Figma node "${nodeId}" does not exist in this file.`);
+    }
+    await page.loadAsync();
+    return node;
+}
+/**
+ * The first other node carrying `tag`, across every page. Scripts start with
+ * only the first page loaded, and `findAll` on an unloaded page silently
+ * misses content, so each page is loaded first.
+ */
+export async function findTagHolder(figma, tag, exceptNodeId) {
+    for (const page of figma.root.children) {
+        await page.loadAsync();
+        const [holder] = page.findAll((candidate) => candidate.id !== exceptNodeId &&
+            !isInstanceSublayerId(candidate.id) &&
+            candidate.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY) === tag);
+        if (holder)
+            return { node: holder, page };
+    }
+    return null;
+}
+/**
+ * Tag a node, re-checking the live document right before writing: the CLI's
+ * REST snapshot can lag behind edits made since it ran.
+ */
+export async function setFundusTag(figma, input) {
+    const node = await loadTaggableNode(figma, input.nodeId);
+    const previous = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY);
+    if (!input.force && previous === input.tag) {
+        throw new Error(`Node "${node.name}" (${node.id}) already carries tag "${input.tag}"; rerun prepare-set-tag with --force to rewrite it.`);
+    }
+    if (!input.force && previous !== '') {
+        throw new Error(`Node "${node.name}" (${node.id}) already carries tag "${previous}"; rerun prepare-set-tag with --force to replace it.`);
+    }
+    const holder = await findTagHolder(figma, input.tag, node.id);
+    if (holder) {
+        throw new Error(`Tag "${input.tag}" is already used by "${holder.node.name}" (${holder.node.id}) on page "${holder.page.name}"; choose another tag.`);
+    }
+    node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY, input.tag);
+    const annotated = supportsAnnotations(node);
+    if (annotated)
+        writeFundusAnnotation(node, input.tag);
+    return {
+        ok: true,
+        nodeId: node.id,
+        nodeName: node.name,
+        tag: input.tag,
+        previousTag: previous === '' ? null : previous,
+        annotated
+    };
+}
+export async function deleteFundusTag(figma, input) {
+    const node = await loadTaggableNode(figma, input.nodeId);
+    const current = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY);
+    if (current !== input.tag) {
+        throw new Error(current === ''
+            ? `Node "${node.name}" (${node.id}) carries no Fundus tag.`
+            : `Node "${node.name}" (${node.id}) carries tag "${current}", not "${input.tag}"; rerun prepare-delete-tag.`);
+    }
+    node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY, '');
+    let annotationRemoved = false;
+    if (supportsAnnotations(node)) {
+        const before = node.annotations.length;
+        stripFundusAnnotation(node);
+        annotationRemoved = node.annotations.length < before;
+    }
+    else {
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, '');
+    }
+    return {
+        ok: true,
+        nodeId: node.id,
+        nodeName: node.name,
+        removedTag: input.tag,
+        annotationRemoved
+    };
+}
+const SCRIPT_CONSTANTS = {
+    FIGMA_TAG_NAMESPACE,
+    FIGMA_TAG_KEY,
+    FIGMA_ANNOTATION_LABEL_KEY,
+    LEGACY_ANNOTATION_PREFIX
+};
+const SCRIPT_FUNCTIONS = [
+    isInstanceSublayerId,
+    supportsAnnotations,
+    annotationText,
+    writableAnnotation,
+    isFundusAnnotation,
+    writeFundusAnnotation,
+    stripFundusAnnotation,
+    pageOfNode,
+    loadTaggableNode,
+    findTagHolder,
+    setFundusTag,
+    deleteFundusTag
+];
+/**
+ * A self-contained `use_figma` script body: top-level `await` and `return`,
+ * with the `figma` global in scope. It returns the operation's JSON result
+ * and throws, before mutating anything, when the live document disagrees.
+ */
+function buildScript(summary, call) {
+    const constants = Object.entries(SCRIPT_CONSTANTS).map(([name, value]) => `const ${name} = ${JSON.stringify(value)};`);
+    return [
+        `// ${summary}`,
+        '// Generated by the fundus CLI — run it unchanged with the Figma MCP `use_figma` tool.',
+        ...constants,
+        ...SCRIPT_FUNCTIONS.map(String),
+        `return await ${call};`,
+        ''
+    ].join('\n\n');
+}
+export function buildSetTagScript(input) {
+    return buildScript(`Set Fundus tag ${JSON.stringify(input.tag)} on Figma node ${JSON.stringify(input.nodeId)}.`, `setFundusTag(figma, ${JSON.stringify(input)})`);
+}
+export function buildDeleteTagScript(input) {
+    return buildScript(`Delete Fundus tag ${JSON.stringify(input.tag)} from Figma node ${JSON.stringify(input.nodeId)}.`, `deleteFundusTag(figma, ${JSON.stringify(input)})`);
+}

package/dist/core/index.d.ts

@@ -3,6 +3,8 @@ export { createEmptyLibrary, parseLibrary, serializeLibrary } from './library.js
 export { rawFileNameError, rawFilePathError, portableRawPathKey, isFundusTransactionName } from './raw-path.js';
 export { ROOT_FOLDER, FOLDER_SENTINEL, folderNameError, folderPathError, normalizeFolderPath, portableFolderPathKey, parentFolderPath, folderNameOf, joinFolderPath, folderOfRawPath, rawFileNameOfPath, isFolderOrDescendant, replaceFolderPrefix } from './folder-path.js';
 export { RESERVED_ASSET_IDS, isValidAssetId, assetIdError, manifestNameError } from './asset-id.js';
+export type { SetFigmaTagInput, SetFigmaTagResult, DeleteFigmaTagInput, DeleteFigmaTagResult } from './figma-tag-script.js';
+export { buildSetTagScript, buildDeleteTagScript, isInstanceSublayerId } from './figma-tag-script.js';
 export type { ManifestColor } from './manifest-appearance.js';
 export { MANIFEST_COLORS, MANIFEST_EMOJIS, isManifestColor, isManifestEmoji, resolveManifestColor, manifestColorError, manifestEmojiError } from './manifest-appearance.js';
 export { acceptedExtensions, acceptedExtensionsForType, typesForFileName, proposeAssetId } from './ingest.js';

package/dist/core/index.js

@@ -2,6 +2,7 @@ export { createEmptyLibrary, parseLibrary, serializeLibrary } from './library.js
 export { rawFileNameError, rawFilePathError, portableRawPathKey, isFundusTransactionName } from './raw-path.js';
 export { ROOT_FOLDER, FOLDER_SENTINEL, folderNameError, folderPathError, normalizeFolderPath, portableFolderPathKey, parentFolderPath, folderNameOf, joinFolderPath, folderOfRawPath, rawFileNameOfPath, isFolderOrDescendant, replaceFolderPrefix } from './folder-path.js';
 export { RESERVED_ASSET_IDS, isValidAssetId, assetIdError, manifestNameError } from './asset-id.js';
+export { buildSetTagScript, buildDeleteTagScript, isInstanceSublayerId } from './figma-tag-script.js';
 export { MANIFEST_COLORS, MANIFEST_EMOJIS, isManifestColor, isManifestEmoji, resolveManifestColor, manifestColorError, manifestEmojiError } from './manifest-appearance.js';
 export { acceptedExtensions, acceptedExtensionsForType, typesForFileName, proposeAssetId } from './ingest.js';
 export { canonicalizeParameters, compareCodeUnits } from './canonicalize.js';

package/dist/runtime/chroma-key-gl.d.ts

@@ -6,13 +6,21 @@
  * The keying algorithm follows the upstream shader: the key color and each
  * pixel are converted to YCbCr chroma (Cb/Cr), the squared chroma distance is mapped
  * through a cutoff/feather window (`colorclose`), the resulting mask is blurred with a
- * 3×3 neighbourhood + smoothstep-sharpened, the keyed color is despilled (green pulled
- * toward the red/blue average, lost luminance re-added), and the output is
+ * 3×3 neighbourhood + smoothstep-sharpened, the keyed color is despilled (lost
+ * luminance re-added), and the output is
  * `vec4(color * mask, mask)` — the upstream output formula (tint fixed at white; tinting
  * is host styling, not asset data) — emitted premultiplied (rgb × alpha) for the canvas
  * compositor (see the fragColor note).
  *
- * Fundus adds an optional mask pass (`setMask`): a grayscale image
+ * Fundus replaces the upstream despill, which hard-codes greenscreen (green pulled toward
+ * (2b + r) / 4 — it misses any other key's spill, and tints white and gray pink even for
+ * green keys). Fundus's despill follows the key color: the key's dominant channels
+ * (`spillChannels`) are clamped down to the pixel's strongest remaining channel, so
+ * only excess in the key's direction is removed and neutral colors stay exact. For a
+ * green key that is the classic "clamp g to max(r, b)". `despillCoverage` fades the
+ * despill out over opaque pixels, so artwork colored like the key survives.
+ *
+ * Fundus also adds an optional mask pass (`setMask`): a grayscale image
  * sampled at the same UVs whose luminance multiplies the final alpha — white keeps a
  * pixel, black drops it, gray fades it (no alpha clip). Absent a mask, a 1×1 white
  * fallback texture makes the pass a no-op.
@@ -20,7 +28,7 @@
  * Owns its own GL context on the given canvas. `create` returns null when WebGL2 is
  * unavailable. Browser-only; the caller drives it per frame with the playing <video>.
  */
-import type { ChromaKeyParameters } from '../core/index.js';
+import { type ChromaKeyParameters } from '../core/index.js';
 export declare class ChromaKeyGl {
     #private;
     /** Returns null when WebGL2 is unavailable or the shader fails to compile. */

package/dist/runtime/chroma-key-gl.js

@@ -1,3 +1,34 @@
+/**
+ * WebGL2 chroma-key video renderer based on the public UnityChromakey shader
+ * (https://github.com/otdavies/UnityChromakey, `Shaders/ChromaKey.shader`) so a
+ * greenscreen video plays with a transparent background.
+ *
+ * The keying algorithm follows the upstream shader: the key color and each
+ * pixel are converted to YCbCr chroma (Cb/Cr), the squared chroma distance is mapped
+ * through a cutoff/feather window (`colorclose`), the resulting mask is blurred with a
+ * 3×3 neighbourhood + smoothstep-sharpened, the keyed color is despilled (lost
+ * luminance re-added), and the output is
+ * `vec4(color * mask, mask)` — the upstream output formula (tint fixed at white; tinting
+ * is host styling, not asset data) — emitted premultiplied (rgb × alpha) for the canvas
+ * compositor (see the fragColor note).
+ *
+ * Fundus replaces the upstream despill, which hard-codes greenscreen (green pulled toward
+ * (2b + r) / 4 — it misses any other key's spill, and tints white and gray pink even for
+ * green keys). Fundus's despill follows the key color: the key's dominant channels
+ * (`spillChannels`) are clamped down to the pixel's strongest remaining channel, so
+ * only excess in the key's direction is removed and neutral colors stay exact. For a
+ * green key that is the classic "clamp g to max(r, b)". `despillCoverage` fades the
+ * despill out over opaque pixels, so artwork colored like the key survives.
+ *
+ * Fundus also adds an optional mask pass (`setMask`): a grayscale image
+ * sampled at the same UVs whose luminance multiplies the final alpha — white keeps a
+ * pixel, black drops it, gray fades it (no alpha clip). Absent a mask, a 1×1 white
+ * fallback texture makes the pass a no-op.
+ *
+ * Owns its own GL context on the given canvas. `create` returns null when WebGL2 is
+ * unavailable. Browser-only; the caller drives it per frame with the playing <video>.
+ */
+import { DEFAULT_CHROMA_KEY_PARAMETERS } from '../core/index.js';
 const VERTEX_SHADER = `#version 300 es
 in vec2 a_pos;
 out vec2 v_uv;
@@ -9,8 +40,8 @@ void main() {
 }`;
 // The upstream fragment, translated HLSL → GLSL. Kept structurally identical (same
 // function names, same sample pattern, same constants) so it can be diffed against
-// the original; only the texel-size plumbing differs (u_texelSize is (1/w, 1/h),
-// Unity's _MainTex_TexelSize packs (1/w, 1/h, w, h)).
+// the original; only the texel-size plumbing (u_texelSize is (1/w, 1/h), Unity's
+// _MainTex_TexelSize packs (1/w, 1/h, w, h)) and the despill block differ.
 const FRAGMENT_SHADER = `#version 300 es
 precision highp float;
 
@@ -28,6 +59,8 @@ uniform float u_maskFeathering;
 uniform float u_sharpening;
 uniform float u_despill;
 uniform float u_despillLuminanceAdd;
+uniform vec3 u_spillChannels;
+uniform float u_despillCoverage;
 
 float rgb2y(vec3 c) {
 	return 0.299 * c.r + 0.587 * c.g + 0.114 * c.b;
@@ -85,9 +118,20 @@ void main() {
 	float smoothedMask = smoothstep(u_sharpening, 1.0, mix(c, blurContribution, u_maskFeathering));
 	vec4 result = color * smoothedMask;
 
-	// Despill
-	float v = (2.0 * result.b + result.r) / 4.0;
-	if (result.g > v) result.g = mix(result.g, v, u_despill);
+	// Despill (Fundus, see the header): clamp the spill channels to the strongest other
+	// channel. Non-spill channels read as 1.0 in the min and 0.0 in the max (result is
+	// in 0–1); a key without spill channels has an all-zero mask and subtracts nothing.
+	vec3 spillValues = mix(vec3(1.0), result.rgb, u_spillChannels);
+	vec3 otherValues = result.rgb * (1.0 - u_spillChannels);
+	float spillExcess = max(
+		min(spillValues.r, min(spillValues.g, spillValues.b)) -
+			max(otherValues.r, max(otherValues.g, otherValues.b)),
+		0.0
+	);
+	// Full despill where the mask is at most 0.8 (the keyed edge), coverage-scaled
+	// above it.
+	float coverage = mix(1.0 - smoothstep(0.8, 1.0, smoothedMask), 1.0, u_despillCoverage);
+	result.rgb -= u_spillChannels * spillExcess * u_despill * coverage;
 	vec4 dif = color - result;
 	float desaturatedDif = rgb2y(dif.xyz);
 	result += mix(0.0, desaturatedDif, u_despillLuminanceAdd);
@@ -107,6 +151,15 @@ void main() {
 	// whole canvas rect on iOS.
 	fragColor = vec4(keyed.rgb * keyed.a, keyed.a);
 }`;
+/**
+ * The key color's spill channels as a 0/1 mask: each channel above the key's channel
+ * mean (green → g; magenta → r, b; cyan → g, b). A gray key has none, so no despill.
+ * Compared as 2c > a + b, which is exact for equal channels.
+ */
+function spillChannels(keyColor) {
+    const [r, g, b] = keyColor;
+    return [2 * r > g + b ? 1 : 0, 2 * g > r + b ? 1 : 0, 2 * b > r + g ? 1 : 0];
+}
 function compileProgram(gl) {
     const compile = (type, source) => {
         const shader = gl.createShader(type);
@@ -202,7 +255,9 @@ export class ChromaKeyGl {
             maskFeathering: location('u_maskFeathering'),
             sharpening: location('u_sharpening'),
             despill: location('u_despill'),
-            despillLuminanceAdd: location('u_despillLuminanceAdd')
+            despillLuminanceAdd: location('u_despillLuminanceAdd'),
+            spillChannels: location('u_spillChannels'),
+            despillCoverage: location('u_despillCoverage')
         };
         gl.uniform1i(gl.getUniformLocation(this.#program, 'u_texture'), 0);
         gl.uniform1i(gl.getUniformLocation(this.#program, 'u_mask'), 1);
@@ -280,6 +335,8 @@ export class ChromaKeyGl {
         gl.uniform1f(this.#uniforms.sharpening, parameters.sharpening);
         gl.uniform1f(this.#uniforms.despill, parameters.despill);
         gl.uniform1f(this.#uniforms.despillLuminanceAdd, parameters.despillLuminanceAdd);
+        gl.uniform3fv(this.#uniforms.spillChannels, spillChannels(parameters.keyColor));
+        gl.uniform1f(this.#uniforms.despillCoverage, parameters.despillCoverage ?? DEFAULT_CHROMA_KEY_PARAMETERS.despillCoverage);
         gl.clear(gl.COLOR_BUFFER_BIT);
         gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
     }

package/dist/runtime/components/ChromaKeyVideo.svelte

@@ -103,7 +103,8 @@
 			maskFeathering: key.maskFeathering,
 			sharpening: key.sharpening,
 			despill: key.despill,
-			despillLuminanceAdd: key.despillLuminanceAdd
+			despillLuminanceAdd: key.despillLuminanceAdd,
+			despillCoverage: key.despillCoverage
 		};
 		lifecycle?.setChromaKey(snapshot);
 	});

package/dist/server/cli-commands.d.ts

@@ -12,6 +12,12 @@ export declare const ASSET_SET_HELP = "fundus asset set \u2014 update an asset's
 export declare const ASSET_RENAME_HELP = "fundus asset rename \u2014 rename an asset id\n\nUsage: fundus asset rename <id> <newId> [--json]\n\nRenames the asset's id (the raw file keeps its name \u2014 ids are the\nstable key) and re-hashes its proxy under the new id via the autosave\nchain. Fails if another asset references <id> \u2014 update the referrers\nfirst \u2014 or if <newId> is taken or invalid.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset rename sidebarPanel navigationPanel --json\n";
 export declare const ASSET_DELETE_HELP = "fundus asset delete \u2014 delete an asset\n\nUsage: fundus asset delete <id> [--json]\n\nDeletes the library record, its raw file, and its proxies, then\nregenerates the affected manifest modules. Fails if another asset\nreferences it \u2014 remove the references first.\n\nFlags:\n  --json   print {\"ok\": true, \"deletedAssetId\": \"<id>\", \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset delete obsoleteBanner --json\n";
 export declare const ASSET_MOVE_HELP = "fundus asset move \u2014 move an asset between folders\n\nUsage: fundus asset move <id> <folder|root> [--json]\n\nMoves the raw file and its current proxy without changing the stable asset id,\nthen runs the autosave chain. The destination folder must already exist; use\nthe literal \"root\" for the implicit root.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset move navigationPanel \"UI/Buttons\" --json\n";
+/**
+ * `--figma-file` accepts either a raw Figma file key or a full design/file link.
+ * A value that parses as a URL is treated as a link (fileKey extracted via
+ * `parseFigmaFileKey`); anything else is passed through as a raw key.
+ */
+export declare function resolveFigmaFileKeyFlag(value: string): string;
 export declare function runAssetCommand(argumentList: string[]): Promise<void>;
 export declare const FOLDER_HELP = "fundus folder \u2014 manage the mirrored raw/proxy folder tree\n\nUsage: fundus folder <subcommand> \u2026\n\nSubcommands:\n  list      list registered folders and their direct assets\n  create    create a persisted folder (fundus folder create <path>)\n  rename    rename one folder segment and its subtree\n  move      move a complete folder subtree below another folder\n  delete    recursively delete a folder subtree and its assets\n\nAll mutations update rawDir and proxyDir together, maintain .gitkeep files,\nand run the full autosave chain. All subcommands accept --json and --help.\n";
 export declare function runFolderCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-commands.js

@@ -898,7 +898,7 @@ function parseFigmaScale(value, commandPath) {
  * A value that parses as a URL is treated as a link (fileKey extracted via
  * `parseFigmaFileKey`); anything else is passed through as a raw key.
  */
-function resolveFigmaFileKeyFlag(value) {
+export function resolveFigmaFileKeyFlag(value) {
     try {
         new URL(value);
     }

package/dist/server/cli-figma-tags.d.ts

@@ -0,0 +1,2 @@
+export declare const FIGMA_HELP = "fundus figma \u2014 prepare Fundus tag writes in Figma\n\nUsage: fundus figma <subcommand> \u2026 [--json]\n\nThe Figma REST API cannot write plugin data, so Fundus cannot tag nodes by\nitself. These commands check the request against the file (via REST) and the\nlibrary, then print a script. Run that script unchanged with the Figma MCP\n`use_figma` tool on the same file: it re-checks the live document (the set\nscript loads every page, which takes a few seconds on large files), writes\nthe tag and its Dev Mode annotation exactly like the Fundus Figma plugin, and\nreturns the result. It throws without writing when the document changed.\n\nSubcommands:\n  prepare-set-tag       tag a node (--node-id, --tag)\n  prepare-delete-tag    remove a node's tag (--tag or --node-id)\n\nRequires import.figma.token in fundus.config.ts.\n";
+export declare function runFigmaCommand(argumentList: string[]): Promise<void>;