@ia-qa/self-healing 1.6.7 → 1.6.10

package/dist/nameMask.d.ts

@@ -0,0 +1,110 @@
+import { PageMapping } from './aom';
+import { diffMappings } from './browser/match';
+import { Usage } from './ingest';
+/**
+ * Name masking — the declared-variable-label class.
+ *
+ * A label that carries a counter, a total or a clock ("🔌 Smithery 3.2k calls",
+ * "Cart (3)", "Step 2 of 5") changes on its own. The selector still resolves, so
+ * `diffMappings` calls it `renamed` and the verdict stays PASS — reported every
+ * single run, dismissed every single run. `nameHint` notices the pattern; this is
+ * the remedy it points at.
+ *
+ * **Why this exists rather than "just use `volatile`".** `volatile` was the only
+ * answer available, and it is the wrong size: it drops the element from the contract
+ * *entirely* — role, selector, href, coverage. The counter you wanted to ignore takes
+ * a real button out of the gate with it, and a selector break on that button then
+ * goes unnoticed forever. A mask is the conservative half: the element stays under
+ * contract on everything that identifies it, and only the varying field stops being
+ * compared. Both are user declarations — the doctrine `volatile.ts` states ("a
+ * declaration, not a heuristic") admits this one for exactly the same reason, at a
+ * granularity that costs less.
+ *
+ * **Applied at comparison, never at capture.** `map` and the run capture keep writing
+ * the raw label to disk, and this module masks in-memory copies right before the diff.
+ * Three things fall out of that: the contracts keep the evidence (the report, the
+ * crops and `_overview.md` still say what the page actually read), editing the config
+ * takes effect without re-mapping, and removing a mask cannot silently rewrite history.
+ *
+ * **It lives outside `src/browser/match.js`**, like `nameDrift.ts` and for the same
+ * two reasons: that file ships twice (npm + the zero-install web tool) and must stay
+ * dependency-free, and the web tool has no config.json to declare a mask in. No
+ * config ⇒ no masks ⇒ `diffWithMasks` is `diffMappings`, object for object.
+ *
+ * **Two refusals keep it from becoming a blindfold.** A mask is dropped, loudly, when
+ *  - a label it would swallow is one the tests locate by name (`usage.names`). Masking
+ *    that is the exact silent failure this package exists to kill: the gate goes green
+ *    while the suite goes red. The user is told which label and which file:line.
+ *  - applying it would leave two elements of the same role sharing one name, on either
+ *    side of the diff. That is a locator coin flip — `check` reports the same shape as
+ *    a finding — and it would turn a clean `healable` into `ambiguous`, i.e. make the
+ *    gate *worse* than no mask at all.
+ */
+export interface NameMask {
+    /** The pattern as written in config.json — also the value masked labels collapse to. */
+    raw: string;
+    regex: RegExp;
+}
+export type MaskRefusalReason = 'referenced-by-tests' | 'collision';
+export interface MaskRefusal {
+    pattern: string;
+    reason: MaskRefusalReason;
+    /** Human-readable specifics: which label, and where it is named. */
+    detail: string;
+}
+export interface MaskOutcome {
+    /** Patterns that took effect, with how many element labels each one collapsed. */
+    applied: Array<{
+        pattern: string;
+        count: number;
+    }>;
+    refused: MaskRefusal[];
+}
+/** Does the pattern keep anything a human could recognise the element by? */
+export declare function hasStablePart(pattern: string): boolean;
+/**
+ * Compile `config.nameMask`. Same glob dialect as `volatile` (`*` = anything,
+ * case-insensitive, whole-string) so there is one pattern language to learn, minus
+ * the field prefixes: a mask is about the accessible name and nothing else.
+ */
+export declare function parseNameMasks(patterns: string[] | undefined): NameMask[];
+/**
+ * The project's masks, or none.
+ *
+ * Tolerant of **absence** and nothing else: the MCP server diffs mapping files that
+ * may belong to no project at all, and the web tool has no config.json — both must
+ * keep behaving exactly as they did, which "no config ⇒ no masks" gives for free.
+ *
+ * A config that *exists* and is malformed is rethrown. Swallowing that would undo the
+ * whole point of validating `nameMask` at load: the user would get a diff that quietly
+ * ignored their declaration — a mask that does nothing, reported as nothing — which is
+ * precisely the silent failure the validation exists to make impossible.
+ */
+export declare function loadNameMasks(): NameMask[];
+export interface MaskedPair {
+    before: PageMapping;
+    after: PageMapping;
+    outcome: MaskOutcome;
+}
+/**
+ * Apply the surviving masks to in-memory copies of both mappings. The originals —
+ * and the files they were read from — are never touched.
+ */
+export declare function applyNameMasks(before: PageMapping, after: PageMapping, masks: NameMask[], usage: Usage | null): MaskedPair;
+/**
+ * The single door every verdict goes through.
+ *
+ * Every path that produces a verdict must apply the same policy — a `diff` and an
+ * MCP `diff_mappings` disagreeing about the same two files is the divergence this
+ * project treats as a defect — so no caller outside this module calls `diffMappings`
+ * directly, and a test asserts that.
+ *
+ * With no masks configured this returns `diffMappings(before, after)` and nothing
+ * else: no copies, no extra field, byte-identical output for every project that never
+ * writes a `nameMask` line.
+ */
+export declare function diffWithMasks(before: PageMapping, after: PageMapping, masks: NameMask[], usage?: Usage | null): ReturnType<typeof diffMappings> & {
+    nameMask?: MaskOutcome;
+};
+/** Union of per-page outcomes, for a directory verdict. */
+export declare function mergeMaskOutcomes(outcomes: Array<MaskOutcome | undefined>): MaskOutcome | undefined;

