feat: Phase 1 — externalize shared runtimes for production builds

Added build-assets module that generates fingerprinted static assets:
- buildRuntimeAsset(): signals runtime (20-40KB) as external JS file
- buildRouterAsset(): SPA router (5-8KB) as external JS file
- fingerprint(): SHA-256 content hashing for cache-busting filenames

Added buildMode option to StxConfig ('compile' | 'serve'):
- injectSignalsRuntime: emits <script src> placeholder in compile mode
- injectRouterScript: emits <script src> placeholder in compile mode
- Dev mode (undefined buildMode) behavior unchanged

12 new tests covering asset generation, fingerprinting, and compile mode.
All 8004 existing tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: glennmichael123

packages/stx/src/build-assets.ts

@@ -0,0 +1,82 @@
+/**
+ * Build Assets
+ *
+ * Generates and fingerprints shared static assets for production builds.
+ * These assets are identical across all pages and can be cached aggressively.
+ *
+ * @module build-assets
+ */
+
+import { createHash } from 'node:crypto'
+import { generateSignalsRuntime, generateSignalsRuntimeDev } from './signals'
+import { getRouterScript } from 'stx-router'
+
+/**
+ * A built asset with content and fingerprinted filename.
+ */
+export interface BuiltAsset {
+  /** The asset content (JS or CSS) */
+  content: string
+  /** Fingerprinted filename (e.g. 'runtime.a1b2c3d4.js') */
+  filename: string
+  /** Content hash for cache busting */
+  hash: string
+}
+
+/**
+ * Generate a fingerprint hash from content.
+ * Uses SHA-256 truncated to 8 hex chars.
+ */
+export function fingerprint(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 8)
+}
+
+/**
+ * Build the signals runtime as an external asset.
+ * This is identical for every page — no need to inline 20-40KB per page.
+ */
+export function buildRuntimeAsset(debug = false): BuiltAsset {
+  const content = debug ? generateSignalsRuntimeDev() : generateSignalsRuntime()
+  const hash = fingerprint(content)
+  return {
+    content,
+    filename: `runtime.${hash}.js`,
+    hash,
+  }
+}
+
+/**
+ * Build the SPA router script as an external asset.
+ * Identical for every page — ~5-8KB.
+ */
+export function buildRouterAsset(): BuiltAsset {
+  const content = getRouterScript()
+  const hash = fingerprint(content)
+  return {
+    content,
+    filename: `router.${hash}.js`,
+    hash,
+  }
+}
+
+/**
+ * Generates `<script src>` and `<link href>` tags for externalized assets.
+ * Used in build mode to replace inline scripts with references.
+ */
+export function assetTags(assets: { runtime?: BuiltAsset, router?: BuiltAsset, css?: BuiltAsset }): {
+  runtimeTag: string
+  routerTag: string
+  cssTag: string
+} {
+  return {
+    runtimeTag: assets.runtime
+      ? `<script src="/__stx/${assets.runtime.filename}"></script>`
+      : '',
+    routerTag: assets.router
+      ? `<script src="/__stx/${assets.router.filename}"></script>`
+      : '',
+    cssTag: assets.css
+      ? `<link rel="stylesheet" href="/__stx/${assets.css.filename}">`
+      : '',
+  }
+}

packages/stx/src/index.ts

@@ -35,6 +35,7 @@ export * from './assets'
 export * from './app-shell'
 export * from './async-components'
 export * from './auth'
+export * from './build-assets'
 export * from './build-optimizer'
 export * from './broadcasting'
 export * from './caching'

packages/stx/src/process.ts

@@ -634,6 +634,21 @@ function injectSignalsRuntime(template: string, options: StxOptions): string {
     return template
   }
 
+  // Build mode: emit a placeholder reference instead of inlining the full runtime.
+  // The production builder will replace this with a fingerprinted <script src> tag.
+  if (options.buildMode === 'compile') {
+    const runtimeScript = `<script src="/__stx/runtime.__STX_HASH__.js"></script>`
+    const firstScriptInDoc = template.indexOf('<script')
+    if (firstScriptInDoc !== -1) {
+      return template.slice(0, firstScriptInDoc) + runtimeScript + '\n' + template.slice(firstScriptInDoc)
+    }
+    if (template.includes('</head>')) {
+      const idx = template.indexOf('</head>')
+      return template.slice(0, idx) + runtimeScript + '\n' + template.slice(idx)
+    }
+    return runtimeScript + '\n' + template
+  }
+
   const runtime = options.debug ? generateSignalsRuntimeDev() : generateSignalsRuntime()
   const runtimeScript = `<script data-stx-scoped>${runtime}</script>`
 
