@anthodev/pi-tools-style 0.1.3 → 0.2.0

package/src/tool-spinner.ts

@@ -1,111 +1,94 @@
 import type { IconMode } from "./tool-icon.js";
 
-interface SpinnerUi {
-  requestRender?: () => void;
+/** A public render-context state and its invalidation, never a Pi component. */
+export interface ToolSpinnerTarget {
+	state: object;
+	invalidate: () => void;
 }
-
-interface ToolSpinnerTarget {
-  executionStarted?: unknown;
-  isPartial?: unknown;
-  ui?: SpinnerUi;
-}
-
 interface SpinnerRuntime {
-  frameIndex: number;
-  targets: Map<object, number>;
-  timer: NodeJS.Timeout | undefined;
+	frameIndex: number;
+	targets: Set<WeakRef<ToolSpinnerTarget>>;
+	references: WeakMap<object, WeakRef<ToolSpinnerTarget>>;
+	timer: NodeJS.Timeout | undefined;
 }
-
 const SPINNER_RUNTIME_KEY = Symbol.for("pi-tools-style:tool-spinner");
 const FRAME_INTERVAL_MS = 80;
-const STALE_TARGET_MS = 2_000;
 const ASCII_FRAMES = ["|", "/", "-", "\\"] as const;
 const NERD_FONT_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 
-export function toolSpinnerFrame(
-  target: object,
-  mode: IconMode,
-): string | undefined {
-  const runtime = getRuntime();
-  if (!isExecuting(target)) {
-    runtime.targets.delete(target);
-    stopTickerIfIdle(runtime);
-    return undefined;
-  }
-
-  runtime.targets.set(target, Date.now());
-  ensureTicker(runtime);
-  const frames = mode === "nerd-font" ? NERD_FONT_FRAMES : ASCII_FRAMES;
-  return frames[runtime.frameIndex % frames.length];
-}
-
-export function clearToolSpinners(): void {
-  const runtime = getRuntime();
-  if (runtime.timer) clearInterval(runtime.timer);
-  runtime.timer = undefined;
-  runtime.frameIndex = 0;
-  runtime.targets.clear();
+/** Public tools use their gated ticker; shell may supply its native-loader clock index. */
+export function getToolSpinnerFrame(mode: IconMode, frameIndex = getRuntime().frameIndex): string {
+	const frames = mode === "nerd-font" ? NERD_FONT_FRAMES : ASCII_FRAMES;
+	return frames[frameIndex % frames.length]!;
 }
 
-function ensureTicker(runtime: SpinnerRuntime): void {
-  if (runtime.timer) return;
-
-  runtime.timer = setInterval(() => tick(runtime), FRAME_INTERVAL_MS);
-  runtime.timer.unref?.();
+/** Unconfirmed replay/export states use a static initial frame. */
+export function toolSpinnerFrame(state: object, mode: IconMode): string {
+	const current = getRuntime();
+	const ref = current.references.get(state);
+	if (ref && current.targets.has(ref) && ref.deref()) return getToolSpinnerFrame(mode);
+	return mode === "nerd-font" ? NERD_FONT_FRAMES[0] : ASCII_FRAMES[0];
 }
 
-function tick(runtime: SpinnerRuntime): void {
-  runtime.frameIndex += 1;
-  const now = Date.now();
-  const activeUis = new Set<SpinnerUi>();
-
-  for (const [target, lastSeenAt] of runtime.targets) {
-    if (!isExecuting(target) || now - lastSeenAt > STALE_TARGET_MS) {
-      runtime.targets.delete(target);
-      continue;
-    }
-    const ui = readTarget(target).ui;
-    if (ui) activeUis.add(ui);
-  }
-
-  for (const ui of activeUis) {
-    try {
-      ui.requestRender?.();
-    } catch {
-      // Presentation failure must never affect tool execution.
-    }
-  }
-
-  stopTickerIfIdle(runtime);
+export function setToolSpinnerActive(target: ToolSpinnerTarget, active: boolean): void {
+	const current = getRuntime();
+	let ref = current.references.get(target.state);
+	if (!active) {
+		if (ref?.deref() === target) {
+			current.targets.delete(ref);
+			current.references.delete(target.state);
+		}
+		stopTickerIfIdle(current);
+		return;
+	}
+	if (!ref || ref.deref() !== target) {
+		if (ref) current.targets.delete(ref);
+		ref = new WeakRef(target);
+		current.references.set(target.state, ref);
+	}
+	current.targets.add(ref);
+	if (!current.timer) {
+		current.timer = setInterval(() => tick(current), FRAME_INTERVAL_MS);
+		current.timer.unref?.();
+	}
 }
 
-function stopTickerIfIdle(runtime: SpinnerRuntime): void {
-  if (runtime.targets.size > 0 || !runtime.timer) return;
-  clearInterval(runtime.timer);
-  runtime.timer = undefined;
-  runtime.frameIndex = 0;
+export function clearToolSpinners(): void {
+	const current = getRuntime();
+	clearInterval(current.timer);
+	current.timer = undefined;
+	current.frameIndex = 0;
+	current.targets.clear();
+	current.references = new WeakMap();
 }
 
-function isExecuting(target: object): boolean {
-  const fields = readTarget(target);
-  return fields.executionStarted === true && fields.isPartial === true;
+function tick(current: SpinnerRuntime): void {
+	current.frameIndex++;
+	for (const ref of current.targets) {
+		const target = ref.deref();
+		if (!target) { current.targets.delete(ref); continue; }
+		try {
+			target.invalidate();
+		} catch {
+			// Detached TUI contexts cannot keep a presentation ticker alive.
+			current.targets.delete(ref);
+			if (current.references.get(target.state) === ref) current.references.delete(target.state);
+		}
+	}
+	stopTickerIfIdle(current);
 }
-
-function readTarget(target: object): ToolSpinnerTarget {
-  return target as ToolSpinnerTarget;
+function stopTickerIfIdle(current: SpinnerRuntime): void {
+	if (current.targets.size > 0 || !current.timer) return;
+	clearInterval(current.timer);
+	current.timer = undefined;
+	current.frameIndex = 0;
 }
-
 function getRuntime(): SpinnerRuntime {
-  const current = Reflect.get(globalThis, SPINNER_RUNTIME_KEY) as
-    | SpinnerRuntime
-    | undefined;
-  if (current) return current;
-
-  const runtime: SpinnerRuntime = {
-    frameIndex: 0,
-    targets: new Map(),
-    timer: undefined,
-  };
-  Reflect.set(globalThis, SPINNER_RUNTIME_KEY, runtime);
-  return runtime;
+	const current = Reflect.get(globalThis, SPINNER_RUNTIME_KEY) as SpinnerRuntime | undefined;
+	if (current?.targets instanceof Set) return current;
+	// Reload replaces the old private-component ticker, not a second clock.
+	clearInterval(current?.timer);
+	const next: SpinnerRuntime = { frameIndex: 0, targets: new Set(), references: new WeakMap(), timer: undefined };
+	Reflect.set(globalThis, SPINNER_RUNTIME_KEY, next);
+	return next;
 }