@avivbenhamo/polly-kit 0.1.0 → 0.3.0

package/dist/studio/stores/fs-store.d.ts

@@ -0,0 +1,70 @@
+import type { RecordingStore, RecordingSummary, ReadResult } from './types.js';
+import type { Har, ResponsePatch } from '../types.js';
+export { StoreError } from './types.js';
+export type { RecordingStore, RecordingSummary, ReadResult } from './types.js';
+/**
+ * Polly's node-server writes with `fs.outputJsonSync(path, data, { spaces: 2 })`, which
+ * routes through `jsonfile`'s `stringify` — `JSON.stringify(obj, null, 2)` plus a final
+ * newline, since `finalEOL` defaults to true (`jsonfile/utils.js`). Matching it exactly,
+ * trailing newline included, is what keeps an edit showing up in git as the lines that
+ * changed rather than as a rewritten file — asserted directly in the tests.
+ */
+export declare function serializeHar(har: Har): string;
+export declare class FsStore implements RecordingStore {
+    readonly root: string;
+    constructor(recordingsDir: string);
+    /**
+     * Every `recording.har` under the root, corrupt ones included.
+     *
+     * A missing directory is an empty list, not an error: a project that has not recorded
+     * anything yet is a normal state. Corrupt files are listed with the parse error —
+     * this is the only place a truncated recording is distinguishable from one that was
+     * never written.
+     */
+    list(): Promise<RecordingSummary[]>;
+    private recordingIds;
+    private describe;
+    read(id: string): Promise<ReadResult>;
+    /**
+     * Read-compare-write, then temp-file-and-rename.
+     *
+     * The etag compare is what turns two people editing the same recording into a
+     * refusal instead of a lost edit. The rename is what stops a crash mid-write from
+     * leaving a half-written file — the exact state Polly can only respond to by asking
+     * the user to delete their recording. The temp file is a sibling of the target, so
+     * the rename never crosses a device, which on Windows would fail outright.
+     */
+    write(id: string, har: Har, etag: string): Promise<void>;
+    /**
+     * Removes the recording's own file, then tidies up the directory it sat in if that
+     * leaves it empty.
+     *
+     * Deleting the *directory* would be wrong: `recordingIds` can legitimately emit both
+     * `Suite/case` and `Suite/case/sub`, because Polly builds ids from nested describe/it
+     * names, so a recursive remove of `Suite/case` would take `Suite/case/sub` with it —
+     * silently, since `force` swallows the evidence. Only `ENOTEMPTY`/`ENOENT` (and
+     * `EEXIST`, which some Node builds report for a non-empty directory on Windows) are
+     * swallowed here; anything else is a real failure and is rethrown.
+     */
+    delete(id: string): Promise<void>;
+    patchEntry(id: string, entryId: string, order: number, etag: string, patch: ResponsePatch): Promise<ReadResult>;
+    deleteEntry(id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+    /**
+     * Polly's own node-server does `path.join(recordingsDir, recording, 'recording.har')`
+     * with no sanitisation, and here the id arrives off an HTTP request. Resolving and
+     * checking containment is the difference between a recordings browser and an
+     * arbitrary-file reader.
+     *
+     * `isAbsolute` is the Windows clause. When the candidate lands on another root —
+     * `D:\secrets`, a drive-relative `D:foo`, a UNC `\\server\share`, or the `\\?\` device
+     * namespace — `relative` cannot express a route there and hands back the absolute
+     * target instead, which starts with neither `..` nor a separator and re-resolves to
+     * itself. Every other clause passes it.
+     *
+     * `rel === FILENAME` is the id that contributed no path segment at all: `''`, `'.'`,
+     * `'a/..'`. Each resolves to `<root>/recording.har`, whose parent is the root itself,
+     * so `delete` would have removed every recording. Checking `rel === ''` cannot catch
+     * them — `FILENAME` is appended before `relative` is taken, so `rel` is never empty.
+     */
+    private pathFor;
+}

package/dist/studio/stores/fs-store.js

@@ -0,0 +1,186 @@
+import { mkdir, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseHar } from '../har.js';
+import { etagFor } from '../etag.js';
+import { StoreError } from './types.js';
+import { deleteEntryVia, patchEntryVia } from './apply.js';
+export { StoreError } from './types.js';
+const FILENAME = 'recording.har';
+/**
+ * Polly's node-server writes with `fs.outputJsonSync(path, data, { spaces: 2 })`, which
+ * routes through `jsonfile`'s `stringify` — `JSON.stringify(obj, null, 2)` plus a final
+ * newline, since `finalEOL` defaults to true (`jsonfile/utils.js`). Matching it exactly,
+ * trailing newline included, is what keeps an edit showing up in git as the lines that
+ * changed rather than as a rewritten file — asserted directly in the tests.
+ */
+export function serializeHar(har) {
+    return `${JSON.stringify(har, null, 2)}\n`;
+}
+export class FsStore {
+    constructor(recordingsDir) {
+        this.root = resolve(recordingsDir);
+    }
+    /**
+     * Every `recording.har` under the root, corrupt ones included.
+     *
+     * A missing directory is an empty list, not an error: a project that has not recorded
+     * anything yet is a normal state. Corrupt files are listed with the parse error —
+     * this is the only place a truncated recording is distinguishable from one that was
+     * never written.
+     */
+    async list() {
+        const ids = await this.recordingIds(this.root, '');
+        const summaries = await Promise.all(ids.sort().map((id) => this.describe(id)));
+        return summaries;
+    }
+    async recordingIds(dir, prefix) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const found = [];
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === FILENAME && prefix !== '') {
+                found.push(prefix);
+            }
+            else if (entry.isDirectory()) {
+                const child = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+                found.push(...(await this.recordingIds(join(dir, entry.name), child)));
+            }
+        }
+        return found;
+    }
+    async describe(id) {
+        const base = {
+            id,
+            entryCount: 0,
+            recordingName: null,
+            problem: null,
+            pollyWillReject: null,
+        };
+        let raw;
+        try {
+            raw = await readFile(this.pathFor(id), 'utf8');
+        }
+        catch (err) {
+            return { ...base, problem: err instanceof Error ? err.message : String(err) };
+        }
+        const parsed = parseHar(raw);
+        if (!parsed.ok)
+            return { ...base, problem: parsed.problem };
+        return {
+            ...base,
+            entryCount: parsed.har.log.entries.length,
+            recordingName: parsed.har.log._recordingName ?? null,
+            pollyWillReject: parsed.pollyWillReject,
+        };
+    }
+    async read(id) {
+        const path = this.pathFor(id);
+        let raw;
+        try {
+            raw = await readFile(path, 'utf8');
+        }
+        catch {
+            throw new StoreError('not-found', `no recording with id ${id}`);
+        }
+        const parsed = parseHar(raw);
+        if (!parsed.ok)
+            throw new StoreError('not-found', `recording ${id} is unreadable: ${parsed.problem}`);
+        return { har: parsed.har, etag: etagFor(raw), pollyWillReject: parsed.pollyWillReject };
+    }
+    /**
+     * Read-compare-write, then temp-file-and-rename.
+     *
+     * The etag compare is what turns two people editing the same recording into a
+     * refusal instead of a lost edit. The rename is what stops a crash mid-write from
+     * leaving a half-written file — the exact state Polly can only respond to by asking
+     * the user to delete their recording. The temp file is a sibling of the target, so
+     * the rename never crosses a device, which on Windows would fail outright.
+     */
+    async write(id, har, etag) {
+        const path = this.pathFor(id);
+        let current;
+        try {
+            current = await readFile(path, 'utf8');
+        }
+        catch {
+            throw new StoreError('not-found', `no recording with id ${id}`);
+        }
+        if (etagFor(current) !== etag) {
+            throw new StoreError('conflict', `recording ${id} changed on disk since it was read — reload before saving`);
+        }
+        await mkdir(join(path, '..'), { recursive: true });
+        const temp = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temp, serializeHar(har), 'utf8');
+            await rename(temp, path);
+        }
+        catch (err) {
+            await unlink(temp).catch(() => { });
+            throw err;
+        }
+    }
+    /**
+     * Removes the recording's own file, then tidies up the directory it sat in if that
+     * leaves it empty.
+     *
+     * Deleting the *directory* would be wrong: `recordingIds` can legitimately emit both
+     * `Suite/case` and `Suite/case/sub`, because Polly builds ids from nested describe/it
+     * names, so a recursive remove of `Suite/case` would take `Suite/case/sub` with it —
+     * silently, since `force` swallows the evidence. Only `ENOTEMPTY`/`ENOENT` (and
+     * `EEXIST`, which some Node builds report for a non-empty directory on Windows) are
+     * swallowed here; anything else is a real failure and is rethrown.
+     */
+    async delete(id) {
+        const path = this.pathFor(id);
+        await rm(path, { force: true });
+        try {
+            await rmdir(join(path, '..'));
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOTEMPTY' && code !== 'ENOENT' && code !== 'EEXIST')
+                throw err;
+        }
+    }
+    patchEntry(id, entryId, order, etag, patch) {
+        return patchEntryVia(this, id, entryId, order, etag, patch);
+    }
+    deleteEntry(id, entryId, order, etag) {
+        return deleteEntryVia(this, id, entryId, order, etag);
+    }
+    /**
+     * Polly's own node-server does `path.join(recordingsDir, recording, 'recording.har')`
+     * with no sanitisation, and here the id arrives off an HTTP request. Resolving and
+     * checking containment is the difference between a recordings browser and an
+     * arbitrary-file reader.
+     *
+     * `isAbsolute` is the Windows clause. When the candidate lands on another root —
+     * `D:\secrets`, a drive-relative `D:foo`, a UNC `\\server\share`, or the `\\?\` device
+     * namespace — `relative` cannot express a route there and hands back the absolute
+     * target instead, which starts with neither `..` nor a separator and re-resolves to
+     * itself. Every other clause passes it.
+     *
+     * `rel === FILENAME` is the id that contributed no path segment at all: `''`, `'.'`,
+     * `'a/..'`. Each resolves to `<root>/recording.har`, whose parent is the root itself,
+     * so `delete` would have removed every recording. Checking `rel === ''` cannot catch
+     * them — `FILENAME` is appended before `relative` is taken, so `rel` is never empty.
+     */
+    pathFor(id) {
+        const candidate = resolve(this.root, id, FILENAME);
+        const rel = relative(this.root, candidate);
+        if (rel === FILENAME ||
+            isAbsolute(rel) ||
+            rel.startsWith('..') ||
+            rel.startsWith(`${sep}..`) ||
+            resolve(this.root, rel) !== candidate) {
+            throw new StoreError('forbidden', `recording id ${id} resolves outside the recordings directory`);
+        }
+        return candidate;
+    }
+}

