@enbox/browser 0.3.70 → 0.3.71

package/src/blob-url-pool.ts

@@ -0,0 +1,55 @@
+import type { ObjectUrlLease } from './object-url-reference.js';
+
+import { ObjectUrlReference } from './object-url-reference.js';
+
+/**
+ * A reference-counted lease for a browser object URL.
+ *
+ * When replacing a URL already rendered by the DOM, `releaseAfter()` provides
+ * a grace period without passing the lease through the component tree.
+ */
+export type BlobUrlLease = ObjectUrlLease;
+
+/** Owns object URLs for Blob identities until their last lease is released. */
+export interface BlobUrlPool {
+  acquire(blob: Blob): BlobUrlLease;
+  dispose(): void;
+}
+
+class DefaultBlobUrlPool implements BlobUrlPool {
+  private readonly _references = new Map<Blob, ObjectUrlReference>();
+  private _isDisposed = false;
+
+  public acquire(blob: Blob): BlobUrlLease {
+    if (this._isDisposed) {
+      throw new Error('BlobUrlPool is disposed.');
+    }
+
+    let reference = this._references.get(blob);
+    if (reference === undefined) {
+      reference = new ObjectUrlReference(blob, (released): void => {
+        this._references.delete(blob);
+        released.revoke();
+      });
+      this._references.set(blob, reference);
+    }
+    return reference.acquire();
+  }
+
+  public dispose(): void {
+    if (this._isDisposed) {
+      return;
+    }
+
+    this._isDisposed = true;
+    for (const reference of this._references.values()) {
+      reference.revoke();
+    }
+    this._references.clear();
+  }
+}
+
+/** Create a terminally disposable, reference-counted object URL pool. */
+export function createBlobUrlPool(): BlobUrlPool {
+  return new DefaultBlobUrlPool();
+}

package/src/file-envelope-url-store.ts

