fundus 0.10.0 → 0.11.1

package/dist/runtime/components/SliceCanvas.svelte

@@ -13,25 +13,28 @@
 	canvas is enlarged by the overdraw's destination size and offset negatively
 	(see `computeCanvasPaintLayout`), so the baked shadow/glow paints outside
 	the layout box while the wrapper (and therefore the layout) keeps the box
-	size — exactly where the DOM backend positions its overdraw cells.
+	size — exactly where the DOM backend positions its border-image paint.
 -->
 <script lang="ts">
-	import type { SliceManifestEntry } from '../../core/index.js';
-	import { computeCanvasPaintLayout, computeRenderCells } from '../geometry.js';
+	import {
+		computeCanvasPaintLayout,
+		computeRenderCells,
+		type CanvasPaintLayout
+	} from '../geometry.js';
 	import { observeBorderBoxSize } from '../observe-border-box-size.js';
+	import type { LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
 
 	interface Props {
-		src: SliceManifestEntry;
+		snapshot: LoadedSliceSnapshot | null;
 		/** Accessible label for the rendered graphic. */
 		alt?: string;
 		class?: string;
 	}
 
-	let { src, alt = '', class: className = '' }: Props = $props();
+	let { snapshot, alt = '', class: className = '' }: Props = $props();
 
 	let root = $state<HTMLDivElement>();
 	let canvas = $state<HTMLCanvasElement>();
-	let image = $state<HTMLImageElement>();
 	let boxWidth = $state(0);
 	let boxHeight = $state(0);
 	let devicePixelRatio = $state(1);
@@ -39,23 +42,6 @@
 	// box nor the entry changed (belt and braces alongside the ResizeObserver).
 	let redrawTick = $state(0);
 
-	// Load the source image once per entry `src` — the same plain URL the DOM
-	// backend paints (slices are image-backed: the browser cache owns the bytes,
-	// preload retains nothing to resolve).
-	$effect(() => {
-		const sourceUrl = src.src;
-		const next = new Image();
-		let cancelled = false;
-		next.onload = () => {
-			if (!cancelled) image = next;
-		};
-		next.src = sourceUrl;
-		return () => {
-			cancelled = true;
-			next.onload = null;
-		};
-	});
-
 	// Track the display's devicePixelRatio: a resolution media query fires
 	// exactly when the DPR leaves the tracked value (browser zoom, moving the
 	// window to another display). The tracked state must be READ first — a
@@ -83,40 +69,65 @@
 		});
 	});
 
-	const layout = $derived(computeCanvasPaintLayout(src, boxWidth, boxHeight, devicePixelRatio));
+	const emptyLayout: CanvasPaintLayout = {
+		cssLeft: 0,
+		cssTop: 0,
+		cssWidth: 0,
+		cssHeight: 0,
+		backingWidth: 0,
+		backingHeight: 0,
+		originX: 0,
+		originY: 0
+	};
+	const layout = $derived.by(() => {
+		const current = snapshot;
+		return current
+			? computeCanvasPaintLayout(current.entry, boxWidth, boxHeight, devicePixelRatio)
+			: emptyLayout;
+	});
 
-	// Redraw when the box size, image, entry, DPR, or window changes.
+	// Redraw only when a committed snapshot, the box, DPR, or window changes.
 	$effect(() => {
-		void image;
-		void src;
-		void layout;
+		const current = snapshot;
+		const currentLayout = layout;
 		void redrawTick;
-		draw();
+		draw(current, currentLayout);
 	});
 
