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

package/dist/build/plan.d.ts

@@ -0,0 +1,75 @@
+import type { CompressedHtml } from './compress.ts';
+import { type EmbeddedAssetsResult } from './player-modules.ts';
+import { type ProjectManifestInfo } from './project-manifest.ts';
+import type { ModuleClassifier, ModuleSize } from './report.ts';
+import { type ProjectScan } from './scan.ts';
+import { type StripOption } from './strip-decision.ts';
+/** What `buildStart` learned about the project for this `vite build`, plus what the bundle told. */
+export interface BuildState {
+    readonly format: 'html' | 'zip';
+    readonly manifest: ProjectManifestInfo;
+    readonly scan: ProjectScan;
+    /** Module paths (under the runtime's `src/`) replaced by stubs. */
+    readonly stripped: ReadonlySet<string>;
+    /** `name a dependency may import → the stripped module it keeps` (the transform net). */
+    readonly stubbedNames: ReadonlyMap<string, string>;
+    readonly stripReason: string | null;
+    readonly stripEnabled: boolean;
+    /** Whether `pix3({ strip })` was set at all (the net errors only when it was not). */
+    readonly stripConfigured: boolean;
+    readonly keep: readonly string[];
+    /** N11: what the dependencies that declare the runtime import from it, and how many files. */
+    readonly dependencyImports: ReadonlySet<string>;
+    readonly dependencyParsed: Record<string, number>;
+    /** Real path of the runtime's `src/`, or null when it did not resolve. */
+    readonly runtimeSrc: string | null;
+    /** How the report and the net name a module id. */
+    readonly classifier: ModuleClassifier;
+    readonly spineInstalled: boolean;
+    readonly postprocessingInstalled: boolean;
+    /** Scenes ship as JSON and the runtime's `yaml` is `JSON.parse`. */
+    readonly stubYaml: boolean;
+    /** No model in the project: `GLTFLoader` is a stub. */
+    readonly stubGltf: boolean;
+    /**
+     * Filled by the bundle hooks, for the report: what the hooks actually replaced (a runtime that
+     * resolves under another path than the one `buildStart` saw would leave these empty).
+     */
+    readonly applied: {
+        readonly modules: Set<string>;
+        yaml: boolean;
+        gltf: boolean;
+        postprocessing: boolean;
+    };
+    readonly moduleSizes: ModuleSize[];
+    bundleBytes: number;
+    assets: EmbeddedAssetsResult | null;
+    compressed: CompressedHtml | null;
+}
+export interface PlanBuildOptions {
+    readonly root: string;
+    readonly format: 'html' | 'zip';
+    readonly resRoot: string;
+    readonly entryScene: string | null;
+    readonly strip: StripOption | undefined;
+    readonly compress: boolean;
+    /** This package's directory (the player's modules are grouped as `player`). */
+    readonly packageDir: string;
+    /** The bundler's resolver from the project's `index.html`: the resolved id, or null. */
+    readonly resolve: (specifier: string) => Promise<string | null>;
+    /** The bundler's `this.parse`. */
+    readonly parse: (code: string) => unknown;
+    readonly log: (line: string) => void;
+    readonly warn: (line: string) => void;
+}
+/** Step 0: flush the editor that `.pix3/dev.json` points at; an unsynced editor fails the build. */
+export declare const flushEditor: (root: string, log: (line: string) => void, fail: (message: string) => never) => Promise<void>;
+/**
+ * Plan §B.6 items 1–2: one scan of every text source (the project's and, N11, every dependency
+ * that declares the runtime) decides what ships and what the stubs replace.
+ */
+export declare const planBuild: (options: PlanBuildOptions) => Promise<BuildState>;
+/** The module path under the runtime's `src/` of a `.ts` module id (`core/Foo`), or null. */
+export declare const runtimeModulePath: (build: BuildState | null, id: string) => string | null;
+/** The bytes an asset ships as: a scene or prefab as JSON when the runtime's `yaml` is a stub. */
+export declare const shippedBytes: (build: BuildState, resPath: string, bytes: Buffer, warn: (line: string) => void) => Buffer;

package/dist/build/plan.js

