Document assets-registry package, add TS definitions (#57231)

Summary:
Pull Request resolved: #57231

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]

Reviewed By: cortinico

Differential Revision: D108624321

fbshipit-source-id: 237dfd6f37183f03109dc32ac2ca9b0f0e939961

Author: huntie

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 |

packages/assets-registry/package.json

@@ -10,18 +10,17 @@
   },
   "homepage": "https://github.com/react/react-native/tree/HEAD/packages/assets-registry#readme",
   "keywords": [
-    "assets",
-    "registry",
-    "react-native",
-    "support"
+    "react-native"
   ],
   "bugs": "https://github.com/react/react-native/issues",
   "engines": {
     "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
   },
   "files": [
     "path-support.js",
+    "path-support.d.ts",
     "registry.js",
+    "registry.d.ts",
     "README.md",
     "!**/__docs__/**",
     "!**/__fixtures__/**",

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;

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;