@@ -0,0 +1,260 @@
+import type { FileEnvelopeData } from '@enbox/api';
+
+import type { BlobUrlLease } from './blob-url-pool.js';
+
+import { ObjectUrlReference } from './object-url-reference.js';
+
+const DEFAULT_MAX_BYTES = 128 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 50;
+
+type CacheEntry = {
+  bytes: number;
+  filename: string;
+  key: string;
+  mimeType: string;
+  url: ObjectUrlReference;
+};
+
+type PendingRead = {
+  controller: AbortController;
+  generation: number;
+  promise: Promise<CacheEntry | undefined>;
+};
+
+/** A cached file envelope represented by a leased browser object URL. */
+export type FileEnvelopeUrlLease = BlobUrlLease & Readonly<{
+  filename: string;
+  mimeType: string;
+}>;
+
+export type FileEnvelopeUrlStoreOptions<Request> = Readonly<{
+  /** Select the stable cache key for a read request. */
+  key(request: Request): string;
+  /** Read and decode the file. The signal aborts invalidated work. */
+  read(request: Request, signal: AbortSignal): Promise<FileEnvelopeData | undefined>;
+  /** Choose the Blob exposed by the URL, retaining MIME/render policy in the caller. */
+  blobForUrl(value: FileEnvelopeData): Blob;
+  /** Maximum cached entries (default 50). Soft while every eviction candidate is leased. */
+  maxEntries?: number;
+  /** Maximum cached Blob bytes (default 128 MiB). Soft while every eviction candidate is leased. */
+  maxBytes?: number;
+}>;
+
+/** A keyed, bounded object URL cache for decoded file envelopes. */
+export interface FileEnvelopeUrlStore<Request> {
+  acquire(request: Request): Promise<FileEnvelopeUrlLease | undefined>;
+  acquireCached(request: Request): FileEnvelopeUrlLease | undefined;
+  clear(): void;
+  dispose(): void;
+  invalidate(request: Request): void;
+}
+
+function assertLimit(value: number, name: string): void {
+  if (value !== Infinity && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new TypeError(`${name} must be a non-negative safe integer or Infinity.`);
+  }
+}
+
+function throwAborted(controller: AbortController): never {
+  controller.abort();
+  throw controller.signal.reason;
+}
+
+class DefaultFileEnvelopeUrlStore<Request> implements FileEnvelopeUrlStore<Request> {
+  private readonly _cache = new Map<string, CacheEntry>();
+  private readonly _entries = new Set<CacheEntry>();
+  private readonly _maxBytes: number;
+  private readonly _maxEntries: number;
+  private readonly _pending = new Map<string, PendingRead>();
+  private _bytes = 0;
+  private _generation = 0;
+  private _isDisposed = false;
+
+  public constructor(private readonly _options: FileEnvelopeUrlStoreOptions<Request>) {
+    this._maxBytes = _options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this._maxEntries = _options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    assertLimit(this._maxBytes, 'maxBytes');
+    assertLimit(this._maxEntries, 'maxEntries');
+  }
+
+  public async acquire(request: Request): Promise<FileEnvelopeUrlLease | undefined> {
+    this._assertActive();
+    const key = this._options.key(request);
+    const cached = this._cache.get(key);
+    if (cached !== undefined) {
+      return this._acquire(cached);
+    }
+
+    const pending = this._pending.get(key) ?? this._startRead(request, key);
+    const entry = await pending.promise;
+    if (this._isDisposed || pending.generation !== this._generation) {
+      return throwAborted(pending.controller);
+    }
+    if (entry === undefined) {
+      return undefined;
+    }
+    if (this._cache.get(key) !== entry) {
+      return throwAborted(pending.controller);
+    }
+    return this._acquire(entry);
+  }
+
+  public acquireCached(request: Request): FileEnvelopeUrlLease | undefined {
+    this._assertActive();
+    const entry = this._cache.get(this._options.key(request));
+    return entry === undefined ? undefined : this._acquire(entry);
+  }
+
+  public invalidate(request: Request): void {
+    this._assertActive();
+    const key = this._options.key(request);
+    const pending = this._pending.get(key);
+    pending?.controller.abort();
+    this._pending.delete(key);
+    const entry = this._cache.get(key);
+    if (entry !== undefined) {
+      this._remove(entry);
+    }
+  }
+
+  public clear(): void {
+    this._assertActive();
+    this._reset(false);
+  }
+
+  public dispose(): void {
+    if (this._isDisposed) {
+      return;
+    }
+
+    this._isDisposed = true;
+    this._reset(true);
+  }
+
+  private _abortReads(): void {
+    for (const pending of this._pending.values()) {
+      pending.controller.abort();
+    }
+    this._pending.clear();
+  }
+
+  private _acquire(entry: CacheEntry): FileEnvelopeUrlLease {
+    this._cache.delete(entry.key);
+    this._cache.set(entry.key, entry);
+    const lease = entry.url.acquire();
+    this._evict();
+    return Object.freeze({
+      filename     : entry.filename,
+      mimeType     : entry.mimeType,
+      release      : lease.release,
+      releaseAfter : lease.releaseAfter,
+      url          : lease.url,
+    });
+  }
+
+  private _assertActive(): void {
+    if (this._isDisposed) {
+      throw new Error('FileEnvelopeUrlStore is disposed.');
+    }
+  }
+
+  private _assertCurrent(key: string, controller: AbortController, generation: number): void {
+    if (
+      this._isDisposed
+      || controller.signal.aborted
+      || this._generation !== generation
+      || this._pending.get(key)?.controller !== controller
+    ) {
+      throwAborted(controller);
+    }
+  }
+
+  private _evict(): void {
+    while (this._cache.size > this._maxEntries || this._bytes > this._maxBytes) {
+      const entry = [...this._cache.values()].find((candidate): boolean => candidate.url.references === 0);
+      if (entry === undefined) {
+        return;
+      }
+      this._remove(entry);
+    }
+  }
+
+  private async _load(request: Request, key: string, controller: AbortController, generation: number): Promise<CacheEntry | undefined> {
+    const value = await this._options.read(request, controller.signal);
+    this._assertCurrent(key, controller, generation);
+    if (value === undefined) {
+      return undefined;
+    }
+
+    const blob = this._options.blobForUrl(value);
+    this._assertCurrent(key, controller, generation);
+    const url = new ObjectUrlReference(blob, (): void => this._released(entry));
+    const entry: CacheEntry = {
+      bytes    : blob.size,
+      filename : value.filename,
+      key,
+      mimeType : value.mimeType,
+      url,
+    };
+    this._cache.set(key, entry);
+    this._bytes += entry.bytes;
+    this._entries.add(entry);
+    return entry;
+  }
+
+  private _released(entry: CacheEntry): void {
+    if (this._cache.get(entry.key) !== entry) {
+      this._revoke(entry);
+    } else {
+      this._evict();
+    }
+  }
+
+  private _remove(entry: CacheEntry): void {
+    if (this._cache.get(entry.key) !== entry) {
+      return;
+    }
+    this._cache.delete(entry.key);
+    this._bytes -= entry.bytes;
+    if (entry.url.references === 0) {
+      this._revoke(entry);
+    }
+  }
+
+  private _reset(revokeActive: boolean): void {
+    this._generation += 1;
+    this._abortReads();
+    this._cache.clear();
+    this._bytes = 0;
+    for (const entry of this._entries) {
+      if (revokeActive || entry.url.references === 0) {
+        this._revoke(entry);
+      }
+    }
+  }
+
+  private _revoke(entry: CacheEntry): void {
+    entry.url.revoke();
+    this._entries.delete(entry);
+  }
+
+  private _startRead(request: Request, key: string): PendingRead {
+    const controller = new AbortController();
+    const generation = this._generation;
+    const promise = this._load(request, key, controller, generation).finally((): void => {
+      if (this._pending.get(key)?.controller === controller) {
+        this._pending.delete(key);
+      }
+    });
+    const pending = { controller, generation, promise };
+    this._pending.set(key, pending);
+    return pending;
+  }
+}
+
+/** Create a bounded file-envelope URL store with deduplicated reads. */
+export function createFileEnvelopeUrlStore<Request>(
+  options: FileEnvelopeUrlStoreOptions<Request>,
+): FileEnvelopeUrlStore<Request> {
+  return new DefaultFileEnvelopeUrlStore(options);
+}

