From 6b6a0569c1e717008fc1961f8494349fdce613a5 Mon Sep 17 00:00:00 2001
From: Alex Hunt <huntie@meta.com>
Date: Wed, 17 Jun 2026 04:58:37 -0700
Subject: [PATCH] Document assets-registry package, add TS definitions (#57231)

Summary:

Quality pass on the `assets-registry` package ahead of the next diff.

- Add user-facing notes to package README.
- Add adjacent `.d.ts` definitions (manually/AI-maintained is fine at this scale).

Changelog: [Internal]

Differential Revision: D108624321
---
 packages/assets-registry/README.md         | 29 +++++++++++++---------
 packages/assets-registry/package.json      |  7 +++---
 packages/assets-registry/path-support.d.ts | 19 ++++++++++++++
 packages/assets-registry/registry.d.ts     | 27 ++++++++++++++++++++
 4 files changed, 66 insertions(+), 16 deletions(-)
 create mode 100644 packages/assets-registry/path-support.d.ts
 create mode 100644 packages/assets-registry/registry.d.ts

diff --git a/packages/assets-registry/README.md b/packages/assets-registry/README.md
index 51f229af163b..b1f095860994 100644
--- a/packages/assets-registry/README.md
+++ b/packages/assets-registry/README.md
@@ -1,21 +1,26 @@
 # @react-native/assets-registry
 
-[![Version][version-badge]][package]
+![npm package](https://img.shields.io/npm/v/@react-native/assets-registry?color=brightgreen&label=npm%20package)
 
-## Installation
+Runtime registry that maps asset IDs generated in a Metro bundle to asset metadata. It backs `<Image>`, `Image.resolveAssetSource()`, and any code that resolves `require('./img.png')` on native.
 
-```
-yarn add --dev @react-native/assets-registry
-```
+Most apps never import this directly — assets are handled through `<Image>`.
 
-*Note: We're using `yarn` to install deps. Feel free to change commands to use `npm` 3+ and `npx` if you like*
+## API
 
-[version-badge]: https://img.shields.io/npm/v/@react-native/assets-registry?style=flat-square
-[package]: https://www.npmjs.com/package/@react-native/assets-registry
+### `@react-native/assets-registry/registry`
 
-## Testing
+| Export | Signature | Notes |
+|---|---|---|
+| `registerAsset` | `(asset: PackagerAsset) => number` | Stores the asset; returns a numeric ID |
+| `getAssetByID` | `(assetId: number) => PackagerAsset` | Looks an asset back up by ID |
 
-To run the tests in this package, run the following commands from the React Native root folder:
+### `@react-native/assets-registry/path-support`
 
-1. `yarn` to install the dependencies. You just need to run this once
-2. `yarn jest packages/assets-registry`.
+Android resource-path helpers, used when copying assets into `drawable-*` folders.
+
+| Export | Signature | Notes |
+|---|---|---|
+| `getAndroidResourceFolderName` | `(asset: PackagerAsset, scale: number) => string` | e.g. `drawable-xhdpi`; non-drawable types resolve to `raw` |
+| `getAndroidResourceIdentifier` | `(asset: PackagerAsset) => string` | Sanitised resource name |
+| `getBasePath` | `(asset: PackagerAsset) => string` | `httpServerLocation` without the leading slash |
diff --git a/packages/assets-registry/package.json b/packages/assets-registry/package.json
index e7208814e309..2dfc7ba94009 100644
--- a/packages/assets-registry/package.json
+++ b/packages/assets-registry/package.json
@@ -10,10 +10,7 @@
   },
   "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/assets-registry#readme",
   "keywords": [
-    "assets",
-    "registry",
-    "react-native",
-    "support"
+    "react-native"
   ],
   "bugs": "https://github.com/facebook/react-native/issues",
   "engines": {
@@ -21,7 +18,9 @@
   },
   "files": [
     "path-support.js",
+    "path-support.d.ts",
     "registry.js",
+    "registry.d.ts",
     "README.md",
     "!**/__docs__/**",
     "!**/__fixtures__/**",
diff --git a/packages/assets-registry/path-support.d.ts b/packages/assets-registry/path-support.d.ts
new file mode 100644
index 000000000000..abdea750aacd
--- /dev/null
+++ b/packages/assets-registry/path-support.d.ts
@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import type {PackagerAsset} from './registry';
+
+export function getAndroidResourceFolderName(
+  asset: PackagerAsset,
+  scale: number,
+): string;
+
+export function getAndroidResourceIdentifier(asset: PackagerAsset): string;
+
+export function getBasePath(asset: PackagerAsset): string;
diff --git a/packages/assets-registry/registry.d.ts b/packages/assets-registry/registry.d.ts
new file mode 100644
index 000000000000..7509ef9ba13e
--- /dev/null
+++ b/packages/assets-registry/registry.d.ts
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+export type AssetDestPathResolver = 'android' | 'generic';
+
+export type PackagerAsset = {
+  readonly __packager_asset: boolean;
+  readonly fileSystemLocation: string;
+  readonly httpServerLocation: string;
+  readonly width: number | null | undefined;
+  readonly height: number | null | undefined;
+  readonly scales: Array<number>;
+  readonly hash: string;
+  readonly name: string;
+  readonly type: string;
+  readonly resolver?: AssetDestPathResolver | undefined;
+};
+
+export function registerAsset(asset: PackagerAsset): number;
+
+export function getAssetByID(assetId: number): PackagerAsset;