fundus 0.24.0 → 0.26.0

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/canvas.d.ts

@@ -1,5 +1,6 @@
 import type { ImageManifestEntry, SliceManifestEntry } from '../core/index.js';
-import type { RetainedEntry } from './retained-entry.js';
+import type { EntryHandle } from './retained-entry.js';
+import type { RetainedEntry } from './retained-entry.svelte.js';
 /** Uses the target's existing 2D context, including its transform and clip. */
 export type CanvasDrawTarget = HTMLCanvasElement | CanvasRenderingContext2D;
 /**
@@ -8,13 +9,15 @@ export type CanvasDrawTarget = HTMLCanvasElement | CanvasRenderingContext2D;
  * The caller owns DPR scaling; explicit dimensions are never scaled by Fundus.
  * Preserves canvas contents and context state. Non-positive sizes draw nothing.
  *
- * Takes the handle from `await retainEntry(entry)`; keep it unreleased until
- * the last draw. This function never loads or decodes the source itself.
+ * Takes the handle from `await retainEntry(entry)` or a `RetainedEntry`; keep
+ * it unreleased until the last draw. This function never loads or decodes the
+ * source itself.
  *
- * @throws {Error} When the handle was released, even for an empty draw.
+ * @throws {Error} When the source is released or not loaded yet, even for an
+ * empty draw.
  * @throws {RangeError} When any coordinate or dimension is not finite.
  */
-export declare function drawImage(target: CanvasDrawTarget, retained: RetainedEntry<ImageManifestEntry>, x: number, y: number, width: number, height: number): void;
+export declare function drawImage(target: CanvasDrawTarget, retained: EntryHandle<ImageManifestEntry> | RetainedEntry<ImageManifestEntry>, x: number, y: number, width: number, height: number): void;
 /**
  * Synchronously paint a retained slice. (x, y, width, height) describes its
  * core layout box in current context units; baked-in overdraw paints outside it.
@@ -22,13 +25,15 @@ export declare function drawImage(target: CanvasDrawTarget, retained: RetainedEn
  * The caller owns DPR scaling, clipping, and clearing. Context state is preserved.
  * Non-positive sizes draw nothing.
  *
- * Takes the handle from `await retainEntry(entry)`; keep it unreleased until
- * the last draw. This function never loads or decodes the source itself.
+ * Takes the handle from `await retainEntry(entry)` or a `RetainedEntry`; keep
+ * it unreleased until the last draw. This function never loads or decodes the
+ * source itself.
  *
- * @throws {Error} When the handle was released, even for an empty draw.
+ * @throws {Error} When the source is released or not loaded yet, even for an
+ * empty draw.
  * @throws {RangeError} When any coordinate or dimension is not finite.
  */
