@unbound-app/api 2.1.0 → 3.0.0

package/src/metro/index.d.ts

@@ -205,7 +205,7 @@ export declare function filter<A extends FilterArgument[]>(
  * @description Finds a module matching a filter. Lazy unless `{ lazy: false }` is passed, or `all` is set: the search runs on first access.
  * @param filter The filter to match modules against: a built-in, a combination, or a predicate you write, which the build keys for the cache.
  * @param options Search options controlling interop, caching, esModule unwrapping, and `all`.
- * @returns The matched module, an array of matches when `all` is set, or `null`.
+ * @returns The matched module, an array of matches when `all` is set, `undefined` when the cache knows it is missing, or `null`.
  */
 export declare function find(filter: MetroFilter, options?: MetroSearchOptions): any;
 /**
@@ -249,10 +249,10 @@ export declare function findByName<T extends MetroLookupArgs<string>>(
 export declare function findByProps<
 	K extends MetroLookupFirst<MetroPropName>,
 	T extends MetroLookupArgs<string>,
->(first: K, ...rest: T): MetroPropertyRecordOrArray<[K, ...T], string> & {};
+>(first: K, ...rest: T): MetroPropertyRecordOrArray<[K, ...T], string>;
 export declare function findByProps<T extends MetroLookupArgs<string>>(
 	...args: T
-): MetroPropertyRecordOrArray<T, string> & {};
+): MetroPropertyRecordOrArray<T, string>;
 /**
  * @description Finds a module whose prototype exposes all of the given method names. Lazy unless `{ lazy: false }` is passed: the search runs on first access.
  * @template U The union of requested prototype method names.
@@ -302,16 +302,16 @@ export declare function onModuleLoad(listener: MetroModuleLoadListener): () => v
 /**
  * @description Calls `onLoad` with the module matching `filter` once it initializes, without ever initializing it.
  * A loaded module is passed at once; otherwise `onLoad` runs inside the module's factory, before its importer reads it.
- * A module a full search of this Discord build found missing never loads, so `onLoad` never runs for it.
+ * A module a full search of this Discord build found missing never loads, so `onLoad` never runs for it; `onMissing` runs instead.
  * @param filter The filter to match against.
  * @param onLoad Receives the matched module, once.
- * @param options Whether to also match the `default` export (`esModules`) and return it on such a match (`interop`).
+ * @param waitOptions Whether to also match the `default` export (`esModules`) and return it on such a match (`interop`), and `onMissing`.
  * @returns A function that stops waiting; it does nothing once `onLoad` has run.
  */
 export declare function onModuleLoaded(
 	filter: MetroFilter,
 	onLoad: (mdl: MetroExport) => void,
-	options?: MetroModuleLoadedOptions,
+	waitOptions?: MetroWaitOptions,
 ): () => void;
 export type AlertActionsComponent = React$1.ComponentType<AlertActionsProps>;
 /** An object of shape `T` widened with an arbitrary property index. */
@@ -26006,12 +26006,12 @@ export type KeysExposingAll<K> = (
 	? Keys
 	: never;
 export type LoadingButtonPillComponent = React$1.ComponentType<LoadingButtonPillProps>;
-/** Widens a single result to an array when the search was made with `all: true`. */
+/** Widens a single result to an array when the search was made with `all: true`; a single one is `undefined` when the cache knows it is missing. */
 export type MetroAllValues<T extends MetroSearchOptions, U> = T extends {
 	all: true;
 }
 	? U[]
-	: U;
+	: U | undefined;
 /** Tuple of param bags followed by a `{ bulk: true }` marker, describing a bulk find. */
 export type MetroBulkFind<T extends string> = [
 	...AnyProps<MetroParamsBag<T>>[],
@@ -26048,7 +26048,7 @@ export type MetroFilter = ((mdl: any, id: number | string) => PredicateResult) &
 };
 /** A function or class exported by a Discord module, whose signature Discord does not document. */
 export type MetroFunction = DiscordFunction & (new (...args: any[]) => any);
-/** Dispatches to the bulk or single by-name result shape based on the argument tuple. */
+/** Dispatches to the bulk or single by-name result shape. */
 export type MetroFunctionSignatureOrArray<T extends any[], U extends string> =
 	T extends MetroBulkFind<U> ? MetroBulkModuleByName<T> : MetroSingleModuleByName<T>;
 /** Options that control internal search behaviour shared across every `findBy*` helper. */
@@ -26102,7 +26102,7 @@ export type MetroModuleLoadListener = (mdl: any, id: number) => void;
 export type MetroModuleLoadedOptions = Pick<MetroSearchOptions, 'esModules' | 'interop'>;
 /** A name `findByName` takes: a default export's runtime name, or any other string. */
 export type MetroModuleName = LiteralUnion<Extract<keyof DiscordModulesByName, string>>;
-/** Dispatches to the bulk or single by-path result shape based on the argument tuple. */
+/** Dispatches to the bulk or single by-path result shape. */
 export type MetroModuleOrArray<T extends any[], U extends string> =
 	T extends MetroBulkFind<U> ? AnyProps : MetroSingleModuleByPath<T>;
 /** A source path `findByFilePath` takes: a Discord module's path, or any other string. */
@@ -26130,9 +26130,7 @@ export type MetroParamsBag<T extends string> = {
 };
 /** A prop name `findByProps` takes: an export name of a Discord module, or any other string. */
 export type MetroPropName = LiteralUnion<DiscordExportName>;
-/**
- * Dispatches to the bulk or single by-property result shape based on the argument tuple.
- */
+/** Dispatches to the bulk or single by-property result shape. */
 export type MetroPropertyRecordOrArray<T extends any[], U extends string> =
 	T extends MetroBulkFind<U> ? MetroBulkModuleByProperty<T> : MetroSingleModuleByProperty<T>;
 /** A record keyed by the requested prop names. */
@@ -26175,21 +26173,21 @@ export type MetroSingleModuleByName<T extends any[]> = T extends [
 					}
 				: MetroNamedExport<Exclude<T[number], object>>
 		>
-	: MetroNamedExport<Exclude<T[number], object>>;
+	: MetroNamedExport<Exclude<T[number], object>> | undefined;
 /** Result shape of a by-path search: the module's exports. */
 export type MetroSingleModuleByPath<T extends any[]> = T extends [
 	...any,
 	infer O extends MetroSearchOptions,
 ]
 	? MetroAllValues<O, MetroModuleAtPath<Exclude<T[number], object>>>
-	: MetroModuleAtPath<Exclude<T[number], object>>;
+	: MetroModuleAtPath<Exclude<T[number], object>> | undefined;
 /** Result shape of a by-property search: a record keyed by the requested props. */
 export type MetroSingleModuleByProperty<T extends any[]> = T extends [
 	...any,
 	infer O extends MetroSearchOptions,
 ]
 	? MetroAllValues<O, MetroModuleWithProps<Exclude<T[number], object>>>
-	: MetroModuleWithProps<Exclude<T[number], object>>;
+	: MetroModuleWithProps<Exclude<T[number], object>> | undefined;
 /** Search options for `flux.getStore`, adding the `short` name-matching toggle. */
 export type MetroStoreOptions = {
 	short?: boolean;
@@ -26199,6 +26197,10 @@ export type MetroStringFindWithOptions<T extends string, Options = MetroSearchOp
 	...T[],
 	Options,
 ];
+/** Options for {@link onModuleLoaded}'s wait, adding `onMissing`, run at once instead of waiting when the cache knows the module is missing. */
+export type MetroWaitOptions = MetroModuleLoadedOptions & {
+	onMissing?: () => void;
+};
 /** `T`, or `Fallback` when `T` is `never`. */
 export type Otherwise<T, Fallback> = [T] extends [never] ? Fallback : T;
 export type PressableHighlightComponent = React$1.ComponentType<

package/src/native.d.ts

@@ -4,6 +4,12 @@ export type {
 	NativeAssociationKey,
 	NativeBatchReference,
 	NativeBatchStep,
+	NativeBridge,
+	NativeBridgeCapability,
+	NativeBridgeError,
+	NativeBridgeErrorCode,
+	NativeBridgeMethod,
+	NativeBridgePlatform,
 	NativeCallOptions,
 	NativeCancelablePromise,
 	NativeClassHandle,
@@ -14,6 +20,7 @@ export type {
 	NativeFFISignature,
 	NativeFFIType,
 	NativeFFITypeName,
+	NativeFabricBatchMutation,
 	NativeFabricBridge,
 	NativeFabricFrame,
 	NativeFabricMountOptions,
@@ -45,11 +52,6 @@ export type {
 	NativeObjCCallPlan,
 	NativeObjectHandle,
 	NativePlatformBridge,
-	NativePluginBridge,
-	NativePluginCapability,
-	NativePluginError,
-	NativePluginErrorCode,
-	NativePluginPlatform,
 	NativePointer,
 	NativeRuntimeBridge,
 	NativeRuntimeEventName,
@@ -67,9 +69,10 @@ export type {
 	PluginContext,
 } from './_internal';
 import type {
+	NativeBridgeCapability,
+	NativeBridgeMethod,
+	NativeBridgePlatform,
 	NativePlatformBridge,
-	NativePluginCapability,
-	NativePluginPlatform,
 	NativeResourceCounts,
 } from './_internal';
 import * as React$1 from 'react';
@@ -78,39 +81,39 @@ import { ComponentType } from 'react';
 declare const NativePlatform$1: NativePlatformBridge | undefined;
 
 /** Thrown when a plugin uses a Capability its manifest does not declare, or declares one that is unknown or the native bridge lacks. */
-export declare class NativePluginCapabilityError extends Error {
+export declare class NativeBridgeCapabilityError extends Error {
 	/** A stable code to match on instead of the message. */
 	readonly code = 'NATIVE_PLUGIN_CAPABILITY_DENIED';
 	/** The Capability that was missing or refused. */
-	readonly capability: NativePluginCapability;
-	constructor(capability: NativePluginCapability);
+	readonly capability: NativeBridgeCapability;
+	constructor(capability: NativeBridgeCapability);
 }
 /** Thrown when native work is called through a plugin's scope after the scope was disposed, such as after the plugin stopped. */
-export declare class NativePluginDisposedError extends Error {
+export declare class NativeBridgeDisposedError extends Error {
 	/** A stable code to match on instead of the message. */
 	readonly code = 'NATIVE_PLUGIN_SCOPE_DISPOSED';
 	constructor();
 }
-/** Thrown when the loader does not provide the native plugin bridge, or the part of it a call needs. */
-export declare class NativePluginUnavailableError extends Error {
+/** Thrown when the loader does not provide the native bridge, or the part of it a call needs. */
+export declare class NativeBridgeUnavailableError extends Error {
 	/** A stable code to match on instead of the message. */
 	readonly code = 'NATIVE_PLUGIN_UNAVAILABLE';
 }
 /** Thrown when the host platform is not one the addon runs on, by its manifest or the handlers given to `definePlatform`. */
-export declare class NativePluginUnsupportedPlatformError extends Error {
+export declare class NativeBridgeUnsupportedPlatformError extends Error {
 	/** A stable code to match on instead of the message. */
 	readonly code = 'NATIVE_PLUGIN_PLATFORM_EXCLUDED';
 	/** The platforms the addon does run on. */
-	readonly platforms: readonly NativePluginPlatform[];
-	constructor(platforms: readonly NativePluginPlatform[], platform: string);
+	readonly platforms: readonly NativeBridgePlatform[];
+	constructor(platforms: readonly NativeBridgePlatform[], platform: string);
 }
-/** Thrown when the native plugin API is older than the manifest's `minNativePluginApi`. */
-export declare class NativePluginVersionError extends Error {
+/** Thrown when the native bridge API is older than the manifest's `minNativeBridgeApi`. */
+export declare class NativeBridgeVersionError extends Error {
 	/** A stable code to match on instead of the message. */
 	readonly code = 'NATIVE_PLUGIN_API_VERSION_UNSUPPORTED';
-	/** The native plugin API version the loader provides. */
+	/** The native bridge API version the loader provides. */
 	readonly installedApi: string;
-	/** The manifest's `minNativePluginApi`. */
+	/** The manifest's `minNativeBridgeApi`. */
 	readonly requiredApi: string;
 	constructor(requiredApi: string, installedApi: string);
 }
@@ -150,11 +153,17 @@ export declare function getRuntimeProperties(): HermesRuntimeProperties;
  * @param capability The capability to look for.
  * @returns Whether the bridge provides it.
  */
-export declare function has(capability: NativePluginCapability): boolean;
+export declare function has(capability: NativeBridgeCapability): boolean;
 /**
  * @description Persists pending settings to storage, then reloads the native bundle.
  */
 export declare function reload(): Promise<void>;
+/**
+ * @description Checks whether the loader on this device implements a bridge method, for methods newer than the capability that gates them.
+ * @param method The method's path, such as `fabric.batchAsync`.
+ * @returns Whether the loader implements it.
+ */
+export declare function supports(method: NativeBridgeMethod): boolean;
 /** Build and release metadata reported by the native client info module. */
 export type BundleInfoType = {
 	/** Discord's app version, shown in Unbound's settings beside `Build`. */
@@ -257,7 +266,7 @@ export type DeviceInfoType = {
 /** What `HermesInternal.getRuntimeProperties()` reports; empty when the engine is not Hermes. */
 export type HermesRuntimeProperties = ReturnType<HermesInternalObject['getRuntimeProperties']>;
 /** One Platform handler per platform an addon runs on. */
-export type PlatformHandlers<Handler> = Partial<Record<NativePluginPlatform, Handler>>;
+export type PlatformHandlers<Handler> = Partial<Record<NativeBridgePlatform, Handler>>;
 /** A native method Discord exposes without documenting what its promise resolves to. */
 export type UndocumentedNativeMethod = () => Promise<unknown>;
 export { NativePlatform$1 as NativePlatform };

package/src/plugins.d.ts

@@ -1,14 +1,14 @@
 // Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
 
-import type { AddonHandle, PushedManifest } from './_internal';
+import type { AddonHandle, PluginSelfTestResult, PushedManifest } from './_internal';
 /** Stops a running plugin without changing its enabled state. */
 declare const stop$1: (id: string) => void | Promise<void>;
+/** Every installed plugin, keyed by id. */
+export declare const addons: ReadonlyMap<PropertyKey, AddonHandle>;
 /** Disables a plugin and stops it. */
 export declare const disable: (id: string) => void;
 /** Enables a plugin and starts it. */
 export declare const enable: (id: string) => void | Promise<void>;
-/** Every installed plugin, keyed by id. */
-export declare const entities: ReadonlyMap<PropertyKey, AddonHandle>;
 /** The error each plugin that failed to load or start threw, keyed by id. */
 export declare const errors: ReadonlyMap<PropertyKey, Error>;
 /** Reads one installed plugin by id. */
@@ -34,6 +34,12 @@ export declare const startDurations: ReadonlyMap<string, number>;
 export declare const toggle: (id: string) => void;
 /** Stops and removes an installed plugin. */
 export declare const uninstall: (id: string) => Promise<void>;
+/**
+ * @description Runs a running plugin's self-test, as the device matrix does after restarting it.
+ * @param id The plugin's id.
+ * @returns Its report, or `undefined` when it is not running or has no self-test; rejects with what the self-test threw.
+ */
+export declare function selfTest(id: string): Promise<PluginSelfTestResult | undefined>;
 /**
  * @description Checks for updates, then applies this plugin's pending update.
  * @param id The plugin's id.

package/src/storage.d.ts

@@ -39,7 +39,11 @@ export declare function persist(): Promise<void>;
  * @param options Set `includeSecrets` to read `displayAs: 'secret'` settings as they are; otherwise they are masked.
  * @returns Every Bucket by name.
  */
-export declare function snapshot({ includeSecrets }?: { includeSecrets?: boolean }): SettingsStores;
+export declare function snapshot({
+	includeSecrets,
+}?: {
+	includeSecrets?: boolean;
+}): SettingsByBucket;
 /**
  * @description React hook that re-renders the component whenever a matching change occurs in the Bucket.
  * @param name The Bucket to subscribe to.
@@ -90,6 +94,8 @@ export type DefinedSettings = {
 	/** React hook that re-renders on any change to the settings while `enabled`, and returns a number that changes with them. */
 	useVersion: (enabled?: boolean) => number;
 };
+/** Every Bucket's settings, keyed by Bucket name, as the loader persists them. */
+export type SettingsByBucket = Record<string, SettingsObject>;
 /** Payload describing a settings change, passed to `onChange` listeners and predicates. */
 export type SettingsPayload = {
 	/** The name of the Bucket that changed. */
@@ -101,8 +107,6 @@ export type SettingsPayload = {
 };
 /** Decides whether a settings change should reach a listener. */
 export type SettingsPredicate = (payload: SettingsPayload) => PredicateResult;
-/** Every Bucket's settings, keyed by Bucket name, as the loader persists them. */
-export type SettingsStores = Record<string, SettingsObject>;
 /** A plugin's settings as an object: reads apply defaults, writes are validated and saved. Sections are nested objects. */
 export type SettingsValues = {
 	[key: string]: SettingValue | SettingsValues;

package/src/sync.d.ts

@@ -1,7 +1,7 @@
 // Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
 
-/** The settings store Sync keeps its mode and last agreed document in. Never synced. */
-export declare const SYNC_STORE = 'unbound::sync';
+/** The Bucket Sync keeps its mode and last agreed document in. Never synced. */
+export declare const SYNC_BUCKET = 'unbound::sync';
 /**
  * @description Deletes the stored document and turns syncing off on this device, so it is not
  * uploaded again. Other devices keep what they have installed.
@@ -20,7 +20,7 @@ export declare function isEnabled(): boolean;
  * @description Syncs now: reads the stored document, merges, applies remote changes here and saves
  * the result. A call while a sync runs queues one more run after it, in this device's mode.
  * @param strategy How to reconcile the two sides; this device's mode by default.
- * @returns Whether the sync succeeded. Failures are recorded as `lastError` in {@link SYNC_STORE}.
+ * @returns Whether the sync succeeded. Failures are recorded as `lastError` in {@link SYNC_BUCKET}.
  */
 export declare function now(strategy?: SyncStrategy): Promise<boolean>;
 /**

package/testing/fake-feedback.ts

@@ -2,7 +2,7 @@ import type { AlertDialogProps, DialogHandle } from '../src/dialogs';
 import type { ToastHandle, ToastOptions } from '../src/toasts';
 import type { IcuVars } from './icu-format';
 
-import { parseIcu } from './icu-parse';
+import { parseIcu } from '../src/_conventions/icu-parse';
 
 /** How the fakes resolve a plugin's message keys, as the client's scoped `resolveMessage` does. */
 export type FakeMessageLookup = {

package/testing/fake-locales.ts

@@ -1,13 +1,11 @@
 import { useSyncExternalStore } from 'react';
 
+import { SOURCE_LOCALE } from '../src/_conventions/addon-locales';
 import { formatIcu, type IcuVars } from './icu-format';
 
 /** One locale's messages, keyed by message key, as a plugin's `i18n/<code>.json` holds them. */
 export type LocaleTable = Record<string, string>;
 
-/** The locale every plugin ships, and the one its messages fall back to. */
-export const SOURCE_LOCALE = 'en-US';
-
 /** The fake `@unbound-app/i18n`, over a plugin's real tables, and the locale a test switches with `setLocale`. */
 export type FakeLocales = {
 	/** Each message in the active locale, falling back to en-US, then the key itself. */

package/testing/fake-metro.ts

@@ -2,14 +2,19 @@ import * as React from 'react';
 
 import type { AnyObject } from '../src/patcher';
 
+import {
+	API_PROPS as CLIENT_API_PROPS,
+	COMMON_PROPS,
+	LAZY_MARKER,
+} from '../src/_conventions/metro';
 import { createFakeReactNative } from './fake-react-native';
 import { createFakeComponents } from './fake-components';
 
 /** A module the fake metro serves: the exports a plugin finds. */
 export type FakeModule = AnyObject;
 
-/** A fake metro filter. `path` marks a file-path filter, which matches the path a module was registered under. */
-export type FakeFilter = ((module: FakeModule) => boolean) & { path?: string };
+/** A fake metro filter. `path` marks a file-path filter, which matches the path a module was registered under; `terms` are the props, path or name it searches by. */
+export type FakeFilter = ((module: FakeModule) => boolean) & { path?: string; terms?: string[] };
 
 type LazyOptions = {
 	signal?: AbortSignal;
@@ -24,40 +29,8 @@ type FindAll = { all: true };
 
 type Presence = 'loaded' | 'missing';
 
-const LAZY_MARKER = '__METRO_LAZY__';
-
-// The props each `metro.common` member is found by, as in the client's metro/common.ts.
-const COMMON_PROPS = {
-	Reanimated: ['useAnimatedStyle', 'useSharedValue'],
-	Gestures: ['PanGestureHandler'],
-	Clipboard: ['setString', 'getString', 'setImage', 'getImage'],
-	MarkdownParser: ['parse', 'parseToAST', 'reactParserFor'],
-	Screens: ['FullWindowOverlay'],
-	SVG: ['Svg', 'Path'],
-	Commands: ['getBuiltInCommands'],
-	Moment: ['isMoment'],
-	Util: ['inspect'],
-	Assets: ['registerAsset'],
-	ImageSources: ['getImageSourcesFromImageProps'],
-	Clyde: ['createBotMessage'],
-	Constants: ['Fonts', 'Endpoints'],
-	Radius: ['Radius'],
-	Theme: ['colors', 'internal'],
-	REST: ['getAPIBaseURL'],
-	i18n: ['getLanguages', 'getSystemLocale', 'intl'],
-};
-
-// The props each `metro.api` member is found by, as in the client's metro/api.ts.
-const API_PROPS = {
-	Messages: ['sendMessage', 'receiveMessage'],
-	Linking: ['openURL', 'openSettings'],
-	Profiles: ['showUserProfile'],
-	AsyncUsers: ['fetchProfile'],
-	Invites: ['acceptInviteAndTransitionToInviteChannel'],
-	OAuth2: ['openOAuth2Modal'],
-	ActionSheets: ['openLazy', 'hideActionSheet'],
-	UserProfiles: ['getUserProfileActionSheetKey', 'showUserProfileActionSheetPostConnection'],
-};
+// On device `metro.api.Linking` is React Native's; here a test registers a module with its methods.
+const API_PROPS = { ...CLIENT_API_PROPS, Linking: ['openURL', 'openSettings'] };
 
 /** What a lazy handle looks its module up by. */
 type LazyLookup = {
@@ -70,12 +43,16 @@ type Wait = {
 	onLoad: (module: FakeModule) => void;
 };
 
+type WaitOptions = { onMissing?: () => void };
+
 /** A metro over modules a test registers, with the finders and filters plugins call. */
 export type FakeMetro = {
 	/** Adds a module, settling any `findLazy` or `onModuleLoaded` waiting for it and calling `onModuleLoad` listeners. */
 	register: (module: FakeModule, path?: string) => void;
-	/** Forgets every registered module and waiting `findLazy` or `onModuleLoaded`, so a lazy handle made earlier finds only what is registered next. */
+	/** Forgets every registered module, missing mark and waiting `findLazy` or `onModuleLoaded`, so a lazy handle made earlier finds only what is registered next. */
 	reset: () => void;
+	/** Marks a prop name, file path or export name as missing from this build, as the device's cache knows after a full search: a lazy lookup by it returns `undefined`, and `onModuleLoaded` calls `onMissing`. */
+	markMissing: (term: string) => void;
 	/** Discord's Flux stores, by the name `metro.stores` gives them, such as `Users`; the preset binds each to the seeded store. */
 	stores: Record<string, FakeModule>;
 	/** Discord's components: each module a bag of fake components that draw their children and are found by name, such as `Discord.Text`. */
@@ -112,7 +89,11 @@ export type FakeMetro = {
 		filter: FakeFilter,
 		options?: LazyOptions,
 	) => FakeModule | Promise<FakeModule | undefined>;
-	onModuleLoaded: (filter: FakeFilter, onLoad: (module: FakeModule) => void) => () => void;
+	onModuleLoaded: (
+		filter: FakeFilter,
+		onLoad: (module: FakeModule) => void,
+		options?: WaitOptions,
+	) => () => void;
 	/** Calls `onLoad` with the module a lazy handle finds, at once when one is registered, else when it registers; a plain object is passed at once. Returns what stops waiting. */
 	whenLoaded: (target: FakeModule, onLoad: (module: FakeModule) => void) => () => void;
 	onModuleLoad: (listener: (module: FakeModule) => void) => () => void;
@@ -178,17 +159,28 @@ export function createFakeMetro(): FakeMetro {
 	const paths = new Map<FakeModule, string>();
 	const waits = new Set<Wait>();
 	const listeners = new Set<(module: FakeModule) => void>();
+	const missing = new Set<string>();
+
+	function isMissing(filter: FakeFilter): boolean {
+		return Boolean(filter.terms?.some((term) => missing.has(term)));
+	}
 
 	const filters: FakeMetro['filters'] = {
-		byProps:
-			(...props) =>
-			(module) =>
-				props.every((prop) => prop in module),
-		byName: (name) => (module) => 'name' in module && module.name === name,
+		byProps: (...props) =>
+			Object.assign((module: FakeModule) => props.every((prop) => prop in module), {
+				terms: props,
+			}),
+		byName: (name) =>
+			Object.assign((module: FakeModule) => 'name' in module && module.name === name, {
+				terms: [name],
+			}),
 		byDisplayName: (name) => (module) => module.displayName === name,
 		byTypeName: (name) => (module) => module.type?.name === name,
 		byFilePath: (path) =>
-			Object.assign((module: FakeModule) => paths.get(module) === path, { path }),
+			Object.assign((module: FakeModule) => paths.get(module) === path, {
+				path,
+				terms: [path],
+			}),
 		all: (...parts) => {
 			for (const part of parts) assertCombinable('all', part);
 
@@ -227,6 +219,8 @@ export function createFakeMetro(): FakeMetro {
 			return first(filter);
 		}
 
+		if (isMissing(filter)) return;
+
 		const resolve = () => first(filter);
 		const handle = lazyHandle(resolve, description);
 
@@ -244,7 +238,17 @@ export function createFakeMetro(): FakeMetro {
 		) as Record<keyof T, FakeModule>;
 	}
 
-	function onModuleLoaded(filter: FakeFilter, onLoad: (module: FakeModule) => void) {
+	function onModuleLoaded(
+		filter: FakeFilter,
+		onLoad: (module: FakeModule) => void,
+		{ onMissing }: WaitOptions = {},
+	) {
+		if (isMissing(filter)) {
+			onMissing?.();
+
+			return () => void 0;
+		}
+
 		const found = first(filter);
 
 		if (found) {
@@ -325,6 +329,10 @@ export function createFakeMetro(): FakeMetro {
 			paths.clear();
 			waits.clear();
 			listeners.clear();
+			missing.clear();
+		},
+		markMissing(term) {
+			missing.add(term);
 		},
 		register(module, path) {
 			modules.push(module);