@design.estate/wcctools 6.1.0 → 7.0.0

package/ts/plugins.ts

@@ -2,10 +2,11 @@
 import * as childProcess from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as fsSync from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import * as url from 'node:url';
 
-export { childProcess, fs, fsSync, path, url };
+export { childProcess, fs, fsSync, os, path, url };
 
 // @api.global scope
 import * as typedrequest from '@api.global/typedrequest';
@@ -13,17 +14,23 @@ import * as typedserver from '@api.global/typedserver';
 
 export { typedrequest, typedserver };
 
+// @design.estate scope
+import * as deesDomtools from '@design.estate/dees-domtools';
+
+export { deesDomtools };
+
 // @git.zone scope
 import * as tswatch from '@git.zone/tswatch';
 
 export { tswatch };
 
 // @push.rocks scope
+import * as smartbrowser from '@push.rocks/smartbrowser/automation';
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as smartconsole from '@push.rocks/smartconsole';
 import * as smartexit from '@push.rocks/smartexit';
 
-export { smartconfig, smartconsole, smartexit };
+export { smartbrowser, smartconfig, smartconsole, smartexit };
 
 // third party scope
 import typescript from 'typescript';

package/ts_interfaces/bridge.ts

@@ -0,0 +1,95 @@
+import type { IWccCatalogManifest } from './catalog.js';
+
+/**
+ * The bridge between the shell and the preview document. The preview runtime installs it as
+ * `window.wccPreview` in the preview document; the shell reaches it through the same-origin
+ * iframe. Every argument and result is plain, structured-cloneable data: values never carry
+ * objects of the other document's realm.
+ */
+
+export type TWccTheme = 'dark' | 'bright';
+
+/** One demo (or page) of the catalog. */
+export interface IWccSelection {
+  sectionName: string;
+  itemName: string;
+  /** 0-based; always 0 for a page. */
+  demoIndex: number;
+}
+
+/** What the preview shows instead of a demo. */
+export interface IWccEmptyState {
+  title: string;
+  detail: string;
+}
+
+export type TWccEmptyReason =
+  | 'nothing-selected'
+  | 'no-demo'
+  | 'ignored'
+  | 'missing'
+  | 'no-such-demo'
+  | 'failed';
+
+export type TWccRenderOutcome =
+  | { kind: 'rendered'; type: 'element' | 'page' }
+  | { kind: 'empty'; reason: TWccEmptyReason; emptyState: IWccEmptyState };
+
+export type TWccPropertyKind = 'String' | 'Number' | 'Boolean' | 'Enum' | 'Object' | 'Array';
+
+/** A scalar property value the properties panel can show and set directly. */
+export type TWccPropertyScalar = string | number | boolean | null;
+
+export interface IWccPropertyDescriptor {
+  name: string;
+  kind: TWccPropertyKind;
+  /** The values of an `Enum` property. */
+  enumValues?: string[];
+  /** The current value of a String, Number, Boolean or Enum property. */
+  value?: TWccPropertyScalar;
+  /** The current value of an Object or Array property, as formatted JSON. */
+  json?: string;
+}
+
+export type TWccPropertyListing =
+  | { kind: 'properties'; elementName: string; properties: IWccPropertyDescriptor[] }
+  | { kind: 'unavailable'; reason: string };
+
+export type TWccPropertyEditResult = { ok: true } | { ok: false; error: string };
+
+export interface IWccRenderedEvent {
+  type: 'rendered';
+  selection: IWccSelection | null;
+  outcome: TWccRenderOutcome;
+}
+
+export type TWccPreviewEvent = IWccRenderedEvent;
+
+export interface IWccPreviewBridge {
+  getManifest(): IWccCatalogManifest;
+  /** The selection rendered last, or null before the first render. */
+  getSelection(): IWccSelection | null;
+  getTheme(): TWccTheme;
+  /** Render a demo or page into the preview document, without reloading it. */
+  render(selectionArg: IWccSelection): Promise<TWccRenderOutcome>;
+  setTheme(themeArg: TWccTheme): Promise<void>;
+  /** The editable properties of the selected element's rendered instance, once it has rendered. */
+  getProperties(): Promise<TWccPropertyListing>;
+  setProperty(nameArg: string, valueArg: TWccPropertyScalar): TWccPropertyEditResult;
+  /** Parse JSON in the preview document and assign it to an Object or Array property. */
+  setPropertyJson(nameArg: string, jsonArg: string): TWccPropertyEditResult;
+  /** The rendered instance of the selected element, for same-origin tooling. */
+  findRenderedInstance(): HTMLElement | null;
+  subscribe(listenerArg: (eventArg: TWccPreviewEvent) => void): () => void;
+}
+
+/** The message a preview document posts to its parent once its bridge is installed. */
+export interface IWccPreviewReadyMessage {
+  type: 'wcctools-preview-ready';
+}
+
+declare global {
+  interface Window {
+    wccPreview?: IWccPreviewBridge;
+  }
+}