package/src/index.ts

@@ -8,14 +8,17 @@
  * @example Single-import dapp setup
  * ```ts
  * import {
- *   Enbox, BrowserConnectHandler,
- *   defineProtocol, recordCodecs,
+ *   BrowserConnectHandler, createConnectionStore,
+ *   defineApplicationManifest,
  * } from '@enbox/browser';
+ * import { MyProtocol } from './my-protocol.js';
  *
- * const { enbox, session } = await Enbox.connect({
- *   connectHandler: BrowserConnectHandler({ appName: 'My App' }),
- *   protocols: [MyProtocol],
+ * const store = createConnectionStore({
+ *   application    : defineApplicationManifest({ protocols: [MyProtocol] }),
+ *   connectHandler : BrowserConnectHandler({ appName: 'My App' }),
  * });
+ * const snapshot = await store.connect();
+ * if (snapshot.phase !== 'connected') throw snapshot.error ?? new Error('Connection failed.');
  * ```
  *
  * For non-browser environments (Node.js, CLI, desktop), import from
@@ -28,150 +31,13 @@
 //
 // The high-level Enbox API: DWN records and protocols.
 
-export {
-  AudienceDecryptError,
-  createConnectionStore,
-  ContextNotReadyError,
-  ContextRetiredError,
-  defineApplicationManifest,
-  DwnResponseError,
-  Enbox,
-  defineProtocol,
-  getApplicationProtocolRequests,
-  ProtocolReadinessError,
-  RecordConflictError,
-  RecordParentNotFoundError,
-  RecordSquashBackstopError,
-  RecordValidationError,
-  protocolContextKey,
-  recordCodecs,
-  ServiceConfigProtocol,
-} from '@enbox/api';
-
-export type {
-  ApplicationConnectionStore,
-  ApplicationConnectionStoreConnectOptions,
-  ApplicationConnectionStoreOptions,
-  ApplicationConnectionStoreRefreshOptions,
-  ApplicationManifest,
-  ApplicationManifestProtocol,
-  ApplicationManifestProtocolInput,
-  AudienceDecryptFailureCause,
-  ConnectionPhase,
-  ConnectionSnapshot,
-  ConnectionSnapshotListener,
-  ConnectionStore,
-  ConnectionStoreOptions,
-  ContextView,
-  ContextViewListener,
-  ContextViewState,
-  ContextMember,
-  ContextMembersApi,
-  ContextInvitation,
-  ContextInvitationPreview,
-  ContextInvitationsApi,
-  ContextMaterializedRecord,
-  ContextRecord,
-  ContextRecordDeleteParams,
-  ContextRecordsApi,
-  ContextRecordUpdateParams,
-  ContextRoleGroup,
-  ContextRoleGroups,
-  ContextRolePath,
-  ContextsApi,
-  DataForPath,
-  DefineApplicationManifestOptions,
-  DwnEndpointResolution,
-  EnboxAnonymousOptions,
-  EnboxConnectOptions,
-  EnboxConnectResult,
-  EnboxParams,
-  EnboxSessionParams,
-  EncodedRecordData,
-  EnsureProtocolsReadyOptions,
-  ExpandableRecordView,
-  FileEnvelopeCodec,
-  FileEnvelopeCodecOptions,
-  FileEnvelopeData,
-  FollowContextOptions,
-  JsonRecordCodecOptions,
-  MaterializedMemberContext,
-  MaterializedRecord,
-  MemberContext,
-  OwnedContext,
-  ProtocolContext,
-  ProtocolRolePaths,
-  SquashProtocolPaths,
-  RecordCodec,
-  RecordCodecContext,
-  RecordCodecValue,
-  RecordFilter,
-  RecordPage,
-  RecordPatch,
-  RecordPatchInput,
-  RecordQuery,
-  RecordSubscription,
-  RecordSubscriptionEvent,
-  RecordSubscriptionListener,
-  RecordView,
-  RecordViewListener,
-  RecordViewState,
-  RecordValidationFailure,
-  RecordValidator,
-  ReplicationCurrentness,
-  RoleDeliveryState,
-  SyncStatusSnapshot,
-  TypedMaterializedRecord,
-  TypedRecord,
-} from '@enbox/api';
+export * from '@enbox/api';
 
 // ─── Re-exports from @enbox/auth ────────────────────────────────
 //
 // Authentication lifecycle, session management, connect handlers.
 
