feat(extension): Include workspace bundled deps sourcemaps on dev build (#583)

Closes #576

This PR fixes sourcemap generation for local workspace packages during
development, enabling effective debugging in browser DevTools.

The issue was that Vite resolved workspace dependencies to their
pre-compiled `dist` folders, breaking the sourcemap chain back to the
original TypeScript source.

This is resolved by adding a conditional `resolve.alias` to the
`extension`'s Vite configuration. In development mode, all `@metamask/*`
workspace imports are aliased to their src directories. This allows Vite
to build the extension from a single, unified source tree, resulting in
a complete and accurate sourcemap. Sourcemaps are in-lined because
security restrictions on the `chrome-extension://` in web workers
prevent the loading of sourcemap files.

For production builds, this aliasing is disabled to ensure builds remain
fast and optimized.

### Development Workflow
Two primary development workflows are now fully supported with
sourcemaps:
1. Automatic Browser Launch:
- Run `yarn start` from within the packages/extension directory.
- This command triggers a development build (build:dev --watch) and
launches a Chromium instance with the extension loaded, providing a
complete debugging experience with sourcemaps out-of-the-box.
2. Manual Extension Loading:
- Run `yarn build:dev` from the root of the monorepo.
- This will build all necessary packages in development mode.
You can then manually load the extension's dist folder into chrome and
still have full sourcemap support.

<img width="1673" height="1127" alt="Screenshot 2025-07-24 at 16 08 18"
src="https://github.com/user-attachments/assets/0892351f-a985-41c7-bb55-53e1e35a9d9f"
/>
<img width="1560" height="1282" alt="Screenshot 2025-07-24 at 16 12 29"
src="https://github.com/user-attachments/assets/467d4ff8-8830-4603-8a41-d4ddca4c9a3e"
/>

Author: sirtimid

README.md

@@ -10,23 +10,16 @@ For detailed information on how to use the OCAP Kernel, please refer to the [OCA
 
 You can launch a browser-based Kernel Control Panel to interact with and manage vats:
 
-1. Navigate to the extension package:
-
 ```bash
-cd packages/extension
+yarn workspace @ocap/extension run start
 ```
 
-2. Start the development server:
-
-```bash
-yarn start
-```
+This will:
 
-3. This will:
-   - Launch a development server serving the extension
-   - Set up a default cluster configuration
-   - Serve sample vat bundles
-   - Provide a UI for managing and interacting with the kernel and vats
+- Launch a development server serving the extension
+- Set up a default cluster configuration
+- Serve sample vat bundles
+- Provide a UI for managing and interacting with the kernel and vats
 
 The control panel allows you to:
 

package.json

@@ -13,10 +13,12 @@
   ],
   "scripts": {
     "build": "yarn build:source && yarn build:special",
+    "build:dev": "yarn build:source && yarn build:special:dev",
     "build:clean": "yarn clean && yarn build",
     "build:docs": "yarn workspaces foreach --all --exclude @ocap/monorepo --exclude @ocap/extension --parallel --interlaced --verbose run build:docs",
     "build:source": "ts-bridge --project tsconfig.build.json --verbose",
     "build:special": "yarn workspace @ocap/vite-plugins run build && yarn workspace @metamask/kernel-shims run build && yarn workspace @metamask/kernel-browser-runtime run build:vite && yarn workspace @metamask/kernel-ui run build && yarn workspace @ocap/extension run build && yarn workspace @ocap/kernel-test run build",
+    "build:special:dev": "yarn workspace @ocap/vite-plugins run build && yarn workspace @metamask/kernel-shims run build && yarn workspace @metamask/kernel-browser-runtime run build:vite && yarn workspace @metamask/kernel-ui run build && yarn workspace @ocap/extension run build:dev && yarn workspace @ocap/kernel-test run build",
     "bundle": "node ./scripts/bundle-vat.js",
     "changelog:update": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:update",
     "changelog:validate": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:validate",

packages/extension/vite.config.ts

@@ -9,30 +9,29 @@ import {
 } from '@ocap/vite-plugins';
 import react from '@vitejs/plugin-react';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { defineConfig } from 'vite';
 import { checker as viteChecker } from 'vite-plugin-checker';
 import { viteStaticCopy } from 'vite-plugin-static-copy';
 import type { Target } from 'vite-plugin-static-copy';
 
+import * as pkg from './package.json';
 import {
-  rootDir,
   kernelBrowserRuntimeSrcDir,
   outDir,
   sourceDir,
   trustedPreludes,
 } from './scripts/build-constants.mjs';
 
-/**
- * Files that need to be statically copied to the destination directory.
- * Paths are relative from the project root directory.
- */
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(dirname, '..', '..');
 const staticCopyTargets: readonly (string | Target)[] = [
   // The extension manifest
-  path.resolve(sourceDir, 'manifest.json'),
+  'packages/extension/src/manifest.json',
   // Trusted prelude-related
-  path.resolve(sourceDir, 'env/dev-console.js'),
-  path.resolve(sourceDir, 'env/background-trusted-prelude.js'),
-  path.resolve(rootDir, 'kernel-shims/dist/endoify.js'),
+  'packages/extension/src/env/dev-console.js',
+  'packages/extension/src/env/background-trusted-prelude.js',
+  'packages/kernel-shims/dist/endoify.js',
 ];
 
 // https://vitejs.dev/config/
@@ -45,13 +44,17 @@ export default defineConfig(({ mode }) => {
 
   return {
     root: rootDir,
-
+    resolve: {
+      alias: isDev ? getPackageDevAliases(pkg.dependencies) : [],
+    },
     build: {
       assetsDir: '',
       emptyOutDir: true,
       // Disable Vite's module preload, which may cause SES-dependent code to run before lockdown.
       modulePreload: false,
       outDir,
+      minify: !isDev,
+      sourcemap: isDev ? 'inline' : false,
       rollupOptions: {
         input: {
           background: path.resolve(sourceDir, 'background.ts'),
@@ -71,14 +74,7 @@ export default defineConfig(({ mode }) => {
           assetFileNames: '[name].[ext]',
         },
       },
-      ...(isDev
-        ? {
-            minify: false,
-            sourcemap: 'inline',
-          }
-        : {}),
     },
-
     plugins: [
       react(),
       htmlTrustedPrelude(),
@@ -118,3 +114,41 @@ export default defineConfig(({ mode }) => {
     ],
   };
 });
+
+/**
+ * Generates Vite aliases for workspace packages to enable proper sourcemap handling in development.
+ *
+ * By default, Vite resolves workspace packages to their `dist` folders, which breaks the
+ * sourcemap chain. These aliases force Vite to use the original TypeScript source from the
+ * `src` directories instead, ensuring a complete and accurate sourcemap for debugging.
+ *
+ * A special alias for `@metamask/kernel-ui/styles.css` is included to resolve the
+ * built stylesheet correctly from its `dist` folder.
+ *
+ * @param deps - The dependencies object from the `package.json` file.
+ * @returns An array of Vite alias objects for development mode.
+ */
+function getPackageDevAliases(
+  deps: Record<string, string> = {},
+): { find: string; replacement: string }[] {
+  const workspacePackages = Object.keys(deps)
+    .filter(
+      (name) => name.startsWith('@metamask/') && deps[name] === 'workspace:^',
+    )
+    .map((pkgName) => ({
+      find: pkgName,
+      replacement: path.resolve(
+        rootDir,
+        `packages/${pkgName.replace('@metamask/', '')}/src`,
+      ),
+    }));
+
+  return [
+    // Special alias for kernel-ui styles, which are in dist
+    {
+      find: '@metamask/kernel-ui/styles.css',
+      replacement: path.resolve(rootDir, 'packages/kernel-ui/dist/styles.css'),
+    },
+    ...workspacePackages,
+  ];
+}