fundus 0.16.0 → 0.17.0

package/dist/server/cli-commands.js

@@ -14,7 +14,7 @@ import { runBuild } from './build.js';
 import { formatCheckFinding, runCheck } from './check.js';
 import { loadConfig } from './config-loader.js';
 import { FundusOperations } from './operations.js';
-import { validateFigmaSourceParameters } from './importers/figma.js';
+import { parseFigmaFileKey, validateFigmaSourceParameters } from './importers/figma.js';
 import { pluginsByType, serverPluginForType } from './plugins.js';
 import { CliUsageError, formatBytes, parseArguments, parseJsonFlag, parseManifestList, printJsonDocument, requirePositionals } from './cli-io.js';
 const COMMON_FLAGS = {
@@ -114,7 +114,9 @@ function printHumanAssetDetail(asset) {
     console.log(`  rawHash:    ${asset.rawHash}`);
     if (asset.importSource?.importer === 'figma') {
         const source = validateFigmaSourceParameters(asset.importSource.parameters);
-        console.log(`  source:     Figma node ${source.nodeId} at ${source.scale}x`);
+        console.log(source.mode === 'tag'
+            ? `  source:     Figma tag "${source.fundusTag}" → node ${source.nodeId} at ${source.scale}x`
+            : `  source:     Figma node ${source.nodeId} at ${source.scale}x`);
     }
     console.log(`  manifests:  ${asset.manifests.length > 0 ? asset.manifests.join(', ') : '(none)'}`);
     for (const membership of asset.passiveManifests) {
@@ -374,19 +376,34 @@ Usage: fundus asset ingest <file> [--type <type>] [--id <id>] [--folder <path|ro
                            [--scale <1|2|3|4>] [--folder <path|root>]
                            [--manifests <a,b>] [--parameters <json>]
                            [--compression-x <0-100>] [--compression-y <0-100>] [--json]
+       fundus asset ingest --from figma --figma-tag <tag> --type <image|slice>
+                           [--figma-file <key|link>] [--scale <1|2|3|4>] [--folder <path|root>]
+                           [--manifests <a,b>] [--parameters <json>]
+                           [--compression-x <0-100>] [--compression-y <0-100>] [--json]
 
 File ingest remains the default and behaves like an editor upload. Figma
 ingest materializes one selection as PNG through the same importer-neutral
 operations pipeline. Both run the full autosave chain.
 
+Figma has two modes. Node mode takes the selection link as the positional and
+requires --id. Tag mode takes --figma-tag <tag> instead of a link: the tag IS
+the asset id, so a positional link and --id are both forbidden with --figma-tag.
+
 Flags:
   --from <file|figma> acquisition source; default: file. URLs are never
                        detected heuristically
   --type <type>        required for Figma (image or slice) and when a file
                        extension is ambiguous; known types:
                        ${Object.keys(pluginsByType).sort().join(', ')}
-  --id <id>            required for Figma; for files defaults to a proposal
-                       from the file name
+  --id <id>            required for Figma node mode; for files defaults to a
+                       proposal from the file name; forbidden with --figma-tag
+  --figma-tag <tag>    Figma tag mode: resolve the node tagged with this Fundus
+                       asset id; the tag becomes the asset id (mutually
+                       exclusive with a node selection link and --id)
+  --figma-file <key|link>
+                       fileKey for tag mode as a raw key or a Figma link;
+                       defaults to import.figma.defaultFileKey from
+                       fundus.config.ts
   --folder <path|root> destination folder; default: root
   --manifests <a,b>    explicit manifest membership (every name must exist)
   --parameters <json>  shallow parameter patch merged after ingest seeding
@@ -408,20 +425,37 @@ Example:
     --compression-x 75 --compression-y 25 --json
   fundus asset ingest 'https://www.figma.com/design/abc/UI?node-id=12-34' \\
     --from figma --type slice --id navigationPanel --scale 3 --json
+  fundus asset ingest --from figma --figma-tag navigationPanel --type slice \\
+    --figma-file abc --scale 3 --json
 `;
 export const ASSET_REIMPORT_HELP = `fundus asset reimport — refresh an asset from its saved source
 
 Usage: fundus asset reimport <id> [--json]
        fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]
+       fundus asset reimport <id> --figma-tag <newTag> [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]
+       fundus asset reimport <id> --figma-file <key|link> [--scale <1|2|3|4>] [--json]
        fundus asset reimport <id> --scale <1|2|3|4> [--json]
 
-Without overrides, re-materializes the persisted importer source. Figma
-overrides may update the link, scale, or both; omitted values are preserved.
-Asset type, parameters, folder, manifests, and id remain unchanged. Raw-file
-drift or concurrent changes abort without overwriting local edits.
+Without overrides, re-materializes the persisted importer source (a Figma tag
+asset re-scans its file for the tagged node, self-healing after node moves).
+A Figma override may update the source or scale; omitted values are preserved.
+Asset type, parameters, folder, and manifests remain unchanged. Raw-file drift
+or concurrent changes abort without overwriting local edits.
+
+Node vs tag assets accept different overrides. A node asset takes --figma-link
+(and --scale); --figma-tag and --figma-file are rejected. A tag asset takes
+--figma-tag to change its tag, --figma-file to re-point in place to another
+document, and --scale; --figma-link is rejected. Because the tag IS the asset
+id, changing it with --figma-tag renames the asset to the new tag (the new id
+must be valid and unused).
 
 Flags:
-  --figma-link <link>  replace the persisted Figma file/node selection
+  --figma-link <link>  node asset only: replace the persisted file/node selection
+  --figma-tag <newTag> tag asset only: change the tag, renaming the asset to the
+                       new tag (the tag is the asset id)
+  --figma-file <key|link>
+                       tag asset only: re-point in place to another file (raw
+                       key or a Figma link)
   --scale <1|2|3|4>    replace the persisted Figma export scale
   --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
   --help               this help
@@ -429,6 +463,8 @@ Flags:
 Example:
   fundus asset reimport navigationPanel
   fundus asset reimport navigationPanel --figma-link '<new-selection-link>'
+  fundus asset reimport navigationPanel --figma-tag mainNavigationPanel
+  fundus asset reimport navigationPanel --figma-file def456
   fundus asset reimport navigationPanel --scale 4
   fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json
 `;
@@ -436,16 +472,26 @@ export const ASSET_REPLACE_HELP = `fundus asset replace — replace an asset's r
 
 Usage: fundus asset replace <id> <file|figma-selection-link>
                             [--from <file|figma>] [--scale <1|2|3|4>] [--json]
+       fundus asset replace <id> --from figma --figma-tag <tag>
+                            [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]
 
 Replaces the stored raw file and content hash while preserving the asset's
 id, type, folder, parameters, references, and manifest memberships. The new
 source must be accepted by the existing asset type. File replacement remains
 the default and disconnects any saved source. Figma replacement stores the new
-selection as a repeatable source. Runs the full autosave chain, so delivered
-assets are reprocessed and manifests regenerated.
+selection (node mode) or tag (tag mode) as a repeatable source. A tag
+replacement must resolve to the asset's own id, so it can only re-point the
+same asset's own tag. Runs the full autosave chain, so delivered assets are
+reprocessed and manifests regenerated.
 
 Flags:
   --from <file|figma> replacement source; default: file
+  --figma-tag <tag>   Figma tag mode: replace from the node tagged with this
+                       Fundus asset id (takes no positional link)
+  --figma-file <key|link>
+                       fileKey for tag mode as a raw key or a Figma link;
+                       defaults to import.figma.defaultFileKey from
+                       fundus.config.ts
   --scale <1|2|3|4>   Figma export scale; default:
                       import.figma.defaults.scale from fundus.config.ts
   --json              print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
@@ -455,6 +501,8 @@ Example:
   fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json
   fundus asset replace navigationPanel \\
     'https://www.figma.com/design/abc/UI?node-id=12-34' --from figma --scale 3 --json
+  fundus asset replace navigationPanel --from figma \\
+    --figma-tag navigationPanel --figma-file abc --scale 3 --json
 `;
 export const ASSET_SET_HELP = `fundus asset set — update an asset's parameters and/or memberships
 
@@ -701,9 +749,10 @@ async function runAssetIngest(argumentList) {
         'compression-y': { takesValue: true },
         folder: { takesValue: true },
         from: { takesValue: true },
-        scale: { takesValue: true }
+        scale: { takesValue: true },
+        'figma-tag': { takesValue: true },
+        'figma-file': { takesValue: true }
     }, 'fundus asset ingest');
-    const [source] = requirePositionals(parsed, ['<file|figma-selection-link>'], 'fundus asset ingest');
     const from = parsed.flags.from === undefined ? 'file' : parsed.flags.from;
     if (from !== 'file' && from !== 'figma') {
         throw new CliUsageError('Flag "--from" must be "file" or "figma" — run `fundus asset ingest --help`.');
@@ -714,6 +763,11 @@ async function runAssetIngest(argumentList) {
     if (from === 'file' && scale !== undefined) {
         throw new CliUsageError('Flag "--scale" is only valid with `--from figma` — run `fundus asset ingest --help`.');
     }
+    const figmaTag = typeof parsed.flags['figma-tag'] === 'string' ? parsed.flags['figma-tag'] : undefined;
+    const figmaFile = typeof parsed.flags['figma-file'] === 'string' ? parsed.flags['figma-file'] : undefined;
+    if (from === 'file' && (figmaTag !== undefined || figmaFile !== undefined)) {
+        throw new CliUsageError('Flags "--figma-tag" and "--figma-file" are only valid with `--from figma` — run `fundus asset ingest --help`.');
+    }
     let parametersPatch = typeof parsed.flags.parameters === 'string'
         ? parseJsonFlag('parameters', parsed.flags.parameters)
         : undefined;
@@ -723,15 +777,56 @@ async function runAssetIngest(argumentList) {
         : undefined;
     const folder = typeof parsed.flags.folder === 'string' ? parseFolderToken(parsed.flags.folder) : '';
     if (from === 'figma') {
+        const type = parsed.flags.type;
+        if (typeof type !== 'string' || (type !== 'image' && type !== 'slice')) {
+            throw new CliUsageError('Figma ingest requires --type <image|slice> — run `fundus asset ingest --help`.');
+        }
+        if (figmaTag !== undefined) {
+            if (parsed.positionals.length > 0) {
+                throw new CliUsageError('Figma tag ingest takes no positional link — `--figma-tag` and a node selection link are mutually exclusive. Run `fundus asset ingest --help`.');
+            }
+            if (parsed.flags.id !== undefined) {
+                throw new CliUsageError('Figma tag ingest forbids --id: the tag is the asset id. Run `fundus asset ingest --help`.');
+            }
+            const fileKey = figmaFile === undefined ? undefined : resolveFigmaFileKeyFlag(figmaFile);
+            const parametersPatchForTag = applySliceCompressionFlags({
+                type,
+                flags: compressionFlags,
+                parametersPatch,
+                commandPath: 'fundus asset ingest'
+            });
+            const operations = await createOperations();
+            const state = await operations.importAsset({
+                importer: 'figma',
+                input: {
+                    mode: 'tag',
+                    tag: figmaTag,
+                    format: 'png',
+                    ...(fileKey !== undefined ? { fileKey } : {}),
+                    ...(scale !== undefined ? { scale } : {})
+                },
+                type,
+                id: figmaTag,
+                folder,
+                parametersPatch: parametersPatchForTag,
+                manifests
+            });
+            const asset = assetById(state, figmaTag);
+            if (parsed.flags.json) {
+                printJsonDocument({ ok: true, asset, issues: state.issues });
+                return;
+            }
+            printMutationResult(`Imported asset "${figmaTag}" from Figma tag as ${type}.`, asset, state);
+            return;
+        }
+        const [source] = requirePositionals(parsed, ['<figma-selection-link>'], 'fundus asset ingest');
         if (typeof parsed.flags.id !== 'string') {
             throw new CliUsageError('Figma ingest requires --id <id> — run `fundus asset ingest --help`.');
         }
-        if (typeof parsed.flags.type !== 'string' ||
-            (parsed.flags.type !== 'image' && parsed.flags.type !== 'slice')) {
-            throw new CliUsageError('Figma ingest requires --type <image|slice> — run `fundus asset ingest --help`.');
+        if (figmaFile !== undefined) {
+            throw new CliUsageError('Flag "--figma-file" is only valid in tag mode (with `--figma-tag`) — run `fundus asset ingest --help`.');
         }
         const id = parsed.flags.id;
-        const type = parsed.flags.type;
         parametersPatch = applySliceCompressionFlags({
             type,
             flags: compressionFlags,
@@ -756,6 +851,7 @@ async function runAssetIngest(argumentList) {
         printMutationResult(`Imported asset "${id}" from Figma as ${type}.`, asset, state);
         return;
     }
+    const [source] = requirePositionals(parsed, ['<file>'], 'fundus asset ingest');
     const filePath = source;
     const absolutePath = resolve(process.cwd(), filePath);
     let bytes;
@@ -797,6 +893,20 @@ function parseFigmaScale(value, commandPath) {
     }
     throw new CliUsageError(`Flag "--scale" must be 1, 2, 3, or 4 — run \`${commandPath} --help\`.`);
 }
+/**
+ * `--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.
+ */
+function resolveFigmaFileKeyFlag(value) {
+    try {
+        new URL(value);
+    }
+    catch {
+        return value;
+    }
+    return parseFigmaFileKey(value);
+}
 function canonicalFigmaSelectionLink(source) {
     const url = new URL(`https://www.figma.com/design/${encodeURIComponent(source.fileKey)}/fundus`);
     url.searchParams.set('node-id', source.nodeId.replace(':', '-'));
@@ -806,6 +916,8 @@ async function runAssetReimport(argumentList) {
     const parsed = parseArguments(argumentList, {
         ...COMMON_FLAGS,
         'figma-link': { takesValue: true },
+        'figma-tag': { takesValue: true },
+        'figma-file': { takesValue: true },
         scale: { takesValue: true }
     }, 'fundus asset reimport');
     const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset reimport');
@@ -813,9 +925,20 @@ async function runAssetReimport(argumentList) {
         ? parseFigmaScale(parsed.flags.scale, 'fundus asset reimport')
         : undefined;
     const figmaLink = typeof parsed.flags['figma-link'] === 'string' ? parsed.flags['figma-link'] : undefined;
+    const figmaTag = typeof parsed.flags['figma-tag'] === 'string' ? parsed.flags['figma-tag'] : undefined;
+    const figmaFile = typeof parsed.flags['figma-file'] === 'string' ? parsed.flags['figma-file'] : undefined;
+    if (figmaTag !== undefined && figmaTag === '') {
+        throw new CliUsageError('Flag "--figma-tag" needs a non-empty tag — run `fundus asset reimport --help`.');
+    }
+    const hasOverride = figmaLink !== undefined ||
+        figmaTag !== undefined ||
+        figmaFile !== undefined ||
+        scale !== undefined;
     const operations = await createOperations();
     let state;
-    if (figmaLink === undefined && scale === undefined) {
+    // A tag rename changes the id; look the asset up under its effective new id.
+    let effectiveId = id;
+    if (!hasOverride) {
         state = await operations.reimportAsset(id);
     }
     else {
@@ -825,28 +948,58 @@ async function runAssetReimport(argumentList) {
             throw new Error(`Asset "${id}" does not have a Figma source.`);
         }
         const source = validateFigmaSourceParameters(currentAsset.importSource.parameters);
-        state = await operations.reimportAsset(id, {
-            url: figmaLink ?? canonicalFigmaSelectionLink(source),
-            format: 'png',
-            scale: scale ?? source.scale
-        });
+        if (source.mode === 'tag') {
+            if (figmaLink !== undefined) {
+                throw new CliUsageError('Flag "--figma-link" is invalid for a Figma tag asset — change the tag with --figma-tag or re-point with --figma-file and/or --scale. Run `fundus asset reimport --help`.');
+            }
+            const fileKey = figmaFile === undefined ? undefined : resolveFigmaFileKeyFlag(figmaFile);
+            state = await operations.retagFigmaAsset(id, {
+                ...(figmaTag !== undefined ? { tag: figmaTag } : {}),
+                ...(fileKey !== undefined ? { fileKey } : {}),
+                ...(scale !== undefined ? { scale } : {})
+            });
+            // A different tag renames the asset (the tag is the id); else the id is unchanged.
+            effectiveId = figmaTag ?? id;
+        }
+        else {
+            if (figmaFile !== undefined) {
+                throw new CliUsageError('Flag "--figma-file" is invalid for a Figma node asset — it applies only to tag assets. Run `fundus asset reimport --help`.');
+            }
+            if (figmaTag !== undefined) {
+                throw new CliUsageError('Flag "--figma-tag" is invalid for a Figma node asset — it applies only to tag assets. Run `fundus asset reimport --help`.');
+            }
+            state = await operations.reimportAsset(id, {
+                url: figmaLink ?? canonicalFigmaSelectionLink(source),
+                format: 'png',
+                scale: scale ?? source.scale
+            });
+        }
     }
-    const asset = assetById(state, id);
+    const asset = assetById(state, effectiveId);
     if (parsed.flags.json) {
         printJsonDocument({ ok: true, asset, issues: state.issues });
         return;
     }
-    printMutationResult(figmaLink === undefined && scale === undefined
-        ? `Refreshed asset "${id}" from its saved source.`
-        : `Reimported asset "${id}" with updated Figma source.`, asset, state);
+    let headline;
+    if (!hasOverride) {
+        headline = `Refreshed asset "${id}" from its saved source.`;
+    }
+    else if (effectiveId !== id) {
+        headline = `Reimported asset "${id}" as "${effectiveId}" with updated Figma tag.`;
+    }
+    else {
+        headline = `Reimported asset "${effectiveId}" with updated Figma source.`;
+    }
+    printMutationResult(headline, asset, state);
 }
 async function runAssetReplace(argumentList) {
     const parsed = parseArguments(argumentList, {
         ...COMMON_FLAGS,
         from: { takesValue: true },
-        scale: { takesValue: true }
+        scale: { takesValue: true },
+        'figma-tag': { takesValue: true },
+        'figma-file': { takesValue: true }
     }, 'fundus asset replace');
-    const [id, source] = requirePositionals(parsed, ['<id>', '<file|figma-selection-link>'], 'fundus asset replace');
     const from = parsed.flags.from === undefined ? 'file' : parsed.flags.from;
     if (from !== 'file' && from !== 'figma') {
         throw new CliUsageError('Flag "--from" must be "file" or "figma" — run `fundus asset replace --help`.');
@@ -857,8 +1010,39 @@ async function runAssetReplace(argumentList) {
     if (from === 'file' && scale !== undefined) {
         throw new CliUsageError('Flag "--scale" is only valid with `--from figma` — run `fundus asset replace --help`.');
     }
+    const figmaTag = typeof parsed.flags['figma-tag'] === 'string' ? parsed.flags['figma-tag'] : undefined;
+    const figmaFile = typeof parsed.flags['figma-file'] === 'string' ? parsed.flags['figma-file'] : undefined;
+    if (from === 'file' && (figmaTag !== undefined || figmaFile !== undefined)) {
+        throw new CliUsageError('Flags "--figma-tag" and "--figma-file" are only valid with `--from figma` — run `fundus asset replace --help`.');
+    }
+    if (from === 'figma' && figmaTag !== undefined) {
+        const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset replace');
+        const fileKey = figmaFile === undefined ? undefined : resolveFigmaFileKeyFlag(figmaFile);
+        const operations = await createOperations();
+        const state = await operations.replaceRawFromSource(id, {
+            importer: 'figma',
+            input: {
+                mode: 'tag',
+                tag: figmaTag,
+                format: 'png',
+                ...(fileKey !== undefined ? { fileKey } : {}),
+                ...(scale !== undefined ? { scale } : {})
+            }
+        });
+        const asset = assetById(state, id);
+        if (parsed.flags.json) {
+            printJsonDocument({ ok: true, asset, issues: state.issues });
+            return;
+        }
+        printMutationResult(`Replaced raw file for asset "${id}" from Figma tag.`, asset, state);
+        return;
+    }
+    const [id, source] = requirePositionals(parsed, ['<id>', from === 'figma' ? '<figma-selection-link>' : '<file>'], 'fundus asset replace');
     const operations = await createOperations();
     if (from === 'figma') {
+        if (figmaFile !== undefined) {
+            throw new CliUsageError('Flag "--figma-file" is only valid in tag mode (with `--figma-tag`) — run `fundus asset replace --help`.');
+        }
         const state = await operations.replaceRawFromSource(id, {
             importer: 'figma',
             input: { url: source, format: 'png', ...(scale !== undefined ? { scale } : {}) }

package/dist/server/config-loader.d.ts

@@ -54,6 +54,7 @@ export interface ResolvedFundusConfig {
     import: {
         figma: {
             token?: string;
+            defaultFileKey?: string;
             defaults: {
                 scale: FigmaImportScale;
             };

package/dist/server/config-loader.js

@@ -149,6 +149,10 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
     if (figma.token !== undefined && (typeof figma.token !== 'string' || figma.token.length === 0)) {
         throw new Error('fundus.config: "import.figma.token" must be a non-empty string.');
     }
+    if (figma.defaultFileKey !== undefined &&
+        (typeof figma.defaultFileKey !== 'string' || figma.defaultFileKey.length === 0)) {
+        throw new Error('fundus.config: "import.figma.defaultFileKey" must be a non-empty string.');
+    }
     const defaults = figma.defaults === undefined ? {} : figma.defaults;
     if (!isRecord(defaults)) {
         throw new Error('fundus.config: "import.figma.defaults" must be an object.');
@@ -178,6 +182,7 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
         import: {
             figma: {
                 ...(figma.token !== undefined ? { token: figma.token } : {}),
+                ...(figma.defaultFileKey !== undefined ? { defaultFileKey: figma.defaultFileKey } : {}),
                 defaults: { scale }
             }
         },

package/dist/server/http.js

@@ -44,6 +44,7 @@ const SOURCE_ERROR_STATUS = {
     unauthorized: 401,
     forbidden: 403,
     'not-found': 404,
+    'ambiguous-tag': 409,
     'rate-limited': 429,
     'upstream-failed': 502,
     'invalid-response': 502,

package/dist/server/importers/figma.d.ts

@@ -1,21 +1,44 @@
-import { type ServerSourceImporter } from './contract.js';
+import { type ImporterContext, type ServerSourceImporter } from './contract.js';
 import { type PinnedHttpsTarget } from './pinned-https.js';
-export interface FigmaSourceParameters {
+export interface FigmaNodeSourceParameters {
+    mode?: 'node';
     fileKey: string;
     nodeId: string;
     format: 'png';
     scale: 1 | 2 | 3 | 4;
 }
-export interface FigmaImportInput {
+export interface FigmaTagSourceParameters {
+    mode: 'tag';
+    fileKey: string;
+    /** The Fundus asset id carried in Figma as `sharedPluginData.fundus.assetId`. */
+    fundusTag: string;
+    /** Resolved node id (colon-form), cached from the last tag resolution. */
+    nodeId: string;
+    format: 'png';
+    scale: 1 | 2 | 3 | 4;
+}
+export type FigmaSourceParameters = FigmaNodeSourceParameters | FigmaTagSourceParameters;
+export interface FigmaNodeImportInput {
+    mode?: 'node';
     url: string;
     format?: 'png';
     scale?: 1 | 2 | 3 | 4;
 }
+export interface FigmaTagImportInput {
+    mode: 'tag';
+    tag: string;
+    fileKey?: string;
+    format?: 'png';
+    scale?: 1 | 2 | 3 | 4;
+}
+export type FigmaImportInput = FigmaNodeImportInput | FigmaTagImportInput;
 export declare function parseFigmaSelectionUrl(value: string): {
     fileKey: string;
     nodeId: string;
 };
+export declare function parseFigmaFileKey(value: string): string;
 export declare function validateFigmaSourceParameters(value: unknown): FigmaSourceParameters;
 export declare function resolveSafeDownloadTarget(value: string | URL): Promise<PinnedHttpsTarget>;
 export declare function assertSafeDownloadUrl(value: string | URL): Promise<URL>;
+export declare function resolveTagToNode(fileKey: string, tag: string, context: ImporterContext): Promise<string>;
 export declare const figmaSourceImporter: ServerSourceImporter<FigmaImportInput, FigmaSourceParameters>;

package/dist/server/importers/figma.js

@@ -1,6 +1,7 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import sharp from 'sharp';
+import { isValidAssetId } from '../../core/index.js';
 import { SourceImportError, invalidInput } from './contract.js';
 import { requestPinnedHttps } from './pinned-https.js';
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
@@ -36,6 +37,24 @@ export function parseFigmaSelectionUrl(value) {
     const [left, right] = nodeIds[0].split(/[-:]/);
     return { fileKey: segments[1], nodeId: `${left}:${right}` };
 }
+export function parseFigmaFileKey(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return invalidInput('Enter a valid Figma file link.');
+    }
+    if (url.protocol !== 'https:' ||
+        (url.hostname !== 'figma.com' && url.hostname !== 'www.figma.com')) {
+        return invalidInput('Figma links must use HTTPS on figma.com.');
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (!['design', 'file', 'proto'].includes(segments[0] ?? '') || !segments[1]) {
+        return invalidInput('The Figma link must point to a design, file, or prototype.');
+    }
+    return segments[1];
+}
 function validateScale(value) {
     if (value !== 1 && value !== 2 && value !== 3 && value !== 4) {
         return invalidInput('Figma export scale must be 1, 2, 3, or 4.');
@@ -44,12 +63,31 @@ function validateScale(value) {
 }
 function validateInput(value) {
     const input = record(value);
-    if (!input || typeof input.url !== 'string')
+    if (!input)
         return invalidInput('Figma import requires a URL.');
     if (input.format !== undefined && input.format !== 'png') {
         return invalidInput('Figma import currently supports PNG only.');
     }
+    if (input.mode === 'tag') {
+        if (typeof input.tag !== 'string' || !isValidAssetId(input.tag)) {
+            return invalidInput('Figma tag import requires a valid Fundus asset id as the tag.');
+        }
+        if (input.fileKey !== undefined &&
+            (typeof input.fileKey !== 'string' || input.fileKey.length === 0)) {
+            return invalidInput('Figma tag import fileKey must be a non-empty string.');
+        }
+        return {
+            mode: 'tag',
+            tag: input.tag,
+            format: 'png',
+            ...(input.fileKey !== undefined ? { fileKey: input.fileKey } : {}),
+            ...(input.scale !== undefined ? { scale: validateScale(input.scale) } : {})
+        };
+    }
+    if (typeof input.url !== 'string')
+        return invalidInput('Figma import requires a URL.');
     return {
+        mode: 'node',
         url: input.url,
         format: 'png',
         ...(input.scale !== undefined ? { scale: validateScale(input.scale) } : {})
@@ -65,6 +103,19 @@ export function validateFigmaSourceParameters(value) {
         source.format !== 'png') {
         return invalidInput('Stored Figma source parameters are invalid.');
     }
+    if (source.mode === 'tag') {
+        if (typeof source.fundusTag !== 'string' || !isValidAssetId(source.fundusTag)) {
+            return invalidInput('Stored Figma source parameters are invalid.');
+        }
+        return {
+            mode: 'tag',
+            fileKey: source.fileKey,
+            fundusTag: source.fundusTag,
+            nodeId: source.nodeId,
+            format: 'png',
+            scale: validateScale(source.scale)
+        };
+    }
     return {
         fileKey: source.fileKey,
         nodeId: source.nodeId,
@@ -332,6 +383,49 @@ async function validatePng(bytes) {
         throw new SourceImportError('image-too-large', 'Figma export exceeds the 32 megapixel limit.');
     }
 }
+function collectTaggedNodeIds(node, tag, matches) {
+    const current = record(node);
+    if (!current)
+        return;
+    const shared = record(current.sharedPluginData);
+    const fundus = shared ? record(shared.fundus) : null;
+    if (fundus && fundus.assetId === tag && typeof current.id === 'string') {
+        matches.push(current.id);
+    }
+    if (Array.isArray(current.children)) {
+        for (const child of current.children)
+            collectTaggedNodeIds(child, tag, matches);
+    }
+}
+export async function resolveTagToNode(fileKey, tag, context) {
+    const token = context.config.import.figma.token;
+    if (!token) {
+        throw new SourceImportError('not-configured', 'Figma access is not configured.');
+    }
+    const endpoint = new URL(`https://api.figma.com/v1/files/${encodeURIComponent(fileKey)}`);
+    endpoint.searchParams.set('plugin_data', 'shared');
+    const jsonBytes = await fetchWithDeadline(context.fetch, endpoint, { redirect: 'error', headers: { 'X-Figma-Token': token } }, async (response) => new Uint8Array(await response.arrayBuffer()));
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(jsonBytes));
+    }
+    catch {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    }
+    const body = record(payload);
+    if (!body || body.err || (typeof body.status === 'number' && body.status >= 400)) {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    }
+    const matches = [];
+    collectTaggedNodeIds(body.document, tag, matches);
+    if (matches.length === 0) {
+        throw new SourceImportError('not-found', `No Figma node is tagged "${tag}" in this file.`);
+    }
+    if (matches.length > 1) {
+        throw new SourceImportError('ambiguous-tag', `More than one Figma node is tagged "${tag}" in this file.`);
+    }
+    return matches[0];
+}
 async function materialize(source, context) {
     const token = context.config.import.figma.token;
     if (!token) {
@@ -371,6 +465,21 @@ export const figmaSourceImporter = {
     label: 'Figma',
     validateInput,
     async importRaw(input, context) {
+        if (input.mode === 'tag') {
+            const fileKey = input.fileKey ?? context.config.import.figma.defaultFileKey;
+            if (!fileKey) {
+                throw new SourceImportError('not-configured', 'Figma tag import needs a fileKey or import.figma.defaultFileKey in fundus.config.');
+            }
+            const nodeId = await resolveTagToNode(fileKey, input.tag, context);
+            return materialize({
+                mode: 'tag',
+                fileKey,
+                fundusTag: input.tag,
+                nodeId,
+                format: 'png',
+                scale: input.scale ?? context.config.import.figma.defaults.scale
+            }, context);
+        }
         const parsed = parseFigmaSelectionUrl(input.url);
         return materialize({
             fileKey: parsed.fileKey,
@@ -381,6 +490,10 @@ export const figmaSourceImporter = {
     },
     validateSourceParameters: validateFigmaSourceParameters,
     async reimportRaw(source, context) {
+        if (source.mode === 'tag') {
+            const nodeId = await resolveTagToNode(source.fileKey, source.fundusTag, context);
+            return materialize({ ...source, nodeId }, context);
+        }
         return materialize(source, context);
     }
 };