@jxsuite/studio 2.0.0 → 2.1.0

package/src/services/clock.ts

@@ -0,0 +1,61 @@
+/**
+ * Clock — the one seam every _relative_ time in Studio reads "now" through.
+ *
+ * Four surfaces render a duration rather than an instant: the Source Control panel's commit ages
+ * and "last refreshed", the Start pane's "last opened", the chat session list's row times, and the
+ * recents list those two read from. Each of them called `Date.now()` inline, which had two costs:
+ *
+ * 1. **They were untestable.** A formatter that reads the wall clock can only be asserted against an
+ *    offset from the real present, so "yesterday" and "over a year ago" were never covered.
+ * 2. **They drift.** Two captures of the same state minutes apart legitimately read `01:59 PM` and
+ *    `02:04 PM` (UX-REDESIGN-PLAN §13.4 measured exactly that on the git-panel shot).
+ *
+ * This is deliberately NOT a global `Date.now` override. Monaco, every `setTimeout`, the collab
+ * clock and the transaction log all read the real clock and must keep reading it — pinning time for
+ * the whole realm hangs the editor. Four imports, four honest readers.
+ *
+ * `pinClock` is also what makes session restore's "last opened" honest: the value written is the
+ * value the formatter reads back.
+ */
+
+/** Epoch milliseconds the clock is pinned to, or `null` while it follows the real clock. */
+let _pinned: number | null = null;
+
+/**
+ * The current time in epoch milliseconds — pinned when {@link pinClock} has been called, otherwise
+ * the wall clock.
+ *
+ * Frozen rather than offset while pinned: a shot, a test and a bug report all want the SAME answer
+ * on the tenth read as on the first, and a ticking pin reintroduces exactly the drift it exists to
+ * remove.
+ */
+export function now(): number {
+  return _pinned ?? Date.now();
+}
+
+/**
+ * Pin the clock to a fixed instant. Accepts epoch milliseconds, a `Date`, or anything `Date` parses
+ * (the `2026-01-15T09:30:00Z` an `open.clock` field carries).
+ *
+ * @returns The pinned instant, in epoch milliseconds.
+ * @throws {TypeError} When the value cannot be read as a time — a silently-ignored pin would
+ *   photograph the wall clock and the capture would be accepted.
+ */
+export function pinClock(at: number | string | Date): number {
+  const ms = at instanceof Date ? at.getTime() : typeof at === "number" ? at : Date.parse(at);
+  if (!Number.isFinite(ms)) {
+    throw new TypeError(`clock: cannot pin to ${JSON.stringify(at)}`);
+  }
+  _pinned = ms;
+  return ms;
+}
+
+/** Release the pin; {@link now} follows the wall clock again. */
+export function unpinClock(): void {
+  _pinned = null;
+}
+
+/** Whether the clock is currently pinned. Read by `probe.state()` and by the tests. */
+export function isClockPinned(): boolean {
+  return _pinned !== null;
+}

package/src/services/document-assistant.ts

@@ -12,11 +12,13 @@
 import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
-import { activeTab, setWorkspaceProject, workspace } from "../workspace/workspace";
+import { activeTab, workspace } from "../workspace/workspace";
 import { toRaw } from "../reactivity";
-import { projectState, setProjectState } from "../store";
+import { projectState } from "../store";
+import { adoptProjectConfig } from "../tabs/project-config";
 import type { Tab } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
+import { activeRegistry } from "../commands/active-registry";
 import { registerAiTools } from "./ai-tools";
 import { registerProjectTools } from "./ai-project-tools";
 import { createGatedToolRegistry } from "./gated-registry";
@@ -104,11 +106,12 @@ export function createDocumentAssistant() {
         sessionStore.moveSession("", root, sessionId);
       }
     },
