Merge pull request #272 from pmndrs/feat/published-source-maps

fix(glyph): publish resolvable hidden source maps

Author: thejustinwalsh

.agents/docs/attestations/2026-10-09-glyph-bb87af1e.md

@@ -26,7 +26,6 @@
     "dist",
     "src",
     "!dist/.tsbuildinfo",
-    "!dist/**/*.map",
     "!dist/internal/raster-baker-profile.d.ts",
     "!dist/internal/raster-baker-profile.js"
   ],

.agents/docs/log/2026-10-09-published-source-maps.md

@@ -5,6 +5,7 @@ import { basename, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { captureCommand } from './support/capture-command.mjs';
+import { rewritePublishedSourceMaps } from './support/published-source-maps.mjs';
 import { writeGeneratedTypescriptAbi } from './support/generated-typescript-abi.mjs';
 import { reproducibleRustEnvironment } from './support/reproducible-rust-env.mjs';
 
@@ -280,6 +281,7 @@ await run(tsc, [
 // private test seams out of the public module graph while the published subpaths share
 // package-owned chunks and TypeGPU metadata compiled at publish time.
 await run(tsdown, ['--out-dir', fileURLToPath(stagingDirectory), '--no-clean']);
+await rewritePublishedSourceMaps(stagingPath, fileURLToPath(distributionDirectory), join(packageRoot, 'src'));
 await run(wasmOpt, [
   '--enable-bulk-memory',
   '--enable-nontrapping-float-to-int',

.agents/docs/packages/glyph.md

@@ -0,0 +1,23 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+/** Rebase staged maps onto the source tree that ships beside dist, without changing their mappings. */
+export async function rewritePublishedSourceMaps(stagingDirectory, distributionDirectory, sourceDirectory) {
+  for (const entry of await readdir(stagingDirectory, { recursive: true })) {
+    if (!entry.endsWith('.map')) continue;
+    const stagedFile = join(stagingDirectory, entry);
+    const map = JSON.parse(await readFile(stagedFile, 'utf8'));
+    map.sources = map.sources.map((source) => {
+      const sourcePath = resolve(dirname(stagedFile), map.sourceRoot ?? '', source);
+      const sourceRelative = relative(sourceDirectory, sourcePath);
+      if (isAbsolute(sourceRelative) || sourceRelative === '..' || sourceRelative.startsWith(`..${sep}`)) {
+        throw new Error(`Source map ${entry} references a source outside the published tree: ${source}`);
+      }
+      return relative(dirname(join(distributionDirectory, entry)), sourcePath)
+        .split(sep)
+        .join('/');
+    });
+    delete map.sourceRoot;
+    await writeFile(stagedFile, JSON.stringify(map));
+  }
+}

packages/glyph/package.json

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { copyFile, mkdtemp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import test from 'node:test';
 import { build } from 'vite';
@@ -58,6 +58,32 @@ test('the packed package exposes every ESM subpath and no CommonJS entry', async
     'package.json',
     'src',
   ]);
+  const maps = packedFiles.filter((path) => path.startsWith('dist/') && path.endsWith('.map'));
+  assert.ok(
+    maps.some((path) => path.endsWith('.js.map')),
+    'JavaScript maps must ship',
+  );
+  assert.ok(
+    maps.some((path) => path.endsWith('.d.ts.map')),
+    'declaration maps must ship',
+  );
+  for (const path of packedFiles.filter((entry) => entry.startsWith('dist/') && entry.endsWith('.js'))) {
+    assert.doesNotMatch(await readFile(join(installedDirectory, path), 'utf8'), /sourceMappingURL=/, path);
+  }
+  for (const path of packedFiles.filter((entry) => entry.startsWith('dist/') && entry.endsWith('.d.ts'))) {
+    const declaration = await readFile(join(installedDirectory, path), 'utf8');
+    for (const [, map] of declaration.matchAll(/sourceMappingURL=([^\s]+)/g)) {
+      assert.ok(packedFiles.includes(join(dirname(path), map)), `${path} must reference a packed map`);
+    }
+  }
+  for (const path of maps) {
+    const map = JSON.parse(await readFile(join(installedDirectory, path), 'utf8'));
+    for (const source of map.sources) {
+      const sourcePath = resolve(dirname(join(installedDirectory, path)), map.sourceRoot ?? '', source);
+      assert.ok(sourcePath.startsWith(`${join(installedDirectory, 'src')}/`), `${path}: ${source}`);
+      assert.ok((await stat(sourcePath)).isFile(), `${path} must resolve to a packed source: ${source}`);
+    }
+  }
   for (const peer of ['typegpu', '@typegpu/gl', '@typegpu/three']) {
     assert.ok(manifest.peerDependencies[peer], `${peer} must be a declared peer`);
     assert.equal(manifest.peerDependenciesMeta[peer]?.optional, true, `${peer} must remain optional`);

packages/glyph/scripts/build.mjs

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import test from 'node:test';
+import { rewritePublishedSourceMaps } from '../../scripts/support/published-source-maps.mjs';
+
+test('staged JS and declaration maps resolve from the published tree and preserve mappings', async (context) => {
+  const root = await mkdtemp(join(tmpdir(), 'glyph-source-maps-'));
+  context.after(() => rm(root, { recursive: true, force: true }));
+  const staging = join(root, '.cache/build/staging/internal');
+  const source = join(root, 'src/internal');
+  await mkdir(staging, { recursive: true });
+  await mkdir(source, { recursive: true });
+  const original = {
+    version: 3,
+    sources: ['module.ts'],
+    sourceRoot: relative(staging, source),
+    names: ['value'],
+    mappings: 'AAAA',
+    sourcesContent: ['export const value = 1;'],
+  };
+  for (const suffix of ['js', 'd.ts']) await writeFile(join(staging, `module.${suffix}.map`), JSON.stringify(original));
+  await rewritePublishedSourceMaps(join(root, '.cache/build/staging'), join(root, 'dist'), join(root, 'src'));
+  for (const suffix of ['js', 'd.ts']) {
+    const map = JSON.parse(await readFile(join(staging, `module.${suffix}.map`), 'utf8'));
+    assert.equal(resolve(root, 'dist/internal', map.sources[0]), join(source, 'module.ts'));
+    const { sourceRoot: _sourceRoot, ...unchanged } = original;
+    assert.deepEqual(map, { ...unchanged, sources: ['../../src/internal/module.ts'] });
+  }
+});
+
+test('source maps cannot escape the packaged source tree', async (context) => {
+  const root = await mkdtemp(join(tmpdir(), 'glyph-source-map-escape-'));
+  context.after(() => rm(root, { recursive: true, force: true }));
+  await mkdir(join(root, 'stage'));
+  await writeFile(join(root, 'stage/module.js.map'), JSON.stringify({ version: 3, sources: ['../../outside.ts'] }));
+  await assert.rejects(
+    rewritePublishedSourceMaps(join(root, 'stage'), join(root, 'dist'), join(root, 'src')),
+    /outside the published tree/,
+  );
+});

packages/glyph/scripts/support/published-source-maps.mjs

@@ -23,7 +23,7 @@ const shared = defineConfig({
     neverBundle: true,
   },
   exports: false,
-  // The package excludes the map files, so the emitted modules must not reference them.
+  // Ship maps for external tooling while keeping browser modules free of map references.
   sourcemap: 'hidden',
   report: false,
   // Auto-naming wraps constructor calls outside their PURE annotations, preventing