fundus 0.15.0 → 0.17.0

package/build/server/chunks/chunks/{context.js-CVuTSPjH.js → context.js-Dh0ibRIF.js}

@@ -1,11 +1,13 @@
-import { c as compareCodeUnits, h as folderOfRawPath, j as rawFileNameOfPath, g as canonicalizeParameters, n as normalizeFolderPath, H as typesForFileName, J as proposeAssetId, k as parentFolderPath, u as portableFolderPathKey } from './core.js-CABVXpby.js';
-import { s as serverPluginsByType, i as isRecord, L as LibraryStore, d as descriptorsByType, m as manifestModuleFileName, l as locateGeneratedAssetDeclaration, a as serializeLibrary, b as serverPluginForType, S as SourceImportError, p as processAssets, g as generateManifestModules, r as readCurrentProxy, e as encodeRelativePathForUrl, c as invalidInput, f as parseLibrary } from './contract.js-itFN0Gon.js';
-import { c as collectAllReferences, a as assetIdError, b as computeLibraryMembership, d as allDeliveredAssetIds } from './manifest-membership.js-BnSECWpJ.js';
-import { v as verifyStableRawFile, c as classifyRawDirectory } from './raw-reconciliation2.js-CscuoBC2.js';
-import { isAbsolute, resolve, join, extname, relative, sep } from 'node:path';
-import { existsSync } from 'node:fs';
-import { createJiti } from 'jiti';
+import { c as compareCodeUnits, h as folderOfRawPath, j as rawFileNameOfPath, g as canonicalizeParameters, n as normalizeFolderPath, H as typesForFileName, k as parentFolderPath, u as portableFolderPathKey, B as isAssetReference } from './core.js-CTyKR4bu.js';
+import { s as serverPluginsByType, i as isRecord, L as LibraryStore, d as descriptorsByType, m as manifestModuleFileName, l as locateGeneratedAssetDeclaration, a as serializeLibrary, b as serverPluginForType, S as SourceImportError, p as processAssets, g as generateManifestModules, r as readCurrentProxy, e as encodeRelativePathForUrl, f as flatLibraryIssues, c as manifestModuleCollisionIssues, h as invalidInput, j as parseLibrary, k as isRecord$1, n as assertSafeKey, o as parseManifestRecord, q as parseImportSource } from './contract.js-_LTMZBo2.js';
+import { c as collectAllReferences, a as assetIdError, b as computeLibraryMembership, d as allDeliveredAssetIds, i as isValidAssetId } from './manifest-membership.js-at1ixQdW.js';
+import { v as verifyStableRawFile, c as classifyRawDirectory } from './raw-reconciliation2.js-z4xl5zw2.js';
+import { createRequire } from 'node:module';
+import { isAbsolute, resolve, join, dirname, extname, relative, sep } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile, realpath } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
 import { execFile } from 'node:child_process';
 import { isDeepStrictEqual, promisify } from 'node:util';
 import sharp from 'sharp';
@@ -14,6 +16,242 @@ import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import { request } from 'node:https';
 
