@jxsuite/studio 3.0.0 → 4.0.0

package/src/panels/toolbar.ts

@@ -41,12 +41,13 @@ import { openQuickSearch } from "./quick-search";
 import { showPromptDialog } from "../ui/layers";
 import { getPlatform, hasPlatform } from "../platform";
 import { getPreviewNavigateHandler } from "../canvas/preview-navigate";
+import { armPreviewOverlay, flushPreviewOverlay } from "../preview/preview-overlay";
 import { documentUrlPattern, dynamicRouteParams } from "../page-params";
 import { getNodeAtPath, nodeLabel, projectState } from "../store";
 import { activeRegistry } from "../commands/active-registry";
 import { notify } from "../services/notify";
 import type { Tab } from "../tabs/tab";
-import type { SiteBuildResult } from "../types";
+import type { SiteBuildResult, SitePreviewResult, StudioPlatform } from "../types";
 import type { CommandRegistry } from "../commands/registry";
 import type { EffectScope } from "@vue/reactivity";
 import type { TemplateResult } from "lit-html";
@@ -253,27 +254,96 @@ export async function runOpenInBrowser() {
     notify.warn(target.reason, { key: OPEN_IN_BROWSER, source: "Preview" });
     return;
   }
-  /* Build first, because the reader is about to see the OUTPUT and the author is looking at the
-     DOCUMENT. Without this they differ by however long it has been since anyone ran a build —
-     which for most projects is "always", since nothing in Studio had ever written the output at
-     all. A preview that quietly shows last week's page is worse than one that says it cannot open.
-
-     The build is also what NAMES the origin. The built site is served on a port of its own, because
-     the editor's own paths mean the project's sources while a built page means its output by the
-     same paths — so a backend that cannot build cannot preview either, and says so instead of
-     sending the reader to an address where half the site is the wrong file. */
   const platform = hasPlatform() ? getPlatform() : null;
