@mintlify/previewing 4.0.1461 → 4.0.1463

package/dist/__tests__/packages-dev.test.js

@@ -0,0 +1,1304 @@
+import { getFileCategory, isMintIgnored } from '@mintlify/common';
+import { collectLocalFiles, } from '@mintlify/package-builder';
+import fse from 'fs-extra';
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+const heldRead = vi.hoisted(() => ({
+    current: undefined,
+}));
+vi.mock('fs/promises', async (importOriginal) => {
+    const actual = await importOriginal();
+    const readFile = actual.readFile;
+    return {
+        ...actual,
+        readFile: async (...args) => {
+            const data = await readFile(...args);
+            const hold = heldRead.current;
+            if (hold && String(args[0]).endsWith(hold.file)) {
+                heldRead.current = undefined;
+                hold.reached = true;
+                await hold.until;
+            }
+            return data;
+        },
+    };
+});
+import { PACKAGE_BUILD_PROPS_FILE, PackagesDev, } from '../local-preview/packages/dev.js';
+import { getPackageImportOptions, setPackageImportOptions, } from '../local-preview/packages/state.js';
+import { collectPackageIslands } from '../packages/collect.js';
+const page = (stroke) => `import { LineChart, Line } from "recharts";
+
+<LineChart width={400} height={200} data={[{ v: 1 }]}>
+  <Line dataKey="v" strokeWidth={${stroke}} />
+</LineChart>
+`;
+const fakeBuild = (mode) => async (input) => {
+    const missingLocalFiles = [];
+    const localFiles = Object.keys(collectLocalFiles({
+        docsRoot: input.docsRoot,
+        islands: input.islands,
+        snippetFiles: input.snippetFiles,
+        provider: input.packages.provider,
+        onMissing: (file) => missingLocalFiles.push(file),
+    })).sort();
+    await mode.building;
+    if (mode.throwing)
+        throw new Error('EACCES: permission denied');
+    const ids = input.islands.map((island) => island.id).sort();
+    const buildId = `b${ids.join('').slice(0, 30)}`;
+    const manifest = {
+        version: 1,
+        builderVersion: 'test',
+        buildId,
+        depsHash: 'd',
+        islandsHash: 'i',
+        react: { version: '18.3.1', domVersion: '18.3.1' },
+        packages: {},
+        css: [],
+        clientAccess: { version: 1, files: {}, globalFiles: [] },
+        islands: {},
+        files: [],
+        diagnostics: mode.missingNodeModules
+            ? [{ level: 'error', code: 'install-missing-node-modules', message: 'No node_modules.' }]
+            : mode.failing
+                ? [
+                    {
+                        level: 'error',
+                        code: mode.failCode ?? 'bundle-failed',
+                        message: 'Could not resolve "recharts".',
+                    },
+                ]
+                : [],
+    };
+    await fse.ensureDir(input.outDir);
+    if (!mode.missingNodeModules) {
+        for (const id of ids) {
+            await fse.outputFile(join(input.outDir, 'client/islands', `${id}.js`), 'export {}');
+            manifest.files.push({
+                path: `client/islands/${id}.js`,
+                bytes: 9,
+                gzipBytes: 9,
+                integrity: 'sha384-fixture',
+            });
+            manifest.clientAccess.files[`client/islands/${id}.js`] = [id];
+            if (mode.islandCss) {
+                await fse.outputFile(join(input.outDir, 'client/islands', `${id}.css`), 'a{}');
+                manifest.files.push({
+                    path: `client/islands/${id}.css`,
+                    bytes: 3,
+                    gzipBytes: 3,
+                    integrity: 'sha384-css',
+                });
+                manifest.clientAccess.files[`client/islands/${id}.css`] = [id];
+            }
+            manifest.islands[id] = {
+                entry: `client/islands/${id}.js`,
+                prefix: `mi-${id}-`,
+                html: `<svg data-id="${id}"></svg>`,
+                ...(mode.islandCss && {
+                    css: [{ path: `client/islands/${id}.css`, integrity: 'sha384-css', bytes: 3 }],
+                }),
+            };
+        }
+        await fse.outputFile(join(input.outDir, 'client/styles.css'), 'a{}');
+        manifest.css.push({ path: 'client/styles.css', integrity: 'sha384-x', bytes: 3 });
+        manifest.files.push({
+            path: 'client/styles.css',
+            integrity: 'sha384-x',
+            bytes: 3,
+            gzipBytes: 3,
+        });
+        manifest.clientAccess.files['client/styles.css'] = [];
+        manifest.clientAccess.globalFiles.push('client/styles.css');
+    }
+    return {
+        ok: !mode.missingNodeModules && !mode.failing,
+        manifest,
+        localFiles,
+        missingLocalFiles: missingLocalFiles.sort(),
+        stats: {
+            installMs: 0,
+            bundleMs: 0,
+            renderMs: 0,
+            totalMs: 0,
+            clientBytes: 0,
+            clientGzipBytes: 0,
+            serverBytes: 0,
+            islandClientGzipBytes: {},
+            reactDirs: { react: [], 'react-dom': [] },
+        },
+    };
+};
+const reporter = () => {
+    const calls = [];
+    return {
+        calls,
+        building: () => calls.push('building'),
+        built: () => calls.push('built'),
+        failed: (errors) => calls.push(`failed ${errors.join(',')}`),
+        missingNodeModules: () => calls.push('missing'),
+        islandErrors: (errors) => {
+            if (errors.length > 0)
+                calls.push(`islandErrors ${errors.join(',')}`);
+        },
+        configError: (message) => calls.push(`configError ${message}`),
+    };
+};
+const until = async (condition) => {
+    for (let i = 0; i < 200; i++) {
+        if (await condition())
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error('condition not met');
+};
+describe('PackagesDev', () => {
+    let root;
+    let docsRoot;
+    let propsPath;
+    let buildsDir;
+    let mode;
+    let rebuilt;
+    let dev;
+    let report;
+    const props = async () => fse.readJson(join(propsPath, PACKAGE_BUILD_PROPS_FILE));
+    const create = (overrides = {}) => new PackagesDev({
+        docsRoot,
+        buildsDir,
+        propsPath,
+        onRebuilt: () => {
+            rebuilt++;
+        },
+        reporter: report,
+        debounceMs: 0,
+        pollMs: 10,
+        build: fakeBuild(mode),
+        ...overrides,
+    });
+    beforeEach(async () => {
+        root = await mkdtemp(join(tmpdir(), 'packages-dev-'));
+        docsRoot = join(root, 'docs');
+        propsPath = join(root, 'props');
+        buildsDir = join(root, 'builds');
+        mode = { missingNodeModules: false };
+        rebuilt = 0;
+        report = reporter();
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputJson(join(docsRoot, 'package.json'), { dependencies: { recharts: '2.15.4' } });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(2));
+        dev = create();
+    });
+    afterEach(async () => {
+        await dev.close();
+        setPackageImportOptions(undefined);
+        await rm(root, { recursive: true, force: true });
+    });
+    it('builds on start and writes the build for the local compile', async () => {
+        await fse.outputFile(join(propsPath, 'charts.mdx'), 'compiled by prebuild');
+        await dev.init();
+        expect(await fse.pathExists(join(propsPath, 'charts.mdx'))).toBe(true);
+        const written = await props();
+        const [id] = Object.keys(written.islands);
+        expect(written.baseUrl).toMatch(/^\/_mintlify\/pkg\/bi[0-9a-f]+-1$/);
+        expect(written.islands[id ?? '']).toEqual({
+            prefix: `mi-${id}-`,
+            html: `<svg data-id="${id}"></svg>`,
+        });
+        expect(written.packageNames).toEqual(['recharts']);
+        expect(written.css.map((css) => css.path)).toEqual(['client/styles.css']);
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+        expect(getPackageImportOptions()?.packageNames).toEqual(new Set(['recharts']));
+        expect(await fse.readdir(buildsDir)).toEqual([written.baseUrl.split('/').pop()]);
+        expect(dev.routeState().enabled).toBe(true);
+    });
+    it('preserves global and island CSS references in local compile props', async () => {
+        mode.islandCss = true;
+        await dev.init();
+        const written = await props();
+        const [id] = Object.keys(written.islands);
+        expect(written.css).toEqual([{ path: 'client/styles.css', integrity: 'sha384-x', bytes: 3 }]);
+        expect(written.islands[id ?? '']?.css).toEqual([
+            { path: `client/islands/${id}.css`, integrity: 'sha384-css', bytes: 3 },
+        ]);
+        expect(written.baseUrl).not.toContain('/pages/');
+    });
+    it('adds a changed island right away and swaps in the rebuild', async () => {
+        await dev.init();
+        rebuilt = 0;
+        const before = await props();
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        const change = dev.onFileChange('charts.mdx', 'page');
+        await change;
+        const pending = await props();
+        const [newId] = Object.keys(pending.islands);
+        expect(Object.keys(before.islands)).not.toContain(newId);
+        expect(pending.baseUrl).toBe(before.baseUrl);
+        expect(pending.islands[newId ?? '']?.html).toBeUndefined();
+        expect(dev.getStatus()).toEqual({ state: 'building' });
+        await until(async () => (await props()).baseUrl !== before.baseUrl);
+        const after = await props();
+        expect(after.islands[newId ?? '']?.html).toContain(newId);
+        expect(rebuilt).toBe(1);
+        expect((await fse.readdir(buildsDir)).sort()).toEqual([before.baseUrl, after.baseUrl].map((url) => url.split('/').pop()).sort());
+    });
+    it('keeps listing the islands edits drop until the next build finishes', async () => {
+        await dev.init();
+        const [built] = Object.keys((await props()).islands);
+        let release = () => { };
+        mode.building = new Promise((resolve) => {
+            release = resolve;
+        });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        await dev.onFileChange('charts.mdx', 'page');
+        const [added] = Object.keys((await props()).islands);
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(4));
+        await dev.onFileChange('charts.mdx', 'page');
+        const pending = (await props()).islands;
+        release();
+        const [current] = Object.keys(pending);
+        expect(Object.keys(pending).sort()).toEqual([current, added, built].sort());
+        expect(pending[built ?? '']?.html).toBe(`<svg data-id="${built}"></svg>`);
+        expect(pending[added ?? '']?.html).toBeUndefined();
+        expect(pending[current ?? '']?.html).toBeUndefined();
+        const settled = {
+            [current ?? '']: { prefix: `mi-${current}-`, html: `<svg data-id="${current}"></svg>` },
+        };
+        await until(async () => JSON.stringify((await props()).islands) === JSON.stringify(settled));
+    });
+    it('rebuilds when a page edit is undone while its build runs', async () => {
+        await dev.init();
+        rebuilt = 0;
+        const before = (await props()).islands;
+        let release = () => { };
+        mode.building = new Promise((resolve) => {
+            release = resolve;
+        });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        await dev.onFileChange('charts.mdx', 'page');
+        await until(() => report.calls.filter((call) => call === 'building').length === 2);
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(2));
+        await dev.onFileChange('charts.mdx', 'page');
+        release();
+        await until(() => rebuilt === 2);
+        expect((await props()).islands).toEqual(before);
+    });
+    it('re-extracts the islands of a <Snippet file> when the snippet changes', async () => {
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), '<Snippet file="chart.mdx" />\n');
+        await fse.outputFile(join(docsRoot, '_snippets/chart.mdx'), page(2));
+        await dev.init();
+        rebuilt = 0;
+        const before = Object.keys((await props()).islands);
+        expect(before).toHaveLength(1);
+        await fse.outputFile(join(docsRoot, '_snippets/chart.mdx'), page(3));
+        await dev.onFileChange('_snippets/chart.mdx', 'snippet');
+        await until(() => rebuilt === 1);
+        const after = Object.keys((await props()).islands);
+        expect(after).toHaveLength(1);
+        expect(after).not.toEqual(before);
+    });
+    it('retries replacing the props file while another process has it open', async () => {
+        const rename = fse.rename.bind(fse);
+        let thrown = 0;
+        const spy = vi.spyOn(fse, 'rename').mockImplementation(async (from, to) => {
+            if (String(to).endsWith(PACKAGE_BUILD_PROPS_FILE) && thrown < 2) {
+                thrown++;
+                throw Object.assign(new Error('EPERM: operation not permitted, rename'), { code: 'EPERM' });
+            }
+            return rename(from, to);
+        });
+        try {
+            await dev.init();
+            expect(thrown).toBe(2);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            expect((await props()).packageNames).toEqual(['recharts']);
+        }
+        finally {
+            spy.mockRestore();
+        }
+    });
+    it('serializes concurrent props writes', async () => {
+        await dev.init();
+        await Promise.all(Array.from({ length: 5 }, () => dev.writeProps()));
+        expect((await props()).packageNames).toEqual(['recharts']);
+        expect((await fse.readdir(propsPath)).filter((file) => file.endsWith('.tmp'))).toEqual([]);
+    });
+    it('never lets a slow props write overwrite a newer one', async () => {
+        await dev.init();
+        rebuilt = 0;
+        const before = await props();
+        const outputFile = fse.outputFile.bind(fse);
+        let delayed = false;
+        const spy = vi.spyOn(fse, 'outputFile').mockImplementation(async (file, data) => {
+            if (!delayed && String(file).includes(PACKAGE_BUILD_PROPS_FILE)) {
+                delayed = true;
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+            return outputFile(file, data);
+        });
+        try {
+            const slow = dev.writeProps();
+            await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+            await Promise.all([slow, dev.onFileChange('charts.mdx', 'page')]);
+            await until(() => rebuilt === 1);
+            const after = await props();
+            expect(after.baseUrl).not.toBe(before.baseUrl);
+            expect(Object.keys(after.islands)).not.toEqual(Object.keys(before.islands));
+            expect(Object.values(after.islands).every((island) => island.html !== undefined)).toBe(true);
+        }
+        finally {
+            spy.mockRestore();
+        }
+    });
+    it('keeps a page edit that lands while every page is being re-collected', async () => {
+        await fse.outputFile(join(docsRoot, 'area.mdx'), page(5));
+        await dev.init();
+        let release = () => { };
+        const hold = {
+            file: join(docsRoot, 'charts.mdx'),
+            until: new Promise((resolve) => {
+                release = resolve;
+            }),
+            reached: false,
+        };
+        heldRead.current = hold;
+        await dev.onFileChange('.mintignore', 'mintIgnore');
+        await until(() => hold.reached);
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        const change = dev.onFileChange('charts.mdx', 'page');
+        await Promise.race([change, new Promise((resolve) => setTimeout(resolve, 200))]);
+        release();
+        await change;
+        const expected = await collectPackageIslands({
+            docsRoot,
+            packageNames: new Set(['recharts']),
+        });
+        const ids = JSON.stringify(expected.islands.map((island) => island.id).sort());
+        await until(async () => {
+            const after = await props();
+            return (JSON.stringify(Object.keys(after.islands).sort()) === ids &&
+                Object.values(after.islands).every((island) => island.html !== undefined));
+        });
+    });
+    it('keeps collecting when a page vanishes while every page is being re-collected', async () => {
+        await fse.outputFile(join(docsRoot, 'area.mdx'), page(5));
+        await dev.init();
+        rebuilt = 0;
+        let vanish = (_error) => { };
+        const hold = {
+            file: join(docsRoot, 'area.mdx'),
+            until: new Promise((_resolve, reject) => {
+                vanish = reject;
+            }),
+            reached: false,
+        };
+        heldRead.current = hold;
+        await fse.outputFile(join(docsRoot, 'added.mdx'), page(7));
+        const change = dev.onFileChange('added.mdx', 'page');
+        await until(() => hold.reached);
+        await fse.remove(join(docsRoot, 'area.mdx'));
+        vanish(Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' }));
+        await change;
+        await dev.onFileChange('area.mdx', 'page');
+        const expected = (await collectPackageIslands({ docsRoot, packageNames: new Set(['recharts']) })).islands
+            .map((island) => island.id)
+            .sort();
+        await until(async () => {
+            const after = await props();
+            return (JSON.stringify(Object.keys(after.islands).sort()) === JSON.stringify(expected) &&
+                Object.values(after.islands).every((island) => island.html !== undefined));
+        });
+        expect(report.calls.filter((call) => call.startsWith('failed'))).toEqual([]);
+    });
+    it('waits for the running build when closed', async () => {
+        await dev.init();
+        rebuilt = 0;
+        let release = () => { };
+        mode.building = new Promise((resolve) => {
+            release = resolve;
+        });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        await dev.onFileChange('charts.mdx', 'page');
+        await until(() => report.calls.filter((call) => call === 'building').length === 2);
+        let closed = false;
+        const closing = dev.close().then(() => {
+            closed = true;
+        });
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        expect(closed).toBe(false);
+        release();
+        await closing;
+        expect(rebuilt).toBe(1);
+    });
+    it('skips the rebuild when a page edit keeps the same islands', async () => {
+        await dev.init();
+        rebuilt = 0;
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), `${page(2)}\nMore prose.\n`);
+        await dev.onFileChange('charts.mdx', 'page');
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(rebuilt).toBe(0);
+    });
+    it('ignores markdown that is neither a page nor a snippet', async () => {
+        await dev.init();
+        rebuilt = 0;
+        report.calls.length = 0;
+        for (const file of [
+            'contribute.md',
+            'guides/contribute.md',
+            'skill.md',
+            '.mintlify/skills/docs/skill.md',
+        ]) {
+            expect(isMintIgnored(file)).toBe(false);
+            await fse.outputFile(join(docsRoot, file), page(3));
+            await dev.onFileChange(file, getFileCategory(file));
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(rebuilt).toBe(0);
+        expect(report.calls).toEqual([]);
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+        await dev.onFileChange('charts.mdx', 'page');
+        await until(() => rebuilt === 1);
+    });
+    it('keeps serving pages without node_modules and rebuilds once they appear', async () => {
+        mode.missingNodeModules = true;
+        await dev.init();
+        const written = await props();
+        expect(written.baseUrl).toBe('/_mintlify/pkg/pending');
+        expect(Object.values(written.islands).every((island) => island.html === undefined)).toBe(true);
+        expect(dev.getStatus()).toEqual({ state: 'missing-node-modules' });
+        expect(report.calls).toContain('missing');
+        mode.missingNodeModules = false;
+        await fse.outputFile(join(docsRoot, 'node_modules/.package-lock.json'), '{}');
+        await until(async () => (await props()).baseUrl !== '/_mintlify/pkg/pending');
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+    });
+    it('rebuilds once an install without a known marker settles node_modules', async () => {
+        mode.missingNodeModules = true;
+        await dev.init();
+        expect(dev.getStatus()).toEqual({ state: 'missing-node-modules' });
+        mode.missingNodeModules = false;
+        mode.failing = true;
+        await fse.outputJson(join(docsRoot, 'node_modules/react/package.json'), { version: '18.3.1' });
+        await until(() => dev.getStatus().state === 'failed');
+        mode.failing = false;
+        await fse.outputJson(join(docsRoot, 'node_modules/recharts/package.json'), {
+            version: '2.15.4',
+        });
+        await until(() => dev.getStatus().state === 'ready');
+        expect((await props()).baseUrl).not.toBe('/_mintlify/pkg/pending');
+    });
+    it('waits for the installer marker instead of a half-written node_modules when a lockfile exists', async () => {
+        await fse.outputJson(join(docsRoot, 'package-lock.json'), { lockfileVersion: 3, packages: {} });
+        mode.missingNodeModules = true;
+        await dev.init();
+        mode.missingNodeModules = false;
+        await fse.outputJson(join(docsRoot, 'node_modules/recharts/package.json'), {
+            version: '2.15.4',
+        });
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        expect(dev.getStatus()).toEqual({ state: 'missing-node-modules' });
+        expect(report.calls.filter((call) => call === 'building')).toHaveLength(1);
+        await fse.outputFile(join(docsRoot, 'node_modules/.package-lock.json'), '{}');
+        await until(() => dev.getStatus().state === 'ready');
+    });
+    it('rebuilds a successful build with dependency drift when the install settles, then stops watching', async () => {
+        const marker = join(docsRoot, 'node_modules/.package-lock.json');
+        const installedVersion = join(docsRoot, 'node_modules/installed-version.txt');
+        await fse.outputJson(join(docsRoot, 'package-lock.json'), { lockfileVersion: 3, packages: {} });
+        await fse.outputFile(marker, '{}');
+        await fse.outputFile(installedVersion, '1.0.0');
+        const build = fakeBuild(mode);
+        await dev.close();
+        dev = create({
+            build: async (input) => {
+                const version = await fse.readFile(installedVersion, 'utf8');
+                const result = await build(input);
+                for (const island of Object.values(result.manifest.islands))
+                    island.html = version;
+                if (version === '1.0.0') {
+                    result.manifest.diagnostics.push({
+                        level: 'warning',
+                        code: 'local-node-modules-drift',
+                        message: 'The installed dependency does not match the lockfile.',
+                    });
+                }
+                return result;
+            },
+        });
+        await dev.init();
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+        expect(Object.values((await props()).islands).map((island) => island.html)).toEqual(['1.0.0']);
+        await fse.writeFile(installedVersion, '2.0.0');
+        await fse.writeFile(marker, '{"installed":true}');
+        await until(() => rebuilt === 2);
+        expect(Object.values((await props()).islands).map((island) => island.html)).toEqual(['2.0.0']);
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+        await fse.writeFile(marker, '{"installed":true,"saved":true}');
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        expect(rebuilt).toBe(2);
+    });
+    it('rebuilds local inputs changed while disabled before the running build finishes', async () => {
+        const helper = join(docsRoot, 'snippets/label.js');
+        const before = 'export default "before";\n';
+        const after = 'export default "after";\n';
+        await fse.outputFile(helper, before);
+        await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), 'import { LineChart } from "recharts";\nimport label from "./label.js";\nexport const Card = () => <LineChart label={label} />;\n');
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), 'import { Card } from "/snippets/card.jsx";\n\n<Card />\n');
+        const build = fakeBuild(mode);
+        let reached = () => { };
+        await dev.close();
+        dev = create({
+            build: async (input) => {
+                const content = await fse.readFile(helper, 'utf8');
+                reached();
+                const result = await build(input);
+                for (const island of Object.values(result.manifest.islands))
+                    island.html = content;
+                return result;
+            },
+        });
+        await dev.init();
+        expect(Object.values((await props()).islands).map((island) => island.html)).toEqual([before]);
+        let release = () => { };
+        mode.building = new Promise((resolve) => {
+            release = resolve;
+        });
+        const started = new Promise((resolve) => {
+            reached = resolve;
+        });
+        try {
+            await dev.onFileChange('package.json', getFileCategory('package.json'));
+            await started;
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await fse.writeFile(helper, after);
+            await dev.onFileChange('snippets/label.js', 'js');
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+            await dev.onFileChange('docs.json', 'docsConfig');
+        }
+        finally {
+            mode.building = undefined;
+            release();
+        }
+        await until(async () => Object.values((await props()).islands).some((island) => island.html === after));
+        expect(Object.values((await props()).islands).map((island) => island.html)).toEqual([after]);
+        expect(report.calls.filter((call) => call === 'building')).toHaveLength(3);
+        expect(report.calls.filter((call) => call === 'built')).toHaveLength(2);
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+    });
+    describe('after a build fails', () => {
+        const failOnce = () => {
+            const builds = fakeBuild(mode);
+            return create({
+                build: async (input) => {
+                    try {
+                        return await builds(input);
+                    }
+                    finally {
+                        mode.failing = false;
+                        mode.throwing = false;
+                    }
+                },
+            });
+        };
+        const saveManifest = async () => {
+            await fse.outputJson(join(docsRoot, 'package.json'), {
+                dependencies: { recharts: '2.15.4', '@acme/ui': '1.0.0' },
+            });
+            await dev.onFileChange('package.json', getFileCategory('package.json'));
+        };
+        const marker = () => join(docsRoot, 'node_modules/.package-lock.json');
+        beforeEach(async () => {
+            await fse.outputJson(join(docsRoot, 'package-lock.json'), {
+                lockfileVersion: 3,
+                packages: {},
+            });
+            await fse.outputFile(marker(), '{}');
+            await dev.close();
+            dev = failOnce();
+            await dev.init();
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+        });
+        it.each([
+            ['a bundle error', { failing: true, failCode: 'bundle-error' }],
+            ['a missing react', { failing: true, failCode: 'react-missing' }],
+            ['a thrown error', { throwing: true }],
+        ])('retries a build that failed with %s only once the install settles', async (_, failure) => {
+            const builds = () => report.calls.filter((call) => call === 'building').length;
+            Object.assign(mode, failure);
+            report.calls.length = 0;
+            await saveManifest();
+            await until(() => dev.getStatus().state === 'failed');
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            expect(dev.getStatus().state).toBe('failed');
+            expect(builds()).toBe(1);
+            await fse.outputFile(marker(), '{"packages":{}}');
+            await until(() => dev.getStatus().state === 'ready');
+            expect(builds()).toBe(2);
+        });
+        it('retries a failed build when the install settles while it runs', async () => {
+            let release = () => { };
+            mode.building = new Promise((resolve) => {
+                release = resolve;
+            });
+            mode.failing = true;
+            report.calls.length = 0;
+            await saveManifest();
+            await until(() => report.calls.includes('building'));
+            await fse.outputFile(marker(), '{"packages":{}}');
+            mode.building = undefined;
+            release();
+            await until(() => dev.getStatus().state === 'ready');
+            expect(report.calls).toEqual([
+                'building',
+                'failed Could not resolve "recharts".',
+                'building',
+                'built',
+            ]);
+        });
+        it('retries on the next page save even when its islands did not change', async () => {
+            mode.failing = true;
+            await saveManifest();
+            await until(() => dev.getStatus().state === 'failed');
+            rebuilt = 0;
+            await fse.outputFile(join(docsRoot, 'charts.mdx'), `${page(2)}\nMore prose.\n`);
+            await dev.onFileChange('charts.mdx', 'page');
+            await until(() => rebuilt === 1);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+        });
+    });
+    describe('when adopting a finished build fails', () => {
+        const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+        const failOnce = (name, fails, message, before) => {
+            const original = fse[name].bind(fse);
+            let thrown = false;
+            return vi.spyOn(fse, name).mockImplementation((async (...args) => {
+                if (!thrown && fails(String(args[0]), args[1], before)) {
+                    thrown = true;
+                    throw new Error(message);
+                }
+                return original(...args);
+            }));
+        };
+        it.each([
+            ['moving it into place', 'EXDEV: cross-device link not permitted', 'move', () => true],
+            [
+                'pruning old builds',
+                'EBUSY: resource busy or locked',
+                'remove',
+                (target) => target === join(buildsDir, 'stale'),
+            ],
+            [
+                'writing package-build.json',
+                'ENOSPC: no space left on device',
+                'outputFile',
+                (target, data, before) => target.includes(PACKAGE_BUILD_PROPS_FILE) && !String(data).includes(before.baseUrl),
+            ],
+        ])('keeps the last build when %s fails, cleans up and retries on the next save', async (_, message, name, fails) => {
+            await dev.init();
+            const before = await props();
+            const builtId = before.baseUrl.split('/').pop();
+            await fse.ensureDir(join(buildsDir, 'stale'));
+            const spy = failOnce(name, fails, message, before);
+            try {
+                await dev.onFileChange('package.json', getFileCategory('package.json'));
+                await until(() => dev.getStatus().state === 'failed');
+                await settle();
+            }
+            finally {
+                spy.mockRestore();
+            }
+            expect(dev.getStatus()).toEqual({ state: 'failed', message });
+            expect(report.calls.filter((call) => call.startsWith('failed'))).toEqual([
+                `failed ${message}`,
+            ]);
+            expect(await props()).toEqual(before);
+            expect((await fse.readdir(buildsDir)).filter((entry) => entry !== 'stale')).toEqual([
+                builtId,
+            ]);
+            await fse.outputFile(join(docsRoot, 'charts.mdx'), `${page(2)}\nMore prose.\n`);
+            await dev.onFileChange('charts.mdx', 'page');
+            await until(() => dev.getStatus().state === 'ready');
+            const after = await props();
+            expect(after.baseUrl).not.toBe(before.baseUrl);
+            expect((await fse.readdir(buildsDir)).sort()).toEqual([builtId, after.baseUrl.split('/').pop()].sort());
+        });
+    });
+    it('stays off without a packages key and turns on when docs.json adds one', async () => {
+        const mtime = async (file) => (await fse.stat(join(propsPath, file))).mtimeMs;
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
+        await dev.init();
+        expect(dev.enabled).toBe(false);
+        expect(dev.routeState().enabled).toBe(false);
+        expect(getPackageImportOptions()).toBeUndefined();
+        expect(await fse.pathExists(join(propsPath, PACKAGE_BUILD_PROPS_FILE))).toBe(false);
+        expect(await fse.pathExists(buildsDir)).toBe(false);
+        await dev.onFileChange('charts.mdx', 'page');
+        expect(rebuilt).toBe(0);
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await fse.outputFile(join(propsPath, 'charts.mdx'), 'compiled without packages');
+        await fse.outputFile(join(propsPath, 'generated.mdx'), 'generated page');
+        await dev.onFileChange('docs.json', 'docsConfig');
+        expect(await mtime('charts.mdx')).toBe(0);
+        expect(await mtime('generated.mdx')).toBeGreaterThan(0);
+        await until(() => rebuilt === 1);
+        expect(dev.enabled).toBe(true);
+        expect((await props()).baseUrl).toMatch(/^\/_mintlify\/pkg\/b/);
+        await fse.outputFile(join(propsPath, 'charts.mdx'), 'stale compile');
+        await fse.outputJson(join(docsRoot, 'package.json'), {
+            dependencies: { recharts: '2.15.4', '@acme/ui': '1.0.0' },
+        });
+        await dev.onFileChange('package.json', getFileCategory('package.json'));
+        expect(await mtime('charts.mdx')).toBe(0);
+        expect(await mtime('generated.mdx')).toBeGreaterThan(0);
+        await until(() => rebuilt === 2);
+    });
+    describe('an invalid packages value', () => {
+        const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+        it('starts with packages off, shows the schema errors and turns on once it is valid', async () => {
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: 'nope' });
+            await fse.outputJson(join(propsPath, PACKAGE_BUILD_PROPS_FILE), { baseUrl: '/stale' });
+            await dev.init();
+            expect(dev.enabled).toBe(false);
+            expect(dev.getStatus()).toEqual({ state: 'disabled' });
+            expect(getPackageImportOptions()).toBeUndefined();
+            expect(await fse.pathExists(join(propsPath, PACKAGE_BUILD_PROPS_FILE))).toBe(false);
+            expect(await fse.pathExists(buildsDir)).toBe(false);
+            expect(rebuilt).toBe(0);
+            expect(report.calls).toEqual([
+                'configError docs.json packages: Expected object, received string. Packages stay off until docs.json is fixed.',
+            ]);
+            report.calls.length = 0;
+            await fse.outputJson(join(docsRoot, 'docs.json'), {
+                name: 'Docs',
+                packages: { provider: '../provider.jsx', isolation: 'none' },
+            });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await settle();
+            expect(dev.enabled).toBe(false);
+            expect(rebuilt).toBe(0);
+            expect(report.calls).toEqual([
+                'configError docs.json packages.provider: Provider path cannot contain `..` segments',
+                "configError docs.json packages.isolation: Invalid enum value. Expected 'page' | 'frame', received 'none'. Packages stay off until docs.json is fixed.",
+            ]);
+            report.calls.length = 0;
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await until(() => rebuilt === 1);
+            expect(dev.enabled).toBe(true);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            expect((await props()).baseUrl).toMatch(/^\/_mintlify\/pkg\/b/);
+            expect(report.calls).toEqual(['building', 'built']);
+        });
+        it('keeps the last packages setup and shows the schema errors until it is valid again', async () => {
+            const regenerateSnippets = vi.fn(async () => { });
+            await dev.close();
+            dev = create({ regenerateSnippets });
+            await dev.init();
+            const built = await props();
+            const importOptions = getPackageImportOptions();
+            await fse.outputFile(join(propsPath, 'charts.mdx'), 'compiled with packages');
+            rebuilt = 0;
+            report.calls.length = 0;
+            await fse.outputJson(join(docsRoot, 'docs.json'), {
+                name: 'Docs',
+                packages: { css: ['./styles.css'] },
+            });
+            await fse.outputJson(join(docsRoot, 'package.json'), {
+                dependencies: { recharts: '2.15.4', '@acme/ui': '1.0.0' },
+            });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await settle();
+            expect(dev.enabled).toBe(true);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            expect(getPackageImportOptions()).toBe(importOptions);
+            expect(await props()).toEqual(built);
+            expect(await fse.pathExists(join(propsPath, 'charts.mdx'))).toBe(true);
+            expect(regenerateSnippets).not.toHaveBeenCalled();
+            expect(rebuilt).toBe(0);
+            expect(report.calls).toEqual([
+                'configError docs.json packages.css.0: CSS entries must be paths inside an installed package, such as `@acme/ui/dist/styles.css`. Keeping the last package setup until docs.json is fixed.',
+            ]);
+            await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+            await dev.onFileChange('charts.mdx', 'page');
+            await until(() => rebuilt === 1);
+            expect((await props()).packageNames).toEqual(['recharts']);
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            expect(regenerateSnippets).toHaveBeenCalledTimes(1);
+            await until(() => rebuilt === 2);
+            expect((await props()).packageNames).toEqual(['@acme/ui', 'recharts']);
+        });
+    });
+    it('collects with the new docs.json variables while keeping the last packages setup', async () => {
+        const chart = `import { LineChart, Line } from "recharts";
+
+<LineChart width={400} height={200} data={[{ v: 1, w: 2 }]}>
+  <Line dataKey="{{key}}" />
+</LineChart>
+`;
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            name: 'Docs',
+            packages: {},
+            variables: { key: 'v' },
+        });
+        await fse.outputFile(join(docsRoot, 'charts.mdx'), chart);
+        await dev.init();
+        rebuilt = 0;
+        report.calls.length = 0;
+        await fse.outputJson(join(docsRoot, 'docs.json'), {
+            name: 'Docs',
+            packages: { css: ['./styles.css'] },
+            variables: { key: 'w' },
+        });
+        await dev.onFileChange('docs.json', 'docsConfig');
+        await until(() => rebuilt === 1);
+        const expected = await collectPackageIslands({
+            docsRoot,
+            packageNames: new Set(['recharts']),
+            variables: { key: 'w' },
+        });
+        const [id] = expected.islands.map((island) => island.id);
+        expect(id).toBeDefined();
+        expect(Object.keys((await props()).islands)).toContain(id);
+        expect(report.calls[0]).toMatch(/Keeping the last package setup until docs\.json is fixed\.$/);
+    });
+    it('rebuilds when a root package manifest changes, going by its path', async () => {
+        await dev.init();
+        for (const file of ['package.json', 'package-lock.json', 'pnpm-lock.yaml']) {
+            rebuilt = 0;
+            await dev.onFileChange(file, getFileCategory(file));
+            await until(() => rebuilt === 1);
+        }
+        rebuilt = 0;
+        await dev.onFileChange('snippets/package.json', getFileCategory('snippets/package.json'));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(rebuilt).toBe(0);
+    });
+    describe('a docs.json that does not parse', () => {
+        const INVALID = '{ "name": "Docs", "packages": {}, }';
+        const parserMessage = (() => {
+            try {
+                JSON.parse(INVALID);
+                return '';
+            }
+            catch (error) {
+                return error.message;
+            }
+        })();
+        const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+        it('keeps the packages setup until it parses again', async () => {
+            const regenerateSnippets = vi.fn(async () => { });
+            await dev.close();
+            dev = create({ regenerateSnippets });
+            await dev.init();
+            const built = await props();
+            const importOptions = getPackageImportOptions();
+            await fse.outputFile(join(propsPath, 'charts.mdx'), 'compiled with packages');
+            rebuilt = 0;
+            report.calls.length = 0;
+            await fse.outputFile(join(docsRoot, 'docs.json'), INVALID);
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await settle();
+            expect(dev.enabled).toBe(true);
+            expect(dev.routeState().enabled).toBe(true);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            expect(getPackageImportOptions()).toBe(importOptions);
+            expect(await props()).toEqual(built);
+            expect(await fse.pathExists(join(propsPath, 'charts.mdx'))).toBe(true);
+            expect(regenerateSnippets).not.toHaveBeenCalled();
+            expect(rebuilt).toBe(0);
+            expect(report.calls).toEqual([
+                expect.stringContaining(`configError docs.json could not be loaded: ${parserMessage}`),
+            ]);
+            await fse.outputFile(join(docsRoot, 'charts.mdx'), page(3));
+            await dev.onFileChange('charts.mdx', 'page');
+            await until(() => rebuilt === 1);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await settle();
+            expect(regenerateSnippets).not.toHaveBeenCalled();
+            expect(rebuilt).toBe(1);
+            await fse.outputJson(join(docsRoot, 'package.json'), {
+                dependencies: { recharts: '2.15.4', '@acme/ui': '1.0.0' },
+            });
+            await dev.onFileChange('package.json', getFileCategory('package.json'));
+            expect(regenerateSnippets).toHaveBeenCalledTimes(1);
+            await until(() => rebuilt === 2);
+            expect((await props()).packageNames).toEqual(['@acme/ui', 'recharts']);
+        });
+        it('stays quiet for a project without packages', async () => {
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
+            await dev.init();
+            report.calls.length = 0;
+            for (const raw of ['', '{ "name": "Do', '\uFEFF{ "name": "Docs" }', '// c\n{}']) {
+                await fse.outputFile(join(docsRoot, 'docs.json'), raw);
+                await dev.onFileChange('docs.json', 'docsConfig');
+            }
+            await fse.remove(join(docsRoot, 'docs.json'));
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await settle();
+            expect(dev.enabled).toBe(false);
+            expect(report.calls).toEqual([]);
+            expect(rebuilt).toBe(0);
+        });
+        it('keeps the setup through empty, truncated, BOM and commented saves, then turns off when packages goes away', async () => {
+            const regenerateSnippets = vi.fn(async () => { });
+            await dev.close();
+            dev = create({ regenerateSnippets });
+            await dev.init();
+            const built = await props();
+            rebuilt = 0;
+            report.calls.length = 0;
+            const saves = ['', '{ "name": "Do', '\uFEFF{ "name": "Docs", "packages": {} }', '// c\n{}'];
+            for (const raw of saves) {
+                await fse.outputFile(join(docsRoot, 'docs.json'), raw);
+                await dev.onFileChange('docs.json', 'docsConfig');
+                await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+                await dev.onFileChange('docs.json', 'docsConfig');
+            }
+            await settle();
+            expect(dev.enabled).toBe(true);
+            expect(await props()).toEqual(built);
+            expect(regenerateSnippets).not.toHaveBeenCalled();
+            expect(rebuilt).toBe(0);
+            expect(report.calls).toHaveLength(saves.length);
+            expect(report.calls.every((call) => call.startsWith('configError docs.json'))).toBe(true);
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs' });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            expect(dev.enabled).toBe(false);
+            expect(regenerateSnippets).toHaveBeenCalledTimes(1);
+            expect(await fse.pathExists(join(propsPath, PACKAGE_BUILD_PROPS_FILE))).toBe(false);
+        });
+        it('turns packages off when docs.json is deleted', async () => {
+            await dev.init();
+            await fse.remove(join(docsRoot, 'docs.json'));
+            await dev.onFileChange('docs.json', 'docsConfig');
+            expect(dev.enabled).toBe(false);
+            expect(getPackageImportOptions()).toBeUndefined();
+            expect(await fse.pathExists(join(propsPath, PACKAGE_BUILD_PROPS_FILE))).toBe(false);
+        });
+        it('starts with packages off and turns them on once it parses', async () => {
+            await fse.outputFile(join(docsRoot, 'docs.json'), INVALID);
+            await fse.outputJson(join(propsPath, PACKAGE_BUILD_PROPS_FILE), { baseUrl: '/stale' });
+            await dev.init();
+            expect(dev.enabled).toBe(false);
+            expect(dev.getStatus()).toEqual({ state: 'disabled' });
+            expect(getPackageImportOptions()).toBeUndefined();
+            expect(await fse.pathExists(join(propsPath, PACKAGE_BUILD_PROPS_FILE))).toBe(false);
+            expect(await fse.pathExists(buildsDir)).toBe(false);
+            expect(report.calls).toEqual([]);
+            await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+            await dev.onFileChange('docs.json', 'docsConfig');
+            await until(() => rebuilt === 1);
+            expect(dev.enabled).toBe(true);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+            expect((await props()).baseUrl).toMatch(/^\/_mintlify\/pkg\/b/);
+        });
+    });
+    it('keeps the packages setup while package.json does not parse, and drops the names once it is deleted', async () => {
+        const regenerateSnippets = vi.fn(async () => { });
+        await dev.close();
+        dev = create({ regenerateSnippets });
+        await dev.init();
+        const built = await props();
+        const importOptions = getPackageImportOptions();
+        await fse.outputFile(join(propsPath, 'charts.mdx'), 'compiled with packages');
+        rebuilt = 0;
+        report.calls.length = 0;
+        const saves = ['', '{ "dependencies": { "recharts": ', '["recharts"]', 'null'];
+        for (const raw of saves) {
+            await fse.outputFile(join(docsRoot, 'package.json'), raw);
+            await dev.onFileChange('package.json', getFileCategory('package.json'));
+        }
+        await fse.outputJson(join(docsRoot, 'docs.json'), { name: 'Docs', packages: {} });
+        await dev.onFileChange('docs.json', 'docsConfig');
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(dev.enabled).toBe(true);
+        expect(dev.getStatus()).toEqual({ state: 'ready' });
+        expect(getPackageImportOptions()).toBe(importOptions);
+        expect(await props()).toEqual(built);
+        expect(await fse.pathExists(join(propsPath, 'charts.mdx'))).toBe(true);
+        expect(regenerateSnippets).not.toHaveBeenCalled();
+        expect(rebuilt).toBe(0);
+        const keeping = '. Keeping the last package setup until package.json is fixed.';
+        expect(report.calls).toEqual([
+            `configError package.json is not valid JSON: Unexpected end of JSON input${keeping}`,
+            `configError package.json is not valid JSON: Unexpected end of JSON input${keeping}`,
+            `configError package.json is not a JSON object${keeping}`,
+            `configError package.json is not a JSON object${keeping}`,
+            `configError package.json is not a JSON object${keeping}`,
+        ]);
+        await fse.outputJson(join(docsRoot, 'package.json'), { dependencies: { recharts: '2.15.4' } });
+        await dev.onFileChange('package.json', getFileCategory('package.json'));
+        await until(() => rebuilt === 1);
+        expect(regenerateSnippets).not.toHaveBeenCalled();
+        expect((await props()).packageNames).toEqual(['recharts']);
+        await fse.remove(join(docsRoot, 'package.json'));
+        await dev.onFileChange('package.json', getFileCategory('package.json'));
+        expect(regenerateSnippets).toHaveBeenCalledTimes(1);
+        expect(getPackageImportOptions()?.packageNames).toEqual(new Set());
+        expect((await props()).packageNames).toEqual([]);
+    });
+    describe('files the package build reads', () => {
+        const CARD = `import { LineChart } from "recharts";
+import "./card.css";
+
+export const Card = () => <LineChart width={400} height={200} data={[{ v: 1 }]} />;
+`;
+        const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+        const duringNextBuild = async (start, during) => {
+            let release = () => { };
+            mode.building = new Promise((resolve) => {
+                release = resolve;
+            });
+            report.calls.length = 0;
+            await start();
+            await until(() => report.calls.includes('building'));
+            mode.building = undefined;
+            await during();
+            release();
+        };
+        beforeEach(async () => {
+            await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), CARD);
+            await fse.outputFile(join(docsRoot, 'cards.mdx'), 'import { Card } from "/snippets/card.jsx";\n\n<Card />\n');
+            await fse.outputFile(join(docsRoot, 'style.css'), 'body { color: red; }\n');
+            await fse.outputFile(join(docsRoot, 'snippets/unused.css'), '.unused { color: red; }\n');
+        });
+        it('rebuilds when CSS or an asset a package snippet pulls in changes, not for other CSS', async () => {
+            await fse.outputFile(join(docsRoot, 'snippets/card.css'), '.card { background: url(./bg.png); }\n');
+            await fse.outputFile(join(docsRoot, 'snippets/bg.png'), new Uint8Array([1, 2, 3]));
+            await dev.init();
+            rebuilt = 0;
+            await fse.outputFile(join(docsRoot, 'style.css'), 'body { color: blue; }\n');
+            await dev.onFileChange('style.css', 'css');
+            await fse.outputFile(join(docsRoot, 'snippets/unused.css'), '.unused { color: blue; }\n');
+            await dev.onFileChange('snippets/unused.css', 'css');
+            await settle();
+            expect(rebuilt).toBe(0);
+            await fse.outputFile(join(docsRoot, 'snippets/card.css'), '.card { color: blue; background: url(./bg.png); }\n');
+            await dev.onFileChange('snippets/card.css', 'css');
+            await until(() => rebuilt === 1);
+            await fse.outputFile(join(docsRoot, 'snippets/bg.png'), new Uint8Array([4, 5, 6]));
+            await dev.onFileChange('snippets/bg.png', 'staticFile');
+            await until(() => rebuilt === 2);
+        });
+        it('rebuilds once a missing file a package snippet imports is created, even outside snippets', async () => {
+            await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), CARD.replace('./card.css', '../styles/card.css'));
+            mode.failing = true;
+            await dev.init();
+            expect(dev.getStatus().state).toBe('failed');
+            rebuilt = 0;
+            await dev.onFileChange('style.css', 'css');
+            await dev.onFileChange('snippets/unused.css', 'css');
+            await settle();
+            expect(rebuilt).toBe(0);
+            mode.failing = false;
+            await fse.outputFile(join(docsRoot, 'styles/card.css'), '.card { color: blue; }\n');
+            await dev.onFileChange('styles/card.css', 'css');
+            await until(() => rebuilt === 1);
+            expect(dev.getStatus()).toEqual({ state: 'ready' });
+        });
+        it('rebuilds when a file the running build reads for the first time changes mid-build', async () => {
+            await fse.outputFile(join(docsRoot, 'styles/card.css'), '.card { color: red; }\n');
+            await dev.init();
+            rebuilt = 0;
+            await duringNextBuild(async () => {
+                await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), CARD.replace('./card.css', '../styles/card.css'));
+                await dev.onFileChange('snippets/card.jsx', 'snippet-v2');
+            }, async () => {
+                await fse.outputFile(join(docsRoot, 'styles/card.css'), '.card { color: blue; }\n');
+                await dev.onFileChange('styles/card.css', 'css');
+            });
+            await until(() => rebuilt === 2);
+        });
+        it('does not rebuild again for an unrelated file that changes mid-build', async () => {
+            await dev.init();
+            rebuilt = 0;
+            await duringNextBuild(() => dev.onFileChange('snippets/card.jsx', 'snippet-v2'), () => dev.onFileChange('snippets/unused.css', 'css'));
+            await until(() => rebuilt >= 1);
+            await settle();
+            expect(rebuilt).toBe(1);
+        });
+        describe('after a build that threw', () => {
+            const write = async ({ file, content, category }) => {
+                await fse.outputFile(join(docsRoot, file), content);
+                await dev.onFileChange(file, category);
+            };
+            const css = (content) => ({
+                file: 'snippets/card.css',
+                content,
+                category: 'css',
+            });
+            beforeEach(async () => {
+                await fse.outputFile(join(docsRoot, 'snippets/card.css'), '.card { color: red; }\n');
+            });
+            it.each([
+                [
+                    'a stylesheet',
+                    {
+                        file: 'snippets/card.jsx',
+                        content: CARD.replace('./card.css', '../styles/new.css'),
+                        category: 'snippet-v2',
+                    },
+                    { file: 'styles/new.css', content: '.card { color: blue; }\n', category: 'css' },
+                ],
+                [
+                    'an image',
+                    css('.card { background: url(../images/hero.webp); }\n'),
+                    { file: 'images/hero.webp', content: 'webp', category: 'staticFile' },
+                ],
+                [
+                    'a font',
+                    css('@font-face { font-family: Inter; src: url(../fonts/inter.woff2); }\n'),
+                    { file: 'fonts/inter.woff2', content: 'woff2', category: 'staticFile' },
+                ],
+                [
+                    'an SVG',
+                    css('.card { mask: url(../images/icon.svg); }\n'),
+                    { file: 'images/icon.svg', content: '<svg/>', category: 'staticFile' },
+                ],
+            ])('rebuilds for %s the throwing build was first to need', async (_, edit, created) => {
+                await dev.init();
+                rebuilt = 0;
+                mode.throwing = true;
+                await write(edit);
+                await until(() => rebuilt === 1);
+                expect(dev.getStatus().state).toBe('failed');
+                mode.throwing = false;
+                await write(created);
+                await until(() => rebuilt === 2);
+                expect(dev.getStatus()).toEqual({ state: 'ready' });
+            });
+            it('skips files no build can read, and goes back to the files read once a build reports', async () => {
+                await fse.outputFile(join(docsRoot, 'images/logo.png'), 'png');
+                await dev.init();
+                rebuilt = 0;
+                mode.throwing = true;
+                await write(css('.card { color: blue; }\n'));
+                await until(() => rebuilt === 1);
+                mode.throwing = false;
+                await write({ file: 'notes.txt', content: 'a', category: 'staticFile' });
+                await write({ file: 'data/config.yaml', content: 'a: 1', category: 'staticFile' });
+                await settle();
+                expect(rebuilt).toBe(1);
+                expect(dev.getStatus().state).toBe('failed');
+                await write({ file: 'images/logo.png', content: 'png2', category: 'staticFile' });
+                await until(() => rebuilt === 2);
+                expect(dev.getStatus()).toEqual({ state: 'ready' });
+                await write({ file: 'images/logo.png', content: 'png3', category: 'staticFile' });
+                await write({ file: 'style.css', content: 'body { color: green; }\n', category: 'css' });
+                await settle();
+                expect(rebuilt).toBe(2);
+            });
+            it.each([
+                ['an asset', 'images/hero.webp', 2],
+                ['a file no build reads', 'notes.txt', 1],
+            ])('reruns a build that throws when %s changes mid-build', async (_, file, builds) => {
+                await dev.init();
+                rebuilt = 0;
+                mode.throwing = true;
+                await duringNextBuild(() => write(css('.card { color: blue; }\n')), () => write({ file, content: 'x', category: 'staticFile' }));
+                await until(() => rebuilt >= 1);
+                await settle();
+                expect(rebuilt).toBe(builds);
+                expect(dev.getStatus().state).toBe('failed');
+            });
+            it('rebuilds for a file the last reporting build read, whatever its type', async () => {
+                await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), `import note from "./note.txt";\n${CARD}`);
+                await fse.outputFile(join(docsRoot, 'snippets/note.txt'), 'a\n');
+                await dev.init();
+                rebuilt = 0;
+                mode.throwing = true;
+                await write(css('.card { color: blue; }\n'));
+                await until(() => rebuilt === 1);
+                expect(dev.getStatus().state).toBe('failed');
+                mode.throwing = false;
+                await write({ file: 'snippets/note.txt', content: 'b\n', category: 'staticFile' });
+                await until(() => rebuilt === 2);
+                expect(dev.getStatus()).toEqual({ state: 'ready' });
+            });
+        });
+        describe('scripts and JSON', () => {
+            const editHelper = async () => {
+                await fse.outputFile(join(docsRoot, 'snippets/format.js'), 'export const label = "b";\n');
+                await dev.onFileChange('snippets/format.js', 'js');
+            };
+            const editUnread = async () => {
+                await fse.outputJson(join(docsRoot, 'openapi.json'), { openapi: '3.1.0', paths: {} });
+                await dev.onFileChange('openapi.json', 'potentialJsonOpenApiSpec');
+                await fse.outputFile(join(docsRoot, 'scripts/x.ts'), 'export const x = 2;\n');
+                await dev.onFileChange('scripts/x.ts', null);
+            };
+            beforeEach(async () => {
+                await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), CARD.replace('import "./card.css";', 'import { label } from "./format.js";'));
+                await fse.outputFile(join(docsRoot, 'snippets/format.js'), 'export const label = "a";\n');
+                await fse.outputJson(join(docsRoot, 'openapi.json'), { openapi: '3.1.0' });
+                await fse.outputFile(join(docsRoot, 'scripts/x.ts'), 'export const x = 1;\n');
+            });
+            it.each([
+                ['ready', false],
+                ['failed', true],
+            ])('when %s, rebuilds for a helper a package snippet imports, not for an OpenAPI spec or script', async (state, failing) => {
+                mode.failing = failing;
+                await dev.init();
+                expect(dev.getStatus().state).toBe(state);
+                rebuilt = 0;
+                await editUnread();
+                await settle();
+                expect(rebuilt).toBe(0);
+                expect(dev.getStatus().state).toBe(state);
+                await editHelper();
+                await until(() => rebuilt === 1);
+            });
+            it('waits for the first build to report what it reads before rebuilding for a file changed mid-build', async () => {
+                let starting = Promise.resolve();
+                await duringNextBuild(async () => {
+                    starting = dev.init();
+                }, editUnread);
+                await starting;
+                await settle();
+                expect(rebuilt).toBe(1);
+            });
+            it('rebuilds for a helper edited while the first build runs', async () => {
+                let starting = Promise.resolve();
+                await duringNextBuild(async () => {
+                    starting = dev.init();
+                }, editHelper);
+                await starting;
+                await until(() => rebuilt === 2);
+            });
+            it('rebuilds for a helper edited after a build that threw before reporting what it reads', async () => {
+                mode.throwing = true;
+                await dev.init();
+                expect(dev.getStatus().state).toBe('failed');
+                mode.throwing = false;
+                rebuilt = 0;
+                await editHelper();
+                await until(() => rebuilt === 1);
+                expect(dev.getStatus()).toEqual({ state: 'ready' });
+            });
+            it('rebuilds for a helper a snippet newly imports when the build after that edit threw', async () => {
+                await dev.init();
+                rebuilt = 0;
+                mode.throwing = true;
+                await fse.outputFile(join(docsRoot, 'snippets/card.jsx'), CARD.replace('import "./card.css";', 'import { label } from "../lib/label.js";'));
+                await dev.onFileChange('snippets/card.jsx', 'snippet-v2');
+                await until(() => rebuilt === 1);
+                expect(dev.getStatus().state).toBe('failed');
+                mode.throwing = false;
+                await fse.outputFile(join(docsRoot, 'lib/label.js'), 'export const label = "a";\n');
+                await dev.onFileChange('lib/label.js', 'js');
+                await until(() => rebuilt === 2);
+                expect(dev.getStatus()).toEqual({ state: 'ready' });
+            });
+        });
+    });
+    it('reports island extraction errors', async () => {
+        await fse.outputFile(join(docsRoot, 'bad.mdx'), 'import { LineChart } from "recharts";\n\n<LineChart onClick={() => {}} />\n');
+        await dev.init();
+        expect(report.calls.find((call) => call.startsWith('islandErrors'))).toMatch(/bad\.mdx:3/);
+    });
+});