@aigne/aos 0.2.0-beta

package/dist/blocklet/registry.d.mts

@@ -0,0 +1,197 @@
+//#region src/blocklet/registry.d.ts
+/**
+ * Blocklet Registry — portable, runtime-agnostic discovery and reading.
+ *
+ * The registry unifies how Node and Cloudflare Worker runtimes discover and
+ * read blocklets. Same detector logic runs against both filesystem-backed
+ * readers (Node) and static-map-backed readers (CF bundle).
+ *
+ * Zero platform imports: everything here works unchanged in Node, Bun, Deno,
+ * browsers, and Cloudflare Workers.
+ */
+/**
+ * Read-only view of a single blocklet's files.
+ *
+ * Paths are relative to the blocklet root (e.g. "index.html", ".aup/app.json").
+ * Implementations should normalize leading slashes and `./` prefixes.
+ */
+interface BlockletReader {
+  /** Return true if a file exists at the given relative path. */
+  exists(relPath: string): Promise<boolean>;
+  /** Read file contents as UTF-8 text, or undefined if missing. */
+  readText(relPath: string): Promise<string | undefined>;
+  /**
+   * Read file contents as raw bytes, or undefined if missing. Required for
+   * binary assets (png / ico / jpg) — using `readText` for those bytes
+   * round-trips through UTF-8 and corrupts the file.
+   */
+  readBytes(relPath: string): Promise<Uint8Array | undefined>;
+  /** Return true if any file exists under the given directory path. */
+  hasDir(relDir: string): Promise<boolean>;
+  /** List relative paths of files directly under `relDir` (non-recursive). */
+  listDir(relDir: string): Promise<string[]>;
+  /**
+   * List entries directly under `relDir` with each one's name + dir/file kind,
+   * in ONE backend round-trip. Optional: when present, `detectBlockletPattern`
+   * probes blocklet.yaml / .aup / index.* from a single `list` instead of 3-4
+   * sequential `exists`/`hasDir` stats — the dominant cold-start cost on CF
+   * DID-Space (issue #808: `resolve.pattern` ~665ms → ~150ms). Readers whose
+   * per-entry stat is already cheap (fs, in-memory map) may omit it;
+   * `detectBlockletPattern` falls back to the sequential probes.
+   */
+  listEntries?(relDir: string): Promise<Array<{
+    name: string;
+    isDir: boolean;
+  }>>;
+}
+/** Normalize a relative path: strip leading `/` and `./`, collapse `//`. */
+declare function normalizeRel(p: string): string;
+/**
+ * Create a reader backed by an in-memory map of relative paths → file content.
+ */
+declare function createMapBlockletReader(files: Record<string, string>): BlockletReader;
+type BlockletPatternKind = /** Directory has an explicit blocklet.yaml — use it as the source of truth. */"manifest" /** Zero-config Pattern A — directory has a .aup/ subdirectory. */ | "zero-aup" /** Zero-config Pattern S — directory has index.html at root. */ | "zero-web" /** Zero-config Pattern B — directory has index.txt / index.md / index.ans at root. */ | "zero-terminal";
+interface BlockletPattern {
+  kind: BlockletPatternKind;
+  /** For Pattern B — which index file was found. */
+  terminalIndexFile?: string;
+  /** For Pattern B — MIME type of the index file. */
+  terminalIndexContentType?: string;
+}
+/** Terminal entry filename + MIME type recognised by Pattern B zero-config. */
+declare const TERMINAL_INDEX_FILES: ReadonlyArray<{
+  file: string;
+  contentType: string;
+}>;
+/**
+ * Inspect a blocklet reader and return its pattern.
+ *
+ * Precedence (same as the fs-based version):
+ *   1. blocklet.yaml → "manifest"
+ *   2. .aup/         → "zero-aup"
+ *   3. index.html    → "zero-web"
+ *   4. index.{txt,md,ans} → "zero-terminal"
+ *   5. otherwise     → null
+ */
+declare function detectBlockletPattern(reader: BlockletReader): Promise<BlockletPattern | null>;
+/**
+ * Registry of available blocklets. Runtime-specific implementations:
+ * - Node: scans a filesystem directory (see runtimes/node/.../fs-blocklet-registry.ts)
+ * - CF Worker: reads from a bundled static map (createStaticBlockletRegistry)
+ * - Future: resolves via DID document
+ */
+interface BlockletRegistry {
+  /** Source label for logging ("local", "embedded", "remote"). */
+  readonly source: "local" | "embedded" | "remote";
+  /** List all known blocklet names. */
+  list(): Promise<string[]>;
+  /** Return the canonical blocklet name for a lookup key or alias, if found. */
+  resolveName?(name: string): Promise<string | null>;
+  /** Return a reader for the named blocklet, or null if not found. */
+  reader(name: string): Promise<BlockletReader | null>;
+  /**
+   * Resolve the raw `(afs, rootPath)` pair backing this blocklet, for
+   * consumers that need list/read/stat against a stable AFS path rather than
+   * the narrower `BlockletReader` surface (e.g. the Web Device SiteServer,
+   * which walks its own sub-paths directly). Optional — registries backed by
+   * a non-path-addressable store (e.g. an embedded static map) omit it.
+   * Returns null when the blocklet is unknown or has no raw AFS root.
+   */
+  afsRoot?(name: string): Promise<{
+    afs: BlockletAfsReader;
+    rootPath: string;
+  } | null>;
+}
+/**
+ * Create a registry backed by a static `{ name → { relPath → content } }` map.
+ * Used by CF Worker to serve blocklets embedded at build time.
+ */
+declare function createStaticBlockletRegistry(blocklets: Record<string, Record<string, string>>): BlockletRegistry;
+/**
+ * Minimal AFS surface this module needs. Typed loosely to avoid dragging the
+ * full `@aigne/afs` AFS type into aos's public surface — only `read`, `list`,
+ * and `stat` are consumed, and only their happy-path shape.
+ */
+/**
+ * Read options forwarded to the underlying AFS. Only the fields the blocklet
+ * serve path needs are surfaced here — chiefly `includeActions:"none"`, which
+ * skips the per-read semantic-action probe (`list <path>/.actions`) that pure
+ * byte-serving reads never use (issue #808). Simple readers that don't wrap a
+ * real AFS ignore it (they have no actions anyway).
+ */
+interface BlockletAfsReadOptions {
+  includeActions?: "none" | "refs" | "schemas";
+  /**
+   * For `stat` only: skip the `read()` fallback when the provider's stat handler
+   * reports the path absent (issue #808). The bundle-cid probe sets it — a stat
+   * miss means "no bundle", so the read fallback would only miss again. Mirrors
+   * {@link AFSStatOptions.noReadFallback}; a real AFS forwards it, simple readers
+   * ignore it.
+   */
+  noReadFallback?: boolean;
+}
+interface BlockletAfsReader {
+  read(path: string, options?: BlockletAfsReadOptions): Promise<{
+    data?: {
+      content?: unknown;
+    } | null | undefined;
+  } | null | undefined>;
+  list(path: string): Promise<{
+    data?: ReadonlyArray<{
+      path: string;
+      meta?: {
+        kind?: string;
+        childrenCount?: number;
+      } | null | undefined;
+    }> | null | undefined;
+  }>;
+  stat(path: string, options?: BlockletAfsReadOptions): Promise<{
+    data?: {
+      meta?: {
+        kind?: string;
+        childrenCount?: number;
+      } | null | undefined;
+    } | null | undefined;
+  } | null>;
+  /**
+   * Optional batch read — fetch many file paths in one shot (issue #808
+   * follow-up). A real AFS pushes this to the DID-Space provider's `getMany`
+   * (one `IN(…)` D1 query, inline content → zero R2). `ReadonlyMap` (not `Map`)
+   * so a concrete `Map<string, AFSEntry | null>` stays assignable here despite
+   * `Map`'s invariance. Absent → callers fall back to per-path `read`.
+   */
+  readMany?(paths: string[]): Promise<ReadonlyMap<string, {
+    content?: unknown;
+  } | null>>;
+}
+/** Create a BlockletReader that serves one blocklet rooted at `blockletRoot` in AFS. */
+declare function createAfsBlockletReader(afs: BlockletAfsReader, blockletRoot: string): BlockletReader;
+/** Options for `createAfsBlockletRegistry`. */
+interface AfsBlockletRegistryOptions {
+  afs: BlockletAfsReader;
+  /** AFS paths to search for blocklet directories, e.g. `["/blocklets"]`. */
+  searchPaths: string[];
+  /** Source label (default `"local"`). */
+  source?: BlockletRegistry["source"];
+}
+/**
+ * Create a registry that discovers blocklets under one or more AFS paths.
+ *
+ * Each search path is listed; every immediate child directory is treated as a
+ * candidate blocklet and probed via `detectBlockletPattern`. First match wins
+ * when the same blocklet name appears in multiple search paths.
+ */
+declare function createAfsBlockletRegistry(opts: AfsBlockletRegistryOptions): BlockletRegistry;
+interface BlockletPatternCache {
+  resolve(name: string): Promise<BlockletPattern | null>;
+  resolveName(name: string): Promise<string | null>;
+  readerFor(name: string): Promise<BlockletReader | null>;
+}
+/**
+ * `null` as a tombstone for "name is known but has no valid pattern" keeps
+ * repeated negative lookups cheap.
+ */
+declare function createPatternCache(registry: BlockletRegistry): BlockletPatternCache;
+//#endregion
+export { AfsBlockletRegistryOptions, BlockletAfsReader, BlockletPattern, BlockletPatternCache, BlockletPatternKind, BlockletReader, BlockletRegistry, TERMINAL_INDEX_FILES, createAfsBlockletReader, createAfsBlockletRegistry, createMapBlockletReader, createPatternCache, createStaticBlockletRegistry, detectBlockletPattern, normalizeRel };
+//# sourceMappingURL=registry.d.mts.map

