@mintlify/package-builder 0.0.0-stage → 0.0.3

package/LICENSE

@@ -0,0 +1,93 @@
+Copyright (c) 2022 Mintlify, Inc.
+
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+_As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim._
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @mintlify/package-builder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Builds npm package islands for docs that set a `packages` key in docs.json. The same code runs in the Cloudflare Sandbox build container and in `mint dev`.
+
+`packages.isolation: "frame"` is not implemented yet. A build that sets it fails with `isolation-frame-not-implemented` instead of running the islands in the page.
+
+Steps:
+
+1. Validates the lockfile (`package-lock.json` v2/v3 or `pnpm-lock.yaml` v6+): every entry needs `integrity`; `git`, `file:`, `link:` and `http:` sources are rejected; https URLs must be on registry.npmjs.org or on the scope's registry from `packages.registries`. package.json dependencies, `overrides` and `pnpm` overrides/extensions must be registry versions, ranges or dist-tags (no `npm:` aliases, git, `file:`, `link:`, `workspace:`, `catalog:`, URLs or paths), `pnpm.patchedDependencies` is rejected, and the lockfile root must match package.json. npm entries marked `inBundle` cannot carry their own `resolved`, and pnpm resolutions may only have `integrity` and `tarball`. For `npm-ci` and `prepared`, package.json and the lockfile must be regular files, not symbolic links, and parse errors report only a line and column.
+2. Installs. `npm-ci` copies only package.json and the lockfile into a temp dir, writes its own `.npmrc` (deleted as soon as the install exits, since it can hold registry tokens; registries and tokens containing `${` are rejected because npm fills them from environment variables) and runs `npm ci --ignore-scripts --omit=dev`. It retries once with `--legacy-peer-deps` on ERESOLVE. On Windows it never spawns a `.cmd` shim or a shell: it runs `npm-cli.js` (or pnpm's `pnpm.cjs`/`pnpm.mjs`/`pnpm.js`) with the current Node, or `pnpm.exe`, found from `npm_execpath`, PATH or the Node install, and fails with `package-manager-missing` otherwise. `local` (for `mint dev`) uses the docs folder's existing node_modules and turns lockfile and package.json errors into warnings. `prepared` is for a caller that installed packages itself, like the build worker: it uses the existing node_modules but keeps every check an error, including installed versions that differ from the lockfile, and never reads node_modules folders above the docs folder. The copied package.json drops `packageManager` and `devEngines`, Corepack is told not to switch versions, and pnpm runs with `package-import-method=copy`; `packageManagers.pnpm` maps a pnpm major to an installed binary, so a project asking for that major gets it and any other major gets the default pnpm with a warning. `registryTokens` is keyed by registry URL: a token is written only for scopes whose registry in `packages.registries` is that URL. `npm-ci` and `prepared` builds reject hard-linked files in packages and docs files.
+3. Bundles every island in one esbuild build with code splitting. Imports cannot leave the docs folder or climb out of a package with `..`, `packages.css` entries must be package paths, and `packages.provider` must be a docs path that starts with `/`, such as `/snippets/provider.jsx` (without the `/` the entry would import it as an npm package). A docs or island `import()`/`require()` that builds a `./`, `../` or `/` path at runtime (a template literal with `${}` or string concatenation) fails with `import-runtime-path` before installing, because only statically imported docs files are hashed and copied; dynamic imports of package paths are left alone. Every file esbuild reads, from any importer (packages, their CSS `@import` and `url()`, glob imports, asset loaders), must have a real path (links and Windows 8.3 short names resolved on both sides, compared case-insensitively on Windows) inside the install root's node_modules, the job's docs files or the builder runtime, so a package or a symlink cannot pull in other files; `local` also accepts node_modules folders above the docs folder, where workspaces hoist packages. The metafile is checked again before anything is written. `react`, `react-dom` and their subpaths are aliased to the project's single copy. A separate Node build is used for server rendering.
+4. Renders each island in its own child process with `renderToString`, using `identifierPrefix: mi-<id>-` and a 3 s timeout per island, then sanitizes the HTML (256 KB cap). A fresh process per island means module-level counters (lodash `uniqueId`, recharts clip paths, react-select instance ids) start over for every island, so two islands on a page could render the same ids. When the HTML has an `id`, the process renders the island a second time; every id that differs between the two renders (all ids when the second render throws or runs out of time) becomes `mi-<island id>-<old id>`, together with its references in `url(#...)` values, `href`/`xlink:href="#..."` and id-list attributes such as `for` and `aria-labelledby`. Ids from `useId` already carry the prefix, and ids that are the same in both renders, such as a gradient id written in the source, keep their names, so elements React mounts after hydration still find them. React keeps server attributes when it hydrates, so renamed ids stay in the page; the browser's own counter ids never collide with them. Code that runs after hydration only knows the browser's counter values, so an element mounted later that points at a renamed id (a recharts `ReferenceArea` with `ifOverflow="hidden"` shown after load) or a `getElementById` call for one finds nothing; without renaming, that only worked in the first island to hydrate. Islands render one at a time and a process only ever loads one island, so its code can only affect its own result. The parent accepts `start` and then one well-formed `done` (followed by the HTML and the second render's HTML or `null`) or `error` for that island's id, then kills the process; any other message fails that island, except that a malformed or oversized message after the HTML only drops the second render. On Node 20+ the render process runs under `--permission` with read access only to the server bundle and the render script, so an island cannot read other files, write to disk (including rewriting another island's bundle), or spawn a process or worker while it renders. On Windows the builder first renders a probe island under the same flags and drops them if it fails, so a Node permission model that rejects Windows paths degrades to an unsandboxed render instead of failing every island. Results come back as JSON lines on a plain pipe that the parent parses itself, capped at 1M characters per message and 16M characters of HTML, with log entries clipped to 20 of 2,000 characters, and each island's HTML is sanitized before the next island renders, so the builder holds one raw result at a time; Node IPC is not used because its own message handling throws in the parent on crafted input. Anything an island writes to the pipe fails only that island rather than crashing the build. Network egress is not restricted here; the build container blocks it at the container layer, and `mint dev` / `mint packages check` run the project's own code on the developer's machine. `node:sqlite`, which the permission model does not cover, is turned off with `--no-experimental-sqlite`. On Linux the parent stops a render whose resident memory passes `renderMemoryLimitBytes` (2 GiB by default). `npm-ci` and `prepared` builds never render without the permission model; `local` builds warn and render. An island that throws, times out, runs out of memory or cannot be sandboxed is reported as a warning and renders in the browser only.
+5. Writes `manifest.json` with sha384 integrity and gzip sizes.
+
+## Build hashes
+
+`computeDepsHash` and `computeIslandsHash` in `src/hashing.ts` are the one definition of the build keys. The server and the package-builder worker carry ports, and all three must pass `__test__/fixtures/hash-vectors.json` (copied byte for byte into both server tests).
+
+```
+H(x)        = lowercase hex sha256 of x (strings as UTF-8)
+canonical() = JSON, no whitespace, object keys sorted by UTF-16 code unit, undefined keys dropped
+depsHash    = H(canonical({ algorithm: 'mint-pkg-deps/1', builderVersion, lockfileKind,
+                            lockfile: H(lockfileBytes), dependencies, registries ?? {} }))
+islandsHash = H(canonical({ algorithm: 'mint-pkg-islands/1',
+                            islands: [{ id, kind, module: H(module) }] sorted by id,
+                            snippets: { [path]: H(source) }, provider ?? null, css ?? [],
+                            ssr ?? true, isolation ?? 'page' }))
+buildId     = H(depsHash + islandsHash).slice(0, 32)
+```
+
+`snippets` holds the job's `snippetFiles` plus every docs file that they, `packages.provider` or an island reach through relative or `/` imports, read from `docsRoot` (`collectLocalFiles`). The bundle reads docs files only from that set, so editing an imported helper, JSON or CSS file always changes the hash. A job that already sends every imported file, as the server does, gets the same hash. A `snippetFiles` string is hashed and bundled as its UTF-8 bytes, so it must be the file's exact text, byte order mark and CRLF line endings included. A file whose bytes are not valid UTF-8 (images, fonts, Latin-1 or UTF-16 text) stays out of `snippetFiles` and is read from `docsRoot` as bytes. The server splits files that way: text whose bytes survive a UTF-8 round trip goes in `snippetFiles`, everything else in `assetFiles`, which the worker writes into the docs folder.
+
+A build job can pass `expected: { depsHash, islandsHash }`. The manifest then carries those values, and the build fails with `deps-hash-mismatch` or `islands-hash-mismatch` if the builder computes different ones, so a job keyed under one hash never publishes output built from different inputs.
+
+## CLI
+
+```sh
+mint-package-builder build --input input.json --out dist [--installer local|npm-ci|prepared] [--json]
+```
+
+`input.json` is a `BuildInput` without `outDir`. The exit code is 1 when the build has errors.
+
+## Output
+
+```
+<out>/manifest.json
+<out>/client/islands/<id>.js   exports hydrate(el, { identifierPrefix, props?, theme? })
+<out>/client/*.js              shared chunks, one React
+<out>/client/styles.css        packages.css plus CSS imported by packages
+<out>/server/                  server build (not served)
+```
+
+`styles.css` is one stylesheet for every island. It starts with the `packages.css` entries in docs.json order, then adds the stylesheets imported from JS: `packages.provider`'s first, then each island's in island id order, each walked depth first in the order esbuild uses for CSS imported from JS (static imports in source order, then `import()` and `require()`). A package `import()` or `require()` whose path is built at runtime, such as ``import(`./themes/${name}.css`)``, adds every file it matches at its place, sorted by path as esbuild sorts them, and JS files it matches are walked the same way. A `?query` or `#hash` suffix on a stylesheet import is dropped, and an import such as `./button.css` that resolves to a JS file (`button.css.js`) stays JS. When two islands import the same files in different orders, the island whose id sorts first decides. A stylesheet that JS imports again, or that `packages.css` already loads directly or through `@import`, keeps its first place. A file that stylesheets `@import` more than once keeps its last place, as in esbuild and the browser. The client build writes no other stylesheet: a stylesheet that JS loads in a way the walk cannot place, such as a runtime path that matches a symlink to a file elsewhere in the package, fails the build with `css-not-collected`. CSS modules (`.module.css`) fail the build too, whether JS imports them (including code that only the server build loads), a stylesheet `@import`s them or `packages.css` lists them, since styles.css loads them globally and their class names would not match.
+
+Package snippets can read the docs theme with `import { useMintTheme } from '@mintlify/islands'`.
+
+## React rules
+
+| Check                                                             | Result  |
+| ----------------------------------------------------------------- | ------- |
+| react and react-dom differ on 19.x, or majors differ              | error   |
+| react and react-dom differ on 18.x                                | warning |
+| more than one react or react-dom in a bundle                      | error   |
+| an island throws, logs an error or times out during SSR           | warning |
+| the alias replaced a package's own React                          | warning |
+| a peer range excludes the installed React                         | warning |
+| `findDOMNode`, `ReactDOM.render` or `.defaultProps =` on React 19 | warning |

package/dist/build.d.ts

@@ -0,0 +1,4 @@
+import type { BuildInput, BuildResult } from './types.js';
+export declare const MAX_SERVER_BUNDLE_BYTES: number;
+export declare const MAX_CLIENT_GZIP_BYTES: number;
+export declare function build(input: BuildInput): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,338 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { bundle, canonical, inside } from './bundle.js';
+import { Diagnostics } from './diagnostics.js';
+import { computeBuildId, computeDepsHash, computeIslandsHash, gzipSize, islandPrefix, sha384Integrity, } from './hashing.js';
+import { install } from './install.js';
+import { collectLocalFiles, runtimeImports } from './local-files.js';
+import { findLockfile, lockfileKind, validateLockfile, validateRegistries } from './lockfile.js';
+import { dependencySpecs, readPackageJson, validatePackageJson } from './package-json.js';
+import { checkDuplicateReact, checkPeerRanges, checkReactVersions, reactPackageDirs, readReactInfo, scanRemovedApis, } from './react.js';
+import { renderEach, sandboxAvailable } from './render.js';
+import { sanitizeIslandHtml, stateIdRenames } from './sanitize.js';
+import { BUILDER_VERSION } from './version.js';
+export const MAX_SERVER_BUNDLE_BYTES = 4 * 1024 * 1024;
+export const MAX_CLIENT_GZIP_BYTES = 5 * 1024 * 1024;
+async function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map((e) => e.isDirectory() ? walk(join(dir, e.name)) : Promise.resolve([join(dir, e.name)])));
+    return nested.flat().sort();
+}
+function toPosix(path) {
+    return path.split(sep).join('/');
+}
+function installedVersions(installRoot, names) {
+    const out = {};
+    for (const name of [...names].sort()) {
+        try {
+            const json = JSON.parse(readFileSync(join(installRoot, 'node_modules', name, 'package.json'), 'utf8'));
+            if (json.version)
+                out[name] = { version: json.version };
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+function closureGzip(metafile, srcDir, gzipByPath) {
+    const outputs = new Map(Object.entries(metafile.outputs).map(([key, value]) => [resolve(srcDir, key), value]));
+    const result = {};
+    for (const [path, output] of outputs) {
+        const match = /[\\/]islands[\\/]([^\\/]+)\.js$/.exec(path);
+        if (!output.entryPoint || !match)
+            continue;
+        const seen = new Set();
+        const stack = [path];
+        let total = 0;
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (seen.has(current))
+                continue;
+            seen.add(current);
+            total += gzipByPath.get(current) ?? 0;
+            for (const imp of outputs.get(current)?.imports ?? []) {
+                if (imp.kind === 'import-statement')
+                    stack.push(resolve(srcDir, imp.path));
+            }
+        }
+        result[match[1]] = total;
+    }
+    return result;
+}
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+function resolveHashes(input, computed, diag) {
+    const expected = input.expected;
+    if (expected === undefined)
+        return computed;
+    if (!HASH_PATTERN.test(expected.depsHash) || !HASH_PATTERN.test(expected.islandsHash)) {
+        diag.error('expected-hash-invalid', 'The build job sent expected hashes that are not 64-character lowercase hex SHA-256 digests.');
+        return computed;
+    }
+    if (expected.depsHash !== computed.depsHash) {
+        diag.error('deps-hash-mismatch', `The build job's depsHash ${expected.depsHash} does not match the builder's ${computed.depsHash} ` +
+            `(@mintlify/package-builder ${BUILDER_VERSION}). The job was hashed from a different lockfile, ` +
+            'dependencies, registries or builder version; check that the server sends the builder version ' +
+            'installed in the build image.');
+    }
+    if (expected.islandsHash !== computed.islandsHash) {
+        diag.error('islands-hash-mismatch', `The build job's islandsHash ${expected.islandsHash} does not match the builder's ${computed.islandsHash}. ` +
+            'The job was hashed from different islands, snippet files or packages settings.');
+    }
+    return { depsHash: expected.depsHash, islandsHash: expected.islandsHash };
+}
+function downgrade(diagnostics) {
+    return diagnostics.map((d) => d.level === 'error'
+        ? { ...d, level: 'warning', message: `${d.message} Deploys fail until this is fixed.` }
+        : d);
+}
+export async function build(input) {
+    const started = performance.now();
+    const diag = new Diagnostics();
+    const packages = input.packages;
+    const docsRoot = resolve(input.docsRoot);
+    const outDir = resolve(input.outDir);
+    const local = input.installer === 'local';
+    const stats = {
+        installMs: 0,
+        bundleMs: 0,
+        renderMs: 0,
+        totalMs: 0,
+        clientBytes: 0,
+        clientGzipBytes: 0,
+        serverBytes: 0,
+        islandClientGzipBytes: {},
+        reactDirs: { react: [], 'react-dom': [] },
+    };
+    if (packages.isolation === 'frame') {
+        diag.error('isolation-frame-not-implemented', 'packages.isolation "frame" is not implemented yet. Remove it or set it to "page".');
+    }
+    const registryErrors = validateRegistries(packages.registries);
+    diag.addAll(registryErrors);
+    const pkg = readPackageJson(docsRoot, { allowSymlink: local });
+    diag.addAll(pkg.diagnostics);
+    const packageJson = pkg.packageJson;
+    if (packageJson) {
+        const specProblems = validatePackageJson(packageJson);
+        diag.addAll(local ? downgrade(specProblems) : specProblems);
+    }
+    const dependencies = packageJson ? dependencySpecs(packageJson, 'dependencies') : {};
+    const found = findLockfile(docsRoot, { allowSymlink: local });
+    diag.addAll(local ? downgrade(found.diagnostics) : found.diagnostics);
+    let expectedVersions;
+    if (found.lockfile && registryErrors.length === 0) {
+        const validation = validateLockfile({
+            fileName: found.lockfile.fileName,
+            content: found.lockfile.content,
+            registries: packages.registries,
+            packageJson,
+        });
+        diag.addAll(local ? downgrade(validation.diagnostics) : validation.diagnostics);
+        expectedVersions = validation.topLevel;
+    }
+    const localFiles = collectLocalFiles({
+        docsRoot,
+        islands: input.islands,
+        snippetFiles: input.snippetFiles,
+        provider: packages.provider,
+        rejectHardLinks: !local,
+    });
+    for (const problem of await runtimeImports(localFiles, input.islands))
+        diag.error('import-runtime-path', problem);
+    const { depsHash, islandsHash } = resolveHashes(input, {
+        depsHash: computeDepsHash({
+            lockfileBytes: found.lockfile?.content ?? '',
+            lockfileKind: found.lockfile ? lockfileKind(found.lockfile.fileName) : 'npm',
+            dependencies,
+            registries: packages.registries,
+            builderVersion: BUILDER_VERSION,
+        }),
+        islandsHash: computeIslandsHash({
+            islands: input.islands,
+            snippetFiles: localFiles,
+            provider: packages.provider,
+            css: packages.css,
+            ssr: packages.ssr,
+            isolation: packages.isolation,
+        }),
+    }, diag);
+    const manifest = {
+        version: 1,
+        builderVersion: BUILDER_VERSION,
+        buildId: computeBuildId(depsHash, islandsHash),
+        depsHash,
+        islandsHash,
+        react: { version: '', domVersion: '' },
+        packages: {},
+        css: [],
+        islands: {},
+        files: [],
+        diagnostics: diag.list,
+    };
+    if (inside(canonical(outDir), canonical(docsRoot))) {
+        diag.error('out-dir-invalid', `The output folder ${outDir} contains the docs folder and would be deleted; use an empty folder.`);
+        stats.totalMs = performance.now() - started;
+        return { ok: false, manifest, stats };
+    }
+    await rm(outDir, { recursive: true, force: true });
+    await mkdir(outDir, { recursive: true });
+    const finish = async () => {
+        stats.totalMs = performance.now() - started;
+        await writeFile(join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+        return { ok: !diag.hasErrors(), manifest, stats };
+    };
+    if (diag.hasErrors())
+        return finish();
+    const installed = await install({
+        docsRoot,
+        installer: input.installer,
+        lockfile: found.lockfile,
+        packageJson,
+        registries: packages.registries,
+        registryTokens: input.registryTokens,
+        packageManagers: input.packageManagers,
+        expectedVersions,
+    });
+    stats.installMs = installed.durationMs;
+    diag.addAll(installed.diagnostics);
+    let srcDir;
+    try {
+        if (!installed.ok)
+            return await finish();
+        const react = readReactInfo(installed.installRoot);
+        diag.addAll(react.diagnostics);
+        if (react.info) {
+            manifest.react = { version: react.info.version, domVersion: react.info.domVersion };
+            diag.addAll(checkReactVersions(react.info.version, react.info.domVersion));
+        }
+        manifest.packages = installedVersions(installed.installRoot, Object.keys(dependencies));
+        if (diag.hasErrors() || !react.info)
+            return await finish();
+        const bundled = await bundle({
+            installRoot: installed.installRoot,
+            islands: input.islands,
+            snippetFiles: localFiles,
+            packages,
+            outDir,
+            workParent: input.installer === 'npm-ci' ? installed.installRoot : undefined,
+            hoistedNodeModules: local,
+            rejectHardLinks: !local,
+        });
+        srcDir = bundled.srcDir;
+        stats.bundleMs = bundled.durationMs;
+        diag.addAll(bundled.diagnostics);
+        for (const replaced of bundled.replacedReact) {
+            diag.warn('react-alias-replaced', `${replaced.pkg} ships its own React${replaced.version ? ` ${replaced.version}` : ''}; it was replaced with the project's react ${react.info.version}. Move react to its peerDependencies.`, replaced.pkg);
+        }
+        if (bundled.client) {
+            const dirs = reactPackageDirs(bundled.client, bundled.srcDir);
+            stats.reactDirs = { react: dirs['react'] ?? [], 'react-dom': dirs['react-dom'] ?? [] };
+            diag.addAll(checkDuplicateReact(bundled.client, bundled.srcDir, 'client'));
+            diag.addAll(scanRemovedApis(bundled.client, bundled.srcDir, react.info.version));
+            diag.addAll(checkPeerRanges(bundled.client, bundled.srcDir, react.info));
+        }
+        if (bundled.server)
+            diag.addAll(checkDuplicateReact(bundled.server, bundled.srcDir, 'server'));
+        const clientFiles = await walk(join(outDir, 'client'));
+        const gzipByPath = new Map();
+        const files = [];
+        for (const file of clientFiles) {
+            const data = new Uint8Array(await readFile(file));
+            const gz = gzipSize(data);
+            gzipByPath.set(file, gz);
+            files.push({
+                path: toPosix(relative(outDir, file)),
+                bytes: data.length,
+                gzipBytes: gz,
+                integrity: sha384Integrity(data),
+            });
+            stats.clientBytes += data.length;
+            stats.clientGzipBytes += gz;
+            if (file === join(outDir, 'client', 'styles.css')) {
+                manifest.css.push({
+                    path: 'client/styles.css',
+                    integrity: sha384Integrity(data),
+                    bytes: data.length,
+                });
+            }
+        }
+        manifest.files = files;
+        for (const file of await walk(join(outDir, 'server')))
+            stats.serverBytes += (await readFile(file)).length;
+        if (bundled.client)
+            stats.islandClientGzipBytes = closureGzip(bundled.client, bundled.srcDir, gzipByPath);
+        if (stats.clientGzipBytes > MAX_CLIENT_GZIP_BYTES) {
+            diag.error('client-bundle-too-large', `Client bundles are ${stats.clientGzipBytes} bytes gzipped; the limit is ${MAX_CLIENT_GZIP_BYTES}.`);
+        }
+        for (const island of input.islands) {
+            manifest.islands[island.id] = {
+                entry: `client/islands/${island.id}.js`,
+                prefix: islandPrefix(island.id),
+            };
+        }
+        if (diag.hasErrors() || input.islands.length === 0)
+            return await finish();
+        if (packages.ssr === false)
+            return await finish();
+        if (stats.serverBytes > MAX_SERVER_BUNDLE_BYTES) {
+            diag.warn('ssr-skipped-large-server-bundle', `The server bundle is ${stats.serverBytes} bytes, over ${MAX_SERVER_BUNDLE_BYTES}; islands render in the browser only.`);
+            return await finish();
+        }
+        const renderStart = performance.now();
+        const pageOf = new Map(input.islands.map((i) => [i.id, i.pagePath]));
+        if (!sandboxAvailable()) {
+            const message = 'This Node.js version has no permission model, so island code runs on the server without a sandbox. Use Node.js 20 or later.';
+            if (local)
+                diag.warn('render-sandbox-unavailable', message);
+            else {
+                diag.error('render-sandbox-unavailable', message);
+                return await finish();
+            }
+        }
+        for await (const outcome of renderEach({
+            serverDir: join(outDir, 'server'),
+            islands: input.islands.map((i) => ({ id: i.id, prefix: islandPrefix(i.id) })),
+            requireSandbox: !local,
+            ...(input.renderMemoryLimitBytes !== undefined
+                ? { memoryLimitBytes: input.renderMemoryLimitBytes }
+                : {}),
+        })) {
+            const where = `Island ${outcome.id} (${pageOf.get(outcome.id) ?? 'unknown page'})`;
+            const entry = manifest.islands[outcome.id];
+            if (!entry)
+                continue;
+            for (const warning of outcome.warnings.slice(0, 3))
+                diag.warn('island-ssr-warning', `${where} logged a warning while rendering: ${warning}`);
+            if (!outcome.ok) {
+                const code = /longer than/.test(outcome.error) ? 'island-ssr-timeout' : 'island-ssr-error';
+                diag.warn(code, `${where} failed to render on the server, so it renders in the browser only: ${outcome.error}`);
+                continue;
+            }
+            for (const error of outcome.errors.slice(0, 3))
+                diag.warn('island-ssr-error', `${where} logged an error while rendering: ${error}`);
+            entry.ssrMs = Math.round(outcome.ssrMs * 100) / 100;
+            const prefix = islandPrefix(outcome.id);
+            const renames = stateIdRenames(outcome.html, outcome.second, prefix);
+            const sanitized = sanitizeIslandHtml(outcome.html, prefix, renames);
+            if (sanitized.tooLarge) {
+                diag.warn('island-html-too-large', `${where} rendered ${sanitized.bytes} bytes of HTML, over the 256 KB cap; it renders in the browser only.`);
+            }
+            else {
+                entry.html = sanitized.html;
+            }
+        }
+        stats.renderMs = performance.now() - renderStart;
+        return await finish();
+    }
+    finally {
+        if (!process.env.MINT_PACKAGE_BUILDER_KEEP_TMP) {
+            await installed.cleanup();
+            if (srcDir)
+                await rm(srcDir, { recursive: true, force: true });
+        }
+    }
+}

package/dist/bundle.d.ts

@@ -0,0 +1,44 @@
+import * as esbuild from 'esbuild';
+import { type PlatformPath } from 'node:path';
+import type { LocalFiles } from './local-files.js';
+import { type ReplacedReact } from './react.js';
+import type { BuildDiagnostic, IslandSpec, PackagesConfig } from './types.js';
+export declare const ISLAND_ID: RegExp;
+export declare const ISLANDS_HOOKS_SPECIFIER = "@mintlify/islands";
+export declare const URL_LIKE: RegExp;
+export type BundleOptions = {
+    installRoot: string;
+    islands: IslandSpec[];
+    snippetFiles: LocalFiles;
+    packages: PackagesConfig;
+    outDir: string;
+    workParent?: string;
+    hoistedNodeModules?: boolean;
+    rejectHardLinks?: boolean;
+};
+export type BundleResult = {
+    ok: boolean;
+    diagnostics: BuildDiagnostic[];
+    durationMs: number;
+    srcDir: string;
+    client?: esbuild.Metafile;
+    server?: esbuild.Metafile;
+    css?: esbuild.Metafile;
+    replacedReact: ReplacedReact[];
+};
+type PathOps = Pick<PlatformPath, 'relative' | 'isAbsolute' | 'resolve'>;
+export declare function inside(parent: string, child: string, ops?: PathOps): boolean;
+export declare function canonical(path: string): string;
+export declare function within(roots: string[], real?: (path: string) => string, ops?: PathOps): (path: string) => boolean;
+export declare function docsPathToRelative(path: string): string | undefined;
+export declare function docsTarget(docsDir: string, path: string, ops?: PathOps): string | undefined;
+export declare function shownPath(path: string, docsDir: string, ops?: PathOps): string;
+export declare function formatMessages(messages: {
+    text: string;
+    location: {
+        file: string;
+        line: number;
+    } | null;
+}[], srcDir: string, islands: Pick<IslandSpec, 'id' | 'pagePath'>[], ops?: PathOps): string[];
+export declare function bundle(opts: BundleOptions): Promise<BundleResult>;
+export {};