package/ts_interfaces/capture.ts

@@ -0,0 +1,144 @@
+import type { IWccSelection, TWccTheme } from './bridge.js';
+
+/**
+ * Captures of the catalog's demos: screenshots and interaction frames the `wcctools dev` server
+ * takes in a headless browser, and frames the shell samples from a recording.
+ */
+
+/** The named capture widths: the dees-domtools breakpoints. */
+export type TWccCaptureViewportPreset = 'phone' | 'phablet' | 'tablet' | 'desktop';
+
+/** A named capture width, or a width in CSS pixels. */
+export type TWccCaptureViewport = TWccCaptureViewportPreset | number;
+
+/**
+ * What a capture shows:
+ * - `element`: the rendered instance of the selected element (the first one its demo renders),
+ * - `viewport`: the visible preview at the capture's width and height,
+ * - `fullpage`: the whole preview document.
+ */
+export type TWccCaptureFraming = 'element' | 'viewport' | 'fullpage';
+
+export type TWccImageMimeType = 'image/png' | 'image/jpeg';
+
+/** An encoded image. */
+export interface IWccImage {
+  mimeType: TWccImageMimeType;
+  /** Width in device pixels. */
+  width: number;
+  /** Height in device pixels. */
+  height: number;
+  dataBase64: string;
+}
+
+/** A frame of a recording or of an observed interaction. */
+export interface IWccTimedFrame extends IWccImage {
+  /** Milliseconds since the start of the recording or observation. */
+  timestampMs: number;
+}
+
+/**
+ * The catalog entry a capture renders. `itemName` is an entry's name or its element's tag;
+ * without `sectionName` it must name exactly one entry across all sections.
+ */
+export interface IWccCaptureSubject {
+  sectionName?: string;
+  itemName: string;
+  /** 0-based demo index; default 0. */
+  demoIndex?: number;
+}
+
+/** How the headless preview is set up for a capture. */
+export interface IWccCaptureView {
+  /** Default `desktop`. */
+  viewport?: TWccCaptureViewport;
+  /** Height of the preview window in CSS pixels; default 800. */
+  height?: number;
+  /** Default `dark`. */
+  theme?: TWccTheme;
+  /** Device pixel ratio, 1 or 2; default 1. */
+  scale?: 1 | 2;
+}
+
+export interface IWccScreenshotRequest extends IWccCaptureView {
+  subject: IWccCaptureSubject;
+  /** Default `element` for element demos and `fullpage` for pages. */
+  framing?: TWccCaptureFraming;
+  /** Default `png`. */
+  format?: 'png' | 'jpeg';
+  /** JPEG quality from 1 to 100; default 80. */
+  quality?: number;
+}
+
+export interface IWccScreenshotResult {
+  /** The demo the subject resolved to. */
+  selection: IWccSelection;
+  framing: TWccCaptureFraming;
+  image: IWccImage;
+  /** True when a full-page capture was cut at the maximum height. */
+  truncated: boolean;
+}
+
+/**
+ * One step of a scripted interaction. A selector is a CSS selector matched in the preview
+ * document and in every open shadow root below it; the first match in document order is used,
+ * once it is visible and enabled.
+ */
+export type TWccInteractionStep =
+  | { action: 'click'; selector: string }
+  | { action: 'hover'; selector: string }
+  /** Replaces the value of an input, textarea, select or contenteditable element. */
+  | { action: 'fill'; selector: string; text: string }
+  /** Presses a key (`Enter`, `Tab`, `a`, …), on the matched element when a selector is given. */
+  | { action: 'press'; key: string; selector?: string }
+  /** Waits until a match is visible, or until none is (`hidden`). */
+  | { action: 'waitFor'; selector: string; state?: 'visible' | 'hidden' }
+  /** Observes for a fixed time, for example an animation. */
+  | { action: 'wait'; ms: number };
+
+export interface IWccInteractionRequest extends IWccCaptureView {
+  subject: IWccCaptureSubject;
+  steps: TWccInteractionStep[];
+  /** How long to keep observing after the last step, in milliseconds; default 500. */
+  observeMs?: number;
+  /** The most frames to return, spread over the observation; default 12. */
+  maxFrames?: number;
+  /** JPEG quality of the frames from 1 to 100; default 70. */
+  frameQuality?: number;
+  /** Also take a screenshot once the steps ran, framed as a screenshot request would be. */
+  finalScreenshot?: { framing?: TWccCaptureFraming; format?: 'png' | 'jpeg'; quality?: number };
+}
+
+export interface IWccInteractionStepResult {
+  index: number;
+  ok: boolean;
+  /** Why the step failed; the steps after a failed one do not run. */
+  error?: string;
+  /** Milliseconds since the start of the observation. */
+  startMs: number;
+  endMs: number;
+}
+
+export interface IWccInteractionResult {
+  selection: IWccSelection;
+  /** Viewport frames in time order, timestamped from the start of the observation. */
+  frames: IWccTimedFrame[];
+  steps: IWccInteractionStepResult[];
+  /** True when every step ran. */
+  completed: boolean;
+  finalImage?: IWccImage;
+}
+
+/** How frames are sampled from a recording. */
+export interface IWccFrameSamplingOptions {
+  /** Number of frames, spread evenly over the range; default 8, at most 32. */
+  count?: number;
+  /** Start of the range in seconds; default the start of the recording. */
+  startS?: number;
+  /** End of the range in seconds; default the end of the recording. */
+  endS?: number;
+  /** Frames wider than this are scaled down; default 960. */
+  maxWidth?: number;
+  /** JPEG quality from 0 to 1; default 0.8. */
+  quality?: number;
+}

