@vrtmrz/livesync-commonlib 0.1.0 → 0.1.1-rc.0

package/README.md

@@ -1,6 +1,6 @@
 # Self-hosted LiveSync Commonlib
 
-Commonlib is the ESM package which provides shared data, storage, replication, and host-context primitives for Self-hosted LiveSync, its CLI, Webapp, and WebPeer.
+Commonlib is the ESM package which provides shared data, storage, replication, and host-context primitives for Self-hosted LiveSync, its CLI, WebApp, WebPeer, and LiveSync Bridge.
 
 This package is primarily for maintainers of those clients and for integrations which deliberately reuse a reviewed Commonlib contract. It is not yet a general-purpose LiveSync SDK: the package does not provide a stable end-to-end client factory or own host UI, permissions, credentials, process lifecycle, or application persistence.
 
@@ -127,7 +127,7 @@ Package developers should read [the developer guide](docs/development.md). The f
 
 ## Proven in maintained hosts
 
-The package boundary is exercised by Self-hosted LiveSync's Obsidian plug-in, CLI, Webapp, and WebPeer compositions. Their validation is not uniform: the Obsidian plug-in and CLI have the strongest real-runtime and cross-host evidence, while the Webapp and WebPeer currently provide focused adapter, type-check, and build evidence.
+The package boundary is exercised by Self-hosted LiveSync's Obsidian plug-in, CLI, WebApp, and WebPeer compositions. Their validation is not uniform: the Obsidian plug-in and CLI have the strongest device and long-running synchronisation evidence, while WebApp and WebPeer have focused adapter and runtime tests, browser smoke tests, a cross-application P2P scenario ending at the production CLI, and public Pages smoke validation.
 
 See [Proven in maintained hosts](docs/proven-in-use.md) for the actual composition points, downstream tests, and remaining limits. The examples deliberately separate focused public entries which a new consumer may copy from `compat/*` imports which exist to migrate the current application.
 

package/dist/API/DirectFileManipulator.d.ts

@@ -1,2 +1,2 @@
 export { DirectFileManipulator } from "./DirectFileManipulatorV2.js";
-export type { DirectFileManipulatorOptions } from "./DirectFileManipulatorV2.js";
+export type { DirectFileManipulatorOptions, DirectFileManipulatorRuntimeOptions, } from "./DirectFileManipulatorV2.js";

package/dist/API/DirectFileManipulatorV2.d.ts

@@ -1,7 +1,7 @@
 /**
  * The API for manipulating files stored in the CouchDB by Self-hosted LiveSync or its families.
  */
-import { type DocumentID, type FilePathWithPrefix, type EntryHasPath, type FilePath, type EntryDoc, type NewEntry, type PlainEntry, type LoadedEntry, type HashAlgorithm, type RemoteDBSettings, type ChunkSplitterVersion, type SyncParameters, type E2EEAlgorithm } from "../common/types.js";
+import { type DocumentID, type FilePathWithPrefix, type EntryHasPath, type FilePath, type EntryDoc, type NewEntry, type PlainEntry, type LoadedEntry, type HashAlgorithm, type ObsidianLiveSyncSettings, type RemoteDBSettings, type ChunkSplitterVersion, type SyncParameters, type E2EEAlgorithm } from "../common/types.js";
 import { LiveSyncLocalDB, type LiveSyncLocalDBEnv } from "../pouchdb/LiveSyncLocalDB.js";
 import { HeadlessServiceHub } from "../services/HeadlessServices.js";
 import { HeadlessDatabaseService } from "../services/implements/headless/HeadlessDatabaseService.js";
@@ -34,6 +34,11 @@ export type DirectFileManipulatorOptions = {
     chunkSplitterVersion?: ChunkSplitterVersion;
     E2EEAlgorithm?: E2EEAlgorithm;
 };
+/** Host runtime capabilities used by a direct CouchDB connection. */
+export type DirectFileManipulatorRuntimeOptions = Readonly<{
+    /** Fetch implementation passed to PouchDB. Omit it to use PouchDB's default transport. */
+    fetch?: typeof globalThis.fetch;
+}>;
 export type ReadyEntry = (NewEntry | PlainEntry) & {
     data: string[];
 };
