Initial Commit

packages/foundation/data/packer-browser/src/manager/manager-helpers.md

@@ -0,0 +1,67 @@
+# manager-helpers
+
+## Purpose
+
+Small free helpers extracted from `manager.ts` to keep the class file
+under CLAUDE.md §3's 300-line hard cap. Both helpers (`deriveCacheKey`
+and `checkAbortedSignal`) are exercised through the manager's tests;
+they have no state and can be reused by any future internal collaborator
+that needs the same primitives.
+
+## Features
+
+- `deriveCacheKey(url, verifyKey?)` — stable cache key derivation that
+  appends the first 8 bytes (hex) of the verify-key as a suffix so
+  two loads against the same URL with different verify-keys live in
+  separate cache slots.
+- `checkAbortedSignal(signal, resolver, key?)` — throw
+  `PackerBrowserError(ABORTED)` when the supplied signal is already
+  aborted; tolerates `undefined` for both `signal` and `resolver` so
+  it works at every call site.
+
+## Usage: Basic Example
+
+```ts
+import { checkAbortedSignal, deriveCacheKey } from "./manager-helpers.js";
+
+const key = deriveCacheKey("/asset.packed");
+const keyed = deriveCacheKey("/asset.packed", new Uint8Array(64));
+checkAbortedSignal(new AbortController().signal, undefined);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { checkAbortedSignal, deriveCacheKey } from "./manager-helpers.js";
+import { defaultPackerBrowserResolver } from "../i18n/messages.js";
+
+const ac = new AbortController();
+ac.abort();
+try {
+    checkAbortedSignal(
+        ac.signal,
+        defaultPackerBrowserResolver,
+        "packer-browser.error.ABORTED.preload"
+    );
+} catch (err) {
+    console.error("preload aborted", err);
+}
+```
+
+## API Reference
+
+- `deriveCacheKey(url: string, verifyKey?: Uint8Array): string`.
+- `checkAbortedSignal(signal: AbortSignal | undefined, resolver?: MessageResolver, key?: string): void`.
+
+## Implementation Notes
+
+- The 8-byte cap on the verify-key prefix balances key uniqueness
+  against cache-key memory cost. A full key would be 32 bytes hex-
+  encoded (64 chars) per entry; the 8-byte prefix is enough to
+  discriminate adversarially-distinct keys.
+- `checkAbortedSignal` accepts a custom message key so the same helper
+  works for `manager.load`, `manager.preload`, `manager.loadStream`,
+  and future async surfaces.
+- These helpers are NOT part of the public barrel — they're internal
+  implementation details of the manager. Direct imports from outside
+  the manager module are discouraged.