@almadar/shell-browser 0.0.0-stage → 0.1.0

package/dist/auth/index.d.ts

@@ -0,0 +1,45 @@
+import { Auth } from 'firebase/auth';
+import { JsonObject } from '@almadar/core';
+
+interface BrowserAuthConfig {
+    /** A distinct name per signed-in surface, so two apps on one page never share a session. */
+    appName: string;
+    apiKey: string;
+    projectId: string;
+    authDomain?: string;
+    /** Identity Platform tenant the app's users belong to. */
+    tenantId?: string;
+    /** `host:port` of the Auth emulator. */
+    emulatorHost?: string;
+    /** Where the session lives: `local` (survives reloads, the default) or `memory` (this page only). */
+    persistence?: 'local' | 'memory';
+}
+interface SignedInUser {
+    uid: string;
+    email?: string;
+    name?: string;
+    photoURL?: string;
+    /** The ID token's claims (custom claims such as `role` included). */
+    claims: JsonObject;
+}
+/** One sign-in surface: who is signed in, the ways to sign in, and the ID token every request carries. */
+interface BrowserAuth {
+    readonly auth: Auth;
+    currentUid(): Promise<string | null>;
+    signInWithCustomToken(customToken: string): Promise<SignedInUser>;
+    signInWithEmail(email: string, password: string): Promise<SignedInUser>;
+    signUpWithEmail(email: string, password: string, displayName?: string): Promise<SignedInUser>;
+    signInWithGoogle(): Promise<SignedInUser>;
+    sendSignInLinkToEmail(email: string, returnUrl: string): Promise<void>;
+    isSignInWithEmailLink(link: string): boolean;
+    signInWithEmailLink(email: string, link: string): Promise<SignedInUser>;
+    /** The current user's ID token (refreshed when near expiry), or undefined when signed out. */
+    idToken(): Promise<string | undefined>;
+    /** Each change of the signed-in user. `onError` receives a failure to resolve a user's claims. */
+    onUserChanged(listener: (user: SignedInUser | null) => void, onError?: (error: Error) => void): () => void;
+    signOut(): Promise<void>;
+}
+declare function connectAuth(config: BrowserAuthConfig): Promise<BrowserAuth>;
+
+export { connectAuth };
+export type { BrowserAuth, BrowserAuthConfig, SignedInUser };

package/dist/auth/index.js