package/dist/nameMask.js.map

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

package/dist/ui/icon.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The console's desktop icon.
+ *
+ * Windows will not take a PNG for a shortcut's `IconLocation` — it wants an
+ * `.ico`, an `.exe` or a `.dll`. Converting an image normally means a native
+ * encoder, which this package will not take on: `sharp`/`jimp` for one desktop
+ * icon would be a heavier dependency than the entire tool.
+ *
+ * It does not need one. Since Vista, an ICO entry may hold a **PNG verbatim**
+ * instead of a BMP, so the conversion is a 22-byte header wrapped around bytes
+ * we already have. No decoding, no re-encoding, no dependency, and the result
+ * is byte-identical every run.
+ *
+ * Layout, all little-endian:
+ *
+ *   ICONDIR       6 bytes   reserved=0, type=1 (icon), count
+ *   ICONDIRENTRY 16 bytes   w, h, palette=0, reserved=0, planes=1, bpp=32,
+ *                           byteLength, offset
+ *   …the PNG file itself
+ */
+export declare const ICO_HEADER_BYTES = 22;
+/** Width/height from a PNG's IHDR, which is always the first chunk. */
+export declare function pngSize(png: Buffer): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Wrap a PNG in an ICO container. Returns null for anything that is not a PNG,
+ * rather than producing a file Windows would silently refuse to draw.
+ *
+ * A dimension of 256 is written as 0 — that is the format's own convention for
+ * "256", and it is why sizes above 256 cannot be expressed at all.
+ */
+export declare function pngToIco(png: Buffer): Buffer | null;
+/**
+ * The brand logo shipped in the tarball. `assets/` must stay in package.json →
+ * `files` or this resolves to a path that only exists in the repo — the same
+ * trap `skills/` has (a test pins both).
+ */
+export declare function brandLogoPath(): string;
+export declare function readBrandLogo(): Buffer | null;