@@ -0,0 +1,162 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileOf, realFileOf, relativeInside } from "../module-paths.js";
+import { RUNTIME_SPECIFIER, scanDependencyImports } from "./dependency-imports.js";
+import { EditorUnsyncedError, flushEditorBeforeBuild } from "./editor-flush.js";
+import { EMBEDDED_ASSETS_ID, SCENE_LIKE_ASSET, sceneAsJson, } from "./player-modules.js";
+import { readProjectManifest } from "./project-manifest.js";
+import { scanProject } from "./scan.js";
+import { decideStrip, runtimeDependents } from "./strip-decision.js";
+import { resolveStrippableRuntimeModules, valueExportNames } from "./strippable-runtime-modules.js";
+/** A `.glb`/`.gltf` (any case) or the loader by name. */
+const MODEL_MENTION = /^(?:glb|gltf|GLTFLoader)$/i;
+/** Step 0: flush the editor that `.pix3/dev.json` points at; an unsynced editor fails the build. */
+export const flushEditor = async (root, log, fail) => {
+    try {
+        const flushed = await flushEditorBeforeBuild(root);
+        if (flushed.status === 'flushed')
+            log(`editor at ${flushed.url} flushed its unsaved scenes`);
+        else if (flushed.status === 'no-editor')
+            log(`dev server at ${flushed.url}: no editor tab open`);
+        else if (flushed.status === 'no-server' && flushed.url)
+            log(`no dev server at ${flushed.url} (${flushed.reason}): .pix3/dev.json is stale`);
+    }
+    catch (error) {
+        if (error instanceof EditorUnsyncedError)
+            fail(`${error.code}: ${error.message}`);
+        throw error;
+    }
+};
+/**
+ * Plan §B.6 items 1–2: one scan of every text source (the project's and, N11, every dependency
+ * that declares the runtime) decides what ships and what the stubs replace.
+ */
+export const planBuild = async (options) => {
+    const { root, format, log, warn } = options;
+    const manifest = readProjectManifest(root);
+    const runtime = await options.resolve(RUNTIME_SPECIFIER);
+    const runtimeSrc = runtime ? dirname(realFileOf(runtime)) : null;
+    if (!runtimeSrc)
+        warn('@pix3/runtime did not resolve from the project; nothing is stripped');
+    const spineInstalled = (await options.resolve('@esotericsoftware/spine-threejs')) !== null;
+    const postprocessingInstalled = (await options.resolve('postprocessing')) !== null;
+    const dependencyScan = await scanDependencyImports({
+        root,
+        packages: options.strip === false ? [] : runtimeDependents(root),
+        parse: options.parse,
+    });
+    const scan = await scanProject({
+        root,
+        resRoot: options.resRoot,
+        manifest,
+        entryScene: options.entryScene,
+        dependencies: dependencyScan,
+    });
+    for (const warning of scan.warnings)
+        warn(warning);
+    if (!scan.entryScenePath)
+        warn('no .pix3scene found: the player will have nothing to boot');
+    if (scan.usesSpine && !spineInstalled)
+        warn('a scene places a SpineSkeleton2D but @esotericsoftware/spine-threejs is not installed');
+    const decision = decideStrip(options.strip, dependencyScan);
+    const nameSets = [
+        scan.mentionedNames,
+        dependencyScan.names,
+        dependencyScan.mentionedNames,
+        new Set(decision.keep),
+    ];
+    const mentions = (name) => nameSets.some(names => names.has(name));
+    const stripped = new Set();
+    const stubbedNames = new Map();
+    if (decision.enabled && runtimeSrc) {
+        // Every value export keeps its module too (the barrel re-exports them all): a mention of
+        // `pointInPolygon` keeps `collision-shapes-2d`, and the net knows every stubbed name.
+        const exportsOf = new Map();
+        const readExports = (modulePath) => {
+            let names = exportsOf.get(modulePath);
+            if (!names) {
+                try {
+                    names = valueExportNames(readFileSync(join(runtimeSrc, `${modulePath}.ts`), 'utf8'));
+                }
+                catch {
+                    names = [];
+                }
+                exportsOf.set(modulePath, names);
+            }
+            return names;
+        };
+        for (const entry of resolveStrippableRuntimeModules(mentions, readExports)) {
+            stripped.add(entry.modulePath);
+            for (const name of [...entry.keepWhenMentioned, ...readExports(entry.modulePath)])
+                stubbedNames.set(name, entry.modulePath);
+        }
+    }
+    // Case-insensitive, like the asset test: `crate.GLB` names a model as well.
+    const stubGltf = decision.enabled &&
+        runtimeSrc !== null &&
+        !nameSets.some(names => [...names].some(name => MODEL_MENTION.test(name))) &&
+        !scan.assetPaths.some(path => /\.(glb|gltf)$/i.test(path));
+    for (const [name, files] of Object.entries(dependencyScan.parsed)) {
+        log(`${name} depends on ${RUNTIME_SPECIFIER}: ${files} file(s) parsed` +
+            (dependencyScan.names.size > 0
+                ? `, keeping ${[...dependencyScan.names].sort().join(', ')}`
+                : ''));
+    }
+    log(`build ${format}${options.compress && format === 'html' ? ' (compressed)' : ''}: ` +
+        `entry ${scan.entryScenePath || '(none)'}, ${scan.scenePaths.length} scene(s), ` +
+        `${scan.assetPaths.length} asset(s), ${scan.textSourceCount} text source(s) scanned; ` +
+        (decision.enabled
+            ? `strip on (${stripped.size} module(s)${stubGltf ? ', GLTFLoader' : ''}, scenes as JSON)` +
+                (decision.reason ? ` — ${decision.reason}` : '')
+            : `strip off — ${decision.reason}`));
+    if (options.compress && format === 'zip')
+        warn('compress applies to build: "html" only; the zip is written as is');
+    return {
+        format,
+        manifest,
+        scan,
+        stripped,
+        stubbedNames,
+        stripReason: decision.reason,
+        stripEnabled: decision.enabled,
+        stripConfigured: options.strip !== undefined,
+        keep: decision.keep,
+        dependencyImports: dependencyScan.names,
+        dependencyParsed: dependencyScan.parsed,
+        runtimeSrc,
+        classifier: {
+            root,
+            runtimeSrc,
+            playerDir: options.packageDir,
+            embeddedAssetsId: EMBEDDED_ASSETS_ID,
+        },
+        spineInstalled,
+        postprocessingInstalled,
+        stubYaml: decision.enabled,
+        stubGltf,
+        applied: { modules: new Set(), yaml: false, gltf: false, postprocessing: false },
+        moduleSizes: [],
+        bundleBytes: 0,
+        assets: null,
+        compressed: null,
+    };
+};
+/** The module path under the runtime's `src/` of a `.ts` module id (`core/Foo`), or null. */
+export const runtimeModulePath = (build, id) => {
+    if (!build?.runtimeSrc || !fileOf(id).endsWith('.ts'))
+        return null;
+    return relativeInside(build.runtimeSrc, realFileOf(id))?.replace(/\.ts$/, '') ?? null;
+};
+/** The bytes an asset ships as: a scene or prefab as JSON when the runtime's `yaml` is a stub. */
+export const shippedBytes = (build, resPath, bytes, warn) => {
+    if (!build.stubYaml || !SCENE_LIKE_ASSET.test(resPath))
+        return bytes;
+    try {
+        return Buffer.from(sceneAsJson(bytes.toString('utf8')), 'utf8');
+    }
+    catch (error) {
+        // Not YAML the build can read: ship it as is; the runtime reports it when it loads.
+        warn(`${resPath} did not parse as YAML (${String(error)}); shipped as written`);
+        return bytes;
+    }
+};