@@ -0,0 +1,107 @@
+// src/auth/index.ts
+import { initializeApp, getApps } from "firebase/app";
+import {
+  GoogleAuthProvider,
+  browserLocalPersistence,
+  connectAuthEmulator,
+  createUserWithEmailAndPassword,
+  getAuth,
+  inMemoryPersistence,
+  isSignInWithEmailLink,
+  onIdTokenChanged,
+  sendSignInLinkToEmail,
+  setPersistence,
+  signInWithCustomToken,
+  signInWithEmailAndPassword,
+  signInWithEmailLink,
+  signInWithPopup,
+  signOut,
+  updateProfile
+} from "firebase/auth";
+import { z } from "zod";
+import { JsonValueSchema } from "@almadar/core";
+var ClaimsSchema = z.record(z.string(), JsonValueSchema);
+async function signedIn(user) {
+  const { claims } = await user.getIdTokenResult();
+  return {
+    uid: user.uid,
+    ...user.email !== null ? { email: user.email } : {},
+    ...user.displayName !== null ? { name: user.displayName } : {},
+    ...user.photoURL !== null ? { photoURL: user.photoURL } : {},
+    claims: ClaimsSchema.parse(JSON.parse(JSON.stringify(claims)))
+  };
+}
+function appFor(config) {
+  const existing = getApps().find((app) => app.name === config.appName);
+  return existing ?? initializeApp(
+    { apiKey: config.apiKey, projectId: config.projectId, ...config.authDomain !== void 0 ? { authDomain: config.authDomain } : {} },
+    config.appName
+  );
+}
+async function connectAuth(config) {
+  const auth = getAuth(appFor(config));
+  if (config.tenantId !== void 0) auth.tenantId = config.tenantId;
+  if (config.emulatorHost !== void 0 && auth.emulatorConfig === null) {
+    connectAuthEmulator(auth, `http://${config.emulatorHost}`, { disableWarnings: true });
+  }
+  await setPersistence(auth, config.persistence === "memory" ? inMemoryPersistence : browserLocalPersistence);
+  return {
+    auth,
+    async currentUid() {
+      await auth.authStateReady();
+      return auth.currentUser?.uid ?? null;
+    },
+    async signInWithCustomToken(customToken) {
+      return signedIn((await signInWithCustomToken(auth, customToken)).user);
+    },
+    async signInWithEmail(email, password) {
+      return signedIn((await signInWithEmailAndPassword(auth, email, password)).user);
+    },
+    async signUpWithEmail(email, password, displayName) {
+      const { user } = await createUserWithEmailAndPassword(auth, email, password);
+      if (displayName !== void 0) await updateProfile(user, { displayName });
+      return signedIn(user);
+    },
+    async signInWithGoogle() {
+      return signedIn((await signInWithPopup(auth, new GoogleAuthProvider())).user);
+    },
+    async sendSignInLinkToEmail(email, returnUrl) {
+      await sendSignInLinkToEmail(auth, email, { url: returnUrl, handleCodeInApp: true });
+    },
+    isSignInWithEmailLink(link) {
+      return isSignInWithEmailLink(auth, link);
+    },
+    async signInWithEmailLink(email, link) {
+      return signedIn((await signInWithEmailLink(auth, email, link)).user);
+    },
+    async idToken() {
+      return auth.currentUser ? auth.currentUser.getIdToken() : void 0;
+    },
+    onUserChanged(listener, onError) {
+      let generation = 0;
+      const stop = onIdTokenChanged(auth, (user) => {
+        const current = ++generation;
+        if (user === null) listener(null);
+        else
+          void signedIn(user).then(
+            (resolved) => {
+              if (current === generation) listener(resolved);
+            },
+            (err) => {
+              if (current === generation) onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
+          );
+      });
+      return () => {
+        generation++;
+        stop();
+      };
+    },
+    async signOut() {
+      await signOut(auth);
+    }
+  };
+}
+export {
+  connectAuth
+};

package/dist/chunk-7SDIX7W6.js

@@ -0,0 +1,258 @@
+// src/kv.ts
+function kvNamespace(app, locale, store) {
+  return `kv:${app}:${locale}:${store}`;
+}
+function kvDatabaseName(app, locale) {
+  return `kv:${app}:${locale}`;
+}
+var KvFailure = class extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+  kind;
+};
+function fail(kind, message) {
+  return { error: { kind, message } };
+}
+function request(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+function done(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error ?? new Error("transaction aborted"));
+  });
+}
+function openDatabase(factory, name, version, stores) {
+  return new Promise((resolve, reject) => {
+    const req = version === void 0 ? factory.open(name) : factory.open(name, version);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      for (const store of stores) {
+        if (!db.objectStoreNames.contains(store)) db.createObjectStore(store);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error("IndexedDB upgrade blocked by another open connection"));
+  });
+}
+function isJsonValue(value) {
+  if (value === void 0) return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((item) => isJsonValue(item));
+  if (typeof value !== "object") return false;
+  return Object.values(value).every((item) => isJsonValue(item));
+}
+function compareUtf8(a, b) {
+  const left = Array.from(a);
+  const right = Array.from(b);
+  const length = Math.min(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const diff = (left[i].codePointAt(0) ?? 0) - (right[i].codePointAt(0) ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return left.length - right.length;
+}
+function storeName(value) {
+  if (typeof value !== "string" || value.length === 0) throw new KvFailure("invalid", "kv: the store name must be a non-empty string");
+  return value;
+}
+function keyName(value) {
+  if (typeof value !== "string") throw new KvFailure("invalid", "kv: the key must be a string");
+  return value;
+}
+function jsonValue(value) {
+  if (value === void 0 || !isJsonValue(value)) throw new KvFailure("invalid", "kv/put: the value must be JSON");
+  return value;
+}
+function scanLimit(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new KvFailure("invalid", "kv/scan: limit must be a non-negative integer");
+  return value;
+}
+function batchOps(value) {
+  if (!Array.isArray(value)) throw new KvFailure("invalid", "kv/batch: ops must be an array");
+  return value.map((item, index) => {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) throw new KvFailure("invalid", `kv/batch: op ${index} must be an object`);
+    if (item.kind === "put") return { kind: "put", key: keyName(item.key), value: jsonValue(item.value) };
+    if (item.kind === "delete") return { kind: "delete", key: keyName(item.key) };
+    throw new KvFailure("invalid", `kv/batch: op ${index} has an unknown kind`);
+  });
+}
+var KvWebPort = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  db = null;
+  lane = Promise.resolve();
+  closed = false;
+  pending = /* @__PURE__ */ new Map();
+  factory() {
+    return this.options.factory ?? globalThis.indexedDB;
+  }
+  /** Open the database and create the store when missing, with a version bump, as the persistence adapter did. */
+  async handle(store) {
+    const factory = this.factory();
+    if (!factory) throw new KvFailure("unsupported", "kv: this host has no IndexedDB");
+    const name = kvDatabaseName(this.options.app, this.options.locale);
+    const settle = this.lane.then(async () => {
+      let db = this.db ?? await openDatabase(factory, name, void 0, [store]);
+      if (!db.objectStoreNames.contains(store)) {
+        const next = db.version + 1;
+        db.close();
+        db = await openDatabase(factory, name, next, [store]);
+      }
+      this.db = db;
+    });
+    this.lane = settle.catch(() => void 0);
+    await settle;
+    if (this.db === null) throw new KvFailure("io", "kv: the database did not open");
+    return this.db;
+  }
+  async run(op, args) {
+    if (this.closed) throw new KvFailure("closed", "kv: the host is closed");
+    const store = storeName(args[0]);
+    const allow = (mode) => {
+      if (this.options.allows && !this.options.allows({ need: "kv", store, mode })) {
+        throw new KvFailure("denied", `kv: no ${mode} grant for store "${store}"`);
+      }
+    };
+    switch (op) {
+      case "kv/get": {
+        const key = keyName(args[1]);
+        allow("read");
+        const db = await this.handle(store);
+        const tx = db.transaction(store, "readonly");
+        const objectStore = tx.objectStore(store);
+        if (await request(objectStore.count(key)) === 0) return { found: false };
+        return { found: true, value: await request(objectStore.get(key)) };
+      }
+      case "kv/put": {
+        const key = keyName(args[1]);
+        const value = jsonValue(args[2]);
+        allow("write");
+        const db = await this.handle(store);
+        const tx = db.transaction(store, "readwrite");
+        tx.objectStore(store).put(value, key);
+        await done(tx);
+        return { storedKey: key };
+      }
+      case "kv/delete": {
+        const key = keyName(args[1]);
+        allow("write");
+        const db = await this.handle(store);
+        const tx = db.transaction(store, "readwrite");
+        const objectStore = tx.objectStore(store);
+        const existed = await request(objectStore.count(key)) > 0;
+        objectStore.delete(key);
+        await done(tx);
+        return { existed };
+      }
+      case "kv/scan": {
+        const prefix = args[1];
+        if (typeof prefix !== "string") throw new KvFailure("invalid", "kv/scan: the prefix must be a string");
+        const limit = scanLimit(args[2]);
+        allow("read");
+        const db = await this.handle(store);
+        const tx = db.transaction(store, "readonly");
+        const found = [];
+        await new Promise((resolve, reject) => {
+          const cursor = tx.objectStore(store).openCursor(prefix === "" ? void 0 : IDBKeyRange.lowerBound(prefix));
+          cursor.onerror = () => reject(cursor.error);
+          cursor.onsuccess = () => {
+            const at = cursor.result;
+            if (!at) return resolve();
+            const key = String(at.key);
+            if (!key.startsWith(prefix)) return resolve();
+            found.push({ key, value: at.value });
+            at.continue();
+          };
+        });
+        found.sort((a, b) => compareUtf8(a.key, b.key));
+        return { entries: limit === null ? found : found.slice(0, limit) };
+      }
+      case "kv/batch": {
+        const ops = batchOps(args[1]);
+        allow("write");
+        const db = await this.handle(store);
+        if (ops.length === 0) return { applied: 0 };
+        const tx = db.transaction(store, "readwrite");
+        const objectStore = tx.objectStore(store);
+        const finished = done(tx);
+        try {
+          for (const item of ops) {
+            if (item.kind === "put") objectStore.put(item.value, item.key);
+            else objectStore.delete(item.key);
+          }
+        } catch (cause) {
+          tx.abort();
+          await finished.catch(() => void 0);
+          throw cause;
+        }
+        await finished;
+        return { applied: ops.length };
+      }
+    }
+  }
+  async answer(op, args) {
+    try {
+      const work = this.run(op, args);
+      const timeoutMs = this.options.timeoutMs;
+      if (timeoutMs === void 0) return { ok: await work };
+      let timer;
+      const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new KvFailure("timeout", `kv: no answer in ${timeoutMs} ms`)), timeoutMs);
+      });
+      try {
+        return { ok: await Promise.race([work, limit]) };
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch (cause) {
+      if (cause instanceof KvFailure) return fail(cause.kind, cause.message);
+      return fail("io", cause instanceof Error ? cause.message : String(cause));
+    }
+  }
+  defer(op, args, key, deliver) {
+    if (this.closed) return fail("closed", "kv: the host is closed");
+    if (this.pending.has(key)) return fail("invalid", `kv: a call with key "${key}" is already pending`);
+    const entry = { cancelled: false };
+    this.pending.set(key, entry);
+    void this.answer(op, args).then((outcome) => {
+      if (this.pending.get(key) === entry) this.pending.delete(key);
+      if (!entry.cancelled) deliver(outcome);
+    });
+    return { ok: null };
+  }
+  cancel(key) {
+    const entry = this.pending.get(key);
+    if (!entry) return false;
+    entry.cancelled = true;
+    this.pending.delete(key);
+    return true;
+  }
+  close() {
+    this.closed = true;
+    this.pending.clear();
+    this.db?.close();
+    this.db = null;
+  }
+};
+function createKvWebPort(options) {
+  return new KvWebPort(options);
+}
+
+export {
+  kvNamespace,
+  kvDatabaseName,
+  KvWebPort,
+  createKvWebPort
+};

