@genesislcap/foundation-logger 15.40.0 → 15.42.0

package/README.md

@@ -4,6 +4,39 @@ Documentation for this package is published on the Genesis docs site:
 
 **Docs: [Utility methods](https://docs.genesis.global/docs/develop/client-capabilities/utility-methods/)**
 
+## Log output
+
+Console messages do **not** include an in-message timestamp by default (Chrome's DevTools clock is separate). Opt in with a live global switch so every `createLogger` instance, including those already created by Foundation packages, prefixes messages with local time including milliseconds (for example `11:52:03.412`):
+
+```ts
+import { setLogTimestamps } from '@genesislcap/foundation-logger';
+
+setLogTimestamps(true);
+```
+
+The flag is stored on `globalThis` via `Symbol.for`, so one call also reaches Module Federation remotes that bundled their own copy of this package (rather than sharing the host's module).
+
+Enable or disable the prefix on one logger only:
+
+```ts
+import { createLogger } from '@genesislcap/foundation-logger';
+
+createLogger('demo', { timestamps: true });
+createLogger('quiet', { timestamps: false });
+createLogger('legacy', { formatOptions: { date: true } });
+```
+
+Options passed to `createLogger` are always merged with `defaultLoggerOptions`. Callers that omit `level` therefore get `debug` (this package's default), not Consola's bare `info` default.
+
+A default reporter is only installed in the browser. Outside the browser Consola has no default
+reporter, so loggers stay silent unless you pass `reporters` explicitly:
+
+```ts
+import { createLogger, TimestampBrowserReporter } from '@genesislcap/foundation-logger';
+
+createLogger('node-side', { reporters: [new TimestampBrowserReporter()] });
+```
+
 ## Installation
 
 Add the package to your `package.json` dependencies. After changing dependencies, run `npm run bootstrap` (or your project's equivalent). See [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) for more information.

package/dist/dts/index.d.ts

@@ -1,2 +1,4 @@
+export * from './log-timestamps';
 export * from './logger';
+export * from './timestamp-browser-reporter';
 //# sourceMappingURL=index.d.ts.map

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,8BAA8B,CAAC"}

package/dist/dts/log-timestamps.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Enables or disables the in-message timestamp prefix for all `createLogger` instances.
+ *
+ * @remarks
+ * This is a live flag: existing loggers pick it up on the next message. Per-logger
+ * `timestamps: true | false` and `formatOptions.date: true` still override it.
+ *
+ * The value is stored on `globalThis` via `Symbol.for` so one call covers every runtime
+ * copy of this package (for example host + federated remotes that did not share the module).
+ *
+ * @example Enable timestamps for every Foundation logger from app bootstrap.
+ * ```ts
+ * import { setLogTimestamps } from '@genesislcap/foundation-logger';
+ * setLogTimestamps(true);
+ * ```
+ *
+ * @param enabled - Whether to prefix console messages with a local timestamp.
+ * @public
+ */
+export declare function setLogTimestamps(enabled: boolean): void;
+/**
+ * Returns whether the global timestamp prefix is currently enabled.
+ *
+ * @returns `true` when {@link setLogTimestamps} was last called with `true`.
+ * @public
+ */
+export declare function areLogTimestampsEnabled(): boolean;
+//# sourceMappingURL=log-timestamps.d.ts.map

package/dist/dts/log-timestamps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-timestamps.d.ts","sourceRoot":"","sources":["../../src/log-timestamps.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}

package/dist/dts/logger.d.ts

@@ -14,9 +14,18 @@ import { ConsolaInstance, ConsolaOptions } from 'consola/core';
 export { LogLevel, LogLevels, LogType } from 'consola/core';
 /**
  * Options for creating a logger.
+ *
+ * @remarks
+ * `timestamps` overrides the global {@link setLogTimestamps} flag for this logger only.
+ * `undefined` follows the global flag; `true` always prefixes; `false` never prefixes.
+ *
  * @public
  */
 export interface LoggerOptions extends Partial<ConsolaOptions> {
+    /**
+     * Per-logger timestamp prefix override.
+     */
+    timestamps?: boolean;
 }
 /**
  * A logger that extends the `Consola` logger.
@@ -57,12 +66,29 @@ export interface Logger extends ConsolaInstance {
 }
 /**
  * The default logger options.
+ *
+ * @remarks
+ * `formatOptions.date` is `false` so Consola's built-in `date: true` default does not turn
+ * the prefix on. Enable timestamps with {@link setLogTimestamps} or per-logger options.
+ *
+ * These defaults are always merged into `createLogger` options. Callers that pass options
+ * without a `level` therefore get `debug`, not Consola's bare `info` default.
+ *
  * @public
  */
 export declare const defaultLoggerOptions: LoggerOptions;
 /**
  * Creates a logger with the given name and options.
  *
+ * @remarks
+ * Timestamp prefixes are opt-in. Call {@link setLogTimestamps} once at app bootstrap to enable
+ * them for every logger (including instances already created), or pass `timestamps: true` /
+ * `formatOptions.date: true` on a single logger. All Consola options are forwarded, not only
+ * `level`.
+ *
+ * A default reporter is only installed in the browser. Outside the browser, pass `reporters`
+ * explicitly to produce output.
+ *
  * @example Create a logger in my-package/utils.
  * ```ts
  * import { createLogger } from '@genesislcap/foundation-logger';

package/dist/dts/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,cAAc,EAGf,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO,CAAC,cAAc,CAAC;CAAG;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,MAAO,SAAQ,eAAe;IAC7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvF;AAED;;;GAGG;AACH,MAAM,WAAW,MAAO,SAAQ,eAAe;CAAG;AAElD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAElC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAoC,GAAG,MAAM,CAgBhG"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,cAAc,EAGf,MAAM,cAAc,CAAC;AAItB;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO,CAAC,cAAc,CAAC;IAC5D;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,MAAO,SAAQ,eAAe;IAC7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvF;AAED;;;GAGG;AACH,MAAM,WAAW,MAAO,SAAQ,eAAe;CAAG;AAElD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAKlC,CAAC;AAwBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAgB9E"}

package/dist/dts/timestamp-browser-reporter.d.ts

@@ -0,0 +1,45 @@
+import type { ConsolaOptions, ConsolaReporter, LogObject } from 'consola/core';
+/**
+ * Formats a log timestamp as local time with milliseconds.
+ *
+ * @example
+ * ```ts
+ * formatLogTimestamp(new Date('2026-01-15T11:52:03.412')); // "11:52:03.412" in local time
+ * ```
+ *
+ * @param date - The date to format, typically Consola's `logObj.date`.
+ * @returns A `HH:mm:ss.SSS` timestamp string.
+ * @public
+ */
+export declare function formatLogTimestamp(date: Date): string;
+/**
+ * Consola reporter based on the built-in browser reporter, with a local timestamp prefix.
+ *
+ * @remarks
+ * Prefixes each message with {@link formatLogTimestamp} using Consola's `logObj.date`.
+ * In browsers the original badge styling is preserved; in non-browser environments a
+ * plain `[tag:type]` label is used so `%c` CSS specifiers are not printed literally.
+ *
+ * Off by default. Enable for every logger with `setLogTimestamps(true)`, for one logger
+ * with `timestamps: true` or `formatOptions.date: true`, or replace the reporter via
+ * `createLogger(name, { reporters })`.
+ *
+ * @public
+ */
+export declare class TimestampBrowserReporter implements ConsolaReporter {
+    private readonly defaultColor;
+    private readonly levelColorMap;
+    private readonly typeColorMap;
+    /**
+     * Writes a log object to the console, prefixed with `logObj.date` when enabled.
+     *
+     * @param logObj - The Consola log object. See Consola's `LogObject`.
+     * @param ctx - Reporter context, including Consola options.
+     */
+    log(logObj: LogObject, ctx: {
+        options: ConsolaOptions;
+    }): void;
+    private logWithBrowserStyles;
+    private logPlain;
+}
+//# sourceMappingURL=timestamp-browser-reporter.d.ts.map

package/dist/dts/timestamp-browser-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-browser-reporter.d.ts","sourceRoot":"","sources":["../../src/timestamp-browser-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAgB/E;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMrD;AAwBD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAC9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAI5B;IACF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAE3B;IAEF;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAe9D,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,QAAQ;CAyBjB"}

package/dist/esm/index.js

@@ -1 +1,3 @@
+export * from './log-timestamps';
 export * from './logger';
+export * from './timestamp-browser-reporter';

package/dist/esm/log-timestamps.js

@@ -0,0 +1,37 @@
+/**
+ * Shared across every copy of this module (including Module Federation remotes that
+ * bundled their own `@genesislcap/foundation-logger`). A plain module-level `let` would
+ * leave each copy with its own flag, so the host's `setLogTimestamps` would not reach them.
+ */
+const LOG_TIMESTAMPS_FLAG = Symbol.for('@genesislcap/foundation-logger:timestamps');
+/**
+ * Enables or disables the in-message timestamp prefix for all `createLogger` instances.
+ *
+ * @remarks
+ * This is a live flag: existing loggers pick it up on the next message. Per-logger
+ * `timestamps: true | false` and `formatOptions.date: true` still override it.
+ *
+ * The value is stored on `globalThis` via `Symbol.for` so one call covers every runtime
+ * copy of this package (for example host + federated remotes that did not share the module).
+ *
+ * @example Enable timestamps for every Foundation logger from app bootstrap.
+ * ```ts
+ * import { setLogTimestamps } from '@genesislcap/foundation-logger';
+ * setLogTimestamps(true);
+ * ```
+ *
+ * @param enabled - Whether to prefix console messages with a local timestamp.
+ * @public
+ */
+export function setLogTimestamps(enabled) {
+    Reflect.set(globalThis, LOG_TIMESTAMPS_FLAG, enabled);
+}
+/**
+ * Returns whether the global timestamp prefix is currently enabled.
+ *
+ * @returns `true` when {@link setLogTimestamps} was last called with `true`.
+ * @public
+ */
+export function areLogTimestampsEnabled() {
+    return Reflect.get(globalThis, LOG_TIMESTAMPS_FLAG) === true;
+}

package/dist/esm/logger.js

@@ -1,5 +1,6 @@
 import { createConsola as createConsolaBrowser } from 'consola/browser';
 import { LogLevels, createConsola as createConsolaCore, } from 'consola/core';
+import { TimestampBrowserReporter } from './timestamp-browser-reporter';
 /**
  * Used to set the logging level.
  *
@@ -15,14 +16,47 @@ import { LogLevels, createConsola as createConsolaCore, } from 'consola/core';
 export { LogLevels } from 'consola/core';
 /**
  * The default logger options.
+ *
+ * @remarks
+ * `formatOptions.date` is `false` so Consola's built-in `date: true` default does not turn
+ * the prefix on. Enable timestamps with {@link setLogTimestamps} or per-logger options.
+ *
+ * These defaults are always merged into `createLogger` options. Callers that pass options
+ * without a `level` therefore get `debug`, not Consola's bare `info` default.
+ *
  * @public
  */
 export const defaultLoggerOptions = {
     level: LogLevels.debug,
+    formatOptions: {
+        date: false,
+    },
 };
+const browserReporter = new TimestampBrowserReporter();
+function resolveLoggerOptions(options, isBrowser) {
+    const resolved = Object.assign(Object.assign(Object.assign({}, defaultLoggerOptions), options), { formatOptions: Object.assign(Object.assign({}, defaultLoggerOptions.formatOptions), options.formatOptions) });
+    /**
+     * Consola ships no reporter outside the browser, so `reporters` is left unset there to keep
+     * non-browser output silent. Setting it would start emitting logs from Node-side consumers
+     * and test runs that have never produced any.
+     */
+    if (isBrowser && !resolved.reporters) {
+        resolved.reporters = [browserReporter];
+    }
+    return resolved;
+}
 /**
  * Creates a logger with the given name and options.
  *
+ * @remarks
+ * Timestamp prefixes are opt-in. Call {@link setLogTimestamps} once at app bootstrap to enable
+ * them for every logger (including instances already created), or pass `timestamps: true` /
+ * `formatOptions.date: true` on a single logger. All Consola options are forwarded, not only
+ * `level`.
+ *
+ * A default reporter is only installed in the browser. Outside the browser, pass `reporters`
+ * explicitly to produce output.
+ *
  * @example Create a logger in my-package/utils.
  * ```ts
  * import { createLogger } from '@genesislcap/foundation-logger';
@@ -49,11 +83,10 @@ export const defaultLoggerOptions = {
  * @returns The resulting logger.
  * @public
  */
-export function createLogger(name, options = defaultLoggerOptions) {
-    const createConsola = typeof window !== 'undefined' ? createConsolaBrowser : createConsolaCore;
-    const logger = createConsola().withTag(name);
-    if ((options === null || options === void 0 ? void 0 : options.level) !== undefined)
-        logger.level = options.level;
+export function createLogger(name, options = {}) {
+    const isBrowser = typeof window !== 'undefined';
+    const createConsola = isBrowser ? createConsolaBrowser : createConsolaCore;
+    const logger = createConsola(resolveLoggerOptions(options, isBrowser)).withTag(name);
     const typedLogger = logger;
     typedLogger.deprecated = (symbol, instruction = 'Consult docs for better alternative.', removalVersionTarget) => {
         typedLogger.warn(`Deprecated symbol used '${symbol}'. ${instruction}`, `${removalVersionTarget ? `Will be removed in version ${removalVersionTarget}.` : ''}`);

package/dist/esm/timestamp-browser-reporter.js

@@ -0,0 +1,118 @@
+import { areLogTimestampsEnabled } from './log-timestamps';
+const TIME_UNIT_DIGITS = 2;
+const MILLISECOND_DIGITS = 3;
+/**
+ * Formats a log timestamp as local time with milliseconds.
+ *
+ * @example
+ * ```ts
+ * formatLogTimestamp(new Date('2026-01-15T11:52:03.412')); // "11:52:03.412" in local time
+ * ```
+ *
+ * @param date - The date to format, typically Consola's `logObj.date`.
+ * @returns A `HH:mm:ss.SSS` timestamp string.
+ * @public
+ */
+export function formatLogTimestamp(date) {
+    const hours = String(date.getHours()).padStart(TIME_UNIT_DIGITS, '0');
+    const minutes = String(date.getMinutes()).padStart(TIME_UNIT_DIGITS, '0');
+    const seconds = String(date.getSeconds()).padStart(TIME_UNIT_DIGITS, '0');
+    const milliseconds = String(date.getMilliseconds()).padStart(MILLISECOND_DIGITS, '0');
+    return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+}
+function getConsoleLogFn(level) {
+    const consolaConsole = console;
+    if (level < 1) {
+        return consolaConsole.__error || consolaConsole.error;
+    }
+    if (level === 1) {
+        return consolaConsole.__warn || consolaConsole.warn;
+    }
+    return consolaConsole.__log || consolaConsole.log;
+}
+function shouldIncludeTimestamp(ctx) {
+    var _a, _b, _c;
+    const timestamps = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.options) === null || _a === void 0 ? void 0 : _a.timestamps;
+    if (typeof timestamps === 'boolean') {
+        return timestamps;
+    }
+    if (((_c = (_b = ctx === null || ctx === void 0 ? void 0 : ctx.options) === null || _b === void 0 ? void 0 : _b.formatOptions) === null || _c === void 0 ? void 0 : _c.date) === true) {
+        return true;
+    }
+    return areLogTimestampsEnabled();
+}
+/**
+ * Consola reporter based on the built-in browser reporter, with a local timestamp prefix.
+ *
+ * @remarks
+ * Prefixes each message with {@link formatLogTimestamp} using Consola's `logObj.date`.
+ * In browsers the original badge styling is preserved; in non-browser environments a
+ * plain `[tag:type]` label is used so `%c` CSS specifiers are not printed literally.
+ *
+ * Off by default. Enable for every logger with `setLogTimestamps(true)`, for one logger
+ * with `timestamps: true` or `formatOptions.date: true`, or replace the reporter via
+ * `createLogger(name, { reporters })`.
+ *
+ * @public
+ */
+export class TimestampBrowserReporter {
+    constructor() {
+        this.defaultColor = '#7f8c8d';
+        this.levelColorMap = {
+            0: '#c0392b',
+            1: '#f39c12',
+            3: '#00BCD4',
+        };
+        this.typeColorMap = {
+            success: '#2ecc71',
+        };
+    }
+    /**
+     * Writes a log object to the console, prefixed with `logObj.date` when enabled.
+     *
+     * @param logObj - The Consola log object. See Consola's `LogObject`.
+     * @param ctx - Reporter context, including Consola options.
+     */
+    log(logObj, ctx) {
+        const consoleLogFn = getConsoleLogFn(logObj.level);
+        const type = logObj.type === 'log' ? '' : logObj.type;
+        const tag = logObj.tag || '';
+        const timestamp = shouldIncludeTimestamp(ctx) ? formatLogTimestamp(logObj.date) : '';
+        const useBrowserStyles = typeof window !== 'undefined' && !!(tag || type);
+        if (useBrowserStyles) {
+            this.logWithBrowserStyles(consoleLogFn, logObj, tag, type, timestamp);
+            return;
+        }
+        this.logPlain(consoleLogFn, logObj, tag, type, timestamp);
+    }
+    logWithBrowserStyles(consoleLogFn, logObj, tag, type, timestamp) {
+        const color = this.typeColorMap[logObj.type] || this.levelColorMap[logObj.level] || this.defaultColor;
+        const style = `
+      background: ${color};
+      border-radius: 0.5em;
+      color: white;
+      font-weight: bold;
+      padding: 2px 0.5em;
+    `;
+        const badge = `%c${[tag, type].filter(Boolean).join(':')}`;
+        const prefix = timestamp ? `${timestamp} ${badge}` : badge;
+        if (typeof logObj.args[0] === 'string') {
+            consoleLogFn(`${prefix}%c ${logObj.args[0]}`, style, '', ...logObj.args.slice(1));
+            return;
+        }
+        consoleLogFn(prefix, style, ...logObj.args);
+    }
+    logPlain(consoleLogFn, logObj, tag, type, timestamp) {
+        const label = [tag, type].filter(Boolean).join(':');
+        const prefix = [timestamp, label ? `[${label}]` : ''].filter(Boolean).join(' ');
+        if (typeof logObj.args[0] === 'string') {
+            consoleLogFn(prefix ? `${prefix} ${logObj.args[0]}` : logObj.args[0], ...logObj.args.slice(1));
+            return;
+        }
+        if (prefix) {
+            consoleLogFn(prefix, ...logObj.args);
+            return;
+        }
+        consoleLogFn(...logObj.args);
+    }
+}

package/dist/foundation-logger.api.json

@@ -172,10 +172,38 @@
       "name": "",
       "preserveMemberOrder": false,
       "members": [
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-logger!areLogTimestampsEnabled:function(1)",
+          "docComment": "/**\n * Returns whether the global timestamp prefix is currently enabled.\n *\n * @returns `true` when {@link setLogTimestamps} was last called with `true`.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function areLogTimestampsEnabled(): "
+            },
+            {
+              "kind": "Content",
+              "text": "boolean"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/log-timestamps.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [],
+          "name": "areLogTimestampsEnabled"
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/foundation-logger!createLogger:function(1)",
-          "docComment": "/**\n * Creates a logger with the given name and options.\n *\n * @param name - The name to give the logger.\n *\n * @param options - The options to use when creating the logger.\n *\n * @returns The resulting logger.\n *\n * @example\n *\n * Create a logger in my-package/utils.\n * ```ts\n * import { createLogger } from '@genesislcap/foundation-logger';\n * export const logger = createLogger('my-package');\n * ```\n *\n * @example\n *\n * Using the logger within my-package.\n * ```ts\n * import { logger } from '../utils';\n * logger.debug(`Data retrieved from ${resourceName}`);\n * logger.info(this.toggled ? 'On' : 'Off');\n * logger.warn('Not available in this browser.');\n * ```\n *\n * @example\n *\n * Explicitly set the level of an imported package.\n * ```ts\n * import { logger as commsLogger } from '@genesislcap/foundation-comms';\n * import { LogLevel } from '@genesislcap/foundation-logger';\n * commsLogger.level = LogLevel.Warn;\n * ```\n *\n * @public\n */\n",
+          "docComment": "/**\n * Creates a logger with the given name and options.\n *\n * @remarks\n *\n * Timestamp prefixes are opt-in. Call {@link setLogTimestamps} once at app bootstrap to enable them for every logger (including instances already created), or pass `timestamps: true` / `formatOptions.date: true` on a single logger. All Consola options are forwarded, not only `level`.\n *\n * A default reporter is only installed in the browser. Outside the browser, pass `reporters` explicitly to produce output.\n *\n * @param name - The name to give the logger.\n *\n * @param options - The options to use when creating the logger.\n *\n * @returns The resulting logger.\n *\n * @example\n *\n * Create a logger in my-package/utils.\n * ```ts\n * import { createLogger } from '@genesislcap/foundation-logger';\n * export const logger = createLogger('my-package');\n * ```\n *\n * @example\n *\n * Using the logger within my-package.\n * ```ts\n * import { logger } from '../utils';\n * logger.debug(`Data retrieved from ${resourceName}`);\n * logger.info(this.toggled ? 'On' : 'Off');\n * logger.warn('Not available in this browser.');\n * ```\n *\n * @example\n *\n * Explicitly set the level of an imported package.\n * ```ts\n * import { logger as commsLogger } from '@genesislcap/foundation-comms';\n * import { LogLevel } from '@genesislcap/foundation-logger';\n * commsLogger.level = LogLevel.Warn;\n * ```\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -238,7 +266,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-logger!defaultLoggerOptions:var",
-          "docComment": "/**\n * The default logger options.\n *\n * @public\n */\n",
+          "docComment": "/**\n * The default logger options.\n *\n * @remarks\n *\n * `formatOptions.date` is `false` so Consola's built-in `date: true` default does not turn the prefix on. Enable timestamps with {@link setLogTimestamps} or per-logger options.\n *\n * These defaults are always merged into `createLogger` options. Callers that pass options without a `level` therefore get `debug`, not Consola's bare `info` default.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -259,6 +287,52 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-logger!formatLogTimestamp:function(1)",
+          "docComment": "/**\n * Formats a log timestamp as local time with milliseconds.\n *\n * @param date - The date to format, typically Consola's `logObj.date`.\n *\n * @returns A `HH:mm:ss.SSS` timestamp string.\n *\n * @example\n * ```ts\n * formatLogTimestamp(new Date('2026-01-15T11:52:03.412')); // \"11:52:03.412\" in local time\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function formatLogTimestamp(date: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Date",
+              "canonicalReference": "!Date:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/timestamp-browser-reporter.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "date",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "formatLogTimestamp"
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-logger!Logger:interface",
@@ -371,7 +445,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-logger!LoggerOptions:interface",
-          "docComment": "/**\n * Options for creating a logger.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Options for creating a logger.\n *\n * @remarks\n *\n * `timestamps` overrides the global {@link setLogTimestamps} flag for this logger only. `undefined` follows the global flag; `true` always prefixes; `false` never prefixes.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -404,13 +478,193 @@
           "releaseTag": "Public",
           "name": "LoggerOptions",
           "preserveMemberOrder": false,
-          "members": [],
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-logger!LoggerOptions#timestamps:member",
+              "docComment": "/**\n * Per-logger timestamp prefix override.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "timestamps?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "timestamps",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
           "extendsTokenRanges": [
             {
               "startIndex": 1,
               "endIndex": 5
             }
           ]
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-logger!setLogTimestamps:function(1)",
+          "docComment": "/**\n * Enables or disables the in-message timestamp prefix for all `createLogger` instances.\n *\n * @remarks\n *\n * This is a live flag: existing loggers pick it up on the next message. Per-logger `timestamps: true | false` and `formatOptions.date: true` still override it.\n *\n * The value is stored on `globalThis` via `Symbol.for` so one call covers every runtime copy of this package (for example host + federated remotes that did not share the module).\n *\n * @param enabled - Whether to prefix console messages with a local timestamp.\n *\n * @example\n *\n * Enable timestamps for every Foundation logger from app bootstrap.\n * ```ts\n * import { setLogTimestamps } from '@genesislcap/foundation-logger';\n * setLogTimestamps(true);\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function setLogTimestamps(enabled: "
+            },
+            {
+              "kind": "Content",
+              "text": "boolean"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/log-timestamps.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "enabled",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "setLogTimestamps"
+        },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/foundation-logger!TimestampBrowserReporter:class",
+          "docComment": "/**\n * Consola reporter based on the built-in browser reporter, with a local timestamp prefix.\n *\n * @remarks\n *\n * Prefixes each message with {@link formatLogTimestamp} using Consola's `logObj.date`. In browsers the original badge styling is preserved; in non-browser environments a plain `[tag:type]` label is used so `%c` CSS specifiers are not printed literally.\n *\n * Off by default. Enable for every logger with `setLogTimestamps(true)`, for one logger with `timestamps: true` or `formatOptions.date: true`, or replace the reporter via `createLogger(name, { reporters })`.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class TimestampBrowserReporter implements "
+            },
+            {
+              "kind": "Reference",
+              "text": "ConsolaReporter",
+              "canonicalReference": "consola!ConsolaReporter:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/timestamp-browser-reporter.ts",
+          "releaseTag": "Public",
+          "isAbstract": false,
+          "name": "TimestampBrowserReporter",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/foundation-logger!TimestampBrowserReporter#log:member(1)",
+              "docComment": "/**\n * Writes a log object to the console, prefixed with `logObj.date` when enabled.\n *\n * @param logObj - The Consola log object. See Consola's `LogObject`.\n *\n * @param ctx - Reporter context, including Consola options.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "log(logObj: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "LogObject",
+                  "canonicalReference": "consola!LogObject:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", ctx: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "{\n        options: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ConsolaOptions",
+                  "canonicalReference": "consola!ConsolaOptions:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n    }"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 7,
+                "endIndex": 8
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "logObj",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "ctx",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "log"
+            }
+          ],
+          "implementsTokenRanges": [
+            {
+              "startIndex": 1,
+              "endIndex": 2
+            }
+          ]
         }
       ]
     }

package/dist/foundation-logger.d.ts

@@ -1,12 +1,31 @@
 import { ConsolaInstance } from 'consola/core';
 import { ConsolaOptions } from 'consola/core';
+import type { ConsolaReporter } from 'consola/core';
 import { LogLevel } from 'consola/core';
 import { LogLevels } from 'consola/core';
+import type { LogObject } from 'consola/core';
 import { LogType } from 'consola/core';
 
+/**
+ * Returns whether the global timestamp prefix is currently enabled.
+ *
+ * @returns `true` when {@link setLogTimestamps} was last called with `true`.
+ * @public
+ */
+export declare function areLogTimestampsEnabled(): boolean;
+
 /**
  * Creates a logger with the given name and options.
  *
+ * @remarks
+ * Timestamp prefixes are opt-in. Call {@link setLogTimestamps} once at app bootstrap to enable
+ * them for every logger (including instances already created), or pass `timestamps: true` /
+ * `formatOptions.date: true` on a single logger. All Consola options are forwarded, not only
+ * `level`.
+ *
+ * A default reporter is only installed in the browser. Outside the browser, pass `reporters`
+ * explicitly to produce output.
+ *
  * @example Create a logger in my-package/utils.
  * ```ts
  * import { createLogger } from '@genesislcap/foundation-logger';
@@ -37,10 +56,32 @@ export declare function createLogger(name: string, options?: LoggerOptions): Log
 
 /**
  * The default logger options.
+ *
+ * @remarks
+ * `formatOptions.date` is `false` so Consola's built-in `date: true` default does not turn
+ * the prefix on. Enable timestamps with {@link setLogTimestamps} or per-logger options.
+ *
+ * These defaults are always merged into `createLogger` options. Callers that pass options
+ * without a `level` therefore get `debug`, not Consola's bare `info` default.
+ *
  * @public
  */
 export declare const defaultLoggerOptions: LoggerOptions;
 
+/**
+ * Formats a log timestamp as local time with milliseconds.
+ *
+ * @example
+ * ```ts
+ * formatLogTimestamp(new Date('2026-01-15T11:52:03.412')); // "11:52:03.412" in local time
+ * ```
+ *
+ * @param date - The date to format, typically Consola's `logObj.date`.
+ * @returns A `HH:mm:ss.SSS` timestamp string.
+ * @public
+ */
+export declare function formatLogTimestamp(date: Date): string;
+
 /**
  * A logger that extends the `Consola` logger.
  *
@@ -82,9 +123,18 @@ export declare interface Logger extends ConsolaInstance {
 
 /**
  * Options for creating a logger.
+ *
+ * @remarks
+ * `timestamps` overrides the global {@link setLogTimestamps} flag for this logger only.
+ * `undefined` follows the global flag; `true` always prefixes; `false` never prefixes.
+ *
  * @public
  */
 export declare interface LoggerOptions extends Partial<ConsolaOptions> {
+    /**
+     * Per-logger timestamp prefix override.
+     */
+    timestamps?: boolean;
 }
 
 export { LogLevel }
@@ -93,4 +143,56 @@ export { LogLevels }
 
 export { LogType }
 
+/**
+ * Enables or disables the in-message timestamp prefix for all `createLogger` instances.
+ *
+ * @remarks
+ * This is a live flag: existing loggers pick it up on the next message. Per-logger
+ * `timestamps: true | false` and `formatOptions.date: true` still override it.
+ *
+ * The value is stored on `globalThis` via `Symbol.for` so one call covers every runtime
+ * copy of this package (for example host + federated remotes that did not share the module).
+ *
+ * @example Enable timestamps for every Foundation logger from app bootstrap.
+ * ```ts
+ * import { setLogTimestamps } from '@genesislcap/foundation-logger';
+ * setLogTimestamps(true);
+ * ```
+ *
+ * @param enabled - Whether to prefix console messages with a local timestamp.
+ * @public
+ */
+export declare function setLogTimestamps(enabled: boolean): void;
+
+/**
+ * Consola reporter based on the built-in browser reporter, with a local timestamp prefix.
+ *
+ * @remarks
+ * Prefixes each message with {@link formatLogTimestamp} using Consola's `logObj.date`.
+ * In browsers the original badge styling is preserved; in non-browser environments a
+ * plain `[tag:type]` label is used so `%c` CSS specifiers are not printed literally.
+ *
+ * Off by default. Enable for every logger with `setLogTimestamps(true)`, for one logger
+ * with `timestamps: true` or `formatOptions.date: true`, or replace the reporter via
+ * `createLogger(name, { reporters })`.
+ *
+ * @public
+ */
+export declare class TimestampBrowserReporter implements ConsolaReporter {
+    private readonly defaultColor;
+    private readonly levelColorMap;
+    private readonly typeColorMap;
+    /**
+     * Writes a log object to the console, prefixed with `logObj.date` when enabled.
+     *
+     * @param logObj - The Consola log object. See Consola's `LogObject`.
+     * @param ctx - Reporter context, including Consola options.
+     */
+    log(logObj: LogObject, ctx: {
+        options: ConsolaOptions;
+    }): void;
+    private logWithBrowserStyles;
+    private logPlain;
+}
+
 export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-logger",
   "description": "Genesis Foundation Logger",
-  "version": "15.40.0",
+  "version": "15.42.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -12,6 +12,8 @@
     "circular": "npx -y madge --extensions ts --circular ./src",
     "clean": "rimraf dist temp tsconfig.tsbuildinfo",
     "dev": "genx dev -b ts",
+    "//test": "Node uvu (not genx test / Playwright) so createLogger's typeof-window===undefined path is covered; Playwright always defines window and would silently lose that case.",
+    "test": "uvu -r tsx/cjs . 'test.ts' --i dist --i coverage --i temp",
     "lint": "genx lint -l ox",
     "lint:fix": "genx lint -l ox --fix"
   },
@@ -22,6 +24,12 @@
       }
     }
   },
+  "devDependencies": {
+    "@types/sinon": "^10.0.13",
+    "sinon": "^17.0.1",
+    "tsx": "^4.7.0",
+    "uvu": "0.5.4"
+  },
   "dependencies": {
     "consola": "^3.0.0"
   },