@gesslar/toolkit 3.20.0 → 3.22.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.20.0",
+  "version": "3.22.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -58,7 +58,7 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^0.6.0",
+    "@gesslar/uglier": "^1.0.0",
     "eslint": "^9.39.2",
     "happy-dom": "^20.1.0",
     "typescript": "^5.9.3"

package/src/node/lib/DirectoryObject.js

@@ -9,8 +9,8 @@ import path from "node:path"
 import {URL} from "node:url"
 
 import Data from "../../browser/lib/Data.js"
-import FS from "./FileSystem.js"
 import FileObject from "./FileObject.js"
+import FS from "./FileSystem.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 import VFileObject from "./VFileObject.js"
@@ -531,6 +531,60 @@ export default class DirectoryObject extends FS {
     return candidateDir === this.path
   }
 
+  /**
+   * Resolves an absolute virtual path from cap root and validates it stays within cap boundary.
+   *
+   * @private
+   * @param {string} absolutePath - Absolute virtual path starting with separator
+   * @returns {string} Normalized resolved virtual path
+   * @throws {Sass} If path would be out of bounds
+   */
+  #resolveAndValidateFromCap(absolutePath) {
+    const relativeFromCap = Data.chopLeft(absolutePath, this.sep)
+    const resolvedVirtualPath = FS.resolvePath(this.cap.path, relativeFromCap)
+    const normalized = FS.fixSlashes(resolvedVirtualPath)
+
+    // Validate cap boundary using real paths
+    const relativeFromCapForReal = normalized.startsWith(this.sep)
+      ? Data.chopLeft(normalized, this.sep)
+      : normalized
+    const resolvedRealPath = FS.resolvePath(
+      this.cap.real.path,
+      relativeFromCapForReal
+    )
+
+    if(!FS.pathContains(this.cap.real.path, resolvedRealPath)) {
+      throw Sass.new(`${normalized} would be out of bounds (cap: ${this.cap.path}).`)
+    }
+
+    return normalized
+  }
+
+  /**
+   * Validates that a resolved virtual path stays within the cap boundary.
+   *
+   * @private
+   * @param {string} virtualPath - Resolved virtual path
+   * @returns {string} Normalized virtual path
+   * @throws {Sass} If path would be out of bounds
+   */
+  #validateCapBoundary(virtualPath) {
+    const normalized = FS.fixSlashes(virtualPath)
+    const relativeFromCap = normalized.startsWith(this.sep)
+      ? Data.chopLeft(normalized, this.sep)
+      : normalized
+    const resolvedRealPath = FS.resolvePath(
+      this.cap.real.path,
+      relativeFromCap
+    )
+
+    if(!FS.pathContains(this.cap.real.path, resolvedRealPath)) {
+      throw Sass.new(`${normalized} would be out of bounds (cap: ${this.cap.path}).`)
+    }
+
+    return normalized
+  }
+
   /**
    * Creates a new DirectoryObject by extending this directory's path.
    *
@@ -555,11 +609,34 @@ export default class DirectoryObject extends FS {
   getDirectory(dir) {
     Valid.type(dir, "String", {allowEmpty: false})
 
+    // Handle VDirectoryObject with absolute virtual paths (starting with "/")
+    if(this.isVirtual && dir.startsWith(this.sep)) {
+      const normalized = this.#resolveAndValidateFromCap(dir)
+
+      return new this.constructor(normalized, this)
+    }
+
+    // Regular resolution
     const newPath = FS.resolvePath(this.path, dir)
 
-    Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
+    // Validate bounds
+    if(!this.isVirtual) {
+      // Regular DO: enforce local-only constraint
+      Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
+
+      return new this.constructor(newPath, this)
+    }
+
+    // VDO relative paths: only allow nested if explicitly prefixed with ./
+    // This maintains security while allowing explicit relative navigation
+    if(dir.includes(this.sep) && !dir.startsWith(`.${this.sep}`)) {
+      throw Sass.new(`${dir} would be out of bounds. Use "./${dir}" for nested paths or chain getDirectory() calls.`)
+    }
+
+    // VDO relative paths: validate cap boundary and pass resolved path
+    const normalized = this.#validateCapBoundary(newPath)
 
-    return new this.constructor(newPath, this)
+    return new this.constructor(normalized, this)
   }
 
   /**
@@ -569,31 +646,58 @@ export default class DirectoryObject extends FS {
    * duplication. The resulting FileObject can be used for reading, writing,
    * and other file operations.
    *
+   * For regular DirectoryObject: only allows direct children (local only).
+   * For VDirectoryObject: supports absolute virtual paths (starting with "/")
+   * which resolve from cap root, and relative paths from current directory.
+   *
    * When called on a VDirectoryObject, returns a VFileObject to maintain
    * virtual path semantics.
    *
-   * @param {string} file - The filename to append (can include subdirectories like "src/index.js")
+   * @param {string} file - The filename to append
    * @returns {FileObject|VFileObject} A new FileObject (or VFileObject if virtual)
    * @throws {Sass} If filename is not a string
+   * @throws {Sass} If path would be out of bounds
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
    * const file = dir.getFile("package.json")
    * console.log(file.path) // "/projects/git/toolkit/package.json"
    *
    * @example
-   * // Can include nested paths
-   * const file = dir.getFile("src/index.js")
-   * const data = await file.read()
+   * // VDirectoryObject with absolute virtual path
+   * const vdo = new TempDirectoryObject("myapp")
+   * const file = vdo.getFile("/config/settings.json")
+   * // Virtual path: /config/settings.json, Real path: {vdo.real.path}/config/settings.json
    */
   getFile(file) {
     Valid.type(file, "String", {allowEmpty: false})
 
-    const newPath = FS.resolvePath(this.path, file)
+    // Handle VDirectoryObject with absolute virtual paths (starting with "/")
+    if(this.isVirtual && file.startsWith(this.sep)) {
+      const normalized = this.#resolveAndValidateFromCap(file)
 
-    Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
+      return new VFileObject(normalized, this)
+    }
 
-    return this.isVirtual
-      ? new VFileObject(file, this)
-      : new FileObject(file, this)
+    // Regular resolution
+    const resolvedPath = FS.resolvePath(this.path, file)
+
+    // Validate bounds
+    if(!this.isVirtual) {
+      // Regular DO: enforce local-only constraint
+      Valid.assert(this.#isLocal(resolvedPath), `${resolvedPath} would be out of bounds.`)
+
+      return new FileObject(file, this)
+    }
+
+    // VDO relative paths: only allow nested if explicitly prefixed with ./
+    // This maintains security while allowing explicit relative navigation
+    if(file.includes(this.sep) && !file.startsWith(`.${this.sep}`)) {
+      throw Sass.new(`${file} would be out of bounds. Use "./${file}" for nested paths or chain getFile() calls.`)
+    }
+
+    // VDO relative paths: validate cap boundary and pass resolved path
+    const normalized = this.#validateCapBoundary(resolvedPath)
+
+    return new VFileObject(normalized, this)
   }
 }