package/dist/chunk-DTZ6GAB4.js

@@ -0,0 +1,33 @@
+// src/page-facts.ts
+var PAGE_FACT_FIELDS = ["hostname", "referrer", "screenWidth"];
+function parsePageFactFields(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return { error: "browser/page-facts: the fields must be a non-empty list of hostname, referrer, screenWidth" };
+  }
+  const fields = [];
+  for (const entry of value) {
+    const field = PAGE_FACT_FIELDS.find((known) => known === entry);
+    if (field === void 0) {
+      return { error: `browser/page-facts: ${String(entry)} is not one of ${PAGE_FACT_FIELDS.join(", ")}` };
+    }
+    if (fields.includes(field)) return { error: `browser/page-facts: ${field} is listed twice` };
+    fields.push(field);
+  }
+  return { fields };
+}
+function readPageFacts(fields) {
+  const facts = { available: false, hostname: "", referrer: "", screenWidth: null };
+  if (typeof window === "undefined" || typeof document === "undefined") return facts;
+  facts.available = true;
+  for (const field of fields) {
+    if (field === "hostname") facts.hostname = window.location.hostname;
+    else if (field === "referrer") facts.referrer = document.referrer;
+    else facts.screenWidth = window.screen?.width ?? null;
+  }
+  return facts;
+}
+
+export {
+  parsePageFactFields,
+  readPageFacts
+};

