@design.estate/wcctools 6.1.0 → 6.2.0

package/ts/classes.devserver.ts

@@ -7,6 +7,11 @@ import { loadShellContent, shellPathPrefix } from './shellcontent.js';
 export interface IWccDevServerOptions {
   /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
   port?: number;
+  /**
+   * The project directory: its tswatch configuration, package.json and catalog are served, and
+   * tswatch bundles and watches in it (default: `process.cwd()` when the server is constructed).
+   */
+  cwd?: string;
 }
 
 export interface IWccDevServerAddress {
@@ -28,84 +33,159 @@ const securityHeaders: plugins.typedserver.ISecurityHeaders = {
 const acceptAnyHostname = () => true;
 
 /**
- * `wcctools dev`: bundles the catalog of the current project with tswatch, as its
- * `@git.zone/tswatch` configuration (or the `element` preset) describes, and serves on one port:
+ * `wcctools dev`: bundles the catalog of a project with tswatch, as its `@git.zone/tswatch`
+ * configuration (or the `element` preset) describes, and serves on one port:
  *
  * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
- * - the typed API on `/wcctools/typedrequest`,
+ * - the typed API on `/wcctools/typedrequest`, including the bundles' status,
  * - the catalog's preview document and bundle from the tswatch serve directory on every other
  *   path, with live reload that reloads only the preview document.
  *
- * tswatch resolves its paths against the process's working directory, so the server serves the
- * project the process runs in.
+ * The server owns no process lifecycle: while it runs, a process shutdown through smartexit's
+ * `ProcessLifecycle` stops it. The entry point installs that lifecycle with
+ * `getShutdownTimeoutMs()`.
  */
 export class WccDevServer {
   /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
   public readonly api = new WccDevApi();
-  private tsWatch: plugins.tswatch.TsWatch | null = null;
+  /** The project directory everything resolves against. */
+  public readonly cwd: string;
+  /** The project's tswatch configuration, or the `element` preset; read once, on construction. */
+  private readonly config: plugins.tswatch.ITswatchConfig;
+  /** Bundling and watching stay tswatch's; its own server stays off. */
+  private readonly tsWatch: plugins.tswatch.TsWatch;
   private typedServer: plugins.typedserver.TypedServer | null = null;
-  private readonly smartExit = new plugins.smartexit.SmartExit({ silent: true });
+  /** Stops the server on a process shutdown; registered by start(), released by stop(). */
+  private smartExit: plugins.smartexit.SmartExit | null = null;
+  private unsubscribeBundleEvents: (() => void) | null = null;
+  private running = false;
+  private starting: Promise<IWccDevServerAddress> | null = null;
+  private stopping: Promise<void> | null = null;
 
   constructor(private readonly options: IWccDevServerOptions = {}) {
-    this.smartExit.addCleanupFunction(() => this.stop());
+    this.cwd = plugins.path.resolve(options.cwd ?? process.cwd());
+    const configHandler = new plugins.tswatch.ConfigHandler(this.cwd);
+    this.config = configHandler.loadConfig() ?? this.getElementPreset(configHandler);
+    this.tsWatch = new plugins.tswatch.TsWatch({ ...this.config, server: { enabled: false } }, { cwd: this.cwd });
   }
 
+  /**
+   * The shutdown deadline the server needs, tswatch's: the entry point installs smartexit's
+   * `ProcessLifecycle` with it, so every watcher command keeps its full grace period.
+   */
+  public getShutdownTimeoutMs(): number {
+    return this.tsWatch.getShutdownTimeoutMs();
+  }
+
+  /**
+   * Bundles the catalog, starts the watchers and serves. Refused while the server runs or stops;
+   * the server starts again after stop().
+   */
   public async start(): Promise<IWccDevServerAddress> {
-    if (this.typedServer) {
-      throw new Error('wcctools: the dev server is already started.');
+    if (this.running || this.stopping) {
+      throw new Error('wcctools: the dev server is already started or still stopping.');
+    }
+    this.running = true;
+    // A process shutdown stops the server from here on, also while it is still starting
+    const smartExit = new plugins.smartexit.SmartExit({ silent: true });
+    smartExit.addCleanupFunction(() => this.stop());
+    this.smartExit = smartExit;
+    const starting = this.startServing();
+    this.starting = starting;
+    try {
+      const address = await starting;
+      if (this.stopping) {
+        throw new Error('wcctools: the dev server was stopped while starting.');
+      }
+      return address;
+    } catch (error) {
+      // A start that failed halfway releases what it opened
+      await this.stop();
+      throw error;
+    } finally {
+      if (this.starting === starting) {
+        this.starting = null;
+      }
     }
-    const cwd = process.cwd();
-    const configHandler = new plugins.tswatch.ConfigHandler(cwd);
-    const config = configHandler.loadConfig() ?? configHandler.getPreset('element');
-    const serveDir = plugins.path.resolve(cwd, config.server?.serveDir ?? defaultServeDir);
-    const port = this.options.port ?? config.server?.port ?? defaultPort;
+  }
+
+  /**
+   * Stops the server and tswatch's bundling and watching, and releases everything start()
+   * registered. A stop during start() waits for the start to settle first; concurrent and
+   * repeated calls share one stop.
+   */
+  public stop(): Promise<void> {
+    this.stopping ??= this.release().finally(() => {
+      this.stopping = null;
+    });
+    return this.stopping;
+  }
+
+  private async release(): Promise<void> {
+    await this.starting?.catch(() => undefined);
+    const smartExit = this.smartExit;
+    const typedServer = this.typedServer;
+    const unsubscribeBundleEvents = this.unsubscribeBundleEvents;
+    this.smartExit = null;
+    this.typedServer = null;
+    this.unsubscribeBundleEvents = null;
+    smartExit?.deregister();
+    // Status requests waiting for a change are refused now, so none holds the server's stop, and
+    // requests until the server stops listening are refused too: the shell backs off
+    this.api.bundleStatus.close();
+    try {
+      await typedServer?.stop();
+    } finally {
+      try {
+        await this.tsWatch.stop();
+      } finally {
+        unsubscribeBundleEvents?.();
+        this.running = false;
+      }
+    }
+  }
+
+  private async startServing(): Promise<IWccDevServerAddress> {
+    const serveDir = plugins.path.resolve(this.cwd, this.config.server?.serveDir ?? defaultServeDir);
+    const port = this.options.port ?? this.config.server?.port ?? defaultPort;
 
     // The preview surface watches the serve directory, which must exist before the first bundle
     await plugins.fs.mkdir(serveDir, { recursive: true });
     this.api.setServerInfo({
       wcctoolsVersion: commitinfo.version,
-      projectName: await this.readProjectName(cwd),
-    });
-    const typedServer = new plugins.typedserver.TypedServer({
-      cors: false,
-      port,
-      surfaces: [
-        await this.createShellSurface(),
-        this.createPreviewSurface(serveDir),
-      ],
+      projectName: await this.readProjectName(),
     });
+    const surfaces = [await this.createShellSurface(), this.createPreviewSurface(serveDir)];
+    const typedServer = new plugins.typedserver.TypedServer({ cors: false, port, surfaces });
     this.typedServer = typedServer;
 
-    // Bundling and watching stay tswatch's; its own server stays off
-    this.tsWatch = new plugins.tswatch.TsWatch({ ...config, server: { enabled: false } });
-    try {
-      await this.tsWatch.start();
-      await typedServer.start();
-    } catch (error) {
-      await this.stop();
-      throw error;
-    }
+    this.api.bundleStatus.open();
+    const bundleStatus = this.api.bundleStatus;
+    this.unsubscribeBundleEvents = this.tsWatch.onBundleEvent((eventArg) => bundleStatus.record(eventArg));
+    // The initial bundles run here; a failed one is reported in the bundle status
+    await this.tsWatch.start();
+    await typedServer.start();
     const boundPort = typedServer.listeningPort ?? port;
     return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
   }
 
-  /** Stops the server, then tswatch's bundling and watching. */
-  public async stop(): Promise<void> {
-    const typedServer = this.typedServer;
-    const tsWatch = this.tsWatch;
-    this.typedServer = null;
-    this.tsWatch = null;
-    this.smartExit.deregister();
-    await typedServer?.stop();
-    await tsWatch?.stop();
+  private getElementPreset(configHandlerArg: plugins.tswatch.ConfigHandler): plugins.tswatch.ITswatchConfig {
+    const preset = configHandlerArg.getPreset('element');
+    if (!preset) {
+      throw new Error('wcctools: tswatch provides no `element` preset.');
+    }
+    return preset;
   }
 
   /**
    * The shell: the prebuilt shell bundle and the typed API.
    *
    * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
-   * side effects is registered here, add a `websocketAdmission`/`requestAdmission` that accepts
-   * only the shell's own origin, and keep surface mode's strict authority validation.
+   * side effects is registered here, the server binds to localhost by default (another interface
+   * only on explicit request), validates the Host header against the addresses it serves instead
+   * of accepting any hostname, and admits typedsocket connections and typed requests only from the
+   * shell's own origin (a `websocketAdmission`/`requestAdmission`), keeping surface mode's strict
+   * authority validation. Until then every handler here is read-only.
    */
   private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
     return {
@@ -154,8 +234,8 @@ export class WccDevServer {
     };
   }
 
-  private async readProjectName(cwdArg: string): Promise<string> {
-    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(cwdArg, 'package.json'), 'utf8')) as { name?: string };
-    return packageJson.name ?? plugins.path.basename(cwdArg);
+  private async readProjectName(): Promise<string> {
+    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(this.cwd, 'package.json'), 'utf8')) as { name?: string };
+    return packageJson.name ?? plugins.path.basename(this.cwd);
   }
 }

package/ts/cli.ts

@@ -23,7 +23,10 @@ export const registerCommands = (out: plugins.smartconsole.SmartConsole): void =
       },
     },
   }, async ({ options }) => {
-    const devServer = new WccDevServer({ port: options.port });
+    const devServer = new WccDevServer({ port: options.port, cwd: process.cwd() });
+    // The entry point owns process signals: SIGINT and SIGTERM run every registered cleanup, the
+    // dev server's stop among them, once within tswatch's shutdown deadline, then exit.
+    plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
     const address = await devServer.start();
     await out.log(`wcctools dev: ${address.url}`);
   });

package/ts/index.ts

@@ -1,3 +1 @@
 export { runCli } from './cli.js';
-export { WccDevServer, type IWccDevServerOptions, type IWccDevServerAddress } from './classes.devserver.js';
-export { WccDevApi } from './classes.devapi.js';

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/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,4 @@
+export * from './catalog.js';
+export * from './bridge.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,65 @@
+import * as plugins from './plugins.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;
+}

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;
+};