-export declare function drawSlice(target: CanvasDrawTarget, retained: RetainedEntry<SliceManifestEntry>, x: number, y: number, width: number, height: number): void;
+export declare function drawSlice(target: CanvasDrawTarget, retained: EntryHandle<SliceManifestEntry> | RetainedEntry<SliceManifestEntry>, x: number, y: number, width: number, height: number): void;
 /**
  * Paint `sliceGrid`'s cells by its paint rule, without modifying the caller's
  * transform. Shared with Slice, whose source lifecycle also supports loading

package/dist/runtime/canvas.js

@@ -5,6 +5,14 @@ function contextOf(target) {
         throw new Error('Fundus drawing requires a 2D canvas context.');
     return context;
 }
+/** Reads a `RetainedEntry`'s reactive source, so a drawing effect re-runs once it loads. */
+function sourceOf(retained) {
+    const source = retained.source;
+    if (source === undefined) {
+        throw new Error(`RetainedEntry "${retained.entry.id}" has no loaded source.`);
+    }
+    return source;
+}
 function hasArea(x, y, width, height) {
     if (![x, y, width, height].every(Number.isFinite)) {
         throw new RangeError('Fundus drawing coordinates and dimensions must be finite.');
@@ -17,14 +25,16 @@ function hasArea(x, y, width, height) {
  * The caller owns DPR scaling; explicit dimensions are never scaled by Fundus.
  * Preserves canvas contents and context state. Non-positive sizes draw nothing.
  *
- * Takes the handle from `await retainEntry(entry)`; keep it unreleased until
- * the last draw. This function never loads or decodes the source itself.
+ * Takes the handle from `await retainEntry(entry)` or a `RetainedEntry`; keep
+ * it unreleased until the last draw. This function never loads or decodes the
+ * source itself.
  *
- * @throws {Error} When the handle was released, even for an empty draw.
+ * @throws {Error} When the source is released or not loaded yet, even for an
+ * empty draw.
  * @throws {RangeError} When any coordinate or dimension is not finite.
  */
 export function drawImage(target, retained, x, y, width, height) {
-    const source = retained.source;
+    const source = sourceOf(retained);
     if (!hasArea(x, y, width, height))
         return;
     contextOf(target).drawImage(source, x, y, width, height);
@@ -36,14 +46,16 @@ export function drawImage(target, retained, x, y, width, height) {
  * The caller owns DPR scaling, clipping, and clearing. Context state is preserved.
  * Non-positive sizes draw nothing.
  *
- * Takes the handle from `await retainEntry(entry)`; keep it unreleased until
- * the last draw. This function never loads or decodes the source itself.
+ * Takes the handle from `await retainEntry(entry)` or a `RetainedEntry`; keep
+ * it unreleased until the last draw. This function never loads or decodes the
+ * source itself.
  *
- * @throws {Error} When the handle was released, even for an empty draw.
+ * @throws {Error} When the source is released or not loaded yet, even for an
+ * empty draw.
  * @throws {RangeError} When any coordinate or dimension is not finite.
  */
 export function drawSlice(target, retained, x, y, width, height) {
-    const source = retained.source;
+    const source = sourceOf(retained);
     if (!hasArea(x, y, width, height))
         return;
     paintSlice(contextOf(target), retained.entry, source, x, y, width, height);

package/dist/runtime/index.d.ts

@@ -2,7 +2,9 @@ export { Manifest, createManifest } from './manifest.js';
 export { drawImage, drawSlice } from './canvas.js';
 export type { CanvasDrawTarget } from './canvas.js';
 export { retainEntry } from './retained-entry.js';
-export type { RetainedEntry, RetainedSourceOf } from './retained-entry.js';
+export type { EntryHandle, RetainedSourceOf } from './retained-entry.js';
+export { RetainedEntry } from './retained-entry.svelte.js';
+export type { RetainedEntryStatus } from './retained-entry.svelte.js';
 export { default as Image } from './components/Image.svelte';
 export { default as Slice } from './components/Slice.svelte';
 export { sliceGrid, sliceLayoutGeometry } from './geometry.js';

package/dist/runtime/index.js

@@ -2,6 +2,7 @@
 export { Manifest, createManifest } from './manifest.js';
 export { drawImage, drawSlice } from './canvas.js';
 export { retainEntry } from './retained-entry.js';
+export { RetainedEntry } from './retained-entry.svelte.js';
 export { default as Image } from './components/Image.svelte';
 export { default as Slice } from './components/Slice.svelte';
 export { sliceGrid, sliceLayoutGeometry } from './geometry.js';

package/dist/runtime/retained-entry.d.ts

@@ -7,7 +7,7 @@
  */
 import type { ManifestEntry } from '../core/index.js';
 /**
- * The retained source a `RetainedEntry` exposes for its entry kind: decoded
+ * The retained source an `EntryHandle` exposes for its entry kind: decoded
  * pixels for image-backed kinds, a playable URL (an object URL over the fully
  * fetched file where supported) for media kinds.
  */
@@ -17,7 +17,7 @@ export type RetainedSourceOf<E extends ManifestEntry> = E extends {
     kind: 'video' | 'chroma-key-video' | 'audio';
 } ? string : never;
 /** One hold on an entry's loaded source, from `retainEntry`. */
-export interface RetainedEntry<E extends ManifestEntry> {
+export interface EntryHandle<E extends ManifestEntry> {
     readonly entry: E;
     /**
      * The loaded source. The same object for every handle while any holder
@@ -45,4 +45,4 @@ export interface RetainedEntry<E extends ManifestEntry> {
  * fails, or an image-backed source cannot be decoded in this environment.
  * A rejection leaves no hold behind.
  */
-export declare function retainEntry<E extends ManifestEntry>(entry: E): Promise<RetainedEntry<E>>;
+export declare function retainEntry<E extends ManifestEntry>(entry: E): Promise<EntryHandle<E>>;

package/dist/runtime/retained-entry.js

@@ -1,6 +1,6 @@
 import { assertEntryByteSize } from './manifest.js';
 import { acquireSource, releaseSource, resolveRetainedImageSource, resolveRetainedSource } from './preload-registry.js';
-class RetainedEntryHandle {
+class Handle {
     entry;
     /** `null` once released. */
     #source;
@@ -12,7 +12,7 @@ class RetainedEntryHandle {
     // reads it — only an explicit access after release throws.
     get source() {
         if (this.#source === null) {
-            throw new Error(`RetainedEntry "${this.entry.id}" was released.`);
+            throw new Error(`EntryHandle "${this.entry.id}" was released.`);
         }
         return this.#source;
     }
@@ -55,7 +55,7 @@ export async function retainEntry(entry) {
             releaseSource(src);
             throw new Error(`Cannot retain "${id}": this environment cannot decode ${kind} sources.`);
         }
-        return new RetainedEntryHandle(entry, source);
+        return new Handle(entry, source);
     }
-    return new RetainedEntryHandle(entry, resolveRetainedSource(src));
+    return new Handle(entry, resolveRetainedSource(src));
 }

package/dist/runtime/retained-entry.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { ManifestEntry } from '../core/index.js';
+import { type RetainedSourceOf } from './retained-entry.js';
+export type RetainedEntryStatus = 'loading' | 'ready' | 'error' | 'released';
+/**
+ * One hold on `entry`'s own source for the lifetime of the constructing
+ * component, shared with manifests and handles exactly like `retainEntry`.
+ * Construct it during component initialisation; the hold is dropped on
+ * destroy, including when the load is still in flight.
+ *
+ * Loading starts on mount, so server rendering never loads and reports
+ * `loading`.
+ *
+ * @throws {Error} When constructed outside component initialisation.
+ */
+export declare class RetainedEntry<E extends ManifestEntry> {
+    #private;
+    readonly entry: E;
+    constructor(entry: E);
+    /** The loaded source; `undefined` while loading, after an error, and after release. */
+    get source(): RetainedSourceOf<E> | undefined;
+    get status(): RetainedEntryStatus;
+    /** The rejection reason while `status` is `error`. */
+    get error(): unknown;
+    /** Drop the hold before destroy. Idempotent; safe to call unbound. */
+    readonly release: () => void;
+}

package/dist/runtime/retained-entry.svelte.js

@@ -0,0 +1,62 @@
+/**
+ * Component-scoped retention: an `EntryHandle` whose lifetime follows the
+ * component that creates it, with the source exposed as reactive state.
+ */
+import { onDestroy, onMount } from 'svelte';
+import { retainEntry } from './retained-entry.js';
+/**
+ * One hold on `entry`'s own source for the lifetime of the constructing
+ * component, shared with manifests and handles exactly like `retainEntry`.
+ * Construct it during component initialisation; the hold is dropped on
+ * destroy, including when the load is still in flight.
+ *
+ * Loading starts on mount, so server rendering never loads and reports
+ * `loading`.
+ *
+ * @throws {Error} When constructed outside component initialisation.
+ */
+export class RetainedEntry {
+    entry;
+    #handle = $state.raw();
+    #status = $state('loading');
+    #error = $state.raw();
+    constructor(entry) {
+        this.entry = entry;
+        onMount(() => {
+            if (this.#status === 'released')
+                return;
+            retainEntry(entry).then((handle) => {
+                if (this.#status === 'released') {
+                    handle.release();
+                    return;
+                }
+                this.#handle = handle;
+                this.#status = 'ready';
+            }, (error) => {
+                // A rejected retain leaves no hold behind.
+                if (this.#status === 'released')
+                    return;
+                this.#error = error;
+                this.#status = 'error';
+            });
+        });
+        onDestroy(this.release);
+    }
+    /** The loaded source; `undefined` while loading, after an error, and after release. */
+    get source() {
+        return this.#handle?.source;
+    }
+    get status() {
+        return this.#status;
+    }
+    /** The rejection reason while `status` is `error`. */
+    get error() {
+        return this.#error;
+    }
+    /** Drop the hold before destroy. Idempotent; safe to call unbound. */
+    release = () => {
+        this.#status = 'released';
+        this.#handle?.release();
+        this.#handle = undefined;
+    };
+}

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>;