package/dist/chunk-GXG5PI2M.js

@@ -0,0 +1,151 @@
+// src/storage/IndexedDbPersistence.ts
+import { FULL_WRITE_CAPABILITIES } from "@almadar/core";
+var CHANGE_LOG = "__changes";
+function request(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+function done(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error);
+  });
+}
+function openDatabase(factory, name, version, stores) {
+  return new Promise((resolve, reject) => {
+    const req = version === void 0 ? factory.open(name) : factory.open(name, version);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      for (const store of stores) {
+        if (!db.objectStoreNames.contains(store)) {
+          db.createObjectStore(store, store === CHANGE_LOG ? { autoIncrement: true } : { keyPath: "id" });
+        }
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+var IndexedDbPersistence = class _IndexedDbPersistence {
+  constructor(db, entityTypes, now) {
+    this.db = db;
+    this.entityTypes = entityTypes;
+    this.now = now;
+  }
+  db;
+  entityTypes;
+  now;
+  /** Open (creating or upgrading) the database so it holds every listed entity type. */
+  static async open(options) {
+    const factory = options.factory ?? globalThis.indexedDB;
+    if (!factory) throw new Error("IndexedDbPersistence: this environment has no IndexedDB");
+    const stores = [...options.entityTypes, CHANGE_LOG];
+    let db = await openDatabase(factory, options.databaseName, void 0, stores);
+    if (stores.some((s) => !db.objectStoreNames.contains(s))) {
+      const next = db.version + 1;
+      db.close();
+      db = await openDatabase(factory, options.databaseName, next, stores);
+    }
+    return new _IndexedDbPersistence(db, new Set(options.entityTypes), options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()));
+  }
+  close() {
+    this.db.close();
+  }
+  store(entityType) {
+    if (!this.entityTypes.has(entityType)) {
+      throw new Error(`IndexedDbPersistence: not opened with entity type "${entityType}"`);
+    }
+    return entityType;
+  }
+  async write(entityType, op, id, row) {
+    const tx = this.db.transaction([this.store(entityType), CHANGE_LOG], "readwrite");
+    if (row) tx.objectStore(entityType).put(row);
+    else tx.objectStore(entityType).delete(id);
+    const change = { op, entityType, id, row, at: this.now() };
+    tx.objectStore(CHANGE_LOG).add(change);
+    await done(tx);
+  }
+  async create(entityType, data) {
+    const id = typeof data.id === "string" && data.id.length > 0 ? data.id : crypto.randomUUID();
+    await this.write(entityType, "create", id, { ...data, id, updatedAt: this.now() });
+    return { id };
+  }
+  async update(entityType, id, data) {
+    const existing = await this.getById(entityType, id);
+    if (!existing) return;
+    await this.write(entityType, "update", id, { ...existing, ...data, id, updatedAt: this.now() });
+  }
+  async delete(entityType, id) {
+    await this.write(entityType, "delete", id, null);
+  }
+  async getById(entityType, id) {
+    const tx = this.db.transaction(this.store(entityType), "readonly");
+    const row = await request(tx.objectStore(entityType).get(id));
+    return row ?? null;
+  }
+  async list(entityType) {
+    const tx = this.db.transaction(this.store(entityType), "readonly");
+    return request(tx.objectStore(entityType).getAll());
+  }
+  writeCapabilities(_entityType) {
+    return { ...FULL_WRITE_CAPABILITIES, commitRows: true };
+  }
+  /** The kernel's decided rows, applied in one readwrite transaction only if each row still equals the version it read (EXEC-STORE-5). */
+  async commitRows(rows) {
+    if (rows.length === 0) return true;
+    const stores = [...new Set(rows.map((row) => this.store(row.entityType)))];
+    const tx = this.db.transaction([...stores, CHANGE_LOG], "readwrite");
+    const log = tx.objectStore(CHANGE_LOG);
+    for (const row of rows) {
+      const current = await request(tx.objectStore(row.entityType).get(row.id));
+      if (!sameRow(current ?? null, row.expected)) {
+        tx.abort();
+        await done(tx).catch(() => void 0);
+        return false;
+      }
+    }
+    for (const row of rows) {
+      const objectStore = tx.objectStore(row.entityType);
+      if (row.write.kind === "put") {
+        const stored = { ...row.write.row, updatedAt: this.now() };
+        objectStore.put(stored);
+        log.add({ op: row.expected === null ? "create" : "update", entityType: row.entityType, id: row.id, row: stored, at: this.now() });
+      } else if (row.write.kind === "delete") {
+        objectStore.delete(row.id);
+        log.add({ op: "delete", entityType: row.entityType, id: row.id, row: null, at: this.now() });
+      }
+    }
+    await done(tx);
+    return true;
+  }
+  async countRows(entityType) {
+    const tx = this.db.transaction(this.store(entityType), "readonly");
+    return request(tx.objectStore(entityType).count());
+  }
+  /** The write log, oldest first — the seam a later `sync` replays. */
+  async changes() {
+    const tx = this.db.transaction(CHANGE_LOG, "readonly");
+    return request(tx.objectStore(CHANGE_LOG).getAll());
+  }
+};
+function sameRow(a, b) {
+  return sameValue(a, b);
+}
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => sameValue(item, b[i]));
+  }
+  if (a === null || b === null || a === void 0 || b === void 0 || typeof a !== "object" || typeof b !== "object") return false;
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => sameValue(a[key], b[key]));
+}
+
+export {
+  CHANGE_LOG,
+  IndexedDbPersistence
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { KvBatchOp, KvHostPort, KvMode, KvOp, KvRequirement, KvWebOptions, KvWebPort, createKvWebPort, kvDatabaseName, kvNamespace } from './kv.js';
+export { parsePageFactFields, readPageFacts } from './page-facts.js';
+export { CHANGE_LOG, ChangeRecord, IndexedDbPersistence, IndexedDbPersistenceOptions } from './storage/index.js';
+import '@almadar/core';
+import '@almadar/core/kernel-wire';

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  CHANGE_LOG,
+  IndexedDbPersistence
+} from "./chunk-GXG5PI2M.js";
+import {
+  KvWebPort,
+  createKvWebPort,
+  kvDatabaseName,
+  kvNamespace
+} from "./chunk-7SDIX7W6.js";
+import {
+  parsePageFactFields,
+  readPageFacts
+} from "./chunk-DTZ6GAB4.js";
+export {
+  CHANGE_LOG,
+  IndexedDbPersistence,
+  KvWebPort,
+  createKvWebPort,
+  kvDatabaseName,
+  kvNamespace,
+  parsePageFactFields,
+  readPageFacts
+};

