@awarebydefault/display-case 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awarebydefault/display-case",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A Bun-native, AI-friendly component showcase — a lightweight alternative to Storybook.",
   "license": "MIT",
   "author": "Jake Uskoski <jake@awarebydefault.com>",
@@ -73,8 +73,10 @@
     "e2e": "playwright test",
     "e2e:headed": "playwright test --headed",
     "e2e:install": "playwright install chromium",
-    "release": "semantic-release",
-    "release:dry": "semantic-release --dry-run --no-ci",
+    "changeset": "changeset",
+    "changeset:status": "changeset status",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish",
     "prepare": "husky"
   },
   "peerDependencies": {
@@ -93,6 +95,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
+    "@changesets/cli": "^2.27.11",
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
     "@emotion/cache": "^11.14.0",
@@ -100,14 +103,11 @@
     "@emotion/server": "^11.11.0",
     "@fission-ai/openspec": "1.4.1",
     "@playwright/test": "^1.60.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
     "@types/bun": "^1.2.0",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "husky": "^9.1.7",
-    "semantic-release": "^25.0.5",
     "typescript": "^5.7.0"
   }
 }

package/src/commands/publish.ts

@@ -10,6 +10,7 @@ import {
   resolveConfig,
 } from '../core/discovery'
 import { mdxPlugin } from '../core/mdx-plugin'
+import { pinReact } from '../core/pin-react'
 import type { DisplayCaseConfig } from '../index'
 import { getManifest } from '../server/server'
 
