@hienlh/ppm 0.23.11 → 0.23.12

package/src/web/hooks/use-file-index-invalidation.ts

@@ -3,19 +3,21 @@ import { useProjectStore } from "@/stores/project-store";
 import { useFileStore, relativeProjectPath } from "@/stores/file-store";
 import { onFsChanged } from "@/components/os-explorer/explorer-store";
 
-/** Keep on-demand indexes fresh even while the mobile file drawer is closed. */
+/**
+ * Keep on-demand indexes fresh even while the mobile file drawer is closed. A change only marks
+ * the index stale — it is refetched when something opens to read it, see `indexStale`.
+ */
 export function useFileIndexInvalidation(): void {
   useEffect(() => {
     const changed = (event: Event) => {
       const projectName = (event as CustomEvent).detail?.projectName;
-      const store = useFileStore.getState();
-      if (projectName && projectName === store.indexProjectName) store.invalidateIndex();
+      if (typeof projectName === "string") useFileStore.getState().markIndexStale(projectName);
     };
     window.addEventListener("file:changed", changed);
     const unsubscribeFs = onFsChanged((directory) => {
       const store = useFileStore.getState();
-      const project = useProjectStore.getState().projects.find((p) => p.name === store.indexProjectName);
-      if (project && relativeProjectPath(project.path, directory) !== null) store.invalidateIndex();
+      const project = useProjectStore.getState().projects.find((p) => p.name === store.indexProject);
+      if (project && relativeProjectPath(project.path, directory) !== null) store.markIndexStale(project.name);
     });
     const unsubscribeProject = useProjectStore.subscribe((state, previous) => {
       if (state.activeProject?.name !== previous.activeProject?.name) useFileStore.getState().reset();

package/src/web/hooks/use-global-events.ts

@@ -3,6 +3,7 @@ import { WsClient } from "@/lib/ws-client";
 import { getAuthToken } from "@/lib/api-client";
 import { useNotificationStore } from "@/stores/notification-store";
 import { useStreamingStore } from "@/stores/streaming-store";
+import { useFileStore } from "@/stores/file-store";
 import { syncRunningSessions } from "@/lib/sync-running-sessions";
 import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
 import { notifyGlobalReady, sendIfOpen, setGlobalWsClient } from "@/lib/global-ws-channel";
@@ -23,7 +24,11 @@ const IDLE_TIMEOUT_MS = 45_000;
  *
  * Handles:
  * - `file:changed` → re-dispatched as a window event for the editor, previews and
- *   file tree to consume.
+ *   file tree to consume, and marks the file index stale.
+ * - `files:index-changed` → marks the file index stale: the server rebuilt it behind the list
+ *   it had been serving, and the paths differ. Neither event fetches the index — on a large
+ *   project that is a 22 MB download — unless something is showing it right now (the palette,
+ *   a picker; see `openIndexReader`); otherwise it is refreshed when something opens to read it.
  * - `session:unread_changed` → cross-device unread sync.
  * - `session:phase_changed` → keeps the tab-strip spinner and title indicator
  *   correct for sessions whose tab is not mounted, and — critically — clears them
@@ -94,10 +99,16 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
       }
 
       if (type === "file:changed") {
+        if (typeof data.projectName === "string") useFileStore.getState().markIndexStale(data.projectName);
         window.dispatchEvent(new CustomEvent("file:changed", { detail: data }));
         return;
       }
 
+      if (type === "files:index-changed") {
+        if (typeof data.projectName === "string") useFileStore.getState().indexRebuilt(data.projectName);
+        return;
+      }
+
       if (type === "session:unread_changed") {
         const d = data as unknown as {
           sessionId: string; unreadCount: number; unreadType: string | null;

package/src/web/hooks/use-remote-file-search.ts

@@ -0,0 +1,39 @@
+/**
+ * The best entries of a project whose file list is too long to send to the browser
+ * (`indexRemote`), searched on the server for `query` — for the palette and the pickers, which
+ * would otherwise filter `fileIndex` themselves. They still rank what comes back as they rank a
+ * list they hold; the server only saves them from holding 175k entries to find the best 100.
+ *
+ * What was last answered stays until the next answer lands, so typing does not blank the list,
+ * and it asks again whenever an index lands (`indexRevision`) — the server's list moved.
+ */
+import { useEffect, useState } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { useFileStore } from "@/stores/file-store";
+import { REMOTE_FILE_SEARCH_LIMIT } from "../../shared/file-index-limits";
+import type { FileEntry } from "../../types/project";
+
+const NONE: FileEntry[] = [];
+
+export function useRemoteFileSearch(
+  projectName: string | null | undefined,
+  query: string,
+  { enabled, kind = "file" }: { enabled: boolean; kind?: "file" | "all" },
+): FileEntry[] {
+  const revision = useFileStore((s) => s.indexRevision);
+  const [files, setFiles] = useState<FileEntry[]>(NONE);
+
+  useEffect(() => {
+    if (!enabled || !projectName) {
+      setFiles(NONE);
+      return;
+    }
+    const controller = new AbortController();
+    const params = new URLSearchParams({ q: query, kind, limit: String(REMOTE_FILE_SEARCH_LIMIT) });
+    api.get<FileEntry[]>(`${projectUrl(projectName)}/files/index/search?${params}`, { signal: controller.signal })
+      .then(setFiles, () => { /* superseded by the next keystroke, or failed: keep what is shown */ });
+    return () => controller.abort();
+  }, [projectName, query, enabled, kind, revision]);
+
+  return files;
+}

package/src/web/hooks/use-ui-preload.ts

@@ -0,0 +1,38 @@
+import { useEffect } from "react";
+import { tabPreloads } from "@/components/layout/tab-pool";
+import { WINDOW_CONTENT } from "@/components/floating-window/window-content-registry";
+import { isTouchOnlyDevice } from "@/hooks/use-is-touch-only";
+import { preloadWhenIdle, shouldPreloadUi, type ConnectionHints } from "@/lib/preload-ui";
+
+/** The head start the tabs a workspace restores get, as in `use-tab-prefetch.ts`. */
+const START_DELAY_MS = 2500;
+
+/** Imported, not reached statically: that would pull Settings' shell into the boot chunk. */
+const preloadSettingsPanes = () =>
+  import("@/components/settings/settings-section-content").then((m) => m.preloadSettingsSections());
+
+/**
+ * Loads the code of every kind of tab and window, and of every Settings pane, once the app has
+ * settled, so the first one of each opens at once. Not under `vite dev`, where it would be
+ * hundreds of unbundled modules.
+ */
+export function useUiPreload(enabled: boolean): void {
+  useEffect(() => {
+    if (!enabled || import.meta.env.DEV) return;
+    const connection = (navigator as Navigator & { connection?: ConnectionHints }).connection;
+    if (!shouldPreloadUi(connection, isTouchOnlyDevice())) return;
+
+    let stop = () => {};
+    const timer = setTimeout(() => {
+      stop = preloadWhenIdle([
+        ...tabPreloads(),
+        ...Object.values(WINDOW_CONTENT).map((content) => content.preload),
+        preloadSettingsPanes,
+      ]);
+    }, START_DELAY_MS);
+    return () => {
+      clearTimeout(timer);
+      stop();
+    };
+  }, [enabled]);
+}

package/src/web/index.html

@@ -91,6 +91,48 @@
             purge().then(function () { location.reload(); });
           };
         }
+        // Tell the server, since nothing bundled can: an `entry_never_ran` row in the
+        // session trace, naming the files that failed to load where the browser says.
+        // Same device id and token keys as src/web/lib/device-id.ts and api-client.ts.
+        function beacon(retried) {
+          try {
+            var token = null, dev = null;
+            try {
+              token = localStorage.getItem("ppm-auth-token");
+              dev = localStorage.getItem("ppm-device-id");
+            } catch (e) {}
+            if (!dev || !/^[A-Za-z0-9-]{8,64}$/.test(dev)) {
+              var b = new Uint8Array(16);
+              crypto.getRandomValues(b);
+              b[6] = (b[6] & 15) | 64;
+              b[8] = (b[8] & 63) | 128;
+              var h = "";
+              for (var i = 0; i < 16; i++) h += (b[i] + 256).toString(16).slice(1);
+              dev = h.slice(0, 8) + "-" + h.slice(8, 12) + "-" + h.slice(12, 16) + "-" + h.slice(16, 20) + "-" + h.slice(20);
+              try { localStorage.setItem("ppm-device-id", dev); } catch (e) {}
+            }
+            var failed = [];
+            try {
+              var list = performance.getEntriesByType("resource");
+              for (var j = 0; j < list.length && failed.length < 20; j++) {
+                if (list[j].responseStatus >= 400) failed.push(list[j].name.replace(location.origin, "") + " " + list[j].responseStatus);
+              }
+            } catch (e) {}
+            var now = Date.now();
+            var headers = { "Content-Type": "application/json" };
+            if (token) headers.Authorization = "Bearer " + token;
+            fetch("/api/trace", {
+              method: "POST",
+              keepalive: true,
+              headers: headers,
+              body: JSON.stringify({
+                deviceId: dev,
+                sentAt: now,
+                entries: [{ ts: now, type: "entry_never_ran", refId: null, payload: { path: location.pathname, retried: retried, failed: failed, ua: navigator.userAgent } }],
+              }),
+            }).catch(function () {});
+          } catch (e) {}
+        }
         function check() {
           // Module scripts execute before `load`, so a flag still unset here is
           // never going to be set — this cannot misfire on a slow boot.
@@ -113,6 +155,7 @@
             // reload is a loop. Go straight to the message.
             retried = true;
           }
+          beacon(retried);
           // One silent attempt first: index.html is served `no-cache`, so a
           // reload with this origin's caches dropped is exactly how a tab
           // holding an upgraded-away chunk list heals itself.

package/src/web/lib/chunk-recovery.ts

@@ -24,6 +24,8 @@
  * one that says what happened.
  */
 
+import { reportTraceError } from "./trace-client";
+
 const RELOAD_KEY = "ppm:chunk-reload";
 
 /**
@@ -107,7 +109,9 @@ export function installChunkErrorRecovery(): void {
   // rethrow, and `React.lazy` then fails reading `.default` of undefined — an
   // error that says nothing about what actually happened. The reload normally
   // wins the race; when it does not, the boundary catches the real throw.
-  window.addEventListener("vite:preloadError", () => {
+  window.addEventListener("vite:preloadError", (event) => {
+    // Recorded before the reload; the page-hide flush carries it out as the page goes.
+    reportTraceError("chunk_error", (event as (Event & { payload?: unknown }) | undefined)?.payload ?? "vite:preloadError");
     reloadOnceForChunkError();
   });
 }

package/src/web/lib/device-id.ts

@@ -0,0 +1,39 @@
+/**
+ * A stable id for this browser, minted once. Browser rows in the session trace are keyed by it
+ * (`browser:<deviceId>`), which answers "which machine does this happen on" and gives each
+ * device its own rate limit on `POST /api/trace`.
+ *
+ * `index.html`'s boot watchdog reads and mints the same key without the bundle, so the two
+ * formats must stay identical.
+ */
+
+export const DEVICE_ID_KEY = "ppm-device-id";
+const VALID = /^[A-Za-z0-9-]{8,64}$/;
+
+let memo: string | null = null;
+
+/**
+ * A v4 UUID from `getRandomValues`. Not `crypto.randomUUID`: that exists only in a secure
+ * context, and PPM is routinely reached over plain HTTP on a LAN.
+ */
+export function uuidV4(): string {
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  b[6] = (b[6]! & 0x0f) | 0x40;
+  b[8] = (b[8]! & 0x3f) | 0x80;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+export function getDeviceId(): string {
+  if (memo) return memo;
+  try {
+    const stored = localStorage.getItem(DEVICE_ID_KEY);
+    if (stored && VALID.test(stored)) return (memo = stored);
+  } catch {
+    // Private mode can refuse storage outright; an id per page load still works.
+  }
+  const id = uuidV4();
+  try { localStorage.setItem(DEVICE_ID_KEY, id); } catch { /* see above */ }
+  return (memo = id);
+}

package/src/web/lib/feature-badges.ts

@@ -16,6 +16,8 @@ export const FEATURE_BADGES = {
   "remote-desktop": "beta",
   /** Design mode (Designs sidebar tab): design chat beside a live canvas, shipped in 0.23.0. */
   designs: "new",
+  /** Android emulator — start an AVD and control its screen from the browser. */
+  android: "beta",
 } as const satisfies Record<string, FeatureBadgeKind>;
 
 export type FeatureBadgeId = keyof typeof FEATURE_BADGES;

package/src/web/lib/lazy-with-preload.tsx

@@ -0,0 +1,43 @@
+/**
+ * `React.lazy`, plus a way to load the module before anything renders it — and, once it is
+ * loaded, a first render that does not suspend at all.
+ *
+ * The second half is the point. A `React.lazy` component suspends on its first render even
+ * when its module is already in memory: its initializer only starts on that render, and a
+ * promise cannot report that it has settled until a microtask later. So the boundary commits
+ * its spinner, and from then on react-dom holds the content back until 300 ms after that
+ * spinner appeared (`FALLBACK_THROTTLE_MS`), however soon it is ready. Measured against
+ * localhost on a desktop: a terminal's code had arrived 11–27 ms after the click, and the
+ * terminal appeared at 350–355 ms. Loading the module sooner cannot change that; not
+ * suspending does.
+ */
+import { lazy, useState, type ComponentType } from "react";
+
+export type PreloadableComponent<P> = ComponentType<P> & {
+  /** Load the module now. A load that fails is forgotten, so the next render asks again. */
+  preload: () => Promise<void>;
+};
+
+export function lazyWithPreload<P extends object>(
+  load: () => Promise<{ default: ComponentType<P> }>,
+): PreloadableComponent<P> {
+  let loaded: ComponentType<P> | undefined;
+  let loading: Promise<void> | undefined;
+  const preload = () =>
+    (loading ??= load().then(
+      (module) => { loaded = module.default; },
+      (error: unknown) => { loading = undefined; throw error; },
+    ));
+  // What an instance mounted before the module arrived renders: it suspends, as `lazy` always did.
+  const Lazy = lazy(() => preload().then(() => ({ default: loaded! })));
+
+  function Preloadable(props: P) {
+    // Chosen once per instance. A transition that suspends here and is pinged before it
+    // resumes commits this instance as `Lazy` without rendering it again, so switching to the
+    // loaded component on a later render would change the element type under it — and React
+    // would remount the whole tab.
+    const [Component] = useState<ComponentType<P>>(() => loaded ?? Lazy);
+    return <Component {...props} />;
+  }
+  return Object.assign(Preloadable, { preload });
+}

package/src/web/lib/preload-ui.ts

@@ -0,0 +1,60 @@
+/**
+ * Loads the code behind every tab and window while the app has nothing else to do, so the
+ * first terminal, editor or chat of a session opens at once instead of behind a spinner.
+ * `lazy-with-preload.tsx` is why a loaded module also has to skip that spinner.
+ *
+ * It is a download, so it is skipped wherever one costs the user something: a data-saver
+ * setting, a 2G link, and any touch-only device not known to be on Wi-Fi — which includes
+ * every iPhone, since Safari says nothing about its connection.
+ */
+
+/** The fields of `navigator.connection` (Network Information API) this reads. */
+export interface ConnectionHints {
+  saveData?: boolean;
+  effectiveType?: string;
+  type?: string;
+}
+
+export function shouldPreloadUi(connection: ConnectionHints | undefined, touchOnly: boolean): boolean {
+  if (connection?.saveData) return false;
+  if (connection?.effectiveType === "slow-2g" || connection?.effectiveType === "2g") return false;
+  if (!touchOnly) return true;
+  return connection?.type === "wifi" || connection?.type === "ethernet";
+}
+
+/** Runs `run` once the main thread is idle; returns a function that calls it off. */
+export type WhenIdle = (run: () => void) => () => void;
+
+const whenIdle: WhenIdle = (run) => {
+  if (typeof requestIdleCallback === "function") {
+    const id = requestIdleCallback(run);
+    return () => cancelIdleCallback(id);
+  }
+  // Safari has no `requestIdleCallback`.
+  const id = setTimeout(run, 200);
+  return () => clearTimeout(id);
+};
+
+/**
+ * Runs `tasks` one after another, each starting in an idle period of its own, so no two
+ * modules are evaluated in one stretch of the main thread. A task that fails is skipped:
+ * whatever needed that module will ask for it again. Returns a function that stops the rest.
+ */
+export function preloadWhenIdle(tasks: ReadonlyArray<() => Promise<unknown>>, idle: WhenIdle = whenIdle): () => void {
+  let stopped = false;
+  let cancel = () => {};
+  const next = (i: number) => {
+    if (stopped || i >= tasks.length) return;
+    cancel = idle(() => {
+      void Promise.resolve()
+        .then(tasks[i])
+        .catch(() => {})
+        .then(() => next(i + 1));
+    });
+  };
+  next(0);
+  return () => {
+    stopped = true;
+    cancel();
+  };
+}

package/src/web/lib/score-file-search.ts

@@ -60,20 +60,7 @@ export function scoreFileSearchFast(
 ): FileSearchScore | null {
   // Multi-word query: score each word independently, require all to match
   if (qLower.includes(" ")) {
-    const words = qLower.split(/\s+/).filter(Boolean);
-    if (words.length === 0) return null;
-    if (words.length === 1) {
-      return scoreFileSearchFast(words[0]!, filenameLower, pathLower, labelLen, depth);
-    }
-    let maxTier = 0;
-    let totalOffset = 0;
-    for (const word of words) {
-      const s = scoreFileSearchFast(word, filenameLower, pathLower, labelLen, depth);
-      if (!s) return null;
-      maxTier = Math.max(maxTier, s.tier);
-      totalOffset += s.offset;
-    }
-    return { tier: maxTier, offset: totalOffset, nameLen: labelLen, depth };
+    return scoreWordsFast(qLower.split(/\s+/).filter(Boolean), filenameLower, pathLower, labelLen, depth);
   }
 
   // Tier 0: exact filename match
@@ -101,6 +88,32 @@ export function scoreFileSearchFast(
   return null;
 }
 
+/**
+ * `scoreFileSearchFast` for a multi-word query already split into its words, so a loop scoring
+ * one query against many paths splits it once rather than once per path.
+ */
+export function scoreWordsFast(
+  words: string[],
+  filenameLower: string,
+  pathLower: string,
+  labelLen: number,
+  depth: number,
+): FileSearchScore | null {
+  if (words.length === 0) return null;
+  if (words.length === 1) {
+    return scoreFileSearchFast(words[0]!, filenameLower, pathLower, labelLen, depth);
+  }
+  let maxTier = 0;
+  let totalOffset = 0;
+  for (const word of words) {
+    const s = scoreFileSearchFast(word, filenameLower, pathLower, labelLen, depth);
+    if (!s) return null;
+    maxTier = Math.max(maxTier, s.tier);
+    totalOffset += s.offset;
+  }
+  return { tier: maxTier, offset: totalOffset, nameLen: labelLen, depth };
+}
+
 /** Convenience wrapper — lowers inputs on the fly. Use for ad-hoc calls. */
 export function scoreFileSearch(
   query: string,

package/src/web/lib/tab-type-icons.ts

@@ -7,7 +7,7 @@
  */
 import {
   Terminal, MessageSquare, FileCode, Database, FileDiff, Settings, Puzzle, Sparkles, Users, CircleX,
-  GitCommitHorizontal, Palette,
+  GitCommitHorizontal, Palette, Smartphone,
   type LucideIcon,
 } from "@/lib/icons";
 import type { ElementType } from "react";
@@ -36,6 +36,7 @@ export const TAB_TYPE_ICONS: Record<TabType, LucideIcon> = {
   group: Users,
   problems: CircleX,
   design: Palette,
+  android: Smartphone,
 };
 
 /** Resolve the icon for a tab type, falling back to a generic glyph. */

package/src/web/lib/trace-boot.ts

@@ -0,0 +1,8 @@
+/**
+ * Starts browser logging. A module of its own so it can be the *first* import of `main.tsx`:
+ * imports evaluate in order before any statement runs, so a call written in `main.tsx` itself
+ * would only happen after the whole app had already evaluated — and logged — without it.
+ */
+import { installTraceClient } from "./trace-client";
+
+installTraceClient();