package/src/node/lib/Glog.js

@@ -79,6 +79,7 @@ class Glog {
   static stackTrace = false
   static name = ""
   static tagsAsStrings = false
+  static symbols = null
 
   // Instance properties (for configured loggers)
   #logLevel = 0
@@ -88,6 +89,7 @@ class Glog {
   #name = ""
   #tagsAsStrings = false
   #displayName = true
+  #symbols = null
   #vscodeError = null
   #vscodeWarn = null
   #vscodeInfo = null
@@ -101,6 +103,7 @@ class Glog {
    * @param {number} [options.logLevel] - Alias for debugLevel
    * @param {string} [options.prefix] - Prefix to prepend to all log messages
    * @param {object} [options.colours] - Colour configuration object
+   * @param {object} [options.symbols] - Custom log level symbols (e.g., {info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
    * @param {boolean} [options.stackTrace=false] - Enable stack trace extraction
    * @param {boolean} [options.tagsAsStrings=false] - Use string tags instead of symbols
    * @param {boolean} [options.displayName=true] - Display logger name in output
@@ -135,6 +138,7 @@ class Glog {
    * @param {number} [options.logLevel] - Alias for debugLevel
    * @param {string} [options.prefix] - Prefix to prepend to all log messages
    * @param {object} [options.colours] - Colour configuration object
+   * @param {object} [options.symbols] - Custom log level symbols (e.g., {info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
    * @param {boolean} [options.stackTrace] - Enable stack trace extraction
    * @param {boolean} [options.tagsAsStrings] - Use string tags instead of symbols
    * @param {boolean} [options.displayName] - Display logger name in output
@@ -145,6 +149,13 @@ class Glog {
     this.#logLevel = options.debugLevel ?? options.logLevel ?? this.#logLevel
     this.#logPrefix = options.prefix ?? this.#logPrefix
     this.#colours = options.colours ?? this.#colours
+
+    if(options.symbols) {
+      const base = this.#symbols ?? logSymbols
+
+      this.#symbols = Object.assign({}, base, options.symbols)
+    }
+
     this.#stackTrace = options.stackTrace ?? this.#stackTrace
     this.#tagsAsStrings = options.tagsAsStrings ?? this.#tagsAsStrings
     this.#displayName = options.displayName ?? this.#displayName
@@ -231,6 +242,23 @@ class Glog {
     return this
   }
 
+  /**
+   * Customize log level symbols for global usage
+   * Merges with existing symbols (can pass partial config)
+   * Only affects output when tagsAsStrings is false
+   * Shape: {debug?: string, info?: string, warn?: string, error?: string, success?: string}
+   *
+   * @param {object} [symbols=logSymbols] - Symbol configuration object (partial or complete)
+   * @returns {typeof Glog} The Glog class for chaining
+   * @example
+   * Glog.withSymbols({info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
+   */
+  static withSymbols(symbols = logSymbols) {
+    this.symbols = Object.assign({}, this.symbols ?? logSymbols, symbols)
+
+    return this
+  }
+
   /**
    * Create a temporary scoped logger with a custom prefix for a single chain (static version)
    * The prefix replaces all formatting (name, tags) with just the prefix + message
@@ -368,6 +396,23 @@ class Glog {
     return this
   }
 
+  /**
+   * Customize log level symbols for this logger instance
+   * Merges with existing symbols (can pass partial config)
+   * Only affects output when tagsAsStrings is false
+   * Shape: {debug?: string, info?: string, warn?: string, error?: string, success?: string}
+   *
+   * @param {object} [symbols=logSymbols] - Symbol configuration object (partial or complete)
+   * @returns {Glog} This Glog instance for chaining
+   * @example
+   * logger.withSymbols({info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
+   */
+  withSymbols(symbols = logSymbols) {
+    this.#symbols = Object.assign({}, this.#symbols ?? logSymbols, symbols)
+
+    return this
+  }
+
   /**
    * Disable displaying the logger name in output for this instance
    *
@@ -474,7 +519,8 @@ class Glog {
     const name = this.#name || Glog.name || "Log"
     const useStrings = this.#tagsAsStrings || Glog.tagsAsStrings
     const showName = this.#displayName
-    const tag = useStrings ? Util.capitalize(level) : logSymbols[level]
+    const symbols = this.#symbols || Glog.symbols || logSymbols
+    const tag = useStrings ? Util.capitalize(level) : symbols[level]
     const namePrefix = showName ? `[${name}] ` : ""
 
     if(!colours) {
@@ -693,7 +739,8 @@ class Glog {
     const colours = this.colours || loggerColours
     const name = this.name || "Log"
     const useStrings = this.tagsAsStrings
-    const tag = useStrings ? "Success" : logSymbols.success
+    const symbols = this.symbols || logSymbols
+    const tag = useStrings ? "Success" : symbols.success
     const colourCode = colours.success || "{F046}"
     const formatted = useStrings
       ? c`[${name}] ${colourCode}${tag}{/}: ${message}`
@@ -731,7 +778,8 @@ class Glog {
     const colours = this.colours || loggerColours
     const name = this.name || "Log"
     const useStrings = this.tagsAsStrings
-    const tag = useStrings ? "Debug" : logSymbols.debug
+    const symbols = this.symbols || logSymbols
+    const tag = useStrings ? "Debug" : symbols.debug
     const colourCode = colours.debug[level] || colours.debug[0]
     const label = useStrings
       ? c`[${name}] ${colourCode}${tag}{/}: ${message}`
@@ -749,7 +797,8 @@ class Glog {
     const colours = this.colours || loggerColours
     const name = this.name || "Log"
     const useStrings = this.tagsAsStrings
-    const tag = useStrings ? "Info" : logSymbols.info
+    const symbols = this.symbols || logSymbols
+    const tag = useStrings ? "Info" : symbols.info
     const label = useStrings
       ? c`[${name}] ${colours.info}${tag}{/}: ${message}`
       : c`[${name}] ${colours.info}${tag}{/} ${message}`
@@ -765,7 +814,8 @@ class Glog {
   static groupSuccess(message) {
     const name = this.name || "Log"
     const useStrings = this.tagsAsStrings
-    const tag = useStrings ? "Success" : logSymbols.success
+    const symbols = this.symbols || logSymbols
+    const tag = useStrings ? "Success" : symbols.success
     const label = useStrings
       ? c`[${name}] {success}${tag}{/}: ${message}`
       : c`[${name}] {success}${tag}{/} ${message}`
@@ -822,7 +872,8 @@ class Glog {
     const name = this.#name || Glog.name || "Log"
     const useStrings = this.#tagsAsStrings || Glog.tagsAsStrings
     const showName = this.#displayName
-    const tag = useStrings ? "Success" : logSymbols.success
+    const symbols = this.#symbols || Glog.symbols || logSymbols
+    const tag = useStrings ? "Success" : symbols.success
     const namePrefix = showName ? `[${name}] ` : ""
     const label = useStrings
       ? c`${namePrefix}{success}${tag}{/}: ${message}`

package/src/node/lib/VFileObject.js

@@ -4,6 +4,7 @@
  * Extends FileObject with virtual path support and real filesystem mapping.
  */
 
+import DirectoryObject from "./DirectoryObject.js"
 import FileObject from "./FileObject.js"
 import FS from "./FileSystem.js"
 import Valid from "./Valid.js"
@@ -34,20 +35,55 @@ export default class VFileObject extends FileObject {
   /**
    * Constructs a VFileObject instance.
    *
-   * @param {string} fileName - The file path
-   * @param {VDirectoryObject} parent - The parent virtual directory (required)
+   * @param {string} virtualPath - The virtual file path (already resolved, can be nested like "/path/to/file.ext")
+   * @param {VDirectoryObject} parent - The parent virtual directory (required, used for cap reference)
    */
-  constructor(fileName, parent) {
-    Valid.type(fileName, "String", {allowEmpty: false})
+  constructor(virtualPath, parent) {
+    Valid.type(virtualPath, "String", {allowEmpty: false})
     Valid.type(parent, "VDirectoryObject")
 
-    super(fileName, parent)
+    // Normalize the virtual path
+    const normalizedVirtual = FS.fixSlashes(virtualPath)
 
-    const parentRealPath = this.parent.real.path
-    const resolved = FS.resolvePath(this.parent.path, fileName)
-    const {base} = FS.pathParts(resolved)
+    // Extract the directory and filename from the virtual path
+    const {dir: virtualDir, base} = FS.pathParts(normalizedVirtual)
 
-    this.#real = new FileObject(base, parentRealPath)
+    // Determine the virtual parent directory
+    // If virtualDir is "/" or empty or equals cap path, use the cap root
+    // Otherwise, construct the parent directory path relative to cap
+    let virtualParent
+    if(!virtualDir || virtualDir === "/" || virtualDir === parent.cap.path) {
+      virtualParent = parent.cap
+    } else {
+      // virtualDir is something like "/path/to" - we need to create a VDirectoryObject for it
+      // Strip leading "/" if present to make it relative to cap
+      const dirRelativeToCap = virtualDir.startsWith("/") ? virtualDir.slice(1) : virtualDir
+      // Use the VDirectoryObject constructor to create the parent directory
+      virtualParent = new parent.constructor(dirRelativeToCap, parent.cap)
+    }
+
+    // Call super with just the filename and the virtual parent
+    // This ensures FileObject sets up the virtual path correctly
+    super(base, virtualParent)
+
+    // Convert virtual path to real path
+    // The virtual path is relative to the cap root, so we resolve it relative to cap's real path
+    const capRealPath = parent.cap.real.path
+
+    // Strip leading "/" from virtual path if present to make it relative
+    const relativeFromCap = normalizedVirtual.startsWith("/")
+      ? normalizedVirtual.slice(1)
+      : normalizedVirtual
+
+    // Resolve the real filesystem path
+    const realPath = FS.resolvePath(capRealPath, relativeFromCap)
+
+    // Create FileObject with the full real path
+    // Extract directory and filename parts
+    const {dir: realDir, base: realBase} = FS.pathParts(realPath)
+    const realParentDir = new DirectoryObject(realDir)
+
+    this.#real = new FileObject(realBase, realParentDir)
   }
 
   get isVirtual() {

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

@@ -276,21 +276,27 @@ export default class DirectoryObject extends FS {
      * duplication. The resulting FileObject can be used for reading, writing,
      * and other file operations.
      *
+     * For regular DirectoryObject: only allows direct children (local only).
+     * For VDirectoryObject: supports absolute virtual paths (starting with "/")
+     * which resolve from cap root, and relative paths from current directory.
+     *
      * When called on a VDirectoryObject, returns a VFileObject to maintain
      * virtual path semantics.
      *
-     * @param {string} file - The filename to append (can include subdirectories like "src/index.js")
+     * @param {string} file - The filename to append
      * @returns {FileObject|VFileObject} A new FileObject (or VFileObject if virtual)
      * @throws {Sass} If filename is not a string
+     * @throws {Sass} If path would be out of bounds
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
      * const file = dir.getFile("package.json")
      * console.log(file.path) // "/projects/git/toolkit/package.json"
      *
      * @example
-     * // Can include nested paths
-     * const file = dir.getFile("src/index.js")
-     * const data = await file.read()
+     * // VDirectoryObject with absolute virtual path
+     * const vdo = new TempDirectoryObject("myapp")
+     * const file = vdo.getFile("/config/settings.json")
+     * // Virtual path: /config/settings.json, Real path: {vdo.real.path}/config/settings.json
      */
     getFile(file: string): FileObject | VFileObject;
     #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":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA2DE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA3CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA0BjB;IA2BD;;;;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;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CA0CjH;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CAgDjH;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,CAQ5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAUD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAdW,MAAM,GACJ,eAAe,CAqB3B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAbW,MAAM,GACJ,UAAU,GAAC,WAAW,CAsBlC;;CACF;eA3kBc,iBAAiB;uBACT,iBAAiB;wBAGhB,kBAAkB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA2DE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA3CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA0BjB;IA2BD;;;;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;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CA0CjH;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CAgDjH;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,CAQ5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAgED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAdW,MAAM,GACJ,eAAe,CA4C3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAfW,MAAM,GACJ,UAAU,GAAC,WAAW,CA6ClC;;CACF;eAlrBc,iBAAiB;uBADT,iBAAiB;wBAIhB,kBAAkB"}

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

@@ -30,6 +30,7 @@ declare class Glog {
     static stackTrace: boolean;
     static name: string;
     static tagsAsStrings: boolean;
+    static symbols: any;
     /**
      * Set the log prefix for global usage
      *
@@ -77,6 +78,18 @@ declare class Glog {
      * @returns {typeof Glog} The Glog class for chaining
      */
     static withTagsAsStrings(enabled?: boolean): typeof Glog;
+    /**
+     * Customize log level symbols for global usage
+     * Merges with existing symbols (can pass partial config)
+     * Only affects output when tagsAsStrings is false
+     * Shape: {debug?: string, info?: string, warn?: string, error?: string, success?: string}
+     *
+     * @param {object} [symbols=logSymbols] - Symbol configuration object (partial or complete)
+     * @returns {typeof Glog} The Glog class for chaining
+     * @example
+     * Glog.withSymbols({info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
+     */
+    static withSymbols(symbols?: object): typeof Glog;
     /**
      * Create a temporary scoped logger with a custom prefix for a single chain (static version)
      * The prefix replaces all formatting (name, tags) with just the prefix + message
@@ -192,6 +205,7 @@ declare class Glog {
      * @param {number} [options.logLevel] - Alias for debugLevel
      * @param {string} [options.prefix] - Prefix to prepend to all log messages
      * @param {object} [options.colours] - Colour configuration object
+     * @param {object} [options.symbols] - Custom log level symbols (e.g., {info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
      * @param {boolean} [options.stackTrace=false] - Enable stack trace extraction
      * @param {boolean} [options.tagsAsStrings=false] - Use string tags instead of symbols
      * @param {boolean} [options.displayName=true] - Display logger name in output
@@ -203,6 +217,7 @@ declare class Glog {
         logLevel?: number;
         prefix?: string;
         colours?: object;
+        symbols?: object;
         stackTrace?: boolean;
         tagsAsStrings?: boolean;
         displayName?: boolean;
@@ -217,6 +232,7 @@ declare class Glog {
      * @param {number} [options.logLevel] - Alias for debugLevel
      * @param {string} [options.prefix] - Prefix to prepend to all log messages
      * @param {object} [options.colours] - Colour configuration object
+     * @param {object} [options.symbols] - Custom log level symbols (e.g., {info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
      * @param {boolean} [options.stackTrace] - Enable stack trace extraction
      * @param {boolean} [options.tagsAsStrings] - Use string tags instead of symbols
      * @param {boolean} [options.displayName] - Display logger name in output
@@ -228,6 +244,7 @@ declare class Glog {
         logLevel?: number;
         prefix?: string;
         colours?: object;
+        symbols?: object;
         stackTrace?: boolean;
         tagsAsStrings?: boolean;
         displayName?: boolean;
@@ -279,6 +296,18 @@ declare class Glog {
      * @returns {Glog} This Glog instance for chaining
      */
     withTagsAsStrings(enabled?: boolean): Glog;
+    /**
+     * Customize log level symbols for this logger instance
+     * Merges with existing symbols (can pass partial config)
+     * Only affects output when tagsAsStrings is false
+     * Shape: {debug?: string, info?: string, warn?: string, error?: string, success?: string}
+     *
+     * @param {object} [symbols=logSymbols] - Symbol configuration object (partial or complete)
+     * @returns {Glog} This Glog instance for chaining
+     * @example
+     * logger.withSymbols({info: '🚒', warn: '🚨', error: '🔥', success: '💧', debug: '🧯'})
+     */
+    withSymbols(symbols?: object): Glog;
     /**
      * Disable displaying the logger name in output for this instance
      *

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

@@ -1 +1 @@
-{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":"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"}

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

@@ -21,10 +21,10 @@ export default class VFileObject extends FileObject {
     /**
      * Constructs a VFileObject instance.
      *
-     * @param {string} fileName - The file path
-     * @param {VDirectoryObject} parent - The parent virtual directory (required)
+     * @param {string} virtualPath - The virtual file path (already resolved, can be nested like "/path/to/file.ext")
+     * @param {VDirectoryObject} parent - The parent virtual directory (required, used for cap reference)
      */
-    constructor(fileName: string, parent: VDirectoryObject);
+    constructor(virtualPath: string, parent: VDirectoryObject);
     get isVirtual(): boolean;
     get real(): FileObject;
     #private;

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

@@ -1 +1 @@
-{"version":3,"file":"VFileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/VFileObject.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;IAGE;;;;;OAKG;IACH,sBAHW,MAAM,UACN,gBAAgB,EAa1B;IAED,yBAEC;IAED,uBAEC;;CACF;uBArDsB,iBAAiB"}
+{"version":3,"file":"VFileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/VFileObject.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;IAGE;;;;;OAKG;IACH,yBAHW,MAAM,UACN,gBAAgB,EAgD1B;IAED,yBAEC;IAED,uBAEC;;CACF;uBAxFsB,iBAAiB"}