package/ts_interfaces/catalog.ts

@@ -0,0 +1,37 @@
+/**
+ * The data-only description of a catalog that the preview runtime hands to the shell.
+ * Element classes and template factories stay in the preview document.
+ */
+
+/** How the entries of a section are rendered: element demos or page factories. */
+export type TWccSectionType = 'elements' | 'pages';
+
+/** A navigable catalog entry. */
+export interface IWccManifestEntry {
+  name: string;
+  /** The registered tag of an element; null for pages and unregistered element classes. */
+  tagName: string | null;
+  /** Number of demos (always 1 for a page). */
+  demoCount: number;
+  demoGroups: string[];
+}
+
+/** A registered element without a usable demo; listed, never navigable. */
+export interface IWccManifestEntryWithoutDemo {
+  name: string;
+  tagName: string | null;
+}
+
+export interface IWccManifestSection {
+  name: string;
+  type: TWccSectionType;
+  icon?: string;
+  collapsed?: boolean;
+  /** Classified, filtered and sorted as the section configures it. */
+  entries: IWccManifestEntry[];
+  entriesWithoutDemo: IWccManifestEntryWithoutDemo[];
+}
+
+export interface IWccCatalogManifest {
+  sections: IWccManifestSection[];
+}

package/ts_interfaces/index.ts

@@ -0,0 +1,5 @@
+export * from './catalog.js';
+export * from './bridge.js';
+export * from './capture.js';
+export * from './requests.js';
+export * from './standard.js';

package/ts_interfaces/plugins.ts

@@ -0,0 +1,3 @@
+import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+
+export { typedrequestInterfaces };

package/ts_interfaces/requests.ts