@@ -166,7 +167,9 @@ export async function publish(
 
   const defines = await buildDefines(pkgDir)
 
-  // Browser bundle: minified, content-hashed, production React.
+  // Browser bundle: minified, content-hashed, production React. pinReact keeps
+  // Display Case's render runtime and the consumer's components on one React copy
+  // (see pinReact for the dual-React bug it prevents).
   const browserEntries = [BROWSER_ENTRY, renderEntry]
   if (primerEntry) browserEntries.push(primerEntry)
   const browser = await Bun.build({
@@ -175,7 +178,7 @@ export async function publish(
     target: 'browser',
     minify: true,
     sourcemap: 'none',
-    plugins: [mdxPlugin()],
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     define: defines,
     naming: {
       entry: '[name]-[hash].[ext]',
@@ -196,7 +199,15 @@ export async function publish(
   }
 
   // SSR renderers for the production server: built once (no watching), imported
-  // by `prod-server`. React stays external (resolved at runtime).
+  // by `prod-server`. React stays external here (unlike the browser bundle and
+  // the dev server's in-process SSR, which pin React to the consumer copy): a
+  // published build deploys with its own `bun install`, so the prod process has a
+  // single React already. Leaving it external keeps `prod-server`'s own chrome
+  // renderer (`ssr-shell`, which needs `react-dom/server` at runtime regardless)
+  // and these bundled case renderers on that one copy — bundling React here would
+  // instead put a second copy in the prod process for no benefit. The dual-React
+  // hazard pinReact addresses comes from a temp/global *tool* install resolving a
+  // different React than the consumer's components; a clean deploy has neither.
   const ssrEntries = [ssrEntry]
   if (ssrPrimerEntry) ssrEntries.push(ssrPrimerEntry)
   const ssr = await Bun.build({

package/src/core/mdx-plugin.test.ts

@@ -57,4 +57,30 @@ describe('mdxPlugin', () => {
       await rm(dir, { recursive: true, force: true })
     }
   })
+
+  test('emits an absolute, self-resolved markdown-to-jsx specifier', async () => {
+    const { run } = captureOnLoad()
+    const dir = await makeTempDir()
+    try {
+      const file = join(dir, 'doc.mdx')
+      await Bun.write(file, '# Title\n\nSome prose.\n')
+      const result = await run({ path: file })
+      // The compiled primer is loaded from the consumer's tree, where a bare
+      // `markdown-to-jsx` would not resolve. The plugin anchors it at Display
+      // Case's own install so the consumer never needs to declare the dep.
+      const resolved = Bun.resolveSync('markdown-to-jsx', import.meta.dir)
+      expect(result.contents).toContain(
+        `import __Md from ${JSON.stringify(resolved)}`,
+      )
+      // Never a bare specifier — that is the bug this guards against.
+      expect(result.contents).not.toContain(
+        "import __Md from 'markdown-to-jsx'",
+      )
+      expect(result.contents).not.toContain(
+        'import __Md from "markdown-to-jsx"',
+      )
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
 })

package/src/core/mdx-plugin.ts

@@ -1,6 +1,38 @@
 import type { BunPlugin } from 'bun'
 import { mdxToTsx } from './mdx-lite'
 
+/**
+ * Absolute path to `markdown-to-jsx`, resolved from Display Case's own location
+ * (this module), memoized on first use.
+ *
+ * The compiled primer module is loaded from inside the *consumer* package's tree
+ * (its `primer.mdx` is the bundle entry), so a bare `import 'markdown-to-jsx'`
+ * would be resolved relative to the consumer — and `markdown-to-jsx` is a private
+ * dependency of `@awarebydefault/display-case`, not hoisted into the consumer's
+ * scope, so that resolution fails with `Could not resolve "markdown-to-jsx"`.
+ * Emitting an absolute path anchored at Display Case's own install makes the
+ * import resolve regardless of the consumer's `node_modules` layout, so authoring
+ * a Markdown/MDX primer never requires the consumer to redeclare the dep. It also
+ * resolves to the same physical module the `.placard.md` DocPanel imports, so Bun
+ * dedupes the two into one bundled copy.
+ */
+let cachedMarkdownSpecifier: string | undefined
+function markdownSpecifier(): string {
+  if (cachedMarkdownSpecifier === undefined) {
+    try {
+      cachedMarkdownSpecifier = Bun.resolveSync(
+        'markdown-to-jsx',
+        import.meta.dir,
+      )
+    } catch {
+      // Fall back to the bare specifier (matches mdx-lite's own default) for the
+      // case where a consumer does carry the dep and resolution from here fails.
+      cachedMarkdownSpecifier = 'markdown-to-jsx'
+    }
+  }
+  return cachedMarkdownSpecifier
+}
+
 /**
  * Bun bundler plugin that compiles `.mdx` to TSX on load, so the Primer entry can
  * `import` an authored `.mdx` document and the components it pulls in.
@@ -23,7 +55,12 @@ export function mdxPlugin(): BunPlugin {
     setup(build) {
       build.onLoad({ filter: /\.mdx$/ }, async (args) => {
         const source = await Bun.file(args.path).text()
-        return { contents: mdxToTsx(source), loader: 'tsx' }
+        return {
+          contents: mdxToTsx(source, {
+            markdownSpecifier: markdownSpecifier(),
+          }),
+          loader: 'tsx',
+        }
       })
     },
   }

package/src/core/pin-react.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { makeTempDir } from '../testing/test-helpers'
+import { pinReact } from './pin-react'
+
+type OnResolveArgs = { path: string }
+type OnResolveResult = { path: string }
+type OnResolveCb = (args: OnResolveArgs) => OnResolveResult
+
+/**
+ * Drive the plugin without a real Bun build: capture the `onResolve` handler it
+ * registers (and its filter), then invoke it directly.
+ */
+function captureOnResolve(pkgDir: string): {
+  filter: RegExp
+  run: OnResolveCb
+} {
+  const calls: Array<{ filter: RegExp; cb: OnResolveCb }> = []
+  const build = {
+    onResolve: (opts: { filter: RegExp }, cb: OnResolveCb) =>
+      calls.push({ filter: opts.filter, cb }),
+  }
+  const plugin = pinReact(pkgDir)
+  plugin.setup(build as unknown as Parameters<typeof plugin.setup>[0])
+  if (!calls[0]) throw new Error('plugin registered no onResolve handler')
+  return { filter: calls[0].filter, run: calls[0].cb }
+}
+
+describe('pinReact', () => {
+  test('matches react / react-dom and their sub-paths, but not lookalikes', () => {
+    const { filter } = captureOnResolve(process.cwd())
+    for (const id of [
+      'react',
+      'react-dom',
+      'react-dom/client',
+      'react-dom/server',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+    ]) {
+      expect(filter.test(id)).toBe(true)
+    }
+    // Unrelated packages that merely start with "react" must not be captured.
+    for (const id of ['react-foo', 'react-router', '@scope/react', 'preact']) {
+      expect(filter.test(id)).toBe(false)
+    }
+  })
+
+  test('resolves every react specifier from the given pkgDir', () => {
+    const dir = process.cwd()
+    const { run } = captureOnResolve(dir)
+    for (const id of [
+      'react',
+      'react-dom',
+      'react-dom/client',
+      'react/jsx-runtime',
+    ]) {
+      expect(run({ path: id }).path).toBe(Bun.resolveSync(id, dir))
+    }
+  })
+
+  test('throws a helpful error when react is not resolvable from pkgDir', async () => {
+    const dir = await makeTempDir()
+    try {
+      const { run } = captureOnResolve(dir)
+      expect(() => run({ path: 'react' })).toThrow(
+        /Install react and react-dom/,
+      )
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('bundles the render runtime and a hook component into one browser bundle', async () => {
+    const dir = await makeTempDir()
+    try {
+      // The pairing that splits across two React copies without pinning: the
+      // renderer (`react-dom/client`) plus a hook-using component. Bundling one
+      // copy per resolved path, and pinning every specifier to a single pkgDir,
+      // is what guarantees they share a React (proven by the resolution test
+      // above); here we assert the plugin keeps a real build working end to end.
+      const entry = join(dir, 'entry.tsx')
+      await Bun.write(
+        entry,
+        [
+          "import { createRoot } from 'react-dom/client'",
+          "import { useState } from 'react'",
+          'export function App() {',
+          '  const [n] = useState(0)',
+          '  return n',
+          '}',
+          'export { createRoot }',
+        ].join('\n'),
+      )
+      const result = await Bun.build({
+        entrypoints: [entry],
+        target: 'browser',
+        plugins: [pinReact(process.cwd())],
+      })
+      expect(result.success).toBe(true)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/core/pin-react.ts

@@ -0,0 +1,48 @@
+import type { BunPlugin } from 'bun'
+
+/**
+ * Bun bundler plugin that pins every `react` / `react-dom` specifier to the
+ * single copy installed in the **consumer** project (`pkgDir`).
+ *
+ * Why this is necessary: Display Case's own client runtime (`browser-entry`,
+ * `render-mount`) statically imports `react-dom/client` and `react`, whose bare
+ * specifiers resolve relative to **where Display Case itself is installed** —
+ * while the consumer's `*.case.tsx` files and their deps resolve relative to the
+ * **consumer project**. When those two installs differ (the common case for
+ * `bunx @awarebydefault/display-case`, which installs the tool — and its peer
+ * react/react-dom — into a temp prefix), the browser bundle ends up with *two*
+ * React instances. `react-dom` drives one React's dispatcher; the consumer's
+ * components read the other's (null) dispatcher → "Invalid hook call … more than
+ * one copy of React", and every hook-using component blanks. Hook-free
+ * components never touch the dispatcher, so they render and mask the bug.
+ *
+ * Forcing all react/react-dom resolution to `pkgDir` collapses the two copies to
+ * one regardless of how the tool was invoked (bunx temp prefix, global install,
+ * npx, pnpm's strict layout, hoisting differences). The renderer
+ * (`createRoot`/`hydrateRoot`/`renderToString`) then binds to the same React the
+ * consumer's components use.
+ *
+ * Resolve from `pkgDir`, NOT the package dir — the renderer must bind to the
+ * React the consumer's components import, not Display Case's own.
+ */
+export function pinReact(pkgDir: string): BunPlugin {
+  return {
+    name: 'display-case-pin-react',
+    setup(build) {
+      // Matches `react`, `react-dom`, and their sub-paths (`react-dom/client`,
+      // `react-dom/server`, `react/jsx-runtime`, `react/jsx-dev-runtime`) — but
+      // not unrelated packages like `react-foo` or `@scope/react`.
+      build.onResolve({ filter: /^(react|react-dom)(\/.*)?$/ }, (args) => {
+        try {
+          return { path: Bun.resolveSync(args.path, pkgDir) }
+        } catch (cause) {
+          throw new Error(
+            `Display Case could not resolve "${args.path}" from ${pkgDir}. ` +
+              'Install react and react-dom in the package you point Display Case at.',
+            { cause },
+          )
+        }
+      })
+    },
+  }
+}

package/src/server/server.ts

@@ -20,6 +20,7 @@ import {
 } from '../core/discovery'
 import type { Manifest } from '../core/manifest'
 import { mdxPlugin } from '../core/mdx-plugin'
+import { pinReact } from '../core/pin-react'
 import type { DisplayCaseConfig } from '../index'
 import type { PrimerHtmlResult } from '../render/ssr-primer'
 import type { CaseRenderer } from '../render/ssr-render'
@@ -225,8 +226,10 @@ async function rebuild(
     outdir,
     target: 'browser',
     // The MDX plugin compiles the primer's `.mdx` (and any `.mdx` it imports)
-    // to JS on load; it's a no-op for builds without a primer entry.
-    plugins: [mdxPlugin()],
+    // to JS on load; it's a no-op for builds without a primer entry. pinReact
+    // collapses Display Case's render runtime and the consumer's components onto
+    // a single React copy — see pinReact for the dual-React bug it prevents.
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     // Inline the consumer's public env (BUN_PUBLIC_*) so a `process.env.*` read
     // in bundled code (e.g. the API base URL) doesn't survive as a literal that
     // throws `process is not defined` in the browser. See publicEnvDefines.
@@ -248,8 +251,10 @@ async function rebuild(
   // each rebuild because Bun caches imports by resolved path — a stable name
   // would return the stale renderer after an edit (the same staleness that forces
   // the manifest into a subprocess). The bundle inlines case source from disk, so
-  // importing the fresh file yields current modules. React stays external so the
-  // server resolves it from node_modules at import time.
+  // importing the fresh file yields current modules. pinReact bundles the
+  // consumer's React (instead of leaving it external) so `renderToString` and
+  // the consumer's components share one React — the same dual-React hazard the
+  // browser bundle faces, here for the in-process server render.
   const ssrEntry = await codegenSsrEntry(pkgDir, files, configPath)
   const ssrOutDir = join(cacheDir(pkgDir), 'ssr')
   const ssrName = `ssr-entry-${++ssrBuildSeq}`
@@ -257,15 +262,8 @@ async function rebuild(
     entrypoints: [ssrEntry],
     outdir: ssrOutDir,
     target: 'bun',
-    plugins: [mdxPlugin()],
+    plugins: [mdxPlugin(), pinReact(pkgDir)],
     define: await publicEnvDefines(pkgDir),
-    external: [
-      'react',
-      'react-dom',
-      'react-dom/server',
-      'react/jsx-runtime',
-      'react/jsx-dev-runtime',
-    ],
     naming: {
       entry: `${ssrName}.[ext]`,
       chunk: '[name]-[hash].[ext]',
@@ -297,15 +295,8 @@ async function rebuild(
       entrypoints: [ssrPrimerEntry],
       outdir: ssrOutDir,
       target: 'bun',
-      plugins: [mdxPlugin()],
+      plugins: [mdxPlugin(), pinReact(pkgDir)],
       define: await publicEnvDefines(pkgDir),
-      external: [
-        'react',
-        'react-dom',
-        'react-dom/server',
-        'react/jsx-runtime',
-        'react/jsx-dev-runtime',
-      ],
       naming: {
         entry: `${ssrPrimerName}.[ext]`,
         chunk: '[name]-[hash].[ext]',