@mintlify/package-builder 0.0.15 → 0.0.17

package/README.md

@@ -12,6 +12,30 @@ Steps:
 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.
 
+## Shared helpers
+
+Use the focused entry points to share build fingerprints, HTML sanitization and types with hosted services:
+
+```ts
+import {
+  computeBuildId,
+  computeDepsHash,
+  computeIslandsHash,
+} from '@mintlify/package-builder/hashing';
+import { MAX_ISLAND_HTML_BYTES, sanitizeIslandHtml } from '@mintlify/package-builder/sanitize';
+import type {
+  IslandSpec,
+  PackageBuildManifest,
+  PackagesConfig,
+} from '@mintlify/package-builder/types';
+```
+
+The sanitizer entry point uses `entities/decode` and standard JavaScript APIs. The hashing entry point uses `node:crypto` and `node:zlib`, so Cloudflare Workers consuming it need `nodejs_compat`. These imports avoid loading the build, installation, bundling and rendering modules exported by the package root. Type-only imports do not load runtime code.
+
+Pin the helper dependency and the build container to the same published package version. A hosted service must still validate and sanitize untrusted container output before publishing it, even when both use the same implementation.
+
+The root import, CLI and existing `@mintlify/package-builder/dist/*` imports remain available. The server and Worker can migrate their copied helpers to these entry points after the package is published.
+
 ## 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/package-builder",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Installs, bundles and server-renders npm package islands for Mintlify docs",
   "engines": {
     "node": ">=18.0.0"
@@ -28,6 +28,26 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./hashing": {
+      "types": "./dist/hashing.d.ts",
+      "default": "./dist/hashing.js"
+    },
+    "./sanitize": {
+      "types": "./dist/sanitize.d.ts",
+      "default": "./dist/sanitize.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./package.json": "./package.json",
+    "./dist/*": "./dist/*"
+  },
   "bin": {
     "mint-package-builder": "./dist/cli.js"
   },
@@ -53,9 +73,9 @@
     "semver": "7.7.4"
   },
   "devDependencies": {
-    "@mintlify/common": "1.0.1229",
+    "@mintlify/common": "1.0.1230",
     "@mintlify/ts-config": "2.0.2",
-    "@mintlify/validation": "0.1.903",
+    "@mintlify/validation": "0.1.904",
     "@tsconfig/recommended": "1.0.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "18.19.21",
@@ -72,5 +92,5 @@
     "typescript": "5.5.3",
     "vitest": "2.1.9"
   },
-  "gitHead": "eaedd7692869e48df3b610de8843861c2bb923f8"
+  "gitHead": "16950ad303f1deae69ce955bac93a411a8cd22df"
 }