-	function draw(): void {
+	function draw(current: LoadedSliceSnapshot | null, currentLayout: CanvasPaintLayout): void {
 		const element = canvas;
-		const source = image;
-		if (!element || !source) return;
-		if (boxWidth === 0 || boxHeight === 0) {
+		if (!element) return;
+		if (!current || boxWidth === 0 || boxHeight === 0) {
 			element.width = 0;
 			element.height = 0;
 			return;
 		}
 
-		element.width = layout.backingWidth;
-		element.height = layout.backingHeight;
+		element.width = currentLayout.backingWidth;
+		element.height = currentLayout.backingHeight;
 
 		const context = element.getContext('2d');
 		if (!context) return;
 		// Origin at the layout box's top-left, so the (possibly negative) cell
 		// coordinates from computeRenderCells apply directly.
-		context.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, layout.originX, layout.originY);
-		context.clearRect(layout.cssLeft, layout.cssTop, layout.cssWidth, layout.cssHeight);
-
-		for (const cell of computeRenderCells(src, boxWidth, boxHeight)) {
+		context.setTransform(
+			devicePixelRatio,
+			0,
+			0,
+			devicePixelRatio,
+			currentLayout.originX,
+			currentLayout.originY
+		);
+		context.clearRect(
+			currentLayout.cssLeft,
+			currentLayout.cssTop,
+			currentLayout.cssWidth,
+			currentLayout.cssHeight
+		);
+
+		for (const cell of computeRenderCells(current.entry, boxWidth, boxHeight)) {
 			context.drawImage(
-				source,
+				current.image,
 				cell.sx,
 				cell.sy,
 				cell.sw,

package/dist/runtime/components/SliceCanvas.svelte.d.ts

@@ -1,6 +1,6 @@
-import type { SliceManifestEntry } from '../../core/index.js';
+import type { LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
 interface Props {
-    src: SliceManifestEntry;
+    snapshot: LoadedSliceSnapshot | null;
     /** Accessible label for the rendered graphic. */
     alt?: string;
     class?: string;

package/dist/runtime/components/SliceDom.svelte

@@ -5,33 +5,96 @@
 	in the entry. Private: hosts render `Slice.svelte`, which dispatches between
 	this and the canvas backend.
 
-	Fills its container and measures it (ResizeObserver), then paints one cell per
-	slice region as an absolutely-positioned window onto the source image: a full
-	copy of the image is scaled and offset (percentages relative to the cell) so
-	the cell shows exactly its source region. Cells abut on integer pixels; corners
-	/ caps keep their aspect ratio (no distortion), the stretch bands fill the rest.
-	With overdraw the cells extend past the container (negative offsets), so the
-	root switches to overflow: visible and the baked shadow/glow draws outside the
-	layout box.
+	Fills its container and measures it (ResizeObserver), then paints the complete
+	slice through one CSS border-image. The browser still stretches the same source
+	regions computed by `computeRenderCells`, but rasterizes them as one border
+	image instead of separate clipped elements. Shared slice edges therefore cannot
+	expose the background under fractional transforms.
+	With overdraw the paint element extends past the container (negative offsets),
+	so the root switches to overflow: visible and the baked shadow/glow draws
+	outside the layout box.
 -->
 <script lang="ts">
-	import type { SliceManifestEntry } from '../../core/index.js';
-	import { computeRenderCells, effectiveOverdraw } from '../geometry.js';
+	import type { SliceInsets, SliceManifestEntry } from '../../core/index.js';
+	import { computeRenderCells, effectiveInsets, effectiveOverdraw } from '../geometry.js';
 	import { observeBorderBoxSize } from '../observe-border-box-size.js';
+	import type { LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
 
 	interface Props {
-		src: SliceManifestEntry;
+		snapshot: LoadedSliceSnapshot | null;
 		/** Accessible label for the rendered graphic. */
 		alt?: string;
 		class?: string;
 	}
 
-	let { src, alt = '', class: className = '' }: Props = $props();
+	let { snapshot, alt = '', class: className = '' }: Props = $props();
 
 	let root = $state<HTMLDivElement>();
 	let boxWidth = $state(0);
 	let boxHeight = $state(0);
 
+	interface BorderImagePaint {
+		left: number;
+		top: number;
+		width: number;
+		height: number;
+		slices: SliceInsets;
+		widths: SliceInsets;
+	}
+
+	function clamp(value: number, min: number, max: number): number {
+		return Math.max(min, Math.min(max, value));
+	}
+
+	function computeBorderImagePaint(
+		entry: SliceManifestEntry,
+		width: number,
+		height: number
+	): BorderImagePaint | null {
+		const cells = computeRenderCells(entry, width, height);
+		if (cells.length === 0) return null;
+
+		const effective = effectiveInsets(entry);
+		const leftSlice = clamp(effective.left, 0, entry.sourceWidth);
+		const rightSlice = clamp(effective.right, 0, entry.sourceWidth - leftSlice);
+		const topSlice = clamp(effective.top, 0, entry.sourceHeight);
+		const bottomSlice = clamp(effective.bottom, 0, entry.sourceHeight - topSlice);
+		const slices = {
+			top: topSlice,
+			right: rightSlice,
+			bottom: bottomSlice,
+			left: leftSlice
+		};
+		const left = Math.min(...cells.map((cell) => cell.dx));
+		const top = Math.min(...cells.map((cell) => cell.dy));
+		const right = Math.max(...cells.map((cell) => cell.dx + cell.dw));
+		const bottom = Math.max(...cells.map((cell) => cell.dy + cell.dh));
+
+		return {
+			left,
+			top,
+			width: right - left,
+			height: bottom - top,
+			slices,
+			widths: {
+				top: cells.find((cell) => topSlice > 0 && cell.sy === 0 && cell.sh === topSlice)?.dh ?? 0,
+				right:
+					cells.find(
+						(cell) =>
+							rightSlice > 0 && cell.sx === entry.sourceWidth - rightSlice && cell.sw === rightSlice
+					)?.dw ?? 0,
+				bottom:
+					cells.find(
+						(cell) =>
+							bottomSlice > 0 &&
+							cell.sy === entry.sourceHeight - bottomSlice &&
+							cell.sh === bottomSlice
+					)?.dh ?? 0,
+				left: cells.find((cell) => leftSlice > 0 && cell.sx === 0 && cell.sw === leftSlice)?.dw ?? 0
+			}
+		};
+	}
+
 	$effect(() => {
 		const element = root;
 		if (!element) return;
@@ -41,9 +104,11 @@
 		});
 	});
 
-	const cells = $derived(computeRenderCells(src, boxWidth, boxHeight));
+	const entry = $derived(snapshot?.entry ?? null);
+	const paint = $derived(entry ? computeBorderImagePaint(entry, boxWidth, boxHeight) : null);
 	const hasOverdraw = $derived.by(() => {
-		const overdraw = effectiveOverdraw(src);
+		if (!entry) return false;
+		const overdraw = effectiveOverdraw(entry);
 		return overdraw.top > 0 || overdraw.right > 0 || overdraw.bottom > 0 || overdraw.left > 0;
 	});
 </script>
@@ -55,25 +120,18 @@
 	role={alt ? 'img' : undefined}
 	aria-label={alt || undefined}
 >
-	{#each cells as cell (cell.key)}
+	{#if entry && paint}
 		<div
-			class="fundus-slice__cell"
-			style:left="{cell.dx}px"
-			style:top="{cell.dy}px"
-			style:width="{cell.dw}px"
-			style:height="{cell.dh}px"
-		>
-			<img
-				src={src.src}
-				alt=""
-				draggable="false"
-				style:width="{(src.sourceWidth / cell.sw) * 100}%"
-				style:height="{(src.sourceHeight / cell.sh) * 100}%"
-				style:left="{(-cell.sx / cell.sw) * 100}%"
-				style:top="{(-cell.sy / cell.sh) * 100}%"
-			/>
-		</div>
-	{/each}
+			class="fundus-slice__paint"
+			style:left="{paint.left}px"
+			style:top="{paint.top}px"
+			style:width="{paint.width}px"
+			style:height="{paint.height}px"
+			style:border-image-source={`url(${JSON.stringify(entry.src)})`}
+			style:border-image-slice={`${paint.slices.top} ${paint.slices.right} ${paint.slices.bottom} ${paint.slices.left} fill`}
+			style:border-image-width={`${paint.widths.top}px ${paint.widths.right}px ${paint.widths.bottom}px ${paint.widths.left}px`}
+		></div>
+	{/if}
 </div>
 
 <style>
@@ -84,21 +142,17 @@
 		overflow: hidden;
 	}
 
-	/* Overdraw cells deliberately extend past the box — don't clip them. */
+	/* Overdraw deliberately extends the paint past the box — don't clip it. */
 	.fundus-slice--overdraw {
 		overflow: visible;
 	}
 
-	.fundus-slice__cell {
-		position: absolute;
-		overflow: hidden;
-	}
-
-	.fundus-slice__cell img {
+	.fundus-slice__paint {
 		position: absolute;
-		max-width: none;
-		max-height: none;
+		box-sizing: border-box;
+		border-width: 0;
+		border-style: solid;
+		border-image-repeat: stretch;
 		pointer-events: none;
-		user-select: none;
 	}
 </style>

package/dist/runtime/components/SliceDom.svelte.d.ts

@@ -1,6 +1,6 @@
-import type { SliceManifestEntry } from '../../core/index.js';
+import type { LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
 interface Props {
-    src: SliceManifestEntry;
+    snapshot: LoadedSliceSnapshot | null;
     /** Accessible label for the rendered graphic. */
     alt?: string;
     class?: string;

package/dist/runtime/slice-source-lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { SliceManifestEntry } from '../core/index.js';
+export interface LoadedSliceSnapshot {
+    entry: SliceManifestEntry;
+    image: HTMLImageElement;
+}
+export type SliceImageLoader = (url: string) => Promise<HTMLImageElement>;
+export declare function loadSliceImage(url: string): Promise<HTMLImageElement>;
+/** Coordinates requested slice entries with the last image-ready snapshot. */
+export declare class SliceSourceLifecycle {
+    #private;
+    constructor(commit: (snapshot: LoadedSliceSnapshot) => void, loadImage?: SliceImageLoader);
+    request(entry: SliceManifestEntry): void;
+    dispose(): void;
+}

package/dist/runtime/slice-source-lifecycle.js

@@ -0,0 +1,70 @@
+export function loadSliceImage(url) {
+    const image = new Image();
+    image.decoding = 'async';
+    image.src = url;
+    return image.decode().then(() => image);
+}
+/** Coordinates requested slice entries with the last image-ready snapshot. */
+export class SliceSourceLifecycle {
+    #loadImage;
+    #commit;
+    #requestedEntry = null;
+    #displayedSnapshot = null;
+    #inFlight = new Map();
+    #disposed = false;
+    constructor(commit, loadImage = loadSliceImage) {
+        this.#commit = commit;
+        this.#loadImage = loadImage;
+    }
+    request(entry) {
+        if (this.#disposed)
+            return;
+        this.#requestedEntry = entry;
+        const displayed = this.#displayedSnapshot;
+        if (displayed?.entry.src === entry.src) {
+            this.#commitSnapshot({ entry, image: displayed.image });
+            return;
+        }
+        if (this.#inFlight.has(entry.src))
+            return;
+        let promise;
+        try {
+            promise = Promise.resolve(this.#loadImage(entry.src));
+        }
+        catch (error) {
+            promise = Promise.reject(error);
+        }
+        const load = { promise };
+        this.#inFlight.set(entry.src, load);
+        void promise.then((image) => this.#settleSuccess(entry.src, load, image), () => this.#settleFailure(entry.src, load));
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#requestedEntry = null;
+        this.#displayedSnapshot = null;
+        this.#inFlight.clear();
+    }
+    #settleSuccess(url, load, image) {
+        if (this.#inFlight.get(url) !== load)
+            return;
+        this.#inFlight.delete(url);
+        if (this.#disposed)
+            return;
+        const requested = this.#requestedEntry;
+        if (!requested || requested.src !== url)
+            return;
+        this.#commitSnapshot({ entry: requested, image });
+    }
+    #settleFailure(url, load) {
+        if (this.#inFlight.get(url) === load)
+            this.#inFlight.delete(url);
+    }
+    #commitSnapshot(snapshot) {
+        if (this.#disposed)
+            return;
+        this.#displayedSnapshot = snapshot;
+        this.#commit(snapshot);
+    }
+}

package/dist/server/check.d.ts

@@ -20,9 +20,15 @@ export interface CheckReport {
     errors: CheckFinding[];
     /** Advisory findings — fatal unless the caller allows warnings. */
     warnings: CheckFinding[];
+    /** Non-fatal integration guidance that never changes the exit status. */
+    advisories: CheckAdvisory[];
     assetCount: number;
     manifestCount: number;
 }
+export interface CheckAdvisory {
+    kind: 'usage-not-configured';
+    message: string;
+}
 export declare function runCheck(projectRoot: string, registry?: ServerPluginRegistry): Promise<CheckReport>;
 /** Pure expansion of a raw classification into canonical hard check findings. */
 export declare function rawCheckFindings(library: Library, raw: RawClassification, registry: ServerPluginRegistry, validationIssues: ValidationIssueDto[]): CheckFinding[];

package/dist/server/check.js

@@ -10,7 +10,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { collectAllReferences, compareCodeUnits, computeLibraryMembership, rawFileNameOfPath, typesForFileName } from '../core/index.js';
-import { loadConfig } from './config-loader.js';
+import { loadConfig, USAGE_NOT_CONFIGURED_MESSAGE } from './config-loader.js';
 import { LibraryStore } from './library-store.js';
 import { classifyRawDirectory } from './raw-reconciliation.js';
 import { buildManifestEntries, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
@@ -28,6 +28,9 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
     const report = {
         errors: [],
         warnings: [],
+        advisories: config.usage === null
+            ? [{ kind: 'usage-not-configured', message: USAGE_NOT_CONFIGURED_MESSAGE }]
+            : [],
         assetCount: Object.keys(library.assets).length,
         manifestCount: Object.keys(library.manifests).length
     };

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

@@ -1,5 +1,7 @@
 export declare const STATE_HELP = "fundus state \u2014 the full project state in one document\n\nUsage: fundus state [--json]\n\nThe agent's one-stop overview: every asset (type, raw file, parameters,\nexplicit + passive manifest memberships, proxy status, reference edges,\nwarnings), every manifest (members, delivered bytes), library-level\nvalidation issues, and the available preset names per asset type.\n\nFlags:\n  --json   print {\"ok\": true, \"state\": <FundusStateDto>} on stdout\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus state --json | jq '.state.assets[].id'\n";
 export declare function runStateCommand(argumentList: string[]): Promise<void>;
+export declare const USAGE_HELP = "fundus usage \u2014 inspect typed source references to assets\n\nUsage: fundus usage [assetId] [--unused] [--json]\n\nWithout an asset id, analyzes every asset and prints its used, unused, or\nunknown status. With an asset id, also returns the concrete source locations,\nmanifest roots, and dependency paths that attribute those usages.\n\nFlags:\n  --unused   only return conclusively unused assets; cannot be combined with an asset id\n  --json     print {\"ok\": true, \"assets\": [<usage record>, \u2026]}\n             Source references omit editor open tokens, which are meaningful\n             only inside the persistent Fundus server process.\n  --help     this help\n\nRead-only: nothing is processed or written. Requires usage.referenceProvider\nand usage.openLocation in fundus.config.ts.\n\nExamples:\n  fundus usage --unused\n  fundus usage navigationPanel --json\n";
+export declare function runUsageCommand(argumentList: string[]): Promise<void>;
 export declare const ASSET_HELP = "fundus asset \u2014 inspect and mutate assets\n\nUsage: fundus asset <subcommand> \u2026\n\nEvery mutation runs the full editor autosave chain: write library \u2192\nprocess affected assets \u2192 regenerate manifest modules. There is no\nseparate apply/sync step. All subcommands accept --json (a single JSON\ndocument on stdout) and --help.\n\nSubcommands:\n  list      list assets (--manifest, --type, --warnings-only)\n  show      one asset in detail\n  ingest    acquire a file or Figma selection as a typed asset\n  reimport  refresh an asset from its saved source\n  replace   replace an asset's raw file while preserving its metadata\n  set       merge parameters and/or replace manifest membership\n  rename    rename an asset id\n  move      move an asset to a folder or root\n  delete    delete an asset (record, raw file, proxies)\n\nRun `fundus asset <subcommand> --help` for the focused page (flags,\nsemantics, an example) \u2014 e.g. `fundus asset set --help` documents the\n--parameters merge rules.\n";
 export declare const ASSET_LIST_HELP: string;
 export declare const ASSET_SHOW_HELP = "fundus asset show \u2014 one asset in detail\n\nUsage: fundus asset show <id> [--json]\n\nPrints the asset's raw file, content hash, parameters, explicit +\npassive manifest memberships, proxy status, reference edges (outgoing\nand incoming), and warnings.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>}\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus asset show navigationPanel --json\n";
@@ -23,5 +25,5 @@ export declare const MANIFEST_PALETTE_HELP = "fundus manifest palette \u2014 lis
 export declare function runManifestCommand(argumentList: string[]): Promise<void>;
 export declare const BUILD_HELP = "fundus build \u2014 run the headless pipeline\n\nUsage: fundus build [--json]\n\nValidates the library, processes every stale or missing proxy, prunes\norphaned proxies, and regenerates all manifest modules. Deterministic\nand idempotent: a second run on an unchanged project processes nothing\nand rewrites byte-identical modules. Run it in CI, postinstall, or\nbefore the host build; commit the result.\n\nFlags:\n  --json   print {\"ok\": true, \"processed\": [\u2026], \"upToDate\": [\u2026],\n           \"prunedProxies\": [\u2026], \"modulesWritten\": [\u2026],\n           \"modulesRemoved\": [\u2026]} \u2014 asset ids for processing,\n           file names for pruning/codegen\n  --help   this help\n\nA validation failure processes nothing and exits 1 (with --json:\n{\"error\": {\"message\": \u2026}}).\n\nExample:\n  fundus build --json | jq '.processed'\n";
 export declare function runBuildCommand(argumentList: string[]): Promise<void>;
-export declare const CHECK_HELP = "fundus check \u2014 verify the committed state (the CI gate)\n\nUsage: fundus check [--allow-warnings] [--json]\n\nVerify-only, no writes: the library must validate, every delivered\nasset's committed proxy must exist under its expected name (staleness\nis a name check), the proxy directory must hold no orphans, and every\ngenerated manifest module must be byte-identical to an in-memory\nregeneration. Warnings (such as unreachable assets) fail the check\nunless --allow-warnings downgrades them. New, missing, edited, or\ninvalid entries in the raw directory are hard errors:\nopen or refocus the Fundus editor and resolve its ingestion queue.\nRaw-file errors never downgrade.\n\nFlags:\n  --allow-warnings   exit 0 despite warnings (errors still fail)\n  --json             print one report document:\n                     {\"ok\": <pass/fail>, \"assetCount\": \u2026, \"manifestCount\": \u2026,\n                      \"errors\": [<finding>, \u2026], \"warnings\": [<finding>, \u2026]}\n                     where a finding is {\"kind\", \"message\"} plus\n                     \"assetId\" / \"manifest\" / \"fileName\" where applicable\n  --help             this help\n\nExit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to\neven run the check (e.g. no fundus.config.ts) exits 1 with the usual\n{\"error\": {\"message\": \u2026}} envelope under --json.\n\nExample:\n  fundus check --json | jq '.errors[].kind'\n";
+export declare const CHECK_HELP = "fundus check \u2014 verify the committed state (the CI gate)\n\nUsage: fundus check [--allow-warnings] [--json]\n\nVerify-only, no writes: the library must validate, every delivered\nasset's committed proxy must exist under its expected name (staleness\nis a name check), the proxy directory must hold no orphans, and every\ngenerated manifest module must be byte-identical to an in-memory\nregeneration. Warnings (such as unreachable assets) fail the check\nunless --allow-warnings downgrades them. New, missing, edited, or\ninvalid entries in the raw directory are hard errors:\nopen or refocus the Fundus editor and resolve its ingestion queue.\nRaw-file errors never downgrade.\n\nFlags:\n  --allow-warnings   exit 0 despite warnings (errors still fail)\n  --json             print one report document:\n                     {\"ok\": <pass/fail>, \"assetCount\": \u2026, \"manifestCount\": \u2026,\n                      \"errors\": [<finding>, \u2026], \"warnings\": [<finding>, \u2026],\n                      \"advisories\": [<non-fatal integration guidance>, \u2026]}\n                     where a finding is {\"kind\", \"message\"} plus\n                     \"assetId\" / \"manifest\" / \"fileName\" where applicable\n  --help             this help\n\nExit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to\neven run the check (e.g. no fundus.config.ts) exits 1 with the usual\n{\"error\": {\"message\": \u2026}} envelope under --json.\n\nExample:\n  fundus check --json | jq '.errors[].kind'\n";
 export declare function runCheckCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-commands.js

@@ -192,6 +192,116 @@ export async function runStateCommand(argumentList) {
     printHumanState(state);
 }
 // ---------------------------------------------------------------------------
+// fundus usage
+// ---------------------------------------------------------------------------
+export const USAGE_HELP = `fundus usage — inspect typed source references to assets
+
+Usage: fundus usage [assetId] [--unused] [--json]
+
+Without an asset id, analyzes every asset and prints its used, unused, or
+unknown status. With an asset id, also returns the concrete source locations,
+manifest roots, and dependency paths that attribute those usages.
+
+Flags:
+  --unused   only return conclusively unused assets; cannot be combined with an asset id
+  --json     print {"ok": true, "assets": [<usage record>, …]}
+             Source references omit editor open tokens, which are meaningful
+             only inside the persistent Fundus server process.
+  --help     this help
+
+Read-only: nothing is processed or written. Requires usage.referenceProvider
+and usage.openLocation in fundus.config.ts.
+
+Examples:
+  fundus usage --unused
+  fundus usage navigationPanel --json
+`;
+function usageReferenceForCli(reference) {
+    return {
+        id: reference.id,
+        file: reference.file,
+        line: reference.line,
+        column: reference.column,
+        ...(reference.label === undefined ? {} : { label: reference.label })
+    };
+}
+function usageAssetForCli(asset) {
+    return {
+        ...asset,
+        references: asset.references.map(usageReferenceForCli)
+    };
+}
+function printHumanUsageOverview(assets, unusedOnly) {
+    if (assets.length === 0) {
+        console.log(unusedOnly ? 'No unused assets.' : 'No assets.');
+        return;
+    }
+    if (unusedOnly) {
+        console.log(`Unused assets (${assets.length}):`);
+    }
+    else {
+        const count = (status) => assets.filter((asset) => asset.status === status).length;
+        console.log(`Asset usage: ${count('used')} used, ${count('unused')} unused, ${count('unknown')} unknown.`);
+    }
+    const idWidth = Math.max(...assets.map((asset) => asset.assetId.length));
+    for (const asset of assets) {
+        console.log(`  ${asset.assetId.padEnd(idWidth)}  ${asset.status}`);
+    }
+}
+function printHumanUsageDetail(asset) {
+    console.log(`${asset.assetId}: ${asset.status}`);
+    if (asset.references.length === 0) {
+        console.log('  code references: none');
+    }
+    else {
+        console.log(`  code references (${asset.references.length}):`);
+        for (const reference of asset.references) {
+            console.log(`    ${reference.file}:${reference.line}:${reference.column}` +
+                (reference.label ? `  ${reference.label}` : ''));
+        }
+    }
+    for (const root of asset.roots) {
+        console.log(`  root: ${root.manifest}.${root.rootAssetId}`);
+        for (const path of root.paths)
+            console.log(`    path: ${path.join(' → ')}`);
+        if (root.additionalPathCount) {
+            console.log(`    +${root.additionalPathCount} additional path(s)`);
+        }
+        if (root.result.status === 'unknown') {
+            console.log(`    unknown: ${root.result.reason ?? 'Usage could not be resolved.'}`);
+        }
+    }
+}
+export async function runUsageCommand(argumentList) {
+    if (hasHelpFlag(argumentList)) {
+        console.log(USAGE_HELP);
+        return;
+    }
+    const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, unused: { takesValue: false } }, 'fundus usage');
+    if (parsed.positionals.length > 1) {
+        throw new CliUsageError('`fundus usage` expects at most one asset id (usage: fundus usage [assetId]) — ' +
+            `got ${parsed.positionals.length}. Run \`fundus usage --help\`.`);
+    }
+    const assetId = parsed.positionals[0];
+    const unusedOnly = parsed.flags.unused === true;
+    if (assetId && unusedOnly) {
+        throw new CliUsageError('Flag "--unused" cannot be combined with an asset id — run `fundus usage --help`.');
+    }
+    const operations = await createOperations();
+    const report = await operations.analyzeUsage(assetId ? { assetId } : {});
+    const assets = unusedOnly
+        ? report.assets.filter((asset) => asset.status === 'unused')
+        : report.assets;
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, assets: assets.map(usageAssetForCli) });
+        return;
+    }
+    if (assetId)
+        printHumanUsageDetail(assets[0]);
+    else
+        printHumanUsageOverview(assets, unusedOnly);
+}
+// ---------------------------------------------------------------------------
 // fundus asset …
 // ---------------------------------------------------------------------------
 export const ASSET_HELP = `fundus asset — inspect and mutate assets
@@ -1402,7 +1512,8 @@ Flags:
   --allow-warnings   exit 0 despite warnings (errors still fail)
   --json             print one report document:
                      {"ok": <pass/fail>, "assetCount": …, "manifestCount": …,
-                      "errors": [<finding>, …], "warnings": [<finding>, …]}
+                      "errors": [<finding>, …], "warnings": [<finding>, …],
+                      "advisories": [<non-fatal integration guidance>, …]}
                      where a finding is {"kind", "message"} plus
                      "assetId" / "manifest" / "fileName" where applicable
   --help             this help
@@ -1431,7 +1542,8 @@ export async function runCheckCommand(argumentList) {
             assetCount: report.assetCount,
             manifestCount: report.manifestCount,
             errors: report.errors,
-            warnings: report.warnings
+            warnings: report.warnings,
+            advisories: report.advisories
         });
         if (failed)
             process.exitCode = 1;
@@ -1443,6 +1555,9 @@ export async function runCheckCommand(argumentList) {
     for (const warning of report.warnings) {
         console.error(`⚠ ${formatCheckFinding(warning)}`);
     }
+    for (const advisory of report.advisories) {
+        console.error(`ℹ ${advisory.message}`);
+    }
     if (failed) {
         console.error(`fundus check failed: ${report.errors.length} error(s), ${report.warnings.length} warning(s)` +
             (warningsFatal ? ' (warnings are errors — pass --allow-warnings to downgrade them)' : '') +

package/dist/server/codegen.d.ts

@@ -1,8 +1,11 @@
 import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ReferencesByAsset } 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';
 import type { AssetProxyInfo } from './processing/processor.js';
 export declare const GENERATED_HEADER = "// generated by fundus \u2014 do not edit\n";
+/** Locate a generated top-level manifest member in frozen module source. */
+export declare function locateGeneratedAssetDeclaration(file: string, source: string, assetId: string): SourceLocation | null;
 /** `mainCatalog` → `main-catalog`. */
 export declare function kebabCaseFromCamel(name: string): string;
 /** Generated module file name for a manifest. */