@electron-stagewright/plugin-budget 0.0.0-stage → 0.1.0

package/dist/probe.js

@@ -0,0 +1,161 @@
+/**
+ * Bodies the plugin evaluates inside the app through the transport's `evaluate` seam. Each is a
+ * self-contained string: no imports, no closures, JSON-safe results.
+ *
+ * @module
+ */
+/** Timer lateness below this is scheduler jitter, not a blocked main thread. */
+export const MIN_STALL_MS = 10;
+export const SAMPLE_INTERVAL_MS = 10;
+export const DEFAULT_IPC_INTERVAL_MS = 25;
+export const DEFAULT_WINDOW_MS = 2_000;
+/** An unread window stops itself after this, so a detached or abandoned app keeps no timer. */
+export const MAX_WINDOW_MS = 600_000;
+const STARTUP_READ_TIMEOUT_MS = 10_000;
+const FIRST_WINDOW_TIMING = `(() => {
+  const entry = performance.getEntriesByType('navigation')[0];
+  return {
+    timeOrigin: performance.timeOrigin,
+    loadEventEnd: entry ? entry.loadEventEnd : 0,
+    type: entry ? entry.type : null,
+    url: entry ? entry.name : location.href,
+  };
+})()`;
+/**
+ * Main-process body. `facts` reads process metrics. `start` arms a 10 ms timer whose lateness is
+ * the blocked time (replacing any earlier window); `read` summarises it and, with `stop`, clears it.
+ * `startup` reads the navigation timing of the first window still open.
+ */
+export const MAIN_BODY = `
+const KEY = '__swBudget';
+const round = (value) => Math.round(value * 10) / 10;
+if (arg.op === 'facts') {
+  return {
+    pid: process.pid,
+    creationTime: typeof process.getCreationTime === 'function' ? process.getCreationTime() : null,
+    electron: process.versions.electron || null,
+    platform: process.platform,
+    processes: electronApp.app.getAppMetrics().map((entry) => ({
+      pid: entry.pid,
+      type: entry.type,
+      name: entry.name || entry.serviceName || null,
+      workingSetKb: entry.memory.workingSetSize,
+      privateKb: typeof entry.memory.privateBytes === 'number' ? entry.memory.privateBytes : null,
+    })),
+  };
+}
+if (arg.op === 'start') {
+  const previous = globalThis[KEY];
+  if (previous) clearInterval(previous.handle);
+  const state = { startedAt: performance.now(), last: performance.now(), stalls: [], handle: null };
+  state.handle = setInterval(() => {
+    const at = performance.now();
+    if (at - state.startedAt > ${MAX_WINDOW_MS}) {
+      clearInterval(state.handle);
+      if (globalThis[KEY] === state) delete globalThis[KEY];
+      return;
+    }
+    const stall = at - state.last - ${SAMPLE_INTERVAL_MS};
+    if (stall >= ${MIN_STALL_MS}) state.stalls.push(stall);
+    state.last = at;
+  }, ${SAMPLE_INTERVAL_MS});
+  if (typeof state.handle.unref === 'function') state.handle.unref();
+  globalThis[KEY] = state;
+  return { started: true };
+}
+if (arg.op === 'read') {
+  const state = globalThis[KEY];
+  if (!state) return null;
+  const at = performance.now();
+  const stalls = state.stalls.slice();
+  const tail = at - state.last - ${SAMPLE_INTERVAL_MS};
+  if (tail >= ${MIN_STALL_MS}) stalls.push(tail);
+  if (arg.stop) {
+    clearInterval(state.handle);
+    delete globalThis[KEY];
+  }
+  const windowMs = Math.max(at - state.startedAt, 1);
+  const blockedMs = stalls.reduce((sum, stall) => sum + stall, 0);
+  return {
+    windowMs: round(windowMs),
+    blockedMs: round(blockedMs),
+    blockedPercent: round((blockedMs / windowMs) * 100),
+    maxStallMs: round(stalls.reduce((max, stall) => Math.max(max, stall), 0)),
+    stallsOver50Ms: stalls.filter((stall) => stall > 50).length,
+    stallsOver100Ms: stalls.filter((stall) => stall > 100).length,
+  };
+}
+if (arg.op === 'startup') {
+  const windows = electronApp.BrowserWindow.getAllWindows().filter((win) => !win.isDestroyed());
+  if (windows.length === 0) return { error: 'no window is open' };
+  const first = windows.reduce((a, b) => (b.id < a.id ? b : a));
+  const contents = first.webContents;
+  // executeJavaScript waits, unbounded, for a window that never loaded or is still loading.
+  if (!contents.getURL() || contents.isLoadingMainFrame()) {
+    return { error: 'the first window has not finished loading' };
+  }
+  const history = contents.navigationHistory;
+  let timer;
+  // A hung renderer must not hold the session's budget queue forever.
+  const timing = await Promise.race([
+    contents.executeJavaScript(${JSON.stringify(FIRST_WINDOW_TIMING)}),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error('the first window did not answer')), ${STARTUP_READ_TIMEOUT_MS});
+    }),
+  ]).finally(() => clearTimeout(timer));
+  const firstEntry =
+    history && typeof history.getEntryAtIndex === 'function' ? history.getEntryAtIndex(0) : null;
+  // Electron before 32 has no navigationHistory, only webContents.length() (deprecated after).
+  const historyLength =
+    !history && typeof contents.length === 'function' ? contents.length() : null;
+  return { ...timing, firstUrl: firstEntry ? firstEntry.url : null, historyLength };
+}
+throw new Error('unknown budget op');
+`;
+const IPC_KEY = '__swBudgetIpc';
+const MAX_IPC_SAMPLES = 20_000;
+/**
+ * Renderer body that starts a background loop timing one round trip of `probe` per interval.
+ * The expression is inlined, not evaluated at runtime, so a page CSP without `unsafe-eval` holds.
+ */
+export function buildIpcStartBody(probe) {
+    return `
+const previous = window['${IPC_KEY}'];
+if (previous) previous.stop = true;
+const state = { samples: [], errors: 0, lastError: null, stop: false };
+window['${IPC_KEY}'] = state;
+const once = async () => { await (${probe}); };
+const intervalMs = arg.intervalMs;
+const begin = performance.now();
+void (async () => {
+  while (
+    !state.stop &&
+    state.samples.length < ${MAX_IPC_SAMPLES} &&
+    performance.now() - begin < ${MAX_WINDOW_MS}
+  ) {
+    const startedAt = performance.now();
+    try {
+      await once();
+      state.samples.push(performance.now() - startedAt);
+    } catch (error) {
+      state.errors += 1;
+      state.lastError = String(error && error.message ? error.message : error);
+      if (state.samples.length === 0 && state.errors >= 20) break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+})();
+return true;
+`;
+}
+/** Renderer body: read the probe samples and, with `stop`, end the loop. Null when none runs. */
+export const IPC_READ_BODY = `
+const state = window['${IPC_KEY}'];
+if (!state) return null;
+if (arg.stop) {
+  state.stop = true;
+  delete window['${IPC_KEY}'];
+}
+return { samples: state.samples.slice(), errors: state.errors, lastError: state.lastError };
+`;
+//# sourceMappingURL=probe.js.map