package/dist/kv.d.ts

@@ -0,0 +1,65 @@
+import { JsonValue } from '@almadar/core';
+import { Settled, OsError } from '@almadar/core/kernel-wire';
+
+/**
+ * The `kv` port of a browser kernel host: `kv/get|put|delete|scan|batch` over IndexedDB, with no Node builtin in sight.
+ * The grant check is the Rust `OsGrants` kv requirement, passed in as `allows`; this file only maps a verified request.
+ * One IndexedDB database per app and locale (`kv:<app>:<locale>`), one object store per kv store, out-of-line string keys.
+ */
+
+type KvOp = 'kv/get' | 'kv/put' | 'kv/delete' | 'kv/scan' | 'kv/batch';
+type KvMode = 'read' | 'write';
+/** One thing a `kv/` call needs from the program's grants: the JSON of the Rust `kv` requirement. */
+interface KvRequirement {
+    need: 'kv';
+    store: string;
+    mode: KvMode;
+}
+type KvBatchOp = {
+    kind: 'put';
+    key: string;
+    value: JsonValue;
+} | {
+    kind: 'delete';
+    key: string;
+};
+interface KvHostPort {
+    answer(op: KvOp, args: JsonValue[]): Promise<Settled<JsonValue, OsError>>;
+    defer?(op: KvOp, args: JsonValue[], key: string, deliver: (outcome: Settled<JsonValue, OsError>) => void): Settled<null, OsError>;
+    cancel?(key: string): boolean;
+    close(): void;
+}
+interface KvWebOptions {
+    app: string;
+    locale: string;
+    /** Defaults to `globalThis.indexedDB`; a host without one answers every ask `unsupported`. */
+    factory?: IDBFactory;
+    /** The wasm grant decision (`OsGrants` kv requirement). Absent means every request is allowed. */
+    allows?: (need: KvRequirement) => boolean;
+    /** Fails an ask with `timeout` when storage has not answered in this many milliseconds. */
+    timeoutMs?: number;
+}
+/** The namespace a kv store lives under: `kv:<app>:<locale>:<store>`. */
+declare function kvNamespace(app: string, locale: string, store: string): string;
+/** The IndexedDB database that holds every kv store of one app and locale. */
+declare function kvDatabaseName(app: string, locale: string): string;
+declare class KvWebPort implements KvHostPort {
+    private readonly options;
+    private db;
+    private lane;
+    private closed;
+    private readonly pending;
+    constructor(options: KvWebOptions);
+    private factory;
+    /** Open the database and create the store when missing, with a version bump, as the persistence adapter did. */
+    private handle;
+    private run;
+    answer(op: KvOp, args: JsonValue[]): Promise<Settled<JsonValue, OsError>>;
+    defer(op: KvOp, args: JsonValue[], key: string, deliver: (outcome: Settled<JsonValue, OsError>) => void): Settled<null, OsError>;
+    cancel(key: string): boolean;
+    close(): void;
+}
+declare function createKvWebPort(options: KvWebOptions): KvHostPort;
+
+export { KvWebPort, createKvWebPort, kvDatabaseName, kvNamespace };
+export type { KvBatchOp, KvHostPort, KvMode, KvOp, KvRequirement, KvWebOptions };