@@ -666,7 +681,7 @@ function injectSignalsRuntime(template: string, options: StxOptions): string {
  * The router is provided by the canonical router in packages/router/src/client.ts.
  * It guards against double-initialization so it's safe to inject alongside @stxRouter.
  */
-export function injectRouterScript(template: string): string {
+export function injectRouterScript(template: string, options?: StxOptions): string {
   // Only inject into full HTML pages (not template fragments or components)
   if (!template.includes('</body>')) {
     return template
@@ -677,7 +692,10 @@ export function injectRouterScript(template: string): string {
     return template
   }
 
-  const routerScript = `<script>${getRouterScript()}</script>`
+  // Build mode: emit a placeholder reference instead of inlining the full router script.
+  const routerScript = options?.buildMode === 'compile'
+    ? `<script src="/__stx/router.__STX_HASH__.js"></script>`
+    : `<script>${getRouterScript()}</script>`
 
   // Use string concatenation to avoid $-interpretation in .replace()
   const bodyCloseIdx = template.lastIndexOf('</body>')

packages/stx/src/types/config-types.ts

@@ -538,6 +538,20 @@ export interface StxConfig {
    */
   strict?: boolean | StrictModeConfig
 
+  /**
+   * Build mode for the processing pipeline.
+   * - `undefined` (default): dev mode, inline everything per request
+   * - `'compile'`: build mode, emit asset reference placeholders instead of inline code
+   * - `'serve'`: production serve mode, hydrate pre-compiled templates
+   */
+  buildMode?: 'compile' | 'serve'
+
+  /**
+   * Output directory for production builds.
+   * @default '.output'
+   */
+  outputDir?: string
+
   /**
    * App shell file for single-shell mode.
    * When set (or auto-detected as 'app.stx'), the shell wraps all pages.

packages/stx/test/build/build-assets.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for build assets — externalized runtime, router, and CSS
+ */
+import { describe, expect, it } from 'bun:test'
+import { buildRuntimeAsset, buildRouterAsset, fingerprint, assetTags } from '../../src/build-assets'
+import { processDirectives, defaultConfig } from '../../src/index'
+
+describe('Build Assets', () => {
+  describe('fingerprint', () => {
+    it('should produce a deterministic 8-char hex hash', () => {
+      const hash = fingerprint('hello world')
+      expect(hash).toHaveLength(8)
+      expect(hash).toMatch(/^[0-9a-f]{8}$/)
+      expect(fingerprint('hello world')).toBe(hash) // deterministic
+    })
+
+    it('should produce different hashes for different content', () => {
+      expect(fingerprint('hello')).not.toBe(fingerprint('world'))
+    })
+  })
+
+  describe('buildRuntimeAsset', () => {
+    it('should produce a valid JS asset with fingerprinted filename', () => {
+      const asset = buildRuntimeAsset()
+      expect(asset.content).toContain('state')
+      expect(asset.content).toContain('derived')
+      expect(asset.content).toContain('effect')
+      expect(asset.filename).toMatch(/^runtime\.[0-9a-f]{8}\.js$/)
+      expect(asset.hash).toHaveLength(8)
+    })
+
+    it('should produce valid JS that parses', () => {
+      const asset = buildRuntimeAsset()
+      expect(() => new Function(asset.content)).not.toThrow()
+    })
+
+    it('should produce deterministic output', () => {
+      const a = buildRuntimeAsset()
+      const b = buildRuntimeAsset()
+      expect(a.hash).toBe(b.hash)
+      expect(a.filename).toBe(b.filename)
+    })
+
+    it('should produce different output for debug mode', () => {
+      const prod = buildRuntimeAsset(false)
+      const dev = buildRuntimeAsset(true)
+      expect(dev.content.length).toBeGreaterThan(prod.content.length)
+      expect(dev.hash).not.toBe(prod.hash)
+    })
+  })
+
+  describe('buildRouterAsset', () => {
+    it('should produce a valid JS asset', () => {
+      const asset = buildRouterAsset()
+      expect(asset.content).toContain('__stxRouter')
+      expect(asset.filename).toMatch(/^router\.[0-9a-f]{8}\.js$/)
+    })
+
+    it('should be deterministic', () => {
+      const a = buildRouterAsset()
+      const b = buildRouterAsset()
+      expect(a.hash).toBe(b.hash)
+    })
+  })
+
+  describe('assetTags', () => {
+    it('should generate script src tags for assets', () => {
+      const runtime = buildRuntimeAsset()
+      const router = buildRouterAsset()
+      const tags = assetTags({ runtime, router })
+
+      expect(tags.runtimeTag).toContain('/__stx/runtime.')
+      expect(tags.runtimeTag).toContain('.js')
+      expect(tags.runtimeTag).toContain('<script src=')
+      expect(tags.routerTag).toContain('/__stx/router.')
+      expect(tags.routerTag).toContain('<script src=')
+    })
+
+    it('should return empty strings for missing assets', () => {
+      const tags = assetTags({})
+      expect(tags.runtimeTag).toBe('')
+      expect(tags.routerTag).toBe('')
+      expect(tags.cssTag).toBe('')
+    })
+  })
+
+  describe('Build mode in processDirectives', () => {
+    const defaultOpts = { partialsDir: '/tmp', componentsDir: '/tmp' }
+
+    it('should emit script src placeholder in compile mode for signals runtime', async () => {
+      const html = `<script>const count = state(0)</script><div>{{ count() }}</div>`
+      const result = await processDirectives(html, {}, '/test.stx', {
+        ...defaultConfig,
+        ...defaultOpts,
+        buildMode: 'compile',
+      }, new Set())
+
+      expect(result).toContain('/__stx/runtime.__STX_HASH__.js')
+      expect(result).not.toContain('window.stx.state') // no inline runtime
+    })
+
+    it('should inline runtime in dev mode (no buildMode)', async () => {
+      const html = `<script>const count = state(0)</script><div>{{ count() }}</div>`
+      const result = await processDirectives(html, {}, '/test.stx', {
+        ...defaultConfig,
+        ...defaultOpts,
+      }, new Set())
+
+      // Dev mode: inline runtime
+      expect(result).not.toContain('/__stx/runtime.')
+    })
+  })
+})