package/dist/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAA;AAC9B,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAA;AACpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAA;AACtC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA;AACpC,MAAM,uBAAuB,GAAG,MAAM,CAAA;AAmBtC,MAAM,mBAAmB,GAAG;;;;;;;;KAQvB,CAAA;AAEL;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;iCAwBQ,aAAa;;;;;sCAKR,kBAAkB;mBACrC,YAAY;;OAExB,kBAAkB;;;;;;;;;;mCAUU,kBAAkB;gBACrC,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCA6BK,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC;;uFAEmB,uBAAuB;;;;;;;;;;;CAW7G,CAAA;AAoBD,MAAM,OAAO,GAAG,eAAe,CAAA;AAC/B,MAAM,eAAe,GAAG,MAAM,CAAA;AAE9B;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO;2BACkB,OAAO;;;UAGxB,OAAO;oCACmB,KAAK;;;;;;6BAMZ,eAAe;kCACV,aAAa;;;;;;;;;;;;;;;CAe9C,CAAA;AACD,CAAC;AAQD,iGAAiG;AACjG,MAAM,CAAC,MAAM,aAAa,GAAG;wBACL,OAAO;;;;mBAIZ,OAAO;;;CAGzB,CAAA"}

package/dist/render.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Markdown tables for a check report and for a before/after comparison.
+ *
+ * @module
+ */
+import type { CheckReport } from './check.js';
+import { type BudgetRun, type SummaryRow } from './run.js';
+export declare function renderCheckReport(report: CheckReport): string;
+export interface ComparisonRow {
+    readonly id: string;
+    readonly phase?: SummaryRow['phase'];
+    readonly unit: SummaryRow['unit'];
+    readonly metric?: string;
+    readonly before?: number;
+    readonly after?: number;
+    readonly deltaPercent?: number;
+}
+/** Pair the rows of two runs. A memory row measured with different metrics is left unpaired. */
+export declare function compareRuns(before: BudgetRun, after: BudgetRun): ComparisonRow[];
+export declare function renderComparison(rows: readonly ComparisonRow[]): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAYxE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAe7D;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,aAAa,EAAE,CAoBhF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAcvE"}

