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

package/dist/files/scan.d.ts

@@ -0,0 +1,71 @@
+import { type BigIntStats } from 'node:fs';
+/**
+ * The revision set and the file table the plugin keeps of it (port of
+ * `packages/cli/src/serve/scan.ts`).
+ *
+ * "Everything that ships" is decided the way `ProjectBuildService.collectShippableProjectFiles`
+ * decides it: walk the whole root, skip directories named in `NON_SHIPPABLE_DIRECTORIES` at any
+ * depth — plus `.pix3/` at the root (the plugin's state). Scenes, prefabs, scripts, assets of every
+ * type, `design/tests/`, `locales/` and `pix3project.yaml` all fall inside that walk; nothing is
+ * filtered by extension. Symlinks are neither listed nor followed.
+ */
+/**
+ * Mirror of `NON_SHIPPABLE_DIRECTORIES` in
+ * `packages/editor-core/src/services/export/ProjectBuildService.ts` (the editor cannot be imported
+ * from here). Keep the two in sync.
+ */
+export declare const NON_SHIPPABLE_DIRECTORIES: ReadonlySet<string>;
+/**
+ * Name of the temp file a write uses when `.pix3/tmp/` is on another device than the target
+ * (rename cannot cross devices). Never part of the table, so it never shows up as a change.
+ */
+export declare const SIBLING_TEMP_PATTERN: RegExp;
+/** True when the wire path is outside the revision set (inside an excluded directory, or one itself). */
+export declare const isExcludedPath: (wirePath: string) => boolean;
+export interface FileEntry {
+    readonly kind: 'file' | 'dir';
+    readonly size: number;
+    /** Integer epoch milliseconds (what goes on the wire). */
+    readonly mtime: number;
+    /** `ino:size:mtimeNs` — the hash cache key; an atomic replace changes `ino` even at equal mtime. */
+    readonly statKey: string;
+    readonly sha256?: string;
+}
+export type FileTable = Map<string, FileEntry>;
+export declare const statKeyOf: (stats: BigIntStats) => string;
+export declare const mtimeOf: (stats: BigIntStats) => number;
+export declare const hashFile: (absolute: string) => Promise<string>;
+/**
+ * sha256 per wire path, reused while `(ino, size, mtimeNs)` is unchanged. Shared by the table
+ * scans and the read-only routes (`file` ETag, `hash`).
+ */
+export declare class HashCache {
+    private readonly entries;
+    private static readonly MAX_ENTRIES;
+    hash(wirePath: string, absolute: string, stats: BigIntStats): Promise<string>;
+    remember(wirePath: string, key: string, sha256: string): void;
+    forget(wirePath: string): void;
+}
+/**
+ * Scan `wirePath` (a file or a directory subtree; `''` = the whole root) into `out`.
+ * Missing paths, symlinks and excluded directories contribute nothing.
+ */
+export declare const scanInto: (root: string, wirePath: string, cache: HashCache, out: FileTable) => Promise<void>;
+/** `revision` = sha256 over the sorted `path:sha256` lines of every FILE, joined by `\n`. */
+export declare const computeRevision: (table: FileTable) => string;
+export interface ChangeEvent {
+    readonly op: 'create' | 'modify' | 'delete' | 'rename';
+    readonly path: string;
+    readonly kind: 'file' | 'dir';
+    readonly sha256?: string;
+    /** Only on `rename`: where the file was. */
+    readonly from?: string;
+}
+/**
+ * Replace the part of `table` at/under `prefix` with `fresh` (a scan of that prefix) and return
+ * what changed. A file whose stat changed but whose content did not is updated silently.
+ *
+ * A `delete` + `create` of identical content in the same batch becomes one `rename` when the
+ * pairing is unambiguous (exactly one deleted and one created file carry that hash).
+ */
+export declare const applySubtree: (table: FileTable, prefixes: readonly string[], fresh: FileTable) => ChangeEvent[];

package/dist/files/scan.js

