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

package/dist/sync/script-graph.js

@@ -0,0 +1,214 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, sep } from 'node:path';
+import { normalizePath } from 'vite';
+import { isExcludedPath } from "../files/scan.js";
+import { relativeInside } from "../module-paths.js";
+/**
+ * The scripts the editor executes, and the proof that it executed the bytes on disk (plan §B.2).
+ *
+ * - `virtual:pix3/editor-scripts` — eager `import.meta.glob` over `scripts/` and `src/scripts/`
+ *   (no specs, tests or declarations), exporting `__pix3Revision`;
+ * - `virtual:pix3/bot-policies` — the same over `design/tests/bots/`;
+ * - every project source module the client environment transforms gets an **executed-content
+ *   stamp**, `(globalThis.__pix3Executed ??= {})[path] = sha`, which runs only when that module
+ *   body runs. S1 showed the root's own hashes prove nothing about nested modules; the stamp does.
+ */
+export const EDITOR_SCRIPTS_ID = 'virtual:pix3/editor-scripts';
+export const BOT_POLICIES_ID = 'virtual:pix3/bot-policies';
+export const ROOT_IDS = [EDITOR_SCRIPTS_ID, BOT_POLICIES_ID];
+export const resolvedId = (id) => `\0${id}`;
+/**
+ * The project-script rule, mirrored from the runtime's `project-script-registration.ts`
+ * (`PROJECT_SCRIPT_DIRECTORIES`, `projectScriptGlobPatterns`, `isProjectScriptEntry`): the
+ * plugin runs in Node and cannot import the runtime's TypeScript sources, so `script-rule.spec.ts`
+ * pins these to the runtime's. A `.ts` under `scripts/` or `src/scripts/` (no specs, tests or
+ * declarations) is an entry — no `.js`, no textual gate.
+ */
+export const SCRIPT_DIRS = ['scripts', 'src/scripts'];
+export const BOT_POLICY_DIRS = ['design/tests/bots'];
+const SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?)$/;
+const NOT_A_SCRIPT = /\.(?:spec|test)\.ts$|\.d\.ts$/;
+/** The glob patterns of a root over `dirs` (= the runtime's `projectScriptGlobPatterns`). */
+export const globPatterns = (dirs) => dirs.flatMap(dir => [
+    `/${dir}/**/*.ts`,
+    `!/${dir}/**/*.spec.ts`,
+    `!/${dir}/**/*.test.ts`,
+    `!/${dir}/**/*.d.ts`,
+]);
+/** Source of a glob root; `revision` is the file table's `seq` when Vite loads it. */
+export const rootModuleSource = (id, revision) => {
+    const dirs = id === BOT_POLICIES_ID ? BOT_POLICY_DIRS : SCRIPT_DIRS;
+    return [
+        `export const __pix3Revision = ${revision};`,
+        `export const modules = import.meta.glob(${JSON.stringify(globPatterns(dirs))}, { eager: true });`,
+        '',
+    ].join('\n');
+};
+/** True for a wire path the editor-scripts or bot-policies glob picks up. */
+export const isGlobbedScript = (wirePath) => wirePath.endsWith('.ts') &&
+    !NOT_A_SCRIPT.test(wirePath) &&
+    [...SCRIPT_DIRS, ...BOT_POLICY_DIRS].some(dir => wirePath.startsWith(`${dir}/`));
+export const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export class ScriptGraph {
+    root;
+    server;
+    /** Absolute directories inside the root that hold no project sources (Vite's `cacheDir`). */
+    ignored;
+    constructor(root, server, ignored = []) {
+        this.root = root;
+        this.server = server;
+        this.ignored = ignored.map(dir => normalizePath(dir).replace(/\/+$/, ''));
+    }
+    /** Module id (absolute path, maybe with a query) → wire path, when it is a project source. */
+    wirePathOf(id) {
+        const file = id.split('?')[0];
+        if (!isAbsolute(file) || !SOURCE_EXTENSION.test(file))
+            return null;
+        // A pre-bundled dependency in an in-project `cacheDir` is not the project's code.
+        if (this.ignored.some(dir => normalizePath(file).startsWith(`${dir}/`)))
+            return null;
+        const wirePath = relativeInside(this.root, file);
+        return wirePath === null || isExcludedPath(wirePath) ? null : wirePath;
+    }
+    absoluteOf(wirePath) {
+        return `${this.root}${sep}${wirePath.split('/').join(sep)}`;
+    }
+    /**
+     * `transform` hook body: append the executed-content stamp to a project source module. The sha
+     * is of the file on disk (what the barrier compares with), not of `code`.
+     */
+    stamp(code, id) {
+        const wirePath = this.wirePathOf(id);
+        if (wirePath === null)
+            return null;
+        let sha;
+        try {
+            sha = sha256Hex(readFileSync(id.split('?')[0]));
+        }
+        catch {
+            return null;
+        }
+        return (`${code}\n;(globalThis.__pix3Executed ??= {})[${JSON.stringify(wirePath)}] = ` +
+            `${JSON.stringify(sha)};\n`);
+    }
+    graph() {
+        return this.server()?.environments.client ?? null;
+    }
+    rootModules() {
+        const env = this.graph();
+        if (!env)
+            return [];
+        const out = [];
+        for (const id of ROOT_IDS) {
+            const mod = env.moduleGraph.getModuleById(resolvedId(id));
+            if (mod)
+                out.push(mod);
+        }
+        return out;
+    }
+    /**
+     * Vite ≥ 5.1 SOFT-invalidates static importers of a changed module: the cached transform is
+     * reused with re-stamped `?t=` and `load()` does not run again, so `__pix3Revision` would stay
+     * stale (S1, finding 1). The roots are hard-invalidated explicitly.
+     *
+     * Twice: as an HMR invalidation (`lastHMRTimestamp`, what the propagation stamps) and as a plain
+     * one, because only `lastInvalidationTimestamp` is what Vite checks a transform against. With
+     * the HMR call alone, a root request already in flight — the tab re-importing after a watcher
+     * `pix3:scripts`, its `load()` done at the old `seq` — is handed to the next request for the same
+     * URL (`transformRequest` dedupes on the URL without `?t=`), and its result is even cached after
+     * the invalidation. The sync's own re-import then executed the previous `__pix3Revision`
+     * (`.plans/scripts-vite.md` S15). Vite's own clock is used, so the invalidation is strictly later
+     * than every request that started before it.
+     */
+    hardInvalidateRoots() {
+        const env = this.graph();
+        if (!env)
+            return;
+        for (const mod of this.rootModules()) {
+            env.moduleGraph.invalidateModule(mod, new Set(), Date.now(), true, false);
+            env.moduleGraph.invalidateModule(mod, new Set(), undefined, false, false);
+        }
+    }
+    /** Client-environment nodes of a file (never Vite 8's mixed nodes — S1, finding 5). */
+    modulesOf(wirePath) {
+        const env = this.graph();
+        if (!env)
+            return [];
+        return [...(env.moduleGraph.getModulesByFile(normalizePath(this.absoluteOf(wirePath))) ?? [])];
+    }
+    /** True when the editor executes `wirePath`: globbed, or imported (transitively) by a root. */
+    isEditorModule(wirePath) {
+        if (isGlobbedScript(wirePath))
+            return true;
+        const roots = new Set(ROOT_IDS.map(resolvedId));
+        const seen = new Set();
+        const queue = this.modulesOf(wirePath);
+        while (queue.length > 0) {
+            const mod = queue.shift();
+            if (seen.has(mod))
+                continue;
+            seen.add(mod);
+            if (mod.id && roots.has(mod.id))
+                return true;
+            for (const importer of mod.importers)
+                queue.push(importer);
+        }
+        return false;
+    }
+    /**
+     * Project modules only the bot policies reach (`.plans/scripts-vite.md` S4/S11): reachable from
+     * `virtual:pix3/bot-policies` and not from `virtual:pix3/editor-scripts`, so the game the editor
+     * plays never runs them and a change to one need not wait for play to stop. Read from the client
+     * graph as it is now (after the barrier's propagation); a module the graph has not seen is not
+     * listed, which errs on the side of holding play.
+     */
+    policyOnlyModules() {
+        const env = this.graph();
+        if (!env)
+            return [];
+        const reach = (rootId) => {
+            const out = new Set();
+            const root = env.moduleGraph.getModuleById(resolvedId(rootId));
+            if (!root)
+                return out;
+            const seen = new Set([root]);
+            const queue = [...root.importedModules];
+            while (queue.length > 0) {
+                const mod = queue.shift();
+                if (seen.has(mod))
+                    continue;
+                seen.add(mod);
+                const wirePath = mod.file ? this.wirePathOf(mod.file) : null;
+                if (wirePath !== null)
+                    out.add(wirePath);
+                for (const imported of mod.importedModules)
+                    queue.push(imported);
+            }
+            return out;
+        };
+        // No editor root in the graph yet: nothing can be proven policy-only.
+        if (!env.moduleGraph.getModuleById(resolvedId(EDITOR_SCRIPTS_ID)))
+            return [];
+        const game = reach(EDITOR_SCRIPTS_ID);
+        return [...reach(BOT_POLICIES_ID)].filter(path => !game.has(path)).sort();
+    }
+    /** HMR-propagate one file through the client graph (stamps `lastHMRTimestamp` up the chain). */
+    async reload(wirePath) {
+        const env = this.graph();
+        if (!env)
+            return 0;
+        const mods = this.modulesOf(wirePath);
+        for (const mod of mods)
+            await env.reloadModule(mod);
+        return mods.length;
+    }
+    /** Re-run the roots' globs (a script was added or removed). */
+    async reloadRoots() {
+        const env = this.graph();
+        if (!env)
+            return;
+        for (const mod of this.rootModules())
+            await env.reloadModule(mod);
+    }
+}

