@pix3/vite-plugin 0.0.0-stage → 2.0.0-alpha.1

package/dist/build/dependency-imports.js

@@ -0,0 +1,239 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+import * as vite from 'vite';
+import { findPackageDir } from "../dev-info.js";
+import { collectImportedSpecifiers, collectMentionedNames } from "./scan.js";
+/**
+ * N11 (plan §B.6 item 2): what a project dependency imports from `@pix3/runtime`. The scan of
+ * `mentionedNames` reads the project's own text sources, never `node_modules`, so a library with
+ * `import { GeometryMesh } from '@pix3/runtime'` would otherwise get the stub — the barrel
+ * re-exports it and the stub's importer is internal. Every package the project depends on that
+ * itself declares `@pix3/runtime` is parsed here before the build decides what to strip:
+ *
+ * - a named import (or `export { X } from`) adds `X` to the names that keep modules;
+ * - `import * as`, a dynamic `import('@pix3/runtime')`, `export * from`, `require(…)` or a file
+ *   that does not parse is **opaque**: the build cannot see which modules the package reaches,
+ *   so strip goes off with a message naming `pix3({ strip: { keep } })`.
+ *
+ * The AST comes from the bundler's own parser (`this.parse` in a hook; `parseAst` in a spec).
+ * TypeScript sources (a workspace package, a library shipping `.ts`) are lowered to JS first
+ * with Vite's own transform (`transformWithOxc` under Vite 8, `transformWithEsbuild` under 7).
+ * A `transform`-hook safety net in the plugin runs the same walk over every `node_modules`
+ * module the bundle actually pulls in, for packages this pre-scan did not know about.
+ */
+export const RUNTIME_SPECIFIER = '@pix3/runtime';
+const isNode = (value) => typeof value === 'object' && value !== null && typeof value.type === 'string';
+const literalString = (node) => {
+    if (!isNode(node))
+        return null;
+    if (node.type === 'Literal' && typeof node.value === 'string')
+        return node.value;
+    if (node.type === 'TemplateLiteral' &&
+        Array.isArray(node.expressions) &&
+        node.expressions.length === 0 &&
+        Array.isArray(node.quasis) &&
+        node.quasis.length === 1) {
+        const cooked = node.quasis[0].value?.cooked;
+        return typeof cooked === 'string' ? cooked : null;
+    }
+    return null;
+};
+const isRuntimeSource = (source) => source === RUNTIME_SPECIFIER || (source !== null && source.startsWith(`${RUNTIME_SPECIFIER}/`));
+const specifierName = (node) => {
+    if (!isNode(node))
+        return null;
+    if (node.type === 'Identifier' && typeof node.name === 'string')
+        return node.name;
+    if (node.type === 'Literal' && typeof node.value === 'string')
+        return node.value;
+    return null;
+};
+/** Walk one module's AST for what it takes from `@pix3/runtime`; `file` names it in messages. */
+export const collectRuntimeImports = (ast, file, findings = { names: new Set(), opaque: [] }) => {
+    const opaque = (what) => {
+        findings.opaque.push(`${file}: ${what}`);
+    };
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        if (!isNode(node))
+            return;
+        switch (node.type) {
+            case 'ImportDeclaration': {
+                if (!isRuntimeSource(literalString(node.source)))
+                    break;
+                if (node.importKind === 'type')
+                    break;
+                for (const specifier of node.specifiers ?? []) {
+                    if (!isNode(specifier))
+                        continue;
+                    if (specifier.importKind === 'type')
+                        continue;
+                    if (specifier.type === 'ImportSpecifier') {
+                        const name = specifierName(specifier.imported);
+                        if (name)
+                            findings.names.add(name);
+                    }
+                    else if (specifier.type === 'ImportNamespaceSpecifier') {
+                        opaque(`import * as ${specifierName(specifier.local) ?? '…'} from '${RUNTIME_SPECIFIER}'`);
+                    }
+                    // A default import: the runtime has no default export; the bundler reports it.
+                }
+                return;
+            }
+            case 'ExportNamedDeclaration': {
+                if (isRuntimeSource(literalString(node.source)) && node.exportKind !== 'type') {
+                    for (const specifier of node.specifiers ?? []) {
+                        if (!isNode(specifier) || specifier.exportKind === 'type')
+                            continue;
+                        const name = specifierName(specifier.local);
+                        if (name)
+                            findings.names.add(name);
+                    }
+                    return;
+                }
+                break;
+            }
+            case 'ExportAllDeclaration': {
+                if (isRuntimeSource(literalString(node.source))) {
+                    opaque(`export * from '${RUNTIME_SPECIFIER}'`);
+                    return;
+                }
+                break;
+            }
+            case 'ImportExpression': {
+                if (isRuntimeSource(literalString(node.source))) {
+                    opaque(`import('${RUNTIME_SPECIFIER}')`);
+                    return;
+                }
+                break;
+            }
+            case 'CallExpression': {
+                const callee = node.callee;
+                const args = node.arguments;
+                if (isNode(callee) &&
+                    callee.type === 'Identifier' &&
+                    callee.name === 'require' &&
+                    isRuntimeSource(literalString(args?.[0]))) {
+                    opaque(`require('${RUNTIME_SPECIFIER}')`);
+                    return;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'type' || key === 'loc' || key === 'range' || key === 'start' || key === 'end')
+                continue;
+            if (typeof value === 'object' && value !== null)
+                visit(value);
+        }
+    };
+    visit(ast);
+    return findings;
+};
+const SOURCE_EXTENSIONS = new Set([
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.jsx',
+    '.ts',
+    '.mts',
+    '.cts',
+    '.tsx',
+]);
+const NEEDS_LOWERING = /\.(?:[cm]?ts|[jt]sx)$/;
+const NOT_A_SOURCE = /\.(?:spec|test)\.[cm]?[jt]sx?$|\.d\.[cm]?ts$/;
+const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    '__tests__',
+    '__mocks__',
+    'test',
+    'tests',
+]);
+/** Every parseable source of a package, as absolute paths (sorted; nested packages excluded). */
+export const listPackageSources = (packageDir) => {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRECTORIES.has(entry.name))
+                    walk(absolute);
+            }
+            else if (entry.isFile() &&
+                SOURCE_EXTENSIONS.has(extname(entry.name)) &&
+                !NOT_A_SOURCE.test(entry.name)) {
+                out.push(absolute);
+            }
+        }
+    };
+    walk(packageDir);
+    return out;
+};
+/** TypeScript / JSX → plain JS, with whichever transform the installed Vite ships. */
+export const lowerToJs = async (code, filename) => {
+    const api = vite;
+    const transform = api.transformWithOxc ?? api.transformWithEsbuild;
+    if (!transform)
+        throw new Error('this Vite has neither transformWithOxc nor transformWithEsbuild');
+    return (await transform(code, filename)).code;
+};
+/**
+ * Parse every source of the given packages that mentions `@pix3/runtime` at all (a cheap text
+ * test first: three's one file is a megabyte). Opaque findings carry the package name and the
+ * path relative to it.
+ *
+ * Every source read is also scanned the way the project's own are (`mentionedNames`, the import
+ * specifiers): a library script that imports only `Script` and calls `this.scene.tween`,
+ * `.physics2d`, `juice.trail()` or `addComponent('core:Fade')` reaches modules no import names.
+ */
+export const scanDependencyImports = async (options) => {
+    const findings = { names: new Set(), opaque: [] };
+    const parsed = {};
+    const mentionedNames = new Set();
+    const importedSpecifiers = new Set();
+    for (const name of options.packages) {
+        const dir = findPackageDir(options.root, name);
+        if (!dir)
+            continue;
+        parsed[name] = 0;
+        for (const file of listPackageSources(dir)) {
+            let code;
+            try {
+                code = readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            collectMentionedNames(code, mentionedNames);
+            collectImportedSpecifiers(code, importedSpecifiers);
+            if (!code.includes(RUNTIME_SPECIFIER))
+                continue;
+            const label = `${name}/${relative(dir, file).split(sep).join('/')}`;
+            try {
+                if (NEEDS_LOWERING.test(file))
+                    code = await lowerToJs(code, file);
+                collectRuntimeImports(options.parse(code), label, findings);
+                parsed[name]++;
+            }
+            catch (error) {
+                findings.opaque.push(`${label}: could not be parsed (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+    }
+    return { ...findings, parsed, mentionedNames, importedSpecifiers };
+};

package/dist/build/dev-manifest.d.ts

@@ -0,0 +1,10 @@
+/** Dev: `virtual:pix3/scene-manifest` from the disk as it is now (a build uses its scan). */
+export declare const devSceneManifestSource: (options: {
+    readonly root: string;
+    readonly resRoot: string;
+    readonly entryScene: string | null;
+    /** Vite's `base`, ending in `/`. */
+    readonly base: string;
+    /** Where an entry scene that does not exist is reported (as a build reports it). */
+    readonly warn: (line: string) => void;
+}) => Promise<string>;

package/dist/build/dev-manifest.js

@@ -0,0 +1,25 @@
+import { sceneManifestSource } from "./player-modules.js";
+import { readProjectManifest, wireToRes } from "./project-manifest.js";
+import { discoverLocalization, isPlayableScenePath, listProjectFiles, resolveEntryScene, } from "./scan.js";
+/** Dev: `virtual:pix3/scene-manifest` from the disk as it is now (a build uses its scan). */
+export const devSceneManifestSource = async (options) => {
+    const { root, resRoot } = options;
+    const manifest = readProjectManifest(root);
+    const resPaths = (await listProjectFiles(root))
+        .map(path => wireToRes(path, resRoot))
+        .filter((path) => path !== null);
+    const scenePaths = resPaths.filter(isPlayableScenePath).sort();
+    const warnings = [];
+    const entryScenePath = resolveEntryScene(scenePaths, manifest, options.entryScene, warnings);
+    for (const line of warnings)
+        options.warn(line);
+    return sceneManifestSource({
+        scenePaths,
+        entryScenePath,
+        manifest,
+        // As the build and the editor: the manifest's block, else the tables `locales/` has.
+        localization: manifest.localization ?? discoverLocalization(new Set(resPaths)),
+        netKindPrefabs: [],
+        resourceBase: `${options.base}${resRoot === '.' ? '' : `${resRoot}/`}`,
+    });
+};

package/dist/build/editor-flush.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Before a build reads the disk (plan §B.6 «npm run build, pix3 check, pix3 smoke»): if
+ * `.pix3/dev.json` points at a live dev server, ask it to flush the editor's unsaved scenes first
+ * (`POST /__pix3/api/flush`, up to {@link FLUSH_TIMEOUT_MS}). A server that refuses the
+ * connection is gone (a stale `dev.json` after a crash); one that accepts it but does not answer
+ * `hello` within {@link PROBE_TIMEOUT_MS} is alive and busy, and — like an editor that cannot flush
+ * in time — is `E_EDITOR_UNSYNCED`: the build would otherwise ship a scene older than what the
+ * designer sees.
+ *
+ * `PIX3_NO_SYNC=1` skips the step (the CLI's `--no-sync`). The CLI carries its own copy of this logic
+ * (`packages/cli/src/editor-sync.ts`); keep the two in step.
+ */
+export declare const FLUSH_TIMEOUT_MS = 15000;
+export type EditorFlushResult = {
+    readonly status: 'skipped';
+}
+/** No `dev.json` (no `url`), or one whose server is gone (`url` and why). */
+ | {
+    readonly status: 'no-server';
+    readonly url?: string;
+    readonly reason?: string;
+} | {
+    readonly status: 'no-editor';
+    readonly url: string;
+} | {
+    readonly status: 'flushed';
+    readonly url: string;
+};
+export declare class EditorUnsyncedError extends Error {
+    readonly code = "E_EDITOR_UNSYNCED";
+    constructor(message: string);
+}
+/**
+ * Flush the editor that `.pix3/dev.json` points at, if any. Throws {@link EditorUnsyncedError}
+ * when an editor is connected but did not confirm the flush in time.
+ */
+export declare const flushEditorBeforeBuild: (root: string, options?: {
+    readonly skip?: boolean;
+    readonly timeoutMs?: number;
+    /** How long `hello` may take before a listening server counts as busy (specs). */
+    readonly probeTimeoutMs?: number;
+}) => Promise<EditorFlushResult>;

package/dist/build/editor-flush.js

@@ -0,0 +1,91 @@
+import { readFileSync } from 'node:fs';
+import { devJsonPath } from "../dev-info.js";
+/**
+ * Before a build reads the disk (plan §B.6 «npm run build, pix3 check, pix3 smoke»): if
+ * `.pix3/dev.json` points at a live dev server, ask it to flush the editor's unsaved scenes first
+ * (`POST /__pix3/api/flush`, up to {@link FLUSH_TIMEOUT_MS}). A server that refuses the
+ * connection is gone (a stale `dev.json` after a crash); one that accepts it but does not answer
+ * `hello` within {@link PROBE_TIMEOUT_MS} is alive and busy, and — like an editor that cannot flush
+ * in time — is `E_EDITOR_UNSYNCED`: the build would otherwise ship a scene older than what the
+ * designer sees.
+ *
+ * `PIX3_NO_SYNC=1` skips the step (the CLI's `--no-sync`). The CLI carries its own copy of this logic
+ * (`packages/cli/src/editor-sync.ts`); keep the two in step.
+ */
+export const FLUSH_TIMEOUT_MS = 15_000;
+const PROBE_TIMEOUT_MS = 2_000;
+export class EditorUnsyncedError extends Error {
+    code = 'E_EDITOR_UNSYNCED';
+    constructor(message) {
+        super(message);
+        this.name = 'EditorUnsyncedError';
+    }
+}
+const readDevInfo = (root) => {
+    try {
+        const parsed = JSON.parse(readFileSync(devJsonPath(root), 'utf8'));
+        return typeof parsed.url === 'string' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+const fetchWithTimeout = (url, init, timeoutMs) => fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+const isTimeout = (error) => error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+const causeOf = (error) => {
+    const cause = error?.cause;
+    if (typeof cause?.code === 'string')
+        return cause.code;
+    if (typeof cause?.message === 'string')
+        return cause.message;
+    return error instanceof Error ? error.message : String(error);
+};
+/**
+ * Flush the editor that `.pix3/dev.json` points at, if any. Throws {@link EditorUnsyncedError}
+ * when an editor is connected but did not confirm the flush in time.
+ */
+export const flushEditorBeforeBuild = async (root, options = {}) => {
+    if (options.skip ?? process.env.PIX3_NO_SYNC === '1')
+        return { status: 'skipped' };
+    const info = readDevInfo(root);
+    if (!info)
+        return { status: 'no-server' };
+    const timeoutMs = options.timeoutMs ?? FLUSH_TIMEOUT_MS;
+    const api = `${info.url.endsWith('/') ? info.url : `${info.url}/`}__pix3/api/`;
+    const probeMs = options.probeTimeoutMs ?? PROBE_TIMEOUT_MS;
+    try {
+        const hello = await fetchWithTimeout(`${api}hello`, {}, probeMs);
+        // Something else answers on that port now (the server is gone, the port reused).
+        if (!hello.ok)
+            return { status: 'no-server', url: info.url, reason: `HTTP ${hello.status}` };
+    }
+    catch (error) {
+        if (isTimeout(error)) {
+            throw new EditorUnsyncedError(`The Pix3 dev server at ${info.url} accepted the connection but did not answer within ` +
+                `${probeMs / 1000} s, so its editor's unsaved scenes could not be flushed. Retry once ` +
+                `it responds, stop it (a stale .pix3/dev.json is ignored), or skip with PIX3_NO_SYNC=1.`);
+        }
+        return { status: 'no-server', url: info.url, reason: causeOf(error) };
+    }
+    let reply;
+    try {
+        const response = await fetchWithTimeout(`${api}flush`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Pix3': '1' },
+            body: JSON.stringify({ timeoutMs }),
+        }, timeoutMs + PROBE_TIMEOUT_MS);
+        reply = (await response.json());
+    }
+    catch (error) {
+        throw new EditorUnsyncedError(`The Pix3 editor at ${info.url} did not confirm the flush of its unsaved scenes within ` +
+            `${Math.round(timeoutMs / 1000)} s (${error instanceof Error ? error.message : String(error)}). ` +
+            `Save in the editor and retry, or skip with PIX3_NO_SYNC=1.`);
+    }
+    if (reply.ok === false) {
+        throw new EditorUnsyncedError(`The Pix3 editor at ${info.url} could not flush its unsaved scenes (${reply.reason ?? 'unknown'}). ` +
+            `Save in the editor and retry, or skip with PIX3_NO_SYNC=1.`);
+    }
+    return reply.editor
+        ? { status: 'flushed', url: info.url }
+        : { status: 'no-editor', url: info.url };
+};

package/dist/build/finish.d.ts

@@ -0,0 +1,11 @@
+import type { BuildState } from './plan.ts';
+/**
+ * The last build hook: the artifact is final, so the zip is written here, then
+ * `dist/<name>.report.json` and `.pix3/build.json`.
+ */
+export declare const finishBuild: (build: BuildState, options: {
+    readonly root: string;
+    readonly outDir: string;
+    readonly log: (line: string) => void;
+    readonly warn: (line: string) => void;
+}) => void;

package/dist/build/finish.js

@@ -0,0 +1,126 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileDigest, writeBuildRecord } from "./record.js";
+import { buildReportPath, gzipBytesOf, summarizeCode, writeBuildReport, } from "./report.js";
+import { zipDirectory } from "./zip.js";
+const kib = (bytes) => (bytes / 1024).toFixed(1);
+/** Strip as it happened: off when the runtime did not resolve or nothing planned was replaced. */
+const stripOutcome = (build, stripped) => {
+    if (!build.stripEnabled)
+        return { enabled: false, reason: build.stripReason };
+    if (build.runtimeSrc === null)
+        return { enabled: false, reason: '@pix3/runtime did not resolve from the project' };
+    if (build.stripped.size > 0 && stripped.length === 0)
+        return {
+            enabled: false,
+            reason: `no runtime module loaded from ${build.runtimeSrc}: nothing was replaced`,
+        };
+    return { enabled: true, reason: build.stripReason };
+};
+/** How each optional library resolved, for the report. */
+const librariesOf = (build) => {
+    const { applied, scan } = build;
+    return {
+        yaml: applied.yaml
+            ? 'stub: scenes and prefabs ship as JSON'
+            : build.stubYaml
+                ? 'bundled (scenes ship as JSON)'
+                : 'bundled',
+        GLTFLoader: applied.gltf ? 'stub: no .glb/.gltf in the project' : 'bundled',
+        postprocessing: !build.postprocessingInstalled
+            ? 'not installed'
+            : applied.postprocessing
+                ? 'stub: no PostProcess node'
+                : scan.usesPostProcessing
+                    ? 'bundled (static import)'
+                    : build.format !== 'html'
+                        ? 'lazy chunk (the runtime import())'
+                        : 'bundled (the runtime import(), inlined)',
+        spine: !scan.usesSpine
+            ? 'not bundled: no SpineSkeleton2D'
+            : build.spineInstalled
+                ? 'bundled (static import)'
+                : 'not installed',
+        network: scan.usesNetwork ? 'bundled (NetworkService installed)' : 'no-op',
+    };
+};
+/**
+ * The last build hook: the artifact is final, so the zip is written here, then
+ * `dist/<name>.report.json` and `.pix3/build.json`.
+ */
+export const finishBuild = (build, options) => {
+    const { root, outDir, log, warn } = options;
+    const htmlPath = join(outDir, 'index.html');
+    let artifact = htmlPath;
+    if (build.format === 'zip') {
+        artifact = zipDirectory(outDir, `${build.manifest.projectName.replace(/[\\/:*?"<>|]+/g, '-')}.zip`);
+    }
+    else if (!existsSync(htmlPath)) {
+        warn(`no ${htmlPath} after the build: is index.html the project's entry?`);
+        return;
+    }
+    const digest = fileDigest(artifact);
+    const at = new Date().toISOString();
+    // What the hooks replaced, not what `buildStart` planned: the two differ only when the
+    // runtime's modules arrived under ids the plan did not recognise — say so.
+    const stripped = [...build.applied.modules].sort();
+    const missed = [...build.stripped].filter(path => !build.applied.modules.has(path));
+    if (missed.length > 0)
+        warn(`${missed.length} runtime module(s) planned for stripping were never replaced ` +
+            `(${missed.slice(0, 3).join(', ')}${missed.length > 3 ? ', …' : ''}): ` +
+            `they did not load from ${build.runtimeSrc ?? 'the resolved runtime'}`);
+    const strip = stripOutcome(build, stripped);
+    const reportPath = buildReportPath(artifact, outDir);
+    const { compressed, assets, scan } = build;
+    writeBuildReport(reportPath, {
+        format: build.format,
+        path: artifact,
+        at,
+        entryScene: scan.entryScenePath,
+        scenes: scan.scenePaths.length,
+        bytes: digest.bytes,
+        gzipBytes: gzipBytesOf(readFileSync(artifact)),
+        compress: compressed
+            ? {
+                enabled: true,
+                bundleBytes: compressed.bundleBytes,
+                gzipBytes: compressed.gzipBytes,
+                base64Bytes: compressed.base64Bytes,
+                ratio: Math.round((compressed.gzipBytes / Math.max(1, compressed.bundleBytes)) * 1000) / 1000,
+                savedBytes: compressed.bundleBytes - compressed.base64Bytes,
+            }
+            : { enabled: false },
+        code: summarizeCode({ bundleBytes: build.bundleBytes, modules: build.moduleSizes }),
+        strip: {
+            ...strip,
+            keep: build.keep,
+            stripped,
+            dependencies: build.dependencyParsed,
+            dependencyImports: [...build.dependencyImports].sort(),
+        },
+        libraries: librariesOf(build),
+        assets: {
+            count: scan.assetPaths.length,
+            rawBytes: assets?.rawBytes ?? 0,
+            base64Bytes: assets?.base64Bytes ?? 0,
+            entries: assets?.entries ?? [],
+        },
+        warnings: scan.warnings,
+    });
+    writeBuildRecord(root, {
+        format: build.format,
+        path: artifact,
+        ...digest,
+        at,
+        entryScene: scan.entryScenePath,
+        assets: scan.assetPaths.length,
+        stripped,
+        warnings: scan.warnings,
+        report: reportPath,
+    });
+    log(`${build.format}: ${relative(root, artifact)} (${kib(digest.bytes)} KiB` +
+        (compressed
+            ? `, bundle ${kib(compressed.bundleBytes)} → gzip ${kib(compressed.gzipBytes)} KiB`
+            : '') +
+        `); report ${relative(root, reportPath)}`);
+};