@@ -0,0 +1,104 @@
+import * as plugins from './plugins.js';
+import type {
+  IWccInteractionRequest,
+  IWccInteractionResult,
+  IWccScreenshotRequest,
+  IWccScreenshotResult,
+} from './capture.js';
+
+/**
+ * Typed requests the shell sends to the `wcctools dev` server on `/wcctools/typedrequest`.
+ */
+
+export interface IWccDevServerInfo {
+  /** Version of the wcctools package that serves the shell. */
+  wcctoolsVersion: string;
+  /** Name of the served project's package. */
+  projectName: string;
+}
+
+export interface IReq_GetDevServerInfo
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_GetDevServerInfo
+  > {
+  method: 'getDevServerInfo';
+  request: {};
+  response: IWccDevServerInfo;
+}
+
+/** The state of a catalog bundle: its latest run started, finished or failed. */
+export type TWccBundleState = 'started' | 'finished' | 'failed';
+
+/** The status of one catalog bundle the dev server builds with tswatch. */
+export interface IWccBundleStatus {
+  /** The bundle's name in the tswatch configuration. */
+  name: string;
+  /** The latest run: `started` while it runs, then `finished` or `failed`. */
+  state: TWccBundleState;
+  /** Milliseconds the latest completed run took; absent before a run completed. */
+  durationMs?: number;
+  /**
+   * The bundler's error message when the latest completed run failed. It stays while the next
+   * run is in progress, so a failure is reported until a run finishes.
+   */
+  errorMessage?: string;
+}
+
+/** The status of every catalog bundle, at a revision that changes with every bundle event. */
+export interface IWccBundleStatusSnapshot {
+  revision: number;
+  bundles: IWccBundleStatus[];
+}
+
+/**
+ * Reads the bundle status. With `afterRevision`, the server answers once the status differs from
+ * that revision, or with the unchanged status after its wait limit, so a client follows the
+ * status with one request at a time. While the server is not serving (it is stopping), the request
+ * is refused with a typed error.
+ */
+export interface IReq_GetBundleStatus
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_GetBundleStatus
+  > {
+  method: 'getBundleStatus';
+  request: {
+    /** The revision the client knows; omitted: answer at once. */
+    afterRevision?: number;
+  };
+  response: IWccBundleStatusSnapshot;
+}
+
+/**
+ * Screenshots one demo in the dev server's headless browser. A capture waits while a catalog
+ * bundle builds, and is refused with a typed error when a bundle failed, when the subject does not
+ * resolve to a rendered demo, when the browser is busy with other captures, when the demo
+ * navigates away from the preview, or on its deadline of 30 seconds.
+ */
+export interface IReq_CaptureScreenshot
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_CaptureScreenshot
+  > {
+  method: 'captureScreenshot';
+  request: IWccScreenshotRequest;
+  response: IWccScreenshotResult;
+}
+
+/**
+ * Renders one demo in the dev server's headless browser, runs the scripted steps on it and
+ * returns the frames it observed meanwhile. A failed step ends the script and is reported in the
+ * result, as is a step that started a navigation away from the preview, which the browser blocked;
+ * refusals are those of `captureScreenshot`. Its deadline is 135 seconds, and `TypedRequest.fire()`
+ * gives up after 60 by default: fire it with a `timeoutMs` above the deadline.
+ */
+export interface IReq_CaptureInteraction
+  extends plugins.typedrequestInterfaces.implementsTR<
+    plugins.typedrequestInterfaces.ITypedRequest,
+    IReq_CaptureInteraction
+  > {
+  method: 'captureInteraction';
+  request: IWccInteractionRequest;
+  response: IWccInteractionResult;
+}

package/ts_interfaces/standard.ts