package/dist/render.js

@@ -0,0 +1,63 @@
+/**
+ * Markdown tables for a check report and for a before/after comparison.
+ *
+ * @module
+ */
+import { summarizeRun } from './run.js';
+function table(header, rows) {
+    const line = (cells) => `| ${cells.join(' | ')} |`;
+    return [line(header), line(header.map(() => '---')), ...rows.map(line)].join('\n');
+}
+const label = (id, phase, metric) => [id, phase === undefined ? '' : `(${phase})`, metric === undefined ? '' : `[${metric}]`]
+    .filter((part) => part.length > 0)
+    .join(' ');
+export function renderCheckReport(report) {
+    const verdict = report.passed ? 'PASS' : `FAIL (${report.reason ?? 'OVER_BUDGET'})`;
+    const { pass, fail, unmeasured } = report.summary;
+    const rows = report.results.map((result) => [
+        label(result.id, result.phase, result.metric),
+        result.actual === undefined ? '-' : `${result.actual} ${result.unit}`,
+        `${result.limit} ${result.unit}`,
+        `${result.allowed} ${result.unit}`,
+        result.status + (result.detail === undefined ? '' : `: ${result.detail}`),
+    ]);
+    return [
+        `Budget check: ${verdict} - ${pass} pass, ${fail} fail, ${unmeasured} unmeasured`,
+        '',
+        table(['metric', 'actual', 'budget', 'allowed', 'status'], rows),
+    ].join('\n');
+}
+/** Pair the rows of two runs. A memory row measured with different metrics is left unpaired. */
+export function compareRuns(before, after) {
+    const key = (row) => `${row.id}@${row.phase ?? ''}@${row.metric ?? ''}`;
+    const beforeRows = new Map(summarizeRun(before).map((row) => [key(row), row]));
+    const afterRows = new Map(summarizeRun(after).map((row) => [key(row), row]));
+    return [...new Set([...beforeRows.keys(), ...afterRows.keys()])].map((rowKey) => {
+        const a = beforeRows.get(rowKey);
+        const b = afterRows.get(rowKey);
+        const row = (a ?? b);
+        return {
+            id: row.id,
+            unit: row.unit,
+            ...(row.phase === undefined ? {} : { phase: row.phase }),
+            ...(row.metric === undefined ? {} : { metric: row.metric }),
+            ...(a === undefined ? {} : { before: a.value }),
+            ...(b === undefined ? {} : { after: b.value }),
+            ...(a === undefined || b === undefined || a.value === 0
+                ? {}
+                : { deltaPercent: Math.round(((b.value - a.value) / a.value) * 1000) / 10 }),
+        };
+    });
+}
+export function renderComparison(rows) {
+    const value = (amount, unit) => amount === undefined ? '-' : `${amount} ${unit}`;
+    return table(['metric', 'before', 'after', 'delta'], rows.map((row) => [
+        label(row.id, row.phase, row.metric),
+        value(row.before, row.unit),
+        value(row.after, row.unit),
+        row.deltaPercent === undefined
+            ? '-'
+            : `${row.deltaPercent > 0 ? '+' : ''}${row.deltaPercent}%`,
+    ]));
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,218 @@
+/**
+ * The run document: raw measurements of one build, and the flat summary `check` and `compare` read.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { type Phase, type ProcessType } from './budget.js';
+export declare const RUN_FORMAT = "electron-stagewright-budget-run";
+export declare const RUN_SCHEMA_VERSION = 1;
+declare const stallSchema: z.ZodObject<{
+    windowMs: z.ZodNumber;
+    blockedMs: z.ZodNumber;
+    blockedPercent: z.ZodNumber;
+    maxStallMs: z.ZodNumber;
+    stallsOver50Ms: z.ZodNumber;
+    stallsOver100Ms: z.ZodNumber;
+}, z.core.$strip>;
+declare const latencySchema: z.ZodObject<{
+    count: z.ZodNumber;
+    p50: z.ZodNumber;
+    p95: z.ZodNumber;
+    p99: z.ZodNumber;
+    max: z.ZodNumber;
+}, z.core.$strip>;
+declare const processSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    type: z.ZodEnum<{
+        main: "main";
+        renderer: "renderer";
+        gpu: "gpu";
+        utility: "utility";
+        other: "other";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    mb: z.ZodOptional<z.ZodNumber>;
+    workingSetMb: z.ZodNumber;
+}, z.core.$strip>;
+declare const memorySchema: z.ZodObject<{
+    metric: z.ZodEnum<{
+        footprint: "footprint";
+        pss: "pss";
+        privateBytes: "privateBytes";
+        workingSet: "workingSet";
+    }>;
+    processes: z.ZodArray<z.ZodObject<{
+        pid: z.ZodNumber;
+        type: z.ZodEnum<{
+            main: "main";
+            renderer: "renderer";
+            gpu: "gpu";
+            utility: "utility";
+            other: "other";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        mb: z.ZodOptional<z.ZodNumber>;
+        workingSetMb: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const measurementSchema: z.ZodObject<{
+    startup: z.ZodOptional<z.ZodObject<{
+        firstWindowMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    memory: z.ZodOptional<z.ZodObject<{
+        metric: z.ZodEnum<{
+            footprint: "footprint";
+            pss: "pss";
+            privateBytes: "privateBytes";
+            workingSet: "workingSet";
+        }>;
+        processes: z.ZodArray<z.ZodObject<{
+            pid: z.ZodNumber;
+            type: z.ZodEnum<{
+                main: "main";
+                renderer: "renderer";
+                gpu: "gpu";
+                utility: "utility";
+                other: "other";
+            }>;
+            name: z.ZodOptional<z.ZodString>;
+            mb: z.ZodOptional<z.ZodNumber>;
+            workingSetMb: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    mainThread: z.ZodOptional<z.ZodObject<{
+        windowMs: z.ZodNumber;
+        blockedMs: z.ZodNumber;
+        blockedPercent: z.ZodNumber;
+        maxStallMs: z.ZodNumber;
+        stallsOver50Ms: z.ZodNumber;
+        stallsOver100Ms: z.ZodNumber;
+    }, z.core.$strip>>;
+    ipc: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+        p50: z.ZodNumber;
+        p95: z.ZodNumber;
+        p99: z.ZodNumber;
+        max: z.ZodNumber;
+    }, z.core.$strip>>;
+    unavailable: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+declare const bundleEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    gzip: z.ZodBoolean;
+    files: z.ZodNumber;
+    bytes: z.ZodNumber;
+    unavailable: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const runSchema: z.ZodObject<{
+    format: z.ZodLiteral<"electron-stagewright-budget-run">;
+    schema_version: z.ZodLiteral<1>;
+    created_at: z.ZodString;
+    platform: z.ZodString;
+    arch: z.ZodString;
+    electron_version: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    rounds: z.ZodArray<z.ZodObject<{
+        round: z.ZodNumber;
+        phase: z.ZodEnum<{
+            cold: "cold";
+            warm: "warm";
+            live: "live";
+        }>;
+        measurement: z.ZodObject<{
+            startup: z.ZodOptional<z.ZodObject<{
+                firstWindowMs: z.ZodNumber;
+            }, z.core.$strip>>;
+            memory: z.ZodOptional<z.ZodObject<{
+                metric: z.ZodEnum<{
+                    footprint: "footprint";
+                    pss: "pss";
+                    privateBytes: "privateBytes";
+                    workingSet: "workingSet";
+                }>;
+                processes: z.ZodArray<z.ZodObject<{
+                    pid: z.ZodNumber;
+                    type: z.ZodEnum<{
+                        main: "main";
+                        renderer: "renderer";
+                        gpu: "gpu";
+                        utility: "utility";
+                        other: "other";
+                    }>;
+                    name: z.ZodOptional<z.ZodString>;
+                    mb: z.ZodOptional<z.ZodNumber>;
+                    workingSetMb: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            mainThread: z.ZodOptional<z.ZodObject<{
+                windowMs: z.ZodNumber;
+                blockedMs: z.ZodNumber;
+                blockedPercent: z.ZodNumber;
+                maxStallMs: z.ZodNumber;
+                stallsOver50Ms: z.ZodNumber;
+                stallsOver100Ms: z.ZodNumber;
+            }, z.core.$strip>>;
+            ipc: z.ZodOptional<z.ZodObject<{
+                count: z.ZodNumber;
+                p50: z.ZodNumber;
+                p95: z.ZodNumber;
+                p99: z.ZodNumber;
+                max: z.ZodNumber;
+            }, z.core.$strip>>;
+            unavailable: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    bundle: z.ZodOptional<z.ZodObject<{
+        entries: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            path: z.ZodString;
+            gzip: z.ZodBoolean;
+            files: z.ZodNumber;
+            bytes: z.ZodNumber;
+            unavailable: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StallSummary = z.infer<typeof stallSchema>;
+export type LatencySummary = z.infer<typeof latencySchema>;
+export type ProcessMemory = z.infer<typeof processSchema>;
+export type MemoryMeasurement = z.infer<typeof memorySchema>;
+export type Measurement = z.infer<typeof measurementSchema>;
+export type BundleEntryMeasurement = z.infer<typeof bundleEntrySchema>;
+export type BudgetRun = z.infer<typeof runSchema>;
+/** A run file that is missing or is not a run document. */
+export declare class RunFileError extends Error {
+    readonly runPath: string;
+    constructor(message: string, runPath: string);
+}
+export declare function loadRun(runPath: string): Promise<BudgetRun>;
+export declare function createRun(fields: Pick<BudgetRun, 'rounds'> & Partial<Pick<BudgetRun, 'bundle' | 'label'>> & {
+    readonly electronVersion?: string;
+    readonly now?: Date;
+}): BudgetRun;
+export declare function median(values: readonly number[]): number;
+/** Nearest-rank percentiles; an empty set reports zeros with `count: 0`. */
+export declare function summarizeLatencies(samples: readonly number[]): LatencySummary;
+/**
+ * Megabytes per process type for one memory sample, in the sample's metric. A type with a pid the
+ * OS reader could not see is left out rather than undercounted.
+ */
+export declare function memoryByType(memory: MemoryMeasurement): Partial<Record<ProcessType, number>>;
+/** One summarised value: the median over the rounds of one phase. */
+export interface SummaryRow {
+    readonly id: string;
+    readonly phase?: Phase;
+    readonly value: number;
+    /** The unrounded median, which a check compares; `value` is for display. */
+    readonly exact: number;
+    readonly unit: 'ms' | 'MB' | '%' | 'KB';
+    /** The memory metric, so a table never shows megabytes without naming what they count. */
+    readonly metric?: string;
+    readonly samples: number;
+}
+/** Flatten a run into comparable rows (`memory.main`, `ipc.p99Ms`, `bundle.<id>`, ...). */
+export declare function summarizeRun(run: BudgetRun): SummaryRow[];
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}