@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/logger/index.js

@@ -0,0 +1,232 @@
+import { i as isErrorLike } from "../../chunks/ErrorLike-Cfj0lZW3.js";
+import { s as serializeError } from "../../chunks/SerializeError-CclP2jCW.js";
+const LogLevel = {
+  /** Refers to the finest-grained diagnostics — per-iteration detail, off in every deployed environment. */
+  Trace: "trace",
+  /** Refers to developer-facing detail for diagnosing — request payloads, cache hits, retry decisions. */
+  Debug: "debug",
+  /** Refers to the normal-operation narrative — lifecycle milestones worth keeping in production. */
+  Info: "info",
+  /** Refers to a recovered or degraded condition — the app continued, but something was off. */
+  Warn: "warn",
+  /** Refers to a failure the app could not absorb — the level the `error` payload rides on. */
+  Error: "error",
+  /** Refers to the threshold that drops everything. Only ever set as a level; never emitted on a record. */
+  Silent: "silent"
+};
+const LogLevelSeverity = {
+  [LogLevel.Trace]: 10,
+  [LogLevel.Debug]: 20,
+  [LogLevel.Info]: 30,
+  [LogLevel.Warn]: 40,
+  [LogLevel.Error]: 50,
+  [LogLevel.Silent]: Number.POSITIVE_INFINITY
+};
+function isLogLevel(value) {
+  return typeof value === "string" && Object.hasOwn(LogLevelSeverity, value);
+}
+function isLevelEnabled(level, threshold) {
+  if (level === LogLevel.Silent) return false;
+  return LogLevelSeverity[level] >= LogLevelSeverity[threshold];
+}
+const DefaultRedactKeys = ["password", "token", "secret", "authorization", "apiKey"];
+const DefaultRedactionMask = "[redacted]";
+const CircularMarker = "[circular]";
+const UnreadableMarker = "[unreadable]";
+const TruncatedMarker = "[truncated]";
+const DefaultMaxRedactDepth = 8;
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+}
+function readProperty(source, key) {
+  try {
+    return source[key];
+  } catch {
+    return UnreadableMarker;
+  }
+}
+function readKeys(source) {
+  try {
+    return Object.keys(source);
+  } catch {
+    return [];
+  }
+}
+function redactValue(value, keys, mask, depth, path) {
+  if (!Array.isArray(value) && !isPlainObject(value)) return value;
+  const container = value;
+  if (path.has(container)) return CircularMarker;
+  if (depth >= DefaultMaxRedactDepth) return TruncatedMarker;
+  path.add(container);
+  try {
+    if (Array.isArray(value)) {
+      const items = [];
+      for (const item of value) items.push(redactValue(item, keys, mask, depth + 1, path));
+      return items;
+    }
+    const copy = {};
+    for (const key of readKeys(value)) {
+      copy[key] = keys.has(key.toLowerCase()) ? mask : redactValue(readProperty(value, key), keys, mask, depth + 1, path);
+    }
+    return copy;
+  } finally {
+    path.delete(container);
+  }
+}
+function redactContext(context, redactKeys = DefaultRedactKeys, mask = DefaultRedactionMask) {
+  try {
+    const keys = new Set(redactKeys.map((key) => key.toLowerCase()));
+    const redacted = redactValue(context, keys, mask, 0, /* @__PURE__ */ new Set());
+    return isPlainObject(redacted) ? redacted : {};
+  } catch {
+    return {};
+  }
+}
+const DefaultLogLevel = LogLevel.Info;
+function copyContext(context) {
+  if (context === void 0) return {};
+  try {
+    return { ...context };
+  } catch {
+    return {};
+  }
+}
+function createLoggerFrom(core, context) {
+  const report = (error, sink, record) => {
+    if (!core.onError) return;
+    try {
+      core.onError(error, { sink, record });
+    } catch {
+    }
+  };
+  const emit = (level, message, callContext, failure) => {
+    try {
+      if (!isLevelEnabled(level, core.level)) return;
+      let merged = context;
+      if (callContext !== void 0) {
+        try {
+          merged = { ...context, ...callContext };
+        } catch {
+          merged = context;
+        }
+      }
+      const record = {
+        level,
+        message,
+        timestamp: core.now(),
+        context: redactContext(merged, core.redactKeys, core.mask),
+        ...failure ? { error: serializeError(failure.value) } : {}
+      };
+      for (const sink of core.sinks) {
+        try {
+          sink.write(record);
+        } catch (sinkFailure) {
+          report(sinkFailure, sink, record);
+        }
+      }
+    } catch {
+    }
+  };
+  return {
+    trace: (message, callContext) => emit(LogLevel.Trace, message, callContext),
+    debug: (message, callContext) => emit(LogLevel.Debug, message, callContext),
+    info: (message, callContext) => emit(LogLevel.Info, message, callContext),
+    warn: (message, callContext) => emit(LogLevel.Warn, message, callContext),
+    error: (message, second, third) => {
+      if (second === void 0) {
+        emit(LogLevel.Error, message, third);
+        return;
+      }
+      if (isPlainObject(second) && !isErrorLike(second)) {
+        emit(LogLevel.Error, message, second);
+        return;
+      }
+      emit(LogLevel.Error, message, third, { value: second });
+    },
+    child: (childContext) => createLoggerFrom(core, { ...context, ...copyContext(childContext) }),
+    setLevel: (level) => {
+      if (isLogLevel(level)) core.level = level;
+    },
+    getLevel: () => core.level,
+    isEnabled: (level) => isLevelEnabled(level, core.level)
+  };
+}
+function createLogger(options = {}) {
+  const core = {
+    sinks: [...options.sinks ?? []],
+    redactKeys: options.redactKeys ?? DefaultRedactKeys,
+    mask: options.redactionMask ?? DefaultRedactionMask,
+    onError: options.onError,
+    now: options.now ?? Date.now,
+    level: isLogLevel(options.level) ? options.level : DefaultLogLevel
+  };
+  return createLoggerFrom(core, copyContext(options.context));
+}
+function resolveMethod(level) {
+  switch (level) {
+    case LogLevel.Trace:
+      return console.trace;
+    case LogLevel.Debug:
+      return console.debug;
+    case LogLevel.Info:
+      return console.info;
+    case LogLevel.Warn:
+      return console.warn;
+    case LogLevel.Error:
+      return console.error;
+    case LogLevel.Silent:
+      return void 0;
+  }
+}
+function consoleLogSink(options = {}) {
+  const prefix = options.prefix ?? "[log]";
+  return {
+    name: "console",
+    write: (record) => {
+      const method = resolveMethod(record.level) ?? console.log;
+      const args = [];
+      if (Object.keys(record.context).length > 0) args.push(record.context);
+      if (record.error !== void 0) args.push(record.error);
+      method.call(console, prefix === "" ? record.message : `${prefix} ${record.message}`, ...args);
+    }
+  };
+}
+function memoryLogSink() {
+  const records = [];
+  return {
+    name: "memory",
+    get records() {
+      return records;
+    },
+    write: (record) => {
+      records.push(record);
+    },
+    reset: () => {
+      records.length = 0;
+    }
+  };
+}
+export {
+  CircularMarker,
+  DefaultLogLevel,
+  DefaultMaxRedactDepth,
+  DefaultRedactKeys,
+  DefaultRedactionMask,
+  LogLevel,
+  LogLevelSeverity,
+  TruncatedMarker,
+  UnreadableMarker,
+  consoleLogSink,
+  createLogger,
+  isLevelEnabled,
+  isLogLevel,
+  memoryLogSink,
+  redactContext
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/logger/LogLevel.ts","../../../src/foundation/logger/Redaction.ts","../../../src/foundation/logger/Logger.ts","../../../src/foundation/logger/ConsoleLogSink.ts","../../../src/foundation/logger/MemoryLogSink.ts"],"sourcesContent":["// The severity vocabulary, plus the one comparison the emit path makes. A const object rather than a TS\n// `enum`, matching `BackoffStrategy` / `AnalyticsCallKind`: an `enum` emits a runtime object into every\n// consumer's bundle and is not erasable under `verbatimModuleSyntax`, while this shape tree-shakes and its\n// values are plain strings a sink can print or ship as-is.\n//\n// `Silent` is a THRESHOLD-ONLY value: it exists so `createLogger({ level: LogLevel.Silent })` drops\n// everything, and no record is ever emitted at it. Hence `Number.POSITIVE_INFINITY` for its severity —\n// nothing clears it — plus the explicit guard in `isLevelEnabled`, without which the degenerate\n// `isLevelEnabled(Silent, Silent)` (`Infinity >= Infinity`) would read as enabled.\n//\n// Severities are spaced by ten so a consumer can slot a custom level between two of ours without\n// renumbering the set.\n\n/** Defines the severity a record is emitted at — ordered `Trace` (finest) through `Error`, with `Silent` as the off switch. */\nexport const LogLevel = {\n  /** Refers to the finest-grained diagnostics — per-iteration detail, off in every deployed environment. */\n  Trace: 'trace',\n  /** Refers to developer-facing detail for diagnosing — request payloads, cache hits, retry decisions. */\n  Debug: 'debug',\n  /** Refers to the normal-operation narrative — lifecycle milestones worth keeping in production. */\n  Info: 'info',\n  /** Refers to a recovered or degraded condition — the app continued, but something was off. */\n  Warn: 'warn',\n  /** Refers to a failure the app could not absorb — the level the `error` payload rides on. */\n  Error: 'error',\n  /** Refers to the threshold that drops everything. Only ever set as a level; never emitted on a record. */\n  Silent: 'silent',\n} as const;\n\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/** Provides the numeric severity of each level — the ordering {@link isLevelEnabled} compares on. `Silent` is infinite, so nothing clears it. */\nexport const LogLevelSeverity: Readonly<Record<LogLevel, number>> = {\n  [LogLevel.Trace]: 10,\n  [LogLevel.Debug]: 20,\n  [LogLevel.Info]: 30,\n  [LogLevel.Warn]: 40,\n  [LogLevel.Error]: 50,\n  [LogLevel.Silent]: Number.POSITIVE_INFINITY,\n};\n\n/**\n * Checks whether a value is one of the known levels — guards the runtime `setLevel` dial and a level read\n * from an env var, where an unrecognized string would otherwise mute the logger in silence.\n *\n * Never throws.\n */\nexport function isLogLevel(value: unknown): value is LogLevel {\n  return typeof value === 'string' && Object.hasOwn(LogLevelSeverity, value);\n}\n\n/**\n * Checks whether a record at `level` clears `threshold` — the single comparison guarding the emit path,\n * made before any context merge, redaction, or error serialization is paid for.\n *\n * `Silent` never passes as a `level`, even against a `Silent` threshold.\n *\n * Never throws.\n */\nexport function isLevelEnabled(level: LogLevel, threshold: LogLevel): boolean {\n  if (level === LogLevel.Silent) return false;\n  return LogLevelSeverity[level] >= LogLevelSeverity[threshold];\n}\n","// Redaction runs on the way IN — inside the logger, before the record reaches any sink — rather than\n// inside each sink. A sink is third-party code that may ship off the device, so a secret that reaches one\n// has already leaked; asking every adapter to redact is asking for the one that forgets.\n//\n// Decisions:\n//\n// - **Keys match case-insensitively; matched values are dropped whole.** `Authorization` / `authorization`\n//   / `AUTHORIZATION` are the same header. A partial mask (`sk-…f31a`) still leaks a prefix and invites a\n//   per-call-site judgement about whether that is enough, so the value is replaced regardless of its type —\n//   a matched key whose value is an object does not get walked.\n// - **The walk copies; it never mutates.** The caller's object is theirs and is very often live\n//   application state — redacting in place would erase a real token from a real session, which is exactly\n//   the kind of damage a logger must never do.\n// - **Recursion covers arrays and PLAIN objects only.** `Object.keys(new Date())` is empty, so walking a\n//   `Date` / `Map` / `URL` / class instance would silently replace it with `{}`. Everything non-plain\n//   passes through by reference — worth knowing, because a secret held on a class instance is NOT redacted.\n//\n// The input is assumed hostile, because a context object is assembled at a call site that may itself be\n// mid-failure: a cycle is cut with `CircularMarker`, a throwing getter or `ownKeys` trap yields\n// `UnreadableMarker`, and depth is capped at `DefaultMaxRedactDepth`. The cap is fail-CLOSED — the subtree\n// becomes `TruncatedMarker` rather than passing through unredacted — and it is what keeps a pathological\n// graph from overflowing the stack, which is the one way this could otherwise break its no-throw contract.\n//\n// Cycles are tracked along the current PATH (added before descending, removed after), not globally, so a\n// value legitimately referenced by several siblings still renders each time instead of the second and later\n// occurrences reading as circular.\n\nimport type { LogContext } from './LogRecord';\n\n/** Provides the context keys redacted by default — the credential names that show up in practically every payload. */\nexport const DefaultRedactKeys: readonly string[] = ['password', 'token', 'secret', 'authorization', 'apiKey'];\n\n/** Provides the placeholder written over a redacted value. */\nexport const DefaultRedactionMask = '[redacted]';\n\n/** Provides the placeholder written where the walk met a value already on the current path. */\nexport const CircularMarker = '[circular]';\n\n/** Provides the placeholder written where reading a property threw — a getter or a `Proxy` trap. */\nexport const UnreadableMarker = '[unreadable]';\n\n/** Provides the placeholder written where the walk hit {@link DefaultMaxRedactDepth} — fail-closed, so nothing below it escapes unredacted. */\nexport const TruncatedMarker = '[truncated]';\n\n/** Provides how many levels the walk descends before truncating — deep enough for any real context, shallow enough to bound the work. */\nexport const DefaultMaxRedactDepth = 8;\n\n/**\n * Checks whether a value is a plain object — prototype `Object.prototype` or `null`. `getPrototypeOf` is a\n * trappable operation, so the read is guarded. Internal; not barrelled.\n */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== 'object') return false;\n  try {\n    const prototype: unknown = Object.getPrototypeOf(value);\n    return prototype === Object.prototype || prototype === null;\n  } catch {\n    return false;\n  }\n}\n\n/** Reads one property without trusting the source — a getter and a `Proxy` `get` trap can both throw. */\nfunction readProperty(source: Record<string, unknown>, key: string): unknown {\n  try {\n    return source[key];\n  } catch {\n    return UnreadableMarker;\n  }\n}\n\n/** Lists a source's own enumerable keys without trusting it — an `ownKeys` trap can throw. */\nfunction readKeys(source: Record<string, unknown>): readonly string[] {\n  try {\n    return Object.keys(source);\n  } catch {\n    return [];\n  }\n}\n\n/** Walks one value, copying it with matched keys masked. Recurses only into arrays and plain objects. */\nfunction redactValue(\n  value: unknown,\n  keys: ReadonlySet<string>,\n  mask: string,\n  depth: number,\n  path: Set<object>,\n): unknown {\n  if (!Array.isArray(value) && !isPlainObject(value)) return value;\n\n  const container: object = value;\n  if (path.has(container)) return CircularMarker;\n  if (depth >= DefaultMaxRedactDepth) return TruncatedMarker;\n\n  path.add(container);\n  try {\n    if (Array.isArray(value)) {\n      const items: unknown[] = [];\n      // `for…of` over the array itself — indexed access would be `T | undefined` under\n      // `noUncheckedIndexedAccess`, and a hole would then be indistinguishable from a stored `undefined`.\n      for (const item of value) items.push(redactValue(item, keys, mask, depth + 1, path));\n      return items;\n    }\n\n    const copy: Record<string, unknown> = {};\n    for (const key of readKeys(value)) {\n      copy[key] = keys.has(key.toLowerCase())\n        ? mask\n        : redactValue(readProperty(value, key), keys, mask, depth + 1, path);\n    }\n    return copy;\n  } finally {\n    path.delete(container);\n  }\n}\n\n/**\n * Copies a context object with every value under a matching key replaced by `mask`, at any nesting depth.\n * Key matching is case-insensitive.\n *\n * The result is always a fresh, cycle-free, depth-bounded plain object, so it is safe to `JSON.stringify`\n * and safe to hand to a sink that outlives the call. The source is never mutated.\n *\n * Never throws — a hostile context (throwing getters, `Proxy` traps, self-reference, pathological depth)\n * degrades to markers, and a total failure degrades to `{}`.\n */\nexport function redactContext(\n  context: LogContext,\n  redactKeys: readonly string[] = DefaultRedactKeys,\n  mask: string = DefaultRedactionMask,\n): LogContext {\n  try {\n    const keys = new Set(redactKeys.map((key) => key.toLowerCase()));\n    const redacted = redactValue(context, keys, mask, 0, new Set<object>());\n    // Non-plain input (a class instance cast to a context) is not walked, so it cannot be proven safe —\n    // dropping it keeps the \"always a plain, serializable object\" guarantee the sinks rely on.\n    return isPlainObject(redacted) ? redacted : {};\n  } catch {\n    return {};\n  }\n}\n","// The logger every app talks to. One contract dominates every decision in this file:\n//\n// DEFINING CONTRACT: NO METHOD HERE THROWS. `logger.error(...)` is called from `catch` blocks, error\n// boundaries, and unhandled-rejection handlers — precisely where a second exception masks the first and\n// takes down the path that was meant to recover. So the emit body is wrapped end to end, every sink is\n// invoked in isolation, and `onError` (itself wrapped) is the only place a failure ever surfaces. A hostile\n// context, a `Proxy` that throws from every trap, a sink that always throws, a clock that throws: all\n// degrade to a dropped or partial record, never to a raised exception.\n//\n// Decisions worth stating:\n//\n// - **The threshold is checked FIRST, before any work.** Merging context, walking it for redaction and\n//   serializing an error all cost more than a suppressed line is worth. Only the caller's own arguments are\n//   evaluated (`logger.debug('x', expensive())` still pays for `expensive()` — that is JS, not us); nothing\n//   this module controls is spent below the threshold, and no sink is touched.\n// - **`child()` forks the CONTEXT, and only the context.** Sinks, redaction config, `onError` and the clock\n//   are shared with the root — and so is the LEVEL, held in one mutable cell for the whole tree. That makes\n//   `setLevel` a single runtime dial (\"turn debug on\") instead of something to re-apply across every child\n//   an app has spawned. A child cannot diverge from its parent's level; that is the design, not a gap.\n// - **Context merges parent-first, so the more specific writer wins:** root < child < grandchild < call\n//   site. A child re-binding `requestId` overrides its parent's, which is how a reader expects the nearest\n//   scope to describe the record.\n// - **`error()`'s second argument is the ERROR unless it is a plain object that is not error-like.** This\n//   mirrors how TypeScript picks the overload — an `Error` instance is not assignable to `LogContext`\n//   (no index signature), so `error(msg, err)` resolves to the error signature and `error(msg, { userId })`\n//   to the context one. The one addition is that a PLAIN object which is error-like (`{ message: '…' }`) is\n//   also taken as the error, because `catch (e) { log.error('failed', e) }` — where a library threw a\n//   non-`Error` — is the whole reason the overload exists, and `e` is typed `unknown` there. The cost: a\n//   context whose fields include `message` reads as an error. Disambiguate with `error(msg, undefined, ctx)`.\n// - **One record object is shared across the fan-out.** Building a copy per sink would be pure waste;\n//   `LogRecord` is fully `readonly` so a sink is expected to treat it as immutable.\n\nimport { isErrorLike, serializeError } from '../errors';\nimport { isLevelEnabled, isLogLevel, LogLevel } from './LogLevel';\nimport type { LogContext, LogRecord } from './LogRecord';\nimport type { LogErrorHandler, LogSink } from './LogSink';\nimport { DefaultRedactionMask, DefaultRedactKeys, isPlainObject, redactContext } from './Redaction';\n\n/** Provides the level a logger starts at when the options name none — production-safe, so `debug` is opt-in. */\nexport const DefaultLogLevel: LogLevel = LogLevel.Info;\n\n/** Defines the options for {@link createLogger}. */\nexport interface LoggerOptions {\n  /** The starting threshold — records below it are dropped. Default {@link DefaultLogLevel}. */\n  readonly level?: LogLevel;\n\n  /** The sinks records fan out to. Copied on construction; empty means every call is a no-op. */\n  readonly sinks?: readonly LogSink[];\n\n  /** The base structured fields merged into every record — service name, release, session id. */\n  readonly context?: LogContext;\n\n  /** The context keys whose values are masked, at any depth, case-insensitively. Default {@link DefaultRedactKeys}. */\n  readonly redactKeys?: readonly string[];\n\n  /** The placeholder written over a redacted value. Default {@link DefaultRedactionMask}. */\n  readonly redactionMask?: string;\n\n  /** Receives every sink failure. Omitted means failures are swallowed — a broken sink is never worth an app crash. */\n  readonly onError?: LogErrorHandler;\n\n  /** Supplies the record timestamp (epoch ms) — injectable for deterministic tests. Default `Date.now`. */\n  readonly now?: () => number;\n}\n\n/** Defines the logger — five level methods, a context fork, and a runtime level dial. No method throws. */\nexport interface Logger {\n  /** Emits at `trace` — the finest detail, suppressed unless the threshold is lowered to it. */\n  trace(message: string, context?: LogContext): void;\n\n  /** Emits at `debug` — developer-facing detail while diagnosing. */\n  debug(message: string, context?: LogContext): void;\n\n  /** Emits at `info` — the normal-operation narrative. */\n  info(message: string, context?: LogContext): void;\n\n  /** Emits at `warn` — a recovered or degraded condition. */\n  warn(message: string, context?: LogContext): void;\n\n  /** Emits at `error` with structured context only. */\n  error(message: string, context?: LogContext): void;\n\n  /** Emits at `error` with a caught value, serialized onto the record's `error`. Pass `undefined` to log context under a `message` key. */\n  error(message: string, error: unknown, context?: LogContext): void;\n\n  /** Creates a logger whose records carry this one's context merged with `context` — the child's keys win. Sinks, level, and config are shared. */\n  child(context: LogContext): Logger;\n\n  /** Moves the threshold for the WHOLE logger tree at runtime — an unknown value is ignored rather than silently muting output. */\n  setLevel(level: LogLevel): void;\n\n  /** Reads the current threshold. */\n  getLevel(): LogLevel;\n\n  /** Checks whether a level would currently be emitted — guard an expensive context build with this. */\n  isEnabled(level: LogLevel): boolean;\n}\n\n/** Holds everything a logger tree shares — every field but `level` is fixed at construction. */\ninterface LoggerCore {\n  /** The sinks every record in the tree fans out to. */\n  readonly sinks: readonly LogSink[];\n\n  /** The keys redacted from every context in the tree. */\n  readonly redactKeys: readonly string[];\n\n  /** The mask written over a redacted value. */\n  readonly mask: string;\n\n  /** The sink-failure handler, when the app supplied one. */\n  readonly onError: LogErrorHandler | undefined;\n\n  /** The clock every record is stamped from. */\n  readonly now: () => number;\n\n  /** The threshold — the one mutable cell, shared by the root and every child. */\n  level: LogLevel;\n}\n\n/** Copies a context object without trusting it — a throwing getter must not turn construction into a failure. */\nfunction copyContext(context: LogContext | undefined): LogContext {\n  if (context === undefined) return {};\n  try {\n    return { ...context };\n  } catch {\n    return {};\n  }\n}\n\n/** Builds one logger node over a shared core and an already-safe context — the root and every child go through here. */\nfunction createLoggerFrom(core: LoggerCore, context: LogContext): Logger {\n  /** Routes a sink failure to `onError` — a handler that itself throws is swallowed, since there is nowhere left to report. */\n  const report = (error: unknown, sink: LogSink, record: LogRecord): void => {\n    if (!core.onError) return;\n    try {\n      core.onError(error, { sink, record });\n    } catch {\n      // The handler is the last line of defence; a throw here must not reach the caller either.\n    }\n  };\n\n  /**\n   * Builds one record and fans it out. `failure` is BOXED so that \"no error was logged\" stays distinct from\n   * \"the logged error was `undefined`\" — `error(msg, undefined, ctx)` means the former.\n   */\n  const emit = (\n    level: LogLevel,\n    message: string,\n    callContext?: LogContext,\n    failure?: { readonly value: unknown },\n  ): void => {\n    try {\n      if (!isLevelEnabled(level, core.level)) return;\n\n      let merged: LogContext = context;\n      if (callContext !== undefined) {\n        try {\n          merged = { ...context, ...callContext };\n        } catch {\n          // A hostile call-site context (a throwing getter, an `ownKeys` trap) costs its own fields, never\n          // the line — the message and the error still reach the sinks under the logger's own context.\n          merged = context;\n        }\n      }\n\n      const record: LogRecord = {\n        level,\n        message,\n        timestamp: core.now(),\n        context: redactContext(merged, core.redactKeys, core.mask),\n        ...(failure ? { error: serializeError(failure.value) } : {}),\n      };\n\n      for (const sink of core.sinks) {\n        try {\n          sink.write(record);\n        } catch (sinkFailure) {\n          report(sinkFailure, sink, record);\n        }\n      }\n    } catch {\n      // A failure in the emit path itself (a hostile context spread, a clock that throws) has no record to\n      // report against and no sink proven able to receive it — the contract says drop it, never raise it.\n    }\n  };\n\n  return {\n    trace: (message: string, callContext?: LogContext): void => emit(LogLevel.Trace, message, callContext),\n\n    debug: (message: string, callContext?: LogContext): void => emit(LogLevel.Debug, message, callContext),\n\n    info: (message: string, callContext?: LogContext): void => emit(LogLevel.Info, message, callContext),\n\n    warn: (message: string, callContext?: LogContext): void => emit(LogLevel.Warn, message, callContext),\n\n    error: (message: string, second?: unknown, third?: LogContext): void => {\n      // Nothing in the second slot: whatever is in the third is the context (the explicit disambiguator).\n      if (second === undefined) {\n        emit(LogLevel.Error, message, third);\n        return;\n      }\n      // A plain, non-error-like object is structured context — everything else is the caught value.\n      if (isPlainObject(second) && !isErrorLike(second)) {\n        emit(LogLevel.Error, message, second);\n        return;\n      }\n      emit(LogLevel.Error, message, third, { value: second });\n    },\n\n    child: (childContext: LogContext): Logger => createLoggerFrom(core, { ...context, ...copyContext(childContext) }),\n\n    setLevel: (level: LogLevel): void => {\n      if (isLogLevel(level)) core.level = level;\n    },\n\n    getLevel: (): LogLevel => core.level,\n\n    isEnabled: (level: LogLevel): boolean => isLevelEnabled(level, core.level),\n  };\n}\n\n/**\n * Creates a {@link Logger} — one per app (or per bounded context), shared by every caller under it.\n *\n * Nothing is wired by default: with no `sinks`, every call is a no-op, so an SDK consumer opts into output\n * explicitly rather than inheriting console noise. Fan out to `consoleLogSink()` in development and add a\n * shipping sink in production; `memoryLogSink()` is the test double.\n *\n * Never throws, and neither does any method on the returned logger.\n */\nexport function createLogger(options: LoggerOptions = {}): Logger {\n  const core: LoggerCore = {\n    sinks: [...(options.sinks ?? [])],\n    redactKeys: options.redactKeys ?? DefaultRedactKeys,\n    mask: options.redactionMask ?? DefaultRedactionMask,\n    onError: options.onError,\n    now: options.now ?? Date.now,\n    level: isLogLevel(options.level) ? options.level : DefaultLogLevel,\n  };\n\n  return createLoggerFrom(core, copyContext(options.context));\n}\n","// The dev sink — the one an app wires up first and the one it keeps in development.\n//\n// Deliberately NOT registered by default: an SDK that writes to the console unasked is noise (GWDNBM), so\n// `createLogger({ sinks: [consoleLogSink()] })` is an explicit opt-in.\n//\n// `console` is read inside `write` rather than captured at factory time, so a test that stubs\n// `console.warn` after construction still sees the stub, and importing this file asserts nothing about the\n// environment. Each level routes to its own method because devtools filters on exactly that — collapsing\n// everything onto `console.log` throws away the level filter the browser already gives you for free. Note\n// `console.trace` prints a stack alongside the message; that is what makes it the trace method, and why\n// `Trace` is off by default.\n//\n// Context and error are passed as separate arguments rather than interpolated into the message, so devtools\n// renders them as inspectable objects instead of `[object Object]`.\n\nimport { LogLevel } from './LogLevel';\nimport type { LogRecord } from './LogRecord';\nimport type { LogSink } from './LogSink';\n\n/** Defines the options for {@link consoleLogSink}. */\nexport interface ConsoleLogSinkOptions {\n  /** The tag prefixed to every message. Default `'[log]'`; pass `''` for no prefix. */\n  readonly prefix?: string;\n}\n\n/** Resolves the console method a level routes to. `Silent` never reaches a sink; it returns `undefined` to keep the switch exhaustive. */\nfunction resolveMethod(level: LogLevel): ((...args: unknown[]) => void) | undefined {\n  switch (level) {\n    case LogLevel.Trace:\n      return console.trace;\n    case LogLevel.Debug:\n      return console.debug;\n    case LogLevel.Info:\n      return console.info;\n    case LogLevel.Warn:\n      return console.warn;\n    case LogLevel.Error:\n      return console.error;\n    case LogLevel.Silent:\n      return undefined;\n  }\n}\n\n/** Creates a sink that writes each record to the matching `console` method — the development destination, opt-in like every other wire. */\nexport function consoleLogSink(options: ConsoleLogSinkOptions = {}): LogSink {\n  const prefix = options.prefix ?? '[log]';\n\n  return {\n    name: 'console',\n    write: (record: LogRecord): void => {\n      const method = resolveMethod(record.level) ?? console.log;\n      const args: unknown[] = [];\n      if (Object.keys(record.context).length > 0) args.push(record.context);\n      if (record.error !== undefined) args.push(record.error);\n\n      method.call(console, prefix === '' ? record.message : `${prefix} ${record.message}`, ...args);\n    },\n  };\n}\n","// The test double — a sink that ships nowhere and remembers everything.\n//\n// `records` surfaces through a getter typed `readonly`, so a test reads the live capture without being able\n// to push into it, and the array identity stays stable across a `reset` (mirrors `memoryAnalyticsProvider`).\n// Records are stored by reference, not copied: they are already frozen in shape and fully `readonly`, and a\n// copy would defeat the assertion that every sink in a fan-out received the SAME object.\n\nimport type { LogRecord } from './LogRecord';\nimport type { LogSink } from './LogSink';\n\n/** Defines the in-memory sink returned by {@link memoryLogSink} — a sink plus the capture it records. */\nexport interface MemoryLogSink extends LogSink {\n  /** Every record written, in emit order. */\n  readonly records: readonly LogRecord[];\n\n  /** Clears the capture — for a `beforeEach` reset of a shared instance. */\n  reset(): void;\n}\n\n/** Creates an in-memory sink capturing every record — the test double for asserting what an app logs. */\nexport function memoryLogSink(): MemoryLogSink {\n  const records: LogRecord[] = [];\n\n  return {\n    name: 'memory',\n\n    get records() {\n      return records;\n    },\n\n    write: (record) => {\n      records.push(record);\n    },\n\n    reset: () => {\n      records.length = 0;\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/media/CanCaptureMedia.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Why media capture is (un)available here.
+ *
+ * - `supported` — `navigator.mediaDevices.getUserMedia` is present and callable.
+ * - `insecure-context` — the API is absent *and* the page is known to be a non-secure context. Actionable:
+ *   serve over HTTPS (or `localhost`). Distinguished from `unsupported` because the fix is completely different.
+ * - `unsupported` — no API and no evidence the context is the reason: SSR, a worker, an older browser.
+ */
+export type MediaSupport = 'supported' | 'insecure-context' | 'unsupported';
+/**
+ * Reads `navigator.mediaDevices` when it exists and carries `member` as a callable.
+ *
+ * Two members are asked for separately because they fail separately: a browser can expose `enumerateDevices`
+ * (device *existence*, no permission needed) while `getUserMedia` is missing or blocked. Guarded end-to-end;
+ * returns `undefined` under SSR. Internal to the slice — used by the sibling modules, absent from the barrel.
+ *
+ * @param member The method the caller is about to invoke.
+ * @returns The `MediaDevices` object, or `undefined` when it or `member` is unusable.
+ */
+export declare function mediaDevicesWith(member: 'getUserMedia' | 'enumerateDevices'): MediaDevices | undefined;
+/**
+ * Reports whether media capture is available here, and when it is not, why.
+ *
+ * The `insecure-context` answer is the one worth rendering differently: it is the only reason a consumer can
+ * actually act on ("this page must be served over HTTPS"), where `unsupported` is terminal for that visit.
+ *
+ * Never throws. Returns `unsupported` under SSR.
+ */
+export declare function getMediaSupport(): MediaSupport;
+/**
+ * Reports whether `requestMediaStream` and friends can reach a real `getUserMedia`.
+ *
+ * The boolean form of {@link getMediaSupport} — for a plain "hide the camera button" check that does not care
+ * *why*. Never throws. Returns `false` under SSR.
+ */
+export declare function canCaptureMedia(): boolean;

package/dist/foundation/media/FacingMode.d.ts

@@ -0,0 +1,45 @@
+import { MediaStreamResult } from './MediaStreamResult';
+/**
+ * Which camera to prefer.
+ *
+ * - `user` — front / selfie camera, facing the user.
+ * - `environment` — rear camera, facing away. What a scanner or a document capture wants.
+ */
+export type FacingMode = 'user' | 'environment';
+/** Tunes how a facing-mode preference is expressed as constraints. */
+export interface FacingModeOptions {
+    /**
+     * Whether to demand the facing mode rather than prefer it. `true` emits `{ exact }`, which REJECTS with
+     * `OverconstrainedError` on any device lacking that camera — see the module header. Defaults to `false`
+     * (`{ ideal }`), which degrades to whatever camera exists.
+     */
+    readonly exact?: boolean;
+    /** Extra video track constraints to merge — resolution, frame rate, `deviceId`. A `facingMode` here is overwritten. */
+    readonly video?: MediaTrackConstraints;
+}
+/**
+ * Builds video track constraints expressing a facing-mode preference.
+ *
+ * Feed the result to {@link requestCameraStream}. Pure — no device access, nothing to fail, so it needs no
+ * result type and never throws.
+ *
+ * @param facingMode The camera to prefer.
+ * @param options Whether to demand rather than prefer it, plus any extra track constraints to merge.
+ * @returns The merged `MediaTrackConstraints`, with `facingMode` applied last.
+ */
+export declare function facingModeConstraints(facingMode: FacingMode, options?: FacingModeOptions): MediaTrackConstraints;
+/**
+ * Flips to the other camera: releases `current`, then acquires a stream for `facingMode`.
+ *
+ * Stops first, always — two camera streams must never be held at once (module header). `current` may be `null`,
+ * which makes this usable as the first acquisition too, so a flip button needs no special case for its initial
+ * press.
+ *
+ * Never throws, never rejects.
+ *
+ * @param current The stream to release. Pass `null` when nothing is live yet.
+ * @param facingMode The camera to switch to.
+ * @param options Whether to demand rather than prefer it, plus any extra track constraints.
+ * @returns The typed outcome of the new acquisition. Anything other than `granted` means nothing is live now.
+ */
+export declare function switchCamera(current: MediaStream | null | undefined, facingMode: FacingMode, options?: FacingModeOptions): Promise<MediaStreamResult>;

package/dist/foundation/media/ListMediaDevices.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Media input / output devices, grouped by kind.
+ *
+ * Labels are empty strings until capture permission has been granted at least once in this origin — see the
+ * module header. Group membership and counts are accurate regardless.
+ */
+export interface MediaDeviceGroups {
+    /** Whether `enumerateDevices` was reachable at all. `false` means every group is empty because the API is absent (SSR, older browser), not because the machine has no devices. */
+    readonly supported: boolean;
+    /** Video inputs — `kind === 'videoinput'`. Webcams, virtual cameras, capture cards. */
+    readonly cameras: readonly MediaDeviceInfo[];
+    /** Audio inputs — `kind === 'audioinput'`. Microphones, line-ins, virtual audio devices. */
+    readonly microphones: readonly MediaDeviceInfo[];
+    /** Audio outputs — `kind === 'audiooutput'`. Speakers and headsets. Absent entirely on Firefox, which does not enumerate outputs. */
+    readonly speakers: readonly MediaDeviceInfo[];
+}
+/**
+ * Lists the available media devices, grouped by kind.
+ *
+ * Call it AFTER a successful `requestCameraStream` / `requestMicrophoneStream` if the labels matter — a picker
+ * built on a pre-permission call renders blank rows (module header). Entries with an unrecognized `kind` are
+ * dropped rather than guessed at.
+ *
+ * Never throws, never rejects.
+ *
+ * @returns The grouped devices, with `supported: false` when the API is absent.
+ */
+export declare function listMediaDevices(): Promise<MediaDeviceGroups>;
+/**
+ * Reports whether this machine has at least one camera.
+ *
+ * Usable BEFORE prompting: counts are accurate without permission even though labels are not, which makes this
+ * the right gate for showing or hiding a "Take a photo" affordance. Never throws; `false` under SSR.
+ */
+export declare function hasCamera(): Promise<boolean>;
+/**
+ * Reports whether this machine has at least one microphone.
+ *
+ * Same pre-permission caveat as {@link hasCamera}. Never throws; `false` under SSR.
+ */
+export declare function hasMicrophone(): Promise<boolean>;

package/dist/foundation/media/MediaPermission.d.ts

@@ -0,0 +1,23 @@
+import { PermissionQueryState } from '../notifications';
+/**
+ * The state of a queried permission — re-exported from `foundation/notifications` so a consumer of this slice
+ * can name the return type without importing a second subpath.
+ */
+export type { PermissionQueryState };
+/**
+ * Reads the camera permission's current state without prompting.
+ *
+ * A hint, not a gate — see the module header. `unsupported` is the normal Firefox answer and means "cannot
+ * tell", never "blocked". Never throws, never rejects.
+ *
+ * @returns `granted` · `denied` · `prompt` · `unsupported`.
+ */
+export declare function getCameraPermission(): Promise<PermissionQueryState>;
+/**
+ * Reads the microphone permission's current state without prompting.
+ *
+ * Same caveats as {@link getCameraPermission}. Never throws, never rejects.
+ *
+ * @returns `granted` · `denied` · `prompt` · `unsupported`.
+ */
+export declare function getMicrophonePermission(): Promise<PermissionQueryState>;

package/dist/foundation/media/MediaStreamResult.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The outcome of a capture attempt. Six arms because a camera prompt has six meaningfully different endings,
+ * each wanting different UI copy and a different next step.
+ *
+ * - `granted` — the user allowed it; `stream` is live and the caller now OWNS it (see `stopMediaStream`).
+ * - `denied` — the user pressed Block, or a prior block is being replayed without a prompt. Not retryable
+ *   without a browser-settings change, so re-prompting on a timer only annoys.
+ * - `unavailable` — no device matches the request. A laptop with no webcam, or an unplugged USB mic.
+ * - `in-use` — the device exists but another application (or another tab) holds it. Retryable once freed.
+ * - `unsupported` — no API here at all: SSR, an insecure context, an older browser. See `getMediaSupport` for
+ *   which of those it is.
+ * - `failed` — anything else, carrying the normalized `Error`.
+ */
+export type MediaStreamResult = {
+    readonly status: 'granted';
+    readonly stream: MediaStream;
+} | {
+    readonly status: 'denied';
+} | {
+    readonly status: 'unavailable';
+} | {
+    readonly status: 'in-use';
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** The `status` discriminant of a {@link MediaStreamResult} — for a consumer's own switch or status→copy map. */
+export type MediaStreamStatus = MediaStreamResult['status'];
+/** Every {@link MediaStreamResult} arm except the successful one — what a rejected `getUserMedia` can become. */
+export type MediaStreamFailure = Exclude<MediaStreamResult, {
+    status: 'granted';
+}>;
+/**
+ * Classifies a rejected `getUserMedia` into its {@link MediaStreamFailure}.
+ *
+ * Exported for the sibling request modules and their tests; absent from the barrel, where the request functions
+ * are the surface a consumer wants. Never throws — an unrecognized name falls through to `failed` with the value
+ * normalized by `foundation/errors`' `toError`, so even a thrown `null` arrives as a real `Error`.
+ *
+ * @param cause The value `getUserMedia` rejected (or threw) with.
+ * @returns The matching failure arm.
+ */
+export declare function toMediaStreamFailure(cause: unknown): MediaStreamFailure;

package/dist/foundation/media/RequestMediaStream.d.ts

@@ -0,0 +1,37 @@
+import { MediaStreamResult } from './MediaStreamResult';
+/**
+ * Requests a stream for arbitrary constraints — the general form the camera / microphone helpers delegate to.
+ *
+ * Call it from a user gesture where possible: some engines require transient activation, and browsers rate-limit
+ * repeated prompts. A `granted` result transfers stream ownership to the caller.
+ *
+ * Never throws, never rejects.
+ *
+ * @param constraints The `MediaStreamConstraints` to pass through, e.g. `{ video: true, audio: true }`.
+ * @returns The typed outcome — `granted` carrying the live stream, or one of the five failure arms.
+ */
+export declare function requestMediaStream(constraints: MediaStreamConstraints): Promise<MediaStreamResult>;
+/**
+ * Requests a camera-only stream.
+ *
+ * Video only, deliberately: a "camera" request that also opened the microphone would widen the permission
+ * prompt (browsers name every device being asked for) and capture audio the caller never asked for. Pass
+ * `{ video: …, audio: true }` to {@link requestMediaStream} when both are genuinely wanted.
+ *
+ * Never throws, never rejects.
+ *
+ * @param constraints Track constraints for the video device — resolution, `deviceId`, `facingMode`. Omitted
+ *   means `video: true`: whichever camera the browser prefers.
+ * @returns The typed outcome.
+ */
+export declare function requestCameraStream(constraints?: MediaTrackConstraints): Promise<MediaStreamResult>;
+/**
+ * Requests a microphone-only stream.
+ *
+ * Never throws, never rejects.
+ *
+ * @param constraints Track constraints for the audio device — `deviceId`, `echoCancellation`, `noiseSuppression`.
+ *   Omitted means `audio: true`.
+ * @returns The typed outcome.
+ */
+export declare function requestMicrophoneStream(constraints?: MediaTrackConstraints): Promise<MediaStreamResult>;

package/dist/foundation/media/StopMediaStream.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stops every track on a stream, releasing the underlying camera / microphone.
+ *
+ * Idempotent and total: a `null` / `undefined` stream, an already-stopped stream, and an object that is not a
+ * stream at all are all no-ops. Never throws — it is called from cleanup paths (`finally`, a scope disposal)
+ * where a throw would mask the original failure or abort the rest of the teardown.
+ *
+ * @param stream The stream to release. Nullable so a caller can pass state without a guard of its own.
+ */
+export declare function stopMediaStream(stream: MediaStream | null | undefined): void;

package/dist/foundation/media/UseMediaStream.d.ts

@@ -0,0 +1,41 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { MediaStreamResult, MediaStreamStatus } from './MediaStreamResult';
+/**
+ * Where a `useMediaStream` instance sits in its cycle: `idle` before the first attempt and after `stop`,
+ * `pending` while the browser prompt is open, then the {@link MediaStreamStatus} of the last attempt.
+ */
+export type MediaStreamState = 'idle' | 'pending' | MediaStreamStatus;
+/** Tunes a `useMediaStream` instance. */
+export interface UseMediaStreamOptions {
+    /** Constraints for every `start()` that does not pass its own. Defaults to `{ video: true }` — camera, no microphone. */
+    readonly constraints?: MediaStreamConstraints;
+}
+/** What {@link useMediaStream} returns. */
+export interface MediaStreamControls {
+    /** The current state — drives the button label, the spinner, and the permission-denied copy. */
+    readonly status: Readonly<ShallowRef<MediaStreamState>>;
+    /** The live stream, or `null` whenever `status` is anything but `granted`. Assign to a `<video>`'s `srcObject`. */
+    readonly stream: Readonly<ShallowRef<MediaStream | null>>;
+    /** The normalized error from a `failed` attempt; `null` for every other status, including `denied`, which is a decision rather than a failure. */
+    readonly error: Readonly<ShallowRef<Error | null>>;
+    /** Acquires a stream, releasing any currently held one first. Resolves to the outcome; never throws. */
+    readonly start: (constraints?: MediaStreamConstraints) => Promise<MediaStreamResult>;
+    /** Releases the held stream and returns to `idle`. Idempotent, safe before the first `start`. */
+    readonly stop: () => void;
+}
+/**
+ * Acquires and owns a media stream, releasing it on `stop` and when the scope is disposed.
+ *
+ * ```vue
+ * const camera = useMediaStream();
+ * <video ref="videoEl" autoplay playsinline muted />
+ * <button @click="camera.start()">Start</button>
+ * // watchEffect(() => { if (videoEl.value) videoEl.value.srcObject = camera.stream.value; })
+ * ```
+ *
+ * Inherits the slice's never-throws contract — a rejected promise is not one of the outcomes.
+ *
+ * @param options Default constraints for `start()`. A ref or getter is read at call time.
+ * @returns The state machine plus the two lifecycle callbacks.
+ */
+export declare function useMediaStream(options?: MaybeRefOrGetter<UseMediaStreamOptions | undefined>): MediaStreamControls;

package/dist/foundation/media/index.d.ts

@@ -0,0 +1,8 @@
+export { canCaptureMedia, getMediaSupport, type MediaSupport } from './CanCaptureMedia';
+export { type MediaStreamResult, type MediaStreamStatus, type MediaStreamFailure } from './MediaStreamResult';
+export { requestMediaStream, requestCameraStream, requestMicrophoneStream } from './RequestMediaStream';
+export { listMediaDevices, hasCamera, hasMicrophone, type MediaDeviceGroups } from './ListMediaDevices';
+export { stopMediaStream } from './StopMediaStream';
+export { facingModeConstraints, switchCamera, type FacingMode, type FacingModeOptions } from './FacingMode';
+export { getCameraPermission, getMicrophonePermission, type PermissionQueryState } from './MediaPermission';
+export { useMediaStream, type MediaStreamControls, type MediaStreamState, type UseMediaStreamOptions, } from './UseMediaStream';