@barefootjs/hono 0.1.0

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@barefootjs/hono",
+  "version": "0.1.0",
+  "description": "Hono integration for BarefootJS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./scripts": {
+      "types": "./dist/scripts.d.ts",
+      "import": "./dist/scripts.js"
+    },
+    "./portals": {
+      "types": "./dist/portals.d.ts",
+      "import": "./dist/portals.js"
+    },
+    "./portal": {
+      "types": "./dist/portal-ssr.d.ts",
+      "import": "./dist/portal-ssr.js"
+    },
+    "./dialog-context": {
+      "types": "./dist/dialog-context.d.ts",
+      "import": "./dist/dialog-context.js"
+    },
+    "./client-shim": {
+      "types": "./dist/client-shim.d.ts",
+      "import": "./dist/client-shim.js"
+    },
+    "./preload": {
+      "types": "./dist/preload.d.ts",
+      "import": "./dist/preload.js"
+    },
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "import": "./dist/dev.js"
+    },
+    "./dev-worker": {
+      "types": "./dist/dev-worker.d.ts",
+      "import": "./dist/dev-worker.js"
+    },
+    "./jsx/jsx-runtime": {
+      "types": "./dist/jsx/jsx-runtime/index.d.ts",
+      "import": "./dist/jsx/jsx-runtime/index.js"
+    },
+    "./jsx/jsx-dev-runtime": {
+      "types": "./dist/jsx/jsx-dev-runtime/index.d.ts",
+      "import": "./dist/jsx/jsx-dev-runtime/index.js"
+    },
+    "./async": {
+      "types": "./dist/async.d.ts",
+      "import": "./dist/async.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./test-render": {
+      "bun": "./src/test-render.ts"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/scripts.tsx ./src/portals.tsx ./src/portal-ssr.tsx ./src/dialog-context.tsx ./src/client-shim.ts ./src/preload.tsx ./src/dev.tsx ./src/dev-worker.ts ./src/jsx/jsx-runtime/index.ts ./src/jsx/jsx-dev-runtime/index.ts ./src/async.tsx ./src/utils.ts ./src/build.ts ./src/app.ts --root ./src --outdir ./dist --format esm --external hono --external @barefootjs/client --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "hono",
+    "jsx",
+    "barefoot",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/adapter-hono"
+  },
+  "peerDependencies": {
+    "@barefootjs/client": "workspace:*",
+    "@barefootjs/jsx": "workspace:*",
+    "@barefootjs/shared": "workspace:*",
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@barefootjs/adapter-tests": "workspace:*",
+    "@types/jsdom": "^27.0.0",
+    "hono": "^4.6.0",
+    "jsdom": "^27.3.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/__tests__/async.test.tsx

@@ -0,0 +1,106 @@
+/** @jsxImportSource hono/jsx */
+/**
+ * BfAsync Component Tests
+ *
+ * Verifies that BfAsync properly wraps Hono's Suspense
+ * for streaming SSR with BarefootJS components.
+ */
+import { describe, it, expect } from 'bun:test'
+import { renderToReadableStream } from 'hono/jsx/streaming'
+import type { HtmlEscapedString } from 'hono/utils/html'
+import { BfAsync } from '../async'
+
+async function collectStream(stream: ReadableStream): Promise<string[]> {
+  const chunks: string[] = []
+  const decoder = new TextDecoder()
+  for await (const chunk of stream as AsyncIterable<Uint8Array>) {
+    chunks.push(decoder.decode(chunk))
+  }
+  return chunks
+}
+
+describe('BfAsync', () => {
+  it('streams fallback then resolved content', async () => {
+    const AsyncContent = () => {
+      return new Promise<HtmlEscapedString>((resolve) =>
+        setTimeout(() => resolve(<div>Loaded!</div>), 10)
+      )
+    }
+
+    const stream = renderToReadableStream(
+      <BfAsync fallback={<p>Loading...</p>}>
+        <AsyncContent />
+      </BfAsync>
+    )
+
+    const chunks = await collectStream(stream)
+
+    // First chunk has fallback
+    expect(chunks[0]).toContain('Loading...')
+    // Later chunk has resolved content
+    const fullOutput = chunks.join('')
+    expect(fullOutput).toContain('Loaded!')
+  })
+
+  it('renders multiple async boundaries independently', async () => {
+    const SlowContent = ({ id }: { id: number }) => {
+      return new Promise<HtmlEscapedString>((resolve) =>
+        setTimeout(() => resolve(<span>Content {id}</span>), 10 * id)
+      )
+    }
+
+    const stream = renderToReadableStream(
+      <div>
+        <BfAsync fallback={<p>Loading 1...</p>}>
+          <SlowContent id={1} />
+        </BfAsync>
+        <BfAsync fallback={<p>Loading 2...</p>}>
+          <SlowContent id={2} />
+        </BfAsync>
+      </div>
+    )
+
+    const chunks = await collectStream(stream)
+    const fullOutput = chunks.join('')
+
+    expect(fullOutput).toContain('Content 1')
+    expect(fullOutput).toContain('Content 2')
+  })
+
+  it('preserves BarefootJS hydration markers in async content', async () => {
+    const AsyncComponent = () => {
+      return new Promise<HtmlEscapedString>((resolve) =>
+        setTimeout(() => resolve(
+          <div bf-s="Counter_abc" bf-p='{"count":0}'>0</div>
+        ), 10)
+      )
+    }
+
+    const stream = renderToReadableStream(
+      <BfAsync fallback={<p>Loading...</p>}>
+        <AsyncComponent />
+      </BfAsync>
+    )
+
+    const chunks = await collectStream(stream)
+    const fullOutput = chunks.join('')
+
+    expect(fullOutput).toContain('bf-s="Counter_abc"')
+    expect(fullOutput).toContain('bf-p=')
+  })
+
+  it('renders synchronous children without streaming', async () => {
+    const SyncContent = () => <div>Already here</div>
+
+    const stream = renderToReadableStream(
+      <BfAsync fallback={<p>Loading...</p>}>
+        <SyncContent />
+      </BfAsync>
+    )
+
+    const chunks = await collectStream(stream)
+
+    // Synchronous content should be in the first chunk (no fallback needed)
+    expect(chunks[0]).toContain('Already here')
+  })
+})

package/src/__tests__/bfscripts-entry-roots.test.tsx

@@ -0,0 +1,135 @@
+/** @jsxImportSource hono/jsx */
+/**
+ * BfScripts `entryRoots` prop (#1431).
+ *
+ * Background: `<BfScripts manifest base />` walks `stubDeps` only for
+ * components whose SSR template ran during the request (the
+ * `bfOutputScripts` set populated by `addScriptCollection`'s injected
+ * snippet). A page that renders a `'use client'` component via a
+ * manual `<script type="module">import "X.client.js"; render(root, "X", props)`
+ * bootstrap — instead of SSR'ing `<X />` — never lands `X` in
+ * `bfOutputScripts`. BfScripts has no root to walk, and `X`'s
+ * `stubDeps` (children reached only through the imperative
+ * `createComponent` stub rewrite, #1240) never ship as `<script>` tags.
+ *
+ * `entryRoots` lets the caller declare those manually-mounted entry
+ * components so their `stubDeps` get walked. The caller's own inline
+ * `<script type="module">` handles `X.client.js`, so `X` itself stays
+ * in the `excluded` set — only its deps get emitted.
+ *
+ * Real-world: piconic-ai/desk #86 — `DeskCanvasPage` skips SSR of
+ * `<DeskCanvas />` (its template body calls `useYjs()` / `fetch()` —
+ * fatal on Cloudflare Workers) and manually mounts via the inline
+ * script. Without `entryRoots`, `IssueCardNodeImpl.client.js` (reached
+ * via `DeskCanvas → IssueCardNode (.ts) → IssueCardNodeImpl (.tsx)`)
+ * doesn't ship, and the runtime renders the red `[IssueCardNodeImpl]`
+ * placeholder for every card.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { Hono } from 'hono'
+import { jsxRenderer } from 'hono/jsx-renderer'
+import { BfScripts } from '../scripts'
+import type { BarefootBuildManifest } from '../app'
+
+const MANIFEST: BarefootBuildManifest = {
+  __barefoot__: { clientJs: 'components/barefoot.js' },
+  'canvas/DeskCanvas': {
+    clientJs: 'components/canvas/DeskCanvas.client.js',
+    stubDeps: ['canvas/nodes/IssueCardNodeImpl'],
+  },
+  'canvas/nodes/IssueCardNodeImpl': {
+    clientJs: 'components/canvas/nodes/IssueCardNodeImpl.client.js',
+  },
+  'canvas/catalog/IssueCardCatalog': {
+    clientJs: 'components/canvas/catalog/IssueCardCatalog.client.js',
+    stubDeps: ['canvas/nodes/IssueCardNodeImpl'],
+  },
+}
+
+function mountApp(entryRoots?: string[]) {
+  const app = new Hono()
+  app.use(
+    '*',
+    jsxRenderer(({ children }) => (
+      <html lang="en">
+        <body>
+          {children}
+          <BfScripts manifest={MANIFEST} base="/static/components/" entryRoots={entryRoots} />
+        </body>
+      </html>
+    )),
+  )
+  app.get('/', (c) => c.render(<div id="canvas-root" />))
+  return app
+}
+
+describe('BfScripts entryRoots (#1431)', () => {
+  test('omitted entryRoots → manually-mounted components miss their stubDeps (baseline regression)', async () => {
+    const res = await mountApp().fetch(new Request('http://localhost/'))
+    const html = await res.text()
+    // DeskCanvas isn't in `bfOutputScripts` (no SSR), and we passed no
+    // entryRoots, so its stubDep IssueCardNodeImpl is NOT emitted.
+    expect(html).not.toContain('IssueCardNodeImpl.client.js')
+  })
+
+  test('entryRoots: ["canvas/DeskCanvas"] → walks its stubDeps even though it was not SSR-rendered', async () => {
+    const res = await mountApp(['canvas/DeskCanvas']).fetch(new Request('http://localhost/'))
+    const html = await res.text()
+    // The whole point of #1431: the manually-mounted root's stubDeps
+    // get emitted as `<script type="module" src=...>` tags.
+    expect(html).toContain('/static/components/canvas/nodes/IssueCardNodeImpl.client.js')
+  })
+
+  test('entryRoots does NOT emit a script for the root itself (caller already does that via the inline mount)', async () => {
+    const res = await mountApp(['canvas/DeskCanvas']).fetch(new Request('http://localhost/'))
+    const html = await res.text()
+    // The caller's own inline `<script type="module">import "DeskCanvas.client.js"`
+    // already loads the root; BfScripts must NOT add a duplicate
+    // `<script src=...DeskCanvas.client.js>` that would re-run hydration.
+    expect(html).not.toContain('/static/components/canvas/DeskCanvas.client.js')
+  })
+
+  test('multiple entryRoots are all walked', async () => {
+    const res = await mountApp(['canvas/DeskCanvas', 'canvas/catalog/IssueCardCatalog']).fetch(
+      new Request('http://localhost/'),
+    )
+    const html = await res.text()
+    // Both roots share the same stubDep; it must be emitted (once is fine
+    // because the underlying walker dedupes against `excluded`/`visited`).
+    const occurrences = html.match(/IssueCardNodeImpl\.client\.js/g) ?? []
+    expect(occurrences.length).toBe(1)
+  })
+
+  test('an entry name listed in BOTH outputSet and entryRoots is not double-emitted as a script tag', async () => {
+    // Simulate the case where the caller's manually-mounted root ALSO
+    // happens to be SSR'd elsewhere (unusual but legal). The script
+    // for the root itself stays out (the caller's inline mount handles
+    // it / outputSet excludes it), and the stubDep emits once.
+    const app = new Hono()
+    app.use(
+      '*',
+      jsxRenderer(({ children }) => (
+        <html lang="en">
+          <body>
+            {children}
+            <BfScripts manifest={MANIFEST} base="/static/components/" entryRoots={['canvas/DeskCanvas']} />
+          </body>
+        </html>
+      )),
+    )
+    app.get('/', (c) => {
+      // Simulate addScriptCollection having pushed DeskCanvas during SSR.
+      const set: Set<string> = c.get('bfOutputScripts') || new Set()
+      set.add('canvas/DeskCanvas')
+      c.set('bfOutputScripts', set)
+      return c.render(<div id="canvas-root" />)
+    })
+    const res = await app.fetch(new Request('http://localhost/'))
+    const html = await res.text()
+    const deskMatches = html.match(/DeskCanvas\.client\.js/g) ?? []
+    const implMatches = html.match(/IssueCardNodeImpl\.client\.js/g) ?? []
+    expect(deskMatches.length).toBe(0)
+    expect(implMatches.length).toBe(1)
+  })
+})

package/src/__tests__/build.test.ts

@@ -0,0 +1,299 @@
+import { describe, test, expect } from 'bun:test'
+import { addScriptCollection, createConfig, maskComments } from '../build'
+
+// ── addScriptCollection ──────────────────────────────────────────────
+
+describe('addScriptCollection', () => {
+  test('injects imports and script collector into exported function', () => {
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Counter(props: CounterProps) {
+  return (<div>hello</div>)
+}`
+
+    const result = addScriptCollection(input, 'Counter', 'Counter.client.js')
+
+    expect(result).toContain("import { useRequestContext } from 'hono/jsx-renderer'")
+    expect(result).toContain("import { Fragment } from 'hono/jsx'")
+    expect(result).toContain('__bfWrap')
+    expect(result).toContain('bfCollectedScripts')
+    expect(result).toContain("'Counter'")
+    expect(result).toContain('Counter.client.js')
+  })
+
+  test('preserves content when no import match', () => {
+    const input = 'const x = 1'
+    // Should not throw, returns unchanged or minimally modified
+    const result = addScriptCollection(input, 'Test', 'Test.client.js')
+    expect(result).toBeDefined()
+  })
+
+  test('uses custom scriptBasePath', () => {
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Counter() {
+  return (<div>hello</div>)
+}`
+
+    const result = addScriptCollection(input, 'Counter', 'Counter.client.js', '/assets/js/')
+    expect(result).toContain('/assets/js/barefoot.js')
+    expect(result).toContain('/assets/js/Counter.client.js')
+    expect(result).not.toContain('/static/components/')
+  })
+
+  test('normalizes scriptBasePath without trailing slash', () => {
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Counter() {
+  return (<div>hello</div>)
+}`
+
+    const result = addScriptCollection(input, 'Counter', 'Counter.client.js', '/assets/js')
+    expect(result).toContain('/assets/js/barefoot.js')
+    expect(result).toContain('/assets/js/Counter.client.js')
+  })
+
+  test('ignores `function PascalCase(` text inside JSDoc / inline comments (#1236)', () => {
+    // A docstring example previously triggered a bogus insertion when
+    // the function-pattern regex matched inside the comment, after
+    // which the paren counter walked into the wrong `{` and corrupted
+    // a real function further down.
+    const input = `import { jsx } from 'hono/jsx'
+
+export interface MyProps {
+  /**
+   * Example imperative signature for the docs:
+   *   function MyNode(this: HTMLElement, props): void
+   */
+  nodeTypes?: Record<string, unknown>
+}
+
+// also: function FakeFromLineComment(this: any) {} should not match
+
+export function Counter(props: MyProps) {
+  return (<div>hello</div>)
+}`
+
+    const result = addScriptCollection(input, 'Counter', 'Counter.client.js')
+
+    // The real Counter must be wrapped exactly once.
+    const collectorCount = (result.match(/let __bfInlineScripts/g) || []).length
+    expect(collectorCount).toBe(1)
+
+    // And the collector must land inside Counter's body, immediately after
+    // its opening brace — the same shape the destructured-params test
+    // above verifies. If the comment matches had fired, the collector
+    // would be misplaced inside the interface or the JSDoc.
+    const counterBodyMatch = result.match(/function Counter\(props: MyProps\)\s*\{/)
+    expect(counterBodyMatch).not.toBeNull()
+    if (counterBodyMatch) {
+      const after = result.slice(result.indexOf(counterBodyMatch[0]) + counterBodyMatch[0].length)
+      expect(after.trimStart().startsWith('let __bfInlineScripts')).toBe(true)
+    }
+  })
+
+  test('still finds function declarations after JSX text with apostrophes (#1236)', () => {
+    // Defensive: an unbalanced `'` inside JSX text content (e.g.
+    // `How's it going`) used to cause an over-aggressive string-mask
+    // to blank everything until the next stray `'`, hiding later
+    // function declarations from the regex. Keep apostrophe-containing
+    // JSX text unmasked so subsequent functions still get instrumented.
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Greeting() {
+  return (<div>Hey! How's it going?</div>)
+}
+
+export function Footer() {
+  return (<div>Bye</div>)
+}`
+
+    const result = addScriptCollection(input, 'page', 'page-abc.js')
+
+    // BOTH functions must be wrapped.
+    const collectorCount = (result.match(/let __bfInlineScripts/g) || []).length
+    expect(collectorCount).toBe(2)
+    expect(result).toMatch(/function Greeting\(\)\s*\{\s*\n?\s*let __bfInlineScripts/)
+    expect(result).toMatch(/function Footer\(\)\s*\{\s*\n?\s*let __bfInlineScripts/)
+  })
+
+  test('handles destructured params with arrow function defaults', () => {
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Textarea({ className = '', onInput = () => {}, onChange = () => {}, ...props }: TextareaProps) {
+  return (<textarea class={className} {...props} />)
+}`
+
+    const result = addScriptCollection(input, 'textarea', 'textarea-abc123.js')
+
+    // Script collector must be inside the Textarea function body, NOT inside a default param
+    expect(result).toContain('__bfInlineScripts')
+    expect(result).toContain('__bfWrap')
+
+    // Verify __bfInlineScripts is declared AFTER the function opening brace,
+    // not inside an arrow function default value
+    const funcBodyMatch = result.match(/\.\.\.props\s*\}\s*:\s*TextareaProps\)\s*\{/)
+    expect(funcBodyMatch).not.toBeNull()
+    // After the function body opening, the next thing should be the script collector
+    if (funcBodyMatch) {
+      const afterFuncBody = result.slice(result.indexOf(funcBodyMatch[0]) + funcBodyMatch[0].length)
+      expect(afterFuncBody.trimStart().startsWith('let __bfInlineScripts')).toBe(true)
+    }
+  })
+})
+
+// ── createConfig() factory ──────────────────────────────────────────
+
+describe('createConfig()', () => {
+  test('creates config with HonoAdapter', () => {
+    const config = createConfig()
+    expect(config.adapter.name).toBe('hono')
+  })
+
+  test('sets transformMarkedTemplate by default', () => {
+    const config = createConfig()
+    expect(typeof config.transformMarkedTemplate).toBe('function')
+  })
+
+  test('disables transformMarkedTemplate when scriptCollection is false', () => {
+    const config = createConfig({ scriptCollection: false })
+    expect(config.transformMarkedTemplate).toBeUndefined()
+  })
+
+  test('uses custom scriptBasePath in transformMarkedTemplate', () => {
+    const config = createConfig({ scriptBasePath: '/assets/js/' })
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Counter() {
+  return (<div>hello</div>)
+}`
+    const result = config.transformMarkedTemplate!(input, 'Counter', 'Counter.client.js')
+    expect(result).toContain('/assets/js/barefoot.js')
+    expect(result).toContain('/assets/js/Counter.client.js')
+    expect(result).not.toContain('/static/components/')
+  })
+
+  test('uses default scriptBasePath in transformMarkedTemplate', () => {
+    const config = createConfig()
+    const input = `import { jsx } from 'hono/jsx'
+
+export function Counter() {
+  return (<div>hello</div>)
+}`
+    const result = config.transformMarkedTemplate!(input, 'Counter', 'Counter.client.js')
+    expect(result).toContain('/static/components/barefoot.js')
+    expect(result).toContain('/static/components/Counter.client.js')
+  })
+
+  test('passes through build options', () => {
+    const config = createConfig({
+      components: ['src'],
+      outDir: 'build',
+      minify: true,
+      contentHash: true,
+    })
+    expect(config.components).toEqual(['src'])
+    expect(config.outDir).toBe('build')
+    expect(config.minify).toBe(true)
+    expect(config.contentHash).toBe(true)
+  })
+
+  test('passes through externals and externalsBasePath', () => {
+    const externals = { react: { url: 'https://cdn.example.com/react.js' } }
+    const config = createConfig({
+      externals,
+      externalsBasePath: '/cdn/',
+    })
+    expect(config.externals).toBe(externals)
+    expect(config.externalsBasePath).toBe('/cdn/')
+  })
+
+  test('externals and externalsBasePath default to undefined', () => {
+    const config = createConfig()
+    expect(config.externals).toBeUndefined()
+    expect(config.externalsBasePath).toBeUndefined()
+  })
+
+  test('passes through localImportPrefixes', () => {
+    const config = createConfig({ localImportPrefixes: ['@/', '@ui/'] })
+    expect(config.localImportPrefixes).toEqual(['@/', '@ui/'])
+  })
+
+  test('localImportPrefixes defaults to undefined', () => {
+    const config = createConfig()
+    expect(config.localImportPrefixes).toBeUndefined()
+  })
+})
+
+// ── maskComments ────────────────────────────────────────────────────
+
+describe('maskComments', () => {
+  test('preserves length and newlines so indices stay valid in the original', () => {
+    const src = '/* foo */ x // bar\ny\n/* multi\nline */ z'
+    const masked = maskComments(src)
+    expect(masked).toHaveLength(src.length)
+    // Every newline position in the original is preserved in the masked
+    // copy, so line counts (and therefore line:column error reporting
+    // from downstream tools) line up.
+    const newlinePositions = (s: string) => [...s].flatMap((c, i) => c === '\n' ? [i] : [])
+    expect(newlinePositions(masked)).toEqual(newlinePositions(src))
+  })
+
+  test('blanks JSDoc / block comments including any quotes inside', () => {
+    const comment = "/** has 'apostrophe' inside */"
+    const tail = ' const x = 1'
+    const src = comment + tail
+    const masked = maskComments(src)
+    // The whole `/** ... */` is replaced with spaces; the apostrophes
+    // inside cannot re-open as strings later.
+    expect(masked).toBe(' '.repeat(comment.length) + tail)
+  })
+
+  test('blanks `//` line comments up to (but not including) the newline', () => {
+    const comment = '// ignored'
+    const tail = '\nconst x = 1'
+    const src = comment + tail
+    const masked = maskComments(src)
+    expect(masked).toBe(' '.repeat(comment.length) + tail)
+  })
+
+  test('handles unclosed block comment by masking through end of input', () => {
+    const src = 'a /* never closed\nfunction Real() {}'
+    const masked = maskComments(src)
+    // Without `*/`, the masker blanks to EOF. `function Real()` is
+    // hidden — this matches the JS lexer's behaviour for unterminated
+    // comments and is the conservative thing to do for the
+    // function-pattern regex.
+    expect(masked.startsWith('a ')).toBe(true)
+    expect(masked).not.toContain('function Real')
+    expect(masked).toHaveLength(src.length)
+  })
+
+  test('leaves comment-free code untouched (no false positives on JSX text)', () => {
+    // Plain code with no comment delimiters round-trips identically.
+    // JSX text with apostrophes (`How's`) is the hot path: a
+    // string-aware masker would treat the `'` as an open quote and
+    // blank the rest of the file, hiding later function declarations
+    // (#1236 follow-up).
+    const src = `export function Greeting() {\n  return (<div>Hey! How's it going?</div>)\n}\nexport function Footer() {}`
+    expect(maskComments(src)).toBe(src)
+  })
+
+  test('KNOWN LIMITATION: `//` inside a string is still treated as a line comment', () => {
+    // Documented in `maskComments` jsdoc: this helper does not track
+    // string boundaries, so a `//` appearing inside a string literal
+    // is still treated as a comment delimiter. SSR template output
+    // (the only current caller) does not produce such cases, so the
+    // simpler implementation is acceptable. If a future caller can
+    // produce them, swap in a real lexer — this test will start to
+    // fail and force the conversation.
+    const prefix = `const u = "https:`
+    const blanked = `//example.com" ; const x = 1`
+    const src = prefix + blanked
+    const masked = maskComments(src)
+    // The `//` in `https://` is treated as a line-comment delimiter
+    // and the rest of the line gets blanked.
+    expect(masked).toBe(prefix + ' '.repeat(blanked.length))
+    expect(masked).toHaveLength(src.length)
+  })
+})