package/dist/blocklet/registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.mts","names":[],"sources":["../../src/blocklet/registry.ts"],"mappings":";;AA+BA;;;;;;;;;;;;;;;UAAiB,cAAA;EAIf;EAFA,MAAA,CAAO,OAAA,WAAkB,OAAA;EAEE;EAA3B,QAAA,CAAS,OAAA,WAAkB,OAAA;EAMjB;;;;;EAAV,SAAA,CAAU,OAAA,WAAkB,OAAA,CAAQ,UAAA;EAIpC;EAFA,MAAA,CAAO,MAAA,WAAiB,OAAA;EAEC;EAAzB,OAAA,CAAQ,MAAA,WAAiB,OAAA;EAUZ;;;;;;;AAIf;;EAJE,WAAA,EAAa,MAAA,WAAiB,OAAA,CAAQ,KAAA;IAAQ,IAAA;IAAc,KAAA;EAAA;AAAA;;iBAI9C,YAAA,CAAa,CAAA;;;;iBASb,uBAAA,CAAwB,KAAA,EAAO,MAAA,mBAAyB,cAAA;AAAA,KAyD5D,mBAAA,GAAZ;UAUiB,eAAA;EACf,IAAA,EAAM,mBAAA;EAAA;EAEN,iBAAA;EAEA;EAAA,wBAAA;AAAA;AAIF;AAAA,cAAa,oBAAA,EAAsB,aAAA;EAAgB,IAAA;EAAc,WAAA;AAAA;;;;;AAgBjE;;;;;;iBAAsB,qBAAA,CACpB,MAAA,EAAQ,cAAA,GACP,OAAA,CAAQ,eAAA;;;;;;;UAuDM,gBAAA;EAAA;EAAA,SAEN,MAAA;;EAET,IAAA,IAAQ,OAAA;EAEoB;EAA5B,WAAA,EAAa,IAAA,WAAe,OAAA;EAEN;EAAtB,MAAA,CAAO,IAAA,WAAe,OAAA,CAAQ,cAAA;EASN;;;;;;;;EAAxB,OAAA,EAAS,IAAA,WAAe,OAAA;IAAU,GAAA,EAAK,iBAAA;IAAmB,QAAA;EAAA;AAAA;;;;;iBAO5C,4BAAA,CACd,SAAA,EAAW,MAAA,SAAe,MAAA,oBACzB,gBAAA;;;;AAFH;;;;;;;;;UAuCiB,sBAAA;EACf,cAAA;EAtCC;;;AAqCH;;;;EASE,cAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA,CACE,IAAA,UACA,OAAA,GAAU,sBAAA,GACT,OAAA;IAAU,IAAA;MAAS,OAAA;IAAA;EAAA;EAKtB,IAAA,CAAK,IAAA,WAAe,OAAA;IAClB,IAAA,GACI,aAAA;MACE,IAAA;MACA,IAAA;QAAS,IAAA;QAAe,aAAA;MAAA;IAAA;EAAA;EAKhC,IAAA,CACE,IAAA,UACA,OAAA,GAAU,sBAAA,GACT,OAAA;IACD,IAAA;MACM,IAAA;QAAS,IAAA;QAAe,aAAA;MAAA;IAAA;EAAA;EAZ1B;;;;;;;EAuBN,QAAA,EAAU,KAAA,aAAkB,OAAA,CAAQ,WAAA;IAAsB,OAAA;EAAA;AAAA;;iBAmB5C,uBAAA,CACd,GAAA,EAAK,iBAAA,EACL,YAAA,WACC,cAAA;;UAsFc,0BAAA;EACf,GAAA,EAAK,iBAAA;EA7GuB;EA+G5B,WAAA;EA/G0D;EAiH1D,MAAA,GAAS,gBAAA;AAAA;AA9FX;;;;;;;AAAA,iBAwGgB,yBAAA,CAA0B,IAAA,EAAM,0BAAA,GAA6B,gBAAA;AAAA,UAwN5D,oBAAA;EACf,OAAA,CAAQ,IAAA,WAAe,OAAA,CAAQ,eAAA;EAC/B,WAAA,CAAY,IAAA,WAAe,OAAA;EAC3B,SAAA,CAAU,IAAA,WAAe,OAAA,CAAQ,cAAA;AAAA;;;;;iBAOnB,kBAAA,CAAmB,QAAA,EAAU,gBAAA,GAAmB,oBAAA"}