-    onProjectConfigWritten: (config: ProjectConfig) => {
-      setWorkspaceProject(workspace.projectRoot, config);
-      if (projectState) {
-        setProjectState({ ...projectState, projectConfig: config });
-      }
+    onProjectConfigWritten: async (config: ProjectConfig) => {
+      /* Into the configuration document, not beside it. This used to assign a fresh object to
+         `projectState.projectConfig`, leaving the document holding the previous configuration —
+         and the next settings commit wrote that stale document back over the assistant's file.
+         `adoptProjectConfig` is the one door for a config that reached disk another way. */
+      await adoptProjectConfig(config);
       /* An `extensions` edit changes what the generated entry documents compose, and the backends
          regenerate them from project.json on demand — so without this the editor and the assistant
          both keep judging by the PREVIOUS project's schemas until the window reopens. */
@@ -125,12 +128,37 @@ export function createDocumentAssistant() {
     "no-project": "no project to be open (it bootstraps one)",
     project: "an open project",
     document: "an open document (use open_document first)",
+    "document-tree":
+      "an open document whose element tree the canvas is editing — Project Settings and the " +
+      "grid editors are documents, but not trees to restructure",
   } as const;
+
+  /**
+   * The HUMAN's own gate, read rather than reimplemented.
+   *
+   * `Command.aiTool` promises "the human's gate and the agent's gate stay one predicate", and the
+   * only way to keep that promise is for the agent to ask the same object: this is the
+   * `CommandContext` `selection.delete` and the movers are evaluated against. Recomputing
+   * `editor.kind` here would make two predicates that agree today and drift the first time either
+   * is edited. Falls back to permissive when no registry is installed — the assistant runs in tests
+   * that never build one, and refusing everything there would be a second wrong answer.
+   */
+  const treeEditable = () => {
+    const registry = activeRegistry();
+    // `=== "canvas"`, the human's exact test — not a looser cousin of it. Being more permissive for
+    // The agent than for the person is the divergence this is here to remove.
+    return registry ? registry.context().editor.kind === "canvas" : true;
+  };
   const availability = new Map<string, ToolAvailability>(
     AI_TOOL_TIERS.map((t) => [
       t.name,
       {
-        when: () => tierActive(t.tier, Boolean(workspace.projectRoot), Boolean(activeTab.value)),
+        when: () =>
+          tierActive(t.tier, {
+            hasDocument: Boolean(activeTab.value),
+            hasProject: Boolean(workspace.projectRoot),
+            treeEditable: treeEditable(),
+          }),
         requires: TIER_REQUIREMENTS[t.tier],
       },
     ]),

package/src/services/idle.ts

@@ -0,0 +1,179 @@
+/// <reference lib="dom" />
+/**
+ * Idle.ts — "settled" is a predicate, and it can fail.
+ *
+ * One question — _has Studio finished reacting?_ — asked of the five subsystems that can still be
+ * mid-flight, over two consecutive animation frames (spec studio.md §13.5, plan §13.4).
+ *
+ * **The rejection is the point.** The thing this replaces is 115 `wait: {ms}` steps totalling 73
+ * seconds, and a sleep cannot fail: a subsystem that was slow that day got answered with `+500 ms`
+ * and the wrong state was photographed, committed and accepted. {@link NotIdleError} carries a
+ * `blockedBy` array naming every outstanding item — `["canvas[page-1]: gen 7 unacked", "platform: 1
+ * in-flight (gitStatus)"]` — so the slow subsystem identifies itself.
+ *
+ * Nothing here polls a subsystem it does not own. Each source is a function the owning module
+ * already had to write for its own reasons:
+ *
+ * 1. `store.rendersInFlight()` — renderers mid-paint.
+ * 2. `panel-scheduler.pendingSchedulers()` — panels with a frame queued or a render withheld.
+ * 3. `iframe-host.canvasIdleBlockers()` — per host: unacked generations and patches, plus the frame's
+ *    own cross-realm report of fonts, running animations and pending image retries.
+ * 4. `platform.platformInFlight()` — unsettled PAL calls, counted at the one seam every adapter and
+ *    all thirty-odd `git*`/fs/fetch methods pass through.
+ * 5. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
+ *    resting toast is not a blocker, which is what lets `toastsAreHeld()` hold one open for a
+ *    capture without `probeIdle()` waiting forever alongside it (plan §13.7's named exception).
+ * 6. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
+ *    duplicate of `platform`: an activity spans a whole operation (an install, a deploy, a clone)
+ *    across many PAL calls, so the gaps between them look quiet at the seam while the operation is
+ *    plainly mid-flight. A finished entry never blocks — the list stays on screen forever.
+ *
+ * The consumers are the `packages/studio:verify` skill, the screenshot runner and P4.2's Activity
+ * tracker (this is a read-only projection of the same in-flight set that dock renders).
+ */
+
+import { rendersInFlight } from "../store";
+import { activityIdleBlockers } from "../panels/activity-panel";
+import { pendingSchedulers } from "../panels/panel-scheduler";
+import { canvasIdleBlockers } from "../canvas/iframe-host";
+import { platformInFlight } from "../platform";
+import { overlayIdleBlockers } from "../ui/layers";
+
+/** One subsystem that can be outstanding, and its account of why. */
+export interface IdleSource {
+  /** Stable name — `render`, `panels`, `canvas`, `platform`, `overlay`. */
+  readonly name: string;
+  /** Empty when quiet; otherwise one human-readable line per outstanding item. */
+  blockers: () => readonly string[];
+}
+
+/** Consecutive quiet animation frames required before Studio counts as settled. */
+export const QUIET_FRAMES = 2;
+
+/** How long {@link probeIdle} waits before rejecting with what is still outstanding. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 10_000;
+
+/** Thrown when Studio did not settle in time — `blockedBy` is the answer, not the message. */
+export class NotIdleError extends Error {
+  readonly blockedBy: readonly string[];
+
+  constructor(blockedBy: readonly string[], timeoutMs: number) {
+    super(
+      blockedBy.length === 0
+        ? `Studio did not report ${QUIET_FRAMES} consecutive quiet frames within ${timeoutMs}ms`
+        : `Studio was not idle after ${timeoutMs}ms — blocked by ${blockedBy.join("; ")}`,
+    );
+    this.name = "NotIdleError";
+    this.blockedBy = blockedBy;
+  }
+}
+
+/**
+ * The six live sources.
+ *
+ * Built per call rather than held in a module constant so a test can substitute one without
+ * unpicking the others, and so a second window's hosts are never read through the first window's
+ * closure.
+ */
+export function defaultIdleSources(): IdleSource[] {
+  return [
+    {
+      blockers: () => {
+        const count = rendersInFlight();
+        return count > 0 ? [`render: ${count} renderer(s) mid-paint`] : [];
+      },
+      name: "render",
+    },
+    {
+      blockers: () => pendingSchedulers().map((panel) => `panels: ${panel}`),
+      name: "panels",
+    },
+    { blockers: canvasIdleBlockers, name: "canvas" },
+    {
+      blockers: () => {
+        const calls = platformInFlight();
+        if (calls.length === 0) {
+          return [];
+        }
+        return [`platform: ${calls.length} in-flight (${[...new Set(calls)].join(", ")})`];
+      },
+      name: "platform",
+    },
+    { blockers: overlayIdleBlockers, name: "overlay" },
+    { blockers: activityIdleBlockers, name: "activity" },
+  ];
+}
+
+/** Everything outstanding right now, across every source. Empty means this instant is quiet. */
+export function idleBlockers(sources: readonly IdleSource[] = defaultIdleSources()): string[] {
+  const blockers: string[] = [];
+  for (const source of sources) {
+    blockers.push(...source.blockers());
+  }
+  return blockers;
+}
+
+export interface IdleOptions {
+  timeoutMs?: number;
+  /** Consecutive quiet frames required. Defaults to {@link QUIET_FRAMES}. */
+  frames?: number;
+  /** Substitute the quiescence sources — what a test states, and what a second window would pass. */
+  sources?: readonly IdleSource[];
+  /** Frame scheduler, injectable so the loop is testable without a real compositor. */
+  raf?: (callback: () => void) => void;
+  /** Clock, injectable for the same reason. */
+  now?: () => number;
+}
+
+/**
+ * Resolve once every source has been quiet for `frames` consecutive animation frames.
+ *
+ * Rejects with {@link NotIdleError} on timeout. A single quiet frame is not enough: a render commits
+ * its DOM in one frame and its layout/animation consequences in the next, which is exactly the
+ * window a one-frame check photographs.
+ */
+export function probeIdle(options: IdleOptions = {}): Promise<void> {
+  const {
+    frames = QUIET_FRAMES,
+    now = () => Date.now(),
+    raf = (callback: () => void) => {
+      requestAnimationFrame(() => callback());
+    },
+    sources = defaultIdleSources(),
+    timeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  } = options;
+
+  return new Promise<void>((resolve, reject) => {
+    const deadline = now() + timeoutMs;
+    let quiet = 0;
+    let settled = false;
+    // The last non-empty account, so a timeout that lands on a momentarily-quiet frame still names
+    // What kept it from reaching `frames` — "not idle, blocked by nothing" helps nobody.
+    let lastBlockers: readonly string[] = [];
+
+    const tick = () => {
+      if (settled) {
+        return;
+      }
+      const blockers = idleBlockers(sources);
+      if (blockers.length > 0) {
+        lastBlockers = blockers;
+        quiet = 0;
+      } else {
+        quiet += 1;
+        if (quiet >= frames) {
+          settled = true;
+          resolve();
+          return;
+        }
+      }
+      if (now() >= deadline) {
+        settled = true;
+        reject(new NotIdleError(blockers.length > 0 ? blockers : lastBlockers, timeoutMs));
+        return;
+      }
+      raf(tick);
+    };
+    raf(tick);
+  });
+}

package/src/services/import-client.ts

@@ -10,6 +10,15 @@
 import type { ImportProgressEvent, ImportSiteOptions } from "../types";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
+/**
+ * The `phase` of the one progress line this client emits itself rather than forwarding.
+ *
+ * Exported so a caller can recognize it without matching a bare string: the import log renders
+ * every phase verbatim, but a warning also needs to outlive the log, which vanishes the moment a
+ * successful import hands off to the new project.
+ */
+export const IMPORT_WARNING_PHASE = "warning";
+
 interface StreamLine {
   type: string;
   phase?: string;
@@ -77,6 +86,13 @@ export async function streamImport(
   const decoder = new TextDecoder();
   let buffer = "";
   let result: { root: string; config: ProjectConfig } | null = null;
+  /*
+   * Lines the parser could not read. Tolerating one is right — an import that ran for two minutes
+   * should not die on a garbled progress line — but doing it *silently* is not: the import then
+   * finishes looking clean while the user never sees the pages it skipped. Counted here and
+   * surfaced once at the end, so the tolerance stays visible instead of becoming a hiding place.
+   */
+  let unreadable = 0;
 
   const handleLine = (line: string) => {
     const trimmed = line.trim();
@@ -87,6 +103,7 @@ export async function streamImport(
     try {
       parsed = JSON.parse(trimmed) as StreamLine;
     } catch {
+      unreadable += 1;
       return; // Tolerate a mangled line rather than killing the whole import.
     }
     if (parsed.type === "progress") {
@@ -127,6 +144,15 @@ export async function streamImport(
     }
   }
 
+  if (unreadable > 0) {
+    onProgress({
+      message:
+        `${unreadable} progress line${unreadable === 1 ? "" : "s"} could not be read and ` +
+        `${unreadable === 1 ? "was" : "were"} skipped — the import may be missing steps.`,
+      phase: IMPORT_WARNING_PHASE,
+    });
+  }
+
   if (!result) {
     throw new Error("Import stream ended without a result");
   }