Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

fix: finish the CommonJS removal the r186 bump started (#81)

Matthew Kissinger93eba299d932
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85a09e37..f07b22a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,27 @@
Changes to `@kiln/engine`. Source and installable packages are distributed through
GitHub. The package is not published on the npm registry.
+## Finishing the CommonJS removal the r186 bump started — 2026-09-12
+
+- The previous entry's fix was incomplete, and looked complete.
+ `src/ops.ts` moved to the ESM build, but `src/__tests__/subdivide-normals.test.ts`
+ still imported the bare specifier — so the CommonJS build kept loading and kept
+ emitting `THREE_CJS_DEPRECATED`, while the production import read as corrected.
+ The whole suite now reports **zero** occurrences of that warning.
+- `three-subdivide` is pinned **exactly** rather than by caret. The deep path
+ `three-subdivide/build/index.module.js` is legal precisely because the package
+ declares no `exports` map; a minor release that added one would make the path
+ unresolvable, and a caret range would have taken that release silently.
+- `src/__tests__/three-subdivide-esm.test.ts` guards the whole tree rather than one
+ file, which is the lesson from the partial fix: it walks every `.ts` under `src/`,
+ asserts the ESM build has no `require(` call, and asserts the pin is exact.
+ Verified by injecting the bare specifier into `src/ops.ts` and confirming the guard
+ fails *and names the offending file*, rather than by observing a pass.
+- Timing, since it reads as urgent and is not: three deprecated the CommonJS build in
+ r186 and has not announced a removal release. Its own precedent — `build/three.js`
+ deprecated at r150, removed at r160 — suggests roughly ten releases of runway. The
+ reason to fix it now is the warning users see today, not the removal.
+
## three.js r186, and the CommonJS load it exposed — 2026-09-11
- `three` and `@types/three` to 0.186.0 in both the engine and `render-service`.
diff --git a/bun.lock b/bun.lock
index c876a490..1a6ed12e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -18,7 +18,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2",
},
diff --git a/dist/build.json b/dist/build.json
index 5c2c4fe1..0cc37840 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,11 +2,11 @@
"schemaVersion": 1,
"entries": {
"mcp": {
- "identity": "sha256:3dce05fe9f707ffb931dc9dca46b8e4020fdd1eb4a292c8a919fe3715de0b3ec",
+ "identity": "sha256:e53c0753be29db98a9df2495ef6f67d106ed39cc36f792a254d9b50029420bf5",
"engineVersion": "0.6.0",
"toolchain": "[email protected]",
"sourceHash": "e78c388ec8e3eb3b197a458d3219254e739a85669c0e869aa34ebd296129b8a0",
- "dependencyHash": "3f2fcf55da59ef80ea5d8ac0e258f5517e1b084c1608a78e7d534aa25bcba611",
+ "dependencyHash": "c6746ae661afc9576bbfaa323ee13af6531644626dc5baeed8d49a06773922d2",
"dependencies": {
"@gltf-transform/core": "4.5.0",
"@gltf-transform/extensions": "4.5.0",
@@ -21,7 +21,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
@@ -30,11 +30,11 @@
"bundleHash": "sha256:bb502af9a18150fe0d204c5acc8318b689e322f903bb37af5484b793f69fdc2b"
},
"cli": {
- "identity": "sha256:3dce05fe9f707ffb931dc9dca46b8e4020fdd1eb4a292c8a919fe3715de0b3ec",
+ "identity": "sha256:e53c0753be29db98a9df2495ef6f67d106ed39cc36f792a254d9b50029420bf5",
"engineVersion": "0.6.0",
"toolchain": "[email protected]",
"sourceHash": "e78c388ec8e3eb3b197a458d3219254e739a85669c0e869aa34ebd296129b8a0",
- "dependencyHash": "3f2fcf55da59ef80ea5d8ac0e258f5517e1b084c1608a78e7d534aa25bcba611",
+ "dependencyHash": "c6746ae661afc9576bbfaa323ee13af6531644626dc5baeed8d49a06773922d2",
"dependencies": {
"@gltf-transform/core": "4.5.0",
"@gltf-transform/extensions": "4.5.0",
@@ -49,7 +49,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
@@ -58,11 +58,11 @@
"bundleHash": "sha256:50befd6901deeed13a85257a9f5839cd80416aad4c8c512c1dbc9fdd7d68c73a"
},
"worker": {
- "identity": "sha256:3dce05fe9f707ffb931dc9dca46b8e4020fdd1eb4a292c8a919fe3715de0b3ec",
+ "identity": "sha256:e53c0753be29db98a9df2495ef6f67d106ed39cc36f792a254d9b50029420bf5",
"engineVersion": "0.6.0",
"toolchain": "[email protected]",
"sourceHash": "e78c388ec8e3eb3b197a458d3219254e739a85669c0e869aa34ebd296129b8a0",
- "dependencyHash": "3f2fcf55da59ef80ea5d8ac0e258f5517e1b084c1608a78e7d534aa25bcba611",
+ "dependencyHash": "c6746ae661afc9576bbfaa323ee13af6531644626dc5baeed8d49a06773922d2",
"dependencies": {
"@gltf-transform/core": "4.5.0",
"@gltf-transform/extensions": "4.5.0",
@@ -77,7 +77,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
@@ -86,11 +86,11 @@
"bundleHash": "sha256:f2ec9893425aad50bb2717d0a4a3889c118421b211dda0062b7299812593d92c"
},
"agent-run": {
- "identity": "sha256:3dce05fe9f707ffb931dc9dca46b8e4020fdd1eb4a292c8a919fe3715de0b3ec",
+ "identity": "sha256:e53c0753be29db98a9df2495ef6f67d106ed39cc36f792a254d9b50029420bf5",
"engineVersion": "0.6.0",
"toolchain": "[email protected]",
"sourceHash": "e78c388ec8e3eb3b197a458d3219254e739a85669c0e869aa34ebd296129b8a0",
- "dependencyHash": "3f2fcf55da59ef80ea5d8ac0e258f5517e1b084c1608a78e7d534aa25bcba611",
+ "dependencyHash": "c6746ae661afc9576bbfaa323ee13af6531644626dc5baeed8d49a06773922d2",
"dependencies": {
"@gltf-transform/core": "4.5.0",
"@gltf-transform/extensions": "4.5.0",
@@ -105,7 +105,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
@@ -114,11 +114,11 @@
"bundleHash": "sha256:fd52e9c43720b0017dd3d6c290e92d485a86e6c5a2d1dba50cb72215d6bf696c"
},
"agent-providers": {
- "identity": "sha256:3dce05fe9f707ffb931dc9dca46b8e4020fdd1eb4a292c8a919fe3715de0b3ec",
+ "identity": "sha256:e53c0753be29db98a9df2495ef6f67d106ed39cc36f792a254d9b50029420bf5",
"engineVersion": "0.6.0",
"toolchain": "[email protected]",
"sourceHash": "e78c388ec8e3eb3b197a458d3219254e739a85669c0e869aa34ebd296129b8a0",
- "dependencyHash": "3f2fcf55da59ef80ea5d8ac0e258f5517e1b084c1608a78e7d534aa25bcba611",
+ "dependencyHash": "c6746ae661afc9576bbfaa323ee13af6531644626dc5baeed8d49a06773922d2",
"dependencies": {
"@gltf-transform/core": "4.5.0",
"@gltf-transform/extensions": "4.5.0",
@@ -133,7 +133,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
diff --git a/package.json b/package.json
index 094be2de..684f99b3 100644
--- a/package.json
+++ b/package.json
@@ -122,7 +122,7 @@
"manifold-3d": "^3.5.3",
"sharp": "^0.35.4",
"three": "0.186.0",
- "three-subdivide": "^1.1.5",
+ "three-subdivide": "1.1.5",
"xatlasjs": "^0.2.0",
"zod": "^4.6.2"
},
diff --git a/src/__tests__/subdivide-normals.test.ts b/src/__tests__/subdivide-normals.test.ts
index 52d3c886..1a70089b 100644
--- a/src/__tests__/subdivide-normals.test.ts
+++ b/src/__tests__/subdivide-normals.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, test } from 'bun:test';
import type * as THREE from 'three';
-import { LoopSubdivision } from 'three-subdivide';
+import { LoopSubdivision } from 'three-subdivide/build/index.module.js';
import { mergeVertices, subdivide } from '../ops';
import { boxGeo, sphereGeo } from '../primitives';
diff --git a/src/__tests__/three-subdivide-esm.test.ts b/src/__tests__/three-subdivide-esm.test.ts
new file mode 100644
index 00000000..db55a5af
--- /dev/null
+++ b/src/__tests__/three-subdivide-esm.test.ts
@@ -0,0 +1,76 @@
+/**
+ * `three-subdivide` must be imported through its ESM build, never the bare specifier.
+ *
+ * The package ships both an ESM build and a UMD/CommonJS one, and it has **no
+ * `exports` map** -- so a bare `from 'three-subdivide'` resolves to `main`, which is
+ * the UMD bundle, which does `require("three")`. three r186 deprecated that build and
+ * now emits `THREE_CJS_DEPRECATED` on stderr when it loads, so the bare specifier put
+ * a deprecation warning in front of every `kiln` CLI invocation. three has announced
+ * the CJS build's removal, at which point the bare specifier stops working entirely.
+ *
+ * `[email protected]` is the latest release, so there is no upstream fix to wait
+ * for. The deep path is legal precisely BECAUSE the package declares no `exports`, and
+ * that is also why the dependency is pinned exactly rather than by caret: a minor
+ * release that added an `exports` map would make this path unresolvable, and a caret
+ * range would take that release silently.
+ *
+ * This guards the whole tree rather than one file, because the first fix missed the
+ * test that imports the same package -- which kept loading the CJS build and kept
+ * firing the warning, while the production import looked corrected.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// `fileURLToPath`, never `URL.pathname`: on Windows the latter yields
+// `/D:/a/kiln/src/`, whose leading slash makes every fs call ENOENT.
+const SRC = fileURLToPath(new URL('..', import.meta.url));
+const ESM_BUILD = 'three-subdivide/build/index.module.js';
+/** This file names the bad pattern in prose and in a regex, so it matches itself. */
+const SELF = fileURLToPath(new URL(import.meta.url));
+
+/** Every `.ts` under `src/`, so a new file cannot reintroduce the bare specifier. */
+function sourceFiles(dir: string, out: string[] = []): string[] {
+ for (const entry of readdirSync(dir)) {
+ const path = join(dir, entry);
+ if (statSync(path).isDirectory()) sourceFiles(path, out);
+ else if (path.endsWith('.ts')) out.push(path);
+ }
+ return out;
+}
+
+describe('three-subdivide is loaded as ESM', () => {
+ test('no file imports the bare specifier, which resolves to the CommonJS build', () => {
+ // Matches `from 'three-subdivide'` and `import('three-subdivide')` but not the
+ // deep ESM path, and not prose mentions of the package name in comments.
+ const bare = /(?:from|import\()\s*['"]three-subdivide['"]/u;
+ const offenders = sourceFiles(SRC)
+ .filter((file) => file !== SELF)
+ .filter((file) => bare.test(readFileSync(file, 'utf8')));
+ expect(offenders).toEqual([]);
+ });
+
+ test('the files that do use it reach the ESM build', () => {
+ const users = sourceFiles(SRC).filter((file) => readFileSync(file, 'utf8').includes(ESM_BUILD));
+ expect(users.length).toBeGreaterThan(0);
+ });
+
+ test('the ESM build contains no require() call, which is the whole point', () => {
+ const esm = readFileSync(
+ fileURLToPath(
+ new URL('../../node_modules/three-subdivide/build/index.module.js', import.meta.url),
+ ),
+ 'utf8',
+ );
+ expect(esm).not.toMatch(/\brequire\s*\(/u);
+ });
+
+ test('the dependency is pinned exactly, so no minor can add an exports map under us', () => {
+ const pkg = JSON.parse(
+ readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'),
+ ) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+ const range = { ...pkg.dependencies, ...pkg.devDependencies }['three-subdivide'];
+ expect(range).toMatch(/^\d+\.\d+\.\d+$/u);
+ });
+});