@jxsuite/studio 2.4.3 → 4.0.0

package/src/services/ai-project-tools.ts

@@ -20,8 +20,9 @@ import type { ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
 import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
 import { workspace } from "../workspace/workspace";
+import { projectState } from "../store";
 import type { Tab } from "../tabs/tab";
-import { beginBatch, endBatch, isBatching } from "../tabs/transact";
+import { adoptCreatedProject } from "./project-adoption";
 import { translateValidationError } from "./ai-tools";
 import { validateDoc, validateProjectConfig } from "./jx-validate";
 import { recordWrite } from "./ai-writes";
@@ -355,8 +356,16 @@ export function registerProjectTools(
           /* The per-project entry document closes the composition over every enabled extension
              (extensions.md §5.2), so this is what catches a typo'd section key or a misshapen
              extension section. Without it the model shipped config its own tool call called clean
-             and Monaco flagged the moment a human opened the file. */
-          const configErrors = await validateProject(parsedConfig);
+             and Monaco flagged the moment a human opened the file.
+
+             Errors the file ALREADY had are subtracted, the same way `services/ai-tools.ts`
+             subtracts them from a document edit: a project whose config was written by something
+             else — an importer, a hand edit, an extension that was removed — would otherwise refuse
+             every write the model attempted, blaming it for a violation it did not introduce and
+             cannot reach from the edit it was asked to make. */
+          const before = new Set(await validateProject(projectState?.projectConfig ?? {}));
+          const found = await validateProject(parsedConfig);
+          const configErrors = found.filter((error) => !before.has(error));
           if (configErrors.length > 0) {
             const formatted = configErrors
               .map((e) => `- ${translateValidationError(e)}`)
@@ -585,30 +594,15 @@ export function registerProjectTools(
         }
 
         /*
-         * Adoption runs the full project-open flow (closes all tabs, opens the home page). The
-         * agent loop may hold an undo batch on the pre-adoption tab — flush it first and re-open
-         * one on whatever tab adoption leaves active, mirroring open_document's batch dance.
-         */
-        const wasBatching = isBatching();
-        if (wasBatching) {
-          endBatch();
-        }
-        let adoptionError: string | null = null;
-        try {
-          await adoptProject(result.root);
-        } catch (error) {
-          adoptionError = error instanceof Error ? error.message : String(error);
-        }
-        if (wasBatching) {
-          beginBatch(getTab());
-        }
-
-        /*
-         * The adopter (openRecentProject) swallows failures into a status message, so a resolved
-         * promise is not proof of adoption — verify against the workspace before re-keying the
-         * chat session.
+         * Git init, then the full project-open flow, then a check that it landed — all three in
+         * `services/project-adoption.ts`, because `import_site` is the same act with a different
+         * backend. Git init in particular was missing here: `specs/desktop.md` §4.5 promises every
+         * create path initialises a repository, and only the New Project modal was keeping it.
          */
-        const adopted = workspace.projectRoot === result.root;
+        const { adopted, error: adoptionError } = await adoptCreatedProject(result.root, {
+          adopt: adoptProject,
+          getTab,
+        });
         if (adopted) {
           onProjectAdopted?.(result.root);
           return {

package/src/services/ai-settings.ts

@@ -1,52 +1,51 @@
 /// <reference lib="dom" />
 /**
- * Ai-settings.js — local persistence for the AI assistant's provider settings.
+ * Ai-settings.js — the AI assistant's provider settings, over the settings kernel.
  *
  * The Stack B proxy reads the OpenAI key from the `X-Api-Key` header (falling back to the server's
- * `OPENAI_API_KEY` env var). Studio stores a user-supplied key in localStorage so the browser/dev
- * build works without an env var. The key never leaves the machine except to the same-origin proxy.
+ * `OPENAI_API_KEY` env var). Studio stores a user-supplied key so the browser/dev build works
+ * without an env var. The key never leaves the machine except to the same-origin proxy.
+ *
+ * This module is now a typed façade over `settings/kernel.ts` — the storage keys, defaults and
+ * normalisation live in `settings/definitions.ts`, and the kernel owns the cache, the write queue
+ * and change notification. What it keeps is the vocabulary: callers say `getOpenAiKey()`, not
+ * `readSetting(SETTINGS.aiOpenAiKey)`.
+ *
+ * **Blank no longer deletes.** `setOpenAiKey("")` stores an empty string; {@link clearAiProvider}
+ * is the revoke path. The old conflation read as a convenience right up until a form that blanked
+ * its own drafts on Save called these setters with them, and a second Save revoked the credentials
+ * the first had stored.
  *
  * @license MIT
  */
 
-import { persistSettings } from "./settings-store";
-
-const KEY_STORAGE = "jx.ai.openaiKey";
-const BASE_URL_STORAGE = "jx.ai.baseUrl";
-const MODEL_STORAGE = "jx.ai.model";
-const DEFAULT_MODEL = "gpt-4o";
+import { SETTINGS } from "./settings/definitions";
+import {
+  clearSettings,
+  hasSetting,
+  readStoredSetting,
+  setSetting,
+  setSettings,
+} from "./settings/kernel";
 
-/** @returns {string} The stored OpenAI key, or "" if none/unavailable. */
+/** @returns {string} The stored OpenAI key, or "" if none. */
 export function getOpenAiKey() {
-  try {
-    return globalThis.localStorage?.getItem(KEY_STORAGE) ?? "";
-  } catch {
-    return "";
-  }
+  return readStoredSetting(SETTINGS.aiOpenAiKey);
 }
 
 /**
- * Persist (or clear) the OpenAI key.
+ * Persist the OpenAI key.
  *
- * @param {string} key - The key to store; an empty/blank value clears it.
+ * @param {string} key - The key to store. A blank value stores blank; it does NOT clear — see
+ *   {@link clearAiProvider}.
  */
 export function setOpenAiKey(key: string) {
-  try {
-    const trimmed = (key || "").trim();
-    if (trimmed) {
-      globalThis.localStorage?.setItem(KEY_STORAGE, trimmed);
-    } else {
-      globalThis.localStorage?.removeItem(KEY_STORAGE);
-    }
-    persistSettings();
-  } catch {
-    /* LocalStorage unavailable — settings are not persisted. */
-  }
+  setSetting(SETTINGS.aiOpenAiKey, key || "");
 }
 
 /** @returns {boolean} Whether a non-empty key is stored. */
 export function hasOpenAiKey() {
-  return getOpenAiKey().length > 0;
+  return hasSetting(SETTINGS.aiOpenAiKey);
 }
 
 /**
@@ -54,59 +53,58 @@ export function hasOpenAiKey() {
  *   or "" to use the proxy's default (`https://api.openai.com/v1` / server `OPENAI_BASE_URL`).
  */
 export function getBaseUrl() {
-  try {
-    return globalThis.localStorage?.getItem(BASE_URL_STORAGE) ?? "";
-  } catch {
-    return "";
-  }
+  return readStoredSetting(SETTINGS.aiBaseUrl);
 }
 
+// ─── Model selection ────────────────────────────────────────────────────────
+
 /**
- * Persist (or clear) the base URL override.
+ * The model the user actually chose, with no default standing in for silence.
  *
- * @param {string} url - The base URL; an empty/blank value clears the override.
+ * The getter this replaced masked _unset_ as `"gpt-4o"`, which is right for a sender and wrong for
+ * anything that writes back: a form prefilled from it and then saved persists a choice nobody made,
+ * which is how `jx.ai.model: "gpt-4o"` came to be the only surviving key in a settings file whose
+ * owner had configured a different provider entirely. Senders want
+ * {@link ../services/ai-models!preferredModel} instead.
+ *
+ * @returns {string} The stored model ID, or "" when none has been chosen.
  */
-export function setBaseUrl(url: string) {
-  try {
-    const trimmed = (url || "").trim().replace(/\/+$/, "");
-    if (trimmed) {
-      globalThis.localStorage?.setItem(BASE_URL_STORAGE, trimmed);
-    } else {
-      globalThis.localStorage?.removeItem(BASE_URL_STORAGE);
-    }
-    persistSettings();
-  } catch {
-    /* LocalStorage unavailable — settings are not persisted. */
-  }
+export function storedModel() {
+  return readStoredSetting(SETTINGS.aiModel);
 }
 
-// ─── Model selection ────────────────────────────────────────────────────────
+/**
+ * Persist the selected model ID.
+ *
+ * @param {string} modelId - The model ID to store. A blank value stores blank; it does NOT clear.
+ */
+export function setModel(modelId: string) {
+  setSetting(SETTINGS.aiModel, modelId || "");
+}
 
-/** @returns {string} The stored model ID, or the default ("gpt-4o"). */
-export function getModel() {
-  try {
-    return globalThis.localStorage?.getItem(MODEL_STORAGE) || DEFAULT_MODEL;
-  } catch {
-    return DEFAULT_MODEL;
-  }
+/**
+ * Store the provider's key, endpoint and model as ONE change.
+ *
+ * What a credentials form's Save should call. Three separate setters coalesce into one write
+ * anyway, but they announce three times, and each intermediate announcement describes a provider
+ * the user never asked for — a new key against the old endpoint, then against no model.
+ *
+ * @param {{ apiKey: string; baseUrl: string; model: string }} provider
+ */
+export function saveAiProvider(provider: { apiKey: string; baseUrl: string; model: string }) {
+  setSettings([
+    [SETTINGS.aiOpenAiKey, provider.apiKey],
+    [SETTINGS.aiBaseUrl, provider.baseUrl],
+    [SETTINGS.aiModel, provider.model],
+  ]);
 }
 
 /**
- * Persist the selected model ID.
+ * Forget the provider entirely — key, endpoint and model.
  *
- * @param {string} modelId - The model ID to store; an empty/blank value clears it, reverting to
- *   default.
+ * The one deletion path, and the one the Accounts list's Disconnect uses. Deliberately all three
+ * together: a key with an orphaned endpoint is a state no surface knows how to describe.
  */
-export function setModel(modelId: string) {
-  try {
-    const trimmed = (modelId || "").trim();
-    if (trimmed) {
-      globalThis.localStorage?.setItem(MODEL_STORAGE, trimmed);
-    } else {
-      globalThis.localStorage?.removeItem(MODEL_STORAGE);
-    }
-    persistSettings();
-  } catch {
-    /* LocalStorage unavailable — settings are not persisted. */
-  }
+export function clearAiProvider() {
+  clearSettings([SETTINGS.aiOpenAiKey, SETTINGS.aiBaseUrl, SETTINGS.aiModel]);
 }

package/src/services/ai-system-prompt.ts

@@ -29,6 +29,12 @@ interface BuildSystemPromptOptions {
    * prompt-shape tests — advertises the same list it always did.
    */
   treeEditable?: boolean | undefined;
+  /**
+   * Whether the platform can import a site. Defaults TRUE so this stays a pure function of what it
+   * is given — a caller that knows nothing about the platform gets the full list, and only
+   * `document-assistant.ts`, which does know, narrows it.
+   */
+  canImport?: boolean | undefined;
   /** Project-relative file paths for the inventory section (project modes; capped). */
   fileInventory?: string[] | undefined;
 }
@@ -52,13 +58,21 @@ const FILE_INVENTORY_CAP = 100;
  * a weaker test than `structurallyEditable`, so a repeater template or `$switch` case was removable
  * by the agent and not by the person.
  */
-export type AiToolTier = "no-project" | "project" | "document" | "document-tree";
+export type AiToolTier = "always" | "no-project" | "project" | "document" | "document-tree";
 
 export interface AiToolInfo {
   name: string;
   tier: AiToolTier;
   /** One-line signature + purpose shown in the system prompt's tool list. */
   blurb: string;
+  /**
+   * A PAL member the tool needs, beyond whatever its tier requires.
+   *
+   * The tier answers "what is open"; this answers "can this backend do it at all". Cloud ships no
+   * `importSite`, so `import_site` must not be advertised there — and a tier cannot express that,
+   * because "no project is open" is exactly as true on cloud as anywhere else.
+   */
+  capability?: "importSite";
 }
 
 /**
@@ -67,7 +81,27 @@ export interface AiToolInfo {
  * list cannot drift (a test asserts the names match the registered tools).
  */
 export const AI_TOOL_TIERS: AiToolInfo[] = [
+  // Always — a question is not gated on what happens to be open
+  {
+    name: "ask_user",
+    tier: "always",
+    blurb:
+      "ask_user(question, options?, context?) — pause and put a question to the user; the turn " +
+      "waits for their reply and resumes with it. Only for a judgement that is genuinely theirs.",
+  },
   // Bootstrap (no project open)
+  {
+    name: "import_site",
+    tier: "no-project",
+    capability: "importSite",
+    blurb:
+      "import_site(url, directory?, depth?, maxPages?, aiComponents?, maxBreakpoints?, " +
+      "breakpointWidths?, breakpointRounding?) — clone a live website into a new Jx project and " +
+      "open it: pages, styles, assets, a shared layout and recurring components. The project opens " +
+      "as soon as the destination exists, so the user watches it fill up while the crawl runs. " +
+      "When the user came through the New Project Import form the destination and options are " +
+      "already settled — pass the url alone.",
+  },
   {
     name: "create_project",
     tier: "no-project",
@@ -174,6 +208,8 @@ export const AI_TOOL_TIERS: AiToolInfo[] = [
 export interface AiToolState {
   hasProject: boolean;
   hasDocument: boolean;
+  /** Whether the platform implements `importSite`. Cloud does not. */
+  canImport?: boolean;
   /**
    * The open document is an element tree the canvas is editing — `editor.kind === "canvas"`.
    *
@@ -189,6 +225,9 @@ export interface AiToolState {
  * tools need an active document (even in single-file mode without a project).
  */
 export function tierActive(tier: AiToolTier, state: AiToolState): boolean {
+  if (tier === "always") {
+    return true;
+  }
   if (tier === "no-project") {
     return !state.hasProject;
   }
@@ -201,12 +240,56 @@ export function tierActive(tier: AiToolTier, state: AiToolState): boolean {
   return state.hasDocument;
 }
 
+/**
+ * Whether a tool is active: its tier, AND any capability it declares.
+ *
+ * The one predicate the prompt's tool list and the gating registry both run, which is the whole
+ * point of {@link AI_TOOL_TIERS} — a tool the model is told about and then refused is a surprise to
+ * it, and one it is refused without being told is invisible.
+ *
+ * @param {AiToolInfo} tool
+ * @param {AiToolState} state
+ * @returns {boolean}
+ */
+export function toolActive(tool: AiToolInfo, state: AiToolState): boolean {
+  if (tool.capability === "importSite" && state.canImport === false) {
+    return false;
+  }
+  return tierActive(tool.tier, state);
+}
+
 // ─── Jx Schema Reference (condensed) ────────────────────────────────────────
 
 /**
  * Condensed reference of Jx document structure rules. Included inline in the system prompt so the
  * LLM understands the schema without consuming excessive tokens.
  */
+/**
+ * When to stop and ask, and — more importantly — when not to.
+ *
+ * Rendered into the closing section of every prompt, because `ask_user` is an `always` tier tool.
+ * The prohibitions carry most of the weight: a tool that suspends a turn on a human is only worth
+ * having if the questions are ones a human actually wants. A model that asks what it could have
+ * read, or asks about a knob its answer cannot reach, trains the author to stop reading the
+ * questions.
+ */
+const ASKING_THE_USER = `## Asking the user
+
+You can stop and ask with ask_user; the turn waits and resumes with the reply. Waiting on a person
+is not free, so ask only when all three hold:
+
+1. It is genuinely THEIR judgement — taste, priority, or intent. "Which of these pages matter?",
+ "keep their brand colours or restyle?", "is this page close enough?"
+2. You could not answer it yourself with another tool. Read the file, list the directory, look at
+ the document. Asking what you could have discovered is the commonest way to waste the question.
+3. You can ACT on any answer they give. Never ask about an option you have no way to change.
+
+Ask one question at a time. Offer options when the sensible answers are a short list; the user can
+always reply in their own words instead. If they decline, decide yourself and say what you chose.
+
+Prefer doing to asking. On a vague prompt, make a defensible choice, do the work, and say what you
+assumed — one good question beats five, and beats none only when it changes what you build.`;
+
 const JX_SCHEMA_REFERENCE = `## Jx Document Format
 
 A Jx document is a JSON object. Key top-level fields:
@@ -560,6 +643,7 @@ export function buildSystemPrompt({
   projectRoot,
   hasProject = Boolean(projectRoot),
   treeEditable = true,
+  canImport = true,
   fileInventory,
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
@@ -568,7 +652,7 @@ export function buildSystemPrompt({
   // The list the model is TOLD about and the list the gate will honour are the same filter, so a
   // Refusal is never a surprise to it.
   const toolList = AI_TOOL_TIERS.filter((t) =>
-    tierActive(t.tier, { hasDocument, hasProject, treeEditable }),
+    toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
   )
     .map((t) => `- ${t.blurb}`)
     .join("\n");
@@ -608,6 +692,8 @@ Your document edits apply to the live canvas immediately and are individually un
 
   const closing = `You have a limited number of tool-call rounds per message. On vague or open-ended prompts ("make it look better", "improve this"), prefer a small number of targeted, high-impact changes over attempting to rebuild the entire page. Explain what you changed and offer to do more.
 
+${ASKING_THE_USER}
+
 Be concise. Don't explain what Jx is unless asked. Just build.`;
 
   const sections = [`${role}\n\n${workflow}\n\n${closing}`];

package/src/services/ai-turn-signal.ts

@@ -0,0 +1,70 @@
+/**
+ * Ai-turn-signal.ts — what the agent loop knows that a tool needs and cannot be passed.
+ *
+ * `ToolRegistry.execute(name, args)` takes no signal, and its signature is fixed in the published
+ * `@jxsuite/ai`. So `runAgentLoop` could hand its signal to `streamChat` and to nothing else: a tool
+ * that ran for minutes (an import) could not be cancelled, and a tool that waits for a human
+ * (`ask_user`) would have hung on Stop forever, because the promise the loop is awaiting has no
+ * other way to learn the turn is over.
+ *
+ * An ambient slot rather than a parameter, for the same reason `services/ai-writes.ts` is one: the
+ * loop already brackets each turn with `beginTurn`/`endTurn` in a try/finally, and this rides that
+ * bracket. Only one turn runs at a time — `sendMessage` and `beginAssistantTurn` are both no-ops
+ * while streaming — so a module-level slot is the whole of the state.
+ *
+ * @license MIT
+ */
+
+let _signal: AbortSignal | undefined;
+
+/**
+ * Publish the turn's signal for the tools it will run. Called by `runAgentLoop`.
+ *
+ * @param {AbortSignal} [signal] - The turn's signal; `undefined` leaves tools uncancellable, which
+ *   is what a caller that passed no signal asked for.
+ */
+export function beginTurnSignal(signal?: AbortSignal): void {
+  _signal = signal;
+}
+
+/**
+ * The running turn's signal, or `undefined` outside a turn.
+ *
+ * A tool must treat `undefined` as "not cancellable" rather than as an error: the evals runner and
+ * several tests drive the loop with no signal at all.
+ *
+ * @returns {AbortSignal | undefined}
+ */
+export function turnSignal(): AbortSignal | undefined {
+  return _signal;
+}
+
+/** Clear the slots. Called from `runAgentLoop`'s `finally`, so it runs on every exit path. */
+export function endTurnSignal(): void {
+  _signal = undefined;
+  _toolCallId = "";
+}
+
+let _toolCallId = "";
+
+/**
+ * Publish the id of the call about to execute. Called by `runAgentLoop` per tool call.
+ *
+ * A tool that outlives its own execution — `ask_user`, whose question stays on screen until a human
+ * answers — needs the id to join what it registered to the chip the transcript is drawing. Without
+ * it a restored, permanently unanswered question is indistinguishable from the live one.
+ *
+ * @param {string} id
+ */
+export function beginToolCall(id: string): void {
+  _toolCallId = id;
+}
+
+/**
+ * The id of the tool call currently executing, or `""` outside one.
+ *
+ * @returns {string}
+ */
+export function currentToolCallId(): string {
+  return _toolCallId;
+}

package/src/services/cf-settings.ts

@@ -1,58 +1,40 @@
 /// <reference lib="dom" />
 /**
- * Cf-settings — local persistence for the Cloudflare publish connection on
- * platforms without a hosted OAuth broker (dev server, desktop). The API
- * token is stored like the AI key: localStorage first, mirrored through the
- * platform settings backend where one exists. It only ever leaves the machine
- * to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
+ * Cf-settings — the Cloudflare publish connection on platforms without a hosted OAuth broker (dev
+ * server, desktop). The API token is stored like the AI key, over `settings/kernel.ts`. It only ever
+ * leaves the machine to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
  * api.cloudflare.com (not CORS-enabled, hence the proxy).
  *
+ * As with the AI provider, a blank value is a VALUE: {@link clearCfConnection} is the deletion path,
+ * so nothing can revoke a connection by rendering an empty field into a setter.
+ *
  * @license MIT
  */
 
-import { persistSettings } from "./settings-store";
-
-const TOKEN_STORAGE = "jx.cf.token";
-const ACCOUNT_STORAGE = "jx.cf.accountId";
-
-function read(key: string): string {
-  try {
-    return globalThis.localStorage?.getItem(key) ?? "";
-  } catch {
-    return "";
-  }
-}
-
-function write(key: string, value: string): void {
-  try {
-    const trimmed = (value || "").trim();
-    if (trimmed) {
-      globalThis.localStorage?.setItem(key, trimmed);
-    } else {
-      globalThis.localStorage?.removeItem(key);
-    }
-  } catch {
-    // Storage unavailable (private mode) — the connection just won't persist.
-  }
-  persistSettings();
-}
+import { SETTINGS } from "./settings/definitions";
+import { clearSettings, readStoredSetting, setSetting } from "./settings/kernel";
 
 /** The stored Cloudflare API token, or "" when not connected. */
 export function getCfToken(): string {
-  return read(TOKEN_STORAGE);
+  return readStoredSetting(SETTINGS.cfToken);
 }
 
-/** Persist (or clear, with a blank value) the Cloudflare API token. */
+/** Persist the Cloudflare API token. Blank stores blank — see {@link clearCfConnection}. */
 export function setCfToken(token: string): void {
-  write(TOKEN_STORAGE, token);
+  setSetting(SETTINGS.cfToken, token || "");
 }
 
 /** The selected Cloudflare account id, or "" when none chosen yet. */
 export function getCfAccountId(): string {
-  return read(ACCOUNT_STORAGE);
+  return readStoredSetting(SETTINGS.cfAccountId);
 }
 
-/** Persist (or clear) the selected Cloudflare account id. */
+/** Persist the selected Cloudflare account id. Blank stores blank. */
 export function setCfAccountId(accountId: string): void {
-  write(ACCOUNT_STORAGE, accountId);
+  setSetting(SETTINGS.cfAccountId, accountId || "");
+}
+
+/** Forget the connection — token and account together. What Disconnect calls. */
+export function clearCfConnection(): void {
+  clearSettings([SETTINGS.cfToken, SETTINGS.cfAccountId]);
 }

package/src/services/connection.ts

@@ -0,0 +1,74 @@
+/**
+ * The backend connection, said out loud.
+ *
+ * Only one launcher can lose a backend mid-session: the chromium desktop shell holds a single
+ * long-lived WebSocket to its project server. When that socket died, every later call returned a
+ * promise that NEVER SETTLED — `WebSocket.send()` on a closed socket discards the frame instead of
+ * throwing, so nothing rejected, nothing resolved, and the visible symptom was **Open Project**
+ * doing nothing at all. No toast, no log, no failed state. Restarting Studio was the only
+ * recovery.
+ *
+ * The transport now rejects those calls, and this is the other half: a person needs to be told
+ * which of "it is broken" and "it is coming back" they are in. One keyed problem so a flapping
+ * connection cannot stack up a column of identical rows, dismissed on recovery so a fixed thing
+ * does not stay on the Problems list (§16.1's third tier, and §16.6's rule that a record is retired
+ * by whoever owns its life).
+ *
+ * A platform without `subscribeConnection` — the dev server, electrobun — installs nothing. There
+ * is no connection to lose there, and a notice about one would be a lie.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { getPlatform } from "../platform";
+import { dismiss, notify } from "./notify";
+import type { Notification } from "./notify";
+
+/** One key for every connection notice, so a flapping socket replaces rather than accumulates. */
+const CONNECTION_KEY = "platform:connection";
+
+/** The outstanding "we are disconnected" record, so recovery can retire it. */
+let outstanding: Notification | null = null;
+
+/**
+ * Start reporting the backend connection. Returns an unsubscribe, or null on a platform that has no
+ * connection to report.
+ *
+ * @returns {(() => void) | null}
+ */
+export function watchConnection(): (() => void) | null {
+  const subscribe = getPlatform().subscribeConnection;
+  if (!subscribe) {
+    return null;
+  }
+  const unsubscribe = subscribe(({ online, reason }) => {
+    if (online) {
+      if (outstanding) {
+        dismiss(outstanding.id);
+        outstanding = null;
+        notify.success("Reconnected to the Jx backend.", { source: "Backend" });
+      }
+      return;
+    }
+    /* Already reported. A reconnect attempt failing is the same state, not a new one. */
+    if (outstanding) {
+      return;
+    }
+    outstanding = notify.error(reason ?? "Lost connection to the Jx backend.", {
+      detail:
+        "Editing continues, but anything that reads or writes files will fail until it comes " +
+        "back. Studio is retrying.",
+      key: CONNECTION_KEY,
+      source: "Backend",
+    });
+  });
+  /* Unsubscribing retires the notice with it: the watcher is the only thing that would ever have
+     dismissed it, so leaving it on the Problems list would leave a report nobody can clear. */
+  return () => {
+    unsubscribe();
+    if (outstanding) {
+      dismiss(outstanding.id);
+      outstanding = null;
+    }
+  };
+}