package/dist/kv.js

@@ -0,0 +1,12 @@
+import {
+  KvWebPort,
+  createKvWebPort,
+  kvDatabaseName,
+  kvNamespace
+} from "./chunk-7SDIX7W6.js";
+export {
+  KvWebPort,
+  createKvWebPort,
+  kvDatabaseName,
+  kvNamespace
+};

package/dist/page-facts.d.ts

@@ -0,0 +1,16 @@
+import { RuntimeValue, PageFactField, BrowserPageFacts } from '@almadar/core';
+
+/**
+ * `browser/page-facts`: the closed fact set, the argument check, and the page reader the client handler uses.
+ */
+
+/** The fields a `browser/page-facts` call asks for, or why the call is refused before anything is read. */
+declare function parsePageFactFields(value: RuntimeValue | undefined): {
+    fields: PageFactField[];
+} | {
+    error: string;
+};
+/** Read `fields` from the page in list order. No window or document is `available: false`; a throwing getter rejects. */
+declare function readPageFacts(fields: readonly PageFactField[]): BrowserPageFacts;
+
+export { parsePageFactFields, readPageFacts };

package/dist/page-facts.js

@@ -0,0 +1,8 @@
+import {
+  parsePageFactFields,
+  readPageFacts
+} from "./chunk-DTZ6GAB4.js";
+export {
+  parsePageFactFields,
+  readPageFacts
+};