package/dist/build/player-modules.d.ts

@@ -0,0 +1,99 @@
+import { type LocalizationSettings, type ProjectManifestInfo } from './project-manifest.ts';
+/**
+ * The `virtual:pix3/*` modules the player (`@pix3/vite-plugin/player`) imports (plan §B.5). Each
+ * is generated here from the project, in dev from `pix3project.yaml` and the scene list, in a
+ * build from the scan (`scan.ts`). The seams for the optional libraries are **static** imports
+ * inside the generated module — a dynamic import would become a chunk a single-file HTML can never
+ * fetch, and a bare specifier left unaliased is silently externalised (the 1.x `postprocessing`
+ * bug, CLAUDE.md «Playable export size»).
+ */
+export declare const SCENE_MANIFEST_ID = "virtual:pix3/scene-manifest";
+export declare const EMBEDDED_ASSETS_ID = "virtual:pix3/embedded-assets";
+export declare const PROJECT_SCRIPTS_ID = "virtual:pix3/project-scripts";
+export declare const SPINE_ID = "virtual:pix3/spine";
+export declare const POSTPROCESSING_ID = "virtual:pix3/postprocessing";
+export declare const NETWORK_ID = "virtual:pix3/network";
+/** What `postprocessing` resolves to in a single-file build whose scenes place no `PostProcess`. */
+export declare const POSTPROCESSING_STUB_ID = "virtual:pix3/postprocessing-stub";
+/** What `yaml` resolves to for the runtime when the scenes ship as JSON. */
+export declare const YAML_STUB_ID = "virtual:pix3/yaml-stub";
+/** What `three/examples/jsm/loaders/GLTFLoader.js` resolves to when no model is shipped. */
+export declare const GLTF_LOADER_STUB_ID = "virtual:pix3/gltf-loader-stub";
+export declare const PLAYER_VIRTUAL_IDS: readonly string[];
+export interface SceneManifestModel {
+    readonly scenePaths: readonly string[];
+    readonly entryScenePath: string;
+    readonly manifest: ProjectManifestInfo;
+    readonly localization: LocalizationSettings | null;
+    readonly netKindPrefabs: readonly string[];
+    /** `ResourceManager` base: `/<resRoot>/` in dev, `./` for a build. */
+    readonly resourceBase: string;
+}
+export declare const sceneManifestSource: (model: SceneManifestModel) => string;
+/** The eager glob root of the project's scripts — the player's `register-project-scripts`. */
+export declare const projectScriptsSource: () => string;
+export interface EmbeddedAssetsSourceOptions {
+    readonly root: string;
+    readonly resRoot: string;
+    /** `res://`-relative paths to embed. */
+    readonly assetPaths: readonly string[];
+    /** The bytes that ship for a path (a scene as JSON, say); the file's own bytes by default. */
+    readonly shippedBytes?: (resPath: string, bytes: Buffer) => Buffer;
+}
+export interface EmbeddedAssetEntry {
+    readonly path: string;
+    readonly rawBytes: number;
+    readonly base64Bytes: number;
+}
+export interface EmbeddedAssetsResult {
+    readonly source: string;
+    readonly rawBytes: number;
+    readonly base64Bytes: number;
+    readonly count: number;
+    /** Largest first. */
+    readonly entries: readonly EmbeddedAssetEntry[];
+}
+/** Asset entries largest first, then by path. */
+export declare const largestFirst: (a: EmbeddedAssetEntry, b: EmbeddedAssetEntry) => number;
+/** `{ [resPath]: { base64, mimeType } }` of every shipped asset (single-file build). */
+export declare const embeddedAssetsSource: (options: EmbeddedAssetsSourceOptions) => Promise<EmbeddedAssetsResult>;
+/** Scene-shaped resources (`.pix3scene`, `.prefab`): the ones the runtime parses as YAML. */
+export declare const SCENE_LIKE_ASSET: RegExp;
+/**
+ * A scene's bytes for a build that stubs `yaml` ({@link yamlStubSource}): the same document as
+ * JSON. JSON is YAML, so a project script that reads the text with its own `yaml` import still
+ * parses it; the runtime's `parse` becomes `JSON.parse`. The 1.x export did the same.
+ */
+export declare const sceneAsJson: (text: string) => string;
+/**
+ * What `yaml` resolves to **for the runtime's own importers** (`SceneLoader`, `SceneSaver`) when
+ * every scene ships as JSON: `parse` is `JSON.parse`, `stringify` throws (a player never writes a
+ * scene — `SceneSaver` is not even constructed, so this tree-shakes out). A project module that
+ * imports `yaml` itself keeps the real parser; this stub is decided per importer.
+ */
+export declare const yamlStubSource: () => string;
+/** The specifier `AssetLoader` imports the loader by. */
+export declare const GLTF_LOADER_SPECIFIER = "three/examples/jsm/loaders/GLTFLoader.js";
+/**
+ * `GLTFLoader` (three addons, ~100 KiB rendered) is value-imported by `AssetLoader` for every
+ * build; a project with no `.glb`/`.gltf` asset and no script naming `GLTFLoader` gets a loader
+ * that fails the way a missing file would (the 1.x `gltf-loader-stub`).
+ */
+export declare const gltfLoaderStubSource: () => string;
+export declare const noEmbeddedAssetsSource: () => string;
+/**
+ * `virtual:pix3/spine`. Dev: the lazy loader (`virtual:pix3/spine-loader` decides whether the
+ * package is installed). Build: a static import when a scene places a `SpineSkeleton2D` and the
+ * package is installed, nothing otherwise.
+ */
+export declare const spineSource: (mode: "dev" | "static" | "none") => string;
+/**
+ * `virtual:pix3/postprocessing`. The runtime's default is `import('postprocessing')`, which is
+ * right in dev and in a zip (a chunk can be fetched). A single-file build registers the module
+ * statically when a scene places a `PostProcess`; otherwise `postprocessing` itself resolves to
+ * {@link postprocessingStubSource}, so the inlined dynamic import costs nothing.
+ */
+export declare const postprocessingSource: (mode: "default" | "static") => string;
+export declare const postprocessingStubSource: () => string;
+/** `virtual:pix3/network`: the real installer, or a no-op that keeps `net/**` out of the bundle. */
+export declare const networkSource: (usesNetwork: boolean) => string;