-export {
-  AuthManager,
-  AuthSession,
-  ConnectDeniedError,
-  SESSION_EXPIRED_ERROR_CODE,
-  SESSION_REVOKED_ERROR_CODE,
-  computeConnectionStatus,
-  isConnectDeniedError,
-  isSessionExpiredError,
-  isSessionInvalidError,
-  normalizeProtocolRequests,
-  WalletConnect,
-} from '@enbox/auth/browser';
-
-export type {
-  AuthEvent,
-  AuthEventHandler,
-  AuthManagerOptions,
-  AuthState,
-  ComputeConnectionStatusOptions,
-  ConnectionMonitorOptions,
-  ConnectionState,
-  ConnectionStatus,
-  ConnectionStatusGrant,
-  ConnectHandler,
-  ConnectOptions,
-  ConnectResult,
-  DisconnectOptions,
-  GetConnectionStatusOptions,
-  HandlerConnectOptions,
-  ImportFromPortableOptions,
-  VaultConnectOptions,
-  Permission,
-  PortableIdentity,
-  ProtocolDefinitionCarrier,
-  ProtocolPermissionRequest,
-  ProtocolRequest,
-  RefreshOptions,
-  RegistrationOptions,
-  StorageAdapter,
-  SyncOption,
-  WalletConnectOptions,
-} from '@enbox/auth/browser';
+export * from '@enbox/auth/browser';
 
 // ─── Re-exports from @enbox/connect ─────────────────────────────
 //