+//#region src/lib/core/package-declaration.ts
+function parsePackageAsset(origin, id, value) {
+	if (!isRecord$1(value)) throw new Error(`Package "${origin}" asset "${id}" must be an object.`);
+	if (typeof value.type !== "string" || value.type.length === 0) throw new Error(`Package "${origin}" asset "${id}" is missing a string "type".`);
+	if ("raw" in value || "rawHash" in value) throw new Error(`Package "${origin}" asset "${id}" declares "raw"/"rawHash"; Packages ship byte-less slots only.`);
+	if (!Array.isArray(value.manifests) || value.manifests.some((entry) => typeof entry !== "string")) throw new Error(`Package "${origin}" asset "${id}" must have a "manifests" array of strings.`);
+	const record = {
+		type: value.type,
+		parameters: "parameters" in value ? value.parameters : {},
+		manifests: value.manifests
+	};
+	if (value.importSource !== void 0) record.importSource = parseImportSource(id, value.importSource);
+	return record;
+}
+/**
+* Parse and structurally validate a `fundus.package.json` (JSON text). Delegates
+* to {@link validatePackageDeclaration} after `JSON.parse`.
+*/
+function parsePackageDeclaration(json, origin) {
+	let value;
+	try {
+		value = JSON.parse(json);
+	} catch (cause) {
+		throw new Error(`Package "${origin}" declaration is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	return validatePackageDeclaration(value, origin);
+}
+/**
+* Structurally validate an already-parsed package declaration — the shared core of
+* both the JSON path ({@link parsePackageDeclaration}) and the TypeScript-module path
+* (a `fundus.package.ts` default export loaded via jiti). Throws with a clear,
+* origin-tagged message on any malformed part. Plugin parameter validation and
+* id/manifest-name validity are separate steps that run over the merged
+* (effective) library, not here — mirroring `parseLibrary`. `version` defaults to 1.
+*/
+function validatePackageDeclaration(value, origin) {
+	if (!isRecord$1(value)) throw new Error(`Package "${origin}" declaration must be an object.`);
+	if (value.version !== void 0 && value.version !== 1) throw new Error(`Package "${origin}" declaration has unsupported version ${JSON.stringify(value.version)} (expected 1).`);
+	if (!isRecord$1(value.assets)) throw new Error(`Package "${origin}" declaration "assets" must be an object.`);
+	if (value.manifests !== void 0 && !isRecord$1(value.manifests)) throw new Error(`Package "${origin}" declaration "manifests" must be an object.`);
+	const assets = {};
+	for (const [id, record] of Object.entries(value.assets)) {
+		assertSafeKey("asset", id);
+		assets[id] = parsePackageAsset(origin, id, record);
+	}
+	const manifests = {};
+	if (isRecord$1(value.manifests)) for (const [name, record] of Object.entries(value.manifests)) {
+		assertSafeKey("manifest", name);
+		if (!isRecord$1(record)) throw new Error(`Package "${origin}" manifest "${name}" must be an object.`);
+		manifests[name] = parseManifestRecord(name, record);
+	}
+	return {
+		version: 1,
+		assets,
+		manifests
+	};
+}
+//#endregion
+//#region src/lib/core/package-merge.ts
+/**
+* The pure Package merge: fold package-shipped partial libraries **under** the
+* host library into one in-memory *effective* library. Host wins per-field
+* (deep). No disk, no config — testable like `resolveConfig`. The effective
+* library is never serialized (a host `Library` always carries `raw`/`rawHash`);
+* `materializeLibrary` drops raw-less inert slots to hand a plain `Library` to
+* processing/codegen once the slot/validation gates have passed.
+*/
+function sortDedupManifests(names) {
+	return [...new Set(names)].sort(compareCodeUnits);
+}
+/**
+* Deep-merge plugin `parameters` — overlay (host) wins. Recurses into plain
+* objects only; arrays are replaced wholesale (host-replace) and `{ $asset }`
+* reference markers are treated as atomic (never merged field-by-field). Applied
+* to `parameters` only — the record-level `manifests` array is unioned by the
+* caller, never routed through here.
+*/
+function deepMergeParameters(base, overlay) {
+	if (isRecord$1(base) && isRecord$1(overlay) && !isAssetReference(base) && !isAssetReference(overlay)) {
+		const result = { ...base };
+		for (const [key, value] of Object.entries(overlay)) result[key] = key in base ? deepMergeParameters(base[key], value) : value;
+		return result;
+	}
+	return overlay;
+}
+/**
+* Merge `packages` under `host` (host wins, per-field deep). Returns the merged
+* effective library, per-asset provenance, and merge findings. `host` is an
+* `EffectiveLibrary` so a raw-less host override branch stays reachable/testable
+* and v2-ready; a plain `Library` is assignable.
+*/
+function mergePackages(host, packages) {
+	const findings = [];
+	const pkgAssets = /* @__PURE__ */ new Map();
+	const pkgManifests = /* @__PURE__ */ new Map();
+	for (const { origin, declaration } of packages) {
+		for (const [id, decl] of Object.entries(declaration.assets)) {
+			const existing = pkgAssets.get(id);
+			if (existing) {
+				findings.push({
+					kind: "package-conflict",
+					assetId: id,
+					origins: [existing.origin, origin],
+					message: `Asset "${id}" is declared by two Packages ("${existing.origin}" and "${origin}"); Package ids must be unique.`
+				});
+				continue;
+			}
+			pkgAssets.set(id, {
+				origin,
+				decl
+			});
+		}
+		for (const [name, record] of Object.entries(declaration.manifests)) if (!pkgManifests.has(name)) pkgManifests.set(name, record);
+	}
+	const assets = {};
+	const provenance = {};
+	for (const [id, hostRecord] of Object.entries(host.assets)) {
+		const pkg = pkgAssets.get(id);
+		if (!pkg) {
+			assets[id] = { ...hostRecord };
+			provenance[id] = { source: "host" };
+			continue;
+		}
+		if (pkg.decl.type !== hostRecord.type) {
+			findings.push({
+				kind: "package-type-mismatch",
+				assetId: id,
+				origin: pkg.origin,
+				message: `Asset "${id}" overrides Package "${pkg.origin}" but changes its type from "${pkg.decl.type}" to "${hostRecord.type}"; changing the type is a different asset, not an override.`
+			});
+			assets[id] = { ...hostRecord };
+			provenance[id] = {
+				source: "override",
+				origin: pkg.origin
+			};
+			continue;
+		}
+		const merged = {
+			type: hostRecord.type,
+			parameters: deepMergeParameters(pkg.decl.parameters, hostRecord.parameters),
+			manifests: sortDedupManifests([...pkg.decl.manifests, ...hostRecord.manifests])
+		};
+		if (hostRecord.raw !== void 0 || hostRecord.importSource !== void 0) {
+			if (hostRecord.raw !== void 0) merged.raw = hostRecord.raw;
+			if (hostRecord.rawHash !== void 0) merged.rawHash = hostRecord.rawHash;
+			if (hostRecord.importSource !== void 0) merged.importSource = hostRecord.importSource;
+		} else if (pkg.decl.importSource !== void 0) merged.importSource = pkg.decl.importSource;
+		assets[id] = merged;
+		provenance[id] = {
+			source: "override",
+			origin: pkg.origin
+		};
+		findings.push({
+			kind: "package-overridden",
+			assetId: id,
+			origin: pkg.origin,
+			message: `Asset "${id}" from Package "${pkg.origin}" is overridden by the host library.`
+		});
+	}
+	for (const [id, { origin, decl }] of pkgAssets) {
+		if (Object.hasOwn(host.assets, id)) continue;
+		const record = {
+			type: decl.type,
+			parameters: decl.parameters,
+			manifests: sortDedupManifests(decl.manifests)
+		};
+		if (decl.importSource !== void 0) record.importSource = decl.importSource;
+		assets[id] = record;
+		provenance[id] = {
+			source: "package",
+			origin
+		};
+	}
+	const manifests = {};
+	for (const [name, record] of pkgManifests) manifests[name] = { ...record };
+	for (const [name, record] of Object.entries(host.manifests)) manifests[name] = {
+		...manifests[name],
+		...record
+	};
+	return {
+		library: {
+			version: Object.values(assets).some((record) => record.importSource !== void 0) ? 2 : host.version,
+			folders: host.folders,
+			assets,
+			manifests
+		},
+		provenance,
+		findings
+	};
+}
+/**
+* Drop raw-less (unfilled) slots from an effective library, yielding a plain
+* `Library` for processing/codegen. Safe only after the slot/validation gates
+* pass — every remaining delivered asset then has `raw`; dropped slots are
+* provably inert (not delivered).
+*/
+function materializeLibrary(effective) {
+	const assets = {};
+	for (const [id, record] of Object.entries(effective.assets)) {
+		if (record.raw === void 0 || record.rawHash === void 0) continue;
+		const materialized = {
+			type: record.type,
+			raw: record.raw,
+			rawHash: record.rawHash,
+			parameters: record.parameters,
+			manifests: record.manifests
+		};
+		if (record.importSource !== void 0) materialized.importSource = record.importSource;
+		assets[id] = materialized;
+	}
+	return {
+		version: effective.version,
+		folders: effective.folders,
+		assets,
+		manifests: effective.manifests
+	};
+}
+//#endregion
+//#region src/lib/core/propose-asset-id.ts
+/**
+* Propose a camelCase asset id from a file (or node) name: split on
+* non-alphanumeric runs and case boundaries, drop a `@2x`-style scale suffix,
+* lowercase the first word, capitalize the rest, strip leading digits.
+*
+* Pure and dependency-free so it can be shared everywhere — including the Figma
+* plugin bundle, which must not pull in the plugin registry that `ingest.ts`
+* imports.
+*/
+function proposeAssetId(fileName) {
+	const words = fileName.replace(/\.[^.]+$/, "").replace(/(?:@|[-_])\dx$/i, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/).filter(Boolean);
+	if (words.length === 0) return "asset";
+	const withoutLeadingDigits = words.map((word, index) => index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("").replace(/^[0-9]+/, "");
+	if (!withoutLeadingDigits) return "asset";
+	return withoutLeadingDigits.charAt(0).toLowerCase() + withoutLeadingDigits.slice(1);
+}
+//#endregion
 //#region src/lib/server/config-loader.ts
 /**
 * Loads and resolves the host's `fundus.config.ts` through jiti, validates
@@ -37,6 +275,70 @@ function configDefinitionsFor(registry) {
 	}
 	return [...byNamespace.values()];
 }
+/**
+* A string `packages` entry is a *path* when it looks like one (starts with
+* `.`/`/`, is absolute, or ends `.json`), or a bare relative path with a
+* separator; otherwise it is a package *name*. A scoped name (`@scope/pkg`)
+* contains a `/` but is a name.
+*/
+function classifyPackageSpec(spec) {
+	if (spec.startsWith(".") || spec.startsWith("/") || isAbsolute(spec)) return "path";
+	if (DECLARATION_FILE_RE.test(spec)) return "path";
+	if (spec.startsWith("@")) return "name";
+	if (spec.includes("/") || spec.includes("\\")) return "path";
+	return "name";
+}
+/** A declaration file is JSON or a JS/TS module (the latter loaded via jiti). */
+var DECLARATION_FILE_RE = /\.(json|[mc]?[jt]s)$/;
+/**
+* Read a package declaration from its resolved file: a JSON `fundus.package.json`
+* (parsed as text) or a JS/TS module (`fundus.package.ts`) whose default export is
+* the declaration — loaded through the same jiti path as `fundus.config.ts`, which
+* keeps the resource `type`s literal for the package's `PackageAssets<…>` derivation.
+*/
+async function loadPackageDeclaration(file, origin) {
+	if (/\.[mc]?[jt]s$/.test(file)) {
+		let module;
+		try {
+			module = await createJiti(import.meta.url, { interopDefault: false }).import(file);
+		} catch (cause) {
+			throw new Error(`Cannot load fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+		}
+		return validatePackageDeclaration(isRecord(module) && "default" in module ? module.default : module, origin);
+	}
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (cause) {
+		throw new Error(`Cannot read fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	return parsePackageDeclaration(text, origin);
+}
+function normalizePackageSource(projectRoot, entry) {
+	let spec;
+	let rawDirOverride;
+	if (typeof entry === "string") spec = entry;
+	else if (isRecord(entry) && typeof entry.package === "string" && entry.package.length > 0) {
+		spec = entry.package;
+		if (entry.rawDir !== void 0) {
+			if (typeof entry.rawDir !== "string" || entry.rawDir.length === 0) throw new Error("fundus.config: a \"packages\" entry \"rawDir\" must be a non-empty string.");
+			rawDirOverride = entry.rawDir;
+		}
+	} else throw new Error("fundus.config: each \"packages\" entry must be a package name, a path string, or { package: string; rawDir?: string }.");
+	const kind = classifyPackageSpec(spec);
+	const reference = kind === "path" ? resolve(projectRoot, spec) : spec;
+	return {
+		origin: spec,
+		kind,
+		reference,
+		...rawDirOverride !== void 0 ? { rawDirOverride } : {}
+	};
+}
+function resolvePackageSources(projectRoot, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new Error("fundus.config: \"packages\" must be an array.");
+	return value.map((entry) => normalizePackageSource(projectRoot, entry));
+}
 /** Pure resolution step (testable without a config file on disk). */
 function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
 	if (!isRecord(value)) throw new Error("fundus.config must default-export a configuration object.");
@@ -54,6 +356,7 @@ function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
 	const figma = importConfig.figma === void 0 ? {} : importConfig.figma;
 	if (!isRecord(figma)) throw new Error("fundus.config: \"import.figma\" must be an object.");
 	if (figma.token !== void 0 && (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 !== void 0 && (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 === void 0 ? {} : figma.defaults;
 	if (!isRecord(defaults)) throw new Error("fundus.config: \"import.figma.defaults\" must be an object.");
 	const scale = defaults.scale === void 0 ? 2 : defaults.scale;
@@ -72,11 +375,91 @@ function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
 		plugins: resolvedPlugins,
 		import: { figma: {
 			...figma.token !== void 0 ? { token: figma.token } : {},
+			...figma.defaultFileKey !== void 0 ? { defaultFileKey: figma.defaultFileKey } : {},
 			defaults: { scale }
 		} },
-		usage: usage === void 0 ? null : usage
+		usage: usage === void 0 ? null : usage,
+		packageSources: resolvePackageSources(projectRoot, value.packages),
+		packages: []
 	};
 }
+function nearestNamedPackageJson(entryPath, name) {
+	let dir = dirname(entryPath);
+	for (;;) {
+		const candidate = join(dir, "package.json");
+		if (existsSync(candidate)) try {
+			const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+			if (isRecord(pkg) && pkg.name === name) return {
+				dir,
+				pkg
+			};
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error(`Cannot find the package.json for fundus package "${name}" (resolved to ${entryPath}).`);
+}
+/**
+* Resolve a name-form Package to its root directory + parsed `package.json`. A
+* declaration-only Package ships no JS entry module, so resolving the bare name
+* would throw `MODULE_NOT_FOUND`; resolve its `package.json` subpath first and
+* only fall back to entry resolution when an `exports` map hides it.
+*/
+function resolvePackageRoot(require, reference, origin) {
+	try {
+		const manifestPath = require.resolve(`${reference}/package.json`);
+		const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+		if (isRecord(pkg)) return {
+			dir: dirname(manifestPath),
+			pkg
+		};
+	} catch {}
+	let entry;
+	try {
+		entry = require.resolve(reference);
+	} catch {
+		throw new Error(`Cannot resolve fundus package "${origin}": no installed package declares it — is it a dependency?`);
+	}
+	return nearestNamedPackageJson(entry, reference);
+}
+/**
+* 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`.
+*/
+async function loadPackages(projectRoot, sources) {
+	const require = createRequire(pathToFileURL(join(projectRoot, "fundus.config.ts")).href);
+	const packages = [];
+	for (const source of sources) {
+		let file;
+		let defaultRawDir;
+		if (source.kind === "path") {
+			file = source.reference;
+			if (!existsSync(file)) throw new Error(`Fundus package file not found: ${file} (from "${source.origin}").`);
+			defaultRawDir = dirname(file);
+		} else {
+			const { dir, pkg } = resolvePackageRoot(require, source.reference, source.origin);
+			const fundusField = pkg.fundus;
+			if (!isRecord(fundusField) || typeof fundusField.package !== "string" || fundusField.package.length === 0) throw new Error(`Fundus package "${source.origin}" is missing a "fundus.package" field in its package.json.`);
+			file = resolve(dir, fundusField.package);
+			if (!existsSync(file)) throw new Error(`Fundus package "${source.origin}" declaration not found: ${file}.`);
+			defaultRawDir = typeof fundusField.rawDir === "string" && fundusField.rawDir.length > 0 ? resolve(dir, fundusField.rawDir) : dir;
+		}
+		const declaration = await loadPackageDeclaration(file, source.origin);
+		const rawDir = source.rawDirOverride !== void 0 ? resolve(projectRoot, source.rawDirOverride) : defaultRawDir;
+		packages.push({
+			origin: source.origin,
+			file,
+			rawDir,
+			declaration
+		});
+	}
+	return packages;
+}
 /** Load `fundus.config.ts` from the host project root. */
 async function loadConfig(projectRoot) {
 	const root = resolve(projectRoot);
@@ -88,7 +471,152 @@ async function loadConfig(projectRoot) {
 	} catch (cause) {
 		throw new Error(`Cannot load fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
 	}
-	return resolveConfig(root, isRecord(module) && "default" in module ? module.default : module);
+	const config = resolveConfig(root, isRecord(module) && "default" in module ? module.default : module);
+	return {
+		...config,
+		packages: await loadPackages(root, config.packageSources)
+	};
+}
+async function imageFingerprint(filePath, hashSize) {
+	const width = hashSize + 1;
+	const pixels = await sharp(filePath).rotate().trim({
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		},
+		threshold: 0
+	}).resize({
+		width,
+		height: hashSize,
+		fit: "fill"
+	}).ensureAlpha().toColourspace("srgb").raw().toBuffer();
+	const hash = new Uint8Array(Math.ceil(hashSize * hashSize / 8));
+	const alphaHash = new Uint8Array(hash.length);
+	const colorTotals = [
+		0,
+		0,
+		0
+	];
+	let alphaTotal = 0;
+	let bit = 0;
+	for (let row = 0; row < hashSize; row++) for (let column = 0; column < hashSize; column++) {
+		const leftOffset = (row * width + column) * 4;
+		const rightOffset = leftOffset + 4;
+		const leftAlpha = pixels[leftOffset + 3] / 255;
+		const rightAlpha = pixels[rightOffset + 3] / 255;
+		if (visibleLuminance(pixels, leftOffset, leftAlpha) < visibleLuminance(pixels, rightOffset, rightAlpha)) hash[bit >> 3] |= 1 << 7 - (bit & 7);
+		if (leftAlpha < rightAlpha) alphaHash[bit >> 3] |= 1 << 7 - (bit & 7);
+		for (let channel = 0; channel < 3; channel++) colorTotals[channel] += pixels[leftOffset + channel] * leftAlpha;
+		alphaTotal += leftAlpha;
+		bit += 1;
+	}
+	const pixelCount = hashSize * hashSize;
+	return {
+		hash,
+		alphaHash,
+		meanColor: colorTotals.map((total) => alphaTotal === 0 ? 0 : total / alphaTotal),
+		meanAlpha: alphaTotal / pixelCount
+	};
+}
+function visibleLuminance(pixels, offset, alpha) {
+	return (pixels[offset] * .2126 + pixels[offset + 1] * .7152 + pixels[offset + 2] * .0722) * alpha + 127 * (1 - alpha);
+}
+function colorDistance(left, right) {
+	return Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2]);
+}
+/** Count differing bits between two equally sized perceptual hashes. */
+function hammingDistance(left, right) {
+	if (left.length !== right.length) throw new Error("Image hashes must have the same length.");
+	let distance = 0;
+	for (let index = 0; index < left.length; index++) {
+		let value = left[index] ^ right[index];
+		while (value !== 0) {
+			value &= value - 1;
+			distance += 1;
+		}
+	}
+	return distance;
+}
+/**
+* Stateful so the editor can reuse fingerprints by content hash between state
+* snapshots. Unreadable raws are omitted: duplicate detection is advisory and
+* must not hide the editor or replace the pipeline's canonical diagnostics.
+*/
+var ImageDuplicateDetector = class {
+	#fingerprints = /* @__PURE__ */ new Map();
+	async find(library, rawDir) {
+		const images = Object.entries(library.assets).filter(([, record]) => record.type === "image").sort(([left], [right]) => compareCodeUnits(left, right));
+		const activeHashes = new Set(images.map(([, record]) => record.rawHash));
+		for (const hash of this.#fingerprints.keys()) if (!activeHashes.has(hash)) this.#fingerprints.delete(hash);
+		const readable = [];
+		for (const [id, record] of images) {
+			let fingerprint = this.#fingerprints.get(record.rawHash);
+			if (!fingerprint) {
+				fingerprint = imageFingerprint(join(rawDir, record.raw), 8);
+				this.#fingerprints.set(record.rawHash, fingerprint);
+			}
+			try {
+				readable.push({
+					id,
+					fingerprint: await fingerprint
+				});
+			} catch {
+				this.#fingerprints.delete(record.rawHash);
+			}
+		}
+		const duplicates = /* @__PURE__ */ new Map();
+		for (let leftIndex = 0; leftIndex < readable.length; leftIndex++) for (let rightIndex = leftIndex + 1; rightIndex < readable.length; rightIndex++) {
+			const left = readable[leftIndex];
+			const right = readable[rightIndex];
+			if (hammingDistance(left.fingerprint.hash, right.fingerprint.hash) > 5 || hammingDistance(left.fingerprint.alphaHash, right.fingerprint.alphaHash) > 5 || Math.abs(left.fingerprint.meanAlpha - right.fingerprint.meanAlpha) > .125 || colorDistance(left.fingerprint.meanColor, right.fingerprint.meanColor) > 32) continue;
+			const leftDuplicates = duplicates.get(left.id) ?? [];
+			leftDuplicates.push(right.id);
+			duplicates.set(left.id, leftDuplicates);
+			const rightDuplicates = duplicates.get(right.id) ?? [];
+			rightDuplicates.push(left.id);
+			duplicates.set(right.id, rightDuplicates);
+		}
+		return duplicates;
+	}
+};
+//#endregion
+//#region src/lib/server/check.ts
+/**
+* The delivered-slot contract: a Package slot that is delivered (explicit member
+* or in a delivered manifest's reference closure) but has no host-supplied bytes
+* must be filled. A slot with an `importSource` is `slot-unmaterialized` (run
+* import); a slot with nothing is `slot-unfilled`. Inert (undelivered) slots
+* produce no finding.
+*/
+function packageSlotFindings(library, provenance, membership) {
+	const deliveringManifests = /* @__PURE__ */ new Map();
+	for (const [name, manifestMembership] of Object.entries(membership)) for (const assetId of manifestMembership.deliveredAssetIds) {
+		const names = deliveringManifests.get(assetId) ?? [];
+		names.push(name);
+		deliveringManifests.set(assetId, names);
+	}
+	const findings = [];
+	for (const [assetId, record] of Object.entries(library.assets)) {
+		if (record.raw !== void 0) continue;
+		const names = deliveringManifests.get(assetId);
+		if (!names || names.length === 0) continue;
+		const originRecord = provenance[assetId];
+		const origin = originRecord && originRecord.source !== "host" ? originRecord.origin : "a package";
+		const deliveredBy = [...names].sort(compareCodeUnits).map((name) => `"${name}"`).join(", ");
+		if (record.importSource !== void 0) findings.push({
+			kind: "slot-unmaterialized",
+			assetId,
+			message: `Slot "${assetId}" (from ${origin}) has an import source but no bytes yet — run import to fill it. Delivered by: ${deliveredBy}.`
+		});
+		else findings.push({
+			kind: "slot-unfilled",
+			assetId,
+			message: `Slot "${assetId}" (from ${origin}) has no bytes, import source, or host override. Delivered by: ${deliveredBy}.`
+		});
+	}
+	return findings;
 }
 //#endregion
 //#region src/lib/server/raw-safety.ts
@@ -253,9 +781,22 @@ function validateScale(value) {
 }
 function validateInput(value) {
 	const input = record(value);
-	if (!input || typeof input.url !== "string") return invalidInput("Figma import requires a URL.");
+	if (!input) return invalidInput("Figma import requires a URL.");
 	if (input.format !== void 0 && 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 !== void 0 && (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 !== void 0 ? { fileKey: input.fileKey } : {},
+			...input.scale !== void 0 ? { 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 !== void 0 ? { scale: validateScale(input.scale) } : {}
@@ -264,6 +805,17 @@ function validateInput(value) {
 function validateFigmaSourceParameters(value) {
 	const source = record(value);
 	if (!source || typeof source.fileKey !== "string" || source.fileKey.length === 0 || typeof source.nodeId !== "string" || !/^\d+:\d+$/.test(source.nodeId) || 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,
@@ -455,6 +1007,37 @@ async function validatePng(bytes) {
 	if (!metadata.width || !metadata.height) throw new SourceImportError("invalid-response", "Figma export has invalid dimensions.");
 	if (metadata.width * metadata.height > MAX_PIXELS) 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);
+}
+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) throw new SourceImportError("not-configured", "Figma access is not configured.");
@@ -494,6 +1077,19 @@ var 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,
@@ -504,6 +1100,13 @@ var 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);
 	}
 };
@@ -1075,110 +1678,6 @@ function pathsFromRoot(root, target, referencesByAsset, countMemo = /* @__PURE__
 function usageSnapshotRevision(parts) {
 	return createHash("sha256").update(parts.join("\0")).digest("hex");
 }
-async function imageFingerprint(filePath, hashSize) {
-	const width = hashSize + 1;
-	const pixels = await sharp(filePath).rotate().trim({
-		background: {
-			r: 0,
-			g: 0,
-			b: 0,
-			alpha: 0
-		},
-		threshold: 0
-	}).resize({
-		width,
-		height: hashSize,
-		fit: "fill"
-	}).ensureAlpha().toColourspace("srgb").raw().toBuffer();
-	const hash = new Uint8Array(Math.ceil(hashSize * hashSize / 8));
-	const alphaHash = new Uint8Array(hash.length);
-	const colorTotals = [
-		0,
-		0,
-		0
-	];
-	let alphaTotal = 0;
-	let bit = 0;
-	for (let row = 0; row < hashSize; row++) for (let column = 0; column < hashSize; column++) {
-		const leftOffset = (row * width + column) * 4;
-		const rightOffset = leftOffset + 4;
-		const leftAlpha = pixels[leftOffset + 3] / 255;
-		const rightAlpha = pixels[rightOffset + 3] / 255;
-		if (visibleLuminance(pixels, leftOffset, leftAlpha) < visibleLuminance(pixels, rightOffset, rightAlpha)) hash[bit >> 3] |= 1 << 7 - (bit & 7);
-		if (leftAlpha < rightAlpha) alphaHash[bit >> 3] |= 1 << 7 - (bit & 7);
-		for (let channel = 0; channel < 3; channel++) colorTotals[channel] += pixels[leftOffset + channel] * leftAlpha;
-		alphaTotal += leftAlpha;
-		bit += 1;
-	}
-	const pixelCount = hashSize * hashSize;
-	return {
-		hash,
-		alphaHash,
-		meanColor: colorTotals.map((total) => alphaTotal === 0 ? 0 : total / alphaTotal),
-		meanAlpha: alphaTotal / pixelCount
-	};
-}
-function visibleLuminance(pixels, offset, alpha) {
-	return (pixels[offset] * .2126 + pixels[offset + 1] * .7152 + pixels[offset + 2] * .0722) * alpha + 127 * (1 - alpha);
-}
-function colorDistance(left, right) {
-	return Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2]);
-}
-/** Count differing bits between two equally sized perceptual hashes. */
-function hammingDistance(left, right) {
-	if (left.length !== right.length) throw new Error("Image hashes must have the same length.");
-	let distance = 0;
-	for (let index = 0; index < left.length; index++) {
-		let value = left[index] ^ right[index];
-		while (value !== 0) {
-			value &= value - 1;
-			distance += 1;
-		}
-	}
-	return distance;
-}
-/**
-* Stateful so the editor can reuse fingerprints by content hash between state
-* snapshots. Unreadable raws are omitted: duplicate detection is advisory and
-* must not hide the editor or replace the pipeline's canonical diagnostics.
-*/
-var ImageDuplicateDetector = class {
-	#fingerprints = /* @__PURE__ */ new Map();
-	async find(library, rawDir) {
-		const images = Object.entries(library.assets).filter(([, record]) => record.type === "image").sort(([left], [right]) => compareCodeUnits(left, right));
-		const activeHashes = new Set(images.map(([, record]) => record.rawHash));
-		for (const hash of this.#fingerprints.keys()) if (!activeHashes.has(hash)) this.#fingerprints.delete(hash);
-		const readable = [];
-		for (const [id, record] of images) {
-			let fingerprint = this.#fingerprints.get(record.rawHash);
-			if (!fingerprint) {
-				fingerprint = imageFingerprint(join(rawDir, record.raw), 8);
-				this.#fingerprints.set(record.rawHash, fingerprint);
-			}
-			try {
-				readable.push({
-					id,
-					fingerprint: await fingerprint
-				});
-			} catch {
-				this.#fingerprints.delete(record.rawHash);
-			}
-		}
-		const duplicates = /* @__PURE__ */ new Map();
-		for (let leftIndex = 0; leftIndex < readable.length; leftIndex++) for (let rightIndex = leftIndex + 1; rightIndex < readable.length; rightIndex++) {
-			const left = readable[leftIndex];
-			const right = readable[rightIndex];
-			if (hammingDistance(left.fingerprint.hash, right.fingerprint.hash) > 5 || hammingDistance(left.fingerprint.alphaHash, right.fingerprint.alphaHash) > 5 || Math.abs(left.fingerprint.meanAlpha - right.fingerprint.meanAlpha) > .125 || colorDistance(left.fingerprint.meanColor, right.fingerprint.meanColor) > 32) continue;
-			const leftDuplicates = duplicates.get(left.id) ?? [];
-			leftDuplicates.push(right.id);
-			duplicates.set(left.id, leftDuplicates);
-			const rightDuplicates = duplicates.get(right.id) ?? [];
-			rightDuplicates.push(left.id);
-			duplicates.set(right.id, rightDuplicates);
-		}
-		return duplicates;
-	}
-};
 //#endregion
 //#region src/lib/server/operations.ts
 /**
@@ -1206,6 +1705,17 @@ function figmaSlicePixelRatio(raw, type) {
 	if (type !== "slice" || raw.importSource?.importer !== "figma") return void 0;
 	return validateFigmaSourceParameters(raw.importSource.parameters).scale;
 }
+/**
+* The Fundus tag of a Figma tag-mode import source, else null. In tag mode the
+* tag IS the asset id, so this is the single seam that ties provenance to
+* identity — used to assert id equality on import/reimport and to forbid
+* renaming a tag-referenced asset. Only Figma sources are inspected.
+*/
+function figmaTagOf(importSource) {
+	if (importSource?.importer !== "figma") return null;
+	const params = validateFigmaSourceParameters(importSource.parameters);
+	return params.mode === "tag" ? params.fundusTag : null;
+}
 var FundusOperations = class {
 	#config;
 	#registry;
@@ -1477,6 +1987,8 @@ var FundusOperations = class {
 		});
 		return this.#enqueueOperation(async () => {
 			this.#validateImportedRaw(raw, options.importer);
+			const tag = figmaTagOf(raw.importSource);
+			if (tag !== null && tag !== options.id) throw new SourceImportError("invalid-input", `A Figma tag import must use its tag as the asset id: the tag is "${tag}", not "${options.id}".`);
 			return this.#createImportedAsset(raw, options);
 		});
 	}
@@ -1513,6 +2025,8 @@ var FundusOperations = class {
 		if (snapshot.input !== void 0 && !raw.importSource) throw new SourceImportError("invalid-response", "The source importer did not return provenance for the updated source.");
 		return this.#enqueueOperation(async () => {
 			this.#validateImportedRaw(raw, snapshot.importer.kind);
+			const tag = figmaTagOf(raw.importSource);
+			if (tag !== null && tag !== id) throw new SourceImportError("invalid-input", `A Figma tag reimport may not retarget asset "${id}" to a different tag "${tag}".`);
 			const plugin = serverPluginForType(snapshot.expected.type, this.#registry);
 			if (!plugin.descriptor.accepts.includes(raw.extension)) throw new SourceImportError("invalid-response", `The ${snapshot.expected.type} type does not accept ".${raw.extension}" files.`);
 			const pixelRatio = snapshot.input === void 0 ? void 0 : figmaSlicePixelRatio(raw, snapshot.expected.type);
@@ -1559,6 +2073,8 @@ var FundusOperations = class {
 		const importSource = raw.importSource;
 		return this.#enqueueOperation(async () => {
 			this.#validateImportedRaw(raw, preflight.importer.kind);
+			const tag = figmaTagOf(importSource);
+			if (tag !== null && tag !== id) throw new SourceImportError("invalid-input", `A Figma tag replacement must use its own tag as the asset id: the tag is "${tag}", not "${id}".`);
 			const plugin = serverPluginForType(preflight.expected.type, this.#registry);
 			if (!plugin.descriptor.accepts.includes(raw.extension)) throw new SourceImportError("invalid-response", `The ${preflight.expected.type} type does not accept ".${raw.extension}" files.`);
 			const previousName = rawFileNameOfPath(preflight.expected.raw);
@@ -1580,11 +2096,101 @@ var FundusOperations = class {
 			}
 		});
 	}
+	/**
+	* Edit a Figma tag asset's tag, fileKey, and/or scale in place. Because in tag
+	* mode the tag IS the asset id, changing the tag renames the asset (moves the
+	* library key); changing only fileKey/scale is an in-place re-point. Mirrors
+	* `reimportAsset`'s three phases: preflight in the queue, materialize outside
+	* it, then commit atomically through `store.repointTagAsset`.
+	*/
+	async retagFigmaAsset(id, input) {
+		const snapshot = await this.#enqueueOperation(async () => {
+			const library = await this.#store.read();
+			this.#requireAsset(library, id);
+			const record = library.assets[id];
+			const currentTag = figmaTagOf(record.importSource);
+			if (currentTag === null || !record.importSource) throw new SourceImportError("invalid-input", `Asset "${id}" is not a Figma tag import.`);
+			const current = validateFigmaSourceParameters(record.importSource.parameters);
+			const newTag = input.tag ?? currentTag;
+			const fileKey = input.fileKey ?? current.fileKey;
+			const scale = input.scale ?? current.scale;
+			if (newTag !== id) {
+				const problem = assetIdError(newTag);
+				if (problem) throw new SourceImportError("invalid-input", problem);
+				if (Object.hasOwn(library.assets, newTag)) throw new SourceImportError("invalid-input", `An asset with id "${newTag}" already exists.`);
+				const candidate = structuredClone(library);
+				candidate.assets[newTag] = candidate.assets[id];
+				delete candidate.assets[id];
+				await this.#assertNoIntroducedIssues(library, candidate);
+			}
+			try {
+				await verifyStableRawFile(join(this.#config.rawDir, record.raw), record.rawHash);
+			} catch {
+				throw new SourceImportError("stale-import", "The local raw file changed. Apply or discard that edit before retagging.");
+			}
+			const importer = this.#importers.require("figma");
+			return {
+				importer,
+				input: importer.validateInput({
+					mode: "tag",
+					tag: newTag,
+					fileKey,
+					scale,
+					format: "png"
+				}),
+				newTag,
+				expected: {
+					raw: record.raw,
+					rawHash: record.rawHash,
+					type: record.type,
+					canonicalSource: canonicalizeParameters(record.importSource)
+				}
+			};
+		});
+		const raw = await snapshot.importer.importRaw(snapshot.input, {
+			config: this.#config,
+			fetch: globalThis.fetch
+		});
+		if (!raw.importSource) throw new SourceImportError("invalid-response", "The Figma importer did not return provenance for the retagged source.");
+		const importSource = raw.importSource;
+		return this.#enqueueOperation(async () => {
+			this.#validateImportedRaw(raw, snapshot.importer.kind);
+			if (figmaTagOf(importSource) !== snapshot.newTag) throw new SourceImportError("invalid-response", `The Figma importer resolved a different tag than "${snapshot.newTag}".`);
+			const plugin = serverPluginForType(snapshot.expected.type, this.#registry);
+			if (!plugin.descriptor.accepts.includes(raw.extension)) throw new SourceImportError("invalid-response", `The ${snapshot.expected.type} type does not accept ".${raw.extension}" files.`);
+			const pixelRatio = figmaSlicePixelRatio(raw, snapshot.expected.type);
+			let library;
+			try {
+				library = await this.#store.repointTagAsset(id, snapshot.newTag, raw.bytes, snapshot.expected, importSource, pixelRatio === void 0 ? void 0 : (parameters) => plugin.descriptor.validateParameters(mergeParameterPatch(parameters, { pixelRatio })));
+			} catch (cause) {
+				if (cause instanceof Error && cause.message === "stale-import") throw new SourceImportError("stale-import", "The asset or local raw file changed while Figma was exporting. Nothing was changed.");
+				throw cause;
+			}
+			return this.#afterMutation(library);
+		});
+	}
 	async #createImportedAsset(raw, options) {
 		this.#validateImportedRaw(raw);
 		const fileName = raw.suggestedFileName ?? `${options.id}.${raw.extension}`;
 		const plugin = serverPluginForType(options.type, this.#registry);
-		const library = await this.#store.createAsset({
+		const packageBase = this.#packageBase(await this.#store.read(), options.id);
+		if (packageBase && packageBase.type !== options.type) throw new SourceImportError("invalid-input", `Filling slot "${options.id}" requires the package type "${packageBase.type}", not "${options.type}".`);
+		let slotOverride = {};
+		if (packageBase) {
+			const pixelRatio = figmaSlicePixelRatio(raw, options.type);
+			if (pixelRatio !== void 0) slotOverride = mergeParameterPatch(slotOverride, { pixelRatio });
+			if (options.parametersPatch !== void 0) slotOverride = mergeParameterPatch(slotOverride, options.parametersPatch);
+		}
+		const library = packageBase ? await this.#store.createAsset({
+			fileName,
+			bytes: raw.bytes,
+			type: options.type,
+			id: options.id,
+			folder: options.folder,
+			manifests: options.manifests,
+			importSource: raw.importSource,
+			parametersOverride: slotOverride
+		}) : await this.#store.createAsset({
 			fileName,
 			bytes: raw.bytes,
 			type: options.type,
@@ -1619,7 +2225,8 @@ var FundusOperations = class {
 		const folder = normalizeFolderPath(options.folder ?? "");
 		if (folder !== "" && !library.folders.includes(folder)) throw new SourceImportError("invalid-input", `Unknown folder "${folder}".`);
 		if (options.manifests !== void 0 && (!Array.isArray(options.manifests) || options.manifests.some((value) => typeof value !== "string"))) throw new SourceImportError("invalid-input", "Import manifests must be an array of strings.");
-		for (const manifest of new Set(options.manifests ?? [])) if (!Object.hasOwn(library.manifests, manifest)) throw new SourceImportError("invalid-input", `Unknown manifest "${manifest}".`);
+		const validManifests = this.#effectiveOf(library).effective.manifests;
+		for (const manifest of new Set(options.manifests ?? [])) if (!Object.hasOwn(validManifests, manifest)) throw new SourceImportError("invalid-input", `Unknown manifest "${manifest}".`);
 	}
 	#validateImportedRaw(raw, importerKind) {
 		if (!(raw.bytes instanceof Uint8Array) || !/^[a-z0-9]+$/.test(raw.extension)) throw new SourceImportError("invalid-response", "The source importer returned invalid raw data.");
@@ -1634,7 +2241,7 @@ var FundusOperations = class {
 	}
 	async #patchAsset(id, body) {
 		let library = await this.#store.read();
-		this.#requireAsset(library, id);
+		this.#assertHostAsset(library, id, "editing it");
 		if (body.parameters !== void 0) library = await this.#store.updateParameters(id, body.parameters);
 		if (body.manifests !== void 0) {
 			if (!Array.isArray(body.manifests) || body.manifests.some((name) => typeof name !== "string")) throw new Error("\"manifests\" must be an array of manifest names.");
@@ -1742,6 +2349,7 @@ var FundusOperations = class {
 	async #renameAsset(id, newId) {
 		const library = await this.#store.read();
 		this.#requireAsset(library, id);
+		if (figmaTagOf(library.assets[id].importSource) !== null) throw new SourceImportError("invalid-input", "This asset is referenced by a Figma tag and cannot be renamed; re-import with a new tag instead.");
 		if (newId !== id && !Object.hasOwn(library.assets, newId)) {
 			const candidate = structuredClone(library);
 			candidate.assets[newId] = candidate.assets[id];
@@ -1835,11 +2443,13 @@ var FundusOperations = class {
 	async #runAfterMutation(library) {
 		const pipelineIssues = [];
 		const classification = await this.#classifyRawDirectory(library);
-		const ordinaryIssues = await this.#store.validate(library);
+		const { effective, provenance, mergeFindings } = this.#effectiveOf(library);
+		const materialized = materializeLibrary(effective);
+		const ordinaryIssues = [...await this.#store.validate(library, { flatSpace: false }), ...this.#flatIssues(effective, provenance, mergeFindings)];
 		const safetyIssues = this.#rawSafetyIssues(library, classification);
 		if (ordinaryIssues.length === 0 && safetyIssues.length === 0) try {
-			const report = await processAssets(this.#config, library, this.#registry);
-			await generateManifestModules(this.#config, library, report.proxies, this.#registry);
+			const report = await processAssets(this.#config, materialized, this.#registry);
+			await generateManifestModules(this.#config, materialized, report.proxies, this.#registry);
 		} catch (cause) {
 			pipelineIssues.push({ message: `Processing failed: ${cause instanceof Error ? cause.message : String(cause)}` });
 		}
@@ -1851,10 +2461,10 @@ var FundusOperations = class {
 			state: await this.#snapshotState(latestLibrary, latestClassification, pipelineIssues)
 		};
 	}
-	async #buildState(library, issues, classification) {
-		const [gitBranch, changedGitAssets] = await Promise.all([currentGitBranch(this.#config.projectRoot), gitAssetChanges(this.#config.projectRoot, this.#config.library, library)]);
+	async #buildState(host, library, provenance, issues, classification) {
+		const [gitBranch, changedGitAssets] = await Promise.all([currentGitBranch(this.#config.projectRoot), gitAssetChanges(this.#config.projectRoot, this.#config.library, host)]);
 		const referencesByAsset = collectAllReferences(library, descriptorsByType(this.#registry));
-		const duplicatesByAsset = await this.#duplicateDetector.find(library, this.#config.rawDir);
+		const duplicatesByAsset = await this.#duplicateDetector.find(host, this.#config.rawDir);
 		const membershipByManifest = computeLibraryMembership(library, referencesByAsset);
 		const delivered = allDeliveredAssetIds(membershipByManifest);
 		const passiveManifestsByAsset = /* @__PURE__ */ new Map();
@@ -1878,12 +2488,21 @@ var FundusOperations = class {
 		const assets = [];
 		for (const assetId of Object.keys(library.assets).sort(compareCodeUnits)) {
 			const record = library.assets[assetId];
+			const prov = provenance[assetId] ?? { source: "host" };
+			const origin = prov.source === "host" ? { kind: "host" } : prov.source === "package" ? {
+				kind: "package",
+				origin: prov.origin
+			} : {
+				kind: "override",
+				origin: prov.origin
+			};
+			const isSlot = record.raw === void 0;
 			const warnings = [];
 			for (const issue of issues) if (issue.assetId === assetId) warnings.push(issue.message);
-			if (record.manifests.length === 0 && !delivered.has(assetId)) warnings.push("In no manifest and not referenced by any delivered asset — nothing is processed or generated for it.");
+			if (record.manifests.length === 0 && !delivered.has(assetId) && !isSlot) warnings.push("In no manifest and not referenced by any delivered asset — nothing is processed or generated for it.");
 			if (record.importSource && !this.#importers.has(record.importSource.importer)) warnings.push(`Importer "${record.importSource.importer}" is unavailable; the local raw file remains usable.`);
 			let proxy = null;
-			if (delivered.has(assetId)) try {
+			if (delivered.has(assetId) && !isSlot) try {
 				const currentProxy = await readCurrentProxy(assetId, record, this.#config, this.#registry);
 				if (currentProxy) proxy = {
 					url: `/files/proxy/${encodeRelativePathForUrl(currentProxy.relativePath)}`,
@@ -1894,13 +2513,15 @@ var FundusOperations = class {
 			} catch (cause) {
 				warnings.push(cause instanceof Error ? cause.message : String(cause));
 			}
+			const raw = record.raw ?? "";
+			const rawHash = record.rawHash ?? "";
 			assets.push({
 				id: assetId,
 				type: record.type,
-				raw: record.raw,
-				folder: folderOfRawPath(record.raw),
-				rawUrl: `/files/raw/${encodeRelativePathForUrl(record.raw)}?v=${record.rawHash.slice(0, 12)}`,
-				rawHash: record.rawHash,
+				raw,
+				folder: folderOfRawPath(raw),
+				rawUrl: isSlot ? "" : `/files/raw/${encodeRelativePathForUrl(raw)}?v=${rawHash.slice(0, 12)}`,
+				rawHash,
 				gitStatus: changedGitAssets.get(assetId) ?? null,
 				importSource: record.importSource,
 				parameters: record.parameters,
@@ -1915,7 +2536,9 @@ var FundusOperations = class {
 						assetId: reference.assetId
 					})),
 					incoming: incomingByAsset.get(assetId) ?? []
-				}
+				},
+				origin,
+				overridden: origin.kind === "override"
 			});
 		}
 		const proxySizeByAssetId = new Map(assets.filter((asset) => asset.proxy).map((asset) => [asset.id, asset.proxy?.fileSize ?? 0]));
@@ -1939,18 +2562,22 @@ var FundusOperations = class {
 			presetNames[type] = names;
 			presetCapabilities[type] = Object.fromEntries(names.map((name) => [name, plugin.presetCapabilities?.(presets[name]) ?? {}]));
 		}
-		const rawIngestionQueue = this.#buildRawIngestionQueue(library, classification);
+		const rawIngestionQueue = this.#buildRawIngestionQueue(host, classification);
 		return {
 			gitBranch,
 			library,
 			assets,
-			importDefaults: { figma: { scale: this.#config.import.figma.defaults.scale } },
+			importDefaults: { figma: {
+				scale: this.#config.import.figma.defaults.scale,
+				...this.#config.import.figma.defaultFileKey !== void 0 ? { defaultFileKey: this.#config.import.figma.defaultFileKey } : {}
+			} },
 			issues,
 			presetNames,
 			presetCapabilities,
 			manifestMemberships,
 			manifestDeliveredBytes,
-			rawIngestionQueue
+			rawIngestionQueue,
+			packageOrigins: this.#config.packages.map((pkg) => pkg.origin).sort(compareCodeUnits)
 		};
 	}
 	#compatibleTypes(path) {
@@ -1963,8 +2590,10 @@ var FundusOperations = class {
 		return rawSafetyIssues(library, classification, (path) => this.#compatibleTypes(path));
 	}
 	async #snapshotState(library, classification, extraIssues = []) {
+		const { effective, provenance, mergeFindings } = this.#effectiveOf(library);
 		const issues = [
-			...await this.#store.validate(library),
+			...await this.#store.validate(library, { flatSpace: false }),
+			...this.#flatIssues(effective, provenance, mergeFindings),
 			...this.#rawSafetyIssues(library, classification),
 			...extraIssues
 		];
@@ -1975,7 +2604,7 @@ var FundusOperations = class {
 			seen.add(key);
 			return true;
 		});
-		return this.#buildState(library, uniqueIssues, classification);
+		return this.#buildState(library, effective, provenance, uniqueIssues, classification);
 	}
 	#canAutoReconcile(classification, retry = false) {
 		return classification.complete && classification.blockers.length === 0 && classification.moves.length + classification.deletions.length > 0 && (!retry || classification.edited.length === 0 && classification.unmanaged.length === 0);
@@ -2064,6 +2693,59 @@ var FundusOperations = class {
 	#requireAsset(library, id) {
 		if (!Object.hasOwn(library.assets, id)) throw new Error(`Unknown asset "${id}".`);
 	}
+	/** Merge the configured Packages under the host library (host wins). */
+	#effectiveOf(host) {
+		const { library, provenance, findings } = mergePackages(host, this.#config.packages ?? []);
+		return {
+			effective: library,
+			provenance,
+			mergeFindings: findings
+		};
+	}
+	/**
+	* The Package base record for `id` when `id` is a read-only Package asset the
+	* host has not yet filled — i.e. this create is a *slot fill*. Returns null
+	* for a plain new host asset.
+	*/
+	#packageBase(host, id) {
+		if (Object.hasOwn(host.assets, id)) return null;
+		const { effective, provenance } = this.#effectiveOf(host);
+		if (provenance[id]?.source === "package") return { type: effective.assets[id].type };
+		return null;
+	}
+	/**
+	* Flat-space validation over the effective library: merge errors, id/type/
+	* parameter/membership/appearance/reference checks, module collisions, and
+	* delivered-slot findings. Disk/host checks stay in `store.validate(host,
+	* { flatSpace: false })`.
+	*/
+	#flatIssues(effective, provenance, mergeFindings) {
+		const membership = computeLibraryMembership(effective, collectAllReferences(effective, descriptorsByType(this.#registry)));
+		return [
+			...mergeFindings.filter((finding) => finding.kind !== "package-overridden").map((finding) => ({
+				assetId: finding.assetId,
+				message: finding.message
+			})),
+			...flatLibraryIssues(effective, descriptorsByType(this.#registry)),
+			...manifestModuleCollisionIssues(effective.manifests),
+			...packageSlotFindings(effective, provenance, membership).map((finding) => ({
+				assetId: finding.assetId,
+				message: finding.message
+			}))
+		];
+	}
+	/**
+	* Whether an id is a read-only Package asset the host has not overridden.
+	* Such ids can be filled/overridden (write a host record) but not mutated,
+	* renamed, moved, or deleted in place.
+	*/
+	#assertHostAsset(host, id, action) {
+		if (Object.hasOwn(host.assets, id)) return;
+		const { provenance } = this.#effectiveOf(host);
+		const prov = provenance[id];
+		if (prov && prov.source !== "host") throw new Error(`Asset "${id}" is provided by package "${prov.origin}"; ${action} is not available. Override it by importing or uploading bytes with this id.`);
+		throw new Error(`Unknown asset "${id}".`);
+	}
 	/**
 	* Apply a CLI asset change to the store, validating the resulting library
 	* on an in-memory candidate first — nothing is persisted when the change
@@ -2112,4 +2794,4 @@ async function createFundusContext() {
 }
 
 export { getFundusContext as g, initializeFundusContext as i };
-//# sourceMappingURL=context.js-CVuTSPjH.js.map
+//# sourceMappingURL=context.js-Dh0ibRIF.js.map