@vrtmrz/livesync-commonlib 0.3.0 → 0.3.2

package/README.md

@@ -14,10 +14,10 @@ This package is primarily for maintainers of those clients and for integrations
 
 ## Status and versioning
 
-Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
-is published on npm through both `latest` and `next`. Self-hosted LiveSync
+Commonlib [0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1)
+is published on npm. Self-hosted LiveSync
 [1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
-uses that exact version. See the [0.2.3 release notes](updates.md#023) for the
+uses Commonlib 0.2.3. The [0.2.3 release notes](updates.md#023) record its
 handler-setter source compatibility change and positive-infinity formatting
 exception.
 
@@ -40,6 +40,21 @@ ordinary replication before resuming local writers. Existing hosts can omit
 this optimisation. Resume cursors retain their existing meaning; this resource
 does not provide an arbitrary-time checkpoint jump or On Demand repair.
 
+Unreleased CouchDB work separates encrypted HTTP responses by Security Seed
+while retaining conditional revalidation within a Seed. See
+[CouchDB response caching](docs/couchdb-http-cache.md) for the request,
+replication-preparation, and host-adapter boundaries.
+
+Journal receipt stops at a per-Journal decode, record, or write failure and
+retries that Journal on the next receive attempt. A host can offer the explicit
+'Skip stopped Journal and resume' operation for the current stopped failure;
+it skips only that Journal, and a later failure stops receipt again. A skip can
+leave content or history incomplete. Use the existing Reset journal received
+history operation to replay entries after correcting the failure, while the
+remote objects remain available and readable. See the
+[Journal receive failures and recovery](docs/journal-receive-recovery.md) for
+the receive, skip, and replay boundaries.
+
 ## Package entry points
 
 | Entry point                                        | Intended use                                                                      | Current contract status                                                                     |
@@ -48,6 +63,7 @@ does not provide an arbitrary-time checkpoint jump or On Demand repair.
 | `@vrtmrz/livesync-commonlib/conflicts` | Keyed conflict-check scheduling with bounded concurrency and explicit completion | Focused, package-tested pre-1.0 contract |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/diagnostics` | Read-only Usage and integrity inspection, name projection, and reports | Focused pre-1.0 diagnostic contract |
+| `@vrtmrz/livesync-commonlib/storage` | Path types, namespace and comparison helpers, and strict Unicode path resolution | Unreleased additive contract; host integration remains explicit |
 | `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
@@ -305,10 +321,17 @@ See [the remote configuration profile guide](docs/remote-configurations.md) for
 
 CouchDB stores the representations already in use as feature identifiers in its version document. Assess that document before synchronisation or direct file operations, and retain unknown identifiers for host diagnostics. See [the remote feature compatibility contract](docs/remote-feature-compatibility.md) for the wire format, update rules, and recovery boundaries.
 
-The maintained CLI and Obsidian hosts can opt into [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB, Object Storage, and P2P in the unreleased transport extension. Existing databases require an explicit Rebuild or Fetch migration before using it. P2P participants must all be updated and migrated.
+Commonlib 0.3.0 provides [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB, Object Storage, and P2P for maintained CLI and Obsidian host integrations. Application adoption remains in [Self-hosted LiveSync #1309](https://github.com/vrtmrz/obsidian-livesync/pull/1309). Changing an existing database's path identity requires coordinated Rebuild and Fetch. P2P participants must all be updated and migrated.
 
 ## Direct database watches
 
+Commonlib 0.3.1 lets direct CouchDB integrations select
+`pathNormalizationVersion: 1` in `DirectFileManipulator` options. Omitted or
+`0` retains Legacy identity. The configured mode must match the database;
+NFC does not relabel a populated Legacy database. A confirmed empty database
+can declare the selected feature before its first Metadata write. Hosts still
+own physical path resolution and the coordinated migration of existing data.
+
 Direct CouchDB reads use the same Chunk arrival waiting and bounded retry processing as application replication. They retrieve missing Chunks through the prepared source connection, including its decryption transforms, without writing fetched Chunks back to that source.
 
 Existing integrations can use `DirectFileManipulator.beginWatch(callback, checkIsInterested?, onCheckpoint?)`. The file callback retains its `(doc: ReadyEntry, seq?: string | number)` signature. Resolving it acknowledges delivery. An incomplete read or rejected delivery remains pending and retries after delays from one second up to 30 seconds, while other documents continue. At most four file-processing operations run concurrently. A newer change for the same document supersedes its pending read, including deletion, rename, or exclusion by `checkIsInterested`.

package/dist/API/DirectFileManipulatorV2.d.ts

@@ -15,6 +15,7 @@ export type DirectFileManipulatorOptions = {
     obfuscatePassphrase: string | undefined;
     idDerivationVersion?: 0 | 1;
     idDerivationKey?: string;
+    pathNormalizationVersion?: 0 | 1;
     encryptInternalMetadata?: boolean;
     useDynamicIterationCount?: boolean;
     customChunkSize?: number;

package/dist/API/DirectFileManipulatorV2.js

@@ -5,18 +5,17 @@ import {
   DEFAULT_SYNC_PARAMETERS,
   ProtocolVersions,
   DOCID_SYNC_PARAMETERS,
-  VERSIONING_DOCID,
   E2EEAlgorithms,
   VER
 } from "../common/types.js";
 import { checkRemoteVersion } from "../pouchdb/negotiation.js";
 import {
-  assessRemoteFeatureDocument,
-  NFC_PATH_IDENTITY_FEATURE,
   requiredRemoteFeatures,
   usesEncryptedInternalMetadata
 } from "../pouchdb/remoteFeatureCompatibility.js";
 import { assessRemoteDocumentIds } from "../pouchdb/remoteIdCompatibility.js";
+import { assertDatabasePathIdentity } from "../pouchdb/pathIdentityCompatibility.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 import { PouchDB } from "../pouchdb/pouchdb-http.js";
 import { LiveSyncLocalDB } from "../pouchdb/LiveSyncLocalDB.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
@@ -71,15 +70,7 @@ class DirectFileManipulator {
       if (idCompatibility === "mismatched") {
         throw new Error("Direct database document IDs do not match the configured ID key.");
       }
-      try {
-        const versionInfo = await this.liveSyncLocalDB.localDatabase.get(VERSIONING_DOCID);
-        const assessment = assessRemoteFeatureDocument(versionInfo);
-        if (assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE)) {
-          throw new Error("Direct database version or features are not compatible.");
-        }
-      } catch (error) {
-        if (!isErrorOfMissingDoc(error)) throw error;
-      }
+      await assertDatabasePathIdentity(this.liveSyncLocalDB.localDatabase, idSettings);
       const requiredFeatures = requiredRemoteFeatures(this.settings);
       if (!await checkRemoteVersion(
         this.liveSyncLocalDB.localDatabase,
@@ -229,6 +220,9 @@ class DirectFileManipulator {
         passphrase: this.options.passphrase ?? "",
         idDerivationVersion: this.options.idDerivationVersion ?? 0,
         idDerivationKey: this.options.idDerivationKey ?? "",
+        pathNormalizationVersion: getPathNormalizationVersion({
+          pathNormalizationVersion: this.options.pathNormalizationVersion
+        }),
         deleteMetadataOfDeletedFiles: DEFAULT_SETTINGS.deleteMetadataOfDeletedFiles,
         customChunkSize: this.options.customChunkSize ?? DEFAULT_SETTINGS.customChunkSize,
         doNotPaceReplication: DEFAULT_SETTINGS.doNotPaceReplication,

package/dist/API/processSetting.d.ts

@@ -156,6 +156,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     jwtSub: string;
     jwtExpDuration: number;
     useRequestAPI: boolean;
+    useCouchDBCacheControlHeadersOnly?: boolean;
     accessKey: string;
     secretKey: string;
     bucket: string;

package/dist/common/models/setting.const.defaults.js

@@ -189,6 +189,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   jwtSub: "",
   jwtExpDuration: 5,
   useRequestAPI: false,
+  useCouchDBCacheControlHeadersOnly: false,
   bucketPrefix: "",
   chunkSplitterVersion: ChunkAlgorithms.RabinKarp,
   E2EEAlgorithm: E2EEAlgorithms.V2,

package/dist/common/models/setting.const.qr.js

@@ -184,6 +184,7 @@ const KeyIndexOfSettings = {
   idDerivationKey: 167,
   pathNormalizationVersion: 168,
   batchSaveInLiveSync: 169,
+  useCouchDBCacheControlHeadersOnly: 170,
   encryptedIdDerivationKey: -1
 };
 export {

package/dist/common/models/setting.policy.d.ts

@@ -441,6 +441,10 @@ export declare const SETTINGS_PROPERTY_POLICY: {
         readonly markdown: "include";
         readonly persistence: "include";
     };
+    readonly useCouchDBCacheControlHeadersOnly: {
+        readonly markdown: "include";
+        readonly persistence: "include";
+    };
     readonly accessKey: {
         readonly markdown: "credentials";
         readonly persistence: "connection";

package/dist/common/models/setting.policy.js

@@ -111,6 +111,7 @@ const SETTINGS_PROPERTY_POLICY = {
   jwtSub: SettingPolicies.ConnectionCredentials,
   jwtExpDuration: SettingPolicies.Default,
   useRequestAPI: SettingPolicies.Default,
+  useCouchDBCacheControlHeadersOnly: SettingPolicies.Default,
   accessKey: SettingPolicies.ConnectionCredentials,
   secretKey: SettingPolicies.ConnectionCredentials,
   bucket: SettingPolicies.LocalConnection,

package/dist/common/models/setting.type.d.ts

@@ -38,6 +38,8 @@ export interface CouchDBConnection {
      * Seems stable, so promoted to the normal setting.
      */
     useRequestAPI: boolean;
+    /** Control CouchDB HTTP caching through headers alone. Defaults to false. */
+    useCouchDBCacheControlHeadersOnly?: boolean;
 }
 /**
  * Interface representing the settings for periodic replication.

package/dist/common/models/tweak.definition.d.ts

@@ -238,6 +238,7 @@ export declare const TweakValuesTemplate: {
     jwtSub?: string;
     jwtExpDuration?: number;
     useRequestAPI?: boolean;
+    useCouchDBCacheControlHeadersOnly?: boolean;
     accessKey?: string;
     secretKey?: string;
     bucket?: string;

package/dist/common/pathNamespace.d.ts

@@ -0,0 +1,4 @@
+import { ICHeader, ICXHeader, PSCHeader } from "./models/fileaccess.const.js";
+export type PathNamespace = "" | typeof ICHeader | typeof ICXHeader | typeof PSCHeader;
+/** Separate one recognised Metadata namespace while retaining the body's spelling. */
+export declare function splitPathNamespace(path: string): readonly [PathNamespace, string];

package/dist/common/pathNamespace.js

@@ -0,0 +1,10 @@
+import { ICHeader, ICXHeader, PSCHeader } from "./models/fileaccess.const.js";
+function splitPathNamespace(path) {
+  for (const prefix of [ICHeader, ICXHeader, PSCHeader]) {
+    if (path.startsWith(prefix)) return [prefix, path.slice(prefix.length)];
+  }
+  return ["", path];
+}
+export {
+  splitPathNamespace
+};

package/dist/common/settingConstants.d.ts

@@ -126,6 +126,7 @@ export declare const AllSettingDefault: {
     jwtSub: string;
     jwtExpDuration: number;
     useRequestAPI: boolean;
+    useCouchDBCacheControlHeadersOnly?: boolean;
     accessKey: string;
     secretKey: string;
     bucket: string;

package/dist/common/settingConstants.js

@@ -375,6 +375,10 @@ const SettingInformation = {
     name: "Use Request API to avoid `inevitable` CORS problem",
     desc: "If enabled, the request API will be used to avoid `inevitable` CORS problems. This is a workaround and may not work in all cases. PLEASE READ THE DOCUMENTATION BEFORE USING THIS OPTION. This is a less-secure option."
   },
+  useCouchDBCacheControlHeadersOnly: {
+    name: "Use headers only for HTTP cache control (compatibility)",
+    desc: "Remove the query parameter used to invalidate cached responses (the same URL behaviour as in 1.0.44 and earlier). Enable only if your CouchDB server or proxy rejects the additional cache query parameter. Older cached encrypted responses may then be reused after a remote Rebuild."
+  },
   hideFileWarningNotice: {
     name: "Show status icon instead of file warnings banner",
     desc: "If enabled, the \u26D4 icon will be shown inside the status instead of the file warnings banner. No details will be shown."

package/dist/platform/AmbiguousNormalisedPathError.d.ts

@@ -0,0 +1,16 @@
+/** More than one listed entry has the requested logical identity. */
+export declare class AmbiguousNormalisedPathError extends Error {
+    /** Path whose logical identity was ambiguous. */
+    readonly path: string;
+    /** Physical candidate paths copied from the listing which exposed the ambiguity. */
+    readonly candidates: readonly string[];
+    /**
+     * Describe an ambiguous request without choosing a physical candidate.
+     *
+     * @param path - Path whose logical identity matched multiple entries.
+     * @param candidates - Matching physical paths, copied into a frozen array.
+     */
+    constructor(
+    /** Path whose logical identity was ambiguous. */
+    path: string, candidates?: readonly string[]);
+}

package/dist/platform/AmbiguousNormalisedPathError.js

@@ -0,0 +1,21 @@
+class AmbiguousNormalisedPathError extends Error {
+  /**
+   * Describe an ambiguous request without choosing a physical candidate.
+   *
+   * @param path - Path whose logical identity matched multiple entries.
+   * @param candidates - Matching physical paths, copied into a frozen array.
+   */
+  constructor(path, candidates = []) {
+    const detail = candidates.length ? ` (${candidates.map((name) => JSON.stringify(name)).join(", ")})` : "";
+    super(`Ambiguous path after Unicode normalisation: ${path}${detail}`);
+    this.path = path;
+    this.name = "AmbiguousNormalisedPathError";
+    this.candidates = Object.freeze([...candidates]);
+  }
+  path;
+  /** Physical candidate paths copied from the listing which exposed the ambiguity. */
+  candidates;
+}
+export {
+  AmbiguousNormalisedPathError
+};

package/dist/platform/StoragePathResolver.d.ts

@@ -0,0 +1,15 @@
+import type { FilePath, ResolvedRename, StorageEntry, StoragePath, StoragePathResolver as ResolverContract, StoragePathResolverOptions } from "./pathTypes.js";
+/** Resolves listed names using one immutable NFC policy and no retained directory cache. */
+export declare class StoragePathResolver implements ResolverContract {
+    private readonly readDirectory;
+    private readonly policy;
+    constructor({ readDirectory, policy }: StoragePathResolverOptions);
+    resolveExisting(path: FilePath): Promise<StoragePath | null>;
+    resolveForWrite(path: FilePath): Promise<StoragePath>;
+    resolveRename(source: FilePath, target: FilePath): Promise<ResolvedRename | null>;
+    listResolvedDirectory(path: StoragePath): Promise<readonly StorageEntry[] | null>;
+    private resolve;
+    private findEntry;
+    private readEntries;
+    private key;
+}

package/dist/platform/StoragePathResolver.js

@@ -0,0 +1,113 @@
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
+import { AmbiguousNormalisedPathError } from "./AmbiguousNormalisedPathError.js";
+import { getStoragePathComparisonKey } from "./pathComparison.js";
+import { validateStoragePath } from "./storagePath.js";
+function storagePath(path) {
+  return validateStoragePath(path);
+}
+function childPath(parent, name) {
+  return storagePath(parent === "" ? name : `${parent}/${name}`);
+}
+function segments(path) {
+  validateStoragePath(path);
+  return path.split("/").filter(Boolean);
+}
+class StoragePathResolver {
+  readDirectory;
+  policy;
+  constructor({ readDirectory, policy }) {
+    if (getPathNormalizationVersion(policy) !== 1) {
+      throw new Error("Storage path resolution requires NFC path identity");
+    }
+    if (typeof policy.handleFilenameCaseSensitive !== "boolean") {
+      throw new TypeError("Filename case handling must be explicit");
+    }
+    this.readDirectory = readDirectory;
+    this.policy = Object.freeze({ ...policy });
+  }
+  async resolveExisting(path) {
+    return await this.resolve(path, false);
+  }
+  async resolveForWrite(path) {
+    const resolved = await this.resolve(path, true);
+    if (resolved === null) throw new Error(`Could not resolve storage target: ${path}`);
+    return resolved;
+  }
+  async resolveRename(source, target) {
+    validateStoragePath(source, false);
+    validateStoragePath(target, false);
+    const resolvedSource = await this.resolveExisting(source);
+    if (resolvedSource === null) return null;
+    const resolvedTarget = await this.resolveForWrite(target);
+    if (resolvedTarget !== resolvedSource || target === resolvedSource) {
+      return { source: resolvedSource, target: resolvedTarget };
+    }
+    const requestedParts = segments(target);
+    const leaf = requestedParts[requestedParts.length - 1];
+    const parent = storagePath(resolvedTarget.slice(0, Math.max(0, resolvedTarget.lastIndexOf("/"))));
+    return { source: resolvedSource, target: childPath(parent, leaf) };
+  }
+  async listResolvedDirectory(path) {
+    validateStoragePath(path);
+    const entries = await this.readEntries(path);
+    if (entries === null) return null;
+    const names = /* @__PURE__ */ new Map();
+    return entries.map((entry) => {
+      const actualPath = childPath(path, entry.name);
+      const key = this.key(entry.name);
+      const previous = names.get(key);
+      if (previous !== void 0) {
+        throw new AmbiguousNormalisedPathError(path, [previous, actualPath]);
+      }
+      names.set(key, actualPath);
+      return { path: actualPath, kind: entry.kind };
+    });
+  }
+  async resolve(path, allowMissing) {
+    const parts = segments(path);
+    let parent = storagePath("");
+    if (parts.length === 0) {
+      return allowMissing || await this.readEntries(parent) !== null ? parent : null;
+    }
+    for (let index = 0; index < parts.length; index++) {
+      const entries = await this.readEntries(parent);
+      const match = entries === null ? void 0 : this.findEntry(entries, parts[index], parent, path);
+      if (!match) {
+        return allowMissing ? childPath(parent, parts.slice(index).join("/")) : null;
+      }
+      parent = childPath(parent, match.name);
+      if (index < parts.length - 1 && match.kind !== "directory") {
+        throw new Error(`A storage path parent is not a directory: ${parent}`);
+      }
+    }
+    return parent;
+  }
+  findEntry(entries, name, parent, requestedPath) {
+    const key = this.key(name);
+    const matches = entries.filter((entry) => this.key(entry.name) === key);
+    if (matches.length > 1) {
+      throw new AmbiguousNormalisedPathError(
+        requestedPath,
+        matches.map((entry) => childPath(parent, entry.name))
+      );
+    }
+    return matches[0];
+  }
+  async readEntries(path) {
+    const entries = await this.readDirectory(path);
+    if (entries === null) return null;
+    for (const entry of entries) {
+      if (typeof entry.name !== "string" || entry.name === "" || entry.name === "." || entry.name === ".." || /[\/\\\0]/u.test(entry.name) || entry.kind !== "file" && entry.kind !== "directory") {
+        throw new TypeError(`Invalid directory entry below ${JSON.stringify(path)}`);
+      }
+      childPath(path, entry.name);
+    }
+    return entries;
+  }
+  key(name) {
+    return getStoragePathComparisonKey(name, this.policy);
+  }
+}
+export {
+  StoragePathResolver
+};

package/dist/platform/browser/UnicodeResolvingFileSystemAccessStorageAdapter.d.ts

@@ -0,0 +1,74 @@
+import type { UXDataWriteOptions } from "../../common/types.js";
+import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
+import type { FilePath, StoragePath } from "../pathTypes.js";
+import { type FileSystemAccessStorageStat } from "./storage.js";
+/**
+ * Resolve NFC-equivalent logical paths against current File System Access directory names.
+ *
+ * @remarks
+ * Each operation snapshots Unicode and case settings. Version `0` delegates to
+ * the existing adapter; version `1` resolves names and rejects observed aliases
+ * before I/O. Physical spelling and the host adapter's mutation semantics remain
+ * unchanged. Resolution does not reserve paths against concurrent changes.
+ */
+export declare class UnicodeResolvingFileSystemAccessStorageAdapter implements IStorageAdapter<FileSystemAccessStorageStat> {
+    private readonly getPathNormalizationVersion;
+    private readonly isCaseInsensitive;
+    private readonly storage;
+    /**
+     * Bind a host-owned root and callbacks for each operation's comparison settings.
+     *
+     * @param rootHandle - Host-selected directory handle with the required permissions.
+     * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+     * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+     */
+    constructor(rootHandle: FileSystemDirectoryHandle, getPathNormalizationVersion?: () => number, isCaseInsensitive?: () => boolean);
+    /** Whether the current settings select NFC path resolution. */
+    get isUnicodePathNormalizationEnabled(): boolean;
+    /**
+     * Resolve a logical path under one snapshot of the current settings.
+     *
+     * @param path - Original root-relative file path.
+     * @param caseInsensitive - Override this lookup's case rule without changing settings.
+     * @param allowMissing - Keep a missing write suffix when true; defaults to true.
+     * @returns The physical target, or `null` for an absent path when `allowMissing`
+     * is false in NFC mode. Legacy mode returns the validated original path.
+     * @throws Propagates NFC ambiguity and reader failures, and rejects invalid input.
+     */
+    resolveLogicalPath(path: FilePath, caseInsensitive?: boolean, allowMissing?: boolean): Promise<StoragePath | null>;
+    /** Read metadata for a physical path without performing another logical lookup. */
+    statExact(path: StoragePath): Promise<FileSystemAccessStorageStat | null>;
+    /** List a physical directory, rejecting equivalent child names in NFC mode. */
+    listExact(path: StoragePath): Promise<{
+        files: string[];
+        folders: string[];
+    }>;
+    /** Check whether the logical path exists under the current Unicode policy. */
+    exists(path: string): Promise<boolean>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    trystat(path: string): Promise<FileSystemAccessStorageStat | null>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    stat(path: string): Promise<FileSystemAccessStorageStat | null>;
+    /** Create a directory at the resolved write target. */
+    mkdir(path: string): Promise<void>;
+    /** Remove the entry at its resolved physical path. */
+    remove(path: string): Promise<void>;
+    /** Read text from the resolved physical file. */
+    read(path: string): Promise<string>;
+    /** Read bytes from the resolved physical file. */
+    readBinary(path: string): Promise<ArrayBuffer>;
+    /** Write text at the resolved target while retaining existing physical spelling. */
+    write(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Write bytes at the resolved target while retaining existing physical spelling. */
+    writeBinary(path: string, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
+    /** Append text at the resolved target using the host adapter semantics. */
+    append(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** List logical directory contents, checking equivalent child names in NFC mode. */
+    list(basePath: string): Promise<{
+        files: string[];
+        folders: string[];
+    }>;
+    private snapshotPolicy;
+    private createResolver;
+    private groupStorageEntries;
+}

package/dist/platform/browser/UnicodeResolvingFileSystemAccessStorageAdapter.js

@@ -0,0 +1,169 @@
+import { getPathNormalizationVersion } from "../../common/pathNormalization.js";
+import { parseFilePath } from "../pathComparison.js";
+import { createStoragePathResolver } from "../storagePathResolution.js";
+import { FileSystemAccessStorageAdapter } from "./storage.js";
+class UnicodeResolvingFileSystemAccessStorageAdapter {
+  /**
+   * Bind a host-owned root and callbacks for each operation's comparison settings.
+   *
+   * @param rootHandle - Host-selected directory handle with the required permissions.
+   * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+   * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+   */
+  constructor(rootHandle, getPathNormalizationVersion2 = () => 0, isCaseInsensitive = () => false) {
+    this.getPathNormalizationVersion = getPathNormalizationVersion2;
+    this.isCaseInsensitive = isCaseInsensitive;
+    this.storage = new FileSystemAccessStorageAdapter(rootHandle);
+  }
+  getPathNormalizationVersion;
+  isCaseInsensitive;
+  storage;
+  /** Whether the current settings select NFC path resolution. */
+  get isUnicodePathNormalizationEnabled() {
+    return this.snapshotPolicy().pathNormalizationVersion === 1;
+  }
+  /**
+   * Resolve a logical path under one snapshot of the current settings.
+   *
+   * @param path - Original root-relative file path.
+   * @param caseInsensitive - Override this lookup's case rule without changing settings.
+   * @param allowMissing - Keep a missing write suffix when true; defaults to true.
+   * @returns The physical target, or `null` for an absent path when `allowMissing`
+   * is false in NFC mode. Legacy mode returns the validated original path.
+   * @throws Propagates NFC ambiguity and reader failures, and rejects invalid input.
+   */
+  async resolveLogicalPath(path, caseInsensitive, allowMissing = true) {
+    const policy = this.snapshotPolicy(caseInsensitive);
+    const logicalPath = parseFilePath(path);
+    if (policy.pathNormalizationVersion === 0) return logicalPath;
+    const resolver = this.createResolver(policy);
+    return allowMissing ? await resolver.resolveForWrite(logicalPath) : await resolver.resolveExisting(logicalPath);
+  }
+  /** Read metadata for a physical path without performing another logical lookup. */
+  async statExact(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.trystat(path);
+    return await this.storage.statResolved(path);
+  }
+  /** List a physical directory, rejecting equivalent child names in NFC mode. */
+  async listExact(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.list(path);
+    const entries = await this.createResolver(policy).listResolvedDirectory(path);
+    return this.groupStorageEntries(entries ?? []);
+  }
+  /** Check whether the logical path exists under the current Unicode policy. */
+  async exists(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.exists(path);
+    return await this.createResolver(policy).resolveExisting(parseFilePath(path)) !== null;
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async trystat(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.trystat(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    return resolved === null ? null : await this.storage.statResolved(resolved);
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async stat(path) {
+    return await this.trystat(path);
+  }
+  /** Create a directory at the resolved write target. */
+  async mkdir(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.mkdir(path);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.mkdirResolved(resolved);
+  }
+  /** Remove the entry at its resolved physical path. */
+  async remove(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.remove(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved !== null) await this.storage.removeResolved(resolved);
+  }
+  /** Read text from the resolved physical file. */
+  async read(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.read(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved === null) throw new Error(`File not found: ${path}`);
+    return await this.storage.readResolved(resolved);
+  }
+  /** Read bytes from the resolved physical file. */
+  async readBinary(path) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.readBinary(path);
+    const resolved = await this.createResolver(policy).resolveExisting(parseFilePath(path));
+    if (resolved === null) throw new Error(`File not found: ${path}`);
+    return await this.storage.readBinaryResolved(resolved);
+  }
+  /** Write text at the resolved target while retaining existing physical spelling. */
+  async write(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.write(path, data, options);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.writeResolved(resolved, data, options);
+  }
+  /** Write bytes at the resolved target while retaining existing physical spelling. */
+  async writeBinary(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) {
+      return await this.storage.writeBinary(path, data, options);
+    }
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.writeBinaryResolved(resolved, data, options);
+  }
+  /** Append text at the resolved target using the host adapter semantics. */
+  async append(path, data, options) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.append(path, data, options);
+    const resolved = await this.createResolver(policy).resolveForWrite(parseFilePath(path));
+    await this.storage.appendResolved(resolved, data, options);
+  }
+  /** List logical directory contents, checking equivalent child names in NFC mode. */
+  async list(basePath) {
+    const policy = this.snapshotPolicy();
+    if (policy.pathNormalizationVersion === 0) return await this.storage.list(basePath);
+    const resolver = this.createResolver(policy);
+    const resolved = await resolver.resolveExisting(parseFilePath(basePath));
+    if (resolved === null) return { files: [], folders: [] };
+    const entries = await resolver.listResolvedDirectory(resolved);
+    return this.groupStorageEntries(entries ?? []);
+  }
+  snapshotPolicy(caseInsensitive) {
+    const pathNormalizationVersion = getPathNormalizationVersion({
+      pathNormalizationVersion: this.getPathNormalizationVersion()
+    });
+    const isCaseInsensitive = caseInsensitive ?? this.isCaseInsensitive();
+    return Object.freeze({
+      pathNormalizationVersion,
+      handleFilenameCaseSensitive: !isCaseInsensitive
+    });
+  }
+  createResolver(policy) {
+    if (policy.pathNormalizationVersion !== 1) {
+      throw new Error("The storage path resolver requires NFC path normalisation");
+    }
+    return createStoragePathResolver({
+      readDirectory: (path) => this.storage.readDirectory(path),
+      policy: {
+        pathNormalizationVersion: 1,
+        handleFilenameCaseSensitive: policy.handleFilenameCaseSensitive
+      }
+    });
+  }
+  groupStorageEntries(entries) {
+    const files = [];
+    const folders = [];
+    for (const entry of entries) {
+      if (entry.kind === "file") files.push(entry.path);
+      else folders.push(entry.path);
+    }
+    return { files, folders };
+  }
+}
+export {
+  UnicodeResolvingFileSystemAccessStorageAdapter
+};

package/dist/platform/browser/index.d.ts

@@ -1 +1,2 @@
 export { FileSystemAccessStorageAdapter, createFileSystemAccessStorage, validateStoragePath, type CreateFileSystemAccessStorageOptions, type FileSystemAccessStorageStat, } from "./storage.js";
+export { UnicodeResolvingFileSystemAccessStorageAdapter } from "./UnicodeResolvingFileSystemAccessStorageAdapter.js";