@@ -179,7 +45,7 @@ export type {
 // transports: opening/sealing envelopes and the deny token.
 
 export { CONNECT_DENIED_TOKEN, ConnectProvider } from '@enbox/connect';
-export type { ConnectApproval, ConnectPermissionRequest, ConnectRequest, ConnectRequestType } from '@enbox/connect';
+export type { ConnectApproval, ConnectRequest } from '@enbox/connect';
 
 // ─── Browser-specific exports ───────────────────────────────────
 //
@@ -213,6 +79,14 @@ export { MAX_PIN_ATTEMPTS, RelayConnectCancelledError, runRelayConnect } from '.
 export type { RelayConnectOptions } from './relay-connect-runner.js';
 export { encodeQr, qrToSvg } from './ui/qr.js';
 export type { QrCode, QrSvgOptions } from './ui/qr.js';
+export { createBlobUrlPool } from './blob-url-pool.js';
+export type { BlobUrlLease, BlobUrlPool } from './blob-url-pool.js';
+export { createFileEnvelopeUrlStore } from './file-envelope-url-store.js';
+export type {
+  FileEnvelopeUrlLease,
+  FileEnvelopeUrlStore,
+  FileEnvelopeUrlStoreOptions,
+} from './file-envelope-url-store.js';
 
 // ─── Convenience re-exports for dapps ───────────────────────────
 //
@@ -222,14 +96,6 @@ export type { QrCode, QrSvgOptions } from './ui/qr.js';
 // more specialized is still available by importing the underlying package
 // directly.
 
-// Canonical typed record (from @enbox/api).
-export { Record } from '@enbox/api';
-
-// Custom storage adapter + DWN registration provider-auth callback shapes
-// (from @enbox/auth).
-export { BrowserStorage } from '@enbox/auth/browser';
-export type { ProviderAuthParams, ProviderAuthResult } from '@enbox/auth/browser';
-
 // Public-profile read/cache layer (from @enbox/protocols): fetch other
 // users' published profiles (displayName + avatar/hero) from their DWNs
 // with caching, retries, negative caching, and refcounted subscriptions.
@@ -255,12 +121,9 @@ export type {
 // DWN interface enum for typing agent requests (from @enbox/agent).
 export { DwnInterface } from '@enbox/agent';
 
-// Sync-status observability for dapp "remotes" panels (from @enbox/agent).
-// Subscribe with `agent.sync.on(event => …)` and snapshot per-remote health
-// (healthy / quota-blocked / degraded / offline), including when a
-// quota-blocked remote will next be re-probed, via
-// `agent.sync.getRemoteSyncStatus()`; resume immediately with
-// `agent.sync.retryRemoteNow(tenantDid, remoteEndpoint)`.
+// Low-level sync-status types for advanced agent consumers. Dapps using a
+// ConnectionStore receive current advertised rows through `snapshot.sync.remotes`
+// and can call `store.retryRemote(remoteEndpoint)` without wiring agent events.
 export type {
   DeadLetterEntry,
   RemoteSyncState,
@@ -270,6 +133,7 @@ export type {
   SyncEvent,
   SyncEventListener,
   SyncHealthSummary,
+  SyncIdentityStatus,
 } from '@enbox/agent';
 
 // Common DWN primitives for record queries, permission scopes, and protocol

package/src/object-url-reference.ts

@@ -0,0 +1,82 @@
+export type ObjectUrlLease = Readonly<{
+  url: string;
+  /** Release immediately, cancelling any deferred release. Idempotent. */
+  release(): void;
+  /** Release after a grace period. The first deferred release wins. */
+  releaseAfter(delayMs: number): void;
+}>;
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+function assertReleaseDelay(delayMs: number): void {
+  if (!Number.isSafeInteger(delayMs) || delayMs < 0 || delayMs > MAX_TIMER_DELAY_MS) {
+    throw new TypeError(`delayMs must be an integer between 0 and ${MAX_TIMER_DELAY_MS}.`);
+  }
+}
+
+/** Private reference-counted ownership for one object URL. */
+export class ObjectUrlReference {
+  public readonly url: string;
+  private _isRevoked = false;
+  private _references = 0;
+  private readonly _releaseTimers = new Set<ReturnType<typeof setTimeout>>();
+
+  public constructor(blob: Blob, private readonly _onEmpty: (reference: ObjectUrlReference) => void) {
+    this.url = globalThis.URL.createObjectURL(blob);
+  }
+
+  public get references(): number {
+    return this._references;
+  }
+
+  public acquire(): ObjectUrlLease {
+    if (this._isRevoked) {
+      throw new Error('Object URL has been revoked.');
+    }
+
+    this._references += 1;
+    let released = false;
+    let releaseTimer: ReturnType<typeof setTimeout> | undefined;
+    const release = (): void => {
+      if (released) {
+        return;
+      }
+      released = true;
+      if (releaseTimer !== undefined) {
+        clearTimeout(releaseTimer);
+        this._releaseTimers.delete(releaseTimer);
+      }
+      if (this._isRevoked) {
+        return;
+      }
+      this._references -= 1;
+      if (this._references === 0) {
+        this._onEmpty(this);
+      }
+    };
+    return Object.freeze({
+      url          : this.url,
+      release,
+      releaseAfter : (delayMs: number): void => {
+        assertReleaseDelay(delayMs);
+        if (released || this._isRevoked || releaseTimer !== undefined) {
+          return;
+        }
+        releaseTimer = setTimeout(release, delayMs);
+        this._releaseTimers.add(releaseTimer);
+      },
+    });
+  }
+
+  public revoke(): void {
+    if (!this._isRevoked) {
+      this._isRevoked = true;
+      for (const timer of this._releaseTimers) {
+        clearTimeout(timer);
+      }
+      this._releaseTimers.clear();
+      this._references = 0;
+      globalThis.URL.revokeObjectURL(this.url);
+    }
+  }
+}