package/dist/studio/stores/http-store.d.ts

@@ -0,0 +1,30 @@
+import type { RecordingStore, RecordingSummary, ReadResult } from './types.js';
+import type { Har, ResponsePatch } from '../types.js';
+/**
+ * The store the page uses under the Node mount. It exists so `mountStudio` can be
+ * written once: to the page this is indistinguishable from `LocalStorageStore`.
+ *
+ * `patchEntry` and `deleteEntry` are one request each, because the read-apply-write
+ * cycle belongs on the server side of the network — shipping a whole HAR back to be
+ * written would double the payload and widen the window a conflicting write can land in.
+ * `write` and `delete` exist to satisfy the interface and are refused; the UI never
+ * calls them.
+ */
+export declare class HttpStore implements RecordingStore {
+    readonly basePath: string;
+    constructor(basePath: string);
+    list(): Promise<RecordingSummary[]>;
+    read(id: string): Promise<ReadResult>;
+    /**
+     * Not on the wire protocol. The UI edits through `patchEntry`/`deleteEntry`. The
+     * parameters are declared (and ignored) rather than dropped so a caller holding a
+     * concrete `HttpStore` — not just a `RecordingStore` — can still call this with the
+     * interface's arity; TypeScript checks a direct call against the class's own
+     * declared signature, not the interface it implements.
+     */
+    write(id: string, har: Har, etag: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    patchEntry(id: string, entryId: string, order: number, etag: string, patch: ResponsePatch): Promise<ReadResult>;
+    deleteEntry(id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+    private json;
+}

package/dist/studio/stores/http-store.js

@@ -0,0 +1,67 @@
+import { StoreError } from './types.js';
+/**
+ * The store the page uses under the Node mount. It exists so `mountStudio` can be
+ * written once: to the page this is indistinguishable from `LocalStorageStore`.
+ *
+ * `patchEntry` and `deleteEntry` are one request each, because the read-apply-write
+ * cycle belongs on the server side of the network — shipping a whole HAR back to be
+ * written would double the payload and widen the window a conflicting write can land in.
+ * `write` and `delete` exist to satisfy the interface and are refused; the UI never
+ * calls them.
+ */
+export class HttpStore {
+    constructor(basePath) {
+        this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    }
+    async list() {
+        const body = (await this.json('GET', '/api/recordings'));
+        return body.recordings;
+    }
+    async read(id) {
+        return (await this.json('GET', `/api/recordings/${encodeURIComponent(id)}`));
+    }
+    /**
+     * Not on the wire protocol. The UI edits through `patchEntry`/`deleteEntry`. The
+     * parameters are declared (and ignored) rather than dropped so a caller holding a
+     * concrete `HttpStore` — not just a `RecordingStore` — can still call this with the
+     * interface's arity; TypeScript checks a direct call against the class's own
+     * declared signature, not the interface it implements.
+     */
+    async write(id, har, etag) {
+        throw new StoreError('forbidden', 'the HTTP API applies edits itself — use patchEntry');
+    }
+    async delete(id) {
+        throw new StoreError('forbidden', 'deleting a whole recording is not exposed over the API');
+    }
+    async patchEntry(id, entryId, order, etag, patch) {
+        return (await this.json('PATCH', `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}`, { etag, patch }));
+    }
+    async deleteEntry(id, entryId, order, etag) {
+        return (await this.json('DELETE', `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}?etag=${encodeURIComponent(etag)}`));
+    }
+    async json(method, path, body) {
+        const res = await fetch(`${this.basePath}${path}`, {
+            method,
+            ...(body === undefined
+                ? {}
+                : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }),
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        if (res.ok)
+            return parsed;
+        // A 404/409/403 from the API means the same thing a StoreError means, so the page
+        // sees one error type whichever store it happens to be holding.
+        const code = res.status === 404
+            ? 'not-found'
+            : res.status === 409
+                ? 'conflict'
+                : res.status === 403
+                    ? 'forbidden'
+                    : res.status === 422
+                        ? 'unprocessable'
+                        : null;
+        if (code !== null)
+            throw new StoreError(code, parsed.error ?? `${method} ${path} failed`);
+        throw new Error(parsed.error ?? `${method} ${path} failed with ${res.status}`);
+    }
+}

package/dist/studio/stores/local-storage-store.d.ts

@@ -0,0 +1,25 @@
+import type { RecordingStore, RecordingSummary, ReadResult } from './types.js';
+import type { Har, ResponsePatch } from '../types.js';
+export interface LocalStorageStoreOptions {
+    key?: string;
+    storage?: Storage;
+}
+/**
+ * The store for an app that has no server at all. `@pollyjs/persister-local-storage`
+ * keeps every recording in one key holding `{ [recordingId]: har }`, so there is no
+ * directory to walk and no file to rename — but the interface the page renders against
+ * is the same one `FsStore` implements, and the page cannot tell which it has.
+ */
+export declare class LocalStorageStore implements RecordingStore {
+    private readonly key;
+    private readonly storage;
+    constructor(options?: LocalStorageStoreOptions);
+    list(): Promise<RecordingSummary[]>;
+    read(id: string): Promise<ReadResult>;
+    write(id: string, har: Har, etag: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    patchEntry(id: string, entryId: string, order: number, etag: string, patch: ResponsePatch): Promise<ReadResult>;
+    deleteEntry(id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+    /** `null` means the key holds something that is not JSON, which `list` reports. */
+    private db;
+}

package/dist/studio/stores/local-storage-store.js

@@ -0,0 +1,109 @@
+import { parseHar } from '../har.js';
+import { etagFor } from '../etag.js';
+import { StoreError } from './types.js';
+import { deleteEntryVia, patchEntryVia } from './apply.js';
+/** Polly's default namespace. `persisterOptions.local-storage.key` can change it. */
+const DEFAULT_KEY = 'pollyjs';
+/**
+ * The store for an app that has no server at all. `@pollyjs/persister-local-storage`
+ * keeps every recording in one key holding `{ [recordingId]: har }`, so there is no
+ * directory to walk and no file to rename — but the interface the page renders against
+ * is the same one `FsStore` implements, and the page cannot tell which it has.
+ */
+export class LocalStorageStore {
+    constructor(options = {}) {
+        this.key = options.key ?? DEFAULT_KEY;
+        const storage = options.storage ?? globalThis.localStorage;
+        if (storage === undefined) {
+            throw new Error('polly-studio: no localStorage available — pass one as options.storage');
+        }
+        this.storage = storage;
+    }
+    async list() {
+        const db = this.db();
+        if (db === null) {
+            return [
+                {
+                    id: this.key,
+                    entryCount: 0,
+                    recordingName: null,
+                    problem: `localStorage[${this.key}] is not valid JSON`,
+                    pollyWillReject: null,
+                },
+            ];
+        }
+        return Object.keys(db)
+            .sort()
+            .map((id) => {
+            const parsed = parseHar(JSON.stringify(db[id]));
+            if (!parsed.ok) {
+                return { id, entryCount: 0, recordingName: null, problem: parsed.problem, pollyWillReject: null };
+            }
+            return {
+                id,
+                entryCount: parsed.har.log.entries.length,
+                recordingName: parsed.har.log._recordingName ?? null,
+                problem: null,
+                pollyWillReject: parsed.pollyWillReject,
+            };
+        });
+    }
+    async read(id) {
+        const db = this.db();
+        if (db === null) {
+            throw new StoreError('not-found', `localStorage[${this.key}] is not valid JSON`);
+        }
+        const record = db[id];
+        if (record === undefined)
+            throw new StoreError('not-found', `no recording with id ${id}`);
+        const raw = JSON.stringify(record);
+        const parsed = parseHar(raw);
+        if (!parsed.ok)
+            throw new StoreError('not-found', `recording ${id} is unreadable: ${parsed.problem}`);
+        return { har: parsed.har, etag: etagFor(raw), pollyWillReject: parsed.pollyWillReject };
+    }
+    async write(id, har, etag) {
+        const db = this.db();
+        if (db === null) {
+            throw new StoreError('not-found', `localStorage[${this.key}] is not valid JSON`);
+        }
+        const record = db[id];
+        if (record === undefined)
+            throw new StoreError('not-found', `no recording with id ${id}`);
+        if (etagFor(JSON.stringify(record)) !== etag) {
+            throw new StoreError('conflict', `recording ${id} changed since it was read — reload before saving`);
+        }
+        db[id] = har;
+        this.storage.setItem(this.key, JSON.stringify(db));
+    }
+    async delete(id) {
+        const db = this.db();
+        if (db === null) {
+            // Coalescing to `{}` here would rewrite the key as `'{}'` and discard whatever
+            // was actually in the corrupt blob — a delete must never launder unrelated data
+            // it never touched. Refuse instead, same as a write would.
+            throw new StoreError('unprocessable', `localStorage[${this.key}] is not valid JSON — refusing to delete, which would discard it`);
+        }
+        delete db[id];
+        this.storage.setItem(this.key, JSON.stringify(db));
+    }
+    patchEntry(id, entryId, order, etag, patch) {
+        return patchEntryVia(this, id, entryId, order, etag, patch);
+    }
+    deleteEntry(id, entryId, order, etag) {
+        return deleteEntryVia(this, id, entryId, order, etag);
+    }
+    /** `null` means the key holds something that is not JSON, which `list` reports. */
+    db() {
+        const raw = this.storage.getItem(this.key);
+        if (raw === null)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed !== null && typeof parsed === 'object' ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/studio/stores/types.d.ts

@@ -0,0 +1,45 @@
+import type { Har, ResponsePatch } from '../types.js';
+export interface RecordingSummary {
+    /** The recordingId. May contain slashes: Polly builds it from describe/it names. */
+    id: string;
+    entryCount: number;
+    recordingName: string | null;
+    /** Why the recording could not be read. Non-null exactly when it could not. */
+    problem: string | null;
+    /** Readable, but Polly's own `findRecording` will assert on it. */
+    pollyWillReject: string | null;
+}
+export interface ReadResult {
+    har: Har;
+    /** Content hash of what was read. Hand it back to `write` to detect a clash. */
+    etag: string;
+    pollyWillReject: string | null;
+}
+/**
+ * The one interface the page renders against. Three implementations exist — the
+ * filesystem, localStorage, and an HTTP client — and the page cannot tell them apart,
+ * which is what lets one UI serve a Node mount and a browser-only mount unchanged.
+ */
+export interface RecordingStore {
+    list(): Promise<RecordingSummary[]>;
+    read(id: string): Promise<ReadResult>;
+    write(id: string, har: Har, etag: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * The two edits the UI performs, as store operations rather than as "read, apply, and
+     * hand a whole HAR back".
+     *
+     * They are on the interface so `mountStudio` never has to ask which store it holds.
+     * `HttpStore` implements them as one request each, because the read-apply-write cycle
+     * belongs on the server side of the network; the local stores implement them by
+     * calling `applyEntryEdit`. Both return the recording as it now stands, so the caller
+     * always leaves holding a fresh etag.
+     */
+    patchEntry(id: string, entryId: string, order: number, etag: string, patch: ResponsePatch): Promise<ReadResult>;
+    deleteEntry(id: string, entryId: string, order: number, etag: string): Promise<ReadResult>;
+}
+export type StoreErrorCode = 'not-found' | 'conflict' | 'forbidden' | 'unprocessable';
+export declare class StoreError extends Error {
+    readonly code: StoreErrorCode;
+    constructor(code: StoreErrorCode, message: string);
+}

package/dist/studio/stores/types.js

@@ -0,0 +1,7 @@
+export class StoreError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'StoreError';
+        this.code = code;
+    }
+}

package/dist/studio/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The HAR shape Polly 6.0.6 writes. Only the fields this package reads or maintains
+ * are named; anything else in the file rides along untouched through `structuredClone`.
+ *
+ * Field-by-field provenance is in the spec, §2 and §5.
+ */
+/**
+ * A HAR name/value pair. `_fromType` is Polly's own addition: it marks a header whose
+ * recorded value was an array, so that `normalizeHeaders` replays it as an array even
+ * when only one value survives. Dropping it silently changes what the app receives.
+ */
+export interface NvPair {
+    name: string;
+    value: string;
+    _fromType?: 'array';
+    comment?: string;
+}
+export interface HarContent {
+    mimeType: string;
+    /** The stored body. Base64 text when `encoding` is `'base64'`. */
+    text?: string;
+    /** `'base64'` for a binary body, absent otherwise. Read at replay. */
+    encoding?: string;
+    size: number;
+}
+export interface HarResponse {
+    httpVersion: string;
+    status: number;
+    statusText: string;
+    headers: NvPair[];
+    headersSize: number;
+    cookies: unknown[];
+    redirectURL: string;
+    content: HarContent;
+    bodySize: number;
+}
+export interface HarRequest {
+    httpVersion: string;
+    url: string;
+    method: string;
+    headers: NvPair[];
+    headersSize: number;
+    queryString: NvPair[];
+    cookies: unknown[];
+    postData?: {
+        mimeType: string;
+        params: unknown[];
+        text?: string;
+    };
+    bodySize: number;
+}
+export interface HarEntry {
+    /** md5 of the normalized request. Never recomputed here — see spec §3. */
+    _id: string;
+    /** Count of earlier same-`_id` requests in this recording, from 0. */
+    _order: number;
+    /** Read by Polly's `expiresIn` check and used to sort entries. Preserved on edit. */
+    startedDateTime: string;
+    request: HarRequest;
+    response: HarResponse;
+    cache: Record<string, unknown>;
+    timings: Record<string, number>;
+    time: number;
+}
+export interface HarLog {
+    version: string;
+    creator: {
+        name: string;
+        version: string;
+        comment?: string;
+    };
+    _recordingName?: string;
+    entries: HarEntry[];
+    pages: unknown[];
+    browser?: {
+        name: string;
+        version: string;
+    };
+}
+export interface Har {
+    log: HarLog;
+}
+/**
+ * What the UI may change about a response. `bodyText` is always *decoded* text: the
+ * caller never deals in base64, `applyResponsePatch` re-encodes when the entry needs it.
+ */
+export interface ResponsePatch {
+    status?: number;
+    statusText?: string;
+    headers?: NvPair[];
+    bodyText?: string;
+}

package/dist/studio/types.js

@@ -0,0 +1,7 @@
+/**
+ * The HAR shape Polly 6.0.6 writes. Only the fields this package reads or maintains
+ * are named; anything else in the file rides along untouched through `structuredClone`.
+ *
+ * Field-by-field provenance is in the spec, §2 and §5.
+ */
+export {};

package/dist/studio/ui/app.d.ts

@@ -0,0 +1,12 @@
+import type { RecordingStore } from '../stores/types.js';
+/**
+ * The page's behaviour, written against `RecordingStore` and nothing else. Under the
+ * Node mount the store is an `HttpStore`; in a browser-only app it is a
+ * `LocalStorageStore`. Nothing below can tell the difference — no branch on which store
+ * it holds, which is why `patchEntry` and `deleteEntry` are on the interface rather than
+ * being assembled here out of `read` and `write`.
+ *
+ * Every mutation re-reads afterwards rather than trusting the local copy: the etag that
+ * the next save depends on comes from the store, never from here.
+ */
+export declare function mountStudio(root: Document | Element, store: RecordingStore): void;