fundus 0.15.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/codegen.d.ts

@@ -1,4 +1,4 @@
-import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ReferencesByAsset } from '../core/index.js';
+import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ManifestName, type ManifestRecord, type ReferencesByAsset, type ValidationIssueDto } from '../core/index.js';
 import type { SourceLocation } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
@@ -10,6 +10,8 @@ export declare function locateGeneratedAssetDeclaration(file: string, source: st
 export declare function kebabCaseFromCamel(name: string): string;
 /** Generated module file name for a manifest. */
 export declare function manifestModuleFileName(manifestName: string): string;
+/** Two manifest names that would generate the same kebab-case module file. */
+export declare function manifestModuleCollisionIssues(manifests: Record<ManifestName, ManifestRecord>): ValidationIssueDto[];
 /**
  * Build the entry data codegen emits for one asset — delegated to
  * the owning server plugin's `buildManifestEntry`. Reference fields

package/dist/server/codegen.js

@@ -35,6 +35,24 @@ export function kebabCaseFromCamel(name) {
 export function manifestModuleFileName(manifestName) {
     return `${kebabCaseFromCamel(manifestName)}.generated.ts`;
 }
+/** Two manifest names that would generate the same kebab-case module file. */
+export function manifestModuleCollisionIssues(manifests) {
+    const issues = [];
+    const namesByModuleFile = new Map();
+    for (const name of Object.keys(manifests)) {
+        const fileName = manifestModuleFileName(name);
+        const existingName = namesByModuleFile.get(fileName);
+        if (existingName !== undefined) {
+            issues.push({
+                message: `Manifests "${existingName}" and "${name}" would both generate "${fileName}".`
+            });
+        }
+        else {
+            namesByModuleFile.set(fileName, name);
+        }
+    }
+    return issues;
+}
 /**
  * Build the entry data codegen emits for one asset — delegated to
  * the owning server plugin's `buildManifestEntry`. Reference fields

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

@@ -1,4 +1,4 @@
-import type { AudioPreset, FigmaImportScale, ImagePreset, ResolvedVideoPreset, UsageConfig } from '../core/index.js';
+import { type AudioPreset, type FigmaImportScale, type ImagePreset, type PackageDeclaration, type ResolvedVideoPreset, type UsageConfig } from '../core/index.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 export interface ResolvedPresetPluginConfig {
     presets: Record<string, ImagePreset>;
@@ -13,6 +13,27 @@ export interface ResolvedVideoPluginConfig {
 export interface ResolvedAudioPluginConfig {
     presets: Record<string, AudioPreset>;
 }
+/**
+ * A `packages` entry after pure normalization (no disk): its declared origin,
+ * whether it is a package name or a path, the resolved reference (absolute path
+ * for the path form; the bare name for the name form), and an optional raw-root
+ * override. Package files are read later, in `loadConfig`.
+ */
+export interface NormalizedPackageSource {
+    origin: string;
+    kind: 'name' | 'path';
+    reference: string;
+    rawDirOverride?: string;
+}
+/** A fully resolved Package: its parsed declaration plus provenance. */
+export interface ResolvedPackage {
+    origin: string;
+    /** Absolute path of the resolved fundus.package.json. */
+    file: string;
+    /** Absolute raw root (recorded for provenance; unused in v1 slots-only). */
+    rawDir: string;
+    declaration: PackageDeclaration;
+}
 export interface ResolvedFundusConfig {
     /** Absolute host project directory containing fundus.config.ts. */
     projectRoot: string;
@@ -33,15 +54,29 @@ export interface ResolvedFundusConfig {
     import: {
         figma: {
             token?: string;
+            defaultFileKey?: string;
             defaults: {
                 scale: FigmaImportScale;
             };
         };
     };
     usage: UsageConfig | null;
+    /** Normalized `packages` entries (from the pure `resolveConfig`, no disk). */
+    packageSources: NormalizedPackageSource[];
+    /** Parsed Packages (filled by `loadConfig`; always [] from `resolveConfig`). */
+    packages: ResolvedPackage[];
 }
 export declare const USAGE_NOT_CONFIGURED_MESSAGE = "Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.";
 /** Pure resolution step (testable without a config file on disk). */
 export declare function resolveConfig(projectRoot: string, value: unknown, registry?: ServerPluginRegistry): ResolvedFundusConfig;
+/**
+ * Read and parse every declared Package from disk. Name entries resolve through
+ * the host's module resolver (respecting `exports`), then walk up to the nearest
+ * `package.json` that declares the name and read its `"fundus"` field. Path
+ * entries point directly at a `fundus.package.json`. Throws a clear,
+ * origin-tagged error on any resolution/read/parse failure — Package assembly
+ * failures are symmetric with a missing `fundus.config.ts`.
+ */
+export declare function loadPackages(projectRoot: string, sources: NormalizedPackageSource[]): Promise<ResolvedPackage[]>;
 /** Load `fundus.config.ts` from the host project root. */
 export declare function loadConfig(projectRoot: string): Promise<ResolvedFundusConfig>;