From fb7ade04494d8a94dd08b2edd1b8d461e7867d07 Mon Sep 17 00:00:00 2001
From: RMO <rmo@black.com>
Date: Thu, 28 Aug 2025 03:42:01 -0600
Subject: [PATCH] docs: add logging helpers

---
 .../app/studio/src/errors/ErrorHandler.ts     |  3 ++
 packages/app/studio/src/errors/ErrorInfo.ts   |  4 +++
 packages/app/studio/src/errors/ErrorLog.ts    |  7 ++++-
 packages/app/studio/src/errors/LogBuffer.ts   |  6 ++++
 .../app/studio/src/service/SyncLogService.ts  |  6 ++++
 packages/docs/docs-dev/debugging/logging.md   | 30 +++++++++++++++++++
 packages/docs/docs-dev/debugging/overview.md  |  1 +
 packages/docs/docs-user/troubleshooting.md    |  6 ++++
 packages/lib/runtime/src/stopwatch.ts         |  1 +
 packages/lib/runtime/src/timespan.ts          |  1 +
 packages/lib/std/src/warning.ts               |  6 ++++
 .../studio/core/src/sync-log/SyncLogWriter.ts | 13 +++++++-
 12 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 packages/docs/docs-dev/debugging/logging.md

diff --git a/packages/app/studio/src/errors/ErrorHandler.ts b/packages/app/studio/src/errors/ErrorHandler.ts
index d8d3aaabf..02f9cae1f 100644
--- a/packages/app/studio/src/errors/ErrorHandler.ts
+++ b/packages/app/studio/src/errors/ErrorHandler.ts
@@ -16,9 +16,11 @@ import { showErrorDialog, showInfoDialog } from "@/ui/components/dialogs.tsx";
  * facing dialog.
  */
 export class ErrorHandler {
+  /** Collects listeners that need to be disposed when the handler stops. */
   readonly terminator = new Terminator();
   readonly #service: StudioService;
 
+  /** Guard to avoid infinite error loops once an error has been processed. */
   #errorThrown: boolean = false;
 
   constructor(service: StudioService) {
@@ -87,6 +89,7 @@ export class ErrorHandler {
    *
    * @param owner - Window or worker to attach listeners to.
    * @param scope - Descriptive name of the owner for reporting.
+   * @returns Terminable that removes the listeners.
    */
   install(
     owner: WindowProxy | Worker | AudioWorkletNode,
diff --git a/packages/app/studio/src/errors/ErrorInfo.ts b/packages/app/studio/src/errors/ErrorInfo.ts
index 9cdcdaf09..677b14319 100644
--- a/packages/app/studio/src/errors/ErrorInfo.ts
+++ b/packages/app/studio/src/errors/ErrorInfo.ts
@@ -5,8 +5,11 @@ import { isDefined } from "@opendaw/lib-std";
 
 /** Normalized representation of diverse error events. */
 export type ErrorInfo = {
+  /** Name of the error type. */
   name: string;
+  /** Optional human-readable error message. */
   message?: string;
+  /** Raw stack trace if available. */
   stack?: string;
 };
 
@@ -28,6 +31,7 @@ export namespace ErrorInfo {
       if (reason instanceof Error) {
         if (!isDefined(reason.stack)) {
           try {
+            // Re-throwing captures a stack when one isn't present.
             // noinspection ExceptionCaughtLocallyJS
             throw reason;
           } catch (error) {
diff --git a/packages/app/studio/src/errors/ErrorLog.ts b/packages/app/studio/src/errors/ErrorLog.ts
index 7243d04af..762332c4b 100644
--- a/packages/app/studio/src/errors/ErrorLog.ts
+++ b/packages/app/studio/src/errors/ErrorLog.ts
@@ -14,7 +14,12 @@ export type ErrorLog = {
   agent: string;
   /** Build information for the running application. */
   build: BuildInfo;
-  /** Number of script tags present on the page. */
+  /**
+   * Number of `<script>` elements on the current page.
+   *
+   * A higher count than expected can hint at browser extensions
+   * injecting code and causing interference.
+   */
   scripts: int;
   /** Normalized error information. */
   error: ErrorInfo;
diff --git a/packages/app/studio/src/errors/LogBuffer.ts b/packages/app/studio/src/errors/LogBuffer.ts
index e6796a4c7..c03100c21 100644
--- a/packages/app/studio/src/errors/LogBuffer.ts
+++ b/packages/app/studio/src/errors/LogBuffer.ts
@@ -10,14 +10,19 @@ import { int } from "@opendaw/lib-std";
 export namespace LogBuffer {
   /** Single console log entry preserved for debugging. */
   export type Entry = {
+    /** Timestamp in milliseconds since epoch when the log was recorded. */
     time: number;
+    /** Console severity level for the entry. */
     level: "debug" | "info" | "warn";
+    /** Arguments forwarded to the original console method. */
     args: Array<string>;
   };
 
   const logBuffer: Entry[] = [];
 
   if (import.meta.env.PROD) {
+    // Upper bound for the number of argument strings stored to avoid
+    // unbounded memory usage in long running sessions.
     let estimatedSize: int = 0;
     const MAX_ARGS_SIZE = 100_000;
     const pushLog = (level: Entry["level"], args: unknown[]) => {
@@ -69,6 +74,7 @@ export namespace LogBuffer {
         // Last resort fallback
         return Object.prototype.toString.call(value);
       } catch {
+        // Catch and mark values that throw during conversion.
         return "[unserializable]";
       }
     };
diff --git a/packages/app/studio/src/service/SyncLogService.ts b/packages/app/studio/src/service/SyncLogService.ts
index 88d760da0..cbe12159d 100644
--- a/packages/app/studio/src/service/SyncLogService.ts
+++ b/packages/app/studio/src/service/SyncLogService.ts
@@ -36,6 +36,7 @@ export namespace SyncLogService {
         const label: FooterLabel = asDefined(service.factoryFooterLabel().unwrap()())
         label.setTitle("SyncLog")
         let count = 0 | 0
+        // Attach a writer that updates the footer after each commit is flushed.
         SyncLogWriter.attach(service.project, wrapBlockWriter(handle, () => label.setValue(`${++count} commits`)))
     }
 
@@ -69,6 +70,7 @@ export namespace SyncLogService {
             console.warn("arrayBuffer", arrayBufferResult.error)
             return
         }
+        // Deserialize the existing log to restore the project and seek the last commit.
         const {project, lastCommit, numCommits} = await SyncLogReader.unwrap(service, arrayBufferResult.value)
         service.fromProject(project, "SyncLog")
         const label: FooterLabel = asDefined(service.factoryFooterLabel().unwrap()())
@@ -85,6 +87,8 @@ export namespace SyncLogService {
      * @returns Observer function passed to {@link SyncLogWriter.attach}.
      */
     const wrapBlockWriter = (handle: FileSystemFileHandle, callback: Exec) => {
+        // Queue of commits waiting to be written to disk. The promise chain
+        // ensures commits are flushed sequentially in order.
         let blocks: Array<Commit> = []
         let lastPromise: Promise<void> = Promise.resolve()
         return (commit: Commit): void => {
@@ -93,6 +97,7 @@ export namespace SyncLogService {
             lastPromise = lastPromise.then(async () => {
                 const writable: FileSystemWritableFileStream = await handle.createWritable({keepExistingData: true})
                 const file = await handle.getFile()
+                // Append to the end of the existing file without truncating it.
                 await writable.seek(file.size)
                 const buffers = blocks.map(block => block.serialize())
                 blocks = []
@@ -111,6 +116,7 @@ export namespace SyncLogService {
     const appendArrayBuffers = (buffers: ReadonlyArray<ArrayBuffer>): ArrayBuffer => {
         const totalLength = buffers.reduce((sum, buffer) => sum + buffer.byteLength, 0)
         const result = new Uint8Array(totalLength)
+        // Copy buffers one after another into the result view.
         buffers.reduce((offset, buffer) => {
             result.set(new Uint8Array(buffer), offset)
             return offset + buffer.byteLength
diff --git a/packages/docs/docs-dev/debugging/logging.md b/packages/docs/docs-dev/debugging/logging.md
new file mode 100644
index 000000000..2566aaa4a
--- /dev/null
+++ b/packages/docs/docs-dev/debugging/logging.md
@@ -0,0 +1,30 @@
+# Logging
+
+openDAW provides several lightweight helpers for collecting diagnostic
+information while developing or running the Studio.
+
+## Console capture
+
+The [`LogBuffer`](/dev/debugging/error-logging#logbuffer) monkey patches the
+browser's console methods in production builds and keeps a bounded history of
+recent messages. When an error is reported the buffer is included in the
+payload so that the server receives context for the failure.
+
+## Sync logs
+
+Project changes can be serialized using the `SyncLogWriter` and related
+utilities. The `SyncLogService` integrates these pieces into the Studio and can
+start a new log or append to an existing file. This stream of commits is useful
+for reproducing complex editing sessions.
+
+## Timing helpers
+
+For ad-hoc instrumentation the `stopwatch` function prints labelled laps to the
+console, while `TimeSpanUtils.startEstimator` returns a function that projects
+the remaining time of a process based on its progress.
+
+## Warnings
+
+The `warn` helper throws a dedicated `Warning` error type. The global
+`ErrorHandler` treats these differently from fatal exceptions and displays an
+informational dialog to the user.
diff --git a/packages/docs/docs-dev/debugging/overview.md b/packages/docs/docs-dev/debugging/overview.md
index 58c701e9e..e02c464ba 100644
--- a/packages/docs/docs-dev/debugging/overview.md
+++ b/packages/docs/docs-dev/debugging/overview.md
@@ -3,4 +3,5 @@
 openDAW provides a set of utilities to help developers diagnose problems during development and in production.
 
 - [Error logging](error-logging.md) describes how runtime issues are captured and reported.
+- [Logging helpers](logging.md) covers general purpose utilities such as `LogBuffer` and `stopwatch`.
 - [Graph runtime](graph-runtime.md) explains the interactive graph view used to inspect box connections.
diff --git a/packages/docs/docs-user/troubleshooting.md b/packages/docs/docs-user/troubleshooting.md
index c8392074c..d9d360691 100644
--- a/packages/docs/docs-user/troubleshooting.md
+++ b/packages/docs/docs-user/troubleshooting.md
@@ -59,6 +59,12 @@
 - Developers looking to diagnose issues in depth can consult the
   [debugging guide](/dev/debugging/overview).
 
+### How do I collect logs for support?
+
+- The Studio automatically captures recent console output and sends it along
+  with error reports. You can also export a project `SyncLog` from the footer
+  menu to share a history of your edits.
+
 ### App stuck on loading screen
 
 - Check your internet connection and reload the page.
diff --git a/packages/lib/runtime/src/stopwatch.ts b/packages/lib/runtime/src/stopwatch.ts
index 7f88047b8..177d72d67 100644
--- a/packages/lib/runtime/src/stopwatch.ts
+++ b/packages/lib/runtime/src/stopwatch.ts
@@ -31,6 +31,7 @@ interface Stopwatch {
  * @returns A stopwatch instance.
  */
 export const stopwatch = (level: "debug" | "info" = "debug"): Stopwatch => {
+    // Capture the start time once; each lap uses the delta to this point.
     const startTime = performance.now()
     return {
         lab: (label: string) =>
diff --git a/packages/lib/runtime/src/timespan.ts b/packages/lib/runtime/src/timespan.ts
index ddb93aaeb..53a9c5af3 100644
--- a/packages/lib/runtime/src/timespan.ts
+++ b/packages/lib/runtime/src/timespan.ts
@@ -27,6 +27,7 @@ export namespace TimeSpanUtils {
     export const startEstimator = (): Func<number, TimeSpan> => {
         const startTime: number = performance.now()
         return (progress: unitValue): TimeSpan => {
+            // Avoid division by zero when no progress has been reported yet.
             if (progress === 0.0) {return TimeSpan.POSITIVE_INFINITY}
             const runtime = performance.now() - startTime
             return TimeSpan.millis(runtime / progress - runtime)
diff --git a/packages/lib/std/src/warning.ts b/packages/lib/std/src/warning.ts
index 7d0fa6f07..e03687801 100644
--- a/packages/lib/std/src/warning.ts
+++ b/packages/lib/std/src/warning.ts
@@ -3,6 +3,12 @@
  */
 export class Warning extends Error {}
 
+/**
+ * Throws a {@link Warning} with the given message.
+ *
+ * This utility allows signalling non-fatal issues that should surface to the
+ * user but are handled differently from regular errors.
+ */
 export const warn = (issue: string): never => {
   throw new Warning(issue);
 };
diff --git a/packages/studio/core/src/sync-log/SyncLogWriter.ts b/packages/studio/core/src/sync-log/SyncLogWriter.ts
index 8fe0d0a14..fc0c8a029 100644
--- a/packages/studio/core/src/sync-log/SyncLogWriter.ts
+++ b/packages/studio/core/src/sync-log/SyncLogWriter.ts
@@ -22,7 +22,12 @@ export class SyncLogWriter implements Terminable {
     readonly #observer: Observer<Commit>
     readonly #subscription: Subscription
 
+    /**
+     * Subscription that stays active during a box-graph transaction to collect
+     * updates. Reset after each commit.
+     */
     #transactionSubscription: Subscription = Terminable.Empty
+    /** Promise chain used to serialize commit writing. */
     #lastPromise: Promise<Commit>
 
     private constructor(project: Project, observer: Observer<Commit>, lastCommit?: Commit) {
@@ -42,7 +47,12 @@ export class SyncLogWriter implements Terminable {
         this.#subscription.terminate()
     }
 
-    /** Queue a commit factory to run after the previous commit has been written. */
+    /**
+     * Queue a commit factory to run after the previous commit has finished.
+     *
+     * This ensures that commits are written in order even when asynchronous
+     * operations are involved.
+     */
     #appendCommit(factory: Func<Commit, Promise<Commit>>): Promise<Commit> {
         return this.#lastPromise = this.#lastPromise.then(async (previous) => {
             const commit = await factory(previous)
@@ -53,6 +63,7 @@ export class SyncLogWriter implements Terminable {
 
     /** Listen to box graph transactions and create update commits. */
     #listen(boxGraph: BoxGraph): Subscription {
+        // Collected updates for the current transaction.
         let updates: Array<Update> = []
         return boxGraph.subscribeTransaction({
             onBeginTransaction: () =>