package/dist/build/output-plugins.d.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from 'vite';
+import type { BuildState } from './plan.ts';
+/**
+ * The optional libraries a build leaves out (CLAUDE.md «Playable export size»), part of the
+ * strip (`strip: false` keeps them all). `enforce: 'pre'`, because Vite's own resolver runs
+ * before a normal plugin's `resolveId`. Every one is stubbed **for the runtime's own importers
+ * only** (real paths compared): a project script or a dependency that imports the library
+ * itself always gets the real one — and the scan counts that import as a use, so the runtime
+ * shares the real copy then too.
+ *
+ * - `postprocessing` in a single-file build with no PostProcess node and no import of it — the
+ *   runtime's `import('postprocessing')` would be inlined whole;
+ * - `yaml` — the scenes ship as JSON (`shippedBytes`), so `SceneLoader`'s `parse` is
+ *   `JSON.parse` (plan §B.6 item 4, done the 1.x way: no runtime change, no second format);
+ * - `GLTFLoader` when no scene, script, library or asset names a model.
+ */
+export declare const libraryStubsPlugin: (getBuild: () => BuildState | null) => Plugin;
+/**
+ * `build: 'html'` (only then are these in the plugin list): inline every chunk and stylesheet into `index.html` (plan §B.6 item 5), then
+ * make that one script classic, at the end of `<body>` (DeepCore's compatibility plugin), and
+ * with `compress` replace it by the gzip payload and its bootstrap (`build/compress.ts`).
+ */
+export declare const singleFilePlugins: (options: {
+    readonly compress: boolean;
+    readonly getBuild: () => BuildState | null;
+}) => Plugin[];