@@ -0,0 +1,103 @@
+/**
+ * The wcctools component standard (docs/standard.md): its configuration in `.smartconfig.json`
+ * and the reports `wcctools check` and `wcctools fix` produce.
+ */
+
+/** Rule set a repository adopts. */
+export type TStandardProfile = 'base' | 'dees';
+
+/** A rule id of the form `<area>/<name>`, e.g. `props/reflect-primitive`. */
+export type TStandardRuleId = string;
+
+export type TStandardSeverity = 'error' | 'warn' | 'info';
+
+/**
+ * What `wcctools fix` does for a rule:
+ * - `auto`: fixes it on every run;
+ * - `opt-in`: fixes it only when the rule is named with `--rule`;
+ * - `none`: reports only.
+ */
+export type TStandardFixMode = 'auto' | 'opt-in' | 'none';
+
+/** `.smartconfig.json` → `@design.estate/wcctools` → `standard`. */
+export interface IStandardConfig {
+  /** Rule set; 'base' when absent. */
+  profile?: TStandardProfile;
+  /** Tag prefix without the trailing hyphen, e.g. 'dees'. */
+  tagPrefix: string;
+  /** dees profile: display name per group area, e.g. { harness: 'Agent Chat' }. */
+  groupNames?: Record<string, string>;
+  /** Exact exceptions: rule id → '<file>#<member>' → '<category>: <reason>'. */
+  allowlist?: Record<TStandardRuleId, Record<string, string>>;
+  /** Accepted counts of error findings: rule id → file → count. Only shrinks. */
+  baselines?: Record<TStandardRuleId, Record<string, number>>;
+}
+
+/** `.smartconfig.json` → `@design.estate/wcctools`. */
+export interface IWccToolsConfig {
+  standard?: IStandardConfig;
+}
+
+export interface IStandardFinding {
+  ruleId: TStandardRuleId;
+  severity: TStandardSeverity;
+  /** Path relative to the repository root, '/' separators. */
+  file: string;
+  /** 1-based. */
+  line: number;
+  /** 1-based. */
+  column: number;
+  message: string;
+  /** True when `wcctools fix` resolves this finding (for opt-in rules: with --rule). */
+  fixable: boolean;
+  /** Set when the finding is covered by the allowlist or a baseline and does not fail check. */
+  covered?: 'allowlist' | 'baseline';
+}
+
+/** A file whose finding count is below its baseline: a candidate for lowering the baseline. */
+export interface IStandardBaselineSlack {
+  ruleId: TStandardRuleId;
+  file: string;
+  baseline: number;
+  current: number;
+}
+
+export interface IStandardReport {
+  profile: TStandardProfile;
+  findings: IStandardFinding[];
+  /** Files whose count is below their baseline: candidates for --update-baseline. */
+  baselineSlack: IStandardBaselineSlack[];
+  /** True when no error finding remains outside the allowlist and baselines. */
+  ok: boolean;
+}
+
+/** A rule as it applies in one profile. */
+export interface IStandardRuleInfo {
+  id: TStandardRuleId;
+  severity: TStandardSeverity;
+  fixMode: TStandardFixMode;
+  /** Categories an allowlist entry for this rule may use; empty when the rule takes no allowlist. */
+  allowlistCategories: string[];
+}
+
+export interface IStandardFileMove {
+  from: string;
+  to: string;
+}
+
+/** The changes a `wcctools fix` run makes (or, with --dry-run, would make). */
+export interface IStandardFixPlan {
+  /** `git mv` operations, from the original path to the final path. */
+  moves: IStandardFileMove[];
+  /** New files, by final path. */
+  created: string[];
+  /** Changed existing files, by final path, with the rules that changed them. */
+  edited: Array<{ file: string; ruleIds: TStandardRuleId[] }>;
+}
+
+export interface IStandardFixResult {
+  dryRun: boolean;
+  plan: IStandardFixPlan;
+  /** The check after the fix (with --dry-run: as the fix would leave the repository). */
+  remaining: IStandardReport;
+}

package/ts_shared/index.ts

@@ -0,0 +1 @@
+export * from './previewroute.js';

package/ts_shared/plugins.ts

@@ -0,0 +1,3 @@
+import * as interfaces from '../ts_interfaces/index.js';
+
+export { interfaces };

package/ts_shared/previewroute.ts