package/dist/build/player-modules.js

@@ -0,0 +1,204 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import { contentTypeFor } from "../files/content-type.js";
+import { globPatterns, SCRIPT_DIRS } from "../sync/script-graph.js";
+import { resToAbsolute, } from "./project-manifest.js";
+/**
+ * The `virtual:pix3/*` modules the player (`@pix3/vite-plugin/player`) imports (plan §B.5). Each
+ * is generated here from the project, in dev from `pix3project.yaml` and the scene list, in a
+ * build from the scan (`scan.ts`). The seams for the optional libraries are **static** imports
+ * inside the generated module — a dynamic import would become a chunk a single-file HTML can never
+ * fetch, and a bare specifier left unaliased is silently externalised (the 1.x `postprocessing`
+ * bug, CLAUDE.md «Playable export size»).
+ */
+export const SCENE_MANIFEST_ID = 'virtual:pix3/scene-manifest';
+export const EMBEDDED_ASSETS_ID = 'virtual:pix3/embedded-assets';
+export const PROJECT_SCRIPTS_ID = 'virtual:pix3/project-scripts';
+export const SPINE_ID = 'virtual:pix3/spine';
+export const POSTPROCESSING_ID = 'virtual:pix3/postprocessing';
+export const NETWORK_ID = 'virtual:pix3/network';
+/** What `postprocessing` resolves to in a single-file build whose scenes place no `PostProcess`. */
+export const POSTPROCESSING_STUB_ID = 'virtual:pix3/postprocessing-stub';
+/** What `yaml` resolves to for the runtime when the scenes ship as JSON. */
+export const YAML_STUB_ID = 'virtual:pix3/yaml-stub';
+/** What `three/examples/jsm/loaders/GLTFLoader.js` resolves to when no model is shipped. */
+export const GLTF_LOADER_STUB_ID = 'virtual:pix3/gltf-loader-stub';
+export const PLAYER_VIRTUAL_IDS = [
+    SCENE_MANIFEST_ID,
+    EMBEDDED_ASSETS_ID,
+    PROJECT_SCRIPTS_ID,
+    SPINE_ID,
+    POSTPROCESSING_ID,
+    NETWORK_ID,
+    POSTPROCESSING_STUB_ID,
+    YAML_STUB_ID,
+    GLTF_LOADER_STUB_ID,
+];
+const json = (value) => JSON.stringify(value, null, 2);
+export const sceneManifestSource = (model) => [
+    `export const scenePaths = ${json(model.scenePaths)};`,
+    `export const activeScenePath = ${json(model.entryScenePath)};`,
+    `export const resourceBase = ${json(model.resourceBase)};`,
+    `export const projectName = ${json(model.manifest.projectName)};`,
+    `export const runtimeViewportBaseSize = ${json(model.manifest.viewportBaseSize)};`,
+    `export const runtimeQuality = ${json(model.manifest.quality)};`,
+    `export const runtimeFonts = ${json(model.manifest.fonts)};`,
+    `export const runtimeLocalization = ${json(model.localization)};`,
+    // Autoloads (`pix3project.yaml` `autoloads:`): the player hands them to the runner, which
+    // builds them from the project-scripts registry once per session.
+    `export const runtimeAutoloads = ${json(model.manifest.autoloads)};`,
+    // Multiplayer kind table (D6): the wire Kind is the index into `prefabs`; sorted by code
+    // point so every build of this project agrees with the room allowlist.
+    `export const netKindTable = ${json({ prefabs: model.netKindPrefabs, authored: [] })};`,
+    '',
+].join('\n');
+/** The eager glob root of the project's scripts — the player's `register-project-scripts`. */
+export const projectScriptsSource = () => `export const modules = import.meta.glob(${JSON.stringify(globPatterns(SCRIPT_DIRS))}, { eager: true });\n`;
+/** Asset entries largest first, then by path. */
+export const largestFirst = (a, b) => b.rawBytes - a.rawBytes || (a.path < b.path ? -1 : 1);
+/** `{ [resPath]: { base64, mimeType } }` of every shipped asset (single-file build). */
+export const embeddedAssetsSource = async (options) => {
+    const lines = [];
+    const entries = [];
+    let rawBytes = 0;
+    let base64Bytes = 0;
+    for (const resPath of options.assetPaths) {
+        const file = await readFile(resToAbsolute(options.root, options.resRoot, resPath));
+        const bytes = options.shippedBytes ? options.shippedBytes(resPath, file) : file;
+        const base64 = bytes.toString('base64');
+        rawBytes += bytes.byteLength;
+        base64Bytes += base64.length;
+        entries.push({ path: resPath, rawBytes: bytes.byteLength, base64Bytes: base64.length });
+        lines.push(`${JSON.stringify(resPath)}: { base64: ${JSON.stringify(base64)}, mimeType: ${JSON.stringify(contentTypeFor(resPath).split(';')[0])} }`);
+    }
+    entries.sort(largestFirst);
+    return {
+        source: `export const embeddedAssets = {\n${lines.join(',\n')}\n};\n`,
+        rawBytes,
+        base64Bytes,
+        count: options.assetPaths.length,
+        entries,
+    };
+};
+/** Scene-shaped resources (`.pix3scene`, `.prefab`): the ones the runtime parses as YAML. */
+export const SCENE_LIKE_ASSET = /\.(pix3scene|prefab)$/i;
+/**
+ * A scene's bytes for a build that stubs `yaml` ({@link yamlStubSource}): the same document as
+ * JSON. JSON is YAML, so a project script that reads the text with its own `yaml` import still
+ * parses it; the runtime's `parse` becomes `JSON.parse`. The 1.x export did the same.
+ */
+export const sceneAsJson = (text) => JSON.stringify(parseYaml(text));
+/**
+ * What `yaml` resolves to **for the runtime's own importers** (`SceneLoader`, `SceneSaver`) when
+ * every scene ships as JSON: `parse` is `JSON.parse`, `stringify` throws (a player never writes a
+ * scene — `SceneSaver` is not even constructed, so this tree-shakes out). A project module that
+ * imports `yaml` itself keeps the real parser; this stub is decided per importer.
+ */
+export const yamlStubSource = () => [
+    '// Scenes and prefabs ship as JSON in this build: the YAML parser is not bundled.',
+    'export const parse = text => JSON.parse(text);',
+    "export const stringify = () => { throw new Error('[Pix3] yaml.stringify was stripped from this build: a player never writes scenes.'); };",
+    'export default { parse, stringify };',
+    '',
+].join('\n');
+/** The specifier `AssetLoader` imports the loader by. */
+export const GLTF_LOADER_SPECIFIER = 'three/examples/jsm/loaders/GLTFLoader.js';
+/**
+ * `GLTFLoader` (three addons, ~100 KiB rendered) is value-imported by `AssetLoader` for every
+ * build; a project with no `.glb`/`.gltf` asset and no script naming `GLTFLoader` gets a loader
+ * that fails the way a missing file would (the 1.x `gltf-loader-stub`).
+ */
+export const gltfLoaderStubSource = () => [
+    '// Stripped from this build: no scene or script names a .glb/.gltf model.',
+    "const stripped = () => new Error('[Pix3] GLTFLoader was stripped from this build because no scene or script names a .glb/.gltf model.');",
+    'export class GLTFLoader {',
+    '  setPath() { return this; }',
+    '  setResourcePath() { return this; }',
+    '  setDRACOLoader() { return this; }',
+    '  setKTX2Loader() { return this; }',
+    '  setMeshoptDecoder() { return this; }',
+    '  register() { return this; }',
+    '  unregister() { return this; }',
+    '  load(_url, _onLoad, _onProgress, onError) { const error = stripped(); if (onError) onError(error); else throw error; }',
+    '  loadAsync() { return Promise.reject(stripped()); }',
+    '  parse(_data, _path, _onLoad, onError) { const error = stripped(); if (onError) onError(error); else throw error; }',
+    '  parseAsync() { return Promise.reject(stripped()); }',
+    '}',
+    '',
+].join('\n');
+export const noEmbeddedAssetsSource = () => `export const embeddedAssets = {};\n`;
+/**
+ * `virtual:pix3/spine`. Dev: the lazy loader (`virtual:pix3/spine-loader` decides whether the
+ * package is installed). Build: a static import when a scene places a `SpineSkeleton2D` and the
+ * package is installed, nothing otherwise.
+ */
+export const spineSource = (mode) => {
+    if (mode === 'none') {
+        return '// No SpineSkeleton2D in this project: Spine is not bundled.\nexport {};\n';
+    }
+    if (mode === 'static') {
+        return [
+            `import * as spine from '@esotericsoftware/spine-threejs';`,
+            `import { setSpineModuleLoader } from '@pix3/runtime';`,
+            `setSpineModuleLoader(() => Promise.resolve(spine));`,
+            '',
+        ].join('\n');
+    }
+    return [
+        `import { loadSpine } from 'virtual:pix3/spine-loader';`,
+        `import { setSpineModuleLoader } from '@pix3/runtime';`,
+        `setSpineModuleLoader(async () => {`,
+        `  const spine = await loadSpine();`,
+        `  if (!spine) throw new Error('This scene uses Spine, but @esotericsoftware/spine-threejs is not installed in the project.');`,
+        `  return spine;`,
+        `});`,
+        '',
+    ].join('\n');
+};
+/**
+ * `virtual:pix3/postprocessing`. The runtime's default is `import('postprocessing')`, which is
+ * right in dev and in a zip (a chunk can be fetched). A single-file build registers the module
+ * statically when a scene places a `PostProcess`; otherwise `postprocessing` itself resolves to
+ * {@link postprocessingStubSource}, so the inlined dynamic import costs nothing.
+ */
+export const postprocessingSource = (mode) => mode === 'static'
+    ? [
+        `import * as postprocessing from 'postprocessing';`,
+        `import { setPostprocessingModuleLoader } from '@pix3/runtime';`,
+        `setPostprocessingModuleLoader(() => Promise.resolve(postprocessing));`,
+        '',
+    ].join('\n')
+    : '// No PostProcess node in this project: the effect stack is not registered.\nexport {};\n';
+export const postprocessingStubSource = () => [
+    '// Stripped from this build: no scene places a PostProcess node.',
+    `const stripped = () => { throw new Error('[Pix3] postprocessing was stripped from this build because no scene places a PostProcess node.'); };`,
+    'export const EffectComposer = stripped;',
+    'export const RenderPass = stripped;',
+    'export const EffectPass = stripped;',
+    'export const ClearPass = stripped;',
+    'export const NormalPass = stripped;',
+    'export const DepthDownsamplingPass = stripped;',
+    'export const BloomEffect = stripped;',
+    'export const VignetteEffect = stripped;',
+    'export const ChromaticAberrationEffect = stripped;',
+    'export const SSAOEffect = stripped;',
+    'export const BlendFunction = {};',
+    'export const KernelSize = {};',
+    '',
+].join('\n');
+/** `virtual:pix3/network`: the real installer, or a no-op that keeps `net/**` out of the bundle. */
+export const networkSource = (usesNetwork) => usesNetwork
+    ? [
+        `import { NetworkService, setNetworkPrefabTable } from '@pix3/runtime';`,
+        `import { netKindTable } from 'virtual:pix3/scene-manifest';`,
+        `export function installNetworkService(runner) {`,
+        `  setNetworkPrefabTable(netKindTable);`,
+        `  runner.setNetworkService(new NetworkService());`,
+        `}`,
+        '',
+    ].join('\n')
+    : [
+        '// Nothing in this project mentions multiplayer: `net/**` is not bundled.',
+        'export function installNetworkService() {}',
+        '',
+    ].join('\n');

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