@@ -54,6 +59,7 @@ export type EnumerateConditions = {
 export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
     liveSyncLocalDB: LiveSyncLocalDB;
     options: DirectFileManipulatorOptions;
+    readonly runtimeOptions: DirectFileManipulatorRuntimeOptions;
     ready: {
         promise: Promise<void>;
         resolve: (value: void | PromiseLike<void>) => void;
@@ -61,8 +67,8 @@ export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
     };
     services: HeadlessServiceHub<ServiceContext>;
     init(): Promise<void>;
-    getBoundDatabaseService(options: () => DirectFileManipulatorOptions): typeof HeadlessDatabaseService;
-    constructor(options: DirectFileManipulatorOptions);
+    getBoundDatabaseService(options: () => DirectFileManipulatorOptions, runtimeOptions: DirectFileManipulatorRuntimeOptions): typeof HeadlessDatabaseService;
+    constructor(options: DirectFileManipulatorOptions, runtimeOptions?: DirectFileManipulatorRuntimeOptions);
     $$id2path(id: DocumentID, entry?: EntryHasPath, stripPrefix?: boolean): FilePathWithPrefix;
     $$path2id(filename: FilePathWithPrefix | FilePath, prefix?: string): Promise<DocumentID>;
     getInitialSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
@@ -73,7 +79,7 @@ export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
     getSettings(): RemoteDBSettings;
     close(): Promise<void>;
     path2id(filename: FilePathWithPrefix | FilePath, prefix?: string): Promise<DocumentID>;
-    get settings(): RemoteDBSettings;
+    get settings(): ObsidianLiveSyncSettings;
     /**
      * Get specific document from the Remote Database by path.
      * @param path
@@ -103,7 +109,7 @@ export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
     enumerate(_cond: EnumerateConditions): AsyncGenerator<never, void, unknown>;
     _enumerate(startKey: string, endKey: string, opt: {
         metaOnly: boolean;
-    }): AsyncGenerator<ReadyEntry, AsyncGenerator<(import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
+    }): AsyncGenerator<(import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
         path: FilePathWithPrefix;
         children: string[];
         type: import("../common/models/db.type.js").EntryTypes["NOTE_BINARY"];
@@ -111,39 +117,18 @@ export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
         path: FilePathWithPrefix;
         children: string[];
         type: import("../common/models/db.type.js").EntryTypes["NOTE_PLAIN"];
-    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | (import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
-        path: FilePathWithPrefix;
-        children: string[];
-        type: import("../common/models/db.type.js").EntryTypes["NOTE_BINARY"];
-    } & {
-        deleted?: boolean;
-    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | (import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
+    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | ReadyEntry, void, unknown>;
+    enumerateAllNormalDocs(opt: {
+        metaOnly: boolean;
+    }): AsyncGenerator<(import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
         path: FilePathWithPrefix;
         children: string[];
         type: import("../common/models/db.type.js").EntryTypes["NOTE_BINARY"];
-    } & {
-        data: string | string[];
-        datatype: import("../common/types.js").EntryTypeNotes;
     } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | (import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
         path: FilePathWithPrefix;
         children: string[];
         type: import("../common/models/db.type.js").EntryTypes["NOTE_PLAIN"];
-    } & {
-        data: string | string[];
-        datatype: import("../common/types.js").EntryTypeNotes;
-    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | (import("../common/types.js").DatabaseEntry & import("../common/types.js").EntryBase & import("../common/types.js").EntryWithEden & {
-        path: FilePathWithPrefix;
-        children: string[];
-        type: import("../common/models/db.type.js").EntryTypes["NOTE_BINARY"];
-    } & {
-        deleted?: boolean;
-    } & {
-        data: string | string[];
-        datatype: import("../common/types.js").EntryTypeNotes;
-    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta), void, unknown>, unknown>;
-    enumerateAllNormalDocs(opt: {
-        metaOnly: boolean;
-    }): AsyncGenerator<ReadyEntry, void, unknown>;
+    } & PouchDB.Core.AllDocsMeta & PouchDB.Core.IdMeta & PouchDB.Core.RevisionIdMeta) | ReadyEntry, void, unknown>;
     watching: boolean;
     changes: PouchDB.Core.Changes<EntryDoc> | undefined;
     since: string;

package/dist/API/DirectFileManipulatorV2.js

@@ -42,32 +42,45 @@ function isReadyEntry(doc) {
 class DirectFileManipulator {
   liveSyncLocalDB;
   options;
+  runtimeOptions;
   ready = promiseWithResolvers();
   services;
   async init() {
-    await this.services.appLifecycle.onReady();
-    await this.liveSyncLocalDB.initializeDatabase();
-    this.ready.resolve();
-    this.liveSyncLocalDB.refreshSettings();
+    try {
+      await this.services.appLifecycle.onReady();
+      await this.liveSyncLocalDB.initializeDatabase();
+      this.liveSyncLocalDB.refreshSettings();
+      this.ready.resolve();
+    } catch (error) {
+      this.ready.reject(error);
+    }
   }
-  getBoundDatabaseService(options) {
+  getBoundDatabaseService(options, runtimeOptions) {
     const _option = options;
+    const _runtimeOptions = runtimeOptions;
     return class HeadlessDatabaseServiceExt extends HeadlessDatabaseService {
       createPouchDBInstance(_name, _options) {
         const option = _option();
-        return new PouchDB(option.url + "/" + option.database, {
+        const pouchDBOptions = {
           auth: { username: option.username, password: option.password }
-        });
+        };
+        if (_runtimeOptions.fetch) {
+          pouchDBOptions.fetch = _runtimeOptions.fetch;
+        }
+        return new PouchDB(option.url + "/" + option.database, pouchDBOptions);
       }
     };
   }
-  constructor(options) {
+  constructor(options, runtimeOptions = {}) {
     this.options = options;
+    this.runtimeOptions = runtimeOptions;
     const getSettings = () => this.settings;
     const context = new ServiceContext();
     this.services = new HeadlessServiceHub(context, {
       pouchDB: PouchDB,
-      database: this.getBoundDatabaseService(() => this.options)
+      database: this.getBoundDatabaseService(() => this.options, this.runtimeOptions),
+      getPathObfuscationPassphrase: () => this.options.obfuscatePassphrase ?? false,
+      databaseLifecycleMode: "direct-access"
     });
     this.services.setting.saveData.setHandler((data) => {
       console.warn("Saving settings is not supported in DirectFileManipulator.");
@@ -77,8 +90,11 @@ class DirectFileManipulator {
       console.warn("Loading settings is not supported in DirectFileManipulator.");
       return Promise.resolve(getSettings());
     });
+    this.services.setting.settings = getSettings();
     this.services.databaseEvents.onDatabaseInitialisation.addHandler(this.$everyOnInitializeDatabase.bind(this));
     this.liveSyncLocalDB = new LiveSyncLocalDB(this.options.url, this);
+    void this.ready.promise.catch(() => {
+    });
     void this.init();
   }
   $$id2path(id, entry, stripPrefix) {
@@ -190,6 +206,7 @@ class DirectFileManipulator {
         endpoint: "",
         enableCompression: this.options.enableCompression ?? DEFAULT_SETTINGS.enableCompression,
         handleFilenameCaseSensitive: this.options.handleFilenameCaseSensitive ?? DEFAULT_SETTINGS.handleFilenameCaseSensitive,
+        usePathObfuscation: !!this.options.obfuscatePassphrase,
         E2EEAlgorithm: this.options.E2EEAlgorithm ?? E2EEAlgorithms.V2
       }
     };
@@ -289,7 +306,7 @@ class DirectFileManipulator {
   async *enumerate(_cond) {
   }
   async *_enumerate(startKey, endKey, opt) {
-    if (opt.metaOnly) return this.liveSyncLocalDB.findEntries(startKey, endKey, {});
+    if (opt.metaOnly) return yield* this.liveSyncLocalDB.findEntries(startKey, endKey, {});
     for await (const f of this.liveSyncLocalDB.findEntries(startKey, endKey, {})) {
       yield await this.getByMeta(f);
     }
@@ -337,7 +354,14 @@ class DirectFileManipulator {
         }
       }
       Logger(`WATCH: PROCESSING: ${doc.path}`, LEVEL_VERBOSE, "watch");
-      const docX = await this.getByMeta(doc);
+      let docX;
+      try {
+        docX = await this.getByMeta(doc);
+      } catch (ex) {
+        Logger(`WATCH: DOCUMENT LOAD FAILED: ${doc.path}`, LEVEL_INFO, "watch");
+        Logger(ex, LEVEL_VERBOSE, "watch");
+        return;
+      }
       try {
         await callback(docX, change.seq);
         Logger(`WATCH: PROCESS DONE: ${doc.path}`, LEVEL_INFO, "watch");

package/dist/index.d.ts

@@ -1 +1 @@
-export { DirectFileManipulator, type DirectFileManipulatorOptions } from "./API/DirectFileManipulator.js";
+export { DirectFileManipulator, type DirectFileManipulatorOptions, type DirectFileManipulatorRuntimeOptions, } from "./API/DirectFileManipulator.js";

package/dist/index.js

@@ -1,4 +1,6 @@
-import { DirectFileManipulator } from "./API/DirectFileManipulator.js";
+import {
+  DirectFileManipulator
+} from "./API/DirectFileManipulator.js";
 export {
   DirectFileManipulator
 };

package/dist/managers/LiveSyncManagers.js

@@ -56,7 +56,7 @@ class LiveSyncManagers {
   }
   getManagerMembers() {
     this.log("Creating LiveSync Managers...");
-    const database = this.options.databaseService.localDatabase.localDatabase;
+    const database = this.options.database;
     const changeManager = new ChangeManager({
       database
     });

package/dist/services/HeadlessServices.d.ts

@@ -12,5 +12,9 @@ export declare class HeadlessServiceHub<T extends ServiceContext> extends Inject
         database?: Constructor<DatabaseService<T>>;
         openKeyValueDatabase?: KeyValueDatabaseFactory;
         onDisplayLanguageChanged?: (language: ObsidianLiveSyncSettings["displayLanguage"]) => void;
+        /** Optional host capability when path obfuscation uses a secret distinct from content encryption. */
+        getPathObfuscationPassphrase?: () => string | false;
+        /** Direct database clients do not run application-level replication or key-value database lifecycles. */
+        databaseLifecycleMode?: "application" | "direct-access";
     });
 }