@@ -0,0 +1,58 @@
+import * as plugins from './plugins.js';
+
+/**
+ * The address of a preview document: the path the `wcctools dev` server serves it on, and
+ * the query that names what it renders. The shell loads it into its iframe; headless tools
+ * load it directly to render one demo alone.
+ */
+
+/** The path `wcctools dev` serves the preview document on. */
+export const previewRoutePath = '/wcctools-preview';
+
+export interface IWccPreviewRoute {
+  selection: plugins.interfaces.IWccSelection | null;
+  theme: plugins.interfaces.TWccTheme;
+}
+
+const queryKeys = {
+  section: 'section',
+  item: 'item',
+  demo: 'demo',
+  theme: 'theme',
+} as const;
+
+/** The query string (with leading `?`) of a preview route. */
+export const formatPreviewQuery = (routeArg: IWccPreviewRoute): string => {
+  const params = new URLSearchParams();
+  if (routeArg.selection) {
+    params.set(queryKeys.section, routeArg.selection.sectionName);
+    params.set(queryKeys.item, routeArg.selection.itemName);
+    params.set(queryKeys.demo, String(routeArg.selection.demoIndex));
+  }
+  params.set(queryKeys.theme, routeArg.theme);
+  return `?${params.toString()}`;
+};
+
+/** Read a preview route from a query string. Missing or invalid parts read as no selection and the dark theme. */
+export const parsePreviewQuery = (searchArg: string): IWccPreviewRoute => {
+  const params = new URLSearchParams(searchArg);
+  const theme: plugins.interfaces.TWccTheme = params.get(queryKeys.theme) === 'bright' ? 'bright' : 'dark';
+  const sectionName = params.get(queryKeys.section);
+  const itemName = params.get(queryKeys.item);
+  if (!sectionName || !itemName) {
+    return { selection: null, theme };
+  }
+  const demoIndex = Number.parseInt(params.get(queryKeys.demo) ?? '0', 10);
+  return {
+    selection: { sectionName, itemName, demoIndex: Number.isInteger(demoIndex) && demoIndex >= 0 ? demoIndex : 0 },
+    theme,
+  };
+};
+
+export const previewReadyMessage: plugins.interfaces.IWccPreviewReadyMessage = { type: 'wcctools-preview-ready' };
+
+export const isPreviewReadyMessage = (dataArg: unknown): dataArg is plugins.interfaces.IWccPreviewReadyMessage => {
+  return typeof dataArg === 'object'
+    && dataArg !== null
+    && (dataArg as { type?: unknown }).type === previewReadyMessage.type;
+};

package/ts_shell/bundlestatus.ts

@@ -0,0 +1,68 @@
+import * as plugins from './plugins.js';
+
+/** The first and the longest pause before a failed status request is sent again. */
+const retryDelayMinMs = 1_000;
+const retryDelayMaxMs = 10_000;
+
+/** Resolves after `msArg`, or at once when the signal aborts. */
+const pause = (msArg: number, signalArg: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signalArg.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, msArg);
+    signalArg.addEventListener('abort', done, { once: true });
+  });
+
+/**
+ * Follows the dev server's bundle status: one `getBundleStatus` request at a time, each answered
+ * when the status changes. A failed request (the server restarting, for example) is sent again
+ * after a growing pause. `dispose()` aborts the request in flight and ends the loop.
+ */
+export class WccBundleStatusClient {
+  private abortController: AbortController | null = null;
+
+  constructor(
+    private readonly apiPath: string,
+    private readonly onStatus: (snapshotArg: plugins.interfaces.IWccBundleStatusSnapshot) => void,
+  ) {}
+
+  public start() {
+    if (this.abortController) {
+      return;
+    }
+    const abortController = new AbortController();
+    this.abortController = abortController;
+    void this.follow(abortController.signal);
+  }
+
+  public dispose() {
+    this.abortController?.abort();
+    this.abortController = null;
+  }
+
+  private async follow(signalArg: AbortSignal) {
+    const request = new plugins.typedrequest.TypedRequest<plugins.interfaces.IReq_GetBundleStatus>(this.apiPath, 'getBundleStatus');
+    let revision: number | undefined;
+    let retryDelay = retryDelayMinMs;
+    while (!signalArg.aborted) {
+      try {
+        const snapshot = await request.fire({ afterRevision: revision }, { abortSignal: signalArg });
+        retryDelay = retryDelayMinMs;
+        if (!signalArg.aborted && snapshot.revision !== revision) {
+          revision = snapshot.revision;
+          this.onStatus(snapshot);
+        }
+      } catch (error) {
+        if (signalArg.aborted) {
+          return;
+        }
+        console.warn('wcctools: reading the bundle status failed; retrying', error);
+        await pause(retryDelay, signalArg);
+        retryDelay = Math.min(retryDelay * 2, retryDelayMaxMs);
+      }
+    }
+  }
+}