@@ -0,0 +1,57 @@
+/**
+ * The part of `pix3project.yaml` the player and the build read (plan §B.5 «scene-manifest из
+ * pix3project.yaml»). A Node-side subset of the editor's `normalizeProjectManifest`
+ * (`packages/editor-core/src/core/ProjectManifest.ts`): same defaults, same clamps, so a build and
+ * the editor's play mode agree on viewport, quality, fonts and locales.
+ */
+export declare const PROJECT_MANIFEST_FILE = "pix3project.yaml";
+export interface QualitySettings {
+    readonly antialias: boolean;
+    readonly shadows: boolean;
+    readonly maxPixelRatio: number;
+}
+export interface ProjectFontFace {
+    readonly family: string;
+    readonly path: string;
+    readonly weight?: number | string;
+    readonly style?: 'normal' | 'italic';
+    readonly unicodeRange?: string;
+}
+export interface LocalizationSettings {
+    readonly defaultLocale: string;
+    readonly fallbackLocale?: string;
+    readonly locales: readonly string[];
+}
+/** One `autoloads:` entry (the runtime's `AutoloadConfig`). */
+export interface AutoloadEntry {
+    readonly singleton: string;
+    readonly scriptPath: string;
+    readonly enabled: boolean;
+}
+export interface ProjectManifestInfo {
+    readonly projectName: string;
+    /** `defaultExportScenePath` without `res://`, or null. */
+    readonly defaultScenePath: string | null;
+    readonly viewportBaseSize: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly quality: QualitySettings;
+    readonly fonts: readonly ProjectFontFace[];
+    /** The manifest's `localization` block, normalised; null = inert. */
+    readonly localization: LocalizationSettings | null;
+    /** The `autoloads:` list, read as the runtime's `normalizeAutoloads` reads it. */
+    readonly autoloads: readonly AutoloadEntry[];
+}
+/** `res://x`, `./x`, `/x` → `x`. */
+export declare const stripRes: (path: string) => string;
+/** `pix3({ resRoot })` as the build and the server use it: no scheme, no trailing `/`, `'.'` for the root. */
+export declare const normalizeResRoot: (resRoot: string) => string;
+/** A project wire path → its `res://`-relative path, or null outside `resRoot`. */
+export declare const wireToRes: (wirePath: string, resRoot: string) => string | null;
+/** The absolute file of a `res://`-relative path. */
+export declare const resToAbsolute: (root: string, resRoot: string, resPath: string) => string;
+/** Parse the manifest text (an empty or malformed manifest yields the defaults). */
+export declare const parseProjectManifest: (text: string, fallbackName: string) => ProjectManifestInfo;
+/** The manifest of the project at `root` (defaults when there is none). */
+export declare const readProjectManifest: (root: string) => ProjectManifestInfo;