package/dist/blocklet/registry.mjs

@@ -0,0 +1,441 @@
+import { joinURL } from "ufo";
+import { makeNsLog } from "@aigne/afs";
+import { time } from "@aigne/afs-timing";
+
+//#region src/blocklet/registry.ts
+/**
+* Blocklet Registry — portable, runtime-agnostic discovery and reading.
+*
+* The registry unifies how Node and Cloudflare Worker runtimes discover and
+* read blocklets. Same detector logic runs against both filesystem-backed
+* readers (Node) and static-map-backed readers (CF bundle).
+*
+* Zero platform imports: everything here works unchanged in Node, Bun, Deno,
+* browsers, and Cloudflare Workers.
+*/
+const log = makeNsLog("aos");
+const UTF8_DECODER = new TextDecoder("utf-8");
+const UTF8_ENCODER = new TextEncoder();
+const ALIASES_PATH = ".afs/aliases.json";
+/** Normalize a relative path: strip leading `/` and `./`, collapse `//`. */
+function normalizeRel(p) {
+	let s = p.replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+/g, "/");
+	if (s.endsWith("/")) s = s.slice(0, -1);
+	return s;
+}
+/**
+* Create a reader backed by an in-memory map of relative paths → file content.
+*/
+function createMapBlockletReader(files) {
+	const normalized = {};
+	for (const [k, v] of Object.entries(files)) normalized[normalizeRel(k)] = v;
+	const keys = Object.keys(normalized);
+	return {
+		async exists(relPath) {
+			return Object.hasOwn(normalized, normalizeRel(relPath));
+		},
+		async readText(relPath) {
+			return normalized[normalizeRel(relPath)];
+		},
+		async readBytes(relPath) {
+			const text = normalized[normalizeRel(relPath)];
+			return text === void 0 ? void 0 : UTF8_ENCODER.encode(text);
+		},
+		async hasDir(relDir) {
+			const prefix = `${normalizeRel(relDir)}/`;
+			return keys.some((k) => k.startsWith(prefix));
+		},
+		async listDir(relDir) {
+			const prefix = normalizeRel(relDir) === "" ? "" : `${normalizeRel(relDir)}/`;
+			const seen = /* @__PURE__ */ new Set();
+			for (const k of keys) {
+				if (!k.startsWith(prefix)) continue;
+				const rest = k.slice(prefix.length);
+				const firstSlash = rest.indexOf("/");
+				seen.add(firstSlash < 0 ? rest : rest.slice(0, firstSlash));
+			}
+			return [...seen];
+		},
+		async listEntries(relDir) {
+			const prefix = normalizeRel(relDir) === "" ? "" : `${normalizeRel(relDir)}/`;
+			const seen = /* @__PURE__ */ new Map();
+			for (const k of keys) {
+				if (!k.startsWith(prefix)) continue;
+				const rest = k.slice(prefix.length);
+				const firstSlash = rest.indexOf("/");
+				const name = firstSlash < 0 ? rest : rest.slice(0, firstSlash);
+				if (name === "") continue;
+				const isDir = firstSlash >= 0;
+				if (isDir || !seen.has(name)) seen.set(name, isDir);
+			}
+			return [...seen].map(([name, isDir]) => ({
+				name,
+				isDir
+			}));
+		}
+	};
+}
+/** Terminal entry filename + MIME type recognised by Pattern B zero-config. */
+const TERMINAL_INDEX_FILES = [
+	{
+		file: "index.txt",
+		contentType: "text/plain; charset=utf-8"
+	},
+	{
+		file: "index.md",
+		contentType: "text/markdown; charset=utf-8"
+	},
+	{
+		file: "index.ans",
+		contentType: "text/plain; charset=utf-8"
+	}
+];
+/**
+* Inspect a blocklet reader and return its pattern.
+*
+* Precedence (same as the fs-based version):
+*   1. blocklet.yaml → "manifest"
+*   2. .aup/         → "zero-aup"
+*   3. index.html    → "zero-web"
+*   4. index.{txt,md,ans} → "zero-terminal"
+*   5. otherwise     → null
+*/
+async function detectBlockletPattern(reader) {
+	if (reader.listEntries) {
+		const entries = await time("resolve.pattern.list", () => reader.listEntries(""));
+		const isFile = (name) => entries.some((e) => e.name === name && !e.isDir);
+		if (isFile("blocklet.yaml")) return { kind: "manifest" };
+		if (entries.some((e) => e.name === ".aup" && e.isDir)) return { kind: "zero-aup" };
+		if (isFile("index.html")) return { kind: "zero-web" };
+		for (const { file, contentType } of TERMINAL_INDEX_FILES) if (isFile(file)) return {
+			kind: "zero-terminal",
+			terminalIndexFile: file,
+			terminalIndexContentType: contentType
+		};
+		return null;
+	}
+	if (await reader.exists("blocklet.yaml")) return { kind: "manifest" };
+	if (await reader.hasDir(".aup")) return { kind: "zero-aup" };
+	if (await reader.exists("index.html")) return { kind: "zero-web" };
+	for (const { file, contentType } of TERMINAL_INDEX_FILES) if (await reader.exists(file)) return {
+		kind: "zero-terminal",
+		terminalIndexFile: file,
+		terminalIndexContentType: contentType
+	};
+	return null;
+}
+/**
+* Create a registry backed by a static `{ name → { relPath → content } }` map.
+* Used by CF Worker to serve blocklets embedded at build time.
+*/
+function createStaticBlockletRegistry(blocklets) {
+	const readers = /* @__PURE__ */ new Map();
+	for (const [name, files] of Object.entries(blocklets)) readers.set(name, createMapBlockletReader(files));
+	return {
+		source: "embedded",
+		async list() {
+			return [...readers.keys()];
+		},
+		async resolveName(name) {
+			return readers.has(name) ? name : null;
+		},
+		async reader(name) {
+			return readers.get(name) ?? null;
+		}
+	};
+}
+/**
+* Directories in AFS always carry `childrenCount` in their meta. Leaves (files,
+* actions) do not. This matches the predicate used by `convention-scanner` in
+* @aigne/afs. Avoids stringly-typed kind matching that would drift as providers
+* add new kinds.
+*/
+function isDirEntry(meta) {
+	return meta?.childrenCount !== void 0 && meta.childrenCount !== null;
+}
+function lastSegment(p) {
+	const i = p.lastIndexOf("/");
+	return i < 0 ? p : p.slice(i + 1);
+}
+/** Create a BlockletReader that serves one blocklet rooted at `blockletRoot` in AFS. */
+function createAfsBlockletReader(afs, blockletRoot) {
+	const NO_ACTIONS = { includeActions: "none" };
+	return {
+		async exists(relPath) {
+			const p = joinURL(blockletRoot, normalizeRel(relPath));
+			try {
+				const meta = (await afs.stat(p, NO_ACTIONS))?.data?.meta;
+				if (!meta) return false;
+				return !isDirEntry(meta);
+			} catch {
+				return false;
+			}
+		},
+		async readText(relPath) {
+			const p = joinURL(blockletRoot, normalizeRel(relPath));
+			try {
+				const content = (await afs.read(p, NO_ACTIONS))?.data?.content;
+				if (typeof content === "string") return content;
+				if (content instanceof Uint8Array) return UTF8_DECODER.decode(content);
+				if (content instanceof ArrayBuffer) return UTF8_DECODER.decode(new Uint8Array(content));
+				return;
+			} catch {
+				return;
+			}
+		},
+		async readBytes(relPath) {
+			const p = joinURL(blockletRoot, normalizeRel(relPath));
+			try {
+				const content = (await afs.read(p, NO_ACTIONS))?.data?.content;
+				if (content instanceof Uint8Array) return content;
+				if (content instanceof ArrayBuffer) return new Uint8Array(content);
+				if (typeof content === "string") return UTF8_ENCODER.encode(content);
+				return;
+			} catch {
+				return;
+			}
+		},
+		async hasDir(relDir) {
+			const p = joinURL(blockletRoot, normalizeRel(relDir));
+			try {
+				return isDirEntry((await afs.stat(p, NO_ACTIONS))?.data?.meta);
+			} catch {
+				return false;
+			}
+		},
+		async listDir(relDir) {
+			const p = joinURL(blockletRoot, normalizeRel(relDir));
+			try {
+				return ((await afs.list(p))?.data ?? []).map((e) => lastSegment(e.path));
+			} catch {
+				return [];
+			}
+		},
+		async listEntries(relDir) {
+			const p = joinURL(blockletRoot, normalizeRel(relDir));
+			try {
+				return ((await afs.list(p))?.data ?? []).map((e) => ({
+					name: lastSegment(e.path),
+					isDir: isDirEntry(e.meta)
+				}));
+			} catch {
+				return [];
+			}
+		}
+	};
+}
+/**
+* Create a registry that discovers blocklets under one or more AFS paths.
+*
+* Each search path is listed; every immediate child directory is treated as a
+* candidate blocklet and probed via `detectBlockletPattern`. First match wins
+* when the same blocklet name appears in multiple search paths.
+*/
+function createAfsBlockletRegistry(opts) {
+	const { afs, searchPaths, source = "local" } = opts;
+	const readerCache = /* @__PURE__ */ new Map();
+	const dirCache = /* @__PURE__ */ new Map();
+	const canonicalNameCache = /* @__PURE__ */ new Map();
+	const aliasCache = /* @__PURE__ */ new Map();
+	const aliasesLoaded = /* @__PURE__ */ new Set();
+	const aliasLoadPromises = /* @__PURE__ */ new Map();
+	let listPromise;
+	function isSafeRegistryName(value) {
+		return value.length > 0 && value.length <= 253 && !value.includes("/") && !value.includes("\\") && !value.includes("..") && !value.includes("@");
+	}
+	function isNotFoundError(err) {
+		if (!err || typeof err !== "object") return false;
+		const maybe = err;
+		if (maybe.name === "AFSNotFoundError" || maybe.code === "AFS_NOT_FOUND") return true;
+		return typeof maybe.message === "string" && /not found/i.test(maybe.message);
+	}
+	async function loadAliases(base) {
+		if (aliasesLoaded.has(base)) return;
+		const existing = aliasLoadPromises.get(base);
+		if (existing) return existing;
+		let cacheableResult = false;
+		const promise = (async () => {
+			try {
+				const res = await afs.read(joinURL(base, ALIASES_PATH));
+				cacheableResult = true;
+				const raw = decodeAfsContent(res?.data);
+				if (!raw) return;
+				const parsed = JSON.parse(raw);
+				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+				for (const [alias, target] of Object.entries(parsed)) {
+					if (typeof target !== "string") continue;
+					const key = alias.trim().toLowerCase();
+					const value = target.trim();
+					if (!isSafeRegistryName(key) || !isSafeRegistryName(value)) continue;
+					aliasCache.set(key, value);
+				}
+			} catch (err) {
+				cacheableResult = cacheableResult || isNotFoundError(err);
+			} finally {
+				if (cacheableResult) aliasesLoaded.add(base);
+				aliasLoadPromises.delete(base);
+			}
+		})();
+		aliasLoadPromises.set(base, promise);
+		return promise;
+	}
+	async function resolveAlias(name) {
+		const key = name.trim().toLowerCase();
+		const cached = aliasCache.get(key);
+		if (cached !== void 0) return cached;
+		for (const base of searchPaths) {
+			await loadAliases(base);
+			const target = aliasCache.get(key);
+			if (target !== void 0) return target;
+		}
+		return null;
+	}
+	async function resolveLocation(name) {
+		const cached = dirCache.get(name);
+		const cachedName = canonicalNameCache.get(name);
+		if (cached !== void 0 && cachedName !== void 0) return {
+			canonicalName: cachedName,
+			dir: cached
+		};
+		const directProbe = resolveDirectDir(name);
+		const aliasTarget = await resolveAlias(name);
+		if (aliasTarget && aliasTarget !== name) {
+			const aliasDir = await resolveDirectDir(aliasTarget);
+			if (aliasDir) {
+				dirCache.set(name, aliasDir);
+				canonicalNameCache.set(name, aliasTarget);
+				dirCache.set(aliasTarget, aliasDir);
+				canonicalNameCache.set(aliasTarget, aliasTarget);
+				return {
+					canonicalName: aliasTarget,
+					dir: aliasDir
+				};
+			}
+		}
+		const directDir = await directProbe;
+		if (directDir) {
+			dirCache.set(name, directDir);
+			canonicalNameCache.set(name, name);
+			return {
+				canonicalName: name,
+				dir: directDir
+			};
+		}
+		return null;
+	}
+	async function resolveDir(name) {
+		return (await resolveLocation(name))?.dir ?? null;
+	}
+	function decodeAfsContent(raw) {
+		const content = raw?.content;
+		if (typeof content === "string") return content;
+		if (content instanceof Uint8Array) return UTF8_DECODER.decode(content);
+		if (content instanceof ArrayBuffer) return UTF8_DECODER.decode(new Uint8Array(content));
+		return "";
+	}
+	async function resolveDirectDir(name) {
+		for (const base of searchPaths) {
+			const full = joinURL(base, name);
+			try {
+				if (isDirEntry((await afs.stat(full))?.data?.meta)) return full;
+			} catch {}
+		}
+		return null;
+	}
+	async function computeList() {
+		const found = /* @__PURE__ */ new Set();
+		for (const base of searchPaths) {
+			let entries = [];
+			try {
+				entries = (await afs.list(base))?.data ?? [];
+			} catch (err) {
+				log.warn(`[aos] blocklet-registry: list("${base}") failed:`, err);
+				continue;
+			}
+			const checks = await Promise.all(entries.map(async (e) => {
+				if (!isDirEntry(e.meta)) return null;
+				const name = lastSegment(e.path);
+				if (found.has(name)) return null;
+				return await detectBlockletPattern(createAfsBlockletReader(afs, joinURL(base, name))) ? name : null;
+			}));
+			for (const n of checks) if (n) found.add(n);
+			await loadAliases(base);
+			for (const [alias, target] of aliasCache) {
+				if (found.has(alias)) continue;
+				const targetDir = await resolveDirectDir(target);
+				if (!targetDir) continue;
+				if (await detectBlockletPattern(createAfsBlockletReader(afs, targetDir))) found.add(alias);
+			}
+		}
+		return [...found];
+	}
+	return {
+		source,
+		async list() {
+			if (!listPromise) {
+				listPromise = computeList();
+				listPromise.catch(() => {
+					listPromise = void 0;
+				});
+			}
+			return listPromise;
+		},
+		async resolveName(name) {
+			return (await resolveLocation(name))?.canonicalName ?? null;
+		},
+		async reader(name) {
+			if (readerCache.has(name)) return readerCache.get(name) ?? null;
+			const dir = await resolveDir(name);
+			if (!dir) return null;
+			const reader = createAfsBlockletReader(afs, dir);
+			readerCache.set(name, reader);
+			return reader;
+		},
+		async afsRoot(name) {
+			const dir = await resolveDir(name);
+			if (!dir) return null;
+			return {
+				afs,
+				rootPath: dir
+			};
+		}
+	};
+}
+/**
+* `null` as a tombstone for "name is known but has no valid pattern" keeps
+* repeated negative lookups cheap.
+*/
+function createPatternCache(registry) {
+	const patterns = /* @__PURE__ */ new Map();
+	const readers = /* @__PURE__ */ new Map();
+	async function readerFor(name) {
+		const cached = readers.get(name);
+		if (cached !== void 0) return cached;
+		const r = await registry.reader(name);
+		if (r) readers.set(name, r);
+		return r;
+	}
+	async function resolve(name) {
+		const cached = patterns.get(name);
+		if (cached !== void 0) return cached;
+		const reader = await readerFor(name);
+		if (!reader) return null;
+		const pattern = await time("resolve.pattern", () => detectBlockletPattern(reader));
+		if (pattern) patterns.set(name, pattern);
+		return pattern;
+	}
+	async function resolveName(name) {
+		const lookupName = (registry.resolveName ? await registry.resolveName(name) : null) ?? name;
+		if (!await resolve(lookupName)) return null;
+		return lookupName;
+	}
+	return {
+		resolve,
+		resolveName,
+		readerFor
+	};
+}
+
+//#endregion
+export { TERMINAL_INDEX_FILES, createAfsBlockletReader, createAfsBlockletRegistry, createMapBlockletReader, createPatternCache, createStaticBlockletRegistry, detectBlockletPattern, normalizeRel };
+//# sourceMappingURL=registry.mjs.map