@@ -0,0 +1,252 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errnoCode } from "../server/http.js";
+import { RESERVED_ROOT_DIR } from "./paths.js";
+/**
+ * The revision set and the file table the plugin keeps of it (port of
+ * `packages/cli/src/serve/scan.ts`).
+ *
+ * "Everything that ships" is decided the way `ProjectBuildService.collectShippableProjectFiles`
+ * decides it: walk the whole root, skip directories named in `NON_SHIPPABLE_DIRECTORIES` at any
+ * depth — plus `.pix3/` at the root (the plugin's state). Scenes, prefabs, scripts, assets of every
+ * type, `design/tests/`, `locales/` and `pix3project.yaml` all fall inside that walk; nothing is
+ * filtered by extension. Symlinks are neither listed nor followed.
+ */
+/**
+ * Mirror of `NON_SHIPPABLE_DIRECTORIES` in
+ * `packages/editor-core/src/services/export/ProjectBuildService.ts` (the editor cannot be imported
+ * from here). Keep the two in sync.
+ */
+export const NON_SHIPPABLE_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    '.yalc',
+    '.vscode',
+    '.idea',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.cache',
+]);
+/**
+ * Name of the temp file a write uses when `.pix3/tmp/` is on another device than the target
+ * (rename cannot cross devices). Never part of the table, so it never shows up as a change.
+ */
+export const SIBLING_TEMP_PATTERN = /^\..+\.pix3-tmp-[0-9a-f]+$/;
+/** True when the wire path is outside the revision set (inside an excluded directory, or one itself). */
+export const isExcludedPath = (wirePath) => {
+    const segments = wirePath.split('/');
+    if (segments[0] === RESERVED_ROOT_DIR)
+        return true;
+    if (SIBLING_TEMP_PATTERN.test(segments[segments.length - 1]))
+        return true;
+    // The last segment is excluded only as a directory; a FILE named `dist` is ordinary.
+    for (let i = 0; i < segments.length - 1; i++) {
+        if (NON_SHIPPABLE_DIRECTORIES.has(segments[i]))
+            return true;
+    }
+    return false;
+};
+const isExcludedDirectory = (wirePath, name) => wirePath === RESERVED_ROOT_DIR || NON_SHIPPABLE_DIRECTORIES.has(name);
+export const statKeyOf = (stats) => `${stats.ino}:${stats.size}:${stats.mtimeNs}`;
+export const mtimeOf = (stats) => Number(stats.mtimeNs / 1000000n);
+export const hashFile = (absolute) => new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(absolute);
+    stream.on('data', chunk => hash.update(chunk));
+    stream.on('error', reject);
+    stream.on('end', () => resolve(hash.digest('hex')));
+});
+/**
+ * sha256 per wire path, reused while `(ino, size, mtimeNs)` is unchanged. Shared by the table
+ * scans and the read-only routes (`file` ETag, `hash`).
+ */
+export class HashCache {
+    entries = new Map();
+    static MAX_ENTRIES = 200_000;
+    async hash(wirePath, absolute, stats) {
+        const key = statKeyOf(stats);
+        const cached = this.entries.get(wirePath);
+        if (cached && cached.key === key)
+            return cached.sha256;
+        const sha256 = await hashFile(absolute);
+        this.remember(wirePath, key, sha256);
+        return sha256;
+    }
+    remember(wirePath, key, sha256) {
+        if (this.entries.size >= HashCache.MAX_ENTRIES)
+            this.entries.clear();
+        this.entries.set(wirePath, { key, sha256 });
+    }
+    forget(wirePath) {
+        this.entries.delete(wirePath);
+    }
+}
+/**
+ * Scan `wirePath` (a file or a directory subtree; `''` = the whole root) into `out`.
+ * Missing paths, symlinks and excluded directories contribute nothing.
+ */
+export const scanInto = async (root, wirePath, cache, out) => {
+    const absolute = wirePath ? join(root, ...wirePath.split('/')) : root;
+    if (wirePath && isExcludedPath(wirePath))
+        return;
+    let stats;
+    try {
+        stats = await lstat(absolute, { bigint: true });
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return;
+        throw error;
+    }
+    if (stats.isFile()) {
+        if (!wirePath)
+            return;
+        let sha256;
+        try {
+            sha256 = await cache.hash(wirePath, absolute, stats);
+        }
+        catch (error) {
+            if (errnoCode(error) === 'ENOENT')
+                return; // vanished mid-scan; the next event says so
+            throw error;
+        }
+        out.set(wirePath, {
+            kind: 'file',
+            size: Number(stats.size),
+            mtime: mtimeOf(stats),
+            statKey: statKeyOf(stats),
+            sha256,
+        });
+        return;
+    }
+    if (!stats.isDirectory())
+        return;
+    const name = wirePath.slice(wirePath.lastIndexOf('/') + 1);
+    if (wirePath && isExcludedDirectory(wirePath, name))
+        return;
+    if (wirePath) {
+        out.set(wirePath, { kind: 'dir', size: 0, mtime: mtimeOf(stats), statKey: statKeyOf(stats) });
+    }
+    let names;
+    try {
+        names = await readdir(absolute);
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return;
+        throw error;
+    }
+    names.sort();
+    for (const child of names) {
+        await scanInto(root, wirePath ? `${wirePath}/${child}` : child, cache, out);
+    }
+};
+/** `revision` = sha256 over the sorted `path:sha256` lines of every FILE, joined by `\n`. */
+export const computeRevision = (table) => {
+    const lines = [];
+    for (const [path, entry] of table) {
+        if (entry.kind === 'file' && entry.sha256)
+            lines.push(`${path}:${entry.sha256}`);
+    }
+    lines.sort();
+    return createHash('sha256').update(lines.join('\n')).digest('hex');
+};
+const isUnder = (path, prefix) => prefix === '' || path === prefix || path.startsWith(`${prefix}/`);
+/**
+ * Replace the part of `table` at/under `prefix` with `fresh` (a scan of that prefix) and return
+ * what changed. A file whose stat changed but whose content did not is updated silently.
+ *
+ * A `delete` + `create` of identical content in the same batch becomes one `rename` when the
+ * pairing is unambiguous (exactly one deleted and one created file carry that hash).
+ */
+export const applySubtree = (table, prefixes, fresh) => {
+    const created = [];
+    const deleted = [];
+    const modified = [];
+    for (const [path, entry] of [...table]) {
+        if (!prefixes.some(prefix => isUnder(path, prefix)))
+            continue;
+        if (fresh.has(path))
+            continue;
+        table.delete(path);
+        deleted.push(deletion(path, entry));
+    }
+    for (const [path, entry] of fresh) {
+        const previous = table.get(path);
+        table.set(path, entry);
+        if (!previous) {
+            created.push({
+                op: 'create',
+                path,
+                kind: entry.kind,
+                ...(entry.sha256 ? { sha256: entry.sha256 } : {}),
+            });
+        }
+        else if (previous.kind !== entry.kind) {
+            deleted.push(deletion(path, previous));
+            created.push({
+                op: 'create',
+                path,
+                kind: entry.kind,
+                ...(entry.sha256 ? { sha256: entry.sha256 } : {}),
+            });
+        }
+        else if (entry.kind === 'file' && previous.sha256 !== entry.sha256) {
+            modified.push({
+                op: 'modify',
+                path,
+                kind: 'file',
+                ...(entry.sha256 ? { sha256: entry.sha256 } : {}),
+            });
+        }
+    }
+    return pairRenames(deleted, created, modified);
+};
+/** Deletes carry the hash they had only until pairing; `pairRenames` strips it from the output. */
+const deletion = (path, entry) => ({
+    op: 'delete',
+    path,
+    kind: entry.kind,
+    ...(entry.sha256 ? { sha256: entry.sha256 } : {}),
+});
+const pairRenames = (deleted, created, modified) => {
+    const countBy = (events) => {
+        const counts = new Map();
+        for (const event of events) {
+            if (event.kind === 'file' && event.sha256)
+                counts.set(event.sha256, (counts.get(event.sha256) ?? 0) + 1);
+        }
+        return counts;
+    };
+    const deletedCounts = countBy(deleted);
+    const createdCounts = countBy(created);
+    const renames = [];
+    const pairedDeletes = new Set();
+    const pairedCreates = new Set();
+    for (const create of created) {
+        const hash = create.sha256;
+        if (create.kind !== 'file' || !hash)
+            continue;
+        if (deletedCounts.get(hash) !== 1 || createdCounts.get(hash) !== 1)
+            continue;
+        const del = deleted.find(event => event.sha256 === hash);
+        if (!del)
+            continue;
+        pairedDeletes.add(del);
+        pairedCreates.add(create);
+        renames.push({ op: 'rename', path: create.path, from: del.path, kind: 'file', sha256: hash });
+    }
+    const strip = (event) => event.op === 'delete' ? { op: 'delete', path: event.path, kind: event.kind } : event;
+    return [
+        ...deleted.filter(event => !pairedDeletes.has(event)).map(strip),
+        ...renames,
+        ...created.filter(event => !pairedCreates.has(event)),
+        ...modified,
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+};

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { type Plugin } from 'vite';
+import type { StripOption } from './build/strip-decision.ts';
+/**
+ * `@pix3/vite-plugin`: the editor at `/__pix3/` with the file API and the sync barrier
+ * (`dev-server.ts`), the scripts' hot path (`sync/`), the player's `virtual:pix3/*` modules and
+ * the playable build (`build/`). This file wires the hooks; each concern lives in its module.
+ */
+export interface Pix3Options {
+    /** Where `res://` points, relative to the Vite root (DeepCore: `'src/assets'`). */
+    readonly resRoot?: string;
+    /** Serve the editor and the file API at `/__pix3/` (default true). */
+    readonly editor?: boolean;
+    /**
+     * Playable build format (plan §B.6): `'html'` (default) — one self-contained `dist/index.html`;
+     * `'zip'` — `dist/<name>.zip` of the plain build with the assets beside it; `false` leaves
+     * `vite build` alone.
+     */
+    readonly build?: 'html' | 'zip' | false;
+    /**
+     * `build: 'html'` only: ship the bundle gzip'd (`iife`, base64) behind a bootstrap that
+     * inflates it with `DecompressionStream` and injects it as a classic script's text (plan §B.6
+     * item 5). About two thirds off the file; a wash over a gzip channel, +21% over brotli
+     * (CLAUDE.md «Playable export size»). Needs Chrome 80+ / Safari 16.4+ / Firefox 113+.
+     */
+    readonly compress?: boolean;
+    /**
+     * Replace runtime modules nothing in the project mentions with throwing stubs (and `yaml`,
+     * `GLTFLoader`, `postprocessing` when unused). On by default; a dependency that declares
+     * `@pix3/runtime` has its imports parsed (N11), and one the build cannot follow (`import * as`,
+     * a dynamic import) turns strip off with a message. `{ keep: ['GeometryMesh', …] }` names
+     * what such a dependency uses and keeps strip on; `false` strips nothing; `true` strips
+     * regardless of what the dependencies import.
+     */
+    readonly strip?: StripOption;
+    /** The scene a build boots into (`res://`-relative); default `defaultExportScenePath`. */
+    readonly entryScene?: string;
+    /** Answer `/__pix3/*` for non-loopback peers too (a dev server started with `--host`). */
+    readonly allowRemote?: boolean;
+    /**
+     * The image-generation proxy (plan §B.1). `home` replaces `~/.pix3` as the place of
+     * `keys.json` (default `PIX3_HOME`, else `~/.pix3`); `upstreams` replace the providers' API
+     * origins (default `PIX3_PROXY_GEMINI_URL` / `PIX3_PROXY_OPENAI_URL`, else the real ones) — a
+     * local mock in a test.
+     */
+    readonly imageGen?: {
+        readonly home?: string;
+        readonly upstreams?: {
+            readonly gemini?: string;
+            readonly openai?: string;
+        };
+    };
+}
+/** Bare specifier of the player entry a project's `src/main.ts` imports. */
+export declare const PLAYER_SPECIFIER = "@pix3/vite-plugin/player";
+export declare function pix3(options?: Pix3Options): Plugin[];
+export default pix3;

package/dist/index.js

@@ -0,0 +1,290 @@
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizePath, version as viteVersion, } from 'vite';
+import { emitZipAssets, recordModuleSizes, strippedImportError } from "./build/bundle-hooks.js";
+import { devSceneManifestSource } from "./build/dev-manifest.js";
+import { finishBuild } from "./build/finish.js";
+import { libraryStubsPlugin, singleFilePlugins } from "./build/output-plugins.js";
+import { flushEditor, planBuild, runtimeModulePath, shippedBytes, } from "./build/plan.js";
+import { DEV_ID, devSource, EMBEDDED_ASSETS_ID, embeddedAssetsSource, GLTF_LOADER_STUB_ID, gltfLoaderStubSource, NETWORK_ID, networkSource, noEmbeddedAssetsSource, PLAYER_VIRTUAL_IDS, POSTPROCESSING_ID, POSTPROCESSING_STUB_ID, postprocessingSource, postprocessingStubSource, PROJECT_SCRIPTS_ID, projectScriptsSource, SCENE_MANIFEST_ID, sceneManifestSource, SPINE_ID, spineSource, YAML_STUB_ID, yamlStubSource, } from "./build/player-modules.js";
+import { normalizeResRoot } from "./build/project-manifest.js";
+import { buildStrippedModuleSource } from "./build/strippable-runtime-modules.js";
+import { installedVersion, pluginVersion } from "./dev-info.js";
+import { startEditorServer } from "./dev-server.js";
+import { EDITOR_HOST_ID, editorHostSource, SPINE_LOADER_ID } from "./editor-page.js";
+import { fileOf } from "./module-paths.js";
+import { scriptHotUpdate } from "./sync/hot-update.js";
+import { BOT_POLICIES_ID, EDITOR_SCRIPTS_ID, resolvedId, rootModuleSource, ScriptGraph, } from "./sync/script-graph.js";
+import { pix3ViteConfig } from "./vite-config.js";
+/** Bare specifier of the player entry a project's `src/main.ts` imports. */
+export const PLAYER_SPECIFIER = '@pix3/vite-plugin/player';
+const VIRTUAL_IDS = new Set([
+    EDITOR_HOST_ID,
+    EDITOR_SCRIPTS_ID,
+    BOT_POLICIES_ID,
+    SPINE_LOADER_ID,
+    ...PLAYER_VIRTUAL_IDS,
+]);
+/** Directory of this package (`src/` or `dist/` sits under it). */
+const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+const FROM_SOURCE = import.meta.url.endsWith('.ts');
+/** The page client, as source under vitest and as emitted JS from `dist/`. */
+const CLIENT_ENTRY = fileURLToPath(new URL(`./client/index.${FROM_SOURCE ? 'ts' : 'js'}`, import.meta.url));
+/** The player (`player/` beside `src/`; `dist/player/` once built). */
+const PLAYER_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/index.ts' : './player/index.js', import.meta.url));
+/** The player's dev tools, imported by path from `virtual:pix3/dev`: the debug overlay (`/?debug`)… */
+const DEBUG_OVERLAY_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/debug/index.ts' : './player/debug/index.js', import.meta.url));
+/** …and the "Pix3 editor" link on the game. */
+const EDITOR_LINK_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/dev/editor-link.ts' : './player/dev/editor-link.js', import.meta.url));
+export function pix3(options = {}) {
+    const settings = {
+        resRoot: normalizeResRoot(options.resRoot ?? '.'),
+        editor: options.editor ?? true,
+        build: options.build ?? 'html',
+        compress: options.compress ?? false,
+        strip: options.strip,
+        entryScene: options.entryScene ?? null,
+        allowRemote: options.allowRemote ?? false,
+    };
+    let config = null;
+    let server = null;
+    let scripts = null;
+    /** The dev server's editor side, once `configureServer` started it (editor on). */
+    let editor = null;
+    let build = null;
+    const log = (line) => config?.logger.info(`[pix3] ${line}`, { timestamp: true });
+    const warn = (line) => config?.logger.warn(`[pix3] ${line}`, { timestamp: true });
+    const isBuild = () => config?.command === 'build' && settings.build !== false;
+    const root = () => config?.root ?? process.cwd();
+    const baseUrl = () => {
+        const base = config?.base ?? '/';
+        return base.endsWith('/') ? base : `${base}/`;
+    };
+    const outDir = () => {
+        const dir = config?.build.outDir ?? 'dist';
+        return isAbsolute(dir) ? dir : join(root(), dir);
+    };
+    const core = {
+        name: 'pix3',
+        config(user, env) {
+            return pix3ViteConfig({
+                user,
+                packageDir: PACKAGE_DIR,
+                format: env.command === 'build' ? settings.build : false,
+                compress: settings.compress,
+                rolldown: typeof this.meta?.rolldownVersion ===
+                    'string',
+            });
+        },
+        configResolved(resolved) {
+            config = resolved;
+            scripts = new ScriptGraph(resolved.root, () => server, [resolved.cacheDir]);
+        },
+        /** `vite build` only (plan §B.6 items 1–2): flush the editor, then plan what ships. */
+        async buildStart() {
+            if (config?.command !== 'build' || settings.build === false)
+                return;
+            await flushEditor(root(), log, message => this.error(message));
+            const importer = join(root(), 'index.html');
+            build = await planBuild({
+                root: root(),
+                format: settings.build,
+                resRoot: settings.resRoot,
+                entryScene: settings.entryScene,
+                strip: settings.strip,
+                compress: settings.compress,
+                packageDir: PACKAGE_DIR,
+                resolve: async (specifier) => (await this.resolve(specifier, importer))?.id ?? null,
+                parse: code => this.parse(code),
+                log,
+                warn,
+            });
+        },
+        /**
+         * Vite awaits this in `server.close()` — also on an in-process restart (a `vite.config` edit):
+         * every write already accepted finishes before a new server (and a new `ProjectFiles`) starts,
+         * so two instances never write the same project at once.
+         *
+         * In a build it is the last hook: the artifact is final here (`build/finish.ts`).
+         */
+        async closeBundle() {
+            await editor?.files.close();
+            editor = null;
+            if (build && isBuild())
+                finishBuild(build, { root: root(), outDir: outDir(), log, warn });
+        },
+        async configureServer(devServer) {
+            server = devServer;
+            if (!settings.editor || !config || !scripts)
+                return;
+            const projectRoot = config.root;
+            editor = await startEditorServer(devServer, {
+                root: projectRoot,
+                base: baseUrl(),
+                resRoot: settings.resRoot,
+                build: settings.build,
+                allowRemote: settings.allowRemote,
+                imageGen: options.imageGen,
+                versions: {
+                    plugin: pluginVersion(),
+                    runtime: installedVersion(projectRoot, '@pix3/runtime'),
+                    editorCore: installedVersion(projectRoot, '@pix3/editor-core'),
+                    vite: viteVersion,
+                },
+                scripts,
+                log,
+            });
+        },
+        resolveId(id) {
+            if (VIRTUAL_IDS.has(id))
+                return resolvedId(id);
+            // The player ships in this package; resolved here so a workspace link, pnpm or a project
+            // without the package in its own `node_modules` all find the same file.
+            if (id === PLAYER_SPECIFIER)
+                return PLAYER_ENTRY;
+            return null;
+        },
+        async load(id) {
+            if (!id.startsWith('\0')) {
+                // Plan §B.6 item 2: an unmentioned runtime module becomes a stub with the same exports.
+                const modulePath = runtimeModulePath(build, id);
+                if (modulePath === null || !build?.stripped.has(modulePath))
+                    return null;
+                build.applied.modules.add(modulePath);
+                return buildStrippedModuleSource(readFileSync(fileOf(id), 'utf8'), modulePath);
+            }
+            const virtual = id.slice(1);
+            const importer = join(root(), 'index.html');
+            switch (virtual) {
+                case EDITOR_SCRIPTS_ID:
+                case BOT_POLICIES_ID:
+                    return rootModuleSource(virtual, editor?.files.currentSeq ?? 0);
+                case SPINE_LOADER_ID:
+                    // Spine is an optional peer: a literal import() of a package that is not installed
+                    // kills the importing module outright (S1, finding 6), so the loader is decided here.
+                    return (await this.resolve('@esotericsoftware/spine-threejs', importer))
+                        ? `export const loadSpine = () => import('@esotericsoftware/spine-threejs');\n`
+                        : `export const loadSpine = () => Promise.resolve(null);\n`;
+                case EDITOR_HOST_ID: {
+                    const base = baseUrl();
+                    return editorHostSource({
+                        base,
+                        clientUrl: `${base}@fs/${normalizePath(CLIENT_ENTRY).replace(/^\//, '')}`,
+                        editorCore: (await this.resolve('@pix3/editor-core', importer)) !== null,
+                    });
+                }
+                // --- the player's modules (plan §B.5) ---
+                case SCENE_MANIFEST_ID:
+                    return build
+                        ? sceneManifestSource({
+                            scenePaths: build.scan.scenePaths,
+                            entryScenePath: build.scan.entryScenePath,
+                            manifest: build.manifest,
+                            localization: build.scan.localization,
+                            netKindPrefabs: build.scan.netKindPrefabs,
+                            resourceBase: './',
+                        })
+                        : devSceneManifestSource({
+                            root: root(),
+                            resRoot: settings.resRoot,
+                            entryScene: settings.entryScene,
+                            base: baseUrl(),
+                            warn,
+                        });
+                case EMBEDDED_ASSETS_ID: {
+                    if (build?.format !== 'html')
+                        return noEmbeddedAssetsSource();
+                    const current = build;
+                    const embedded = await embeddedAssetsSource({
+                        root: root(),
+                        resRoot: settings.resRoot,
+                        assetPaths: current.scan.assetPaths,
+                        shippedBytes: (resPath, bytes) => shippedBytes(current, resPath, bytes, warn),
+                    });
+                    current.assets = embedded;
+                    log(`embedded ${embedded.count} asset(s), ${(embedded.rawBytes / 1024).toFixed(1)} KiB raw`);
+                    return embedded.source;
+                }
+                case YAML_STUB_ID:
+                    return yamlStubSource();
+                case GLTF_LOADER_STUB_ID:
+                    return gltfLoaderStubSource();
+                case PROJECT_SCRIPTS_ID:
+                    return projectScriptsSource();
+                case SPINE_ID:
+                    if (!build)
+                        return spineSource('dev');
+                    return spineSource(build.scan.usesSpine && build.spineInstalled ? 'static' : 'none');
+                case POSTPROCESSING_ID:
+                    return postprocessingSource(build?.format === 'html' &&
+                        build.scan.usesPostProcessing &&
+                        build.postprocessingInstalled
+                        ? 'static'
+                        : 'default');
+                case POSTPROCESSING_STUB_ID:
+                    return postprocessingStubSource();
+                case NETWORK_ID:
+                    return networkSource(build ? build.scan.usesNetwork : true);
+                case DEV_ID:
+                    return config?.command === 'serve'
+                        ? devSource('dev', {
+                            overlayPath: normalizePath(DEBUG_OVERLAY_ENTRY),
+                            editorLinkPath: normalizePath(EDITOR_LINK_ENTRY),
+                            editorUrl: settings.editor ? `${baseUrl()}__pix3/` : null,
+                        })
+                        : devSource('none');
+                default:
+                    return null;
+            }
+        },
+        /** Every format: the chunks' per-module sizes, for the report; zip: the assets beside it. */
+        generateBundle(_options, bundle) {
+            if (!build || !isBuild())
+                return;
+            recordModuleSizes(build, bundle);
+            if (build.format !== 'zip')
+                return;
+            emitZipAssets(build, {
+                root: root(),
+                resRoot: settings.resRoot,
+                emit: (fileName, source) => this.emitFile({ type: 'asset', fileName, source }),
+                warn,
+            });
+        },
+        transform(code, id, transformOptions) {
+            if (transformOptions?.ssr)
+                return null;
+            if (config?.command === 'serve')
+                return scripts ? scripts.stamp(code, id) : null;
+            if (!build)
+                return null;
+            const error = strippedImportError(build, code, id, {
+                root: root(),
+                packageDir: PACKAGE_DIR,
+                forced: settings.strip === true,
+                parse: source => this.parse(source),
+                warn,
+            });
+            if (error)
+                this.error(error);
+            return null;
+        },
+        async hotUpdate(update) {
+            if (!scripts || !editor)
+                return;
+            return scriptHotUpdate(update, this.environment, { root: root(), scripts, editor });
+        },
+    };
+    if (settings.build === false)
+        return [core];
+    const getBuild = () => build;
+    return [
+        libraryStubsPlugin(getBuild),
+        core,
+        ...(settings.build === 'html'
+            ? singleFilePlugins({ compress: settings.compress, getBuild })
+            : []),
+    ];
+}
+export default pix3;

package/dist/module-paths.d.ts

@@ -0,0 +1,13 @@
+/** A module id without its query (`/a/b.ts?v=1` → `/a/b.ts`). */
+export declare const fileOf: (id: string) => string;
+/** A platform path with `/` separators. */
+export declare const posixPath: (path: string) => string;
+/** `file` relative to `dir`, `/`-separated, when it lies strictly inside `dir`; else null. */
+export declare const relativeInside: (dir: string, file: string) => string | null;
+export declare const isUnder: (file: string, dir: string | null) => boolean;
+/**
+ * The real path of a module id (query dropped; the id itself when it is not a file), cached. The
+ * runtime's `src/` is a real path, and module ids are not always (`resolve.preserveSymlinks`, a
+ * linked workspace): comparing the two as written would silently strip nothing.
+ */
+export declare const realFileOf: (id: string) => string;