add loading progress support and new indicator

src/torqueScript/index.ts

@@ -7,6 +7,7 @@ import { TorqueObject, TorqueRuntime, TorqueRuntimeOptions } from "./types";
 export { generate, type GeneratorOptions } from "./codegen";
 export type { Program } from "./ast";
 export { createBuiltins } from "./builtins";
+export { createProgressTracker, type ProgressTracker } from "./progress";
 export { createRuntime, createScriptCache } from "./runtime";
 export { normalizePath } from "./utils";
 export type {

src/torqueScript/progress.ts

@@ -0,0 +1,75 @@
+export type ProgressEventType = "update";
+export type ProgressListener = () => void;
+
+export interface ProgressTracker {
+  /** Total items discovered so far (increases as dependencies are found) */
+  readonly total: number;
+  /** Items completed */
+  readonly loaded: number;
+  /** Currently loading item path, if any */
+  readonly current: string | null;
+  /** Progress as a ratio from 0 to 1 (or 0 if total is 0) */
+  readonly progress: number;
+  /** Subscribe to progress updates */
+  on(event: ProgressEventType, listener: ProgressListener): void;
+  /** Unsubscribe from progress updates */
+  off(event: ProgressEventType, listener: ProgressListener): void;
+}
+
+export interface ProgressTrackerInternal extends ProgressTracker {
+  /** Increment total count when a new item is discovered */
+  addItem(path: string): void;
+  /** Mark an item as completed */
+  completeItem(): void;
+  /** Set the currently loading item */
+  setCurrent(path: string | null): void;
+}
+
+export function createProgressTracker(): ProgressTrackerInternal {
+  const listeners = new Set<ProgressListener>();
+
+  let total = 0;
+  let loaded = 0;
+  let current: string | null = null;
+
+  function notify(): void {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  return {
+    get total() {
+      return total;
+    },
+    get loaded() {
+      return loaded;
+    },
+    get current() {
+      return current;
+    },
+    get progress() {
+      return total === 0 ? 0 : loaded / total;
+    },
+    on(_event: ProgressEventType, listener: ProgressListener) {
+      listeners.add(listener);
+    },
+    off(_event: ProgressEventType, listener: ProgressListener) {
+      listeners.delete(listener);
+    },
+    addItem(path: string) {
+      total++;
+      current = path;
+      notify();
+    },
+    completeItem() {
+      loaded++;
+      current = null;
+      notify();
+    },
+    setCurrent(path: string | null) {
+      current = path;
+      notify();
+    },
+  };
+}

src/torqueScript/runtime.ts

@@ -1121,12 +1121,16 @@ export function createRuntime(
         return;
       }
 
+      // Track this script in progress
+      options.progress?.addItem(ref);
+
       const loadPromise = (async () => {
         // Pass original path to loader - it handles its own normalization
         const source = await loader(ref);
         if (source == null) {
           console.warn(`Script not found: ${ref}`);
           state.failedScripts.add(normalized);
+          options.progress?.completeItem();
           return;
         }
 
@@ -1136,6 +1140,7 @@ export function createRuntime(
         } catch (err) {
           console.warn(`Failed to parse script: ${ref}`, err);
           state.failedScripts.add(normalized);
+          options.progress?.completeItem();
           return;
         }
 
@@ -1152,6 +1157,7 @@ export function createRuntime(
 
         // Store the parsed AST
         state.scripts.set(normalized, depAst);
+        options.progress?.completeItem();
       })();
 
       loadingPromises.set(normalized, loadPromise);
@@ -1173,13 +1179,19 @@ export function createRuntime(
       return createLoadedScript(state.scripts.get(normalized)!, path);
     }
 
+    // Track this script in progress
+    options.progress?.addItem(path);
+
     // Pass original path to loader - it handles its own normalization
     const source = await loader(path);
     if (source == null) {
+      options.progress?.completeItem();
       throw new Error(`Script not found: ${path}`);
     }
 
-    return loadFromSource(source, { path });
+    const result = await loadFromSource(source, { path });
+    options.progress?.completeItem();
+    return result;
   }
 
   async function loadFromSource(

src/torqueScript/types.ts

@@ -1,4 +1,5 @@
 import type { Program } from "./ast";
+import type { ProgressTrackerInternal } from "./progress";
 import type { CaseInsensitiveMap } from "./utils";
 
 export type TorqueFunction = (...args: any[]) => any;
@@ -108,6 +109,12 @@ export interface TorqueRuntimeOptions {
    * Create with `createScriptCache()`.
    */
   cache?: ScriptCache;
+  /**
+   * Progress tracker for monitoring script loading. If provided, the runtime
+   * will report loading progress as scripts are discovered and loaded.
+   * Create with `createProgressTracker()`.
+   */
+  progress?: ProgressTrackerInternal;
 }
 
 export interface LoadScriptOptions {