Imaginalis engine-opt: parametric camera-visibility cull + world topology + cull perf opt-ins

.github/scripts/bump-versions.mjs

@@ -11,15 +11,15 @@
  * untouched), and prints the new version to stdout (also exported as
  * NEXT_VERSION when running inside GitHub Actions).
  */
-import { readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, writeFileSync, appendFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..", "..");
-const packages = ["core", "polycss", "react", "vue"].map((d) =>
-  resolve(root, "packages", d, "package.json"),
-);
+const packagesRoot = resolve(root, "packages");
+const sourcePackage = resolve(packagesRoot, "core", "package.json");
+const packages = discoverPackageJsons(packagesRoot);
 
 const bump = process.argv[2];
 if (!["patch", "minor", "major"].includes(bump)) {
@@ -29,10 +29,15 @@ if (!["patch", "minor", "major"].includes(bump)) {
 
 const versionRe = /^(\s*"version":\s*")(\d+)\.(\d+)\.(\d+)(")/m;
 
-const first = readFileSync(packages[0], "utf8");
+if (!packages.includes(sourcePackage)) {
+  console.error(`could not find ${sourcePackage}`);
+  process.exit(1);
+}
+
+const first = readFileSync(sourcePackage, "utf8");
 const m = first.match(versionRe);
 if (!m) {
-  console.error(`could not find a "version" field in ${packages[0]}`);
+  console.error(`could not find a "version" field in ${sourcePackage}`);
   process.exit(1);
 }
 const [maj, min, pat] = [Number(m[2]), Number(m[3]), Number(m[4])];
@@ -59,3 +64,11 @@ if (process.env.GITHUB_ENV) {
 if (process.env.GITHUB_OUTPUT) {
   appendFileSync(process.env.GITHUB_OUTPUT, `version=${next}\n`);
 }
+
+function discoverPackageJsons(packagesRoot) {
+  return readdirSync(packagesRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => resolve(packagesRoot, entry.name, "package.json"))
+    .filter((file) => existsSync(file))
+    .sort();
+}

.github/scripts/sync-package-readmes.mjs

@@ -1,5 +1,5 @@
 import { copyFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -11,6 +11,16 @@ const targets = [
   "packages/vue/README.md",
 ];
 
+const invokedFrom = relative(repoRoot, process.cwd());
+const invokedFromPackageReadme = invokedFrom.startsWith("packages/")
+  ? `${invokedFrom}/README.md`
+  : undefined;
+
+if (invokedFromPackageReadme !== undefined && !targets.includes(invokedFromPackageReadme)) {
+  console.log(`[sync-package-readmes] skipped for ${invokedFromPackageReadme}`);
+  process.exit(0);
+}
+
 for (const target of targets) {
   copyFileSync(source, resolve(repoRoot, target));
 }

AGENTS.md

@@ -15,8 +15,9 @@ Monorepo layout (pnpm workspaces):
 | `packages/react` | `@layoutit/polycss-react` | React components + hooks. Owns its own copy of atlas rasterisation. Depends on `core` only — **NOT on `polycss`.** |
 | `packages/vue` | `@layoutit/polycss-vue` | Vue 3 mirror of the React package. Owns its own copy of atlas rasterisation. Depends on `core` only. |
 | `packages/fonts` | `@layoutit/polycss-fonts` | Fonts + text → extruded 3D `Polygon[]`. Hand-written TrueType (`glyf`) reader + extruder (flat/round/bevel profiles) + Google Fonts loader. Framework-agnostic (returns `Polygon[]`, no React/Vue mirror needed). Depends on `core` + `earcut`. |
+| `packages/world` | `@layoutit/polycss-world` | Framework-agnostic topology, BSP/PVS compilation, state, planning, and DOM-apply helpers for authored worlds: regions, links, elements, selectors, resolution, state diffs, layer plans, caller-provided DOM-like records, stable-order apply results, and debug snapshots. Depends on `core` only. |
 | `website` | `@layoutit/polycss-website` | Astro + Starlight docs site. Not published. |
-| `examples/{html,vanilla,react,vue,fontcss}` | private | Per-framework Vite apps demonstrating the minimal usage for each renderer (`fontcss` demos `@layoutit/polycss-fonts`). Workspace members so they resolve to local `workspace:^` packages. Not published. |
+| `examples/{html,vanilla,react,vue,world}` | private | Per-framework Vite apps demonstrating the minimal usage for each renderer, plus `world` for `@layoutit/polycss-world` dogfooding. Workspace members so they resolve to local `workspace:^` packages. Not published. |
 
 Public API is **mirrored** across React and Vue. Adding a hook on one side without adding the matching composable on the other is not acceptable (see "Cross-package discipline" below).
 

README.md

@@ -233,6 +233,8 @@ Each visible polygon is emitted as one leaf element; the renderer chooses the le
 | `@layoutit/polycss` | Vanilla custom elements and imperative `createPolyScene` API. |
 | `@layoutit/polycss-react` | React components, hooks, controls, and core re-exports. |
 | `@layoutit/polycss-vue` | Vue 3 components, composables, controls, and core re-exports. |
+| `@layoutit/polycss-fonts` | Font parsing, Google font loading, and text-to-polygon mesh generation. |
+| `@layoutit/polycss-world` | Framework-agnostic topology, BSP/PVS compilation, state, planning, and DOM-apply helpers for authored PolyCSS worlds. |
 
 ## Made with PolyCSS