-  if (!platform?.buildSite) {
-    notify.warn("This backend cannot build a preview of the site.", {
+  if (!platform?.previewSite && !platform?.buildSite) {
+    notify.warn("This backend cannot preview the site.", {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  /* A LIVE preview is what this action is for, and a build is the fallback for a backend that
+     cannot do one. The two answer different questions: "what does this page look like at its real
+     URL?" wants the tree as it stands, and "does my site build?" is `Build Site`. */
+  if (platform.previewSite) {
+    await runLivePreview(platform.previewSite, target.path);
+    return;
+  }
+  await runBuiltPreview(platform.buildSite!, target.path);
+}
+
+/**
+ * Preview the working tree, and open a tab only if one is not already showing this project.
+ *
+ * The overlay is flushed FIRST, and that ordering is the whole point: the page the author is about
+ * to look at should carry the keystroke they just typed, not the one before the debounce.
+ */
+async function runLivePreview(
+  previewSite: NonNullable<StudioPlatform["previewSite"]>,
+  path: string,
+) {
+  armPreviewOverlay();
+  await flushPreviewOverlay();
+  notify.info("Opening a live preview…", { key: OPEN_IN_BROWSER, source: "Preview" });
+  let result: SitePreviewResult;
+  try {
+    result = await previewSite({ route: path });
+  } catch (error) {
+    notify.error(`The site could not be previewed: ${errorText(error)}`, {
       key: OPEN_IN_BROWSER,
       source: "Preview",
     });
     return;
   }
+  if (!result.url) {
+    notify.warn("This backend serves no preview of the site.", {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  /* `reused` is honoured, and honouring it is the feature. A tab already holding this project's
+     preview has been pointed at the route; opening another would leave the author with two tabs on
+     one project, which is exactly what retargeting the first one exists to prevent. What it costs
+     is that the browser does not come forward — no page can raise a background tab, and handing the
+     URL to the OS again would open a duplicate rather than switch to it — so the notification says
+     where to look. A reader who CLOSED their tab is not stuck here: the stream closes with it, so
+     `reused` comes back false and a fresh tab opens without anyone having to ask. */
+  if (result.reused) {
+    notify.info(`Updated your preview tab — switch to your browser to see ${path}`, {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+    return;
+  }
+
+  if (result.errors.length > 0) {
+    notify.warn(`Previewed with ${result.errors.length} problem(s): ${result.errors[0]}`, {
+      key: OPEN_IN_BROWSER,
+      source: "Preview",
+    });
+  } else {
+    notify.success(
+      `Opened a live preview of ${result.routes} page(s) — rendered from your working tree, not a build.`,
+      { key: OPEN_IN_BROWSER, source: "Preview" },
+    );
+  }
+  openUrlExternally(`${result.url}${path}`);
+}
+
+/**
+ * The compiler-backed path, for a backend that declares no live preview.
+ *
+ * Kept so nothing regresses on a backend that predates `previewSite`: the cloud adapter answers
+ * `buildSite` with `mode: "live"` of its own, and `jx dev` answers it with a real build.
+ */
+async function runBuiltPreview(buildSite: NonNullable<StudioPlatform["buildSite"]>, path: string) {
   notify.info("Building the site…", { key: OPEN_IN_BROWSER, source: "Preview" });
   let result: SiteBuildResult;
   try {
-    result = await platform.buildSite();
+    result = await buildSite();
   } catch (error) {
     notify.error(`The site could not be built: ${errorText(error)}`, {
       key: OPEN_IN_BROWSER,
@@ -288,20 +358,70 @@ export async function runOpenInBrowser() {
     });
     return;
   }
+  /* A live preview is not a build and the report must not say it was: what it renders is the
+     working tree, unsaved edits and all, assembled in the reader's browser rather than compiled. */
+  const live = result.mode === "live";
   if (result.errors.length > 0) {
     /* Named, and the page still opens. A partial build produced pages, and the author can see the
        one they asked for while reading what failed — which is the whole difference between a
        preview and a build log. */
-    notify.warn(`The site built with ${result.errors.length} error(s): ${result.errors[0]}`, {
+    const verb = live ? "previewed" : "built";
+    notify.warn(`The site ${verb} with ${result.errors.length} error(s): ${result.errors[0]}`, {
       key: OPEN_IN_BROWSER,
       source: "Preview",
     });
+  } else if (live) {
+    notify.success(
+      `Opened a live preview of ${result.routes} page(s) — rendered from your working tree, not a build.`,
+      { key: OPEN_IN_BROWSER, source: "Preview" },
+    );
   } else {
     notify.success(`Built ${result.routes} page(s).`, { key: OPEN_IN_BROWSER, source: "Preview" });
   }
-  openUrlExternally(`${result.url}${target.path}`);
+  openUrlExternally(`${result.url}${path}`);
+}
+
+/**
+ * Run `Build Site`, the compiler-backed answer to "does my site build?".
+ *
+ * `View: Open in Browser` stopped meaning this when it started previewing the working tree, and the
+ * question did not stop being worth asking: a build runs the bundler, the image pipeline and every
+ * emitter, and a live preview runs none of them. So it keeps its own verb, its own report, and the
+ * output origin it always opened.
+ */
+export async function runBuildSite() {
+  const platform = hasPlatform() ? getPlatform() : null;
+  if (!platform?.buildSite) {
+    notify.warn("This backend cannot build the site.", { key: BUILD_SITE, source: "Build" });
+    return;
+  }
+  notify.info("Building the site…", { key: BUILD_SITE, source: "Build" });
+  let result: SiteBuildResult;
+  try {
+    result = await platform.buildSite();
+  } catch (error) {
+    notify.error(`The site could not be built: ${errorText(error)}`, {
+      key: BUILD_SITE,
+      source: "Build",
+    });
+    return;
+  }
+  if (result.errors.length > 0) {
+    notify.warn(`Built with ${result.errors.length} error(s): ${result.errors[0]}`, {
+      key: BUILD_SITE,
+      source: "Build",
+    });
+    return;
+  }
+  notify.success(`Built ${result.routes} page(s), ${result.files} file(s).`, {
+    key: BUILD_SITE,
+    source: "Build",
+  });
 }
 
+/** One notification key for the build, kept apart so a build report never replaces a preview's. */
+const BUILD_SITE = "project.buildSite";
+
 /** One notification key for the whole flow, so building → built → failed replaces rather than piles. */
 const OPEN_IN_BROWSER = "view.openInBrowser";
 

package/src/platforms/cloud.ts

@@ -28,6 +28,7 @@ import type {
   GitStatusResult,
   PackageInfo,
   ProjectListEntry,
+  SiteBuildResult,
   ProjectSchemasResponse,
   ReferencesResult,
   RenameResult,
@@ -765,6 +766,25 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       // The GitHub repo IS the remote; nothing to add.
     },
 
+    /**
+     * Open in Browser, cloud edition — a LIVE preview rather than a build.
+     *
+     * The backend cannot run `jx build`: it never executes project JS, and the compiler needs
+     * `sharp`, a bundler and a filesystem, none of which exist in a Worker. What it can do is serve
+     * the working tree as a real site on an origin of its own, rendering each page with the same
+     * runtime the canvas uses — so the reply names `mode: "live"` and Studio says so, instead of
+     * letting a reader assume they are looking at build output.
+     *
+     * That it is not a build is also the best thing about it: the preview is the tree as it stands,
+     * including edits nobody has saved and edits another collaborator is making right now.
+     */
+    async buildSite() {
+      return okJson<SiteBuildResult>(
+        await api("/build", { method: "POST" }),
+        "The site could not be previewed.",
+      );
+    },
+
     // ─── Project catalogue & navigation (Studio welcome / New Project UI) ──
 
     async listProjects(): Promise<ProjectListEntry[]> {

package/src/platforms/devserver.ts

@@ -28,6 +28,7 @@ import type {
   ExtensionsInfo,
   FsEvent,
   ImportProgressEvent,
+  ImportReadyEvent,
   ImportSiteOptions,
   ProjectSchemasResponse,
   ReferencesResult,
@@ -35,6 +36,7 @@ import type {
   SecretsSetRequest,
   SecretsSetResponse,
   SiteBuildResult,
+  SitePreviewResult,
   StarterInfo,
 } from "../types";
 import { problemDetail, problemMessage } from "@jxsuite/protocol";
@@ -62,11 +64,26 @@ interface SiteEntry {
  *
  * The adapter is stateless apart from `_projectRoot`, which tracks the server-relative project
  * directory (e.g. "examples/site-demo"). All paths passed INTO PAL methods are project-relative;
- * the adapter prefixes them with `_projectRoot` before hitting the server, and strips the prefix
- * from responses.
+ * the adapter prefixes them with `_projectRoot` before hitting the server.
+ *
+ * **Coming back, the space depends on the route, and the routes do not all agree** (the contract is
+ * `specs/server.md` §4.1). `/__studio/files` echoes what it was asked — server-root-relative — so
+ * its replies are stripped. The refactor routes (`file/rename`, `references`) answer in the ACTIVE
+ * PROJECT's space, because that is the space their sweep runs in, so their replies are returned
+ * untouched. Stripping one of those is not a harmless no-op: it would eat the first segment of any
+ * path that begins with the project root's own name.
  */
 export function createDevServerPlatform() {
   let _projectRoot = "";
+  /**
+   * The in-flight `activate()` for the current root, so a query whose answer depends on the
+   * server's project binding can await it.
+   *
+   * `set projectRoot` fires activation fire-and-forget, and `/__studio/references` is the one route
+   * with no `dir` parameter — its sweep root comes solely from the server's activated project. A
+   * query landing inside that window would sweep the server's own root instead (issue 239).
+   */
+  let _activation: Promise<unknown> | null = null;
   /**
    * Lazy /__studio/collab capability probe (null = not asked yet). Its result is the subprotocol
    * negotiation, not a boolean: the probe is the only place the client can learn what envelope the
@@ -126,7 +143,7 @@ export function createDevServerPlatform() {
         // Fire-and-forget: callers that need the binding in place before reading await activate()
         // Themselves. The rejection is reported rather than dropped — an unactivated root leaves
         // Every rootless endpoint (git especially) operating on the server's OWN root.
-        void this.activate(_projectRoot).catch((error: unknown) => {
+        _activation = this.activate(_projectRoot).catch((error: unknown) => {
           console.error("Project activation failed:", error);
         });
       }
@@ -335,8 +352,9 @@ export function createDevServerPlatform() {
       opts: ImportSiteOptions,
       onProgress: (evt: ImportProgressEvent) => void,
       signal?: AbortSignal,
+      onReady?: (evt: ImportReadyEvent) => void,
     ) {
-      return await streamImport("/__studio/import-site", opts, onProgress, signal);
+      return await streamImport("/__studio/import-site", opts, onProgress, signal, onReady);
     },
 
     // ─── File operations ──────────────────────────────────────────────────
@@ -421,21 +439,11 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Failed to rename: ${from} → ${to}`);
       }
-      const report = await readJson<RenameResult>(res);
-      // Map server-root-relative report paths back to project-relative for the studio.
-      if (typeof report.from === "string") {
-        report.from = stripRoot(report.from);
-      }
-      if (typeof report.to === "string") {
-        report.to = stripRoot(report.to);
-      }
-      for (const f of report.references?.files ?? []) {
-        f.path = stripRoot(f.path);
-      }
-      for (const e of report.errors ?? []) {
-        e.path = stripRoot(e.path);
-      }
-      return report;
+      /* No strip on the way back: the route takes its paths in server space and answers in the
+         project's (specs/server.md §4.1). Stripping an already-project-relative path is not merely
+         redundant — it corrupts any path whose first segment happens to match the project root's
+         own name, which a server-root-relative root makes reachable. */
+      return readJson<RenameResult>(res);
     },
 
     /**
@@ -446,6 +454,7 @@ export function createDevServerPlatform() {
      * @param {{ path?: string; tagName?: string }} target
      */
     async findReferences(target: { path?: string; tagName?: string }): Promise<ReferencesResult> {
+      await _activation;
       const params = new URLSearchParams();
       if (target.path) {
         params.set("path", serverPath(target.path));
@@ -457,18 +466,8 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Failed to find references: ${target.path ?? target.tagName ?? ""}`);
       }
-      const result = await readJson<ReferencesResult>(res);
-      // Server-root-relative report paths → project-relative, as renameFile already does.
-      if (typeof result.path === "string") {
-        result.path = stripRoot(result.path);
-      }
-      for (const f of result.files ?? []) {
-        f.path = stripRoot(f.path);
-      }
-      for (const e of result.errors ?? []) {
-        e.path = stripRoot(e.path);
-      }
-      return result;
+      // Project-relative on the way out, exactly as `renameFile` above receives it.
+      return readJson<ReferencesResult>(res);
     },
 
     /**
@@ -627,8 +626,8 @@ export function createDevServerPlatform() {
       return Boolean(data.needsInstall);
     },
 
-    async outdatedPackages() {
-      const res = await fetch("/__studio/packages/outdated");
+    async packageVersions() {
+      const res = await fetch("/__studio/packages/versions");
       if (!res.ok) {
         return [];
       }
@@ -1149,6 +1148,41 @@ export function createDevServerPlatform() {
       return (await res.json()) as SiteBuildResult;
     },
 
+    /**
+     * Preview the working tree live, and point this project's open tab at a route.
+     *
+     * The dev server holds the same live origin the desktop launchers do, so the browser Studio
+     * gets the same preview: composed on demand, unsaved edits included.
+     */
+    async previewSite(opts: { route: string }) {
+      const res = await fetch("/__studio/preview", {
+        body: JSON.stringify(opts),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+      if (!res.ok) {
+        const body = await readJson<ErrorBody>(res);
+        throw new Error(problemDetail(body) ?? "The site could not be previewed.");
+      }
+      return (await res.json()) as SitePreviewResult;
+    },
+
+    async setPreviewOverlay(path: string, contents: string) {
+      await fetch("/__studio/preview/overlay", {
+        body: JSON.stringify({ contents, path }),
+        headers: { "Content-Type": "application/json" },
+        method: "POST",
+      });
+    },
+
+    async clearPreviewOverlay(path?: string) {
+      await fetch("/__studio/preview/overlay", {
+        body: JSON.stringify(path === undefined ? {} : { path }),
+        headers: { "Content-Type": "application/json" },
+        method: "DELETE",
+      });
+    },
+
     /**
      * @param {string} name
      * @param {string} url

package/src/preview/preview-overlay.ts

@@ -0,0 +1,226 @@
+/**
+ * Publishing what the author is looking at, so a live preview shows the canvas and not the disk.
+ *
+ * A live preview composes a page from the project's working TREE, and the tree is what has been
+ * saved. The document the author is actually editing lives in a tab's reactive memory and nowhere
+ * else, so without this the one thing that makes a live preview worth having — seeing an edit
+ * before it is written — would be exactly the thing it could not show.
+ *
+ * What travels is BYTES, and specifically {@link serializeDocument}'s: the same function `saveFile`
+ * writes through, grid controllers, format round-trips, frontmatter and all. That is what makes
+ * "what the reader sees" and "what saving would produce" one answer rather than two that drift. A
+ * document object would bypass the format layer, and a `.md` page's bytes are not
+ * `JSON.stringify(doc)`.
+ *
+ * **Why an effect and not `transactDoc`.** `transact.ts` has exactly one observer slot and the
+ * collab layer owns it. More importantly a transaction hook would MISS three of the most common
+ * ways a document changes: a Monaco source commit, a content-entry field edit, and every grid edit
+ * route around `transactDoc` entirely. "I edited it in Source and the preview did not change" is
+ * the bug this shape avoids.
+ *
+ * **Why one effect over the whole tab set rather than one per tab.** Reading the map tracks
+ * additions, so a tab opened later needs no registration and a tab closed needs no teardown. And
+ * the publish is a DIFF against what was last published, which means save, close, discard and undo
+ * back to clean all resolve through the same line instead of four hooks that can each be
+ * forgotten.
+ *
+ * **Armed, not always on.** Serializing dirty documents on every edit is not free, and before the
+ * author has ever opened a preview there is nothing to publish to. Nothing happens until a preview
+ * origin exists.
+ *
+ * @docs studio/interface
+ */
+
+import { effect, effectScope } from "../reactivity";
+import { getPlatform, hasPlatform } from "../platform";
+import { serializeDocument } from "../files/serialize-document";
+import { workspace } from "../workspace/workspace";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * Trailing debounce on a publish.
+ *
+ * No leading edge: a leading publish would send the first keystroke of a burst and the last, which
+ * is two reloads for one thought. The max wait is what keeps a continuous drag from starving the
+ * trailing timer forever.
+ */
+const PUBLISH_DEBOUNCE_MS = 200;
+const PUBLISH_MAX_WAIT_MS = 500;
+
+/** Bytes one document may publish before it is left showing its saved state instead. */
+const MAX_ENTRY_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Path to the bytes last published for it, so identical bytes cost nothing.
+ *
+ * The TEXT rather than a digest of it. An edit that lands back on the same bytes — a character
+ * typed and deleted — must not cost the reader a reload, and comparing what was sent is exact where
+ * a hash would be a collision away from being wrong for no saving anyone can measure. Memory is
+ * bounded by the same per-entry cap the publish is.
+ */
+const published = new Map<string, string>();
+
+let armed = false;
+let scope: ReturnType<typeof effectScope> | null = null;
+let timer: ReturnType<typeof setTimeout> | null = null;
+let burstStartedAt: number | null = null;
+/** The publish in flight, so a flush awaits it rather than racing it. */
+let inFlight: Promise<void> | null = null;
+
+/** The documents whose unsaved bytes a preview needs, in the order they were opened. */
+function dirtyTabs(): Tab[] {
+  const tabs: Tab[] = [];
+  for (const tab of workspace.tabs.values()) {
+    /* Dirty only. A clean tab's bytes are on disk by definition, and publishing them would create
+       a second source of truth for identical content. */
+    if (tab.doc.dirty && tab.documentPath) {
+      tabs.push(tab);
+    }
+  }
+  return tabs;
+}
+
+/**
+ * Publish what changed and retract what no longer applies.
+ *
+ * A diff rather than a stream of events: whatever reason a document has for no longer being unsaved
+ * — saved, closed, discarded, undone back to its file — it is simply absent from this pass, and the
+ * retraction follows without anywhere else having to remember to ask for it.
+ */
+async function publish(): Promise<void> {
+  /* Not `armed` too: `flushPreviewOverlay` refuses when disarmed and `disarmPreviewOverlay` clears
+     the pending timer, so there is no path into here without it. A host with no platform at all is
+     real though — `getPlatform()` throws rather than answering null. */
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.setPreviewOverlay || !platform.clearPreviewOverlay) {
+    return;
+  }
+  const live = new Set<string>();
+  for (const tab of dirtyTabs()) {
+    const path = tab.documentPath!.replace(/^\.\//, "");
+    let text: string;
+    try {
+      text = await serializeDocument(tab);
+    } catch {
+      /* A half-typed document that will not serialize is not a reason to stop previewing the layout
+         beside it. Skipped, and the next edit that does serialize publishes it. */
+      continue;
+    }
+    if (text.length > MAX_ENTRY_BYTES) {
+      continue;
+    }
+    live.add(path);
+    if (published.get(path) === text) {
+      continue;
+    }
+    published.set(path, text);
+    await platform.setPreviewOverlay(path, text);
+  }
+  for (const path of published.keys()) {
+    if (!live.has(path)) {
+      published.delete(path);
+      await platform.clearPreviewOverlay(path);
+    }
+  }
+}
+
+/** Run a publish, coalescing with any already scheduled. */
+function schedule(): void {
+  if (!armed) {
+    return;
+  }
+  const now = Date.now();
+  burstStartedAt ??= now;
+  if (timer) {
+    clearTimeout(timer);
+  }
+  const waited = now - burstStartedAt;
+  const delay = Math.max(0, Math.min(PUBLISH_DEBOUNCE_MS, PUBLISH_MAX_WAIT_MS - waited));
+  timer = setTimeout(() => {
+    timer = null;
+    burstStartedAt = null;
+    inFlight = publish().finally(() => {
+      inFlight = null;
+    });
+  }, delay);
+}
+
+/**
+ * Note an edit the reactive effect cannot see.
+ *
+ * `transactDoc` replaces the document's ROOT REFERENCE on every transaction, and a Monaco source
+ * commit assigns a fresh one, so a shallow read catches both. A content-entry field edit writes a
+ * key in place on an already-dirty tab, which changes nothing the effect reads. This is the seam
+ * for exactly that: an explicit call from the few places that mutate without swapping.
+ */
+export function notePreviewOverlayEdit(): void {
+  schedule();
+}
+
+/**
+ * Start publishing, because a preview origin now exists to publish to.
+ *
+ * Idempotent: `View: Open in Browser` calls it on every invocation and only the first does work.
+ */
+export function armPreviewOverlay(): void {
+  if (armed) {
+    return;
+  }
+  armed = true;
+  scope = effectScope();
+  scope.run(() => {
+    effect(() => {
+      for (const tab of workspace.tabs.values()) {
+        /* Two reads, both shallow. `document` is a fresh reference on every transaction — see
+           `transactDoc`, which assigns one specifically so effects re-run — so this costs a
+           property read rather than a walk of the document. */
+        void tab.doc.dirty;
+        void tab.doc.document;
+      }
+      schedule();
+    });
+  });
+}
+
+/**
+ * Stop publishing and forget what was published, without retracting it.
+ *
+ * Called when the window changes project. The published map is keyed by project-relative path, so
+ * carrying it across a switch would let one project's `pages/index.json` be read as the answer for
+ * another's — and the backend lets go of the old root's overlay on its own re-root anyway.
+ */
+export function disarmPreviewOverlay(): void {
+  armed = false;
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  burstStartedAt = null;
+  scope?.stop();
+  scope = null;
+  published.clear();
+}
+
+/**
+ * Publish now and wait for it.
+ *
+ * Two callers, and both are moments where the debounce is exactly wrong: on the way to opening a
+ * browser tab, so the page the author is about to look at already carries their last keystroke; and
+ * after a save, so the retraction rides with the write instead of arriving a debounce later and
+ * costing a second reload.
+ */
+export async function flushPreviewOverlay(): Promise<void> {
+  if (!armed) {
+    return;
+  }
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+    burstStartedAt = null;
+  }
+  await inFlight;
+  await publish();
+}