package/dist/build/output-plugins.js

@@ -0,0 +1,88 @@
+import { viteSingleFile } from 'vite-plugin-singlefile';
+import { isUnder, realFileOf } from "../module-paths.js";
+import { resolvedId } from "../sync/script-graph.js";
+import { toClassicScriptHtml } from "./classic-script.js";
+import { toCompressedHtml } from "./compress.js";
+import { GLTF_LOADER_SPECIFIER, GLTF_LOADER_STUB_ID, POSTPROCESSING_STUB_ID, YAML_STUB_ID, } from "./player-modules.js";
+/**
+ * The optional libraries a build leaves out (CLAUDE.md «Playable export size»), part of the
+ * strip (`strip: false` keeps them all). `enforce: 'pre'`, because Vite's own resolver runs
+ * before a normal plugin's `resolveId`. Every one is stubbed **for the runtime's own importers
+ * only** (real paths compared): a project script or a dependency that imports the library
+ * itself always gets the real one — and the scan counts that import as a use, so the runtime
+ * shares the real copy then too.
+ *
+ * - `postprocessing` in a single-file build with no PostProcess node and no import of it — the
+ *   runtime's `import('postprocessing')` would be inlined whole;
+ * - `yaml` — the scenes ship as JSON (`shippedBytes`), so `SceneLoader`'s `parse` is
+ *   `JSON.parse` (plan §B.6 item 4, done the 1.x way: no runtime change, no second format);
+ * - `GLTFLoader` when no scene, script, library or asset names a model.
+ */
+export const libraryStubsPlugin = (getBuild) => ({
+    name: 'pix3:library-stubs',
+    apply: 'build',
+    enforce: 'pre',
+    resolveId(id, importer) {
+        const build = getBuild();
+        if (!build?.stripEnabled || !importer || importer.startsWith('\0'))
+            return null;
+        if (id !== 'postprocessing' && id !== 'yaml' && id !== GLTF_LOADER_SPECIFIER)
+            return null;
+        if (!isUnder(realFileOf(importer), build.runtimeSrc))
+            return null;
+        if (id === 'postprocessing' && build.format === 'html' && !build.scan.usesPostProcessing) {
+            build.applied.postprocessing = true;
+            return resolvedId(POSTPROCESSING_STUB_ID);
+        }
+        if (id === 'yaml' && build.stubYaml) {
+            build.applied.yaml = true;
+            return resolvedId(YAML_STUB_ID);
+        }
+        if (id === GLTF_LOADER_SPECIFIER && build.stubGltf) {
+            build.applied.gltf = true;
+            return resolvedId(GLTF_LOADER_STUB_ID);
+        }
+        return null;
+    },
+});
+/**
+ * `build: 'html'` (only then are these in the plugin list): inline every chunk and stylesheet into `index.html` (plan §B.6 item 5), then
+ * make that one script classic, at the end of `<body>` (DeepCore's compatibility plugin), and
+ * with `compress` replace it by the gzip payload and its bootstrap (`build/compress.ts`).
+ */
+export const singleFilePlugins = (options) => {
+    const singleFile = {
+        ...viteSingleFile({
+            useRecommendedBuildConfig: false,
+            // `modulePreload: false` (vite-config.ts) means there is no preload polyfill to remove — and
+            // the removal's regex takes the first IIFE it sees for that polyfill, which in a compressed
+            // (`iife`) build is the head of the bundle itself.
+            removeViteModuleLoader: false,
+        }),
+        name: 'pix3:single-file',
+        apply: 'build',
+    };
+    const classicScript = {
+        name: 'pix3:classic-script',
+        apply: 'build',
+        enforce: 'post',
+        generateBundle(_options, bundle) {
+            for (const output of Object.values(bundle)) {
+                if (output.type !== 'asset' || !output.fileName.endsWith('.html'))
+                    continue;
+                const html = typeof output.source === 'string'
+                    ? output.source
+                    : Buffer.from(output.source).toString('utf8');
+                const classic = toClassicScriptHtml(html);
+                const build = options.compress ? options.getBuild() : null;
+                if (!build) {
+                    output.source = classic;
+                    continue;
+                }
+                build.compressed = toCompressedHtml(classic);
+                output.source = build.compressed.html;
+            }
+        },
+    };
+    return [singleFile, classicScript];
+};