package/dist/ui/icon.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICO_HEADER_BYTES = void 0;
+exports.pngSize = pngSize;
+exports.pngToIco = pngToIco;
+exports.brandLogoPath = brandLogoPath;
+exports.readBrandLogo = readBrandLogo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * The console's desktop icon.
+ *
+ * Windows will not take a PNG for a shortcut's `IconLocation` — it wants an
+ * `.ico`, an `.exe` or a `.dll`. Converting an image normally means a native
+ * encoder, which this package will not take on: `sharp`/`jimp` for one desktop
+ * icon would be a heavier dependency than the entire tool.
+ *
+ * It does not need one. Since Vista, an ICO entry may hold a **PNG verbatim**
+ * instead of a BMP, so the conversion is a 22-byte header wrapped around bytes
+ * we already have. No decoding, no re-encoding, no dependency, and the result
+ * is byte-identical every run.
+ *
+ * Layout, all little-endian:
+ *
+ *   ICONDIR       6 bytes   reserved=0, type=1 (icon), count
+ *   ICONDIRENTRY 16 bytes   w, h, palette=0, reserved=0, planes=1, bpp=32,
+ *                           byteLength, offset
+ *   …the PNG file itself
+ */
+exports.ICO_HEADER_BYTES = 22;
+/** Width/height from a PNG's IHDR, which is always the first chunk. */
+function pngSize(png) {
+    const SIGNATURE = '89504e470d0a1a0a';
+    if (png.length < 24 || png.subarray(0, 8).toString('hex') !== SIGNATURE)
+        return null;
+    return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+}
+/**
+ * Wrap a PNG in an ICO container. Returns null for anything that is not a PNG,
+ * rather than producing a file Windows would silently refuse to draw.
+ *
+ * A dimension of 256 is written as 0 — that is the format's own convention for
+ * "256", and it is why sizes above 256 cannot be expressed at all.
+ */
+function pngToIco(png) {
+    const size = pngSize(png);
+    if (!size)
+        return null;
+    if (size.width > 256 || size.height > 256)
+        return null;
+    const header = Buffer.alloc(exports.ICO_HEADER_BYTES);
+    header.writeUInt16LE(0, 0); // reserved
+    header.writeUInt16LE(1, 2); // type: icon
+    header.writeUInt16LE(1, 4); // one image
+    header.writeUInt8(size.width === 256 ? 0 : size.width, 6);
+    header.writeUInt8(size.height === 256 ? 0 : size.height, 7);
+    header.writeUInt8(0, 8); // palette colours: none, it is truecolour
+    header.writeUInt8(0, 9); // reserved
+    header.writeUInt16LE(1, 10); // colour planes
+    header.writeUInt16LE(32, 12); // bits per pixel
+    header.writeUInt32LE(png.length, 14);
+    header.writeUInt32LE(exports.ICO_HEADER_BYTES, 18);
+    return Buffer.concat([header, png]);
+}
+/**
+ * The brand logo shipped in the tarball. `assets/` must stay in package.json →
+ * `files` or this resolves to a path that only exists in the repo — the same
+ * trap `skills/` has (a test pins both).
+ */
+function brandLogoPath() {
+    // dist/ui/icon.js → package root
+    return path.join(__dirname, '..', '..', 'assets', 'logoKawaiiGreenTiny.png');
+}
+function readBrandLogo() {
+    try {
+        return fs.readFileSync(brandLogoPath());
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=icon.js.map

package/dist/ui/icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon.js","sourceRoot":"","sources":["../../src/ui/icon.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,0BAIC;AASD,4BAkBC;AAOD,sCAGC;AAED,sCAMC;AA5ED,uCAAyB;AACzB,2CAA6B;AAE7B;;;;;;;;;;;;;;;;;;;GAmBG;AAEU,QAAA,gBAAgB,GAAG,EAAE,CAAC;AAEnC,uEAAuE;AACvE,SAAgB,OAAO,CAAC,GAAW;IACjC,MAAM,SAAS,GAAG,kBAAkB,CAAC;IACrC,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrF,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,GAAW;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,KAAK,GAAG,GAAG,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,wBAAgB,CAAC,CAAC;IAC9C,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;IACvC,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa;IACzC,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY;IACxC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,0CAA0C;IACnE,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;IACpC,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB;IAC7C,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB;IAC/C,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,CAAC,aAAa,CAAC,wBAAgB,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa;IAC3B,iCAAiC;IACjC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,yBAAyB,CAAC,CAAC;AAC/E,CAAC;AAED,SAAgB,aAAa;IAC3B,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/ui/lock.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Who is already serving this project's console — `.ia-qa/ui.lock`.
+ *
+ * The console is opened by clicking something, and people click twice. Without
+ * this, the second click either fails on a port collision or starts a *second*
+ * server with a *different* token, leaving an orphan process and a browser tab
+ * that will 401 the moment the first one is closed. Neither is explicable to
+ * the person who clicked.
+ *
+ * So the lock holds the port and the token, and a launcher that finds a live
+ * console simply opens it. The file is a hint, never an authority: it is
+ * verified by an actual request before being believed (a lock left behind by a
+ * killed process is the normal case, not the exception), and it lives next to
+ * the contracts because that is what it is scoped to — one console per project
+ * directory, not one per machine.
+ *
+ * It holds a session token, so it is a file to gitignore, like `_shots/`.
+ */
+export declare const UI_LOCK_FILENAME = "ui.lock";
+export interface UiLock {
+    port: number;
+    token: string;
+    pid: number;
+    startedAt: string;
+}
+export declare function lockPath(cwd?: string): string;
+export declare function writeLock(lock: UiLock): void;
+export declare function clearLock(): void;
+export declare function readLock(): UiLock | null;
+/**
+ * Is the console named by the lock actually answering?
+ *
+ * Checked with a real request rather than by testing whether the pid exists: a
+ * pid can be reused, and what matters is not that *something* is alive but that
+ * it is a console that accepts this token. Short timeout — this runs before a
+ * human sees anything, so a stale lock must not cost them a visible pause.
+ */
+export declare function probe(lock: UiLock, timeoutMs?: number): Promise<boolean>;
+/** The URL of a console already serving this project, or null. */
+export declare function findRunningConsole(): Promise<string | null>;

package/dist/ui/lock.js

@@ -0,0 +1,138 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_LOCK_FILENAME = void 0;
+exports.lockPath = lockPath;
+exports.writeLock = writeLock;
+exports.clearLock = clearLock;
+exports.readLock = readLock;
+exports.probe = probe;
+exports.findRunningConsole = findRunningConsole;
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+/**
+ * Who is already serving this project's console — `.ia-qa/ui.lock`.
+ *
+ * The console is opened by clicking something, and people click twice. Without
+ * this, the second click either fails on a port collision or starts a *second*
+ * server with a *different* token, leaving an orphan process and a browser tab
+ * that will 401 the moment the first one is closed. Neither is explicable to
+ * the person who clicked.
+ *
+ * So the lock holds the port and the token, and a launcher that finds a live
+ * console simply opens it. The file is a hint, never an authority: it is
+ * verified by an actual request before being believed (a lock left behind by a
+ * killed process is the normal case, not the exception), and it lives next to
+ * the contracts because that is what it is scoped to — one console per project
+ * directory, not one per machine.
+ *
+ * It holds a session token, so it is a file to gitignore, like `_shots/`.
+ */
+exports.UI_LOCK_FILENAME = 'ui.lock';
+function lockPath(cwd = (0, config_1.baseDir)()) {
+    return path.join(cwd, config_1.CONFIG_DIR, exports.UI_LOCK_FILENAME);
+}
+function writeLock(lock) {
+    try {
+        fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+        // 0600: it carries the session token, and the console it unlocks can edit
+        // test files. On Windows the mode is advisory, which is why the token is
+        // random per process and dies with it rather than being a stored secret.
+        fs.writeFileSync(lockPath(), JSON.stringify(lock), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        /* a console that cannot write its lock still works; it just cannot be found */
+    }
+}
+function clearLock() {
+    try {
+        fs.unlinkSync(lockPath());
+    }
+    catch {
+        /* already gone */
+    }
+}
+function readLock() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(lockPath(), 'utf8'));
+        if (!Number.isInteger(raw.port) || typeof raw.token !== 'string' || raw.token === '')
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is the console named by the lock actually answering?
+ *
+ * Checked with a real request rather than by testing whether the pid exists: a
+ * pid can be reused, and what matters is not that *something* is alive but that
+ * it is a console that accepts this token. Short timeout — this runs before a
+ * human sees anything, so a stale lock must not cost them a visible pause.
+ */
+function probe(lock, timeoutMs = 700) {
+    return new Promise((resolve) => {
+        const req = http.get({
+            host: '127.0.0.1',
+            port: lock.port,
+            path: `/api/state?t=${encodeURIComponent(lock.token)}`,
+            timeout: timeoutMs,
+            headers: { Host: `127.0.0.1:${lock.port}` },
+        }, (res) => {
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.on('error', () => resolve(false));
+    });
+}
+/** The URL of a console already serving this project, or null. */
+async function findRunningConsole() {
+    const lock = readLock();
+    if (!lock)
+        return null;
+    if (!(await probe(lock))) {
+        clearLock();
+        return null;
+    }
+    return `http://127.0.0.1:${lock.port}/?t=${lock.token}`;
+}
+//# sourceMappingURL=lock.js.map

package/dist/ui/lock.js.map

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

package/dist/ui/page.d.ts

@@ -0,0 +1 @@
+export declare function renderConsoleHtml(token: string): string;