package/dist/services/HeadlessServices.js

@@ -50,6 +50,7 @@ class HeadlessUIService extends UIService {
 class HeadlessServiceHub extends InjectableServiceHub {
   constructor(_context, overrideServiceConstructor) {
     const context = _context ?? new ServiceContext();
+    const registerApplicationDatabaseLifecycle = (overrideServiceConstructor.databaseLifecycleMode ?? "application") === "application";
     const API = new HeadlessAPIService(context);
     const conflict = new InjectableConflictService(context);
     const fileProcessing = new InjectableFileProcessingService(context);
@@ -74,7 +75,8 @@ class HeadlessServiceHub extends InjectableServiceHub {
     const test = new InjectableTestService(context);
     const databaseEvents = new InjectableDatabaseEventService(context);
     const path = new PathServiceCompat(context, {
-      settingService: setting
+      settingService: setting,
+      getPathObfuscationPassphrase: overrideServiceConstructor.getPathObfuscationPassphrase
     });
     const database = new (overrideServiceConstructor.database ?? HeadlessDatabaseService)(context, {
       pouchDB: overrideServiceConstructor.pouchDB,
@@ -90,7 +92,8 @@ class HeadlessServiceHub extends InjectableServiceHub {
     const replicator = new InjectableReplicatorService(context, {
       settingService: setting,
       appLifecycleService: appLifecycle,
-      databaseEventService: databaseEvents
+      databaseEventService: databaseEvents,
+      registerLifecycleHandlers: registerApplicationDatabaseLifecycle
     });
     const replication = new InjectableReplicationService(context, {
       APIService: API,
@@ -104,7 +107,8 @@ class HeadlessServiceHub extends InjectableServiceHub {
       openKeyValueDatabase: overrideServiceConstructor.openKeyValueDatabase ?? createIndexedDBKeyValueDatabaseFactory(),
       appLifecycle,
       databaseEvents,
-      vault
+      vault,
+      registerLifecycleHandlers: registerApplicationDatabaseLifecycle
     });
     const control = new ControlService(context, {
       appLifecycleService: appLifecycle,

package/dist/services/base/KeyValueDBService.d.ts

@@ -9,6 +9,7 @@ export interface KeyValueDBDependencies<T extends ServiceContext = ServiceContex
     databaseEvents: InjectableDatabaseEventService<T>;
     vault: IVaultService;
     appLifecycle: AppLifecycleServiceBase<T>;
+    registerLifecycleHandlers?: boolean;
 }
 /**
  * The KeyValueDBService provides methods for managing the local key-value database.

package/dist/services/base/KeyValueDBService.js

@@ -93,11 +93,13 @@ class KeyValueDBService extends ServiceBase {
     this.vault = dependencies.vault;
     this.appLifecycle = dependencies.appLifecycle;
     this.openKeyValueDatabase = dependencies.openKeyValueDatabase;
-    this.databaseEvents.onResetDatabase.addHandler(this._everyOnResetDatabase.bind(this));
-    this.appLifecycle.onSettingLoaded.addHandler(this._everyOnloadAfterLoadSettings.bind(this));
-    this.databaseEvents.onDatabaseInitialisation.addHandler(this._everyOnInitializeDatabase.bind(this));
-    this.databaseEvents.onUnloadDatabase.addHandler(this._onOtherDatabaseUnload.bind(this));
-    this.databaseEvents.onCloseDatabase.addHandler(this._onOtherDatabaseClose.bind(this));
+    if (dependencies.registerLifecycleHandlers ?? true) {
+      this.databaseEvents.onResetDatabase.addHandler(this._everyOnResetDatabase.bind(this));
+      this.appLifecycle.onSettingLoaded.addHandler(this._everyOnloadAfterLoadSettings.bind(this));
+      this.databaseEvents.onDatabaseInitialisation.addHandler(this._everyOnInitializeDatabase.bind(this));
+      this.databaseEvents.onUnloadDatabase.addHandler(this._onOtherDatabaseUnload.bind(this));
+      this.databaseEvents.onCloseDatabase.addHandler(this._onOtherDatabaseClose.bind(this));
+    }
   }
   openSimpleStore(kind) {
     const getDB = () => {

package/dist/services/base/PathService.d.ts

@@ -4,6 +4,11 @@ import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 import type { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../../common/models/shared.const.symbols.js";
 export interface PathServiceDependencies {
     settingService: ISettingService;
+    /**
+     * Optional host capability for consumers which keep content encryption and
+     * path-obfuscation passphrases separate.
+     */
+    getPathObfuscationPassphrase?: () => string | false;
 }
 /**
  * The PathService provides methods for converting between file paths and document IDs.
@@ -11,6 +16,7 @@ export interface PathServiceDependencies {
  */
 export declare abstract class PathService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IPathService {
     protected settingService: ISettingService;
+    private readonly getPathObfuscationPassphrase?;
     protected abstract normalizePath(path: string): string;
     get settings(): import("../../common/types.js").ObsidianLiveSyncSettings;
     constructor(context: T, dependencies: PathServiceDependencies);

package/dist/services/base/PathService.js

@@ -3,12 +3,14 @@ import { addPrefix, id2path_base, path2id_base } from "../../string_and_binary/p
 import { isInternalMetadata, stripInternalMetadataPrefix } from "../../common/typeUtils.js";
 class PathService extends ServiceBase {
   settingService;
+  getPathObfuscationPassphrase;
   get settings() {
     return this.settingService.currentSettings();
   }
   constructor(context, dependencies) {
     super(context);
     this.settingService = dependencies.settingService;
+    this.getPathObfuscationPassphrase = dependencies.getPathObfuscationPassphrase;
   }
   _id2path(id, entry) {
     const filename = id2path_base(id, entry);
@@ -51,9 +53,10 @@ class PathService extends ServiceBase {
   async path2id(filename, prefix) {
     const destPath = addPrefix(filename, prefix ?? "");
     const setting = this.settings;
+    const pathObfuscationPassphrase = this.getPathObfuscationPassphrase?.() ?? (setting.usePathObfuscation ? setting.passphrase : false);
     return await this._path2id(
       destPath,
-      setting.usePathObfuscation ? setting.passphrase : "",
+      pathObfuscationPassphrase,
       !setting.handleFilenameCaseSensitive
     );
   }

package/dist/services/base/ReplicatorService.d.ts

@@ -11,6 +11,7 @@ export interface ReplicatorServiceDependencies {
     appLifecycleService: AppLifecycleService;
     databaseEventService: DatabaseEventService;
     activityRunner?: AsyncActivityRunner;
+    registerLifecycleHandlers?: boolean;
 }
 /**
  * The ReplicatorService provides methods for managing replication.

package/dist/services/base/ReplicatorService.js

@@ -17,13 +17,15 @@ class ReplicatorService extends ServiceBase {
     this.appLifecycleService = dependencies.appLifecycleService;
     this._unresolvedErrorManager = new UnresolvedErrorManager(dependencies.appLifecycleService, this.context.events);
     this.settingService = dependencies.settingService;
-    this.settingService.onRealiseSetting.addHandler(this._initialiseReplicator.bind(this));
     this.databaseEventService = dependencies.databaseEventService;
-    this.databaseEventService.onResetDatabase.addHandler(this.disposeReplicator.bind(this));
-    this.databaseEventService.onDatabaseInitialisation.addHandler(this.disposeReplicator.bind(this));
-    this.databaseEventService.onDatabaseInitialised.addHandler(this.reinitialiseReplicator.bind(this));
-    this.databaseEventService.onDatabaseHasReady.addHandler(this.reinitialiseReplicator.bind(this));
-    this.appLifecycleService.onSuspending.addHandler(this.suspendReplication.bind(this));
+    if (dependencies.registerLifecycleHandlers ?? true) {
+      this.settingService.onRealiseSetting.addHandler(this._initialiseReplicator.bind(this));
+      this.databaseEventService.onResetDatabase.addHandler(this.disposeReplicator.bind(this));
+      this.databaseEventService.onDatabaseInitialisation.addHandler(this.disposeReplicator.bind(this));
+      this.databaseEventService.onDatabaseInitialised.addHandler(this.reinitialiseReplicator.bind(this));
+      this.databaseEventService.onDatabaseHasReady.addHandler(this.reinitialiseReplicator.bind(this));
+      this.appLifecycleService.onSuspending.addHandler(this.suspendReplication.bind(this));
+    }
   }
   dependencies;
   boundedRemoteActivityCount = reactiveSource(0);

package/dist/services/implements/base/SvelteDialog.d.ts

@@ -66,6 +66,11 @@ export interface SvelteDialogInstance<T, U, C extends ServiceContext = ServiceCo
 export type SvelteDialogClass<TBase extends Constructor<IModalBase>> = {
     new <T, U, C extends ServiceContext = ServiceContext>(...args: ConstructorParameters<TBase>): SvelteDialogInstance<T, U, C>;
 };
+/**
+ * Adds Svelte dialogue state to a modal class through dynamic inheritance.
+ *
+ * @deprecated Compose the dialogue lifecycle explicitly in the owning host.
+ */
 export declare function SvelteDialogMixIn<TBase extends Constructor<IModalBase>>(TBase: TBase, d: Component<DialogHostProps>): SvelteDialogClass<TBase>;
 export declare abstract class SvelteDialogManagerBase<T extends ServiceContext> implements SvelteDialogManager<T> {
     abstract openSvelteDialog<T, U = T>(component: ComponentHasResult<T, U>, initialData?: U): Promise<T | undefined>;

package/dist/services/implements/headless/HeadlessAPIService.js

@@ -1,6 +1,7 @@
 import { InjectableAPIService } from "../injectable/InjectableAPIService.js";
 import module from "node:crypto";
 import { _activeDocument } from "../../../common/coreEnvFunctions.js";
+import { Logger } from "../../../common/logger.js";
 class HeadlessConfirm {
   askYesNo(message) {
     console.error(`[Headless] ${message} \u2192 no`);
@@ -37,6 +38,7 @@ class HeadlessAPIService extends InjectableAPIService {
   constructor(context) {
     super(context);
     this._confirmInstance = new HeadlessConfirm();
+    this.addLog.setHandler(Logger);
   }
   get confirm() {
     return this._confirmInstance;

package/docs/proven-in-use.md

@@ -2,7 +2,7 @@
 
 Commonlib is extracted from the implementation shared by [Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync) and its host applications. The package is therefore exercised by a substantial maintained consumer, but it does not yet claim a separate ecosystem of independent applications or a stable end-to-end SDK.
 
-The useful evidence is host- and contract-specific. Focused Commonlib tests establish reusable result semantics; Self-hosted LiveSync tests establish how those contracts compose into the Obsidian plug-in and CLI. The Webapp has focused adapter tests, and both the Webapp and WebPeer are type-checked and built, but they do not have an equally current end-to-end gate.
+The useful evidence is host- and contract-specific. Focused Commonlib tests establish reusable result semantics; Self-hosted LiveSync tests establish how those contracts compose into the Obsidian plug-in, CLI, WebApp, and WebPeer. The Obsidian plug-in and CLI retain the strongest device and long-running synchronisation evidence. The browser applications add focused adapter and runtime tests, browser smoke tests, a cross-application P2P scenario ending at the production CLI, and public Pages smoke validation.
 
 The code paths below identify the maintained Self-hosted LiveSync composition points used to establish this package boundary. The exact reviewed downstream revision and compatibility imports are recorded in [`migration/downstream-imports.json`](migration/downstream-imports.json), which is regenerated by the package-boundary tooling rather than copied into prose links. The integration descriptions must still be reviewed when the maintained downstream changes.
 
@@ -22,6 +22,8 @@ The plug-in's manual onboarding and Remote Databases pane use the focused `/remo
 
 Commonlib's confirmation contract can also convey a host-neutral vertical action-layout request for long, safety-sensitive choices. Self-hosted LiveSync maps that request to Fancy Kit at its Obsidian boundary. Focused tests check the mapping, and the consumer's real-Obsidian suite checks the resulting controls and mobile touch targets; Commonlib does not own the rendering or CSS.
 
+Self-hosted LiveSync's Obsidian and browser dialogue hosts now share an application-owned `SvelteDialogSession` lifecycle. They continue to consume Commonlib's dialogue types and manager base, but no maintained LiveSync path uses `SvelteDialogMixIn`. The dynamic-inheritance helper remains available through the compatibility boundary and is deprecated in favour of host-owned composition.
+
 ## CLI
 
 The CLI extends the same neutral context with its database path and injected `StandardIo` in `src/apps/cli/services/NodeServiceContext.ts`. Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.
@@ -30,20 +32,26 @@ The CLI filesystem composition receives a configured base directory and construc
 
 The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the CLI-to-real-Obsidian synchronisation scenario in `test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts`. The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
 
-## Webapp
+## WebApp
 
-The Webapp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside `src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts`. The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
+WebApp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside `src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts`. The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
 
-The browser and Node storage implementations run through the same Commonlib result contract, and the Webapp adapter has focused unit coverage. The Webapp is also type-checked and built by downstream verification. Its browser E2E has not been kept at the same level as the Obsidian and CLI suites, so the documentation does not treat Webapp integration as equivalent real-runtime evidence.
+The browser and Node storage implementations run through the same Commonlib result contract, and the WebApp adapter and runtime have focused unit coverage. Application-owned Deno and Chromium checks cover Root selection, runtime start-up, settings, scanning, and P2P controls. The Compose interoperability scenario transfers content from WebApp to WebPeer and then to the production CLI, while the public Pages smoke check covers the deployed Root and configuration flow. This evidence remains narrower than the real-Obsidian and CLI synchronisation suites.
 
 ## WebPeer and browser service composition
 
-The browser service composition in `src/apps/browser/createLiveSyncBrowserServiceHub.ts` supplies browser-owned API and UI services around a caller-supplied context. WebPeer and the browser applications exercise this compatibility surface through type checks and builds.
+The browser service composition in `src/apps/browser/createLiveSyncBrowserServiceHub.ts` is owned by Self-hosted LiveSync. It combines Commonlib's injectable service contracts and data implementations with LiveSync-owned browser API, UI, settings persistence, restart policy, and Vault identity. Commonlib therefore does not provide or select a general browser host.
 
-The Obsidian plug-in, CLI, and Webapp compose P2P ownership through `useP2PReplicatorFeature`. Commands and Obsidian views retain its live result object and resolve the current replicator when an action occurs. WebPeer still enters through the deprecated combined compatibility function, which now delegates the same ownership and lifecycle to the focused feature instead of maintaining a second implementation. Downstream Deno and Compose P2P E2E cover headless peer discovery and synchronisation. The real-Obsidian Setup URI workflow additionally covers first-device local initialisation, one-pass additional-device Fetch, explicit peer approval, Vault reflection, and a two-way note round-trip. The Webapp and WebPeer UI surfaces themselves remain build- and type-check evidence rather than equivalent real-runtime gates.
+The Obsidian plug-in, CLI, WebApp, and WebPeer compose P2P ownership through `useP2PReplicatorFeature`. Commands and views retain its live result object and resolve the current replicator when an action occurs. Downstream Deno and Compose P2P E2E cover headless peer discovery and synchronisation, including the WebApp-to-WebPeer-to-CLI journey. Application-owned Chromium checks cover the browser UI flows, and the public Pages deployment has separate post-deployment smoke validation. The real-Obsidian Setup URI workflow additionally covers first-device local initialisation, one-pass additional-device Fetch, explicit peer approval, Vault reflection, and a two-way note round-trip.
 
 This is evidence that the current package boundary can be consumed without the Obsidian host, but it is not yet a recommended standalone Commonlib client factory. The high-level lifecycle, readiness, error, and disposal contract remains future package work after Self-hosted LiveSync 1.0 rather than a gate for that release.
 
+## LiveSync Bridge
+
+[LiveSync Bridge](https://github.com/vrtmrz/livesync-bridge) uses the root `DirectFileManipulator` entry to access CouchDB directly from Deno. The host supplies its fetch implementation, owns reachability probes, retries, and process health, and waits for the manipulator's readiness result before starting its watch. It does not compose the full LiveSync application Service Hub or use the planned file-client factory.
+
+The downstream Deno checks and unit tests run against the installed package. Its Compose integration starts a real CouchDB instance and verifies create, read, update, and deletion between two Bridge peers. This is evidence for the existing direct-access migration path. Commonlib's focused tests separately cover host fetch injection and initialisation failure reporting. This evidence does not make `DirectFileManipulator` a stable high-level SDK contract or establish the semantics still reserved for `createLiveSyncFileClient`.
+
 ## Verification ownership
 
 Commonlib tests the result and lifecycle contracts of the real implementations it publishes. A maintained host tests only its own composition, persistence, presentation, restart, and policy. When a current host test needs isolation, the host may inject the narrow structural capability it consumes and provide a small fake or spy for that test; Commonlib does not publish test-runner-specific mocks or expose its private service graph.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0",
+  "version": "0.1.1-rc.0",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",
@@ -71,11 +71,6 @@
       "import": "./dist/API/processSetting.js",
       "default": "./dist/API/processSetting.js"
     },
-    "./compat/bureau/bureau": {
-      "types": "./dist/bureau/bureau.d.ts",
-      "import": "./dist/bureau/bureau.js",
-      "default": "./dist/bureau/bureau.js"
-    },
     "./compat/common/ConnectionString": {
       "types": "./dist/common/ConnectionString.d.ts",
       "import": "./dist/common/ConnectionString.js",
@@ -201,16 +196,16 @@
       "import": "./dist/interfaces/DatabaseRebuilder.js",
       "default": "./dist/interfaces/DatabaseRebuilder.js"
     },
-    "./compat/interfaces/FileReflectionProvenance": {
-      "types": "./dist/interfaces/FileReflectionProvenance.d.ts",
-      "import": "./dist/interfaces/FileReflectionProvenance.js",
-      "default": "./dist/interfaces/FileReflectionProvenance.js"
-    },
     "./compat/interfaces/FileHandler": {
       "types": "./dist/interfaces/FileHandler.d.ts",
       "import": "./dist/interfaces/FileHandler.js",
       "default": "./dist/interfaces/FileHandler.js"
     },
+    "./compat/interfaces/FileReflectionProvenance": {
+      "types": "./dist/interfaces/FileReflectionProvenance.d.ts",
+      "import": "./dist/interfaces/FileReflectionProvenance.js",
+      "default": "./dist/interfaces/FileReflectionProvenance.js"
+    },
     "./compat/interfaces/KeyValueDatabase": {
       "types": "./dist/interfaces/KeyValueDatabase.d.ts",
       "import": "./dist/interfaces/KeyValueDatabase.js",
@@ -331,16 +326,6 @@
       "import": "./dist/replication/trystero/P2PLogCollector.js",
       "default": "./dist/replication/trystero/P2PLogCollector.js"
     },
-    "./compat/replication/trystero/P2PReplicatorBase": {
-      "types": "./dist/replication/trystero/P2PReplicatorBase.d.ts",
-      "import": "./dist/replication/trystero/P2PReplicatorBase.js",
-      "default": "./dist/replication/trystero/P2PReplicatorBase.js"
-    },
-    "./compat/replication/trystero/P2PReplicatorCore": {
-      "types": "./dist/replication/trystero/P2PReplicatorCore.d.ts",
-      "import": "./dist/replication/trystero/P2PReplicatorCore.js",
-      "default": "./dist/replication/trystero/P2PReplicatorCore.js"
-    },
     "./compat/replication/trystero/P2PReplicatorPaneCommon": {
       "types": "./dist/replication/trystero/P2PReplicatorPaneCommon.d.ts",
       "import": "./dist/replication/trystero/P2PReplicatorPaneCommon.js",
@@ -436,11 +421,6 @@
       "import": "./dist/serviceModules/adapters/index.js",
       "default": "./dist/serviceModules/adapters/index.js"
     },
-    "./compat/services/BrowserServices": {
-      "types": "./dist/services/BrowserServices.d.ts",
-      "import": "./dist/services/BrowserServices.js",
-      "default": "./dist/services/BrowserServices.js"
-    },
     "./compat/services/ServiceHub": {
       "types": "./dist/services/ServiceHub.d.ts",
       "import": "./dist/services/ServiceHub.js",
@@ -516,11 +496,6 @@
       "import": "./dist/services/implements/base/UIService.js",
       "default": "./dist/services/implements/base/UIService.js"
     },
-    "./compat/services/implements/browser/BrowserAPIService": {
-      "types": "./dist/services/implements/browser/BrowserAPIService.d.ts",
-      "import": "./dist/services/implements/browser/BrowserAPIService.js",
-      "default": "./dist/services/implements/browser/BrowserAPIService.js"
-    },
     "./compat/services/implements/browser/ConfigServiceBrowserCompat": {
       "types": "./dist/services/implements/browser/ConfigServiceBrowserCompat.d.ts",
       "import": "./dist/services/implements/browser/ConfigServiceBrowserCompat.js",