package/dist/storage/index.d.ts

@@ -0,0 +1,61 @@
+import { EntityRow, PersistenceAdapter, WriteCapabilities, RowCommit } from '@almadar/core';
+
+/**
+ * IndexedDbPersistence — the browser store for `[persistent: x, browser]` entities.
+ *
+ * Implements the shared `PersistenceAdapter` contract, so the effect stage runs
+ * `fetch`/`persist` against it exactly as a server runs them against Firestore
+ * or Postgres. Sync-ready: minted ids are UUIDs, every write stamps `updatedAt`
+ * and appends to an ordered change log (`__changes`) a later sync can replay.
+ * It answers plain reads; the kernel filters, orders and windows rows itself. Writes arrive as one
+ * compare-and-commit of rows the kernel decided (EXEC-STORE-5), so the store holds no query or write semantics.
+ *
+ * @packageDocumentation
+ */
+
+/** Object store holding the append-only write log. */
+declare const CHANGE_LOG = "__changes";
+interface ChangeRecord {
+    op: "create" | "update" | "delete";
+    entityType: string;
+    id: string;
+    row: EntityRow | null;
+    at: string;
+}
+interface IndexedDbPersistenceOptions {
+    /** One database per app, e.g. `almadar:<app name>`. */
+    databaseName: string;
+    /** Every browser-stored entity type this store holds (one object store each). */
+    entityTypes: readonly string[];
+    /** IndexedDB implementation; defaults to the browser's `indexedDB`. */
+    factory?: IDBFactory;
+    /** Clock for `updatedAt` / change stamps; defaults to `new Date().toISOString()`. */
+    now?: () => string;
+}
+declare class IndexedDbPersistence implements PersistenceAdapter {
+    private readonly db;
+    private readonly entityTypes;
+    private readonly now;
+    private constructor();
+    /** Open (creating or upgrading) the database so it holds every listed entity type. */
+    static open(options: IndexedDbPersistenceOptions): Promise<IndexedDbPersistence>;
+    close(): void;
+    private store;
+    private write;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<EntityRow[]>;
+    writeCapabilities(_entityType: string): WriteCapabilities;
+    /** The kernel's decided rows, applied in one readwrite transaction only if each row still equals the version it read (EXEC-STORE-5). */
+    commitRows(rows: readonly RowCommit[]): Promise<boolean>;
+    countRows(entityType: string): Promise<number>;
+    /** The write log, oldest first — the seam a later `sync` replays. */
+    changes(): Promise<ChangeRecord[]>;
+}
+
+export { CHANGE_LOG, IndexedDbPersistence };
+export type { ChangeRecord, IndexedDbPersistenceOptions };

package/dist/storage/index.js

@@ -0,0 +1,8 @@
+import {
+  CHANGE_LOG,
+  IndexedDbPersistence
+} from "../chunk-GXG5PI2M.js";
+export {
+  CHANGE_LOG,
+  IndexedDbPersistence
+};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@almadar/shell-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Browser I/O ports for the Almadar TypeScript shell: IndexedDB, page facts and Firebase sign-in SDK.",
+  "license": "BUSL-1.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./kv": {
+      "types": "./dist/kv.d.ts",
+      "import": "./dist/kv.js"
+    },
+    "./page-facts": {
+      "types": "./dist/page-facts.d.ts",
+      "import": "./dist/page-facts.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@almadar/core": "^10.129.0",
+    "firebase": "^11.1.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "tsup": "^9.0.0",
+    "vitest": "^4.1.12",
+    "fake-indexeddb": "6.2.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/almadar-io/orbital-shell-typescript.git",
+    "directory": "hosts/browser"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.