@gesslar/toolkit 3.27.0 → 3.29.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.27.0",
+  "version": "3.29.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -61,7 +61,7 @@
   "devDependencies": {
     "@gesslar/uglier": "^1.2.0",
     "eslint": "^9.39.2",
-    "happy-dom": "^20.3.7",
+    "happy-dom": "^20.4.0",
     "typescript": "^5.9.3"
   },
   "scripts": {

package/src/browser/index.js

@@ -8,6 +8,7 @@ export {Disposer as DisposerClass} from "./lib/Disposer.js"
 export {default as HTML} from "./lib/HTML.js"
 export {HTML as HTMLClass} from "./lib/HTML.js"
 export {default as Notify} from "./lib/Notify.js"
+export {Notify as NotifyClass} from "./lib/Notify.js"
 export {default as Promised} from "./lib/Promised.js"
 export {default as Sass} from "./lib/Sass.js"
 export {default as Tantrum} from "./lib/Tantrum.js"

package/src/browser/lib/Notify.js

@@ -10,7 +10,7 @@
  * @property {boolean} [cancelable] - Whether the event can be canceled.
  * @property {boolean} [composed] - Whether the event can cross the shadow DOM boundary.
  */
-export default new class Notify {
+export class Notify {
   /** @type {string} Display name for debugging. */
   name = "Notify"
 
@@ -87,3 +87,5 @@ export default new class Notify {
     return {detail}
   }
 }
+
+export default new Notify()

package/src/node/index.js

@@ -21,4 +21,5 @@ export {default as FileSystem} from "./lib/FileSystem.js"
 export {default as Font} from "./lib/Font.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
+export {Notify as NotifyClass} from "./lib/Notify.js"
 export {default as Term} from "./lib/Term.js"

package/src/node/lib/DirectoryObject.js

@@ -5,6 +5,7 @@
  */
 
 import {glob, mkdir, opendir, readdir, rmdir} from "node:fs/promises"
+import {relative} from "node:path"
 import path from "node:path"
 import {URL} from "node:url"
 
@@ -540,75 +541,100 @@ export default class DirectoryObject extends FS {
   /**
    * Creates a new DirectoryObject by extending this directory's path.
    *
+   * Paths are always resolved relative to THIS directory. Any attempt to
+   * escape via `..` or absolute paths is constrained - the `..` segments
+   * are stripped and the remaining path is resolved relative to this directory.
+   *
+   * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+   * are also constrained - the drive root is stripped and the path is resolved
+   * relative to this directory.
+   *
    * Uses overlapping path segment detection to intelligently combine paths.
-   * Preserves the temporary flag from the current directory.
    *
    * @param {string} newPath - The path to append to this directory's path.
    * @returns {DirectoryObject} A new DirectoryObject with the extended path.
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const subDir = dir.addDirectory("src/lib")
+   * const subDir = dir.getDirectory("src/lib")
    * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+   *
+   * @example
+   * // Path traversal is constrained to this directory
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const escaped = dir.getDirectory("../../../foo/bar")
+   * console.log(escaped.path) // "/projects/git/toolkit/foo/bar"
    */
   getDirectory(newPath) {
     Valid.type(newPath, "String", {allowEmpty: false})
 
-    // Reject absolute paths
-    if(path.isAbsolute(newPath)) {
-      throw Sass.new(`Absolute paths not allowed: ${newPath}`)
-    }
-
-    // Reject parent directory traversal
-    if(newPath.includes("..")) {
-      throw Sass.new(`Path traversal not allowed: ${newPath} contains '..'`)
-    }
-
+    // New direction: every path is relative to THIS path. Absolute?
+    //  ../../../..? up to this path and then down again if required.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, newPath)
     const resolved = FS.resolvePath(thisPath, merged)
+    let local = relative(thisPath, resolved)
 
-    // Final safety check
-    if(!FS.pathContains(thisPath, resolved)) {
-      throw Sass.new(`Path resolves outside directory: ${newPath}`)
-    }
+    // On Windows, cross-drive paths return absolute - strip the root
+    if(path.isAbsolute(local))
+      local = local.slice(path.parse(local).root.length)
+
+    const parts = local.split(this.sep)
+
+    while(parts[0] === "..")
+      parts.shift()
+
+    const newLocal = parts.join(this.sep)
 
-    return new this.constructor(resolved)
+    return new this.constructor(FS.resolvePath(this.path, newLocal))
   }
 
   /**
    * Creates a new FileObject by extending this directory's path.
    *
+   * Paths are always resolved relative to THIS directory. Any attempt to
+   * escape via `..` or absolute paths is constrained - the `..` segments
+   * are stripped and the remaining path is resolved relative to this directory.
+   *
+   * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+   * are also constrained - the drive root is stripped and the path is resolved
+   * relative to this directory.
+   *
    * Uses overlapping path segment detection to intelligently combine paths.
    *
    * @param {string} filename - The filename to append to this directory's path.
    * @returns {FileObject} A new FileObject with the extended path.
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const file = dir.addFile("package.json")
+   * const file = dir.getFile("package.json")
    * console.log(file.path) // "/projects/git/toolkit/package.json"
+   *
+   * @example
+   * // Path traversal is constrained to this directory
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const escaped = dir.getFile("../../../foo/bar.js")
+   * console.log(escaped.path) // "/projects/git/toolkit/foo/bar.js"
    */
   getFile(filename) {
     Valid.type(filename, "String", {allowEmpty: false})
 
-    // Reject absolute paths
-    if(path.isAbsolute(filename)) {
-      throw Sass.new(`Absolute paths not allowed: ${filename}`)
-    }
-
-    // Reject parent directory traversal
-    if(filename.includes("..")) {
-      throw Sass.new(`Path traversal not allowed: ${filename} contains '..'`)
-    }
-
+    // Every path is relative to THIS path. Absolute or .. paths
+    // are constrained to this directory.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, filename)
     const resolved = FS.resolvePath(thisPath, merged)
+    let local = relative(thisPath, resolved)
 
-    // Final safety check
-    if(!FS.pathContains(thisPath, resolved)) {
-      throw Sass.new(`Path resolves outside directory: ${filename}`)
-    }
+    // On Windows, cross-drive paths return absolute - strip the root
+    if(path.isAbsolute(local))
+      local = local.slice(path.parse(local).root.length)
+
+    const parts = local.split(this.sep)
+
+    while(parts[0] === "..")
+      parts.shift()
+
+    const newLocal = parts.join(this.sep)
 
-    return new FileObject(resolved)
+    return new FileObject(newLocal, this)
   }
 }

package/src/node/lib/FileSystem.js

@@ -251,11 +251,11 @@ export default class FileSystem {
    * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
    * @returns {string|null} The relative path, empty string if paths are identical, or null if no overlap found
    * @example
-   * FS.toRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
-   * FS.toRelativePath("/home/user", "/home/user") // ""
-   * FS.toRelativePath("/projects/app", "/other/path") // null
+   * FS.toLocalRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+   * FS.toLocalRelativePath("/home/user", "/home/user") // ""
+   * FS.toLocalRelativePath("/projects/app", "/other/path") // null
    */
-  static toRelativePath(from, to, sep=path.sep) {
+  static toLocalRelativePath(from, to, sep=path.sep) {
     // If they're the same, just return ""
     if(from === to)
       return ""
@@ -276,20 +276,46 @@ export default class FileSystem {
   }
 
   /**
-   * Find the common root path between two paths by identifying overlapping segments.
-   * Returns the portion of 'from' that matches up to the overlap point in 'to'.
+   * Computes the relative path from one path to another using Node's path.relative.
+   *
+   * Unlike toLocalRelativePath which uses overlap detection, this method uses
+   * standard relative path calculation and may return paths with ".." segments.
+   *
+   * @static
+   * @param {string} from - The base path to calculate relative from
+   * @param {string} to - The target path to make relative
+   * @returns {string} The relative path, or empty string if paths are identical
+   * @example
+   * FS.toRelativePath("/home/user", "/home/user/docs") // "docs"
+   * FS.toRelativePath("/home/user", "/home/user") // ""
+   * FS.toRelativePath("/home/user", "/home/other") // "../other"
+   */
+  static toRelativePath(from, to) {
+    // If they're the same, just return ""
+    if(from === to)
+      return ""
+
+    return path.relative(from, to)
+  }
+
+  /**
+   * Find where a path's final segment appears in another path, returning the
+   * portion of 'from' up to that overlap point.
+   *
+   * Looks for the last segment of `from` within `to`. If found, returns `from`
+   * sliced to the index where that segment appears in `to`.
    *
    * @static
-   * @param {string} from - The first path to compare
-   * @param {string} to - The second path to find common root with
+   * @param {string} from - The source path whose final segment to search for
+   * @param {string} to - The target path to search within
    * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-   * @returns {string|null} The common root path, the original path if identical, or null if no overlap found
+   * @returns {string|null} The sliced portion of from, the original path if identical, or null if no overlap
    * @throws {Sass} If from is not a non-empty string
    * @throws {Sass} If to is not a non-empty string
    * @example
-   * FS.getCommonRootPath("/projects/toolkit/src", "/projects/toolkit/tests") // "/projects/toolkit"
+   * FS.getCommonRootPath("/projects/toolkit", "/projects/toolkit/src") // "/projects/toolkit"
    * FS.getCommonRootPath("/home/user", "/home/user") // "/home/user"
-   * FS.getCommonRootPath("/projects/app", "/other/path") // null
+   * FS.getCommonRootPath("/projects/app", "/other/path") // null (no overlap)
    */
   static getCommonRootPath(from, to, sep=path.sep) {
     Valid.type(from, "String", {allowEmpty: false})

package/src/node/lib/Notify.js

@@ -19,7 +19,7 @@ import Util from "./Util.js"
  * Notify class provides a thin wrapper around EventEmitter for centralized
  * event handling in Node.js applications. Mirrors the browser Notify API.
  */
-export default new class Notify {
+export class Notify {
   /** @type {string} Display name for debugging. */
   name = "Notify"
 
@@ -106,3 +106,5 @@ export default new class Notify {
     emitter.off(type, handler)
   }
 }
+
+export default new Notify()

package/types/browser/index.d.ts

@@ -1,6 +1,5 @@
 export { default as Collection } from "./lib/Collection.js";
 export { default as Data } from "./lib/Data.js";
-export { default as Notify } from "./lib/Notify.js";
 export { default as Promised } from "./lib/Promised.js";
 export { default as Sass } from "./lib/Sass.js";
 export { default as Tantrum } from "./lib/Tantrum.js";
@@ -10,4 +9,5 @@ export { default as Util } from "./lib/Util.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Disposer, Disposer as DisposerClass } from "./lib/Disposer.js";
 export { default as HTML, HTML as HTMLClass } from "./lib/HTML.js";
+export { default as Notify, Notify as NotifyClass } from "./lib/Notify.js";
 //# sourceMappingURL=index.d.ts.map

package/types/browser/lib/Notify.d.ts

@@ -1,4 +1,15 @@
-declare const _default: {
+/**
+ * Thin wrapper around `window` event handling to centralize emit/on/off
+ * helpers. Used to dispatch simple CustomEvents and manage listeners in one
+ * place.
+ */
+/**
+ * @typedef {object} NotifyEventOptions
+ * @property {boolean} [bubbles] - Whether the event bubbles up the DOM tree.
+ * @property {boolean} [cancelable] - Whether the event can be canceled.
+ * @property {boolean} [composed] - Whether the event can cross the shadow DOM boundary.
+ */
+export class Notify {
     /** @type {string} Display name for debugging. */
     name: string;
     /**
@@ -29,7 +40,7 @@ declare const _default: {
      * @param {boolean | object} [options] - Options to pass to addEventListener.
      * @returns {() => void} Dispose function to unregister the handler.
      */
-    on(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): () => void;
+    on(type: string, handler: (evt: Notify) => void, element?: HTMLElement | Window, options?: boolean | object): () => void;
     /**
      * Removes a previously registered listener for the given event type.
      *
@@ -39,9 +50,10 @@ declare const _default: {
      * @param {boolean | object} [options] - Options to pass to removeEventListener.
      * @returns {void}
      */
-    off(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): void;
-    "__#private@#buildEventInit"(detail: any, options: any): any;
-};
+    off(type: string, handler: (evt: Notify) => void, element?: HTMLElement | Window, options?: boolean | object): void;
+    #private;
+}
+declare const _default: Notify;
 export default _default;
 export type NotifyEventOptions = {
     /**

package/types/browser/lib/Notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Notify.js"],"names":[],"mappings":";IAaE,iDAAiD;UAAtC,MAAM;IAGjB;;;;;;;OAOG;eAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,IAAI;IAOjB;;;;;;;OAOG;kBAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,OAAO;IASpB;;;;;;;;;OASG;aALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,MAAM,IAAI;IAcvB;;;;;;;;OAQG;cALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,IAAI;;;;;;;;cAjEL,OAAO;;;;iBACP,OAAO;;;;eACP,OAAO"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Notify.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAEf;;;;;;;OAOG;IACH,WALW,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,IAAI,CAKhB;IAED;;;;;;;OAOG;IACH,cALW,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,OAAO,CAOnB;IAED;;;;;;;;;OASG;IACH,SANW,MAAM,WACN,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,MAAM,IAAI,CAYtB;IAED;;;;;;;;OAQG;IACH,UANW,MAAM,WACN,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,IAAI,CAIhB;;CAWF;;;;;;;cAhFa,OAAO;;;;iBACP,OAAO;;;;eACP,OAAO"}

package/types/node/index.d.ts

@@ -13,7 +13,7 @@ export { default as FileObject } from "./lib/FileObject.js";
 export { default as FileSystem } from "./lib/FileSystem.js";
 export { default as Font } from "./lib/Font.js";
 export { default as Glog } from "./lib/Glog.js";
-export { default as Notify } from "./lib/Notify.js";
 export { default as Term } from "./lib/Term.js";
 export { default as Disposer, Disposer as DisposerClass } from "../browser/lib/Disposer.js";
+export { default as Notify, Notify as NotifyClass } from "./lib/Notify.js";
 //# sourceMappingURL=index.d.ts.map

package/types/node/lib/DirectoryObject.d.ts

@@ -266,28 +266,55 @@ export default class DirectoryObject extends FS {
     /**
      * Creates a new DirectoryObject by extending this directory's path.
      *
+     * Paths are always resolved relative to THIS directory. Any attempt to
+     * escape via `..` or absolute paths is constrained - the `..` segments
+     * are stripped and the remaining path is resolved relative to this directory.
+     *
+     * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+     * are also constrained - the drive root is stripped and the path is resolved
+     * relative to this directory.
+     *
      * Uses overlapping path segment detection to intelligently combine paths.
-     * Preserves the temporary flag from the current directory.
      *
      * @param {string} newPath - The path to append to this directory's path.
      * @returns {DirectoryObject} A new DirectoryObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const subDir = dir.addDirectory("src/lib")
+     * const subDir = dir.getDirectory("src/lib")
      * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+     *
+     * @example
+     * // Path traversal is constrained to this directory
+     * const dir = new DirectoryObject("/projects/git/toolkit")
+     * const escaped = dir.getDirectory("../../../foo/bar")
+     * console.log(escaped.path) // "/projects/git/toolkit/foo/bar"
      */
     getDirectory(newPath: string): DirectoryObject;
     /**
      * Creates a new FileObject by extending this directory's path.
      *
+     * Paths are always resolved relative to THIS directory. Any attempt to
+     * escape via `..` or absolute paths is constrained - the `..` segments
+     * are stripped and the remaining path is resolved relative to this directory.
+     *
+     * On Windows, cross-drive absolute paths (e.g., `D:\foo` when base is `C:\`)
+     * are also constrained - the drive root is stripped and the path is resolved
+     * relative to this directory.
+     *
      * Uses overlapping path segment detection to intelligently combine paths.
      *
      * @param {string} filename - The filename to append to this directory's path.
      * @returns {FileObject} A new FileObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const file = dir.addFile("package.json")
+     * const file = dir.getFile("package.json")
      * console.log(file.path) // "/projects/git/toolkit/package.json"
+     *
+     * @example
+     * // Path traversal is constrained to this directory
+     * const dir = new DirectoryObject("/projects/git/toolkit")
+     * const escaped = dir.getFile("../../../foo/bar.js")
+     * console.log(escaped.path) // "/projects/git/toolkit/foo/bar.js"
      */
     getFile(filename: string): FileObject;
     #private;

package/types/node/lib/DirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA8CpF;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAiD/F;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;OAYG;IACH,sBAPW,MAAM,GACJ,eAAe,CA6B3B;IAED;;;;;;;;;;;OAWG;IACH,kBAPW,MAAM,GACJ,UAAU,CA6BtB;;CACF;;UAnlBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;uBADT,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA8CpF;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAiD/F;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBAbW,MAAM,GACJ,eAAe,CAkC3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkCtB;;CACF;;UA5mBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;uBADT,iBAAiB"}

package/types/node/lib/FileSystem.d.ts

@@ -101,26 +101,45 @@ export default class FileSystem {
      * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
      * @returns {string|null} The relative path, empty string if paths are identical, or null if no overlap found
      * @example
-     * FS.toRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+     * FS.toLocalRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
+     * FS.toLocalRelativePath("/home/user", "/home/user") // ""
+     * FS.toLocalRelativePath("/projects/app", "/other/path") // null
+     */
+    static toLocalRelativePath(from: string, to: string, sep?: string): string | null;
+    /**
+     * Computes the relative path from one path to another using Node's path.relative.
+     *
+     * Unlike toLocalRelativePath which uses overlap detection, this method uses
+     * standard relative path calculation and may return paths with ".." segments.
+     *
+     * @static
+     * @param {string} from - The base path to calculate relative from
+     * @param {string} to - The target path to make relative
+     * @returns {string} The relative path, or empty string if paths are identical
+     * @example
+     * FS.toRelativePath("/home/user", "/home/user/docs") // "docs"
      * FS.toRelativePath("/home/user", "/home/user") // ""
-     * FS.toRelativePath("/projects/app", "/other/path") // null
+     * FS.toRelativePath("/home/user", "/home/other") // "../other"
      */
-    static toRelativePath(from: string, to: string, sep?: string): string | null;
+    static toRelativePath(from: string, to: string): string;
     /**
-     * Find the common root path between two paths by identifying overlapping segments.
-     * Returns the portion of 'from' that matches up to the overlap point in 'to'.
+     * Find where a path's final segment appears in another path, returning the
+     * portion of 'from' up to that overlap point.
+     *
+     * Looks for the last segment of `from` within `to`. If found, returns `from`
+     * sliced to the index where that segment appears in `to`.
      *
      * @static
-     * @param {string} from - The first path to compare
-     * @param {string} to - The second path to find common root with
+     * @param {string} from - The source path whose final segment to search for
+     * @param {string} to - The target path to search within
      * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-     * @returns {string|null} The common root path, the original path if identical, or null if no overlap found
+     * @returns {string|null} The sliced portion of from, the original path if identical, or null if no overlap
      * @throws {Sass} If from is not a non-empty string
      * @throws {Sass} If to is not a non-empty string
      * @example
-     * FS.getCommonRootPath("/projects/toolkit/src", "/projects/toolkit/tests") // "/projects/toolkit"
+     * FS.getCommonRootPath("/projects/toolkit", "/projects/toolkit/src") // "/projects/toolkit"
      * FS.getCommonRootPath("/home/user", "/home/user") // "/home/user"
-     * FS.getCommonRootPath("/projects/app", "/other/path") // null
+     * FS.getCommonRootPath("/projects/app", "/other/path") // null (no overlap)
      */
     static getCommonRootPath(from: string, to: string, sep?: string): string | null;
     /**

package/types/node/lib/FileSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAzTD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAwSF;yBA3Ua,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,iCATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,MACN,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAnVD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAkUF;yBArWa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}

package/types/node/lib/Notify.d.ts

@@ -1,8 +1,15 @@
-declare const _default: {
+/**
+ * @typedef {object} NotifyEventOptions
+ * @property {boolean} [once] - Whether the listener should be invoked only once.
+ * @property {AbortSignal} [signal] - An AbortSignal to remove the listener.
+ */
+/**
+ * Notify class provides a thin wrapper around EventEmitter for centralized
+ * event handling in Node.js applications. Mirrors the browser Notify API.
+ */
+export class Notify {
     /** @type {string} Display name for debugging. */
     name: string;
-    /** @type {EventEmitter} Internal event emitter */
-    "__#private@#emitter": EventEmitter;
     /**
      * Emits an event without expecting a return value.
      *
@@ -49,7 +56,9 @@ declare const _default: {
      * @returns {void}
      */
     off(type: string, handler: (payload: unknown) => void, emitter?: EventEmitter): void;
-};
+    #private;
+}
+declare const _default: Notify;
 export default _default;
 export type NotifyEventOptions = {
     /**

package/types/node/lib/Notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":";IAsBE,iDAAiD;UAAtC,MAAM;IAGjB,kDAAkD;2BAAvC,YAAY;IAGvB;;;;;;OAMG;eAHQ,MAAM,YACN,OAAO,GACL,IAAI;IAQjB;;;;;;;;OAQG;oBAHQ,MAAM,YACN,OAAO,GACL,OAAO,CAAC,IAAI,CAAC;IAQ1B;;;;;;;OAOG;kBAHQ,MAAM,YACN,OAAO,GACL,OAAO;IAUpB;;;;;;;;OAQG;aALQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI;IAevB;;;;;;;OAOG;cAJQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI;;;;;;;WAvFL,OAAO;;;;aACP,WAAW"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;GAGG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAKf;;;;;;OAMG;IACH,WAJW,MAAM,YACN,OAAO,GACL,IAAI,CAMhB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI,CAatB;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI,CAMhB;;CACF;;;;;;;WA9Fa,OAAO;;;;aACP,WAAW"}