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

package/dist/build/project-manifest.js

@@ -0,0 +1,169 @@
+import { readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+/**
+ * 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 const PROJECT_MANIFEST_FILE = 'pix3project.yaml';
+const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
+const MIN_VIEWPORT = 64;
+const MIN_PIXEL_RATIO = 1;
+const MAX_PIXEL_RATIO = 4;
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const qualityFor = (platform) => {
+    switch (platform) {
+        case 'mobile':
+            return { antialias: false, shadows: false, maxPixelRatio: 2 };
+        case 'desktop':
+            return { antialias: true, shadows: true, maxPixelRatio: 3 };
+        default:
+            return { antialias: true, shadows: true, maxPixelRatio: 2 };
+    }
+};
+const normalizeQuality = (input, platform) => {
+    const defaults = qualityFor(platform);
+    if (!isRecord(input))
+        return defaults;
+    const rawRatio = Number(input.maxPixelRatio);
+    return {
+        antialias: typeof input.antialias === 'boolean' ? input.antialias : defaults.antialias,
+        shadows: typeof input.shadows === 'boolean' ? input.shadows : defaults.shadows,
+        maxPixelRatio: Number.isFinite(rawRatio)
+            ? Math.min(MAX_PIXEL_RATIO, Math.max(MIN_PIXEL_RATIO, rawRatio))
+            : defaults.maxPixelRatio,
+    };
+};
+const normalizeViewport = (input) => {
+    const record = isRecord(input) ? input : {};
+    const width = Number(record.width);
+    const height = Number(record.height);
+    return {
+        width: Math.max(MIN_VIEWPORT, Number.isFinite(width) ? Math.round(width) : DEFAULT_VIEWPORT.width),
+        height: Math.max(MIN_VIEWPORT, Number.isFinite(height) ? Math.round(height) : DEFAULT_VIEWPORT.height),
+    };
+};
+const normalizeFonts = (input) => {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of input) {
+        if (!isRecord(entry))
+            continue;
+        const family = typeof entry.family === 'string' ? entry.family.trim() : '';
+        const path = typeof entry.path === 'string' ? stripRes(entry.path.trim()) : '';
+        if (!family || !path)
+            continue;
+        const weight = typeof entry.weight === 'number' || typeof entry.weight === 'string' ? entry.weight : 400;
+        const style = entry.style === 'italic' ? 'italic' : 'normal';
+        const key = `${family}|${weight}|${style}|${path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const unicodeRange = typeof entry.unicodeRange === 'string' && entry.unicodeRange.trim()
+            ? entry.unicodeRange.trim()
+            : undefined;
+        out.push({ family, path, weight, style, ...(unicodeRange ? { unicodeRange } : {}) });
+    }
+    return out;
+};
+const normalizeLocalization = (input) => {
+    if (!isRecord(input))
+        return null;
+    const locales = Array.isArray(input.locales)
+        ? [...new Set(input.locales.filter((l) => typeof l === 'string' && l.length > 0))]
+        : [];
+    const declaredDefault = typeof input.defaultLocale === 'string' && input.defaultLocale.length > 0
+        ? input.defaultLocale
+        : (locales[0] ?? '');
+    if (!declaredDefault)
+        return null;
+    const finalLocales = locales.includes(declaredDefault) ? locales : [declaredDefault, ...locales];
+    const fallbackLocale = typeof input.fallbackLocale === 'string' && input.fallbackLocale.length > 0
+        ? input.fallbackLocale
+        : undefined;
+    return {
+        defaultLocale: declaredDefault,
+        ...(fallbackLocale ? { fallbackLocale } : {}),
+        locales: finalLocales,
+    };
+};
+/**
+ * Same rule as the runtime's `normalizeAutoloads` (this side of the plugin does not import the
+ * runtime): entries need a `singleton` and a `scriptPath`, `enabled` defaults to true, a repeated
+ * singleton keeps its first entry.
+ */
+const normalizeAutoloads = (input) => {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of input) {
+        if (!isRecord(entry))
+            continue;
+        const scriptPath = typeof entry.scriptPath === 'string' ? entry.scriptPath.trim() : '';
+        const singleton = typeof entry.singleton === 'string' ? entry.singleton.trim() : '';
+        if (!scriptPath || !singleton || seen.has(singleton))
+            continue;
+        seen.add(singleton);
+        out.push({ singleton, scriptPath, enabled: entry.enabled !== false });
+    }
+    return out;
+};
+/** `res://x`, `./x`, `/x` → `x`. */
+export const stripRes = (path) => path
+    .replace(/\\/g, '/')
+    .replace(/^res:\/\//i, '')
+    .replace(/^\.\/+/, '')
+    .replace(/^\/+/, '');
+/** `pix3({ resRoot })` as the build and the server use it: no scheme, no trailing `/`, `'.'` for the root. */
+export const normalizeResRoot = (resRoot) => stripRes(resRoot).replace(/\/+$/, '') || '.';
+/** A project wire path → its `res://`-relative path, or null outside `resRoot`. */
+export const wireToRes = (wirePath, resRoot) => {
+    if (resRoot === '.')
+        return wirePath;
+    return wirePath.startsWith(`${resRoot}/`) ? wirePath.slice(resRoot.length + 1) : null;
+};
+/** The absolute file of a `res://`-relative path. */
+export const resToAbsolute = (root, resRoot, resPath) => join(root, resRoot, ...resPath.split('/'));
+/** Parse the manifest text (an empty or malformed manifest yields the defaults). */
+export const parseProjectManifest = (text, fallbackName) => {
+    let parsed = null;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch {
+        parsed = null;
+    }
+    const record = isRecord(parsed) ? parsed : {};
+    const metadata = isRecord(record.metadata) ? record.metadata : {};
+    const platform = typeof record.targetPlatform === 'string' ? record.targetPlatform : 'universal';
+    const defaultScene = typeof record.defaultExportScenePath === 'string' && record.defaultExportScenePath.trim()
+        ? stripRes(record.defaultExportScenePath.trim())
+        : null;
+    return {
+        projectName: typeof metadata.projectName === 'string' && metadata.projectName.trim()
+            ? metadata.projectName.trim()
+            : fallbackName,
+        defaultScenePath: defaultScene,
+        viewportBaseSize: normalizeViewport(record.viewportBaseSize),
+        quality: normalizeQuality(record.quality, platform.toLowerCase()),
+        fonts: normalizeFonts(record.fonts),
+        localization: normalizeLocalization(record.localization),
+        autoloads: normalizeAutoloads(record.autoloads),
+    };
+};
+/** The manifest of the project at `root` (defaults when there is none). */
+export const readProjectManifest = (root) => {
+    let text = '';
+    try {
+        text = readFileSync(join(root, PROJECT_MANIFEST_FILE), 'utf8');
+    }
+    catch {
+        text = '';
+    }
+    return parseProjectManifest(text, basename(root));
+};

package/dist/build/record.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `.pix3/build.json` — what the last `vite build` produced. Written by the plugin at the end of a
+ * build, so whoever ran `npm run build` (the coding agent, a script, CI) gets the artifact's path,
+ * size and hash without parsing Vite's output.
+ */
+export interface BuildRecord {
+    readonly format: 'html' | 'zip';
+    /** Absolute path of the artifact (`dist/index.html` or `dist/<name>.zip`). */
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly at: string;
+    readonly entryScene: string;
+    readonly assets: number;
+    readonly stripped: readonly string[];
+    readonly warnings: readonly string[];
+    /** Absolute path of `dist/<name>.report.json` (sizes by group, stubs, assets, compression). */
+    readonly report?: string;
+}
+export declare const buildRecordPath: (root: string) => string;
+export declare const writeBuildRecord: (root: string, record: BuildRecord) => void;
+export declare const fileDigest: (path: string) => {
+    bytes: number;
+    sha256: string;
+};

package/dist/build/record.js

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { RESERVED_ROOT_DIR } from "../files/paths.js";
+export const buildRecordPath = (root) => join(root, RESERVED_ROOT_DIR, 'build.json');
+export const writeBuildRecord = (root, record) => {
+    const path = buildRecordPath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`);
+};
+export const fileDigest = (path) => ({
+    bytes: statSync(path).size,
+    sha256: createHash('sha256').update(readFileSync(path)).digest('hex'),
+});

package/dist/build/report.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `dist/<name>.report.json` (plan §B.6 item 5): why the artifact weighs what it does, written
+ * beside it so whoever ran `npm run build` (the coding agent first of all) can answer "why is it
+ * this big" without rebuilding — CLAUDE.md «Playable export size» is the prose, this is the
+ * numbers for one build.
+ *
+ * Module sizes come from the bundler's per-chunk `modules` map (`renderedLength`: the module's
+ * code after tree-shaking, **before minification**), grouped by where the id lives: `three`,
+ * `runtime` (`@pix3/runtime`'s `src/`), `player` (this package's player and the generated
+ * `virtual:pix3/*` modules), `project` (the project's own sources), `assets` (the embedded-asset
+ * module) and `dependencies` (every other `node_modules` package, listed by name). Each group also
+ * carries an estimate of its share of the final minified bundle (its rendered share scaled to the
+ * bundle's size), which is the number to quote.
+ */
+export type ModuleGroup = 'three' | 'runtime' | 'player' | 'project' | 'assets' | 'dependencies' | 'other';
+export interface ModuleSize {
+    readonly id: string;
+    readonly group: ModuleGroup;
+    /** Package name for `dependencies` and `three`, null otherwise. */
+    readonly package: string | null;
+    readonly renderedBytes: number;
+}
+export interface GroupSize {
+    readonly modules: number;
+    readonly renderedBytes: number;
+    /** Rendered share of the chunk, scaled to the final (minified) bundle bytes. */
+    readonly estimatedMinifiedBytes: number;
+    readonly share: number;
+}
+export interface AssetSizeEntry {
+    readonly path: string;
+    readonly rawBytes: number;
+    readonly base64Bytes: number;
+}
+export interface BuildReport {
+    readonly format: 'html' | 'zip';
+    readonly path: string;
+    readonly at: string;
+    readonly entryScene: string;
+    readonly scenes: number;
+    /** The artifact on disk. */
+    readonly bytes: number;
+    /** What a gzip channel would transfer for the artifact (zlib level 6). */
+    readonly gzipBytes: number;
+    readonly compress: {
+        readonly enabled: true;
+        readonly bundleBytes: number;
+        readonly gzipBytes: number;
+        readonly base64Bytes: number;
+        /** `gzipBytes / bundleBytes`. */
+        readonly ratio: number;
+        /** `bundleBytes - base64Bytes`: what the file lost (the bootstrap is ~1.5 KiB). */
+        readonly savedBytes: number;
+    } | {
+        readonly enabled: false;
+    };
+    readonly code: {
+        /** Final JS bytes of every chunk (minified). */
+        readonly bundleBytes: number;
+        /** Sum of the modules' rendered lengths (before minification). */
+        readonly renderedBytes: number;
+        readonly groups: Record<ModuleGroup, GroupSize>;
+        /** `node_modules` packages by rendered bytes (three included), largest first. */
+        readonly packages: Record<string, number>;
+        readonly largestModules: readonly ModuleSize[];
+    };
+    readonly strip: {
+        readonly enabled: boolean;
+        readonly reason: string | null;
+        readonly keep: readonly string[];
+        /** Runtime modules replaced by stubs (paths under `@pix3/runtime/src`). */
+        readonly stripped: readonly string[];
+        /** `package → files parsed` for the dependencies that declare the runtime (N11). */
+        readonly dependencies: Record<string, number>;
+        /** Names a dependency imports from the runtime barrel (kept by that). */
+        readonly dependencyImports: readonly string[];
+    };
+    /** The optional libraries and how each one was resolved. */
+    readonly libraries: Record<string, string>;
+    readonly assets: {
+        readonly count: number;
+        readonly rawBytes: number;
+        readonly base64Bytes: number;
+        /** Largest first. */
+        readonly entries: readonly AssetSizeEntry[];
+    };
+    readonly warnings: readonly string[];
+}
+export interface ModuleClassifier {
+    readonly root: string;
+    readonly runtimeSrc: string | null;
+    readonly playerDir: string;
+    readonly embeddedAssetsId: string;
+}
+/** The package name of a `node_modules` id (`@scope/name` or `name`), or null. */
+export declare const packageNameOf: (id: string) => string | null;
+export declare const classifyModule: (id: string, classifier: ModuleClassifier) => {
+    group: ModuleGroup;
+    package: string | null;
+};
+/**
+ * A readable id: `@pix3/runtime/src/…` for the runtime, `<package>/…` inside `node_modules`,
+ * relative to the root for the project's own files.
+ */
+export declare const displayId: (id: string, classifier: ModuleClassifier) => string;
+export interface CodeSizes {
+    readonly bundleBytes: number;
+    readonly modules: readonly ModuleSize[];
+}
+export declare const summarizeCode: (sizes: CodeSizes, largest?: number) => BuildReport["code"];
+export declare const gzipBytesOf: (bytes: Buffer) => number;
+/** `<outDir>/<artifact basename without extension>.report.json`. */
+export declare const buildReportPath: (artifactPath: string, outDir: string) => string;
+export declare const writeBuildReport: (path: string, report: BuildReport) => void;

package/dist/build/report.js

@@ -0,0 +1,102 @@
+import { writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { fileOf, isUnder, posixPath, relativeInside } from "../module-paths.js";
+/** The package name of a `node_modules` id (`@scope/name` or `name`), or null. */
+export const packageNameOf = (id) => {
+    const normalized = posixPath(id);
+    const marker = normalized.lastIndexOf('/node_modules/');
+    if (marker < 0)
+        return null;
+    const parts = normalized.slice(marker + '/node_modules/'.length).split('/');
+    if (parts[0]?.startsWith('@'))
+        return parts.length > 1 ? `${parts[0]}/${parts[1]}` : null;
+    return parts[0] || null;
+};
+export const classifyModule = (id, classifier) => {
+    if (id.startsWith('\0')) {
+        const virtual = id.slice(1);
+        if (virtual === classifier.embeddedAssetsId)
+            return { group: 'assets', package: null };
+        if (virtual.startsWith('virtual:pix3/'))
+            return { group: 'player', package: null };
+        return { group: 'other', package: null };
+    }
+    const file = fileOf(id);
+    if (isUnder(file, classifier.runtimeSrc))
+        return { group: 'runtime', package: null };
+    if (isUnder(file, classifier.playerDir))
+        return { group: 'player', package: null };
+    const pkg = packageNameOf(file);
+    if (pkg === 'three')
+        return { group: 'three', package: pkg };
+    if (pkg)
+        return { group: 'dependencies', package: pkg };
+    if (isUnder(file, classifier.root))
+        return { group: 'project', package: null };
+    return { group: 'other', package: null };
+};
+/**
+ * A readable id: `@pix3/runtime/src/…` for the runtime, `<package>/…` inside `node_modules`,
+ * relative to the root for the project's own files.
+ */
+export const displayId = (id, classifier) => {
+    if (id.startsWith('\0'))
+        return id.slice(1);
+    const file = fileOf(id);
+    const inRuntime = classifier.runtimeSrc && relativeInside(classifier.runtimeSrc, file);
+    if (inRuntime)
+        return `@pix3/runtime/src/${inRuntime}`;
+    const posix = posixPath(file);
+    const marker = posix.lastIndexOf('/node_modules/');
+    if (marker >= 0)
+        return posix.slice(marker + '/node_modules/'.length);
+    return relativeInside(classifier.root, file) ?? posix;
+};
+const GROUPS = [
+    'three',
+    'runtime',
+    'player',
+    'project',
+    'assets',
+    'dependencies',
+    'other',
+];
+export const summarizeCode = (sizes, largest = 30) => {
+    const renderedBytes = sizes.modules.reduce((sum, m) => sum + m.renderedBytes, 0);
+    const groups = {};
+    for (const group of GROUPS) {
+        const members = sizes.modules.filter(m => m.group === group);
+        const rendered = members.reduce((sum, m) => sum + m.renderedBytes, 0);
+        const share = renderedBytes > 0 ? rendered / renderedBytes : 0;
+        groups[group] = {
+            modules: members.length,
+            renderedBytes: rendered,
+            estimatedMinifiedBytes: Math.round(share * sizes.bundleBytes),
+            share: Math.round(share * 1000) / 1000,
+        };
+    }
+    const packages = {};
+    for (const m of sizes.modules) {
+        if (m.package && m.renderedBytes > 0) {
+            packages[m.package] = (packages[m.package] ?? 0) + m.renderedBytes;
+        }
+    }
+    const sortedPackages = Object.fromEntries(Object.entries(packages).sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)));
+    const largestModules = [...sizes.modules]
+        .sort((a, b) => b.renderedBytes - a.renderedBytes || (a.id < b.id ? -1 : 1))
+        .slice(0, largest);
+    return {
+        bundleBytes: sizes.bundleBytes,
+        renderedBytes,
+        groups,
+        packages: sortedPackages,
+        largestModules,
+    };
+};
+export const gzipBytesOf = (bytes) => gzipSync(bytes, { level: 6 }).byteLength;
+/** `<outDir>/<artifact basename without extension>.report.json`. */
+export const buildReportPath = (artifactPath, outDir) => join(outDir, `${basename(artifactPath, extname(artifactPath))}.report.json`);
+export const writeBuildReport = (path, report) => {
+    writeFileSync(path, `${JSON.stringify(report, null, 2)}\n`);
+};

package/dist/build/scan.d.ts

@@ -0,0 +1,84 @@
+import type { LocalizationSettings, ProjectManifestInfo } from './project-manifest.ts';
+/**
+ * The build's scan of the project (plan §B.6 item 1): every text source outside `node_modules`,
+ * `dist`, `.pix3`, … is read once, and from that one pass come
+ *
+ * - `mentionedNames` — every identifier-like token (plus `core:Follow`-shaped ids), the superset
+ *   the strip asks "does anything mention this module?" (a false positive costs kilobytes, a
+ *   false negative would ship a broken game — `../pix3/.plans/done/playable-export-size.md` §2 Р4);
+ * - the asset set: every scene and prefab, everything they and the scripts name by `res://`,
+ *   directories those references expand to, Spine atlas pages, the declared locale tables and
+ *   their sprites, the project's fonts (no pre-packed atlas: nothing in 2.x writes one);
+ * - whether Spine, `postprocessing` or the multiplayer stack are used at all.
+ *
+ * Node port of 1.x `ProjectBuildService.collectAssetPaths` / `scanMentionedNames`, widened to
+ * `src/**` and every other text source as the plan asks (DeepCore imports runtime nodes from
+ * `src/`). Scene paths are `res://`-relative (under `resRoot`); the scan reports them without the
+ * scheme.
+ */
+export interface ScanOptions {
+    readonly root: string;
+    /** Where `res://` points, relative to the root (`'.'` by default). */
+    readonly resRoot: string;
+    readonly manifest: ProjectManifestInfo;
+    /** `pix3({ entryScene })`: a `res://`-relative scene path. */
+    readonly entryScene?: string | null;
+    /**
+     * What the dependencies that declare the runtime mention and import (`scanDependencyImports`):
+     * they count for the `uses*` answers as the project's own sources do.
+     */
+    readonly dependencies?: SourceMentions;
+}
+/** Identifiers and bare import specifiers found in a set of sources. */
+export interface SourceMentions {
+    readonly mentionedNames: ReadonlySet<string>;
+    /** `from 'x'`, `import('x')`, `import 'x'`, `require('x')` in code sources. */
+    readonly importedSpecifiers: ReadonlySet<string>;
+}
+export interface ProjectScan {
+    /** Navigable scenes (`res://`-relative, sorted): every `.pix3scene` that is not a prefab. */
+    readonly scenePaths: readonly string[];
+    /** The scene the player boots into; `''` when the project has no scene. */
+    readonly entryScenePath: string;
+    /** Every shipped file, `res://`-relative and sorted (scenes and prefabs included). */
+    readonly assetPaths: readonly string[];
+    readonly mentionedNames: ReadonlySet<string>;
+    /** Module specifiers the project's code sources import (see {@link SourceMentions}). */
+    readonly importedSpecifiers: ReadonlySet<string>;
+    readonly usesSpine: boolean;
+    readonly usesPostProcessing: boolean;
+    readonly usesNetwork: boolean;
+    /** The effective localization config (manifest block, else discovered `locales/`). */
+    readonly localization: LocalizationSettings | null;
+    /** Prefab paths for the multiplayer kind table, sorted by code point. */
+    readonly netKindPrefabs: readonly string[];
+    readonly warnings: readonly string[];
+    /** How many text sources were read (for the build log). */
+    readonly textSourceCount: number;
+}
+/** Every identifier-like token of a text (the strip's mention superset) into `names`. */
+export declare const collectMentionedNames: (text: string, names: Set<string>) => void;
+/** Every module specifier a code text imports, statically or not, into `specifiers`. */
+export declare const collectImportedSpecifiers: (text: string, specifiers: Set<string>) => void;
+/** Names that mean "this project talks to the multiplayer stack". */
+export declare const NETWORK_MENTION_NAMES: readonly ["network", "netNodes", "Network", "NetworkService", "NetworkedNode", "ReplicatedTransform", "NetworkedNodeBehavior", "ReplicatedTransformBehavior", "core:NetworkedNode", "core:ReplicatedTransform"];
+/**
+ * A `.pix3scene` that is instantiated rather than navigated to: `prefabs/`, `.prefab`, and
+ * `scenes/ui/` overlays (the conventions of the 1.x exporter and `pix3 smoke`).
+ */
+export declare const isPrefabPath: (path: string) => boolean;
+/** A scene the player can boot into or `changeScene` to: a `.pix3scene` that is not a prefab. */
+export declare const isPlayableScenePath: (path: string) => boolean;
+/** Page image names declared inside an `.atlas` file (port of `parseSpineAtlasPageNames`). */
+export declare const parseSpineAtlasPageNames: (atlasText: string) => string[];
+/** Every file under `root` as a wire path, excluding tooling, build output and `.pix3/`. */
+export declare const listProjectFiles: (root: string) => Promise<string[]>;
+export declare const scanProject: (options: ScanOptions) => Promise<ProjectScan>;
+/** Zero-config localization: `locales/*.json` → `en` if present, else the first (editor rule). */
+export declare const discoverLocalization: (resFiles: ReadonlySet<string>) => LocalizationSettings | null;
+/**
+ * The scene the player boots into, the same in dev and in a build: `pix3({ entryScene })`, else
+ * `pix3project.yaml` `defaultExportScenePath`, else `scenes/main.pix3scene`, else the first scene.
+ * A named scene that is not one of `scenePaths` is skipped with a warning.
+ */
+export declare const resolveEntryScene: (scenePaths: readonly string[], manifest: ProjectManifestInfo, requested: string | null | undefined, warnings: string[]) => string;