package/dist/vite-config.d.ts

@@ -0,0 +1,12 @@
+import { type UserConfig } from 'vite';
+/** The plugin's `config` hook: what it adds to the user's Vite config. */
+export declare const pix3ViteConfig: (options: {
+    readonly user: UserConfig;
+    /** This package's directory (the page client and the player are served from it). */
+    readonly packageDir: string;
+    /** The playable build this command makes, or false (dev, `build: false`). */
+    readonly format: "html" | "zip" | false;
+    readonly compress: boolean;
+    /** Vite 8 bundles with rolldown (`this.meta.rolldownVersion`), Vite 7 with rollup. */
+    readonly rolldown: boolean;
+}) => UserConfig;

package/dist/vite-config.js

@@ -0,0 +1,65 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { searchForWorkspaceRoot } from 'vite';
+import { findPackageDir } from "./dev-info.js";
+/** `dist/optimize-deps.json` of the installed editor, or nothing. */
+const editorOptimizeDeps = (editorCoreDir) => {
+    if (!editorCoreDir)
+        return [];
+    try {
+        const list = JSON.parse(readFileSync(join(editorCoreDir, 'dist', 'optimize-deps.json'), 'utf8'));
+        return Array.isArray(list) ? list.filter((id) => typeof id === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+};
+/** The plugin's `config` hook: what it adds to the user's Vite config. */
+export const pix3ViteConfig = (options) => {
+    const { user, format } = options;
+    const projectRoot = resolve(user.root ?? process.cwd());
+    const linkedEditorCore = findPackageDir(projectRoot, '@pix3/editor-core');
+    // Vite checks `fs.allow` against real paths (`.native`: long names on Windows, as Vite resolves
+    // them); a workspace or pnpm link points elsewhere.
+    const editorCoreDir = linkedEditorCore ? realpathSync.native(linkedEditorCore) : null;
+    // An explicit `fs.allow` switches off Vite's workspace-root default; keep it when the user
+    // set none, and add this package (the page client and the player are served from it by
+    // `/@fs/`) and the prebuilt editor (served from wherever npm put it: hoisted, pnpm, a
+    // workspace link).
+    const own = [options.packageDir, ...(editorCoreDir ? [editorCoreDir] : [])];
+    const allow = user.server?.fs?.allow ? own : [searchForWorkspaceRoot(projectRoot), ...own];
+    // rolldown's output option is `codeSplitting`; rollup spells the same `inlineDynamicImports`.
+    const singleChunk = options.rolldown ? { codeSplitting: false } : { inlineDynamicImports: true };
+    // A compressed build is injected as script text: `iife`, so it declares nothing global.
+    const outputFormat = options.compress && format === 'html' ? { format: 'iife' } : {};
+    return {
+        resolve: { dedupe: ['three', '@pix3/runtime'] },
+        optimizeDeps: {
+            // One runtime and one three for the game and the editor (plan §B.2, S1), plus the bare
+            // subpaths the prebuilt editor imports (`dist/optimize-deps.json`).
+            include: ['@pix3/runtime', 'three', ...editorOptimizeDeps(editorCoreDir)],
+            // The installed player imports virtual modules resolved by this plugin's Vite hooks;
+            // the dependency optimizer cannot resolve them while prebundling node_modules.
+            exclude: ['@pix3/editor-core', '@pix3/vite-plugin/player'],
+        },
+        server: { fs: { allow } },
+        ...(format
+            ? {
+                // Relative URLs: the artifact runs from `file://`, a subfolder or a sandboxed frame.
+                base: './',
+                build: format === 'html'
+                    ? {
+                        // Everything inlined (the single-file plugin's recommended config, set here
+                        // so the chunking flag follows the bundler, not Vite's version string).
+                        assetsInlineLimit: () => true,
+                        chunkSizeWarningLimit: 100_000_000,
+                        cssCodeSplit: false,
+                        assetsDir: '',
+                        modulePreload: false,
+                        rollupOptions: { output: { ...singleChunk, ...outputFormat } },
+                    }
+                    : {},
+            }
+            : {}),
+    };
+};

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@pix3/vite-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.1",
+  "description": "Pix3 editor, file API, sync barrier and build as a Vite plugin.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pix3dev/pix3-core.git",
+    "directory": "packages/vite-plugin"
+  },
+  "homepage": "https://github.com/pix3dev/pix3-core/tree/main/packages/vite-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/pix3dev/pix3-core/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./player": {
+      "types": "./dist/player/index.d.ts",
+      "import": "./dist/player/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p player/tsconfig.build.json",
+    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && npm run build",
+    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p player/tsconfig.json"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "vite-plugin-singlefile": "^2.3.3",
+    "ws": "^8.18.0",
+    "yaml": "^2.6.0"
+  },
+  "peerDependencies": {
+    "@pix3/runtime": "2.0.0-alpha.1",
+    "vite": "^7 || ^8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.8.3",
+    "vite": "^8.3.3"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}