browser-module-runtime 0.0.0-stage → 0.0.2

package/src/engine/compile-cache.js

@@ -0,0 +1,379 @@
+const DEFAULT_LOCAL_STORAGE_PREFIX = "browser-module-runtime:compile-cache:";
+const DEFAULT_IDB_DATABASE = "browser-module-runtime-compile-cache";
+const DEFAULT_IDB_STORE = "artifacts";
+
+
+export function createCompileCache(options = {}) {
+  if (options == null) options = {};
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("createCompileCache(options) expects an options object.");
+  }
+
+  const storage = String(options.storage ?? "indexeddb").toLowerCase();
+  let store;
+  if (storage === "indexeddb") {
+    store = createIndexedDBCompileCache({
+      ...(options.database == null ? {} : { database: options.database }),
+      ...(options.storeName == null ? {} : { storeName: options.storeName }),
+      ...(options.databaseVersion == null ? {} : { databaseVersion: options.databaseVersion }),
+      ...(options.indexedDB == null ? {} : { indexedDB: options.indexedDB }),
+    });
+  } else if (storage === "localstorage") {
+    store = createLocalStorageCompileCache({
+      ...(options.prefix == null ? {} : { prefix: options.prefix }),
+      ...(options.localStorage == null ? {} : { storage: options.localStorage }),
+    });
+  } else if (storage === "memory") {
+    store = createMemoryCompileCache({
+      ...(options.records == null ? {} : { records: options.records }),
+    });
+  } else {
+    throw new TypeError(`Unknown compile cache storage ${JSON.stringify(options.storage)}. Expected "indexeddb", "localstorage", or "memory".`);
+  }
+
+  return {
+    store,
+    namespace: String(options.name ?? options.namespace ?? "default"),
+    version: String(options.version ?? "1"),
+    ...(options.maxEntries == null ? {} : { maxEntries: options.maxEntries }),
+    ...(options.maxBytes == null ? {} : { maxBytes: options.maxBytes }),
+    ...(options.maxAge == null ? {} : { maxAge: options.maxAge }),
+  };
+}
+
+export function createMemoryCompileCache(options = {}) {
+  const records = options.records instanceof Map ? options.records : new Map();
+
+  return {
+    kind: "memory",
+    async get(key) {
+      return records.get(String(key));
+    },
+    async set(key, value) {
+      records.set(String(key), cloneValue(value));
+    },
+    async delete(key) {
+      return records.delete(String(key));
+    },
+    async clear(options = {}) {
+      const prefix = options.prefix == null ? null : String(options.prefix);
+      if (prefix == null) {
+        const count = records.size;
+        records.clear();
+        return count;
+      }
+      let count = 0;
+      for (const key of [...records.keys()]) {
+        if (key.startsWith(prefix)) {
+          records.delete(key);
+          count += 1;
+        }
+      }
+      return count;
+    },
+    async entries(options = {}) {
+      const prefix = options.prefix == null ? null : String(options.prefix);
+      const result = [];
+      for (const [key, value] of records) {
+        if (prefix == null || key.startsWith(prefix)) result.push([key, cloneValue(value)]);
+      }
+      return result;
+    },
+  };
+}
+
+export function createLocalStorageCompileCache(options = {}) {
+  const prefix = String(options.prefix ?? DEFAULT_LOCAL_STORAGE_PREFIX);
+  const configuredStorage = options.storage;
+
+  function assertStorage() {
+    let storage = configuredStorage;
+    if (!storage) {
+      try { storage = globalThis.localStorage; } catch (error) { throw error; }
+    }
+    if (!storage || typeof storage.getItem !== "function") {
+      throw new Error("localStorage is unavailable in this environment.");
+    }
+    return storage;
+  }
+
+  const physical = key => `${prefix}${String(key)}`;
+  const logical = key => String(key).slice(prefix.length);
+
+  return {
+    kind: "localstorage",
+    async get(key) {
+      const raw = assertStorage().getItem(physical(key));
+      return raw == null ? undefined : JSON.parse(raw);
+    },
+    async set(key, value) {
+      assertStorage().setItem(physical(key), JSON.stringify(value));
+    },
+    async delete(key) {
+      const target = physical(key);
+      const store = assertStorage();
+      const existed = store.getItem(target) != null;
+      store.removeItem(target);
+      return existed;
+    },
+    async clear(options = {}) {
+      const store = assertStorage();
+      const logicalPrefix = options.prefix == null ? "" : String(options.prefix);
+      const targetPrefix = physical(logicalPrefix);
+      const keys = [];
+      for (let index = 0; index < store.length; index += 1) {
+        const key = store.key(index);
+        if (key != null && key.startsWith(targetPrefix)) keys.push(key);
+      }
+      for (const key of keys) store.removeItem(key);
+      return keys.length;
+    },
+    async entries(options = {}) {
+      const store = assertStorage();
+      const logicalPrefix = options.prefix == null ? "" : String(options.prefix);
+      const targetPrefix = physical(logicalPrefix);
+      const result = [];
+      for (let index = 0; index < store.length; index += 1) {
+        const key = store.key(index);
+        if (key == null || !key.startsWith(targetPrefix)) continue;
+        const raw = store.getItem(key);
+        if (raw == null) continue;
+        result.push([logical(key), JSON.parse(raw)]);
+      }
+      return result;
+    },
+  };
+}
+
+export function createIndexedDBCompileCache(options = {}) {
+  const database = String(options.database ?? DEFAULT_IDB_DATABASE);
+  const storeName = String(options.storeName ?? DEFAULT_IDB_STORE);
+  const databaseVersion = Number(options.databaseVersion ?? 1);
+  const indexedDBFactory = options.indexedDB ?? globalThis.indexedDB;
+  let dbPromise;
+
+  function openDatabase() {
+    if (dbPromise) return dbPromise;
+    if (!indexedDBFactory || typeof indexedDBFactory.open !== "function") {
+      return Promise.reject(new Error("IndexedDB is unavailable in this environment."));
+    }
+
+    dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDBFactory.open(database, databaseVersion);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => {
+        dbPromise = undefined;
+        reject(request.error ?? new Error(`Failed to open IndexedDB database ${database}.`));
+      };
+      request.onblocked = () => {
+        dbPromise = undefined;
+        reject(new Error(`Opening IndexedDB database ${database} was blocked.`));
+      };
+    });
+
+    return dbPromise;
+  }
+
+
+
+  return {
+    kind: "indexeddb",
+    async get(key) {
+      const db = await openDatabase();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, "readonly");
+        const request = tx.objectStore(storeName).get(String(key));
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB cache read failed."));
+      });
+    },
+    async set(key, value) {
+      const db = await openDatabase();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, "readwrite");
+        tx.objectStore(storeName).put(value, String(key));
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB cache write failed."));
+        tx.onabort = () => reject(tx.error ?? new Error("IndexedDB cache write was aborted."));
+      });
+    },
+    async delete(key) {
+      const db = await openDatabase();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, "readwrite");
+        const store = tx.objectStore(storeName);
+        const lookup = store.getKey(String(key));
+        let existed = false;
+        lookup.onsuccess = () => {
+          existed = lookup.result !== undefined;
+          store.delete(String(key));
+        };
+        lookup.onerror = () => reject(lookup.error ?? new Error("IndexedDB cache delete lookup failed."));
+        tx.oncomplete = () => resolve(existed);
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB cache delete failed."));
+        tx.onabort = () => reject(tx.error ?? new Error("IndexedDB cache delete was aborted."));
+      });
+    },
+    async clear(options = {}) {
+      const prefix = options.prefix == null ? null : String(options.prefix);
+      const db = await openDatabase();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, "readwrite");
+        const store = tx.objectStore(storeName);
+        if (prefix == null || prefix === "") {
+          const countRequest = store.count();
+          let count = 0;
+          countRequest.onsuccess = () => { count = countRequest.result; };
+          store.clear();
+          tx.oncomplete = () => resolve(count);
+          tx.onerror = () => reject(tx.error ?? new Error("IndexedDB cache clear failed."));
+          tx.onabort = () => reject(tx.error ?? new Error("IndexedDB cache clear was aborted."));
+          return;
+        }
+
+        let count = 0;
+        const request = store.openCursor();
+        request.onsuccess = () => {
+          const cursor = request.result;
+          if (!cursor) return;
+          if (String(cursor.key).startsWith(prefix)) {
+            cursor.delete();
+            count += 1;
+          }
+          cursor.continue();
+        };
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB cache clear cursor failed."));
+        tx.oncomplete = () => resolve(count);
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB cache clear failed."));
+        tx.onabort = () => reject(tx.error ?? new Error("IndexedDB cache clear was aborted."));
+      });
+    },
+    async entries(options = {}) {
+      const prefix = options.prefix == null ? null : String(options.prefix);
+      const db = await openDatabase();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, "readonly");
+        const request = tx.objectStore(storeName).openCursor();
+        const result = [];
+        request.onsuccess = () => {
+          const cursor = request.result;
+          if (!cursor) return;
+          const key = String(cursor.key);
+          if (prefix == null || key.startsWith(prefix)) result.push([key, cursor.value]);
+          cursor.continue();
+        };
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB cache entries cursor failed."));
+        tx.oncomplete = () => resolve(result);
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB cache entries transaction failed."));
+      });
+    },
+  };
+}
+
+export async function sha256(value) {
+  const bytes = new TextEncoder().encode(String(value));
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const digest = await subtle.digest("SHA-256", bytes);
+    return toHex(new Uint8Array(digest));
+  }
+  return sha256Fallback(bytes);
+}
+
+export function stableSerialize(value) {
+  return JSON.stringify(normalize(value));
+}
+
+export function approximateByteSize(value) {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalize(value) {
+  if (value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map(normalize);
+  if (typeof value === "object") {
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = value[key];
+      if (item === undefined) continue;
+      result[key] = normalize(item);
+    }
+    return result;
+  }
+  return String(value);
+}
+
+function toHex(bytes) {
+  return [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function sha256Fallback(bytes) {
+  const K = [
+    0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+    0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+    0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+    0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+    0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+    0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+    0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+    0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
+  ];
+  const H = [0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19];
+  const bitLength = bytes.length * 8;
+  const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+  const data = new Uint8Array(paddedLength);
+  data.set(bytes);
+  data[bytes.length] = 0x80;
+  const view = new DataView(data.buffer);
+  const high = Math.floor(bitLength / 0x100000000);
+  const low = bitLength >>> 0;
+  view.setUint32(paddedLength - 8, high, false);
+  view.setUint32(paddedLength - 4, low, false);
+  const w = new Uint32Array(64);
+
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = view.getUint32(offset + i * 4, false);
+    for (let i = 16; i < 64; i += 1) {
+      const a = w[i - 15];
+      const b = w[i - 2];
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let [a,b,c,d,e,f,g,h] = H;
+    for (let i = 0; i < 64; i += 1) {
+      const S1 = rotr(e,6) ^ rotr(e,11) ^ rotr(e,25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + S1 + ch + K[i] + w[i]) >>> 0;
+      const S0 = rotr(a,2) ^ rotr(a,13) ^ rotr(a,22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      h=g; g=f; f=e; e=(d+t1)>>>0; d=c; c=b; b=a; a=(t1+t2)>>>0;
+    }
+    H[0]=(H[0]+a)>>>0; H[1]=(H[1]+b)>>>0; H[2]=(H[2]+c)>>>0; H[3]=(H[3]+d)>>>0;
+    H[4]=(H[4]+e)>>>0; H[5]=(H[5]+f)>>>0; H[6]=(H[6]+g)>>>0; H[7]=(H[7]+h)>>>0;
+  }
+  const output = new Uint8Array(32);
+  const out = new DataView(output.buffer);
+  H.forEach((value, index) => out.setUint32(index * 4, value, false));
+  return toHex(output);
+}
+
+function rotr(value, bits) {
+  return (value >>> bits) | (value << (32 - bits));
+}
+
+function cloneValue(value) {
+  if (typeof structuredClone === "function") {
+    try { return structuredClone(value); } catch {}
+  }
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}

package/src/engine/errors.js

@@ -0,0 +1,41 @@
+export class ModuleRuntimeError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "ModuleRuntimeError";
+  }
+}
+
+export class ModuleResolutionError extends ModuleRuntimeError {
+  constructor(specifier, importer, message) {
+    super(message ?? `Could not resolve module ${JSON.stringify(specifier)} from ${JSON.stringify(importer ?? "<runtime>")}.`);
+    this.name = "ModuleResolutionError";
+    this.specifier = specifier;
+    this.importer = importer ?? null;
+  }
+}
+
+export class CircularDependencyError extends ModuleRuntimeError {
+  constructor(cycle) {
+    super(`Circular virtual module dependency is not supported yet: ${cycle.join(" -> ")}`);
+    this.name = "CircularDependencyError";
+    this.cycle = [...cycle];
+  }
+}
+
+export class ModuleCompileError extends ModuleRuntimeError {
+  constructor(id, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to compile module ${JSON.stringify(id)}: ${detail}`, { cause });
+    this.name = "ModuleCompileError";
+    this.id = id;
+  }
+}
+
+export class ModuleWaitTimeoutError extends ModuleRuntimeError {
+  constructor(moduleId, timeout) {
+    super(`Timed out after ${timeout}ms waiting for runtime module ${JSON.stringify(moduleId)}.`);
+    this.name = "ModuleWaitTimeoutError";
+    this.moduleId = moduleId;
+    this.timeout = timeout;
+  }
+}

package/src/engine/events.js

@@ -0,0 +1,63 @@
+export function createEventDispatcher(options = {}) {
+  const subscriptions = new Set();
+  const onListenerError = options.onListenerError;
+
+  return {
+    subscribe,
+    emit,
+    clear,
+    get size() {
+      return subscriptions.size;
+    },
+  };
+
+  function subscribe(typesOrListener, maybeListener) {
+    let types;
+    let listener;
+
+    if (typeof typesOrListener === "function") {
+      listener = typesOrListener;
+      types = undefined;
+    } else {
+      listener = maybeListener;
+      if (typeof typesOrListener === "string") {
+        types = new Set([typesOrListener]);
+      } else if (Array.isArray(typesOrListener)) {
+        if (typesOrListener.length === 0 || typesOrListener.some(type => typeof type !== "string" || !type)) {
+          throw new TypeError("subscribe(types, listener) expects a non-empty event type or event type array.");
+        }
+        types = new Set(typesOrListener);
+      } else {
+        throw new TypeError("subscribe() expects a listener, event type + listener, or event type array + listener.");
+      }
+    }
+
+    if (typeof listener !== "function") {
+      throw new TypeError("subscribe() expects a listener function.");
+    }
+
+    const subscription = { types, listener };
+    subscriptions.add(subscription);
+
+    return () => subscriptions.delete(subscription);
+  }
+
+  function emit(event) {
+    for (const subscription of [...subscriptions]) {
+      if (subscription.types && !subscription.types.has(event.type)) continue;
+      try {
+        subscription.listener(event);
+      } catch (error) {
+        try {
+          onListenerError?.(error, event);
+        } catch {
+          // Listener error reporting must never break the emitter.
+        }
+      }
+    }
+  }
+
+  function clear() {
+    subscriptions.clear();
+  }
+}

package/src/engine/package-resolution/index.js

@@ -0,0 +1,179 @@
+/** Pure, per-runtime package resolution. No import-map mutation or network access. */
+export class PackageVersionResolutionError extends Error {
+  constructor(code, message, details = {}) {
+    super(`${code}: ${message}`);
+    this.name = "PackageVersionResolutionError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+const OWN_NAME = /^[a-z0-9][a-z0-9._~-]*$/;
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const error = (code, message, details) => new PackageVersionResolutionError(code, message, details);
+
+export function parsePackageSpecifier(specifier) {
+  if (typeof specifier !== "string" || !specifier || /[\\%?#\s\x00-\x1f]/.test(specifier)) return undefined;
+  if (/^(?:\.|\/|#|[a-z][a-z\d+.-]*:)/i.test(specifier)) return undefined;
+  const segments = specifier.split("/");
+  const scoped = segments[0]?.startsWith("@");
+  const count = scoped ? 2 : 1;
+  const packageParts = segments.slice(0, count);
+  if (packageParts.length !== count || packageParts.some(part => !part)) return undefined;
+  if (scoped) {
+    if (!OWN_NAME.test(packageParts[0].slice(1)) || !OWN_NAME.test(packageParts[1])) return undefined;
+  } else if (!OWN_NAME.test(packageParts[0])) return undefined;
+  const subpathParts = segments.slice(count);
+  if (subpathParts.some(part => !part || part === "." || part === ".." || part.includes(".."))) return undefined;
+  return { packageName: packageParts.join("/"), subpath: subpathParts.length ? `/${subpathParts.join("/")}` : "" };
+}
+
+export function validateExactVersion(version, packageName = "package") {
+  if (typeof version !== "string" || !VERSION.test(version)) {
+    throw error("PACKAGE_VERSION_INVALID", `Expected an exact semver version for ${JSON.stringify(packageName)}, received ${JSON.stringify(version)}. Tags and ranges are not supported.`, { packageName, version });
+  }
+  return version;
+}
+
+export function normalizePackageProvider(value) {
+  if (value === "esm.sh" || value === "esm") return "esm.sh";
+  if (value === "jsdelivr" || value === "jsDelivr") return "jsdelivr";
+  throw error("PACKAGE_PROVIDER_UNSUPPORTED", `Unknown package provider ${JSON.stringify(value)}. Choose "esm.sh" or "jsdelivr".`, { provider: value });
+}
+
+function safeToken(token) {
+  return typeof token === "string" && SAFE_SEGMENT.test(token) && token !== "." && token !== ".." && !token.includes("..");
+}
+function validateGithub(repository, ref, name, value) {
+  const parts = typeof repository === "string" ? repository.split("/") : [];
+  if (parts.length !== 2 || !parts.every(safeToken) || !safeToken(ref)) {
+    throw error("PACKAGE_VALUE_INVALID", `Invalid GitHub source for ${JSON.stringify(name)}. Use gh/owner/repo@tag-or-commit (no URL query, fragment or path traversal).`, { packageName: name, source: "github", value });
+  }
+  return { repository, ref };
+}
+function validatePreview(locator, ref, name, value) {
+  const parts = typeof locator === "string" ? locator.split("/") : [];
+  if (!(parts.length === 1 || parts.length >= 3) || !parts.every(safeToken) || !safeToken(ref)) {
+    throw error("PACKAGE_VALUE_INVALID", `Invalid pkg.pr.new locator for ${JSON.stringify(name)}. Use pr/package@build or pr/owner/repo/package@build.`, { packageName: name, source: "pkg.pr.new", value });
+  }
+  return { locator, ref };
+}
+function sourceFromCompact(raw, provider, name) {
+  const github = raw.startsWith("gh/");
+  const preview = raw.startsWith("pr/");
+  if (!github && !preview) {
+    throw error("PACKAGE_VALUE_INVALID", `Unsupported package source value ${JSON.stringify(raw)} for ${JSON.stringify(name)}. Use an exact npm version, gh/owner/repo@ref, or pr/package@build.`, { packageName: name, value: raw });
+  }
+  if (provider !== "esm.sh") throw error("PACKAGE_SOURCE_UNSUPPORTED", `${provider} does not support ${github ? "GitHub" : "pkg.pr.new"} source imports. Select esm.sh.`, { provider, source: github ? "github" : "pkg.pr.new", packageName: name, value: raw });
+  const at = raw.lastIndexOf("@");
+  if (at < 0) throw error("PACKAGE_VALUE_INVALID", `Missing source ref/build identifier in ${JSON.stringify(raw)}.`, { packageName: name, value: raw });
+  const path = raw.slice(github ? 3 : 3, at);
+  const ref = raw.slice(at + 1);
+  return github ? { provider, source: "github", ...validateGithub(path, ref, name, raw), subpaths: false }
+    : { provider, source: "pkg.pr.new", ...validatePreview(path, ref, name, raw), subpaths: false };
+}
+
+/** Parse short strings before matching any import specifier, never while importing. */
+export function parsePackageVersionValue(value, name, defaultProvider) {
+  if (typeof value !== "string" || !value) throw error("PACKAGE_VALUE_INVALID", `Expected a nonempty package version string for ${JSON.stringify(name)}.`, { packageName: name, value });
+  if (VERSION.test(value)) {
+    if (!defaultProvider) throw error("PACKAGE_PROVIDER_REQUIRED", `packages.provider is required for unprefixed version ${JSON.stringify(name)} (or specify esm.sh: / jsdelivr:).`, { packageName: name });
+    return { provider: defaultProvider, source: "npm", version: value, subpaths: true };
+  }
+  const colon = value.indexOf(":");
+  if (colon < 0) return { provider: defaultProvider, source: "npm", version: validateExactVersion(value, name), subpaths: true };
+  const provider = normalizePackageProvider(value.slice(0, colon));
+  const source = value.slice(colon + 1);
+  if (VERSION.test(source)) return { provider, source: "npm", version: source, subpaths: true };
+  return sourceFromCompact(source, provider, name);
+}
+
+function normalizeObject(value, name, defaultProvider) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw error("PACKAGE_VALUE_INVALID", `Package entry ${JSON.stringify(name)} must be an object.`, { packageName: name, value });
+  if (Object.prototype.hasOwnProperty.call(value, "url")) {
+    if (typeof value.url !== "string") throw error("PACKAGE_VALUE_INVALID", `URL entry ${JSON.stringify(name)} needs an HTTPS URL.`, { packageName: name });
+    let parsed;
+    try { parsed = new URL(value.url); } catch { /* below */ }
+    if (!parsed || parsed.protocol !== "https:" || parsed.username || parsed.password || value.subpaths === true || value.source || value.version || value.provider) {
+      throw error("PACKAGE_VALUE_INVALID", `Custom URL ${JSON.stringify(name)} must be HTTPS, credential-free and root-only.`, { packageName: name });
+    }
+    return { source: "url", url: parsed.href, subpaths: false };
+  }
+  const provider = value.provider == null ? defaultProvider : normalizePackageProvider(value.provider);
+  const source = value.source ?? "npm";
+  if (source === "npm") {
+    if (!provider) throw error("PACKAGE_PROVIDER_REQUIRED", `Package ${JSON.stringify(name)} needs a provider.`, { packageName: name });
+    return { provider, source, version: validateExactVersion(value.version, name), subpaths: value.subpaths !== false };
+  }
+  if (source !== "github" && source !== "pkg.pr.new") {
+    throw error("PACKAGE_SOURCE_UNSUPPORTED", `Unsupported package source ${JSON.stringify(source)} for ${JSON.stringify(name)}.`, { packageName: name, source, provider });
+  }
+  if (!provider) throw error("PACKAGE_PROVIDER_REQUIRED", `Package ${JSON.stringify(name)} needs a provider.`, { packageName: name });
+  if (provider !== "esm.sh") throw error("PACKAGE_SOURCE_UNSUPPORTED", `${provider} does not support ${source}.`, { provider, source, packageName: name });
+  if (source === "github") return { provider, source, ...validateGithub(value.repository, value.ref, name, value), subpaths: value.subpaths === true };
+  if (value.subpaths === true) throw error("PACKAGE_SUBPATH_UNSUPPORTED", `pkg.pr.new subpaths are not verified for ${JSON.stringify(name)}.`, { packageName: name, provider, source });
+  return { provider, source, ...validatePreview(value.package, value.ref, name, value), subpaths: false };
+}
+
+export function normalizePackageOptions(options = {}, { inheritedProvider } = {}) {
+  if (options == null) options = {};
+  if (typeof options !== "object" || Array.isArray(options)) throw error("PACKAGE_NAME_INVALID", "packages must be an object.");
+  const versions = options.versions ?? {};
+  const entries = options.entries ?? {};
+  for (const [field, value] of [["versions", versions], ["entries", entries]]) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw error("PACKAGE_NAME_INVALID", `packages.${field} must be an object of package roots.`);
+  }
+  const provider = options.provider == null ? (inheritedProvider ? normalizePackageProvider(inheritedProvider) : undefined) : normalizePackageProvider(options.provider);
+  const pins = new Map();
+  for (const [name, value] of [...Object.entries(versions), ...Object.entries(entries)]) {
+    const parsed = parsePackageSpecifier(name);
+    if (!parsed || parsed.packageName !== name || parsed.subpath) throw error("PACKAGE_NAME_INVALID", `Package key ${JSON.stringify(name)} must be an exact npm-style package root (no trailing slash or subpath).`, { packageName: name });
+    if (pins.has(name)) throw error("PACKAGE_ENTRY_DUPLICATE", `Package ${JSON.stringify(name)} appears in both versions and entries. Use only one declaration.`, { packageName: name });
+    const normalized = Object.prototype.hasOwnProperty.call(versions, name)
+      ? parsePackageVersionValue(value, name, provider)
+      : normalizeObject(value, name, provider);
+    pins.set(name, Object.freeze({ importName: name, ...normalized }));
+  }
+  return { provider, pins };
+}
+
+/** Provider-specific URL builders; importer matching is independent of their shape. */
+export function buildPackageUrl(entry, subpath = "") {
+  const { provider, source, importName: packageName } = entry;
+  if (subpath && !entry.subpaths) throw error("PACKAGE_SUBPATH_UNSUPPORTED", `Subpath ${JSON.stringify(packageName + subpath)} is not supported for ${source} through ${provider ?? "custom URL"}.`, { provider, source, packageName, subpath });
+  if (source === "url") return entry.url;
+  if (source === "npm") {
+    if (provider === "esm.sh") return `https://esm.sh/${packageName}@${entry.version}${subpath}`;
+    if (subpath) throw error("PACKAGE_SUBPATH_UNSUPPORTED", `jsDelivr +esm subpath resolution is not verified for ${JSON.stringify(packageName + subpath)}.`, { provider, source, packageName, subpath });
+    return `https://cdn.jsdelivr.net/npm/${packageName}@${entry.version}/+esm`;
+  }
+  if (provider !== "esm.sh") throw error("PACKAGE_SOURCE_UNSUPPORTED", `${source} requires esm.sh.`, { provider, source, packageName });
+  if (source === "github") return `https://esm.sh/gh/${entry.repository}@${entry.ref}${subpath}`;
+  if (source === "pkg.pr.new") return `https://esm.sh/pr/${entry.locator}@${entry.ref}`;
+  throw error("PACKAGE_SOURCE_UNSUPPORTED", `Unknown package source ${JSON.stringify(source)}.`, { provider, source, packageName });
+}
+
+/** Optional internal Solid-family extension; both factories share exact package matching. */
+export function createPackagePolicy(options, { inheritedProvider, familyRules } = {}) {
+  const normalized = normalizePackageOptions(options, { inheritedProvider });
+  const family = new Map(Object.entries(familyRules ?? {}));
+  function inspect(specifier) {
+    const parsed = parsePackageSpecifier(specifier);
+    if (!parsed) return undefined;
+    const owned = family.get(parsed.packageName);
+    if (owned) {
+      const ownedUrl = owned.subpathUrl ? owned.subpathUrl(parsed.subpath) : (parsed.subpath ? buildPackageUrl({ source: "npm", importName: parsed.packageName, version: owned.version, provider: owned.provider, subpaths: true }, parsed.subpath) : owned.url);
+      return Object.freeze({ specifier, packageName: parsed.packageName, subpath: parsed.subpath, version: owned.version, source: "npm", provider: owned.provider, url: ownedUrl, kind: "solid-family", implicitSubpath: Boolean(parsed.subpath) });
+    }
+    const entry = normalized.pins.get(parsed.packageName);
+    if (!entry) return undefined;
+    const inspected = { specifier, packageName: parsed.packageName, subpath: parsed.subpath, provider: entry.provider, source: entry.source, url: buildPackageUrl(entry, parsed.subpath), kind: "package", implicitSubpath: Boolean(parsed.subpath) };
+    if (entry.version) inspected.version = entry.version;
+    if (entry.ref) inspected.ref = entry.ref;
+    if (entry.repository) inspected.repository = entry.repository;
+    if (entry.locator) inspected.locator = entry.locator;
+    return Object.freeze(inspected);
+  }
+  return Object.freeze({ inspect, provider: normalized.provider, pins: normalized.pins });
+}