pi-one-ui 0.1.1 → 0.2.0

package/extensions/{shell → services}/live-context.ts

@@ -1,5 +1,5 @@
 import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
-import type { SessionLifecycle } from "./session-lifecycle.ts";
+import type { SessionLifecycle } from "../app/runtime/session-lifecycle.ts";
 
 export type LiveContextOverride = {
   tokens: number;
@@ -49,10 +49,35 @@ export class LiveContextController {
     this.requestRender = requestRender;
   }
 
+  /**
+   * Starts a new live-context session and clears predecessor data.
+   */
+  startSession(): void {
+    this.clear();
+  }
+
+  /**
+   * Shuts down live-context updates and clears pending redraw state.
+   */
+  shutdown(): void {
+    this.clear();
+  }
+
+  /**
+   * Returns the latest valid streaming context override.
+   *
+   * @returns Current live context override, when available.
+   */
   get(): LiveContextOverride | undefined {
     return this.override;
   }
 
+  /**
+   * Records a valid assistant usage update and schedules a throttled redraw.
+   *
+   * @param message Latest assistant message snapshot.
+   * @returns Whether the update produced a live context override.
+   */
   update(message: unknown): boolean {
     const next = liveContextFromMessage(message);
     if (!next || !this.lifecycle.isCurrent()) return false;
@@ -73,6 +98,9 @@ export class LiveContextController {
     return true;
   }
 
+  /**
+   * Clears the current override and cancels its pending redraw.
+   */
   clear(): void {
     this.override = undefined;
     this.cancelScheduledRender?.();

package/extensions/services/project-refresh.ts

@@ -0,0 +1,374 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionLifecycle } from "../app/runtime/session-lifecycle.ts";
+import { readGitStatus } from "./git-data.ts";
+import type { FooterState } from "./session-state.ts";
+import { applyProjectRefreshToState } from "./project-state.ts";
+import { readPackageVersionResult } from "./package-data.ts";
+import { readRuntimeInfo } from "./runtime-data.ts";
+
+export type StopProjectRefreshInterval = () => void;
+
+export type ScheduleProjectRefreshOptions = {
+  force?: boolean;
+};
+
+export type ProjectRefreshRun = {
+  isCurrent: () => boolean;
+};
+
+export type ProjectRefreshScheduler<T> = {
+  schedule: (target: T, options?: ScheduleProjectRefreshOptions) => void;
+  invalidate: () => void;
+  stop: () => void;
+};
+
+export const PROJECT_REFRESH_THROTTLE_MS = 5_000;
+
+export type ProjectRefreshActivationOptions = {
+  needed: boolean;
+  intervalMs: number;
+  onTick: () => void;
+};
+
+/**
+ * Owns the optional wall-clock interval used by project refresh consumers.
+ */
+export class ProjectRefreshActivation {
+  private stopInterval: StopProjectRefreshInterval = () => {};
+  private active = false;
+
+  /**
+   * Reconciles interval ownership with the current consumer requirements.
+   *
+   * @param options Current requirement, interval, and refresh callback.
+   * @returns Whether the interval was newly activated.
+   */
+  reconcile(options: ProjectRefreshActivationOptions): boolean {
+    if (!options.needed) {
+      this.stop();
+      return false;
+    }
+    if (this.active) return false;
+    this.stopInterval = startProjectRefreshInterval(
+      options.intervalMs,
+      options.onTick,
+    );
+    this.active = true;
+    return true;
+  }
+
+  /**
+   * Stops the active interval and clears its ownership state.
+   */
+  stop(): void {
+    this.stopInterval();
+    this.stopInterval = () => {};
+    this.active = false;
+  }
+}
+
+export type ProjectRefreshConfig = {
+  projectRefreshIntervalMs: number;
+  components: {
+    footer: {
+      styles: {
+        starship: {
+          gitCommit: { showTag: boolean };
+          gitMetrics: { ignoreSubmodules: boolean };
+        };
+      };
+    };
+  };
+};
+
+export type ProjectRefreshServiceContext = {
+  readonly getConfig: () => ProjectRefreshConfig;
+  readonly state: FooterState;
+  readonly sessionLifecycle: SessionLifecycle;
+  readonly getFooterReferences: () => ReadonlySet<string>;
+  readonly needsRefresh: () => boolean;
+  readonly reconcileOwnership: (ctx: ExtensionContext) => void;
+  readonly onProjectRoot: (root: string | undefined) => void;
+  readonly refresh: () => void;
+};
+
+type ProjectRefreshTarget = { cwd: string; generation: number };
+
+/**
+ * Coordinates project data reads and interval activation for Footer and Editor.
+ */
+export class ProjectRefreshService {
+  private readonly context: ProjectRefreshServiceContext;
+  private readonly scheduler: ProjectRefreshScheduler<ProjectRefreshTarget>;
+  private readonly activation = new ProjectRefreshActivation();
+  private lastProjectCwd: string | undefined;
+  private requestedProjectCwd: string | undefined;
+
+  /**
+   * Creates a generation-aware project refresh service.
+   *
+   * @param context Shared state and layout-neutral selectors.
+   */
+  constructor(context: ProjectRefreshServiceContext) {
+    this.context = context;
+    this.scheduler = createProjectRefreshScheduler(
+      (target, run) => this.refreshProjectState(target, run),
+      context.refresh,
+    );
+  }
+
+  /**
+   * Schedules an immediate or throttled project refresh for a session context.
+   *
+   * @param ctx Active Pi extension context.
+   * @param options Refresh priority options.
+   */
+  schedule(
+    ctx: ExtensionContext,
+    options?: ScheduleProjectRefreshOptions,
+  ): void {
+    const generation = this.context.sessionLifecycle.currentGeneration();
+    if (!this.context.sessionLifecycle.isCurrent(generation)) return;
+    this.requestedProjectCwd = ctx.cwd;
+    this.scheduler.schedule({ cwd: ctx.cwd, generation }, options);
+  }
+
+  /**
+   * Reconciles polling ownership with the active Footer or Editor consumers.
+   *
+   * @param ctx Active Pi extension context.
+   * @param force Whether to invalidate an active in-flight schedule.
+   */
+  reconcile(ctx: ExtensionContext, force = false): void {
+    if (
+      !this.context.sessionLifecycle.isCurrent() ||
+      !this.context.needsRefresh()
+    ) {
+      this.stop();
+      return;
+    }
+    const activated = this.activation.reconcile({
+      needed: true,
+      intervalMs: this.context.getConfig().projectRefreshIntervalMs,
+      onTick: () => {
+        this.context.reconcileOwnership(ctx);
+        if (!this.context.needsRefresh()) this.stop();
+        else this.schedule(ctx);
+      },
+    });
+    if (force && !activated) this.scheduler.invalidate();
+    if (force || activated) this.schedule(ctx, { force: true });
+  }
+
+  /**
+   * Stops polling and invalidates all pending project refresh callbacks.
+   */
+  stop(): void {
+    this.activation.stop();
+    this.scheduler.stop();
+  }
+
+  /**
+   * Refreshes Git, runtime, package, and repository-root data safely.
+   *
+   * @param target Session cwd and generation target.
+   * @param run Scheduler freshness guard.
+   */
+  private async refreshProjectState(
+    { cwd, generation }: ProjectRefreshTarget,
+    run: ProjectRefreshRun,
+  ): Promise<void> {
+    if (
+      !run.isCurrent() ||
+      !this.context.sessionLifecycle.isCurrent(generation)
+    )
+      return;
+    const starship = this.context.getConfig().components.footer.styles.starship;
+    const references = this.context.getFooterReferences();
+    const wantExactTag =
+      (references.has("git_commit") && starship.gitCommit.showTag) ||
+      references.has("git_tag");
+    const wantMetrics =
+      references.has("git_metrics") ||
+      references.has("git_added") ||
+      references.has("git_deleted");
+    const wantPackage =
+      references.has("package") || references.has("package_version");
+    const wantRuntime = references.has("runtime");
+    const [git, runtime, packageVersion] = await Promise.all([
+      readGitStatus(cwd, {
+        readExactTag: wantExactTag,
+        readMetrics: wantMetrics,
+        ignoreSubmodules: starship.gitMetrics.ignoreSubmodules,
+      }),
+      wantRuntime
+        ? readRuntimeInfo(cwd)
+        : Promise.resolve({ kind: "ok" as const, runtime: undefined }),
+      wantPackage
+        ? readPackageVersionResult(cwd)
+        : Promise.resolve({ kind: "ok" as const, result: null }),
+    ]);
+    if (
+      !run.isCurrent() ||
+      !this.context.sessionLifecycle.isCurrent(generation) ||
+      this.requestedProjectCwd !== cwd
+    )
+      return;
+    this.context.onProjectRoot(
+      git.kind === "ok" ? findRepositoryRoot(cwd) : undefined,
+    );
+    this.lastProjectCwd = applyProjectRefreshToState(this.context.state, {
+      cwd,
+      previousCwd: this.lastProjectCwd,
+      git,
+      runtime,
+      packageVersion,
+    });
+  }
+}
+
+/**
+ * Finds the nearest repository root without invoking a shell.
+ *
+ * @param cwd Starting directory.
+ * @returns Repository root, when one is visible.
+ */
+function findRepositoryRoot(cwd: string): string | undefined {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+/**
+ * Starts a polling interval unless the configured interval disables polling.
+ *
+ * @param intervalMs Polling interval in milliseconds.
+ * @param refresh Callback invoked for each polling tick.
+ * @returns Idempotent interval cleanup function.
+ */
+export function startProjectRefreshInterval(
+  intervalMs: number,
+  refresh: () => void,
+): StopProjectRefreshInterval {
+  if (intervalMs <= 0) return () => {};
+
+  const timer = setInterval(refresh, intervalMs);
+  timer.unref?.();
+
+  return () => clearInterval(timer);
+}
+
+/**
+ * Creates a throttled, generation-invalidatable project refresh scheduler.
+ *
+ * @param refresh Asynchronous project refresh operation.
+ * @param afterRefresh Callback invoked after a current refresh settles.
+ * @param throttleMs Minimum delay between ordinary refreshes.
+ * @returns Scheduler controls.
+ */
+export function createProjectRefreshScheduler<T>(
+  refresh: (target: T, run: ProjectRefreshRun) => Promise<void>,
+  afterRefresh: () => void,
+  throttleMs = PROJECT_REFRESH_THROTTLE_MS,
+): ProjectRefreshScheduler<T> {
+  let refreshInFlight = false;
+  let refreshPending = false;
+  let pendingForce = false;
+  let pendingTarget: T | undefined;
+  let delayedRefresh: ReturnType<typeof setTimeout> | undefined;
+  let lastRefreshStartedAt: number | undefined;
+  let generation = 0;
+
+  const clearDelayedRefresh = () => {
+    if (!delayedRefresh) return;
+    clearTimeout(delayedRefresh);
+    delayedRefresh = undefined;
+  };
+
+  const runRefresh = (
+    target: T,
+    options: ScheduleProjectRefreshOptions = {},
+  ) => {
+    clearDelayedRefresh();
+    if (refreshInFlight) {
+      refreshPending = true;
+      pendingForce ||= options.force === true;
+      pendingTarget = target;
+      return;
+    }
+
+    const currentGeneration = generation;
+    const run: ProjectRefreshRun = {
+      isCurrent: () => currentGeneration === generation,
+    };
+    refreshInFlight = true;
+    lastRefreshStartedAt = Date.now();
+    void refresh(target, run)
+      .catch(() => undefined)
+      .finally(() => {
+        if (currentGeneration !== generation) return;
+        refreshInFlight = false;
+        afterRefresh();
+        if (refreshPending) {
+          refreshPending = false;
+          const nextForce = pendingForce;
+          pendingForce = false;
+          const nextTarget = pendingTarget ?? target;
+          pendingTarget = undefined;
+          schedule(nextTarget, { force: nextForce });
+        }
+      });
+  };
+
+  const schedule = (target: T, options: ScheduleProjectRefreshOptions = {}) => {
+    if (
+      options.force ||
+      throttleMs <= 0 ||
+      lastRefreshStartedAt === undefined
+    ) {
+      runRefresh(target, options);
+      return;
+    }
+
+    const delayMs = Math.max(
+      0,
+      throttleMs - (Date.now() - lastRefreshStartedAt),
+    );
+    if (delayMs === 0) {
+      runRefresh(target);
+      return;
+    }
+
+    pendingTarget = target;
+    if (delayedRefresh) return;
+    delayedRefresh = setTimeout(() => {
+      delayedRefresh = undefined;
+      const nextTarget = pendingTarget ?? target;
+      pendingTarget = undefined;
+      runRefresh(nextTarget);
+    }, delayMs);
+    delayedRefresh.unref?.();
+  };
+
+  const invalidate = () => {
+    generation += 1;
+    clearDelayedRefresh();
+    refreshInFlight = false;
+    refreshPending = false;
+    pendingForce = false;
+    pendingTarget = undefined;
+    lastRefreshStartedAt = undefined;
+  };
+
+  return {
+    schedule,
+    invalidate,
+    stop: invalidate,
+  };
+}

package/extensions/{shell → services}/project-state.ts

@@ -1,8 +1,8 @@
-import type { GitReadResult } from "./git.ts";
-import { emptyGitStatus } from "./git.ts";
-import type { PackageVersionReadResult } from "./package-version.ts";
-import type { RuntimeReadResult } from "./runtime.ts";
-import type { FooterState } from "./state.ts";
+import type { GitReadResult } from "./git-data.ts";
+import { emptyGitStatus } from "./git-data.ts";
+import type { PackageVersionReadResult } from "./package-data.ts";
+import type { RuntimeReadResult } from "./runtime-data.ts";
+import type { FooterState } from "./session-state.ts";
 
 /**
  * Apply a project refresh (git + runtime) onto footer state, preserving

package/extensions/{shell/state.ts → services/session-state.ts}

@@ -8,10 +8,12 @@ import {
   buildTokenLabel,
   formatProviderLabel,
   getUsageTotals,
-} from "./format.ts";
-import type { GitStatusSummary } from "./git.ts";
-import type { PackageVersionResult } from "./package-version.ts";
-import type { RuntimeInfo } from "./runtime.ts";
+  invalidateUsageTotalsCache,
+} from "../shared/format.ts";
+import { emptyGitStatus } from "./git-data.ts";
+import type { GitStatusSummary } from "./git-data.ts";
+import type { PackageVersionResult } from "./package-data.ts";
+import type { RuntimeInfo } from "./runtime-data.ts";
 import type { FooterTelemetry } from "./telemetry.ts";
 
 export type FooterState = GitStatusSummary & {
@@ -60,6 +62,74 @@ export function modelLabelFor(
     : state.modelId || "no-model";
 }
 
+export type SessionStateSynchronizer = (
+  state: FooterState,
+  ctx: ExtensionContext,
+  cacheHitIcon: string,
+  telemetry: FooterTelemetry,
+) => void;
+
+export type SessionStateServiceContext = {
+  readonly getCacheHitIcon: () => string;
+  readonly resolveTelemetry: (ctx: ExtensionContext) => FooterTelemetry;
+  readonly syncState: SessionStateSynchronizer;
+};
+
+/**
+ * Owns the shared Footer state lifecycle used by the runtime and layouts.
+ */
+export class SessionStateService {
+  readonly state: FooterState;
+  private readonly context: SessionStateServiceContext;
+
+  /**
+   * Creates a session state service with neutral Git defaults.
+   *
+   * @param context Runtime selectors for icons and optional telemetry.
+   */
+  constructor(context: SessionStateServiceContext) {
+    this.context = context;
+    this.state = createInitialState(emptyGitStatus());
+  }
+
+  /**
+   * Resets session-scoped state and invalidates cached usage totals.
+   */
+  startSession(): void {
+    this.state.sessionStartEpoch = Date.now();
+    invalidateUsageTotalsCache();
+  }
+
+  /**
+   * Invalidates cached usage totals before a fresh state synchronization.
+   */
+  invalidateUsageCache(): void {
+    invalidateUsageTotalsCache();
+  }
+
+  /**
+   * Synchronizes model, context, usage, cost, and telemetry fields.
+   *
+   * @param ctx Active Pi extension context.
+   */
+  sync(ctx: ExtensionContext): void {
+    this.context.syncState(
+      this.state,
+      ctx,
+      this.context.getCacheHitIcon(),
+      this.context.resolveTelemetry(ctx),
+    );
+  }
+}
+
+/**
+ * Synchronizes a Footer state snapshot with the active Pi context.
+ *
+ * @param state Mutable Footer state snapshot.
+ * @param ctx Active Pi extension context.
+ * @param cacheHitIcon Cache-hit icon used by the token formatter.
+ * @param telemetry Optional telemetry values.
+ */
 export function syncState(
   state: FooterState,
   ctx: ExtensionContext,
@@ -70,7 +140,7 @@ export function syncState(
   const m = ctx.model;
   state.modelId = m?.id ?? "";
   state.modelName = m?.name ?? "";
-  // Retained as a compatibility snapshot only; production surfaces format from raw fields.
+  // Retained as a compatibility snapshot only; production layouts format from raw fields.
   state.modelLabel = modelLabelFor(state, "id");
   state.providerLabel = formatProviderLabel(ctx.model?.provider);
   state.contextLabel = buildContextLabel(ctx);

package/extensions/{shell → shared}/format.ts

@@ -9,15 +9,15 @@ import type {
   GitBranchMaxLength,
   PathDisplayMode,
 } from "../app/config/shell.ts";
-import type { GitCommitInfo, GitMetricsInfo } from "./git.ts";
+import type { GitCommitInfo, GitMetricsInfo } from "../services/git-data.ts";
 import type { IconMode } from "./icons.ts";
 import {
   resolveOsIcon,
   resolvePackageIcon,
   resolveRuntimeSymbol,
 } from "./icons.ts";
-import type { PackageVersionResult } from "./package-version.ts";
-import type { RuntimeInfo } from "./runtime.ts";
+import type { PackageVersionResult } from "../services/package-data.ts";
+import type { RuntimeInfo } from "../services/runtime-data.ts";
 import { renderStyleForSource } from "./style.ts";
 
 /**
@@ -440,7 +440,7 @@ export function formatRuntimeSegment(
 /**
  * Render the package-version segment in Starship `is <glyph> <version>` shape.
  *
- * Distinct from the runtime segment: this surfaces the project's own
+ * Distinct from the runtime segment: this layouts the project's own
  * manifest version (e.g. `package.json#version`), not the installed
  * toolchain version. Glyph comes from the Starship Nerd Font preset
  * (https://starship.rs/presets/nerd-font); default color `208` matches

package/extensions/tools/component-tree.ts

@@ -1,11 +1,11 @@
 /**
- * 组件树递归遍历共享实现。
+ * Shared recursive traversal for component trees.
  *
- * 收敛原先散落在 renderer 的 compact-mode / message-display / transcript-refresh /
- * grouping / mouse/packets 的「children + getMountedRoots + seen 防环」同款遍历。
+ * The implementation covers the children/getMountedRoots/seen traversal used by
+ * context rendering, grouping and mouse packet handling.
  *
- * visitor 在每个非数组对象节点上调用一次；返回 `false` 表示不再下钻该节点的
- * children 与 mounted roots（对应各处原有的提前 return 语义）。
+ * The visitor runs once for every non-array object. Returning `false` stops
+ * traversal into that node's children and mounted roots.
  */
 export function walkComponentTree(
   root: any,
@@ -30,7 +30,7 @@ export function walkComponentTree(
         for (const root of mounted) visit(root);
       }
     } catch {
-      // renderer 切换中的惰性 Proxy 可能暂时没有 mounted roots。
+      // A lazy proxy may temporarily have no mounted roots while switching renderers.
     }
   };
   visit(root);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-one-ui",
-  "version": "0.1.1",
-  "description": "A single, customizable Pi UI package combining Zentui shell chrome with Claude Code-style transcript rendering.",
+  "version": "0.2.0",
+  "description": "A single, customizable Pi UI package with layout-oriented Context and Shell rendering for Pi.",
   "type": "module",
   "license": "MIT",
   "files": [
@@ -13,11 +13,11 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "npm run test:node && npm run test:vitest",
-    "test:node": "node --test tests/config.test.ts tests/one-ui-integration.test.ts tests/transcript-*.test.ts",
+    "test:node": "node --test tests/config.test.ts tests/config-store.test.ts tests/header-*.test.ts tests/one-ui-integration.test.ts tests/overlay-infrastructure.test.ts tests/runtime-infrastructure.test.ts tests/context-*.test.ts",
     "format": "biome format --write extensions tests package.json tsconfig.json biome.json",
     "format:check": "biome format extensions tests package.json tsconfig.json biome.json",
     "lint": "biome check extensions/index.ts extensions/app/panel.ts extensions/app/presets.ts package.json tsconfig.json biome.json",
-    "test:vitest": "vitest run tests/shell-*.test.ts",
+    "test:vitest": "vitest run tests/shell-*.test.ts tests/working-line-*.test.ts tests/editor-*.test.ts tests/footer-*.test.ts tests/services-*.test.ts",
     "verify": "npm run format:check && npm run lint && npm run typecheck && npm test",
     "pack:check": "npm pack --dry-run",
     "pi:dev": "${PI_BIN:-pi} --no-extensions -e ./extensions/index.ts",