@pyreon/vite-plugin 0.23.0 → 0.24.0

package/src/index.ts

@@ -134,6 +134,31 @@ export interface PyreonPluginOptions {
    */
   islands?: boolean
 
+  /**
+   * **LPIH auto-bridge** — zero-config Live Program Inlay Hints in dev.
+   *
+   * When `true` (the default in dev), the plugin auto-wires the LPIH
+   * cache file: the browser-side activates devtools + polls fire data
+   * every `intervalMs` (250ms default), and the dev-server middleware
+   * receives the POST + writes `<project-root>/.pyreon-lpih.json` using
+   * the atomic-rename pattern from `@pyreon/reactivity/lpih`. The LSP
+   * (`pyreon-lint --lsp`) auto-discovers that file, so the end-to-end
+   * "save file → see fire counts" loop needs ZERO user wiring.
+   *
+   * Set to `false` to opt out (e.g. if you're wiring `startLpihPolling()`
+   * yourself from a non-browser runtime, or you want LPIH off entirely).
+   * Pass an object to override the interval or the cache-file path.
+   *
+   * Build-only consumer: production builds skip injection entirely.
+   *
+   * @example
+   * pyreon({ lpih: true })                          // default in dev
+   * pyreon({ lpih: false })                         // opt out
+   * pyreon({ lpih: { intervalMs: 500 } })           // slower poll
+   * pyreon({ lpih: { cachePath: '/tmp/x.json' } })  // custom path
+   */
+  lpih?: boolean | PyreonLpihOptions
+
   /**
    * P0 — opt-in compile-time rocketstyle wrapper collapse. `true` uses
    * the default provider/theme/mode wiring (PyreonUI + theme +
@@ -174,6 +199,26 @@ export interface PyreonCollapseOptions {
   mode?: { name: string; source: string }
 }
 
+export interface PyreonLpihOptions {
+  /**
+   * Poll interval in milliseconds. The browser-side bridge reads
+   * `getFireSummaries()` and POSTs every `intervalMs` to the dev-server
+   * middleware. Default 250ms — matches the LSP-debounce window so
+   * editor hints settle within one frame of the typical save→hint cycle.
+   *
+   * Lower values (e.g. 100ms) trade dev-server CPU for snappier hints;
+   * higher values (1000ms) reduce overhead for slow machines.
+   */
+  intervalMs?: number
+  /**
+   * Cache-file path override. Defaults to
+   * `<projectRoot>/.pyreon-lpih.json` — the convention the LSP auto-
+   * discovers (R2, #777). Override only if you need a non-default
+   * location (shared mount, custom workspace layout).
+   */
+  cachePath?: string
+}
+
 // ── Compat alias maps ─────────────────────────────────────────────────────────
 
 const COMPAT_ALIASES: Record<CompatFramework, Record<string, string>> = {
@@ -336,6 +381,15 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
   // you have a specific reason.
   const islandsEnabled = options?.islands !== false
 
+  // ── LPIH auto-bridge config ──────────────────────────────────────────────
+  // Default `true` (zero-config Live Program Inlay Hints in dev). Set to
+  // `false` to opt out. Object form overrides interval / cache path.
+  const lpihOpt = options?.lpih
+  const lpihEnabled = lpihOpt !== false
+  const lpihUserCfg: PyreonLpihOptions =
+    lpihOpt && lpihOpt !== true ? lpihOpt : {}
+  const lpihIntervalMs = lpihUserCfg.intervalMs ?? 250
+
   // ── P0 rocketstyle-collapse config (opt-in) ───────────────────────────────
   const collapseOpt = options?.collapse
   const collapseEnabled = collapseOpt === true || (collapseOpt != null && collapseOpt !== false)
@@ -748,8 +802,10 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       // ── Dev-only transforms ────────────────────────────────────────────
       if (!isBuild) {
         output = injectHmr(output, id)
-        // Inject debug names for signal() calls not rewritten by HMR
-        output = injectSignalNames(output)
+        // Inject debug names + LPIH source locations for signal() calls
+        // not rewritten by HMR. `id` is Vite's resolved module path —
+        // the same path the runtime would have parsed from new Error().
+        output = injectSignalNames(output, id)
       }
 
       // R12: surface the compiler's V3 source map so stack traces /
@@ -777,6 +833,14 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
         }
       })
 
+      // LPIH auto-bridge — accepts POST /__pyreon_lpih__ from the browser
+      // client and atomically writes the cache file the LSP auto-discovers.
+      // Registered BEFORE the SSR middleware so it short-circuits and never
+      // falls through to handleSsrRequest.
+      if (lpihEnabled) {
+        registerLpihMiddleware(server, projectRoot, lpihUserCfg)
+      }
+
       if (!ssrConfig) return
 
       // Return a function so the middleware runs AFTER Vite's built-in middleware
@@ -796,6 +860,18 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
         })
       }
     },
+
+    // ── LPIH auto-bridge client injection ────────────────────────────────────
+    transformIndexHtml(html: string): string | undefined {
+      if (isBuild || !lpihEnabled) return undefined
+      // Inject a tiny <script type="module"> that activates devtools + polls
+      // getFireSummaries() and POSTs to /__pyreon_lpih__. The dev server
+      // middleware (above) writes the body to <projectRoot>/.pyreon-lpih.json
+      // using @pyreon/reactivity's atomic-rename pattern. The LSP
+      // auto-discovers that file (R2, #777) so the user wires NOTHING.
+      const script = buildLpihClientScript(lpihIntervalMs)
+      return html.replace('</head>', `${script}\n</head>`)
+    },
   }
 }
 
@@ -854,6 +930,186 @@ function generateProjectContext(root: string): void {
   }
 }
 
+// ── LPIH auto-bridge helpers ───────────────────────────────────────────────
+
+/**
+ * Resolve the LPIH cache-file path for a given project root. Matches the
+ * convention `@pyreon/reactivity/lpih`'s `getDefaultLpihCachePath()` uses
+ * AND the LSP auto-discovers (R2, #777): `<projectRoot>/.pyreon-lpih.json`.
+ *
+ * @internal — exported for tests.
+ */
+export function resolveLpihCachePath(projectRoot: string): string {
+  return pathJoin(projectRoot, '.pyreon-lpih.json')
+}
+
+/**
+ * Register the LPIH dev-server middleware on a Vite server. Extracted from
+ * `configureServer` so the `cachePath` option reference lives at module
+ * scope (top-level helper) rather than inside the plugin's inline body —
+ * keeps `scripts/audit-types.ts` happy regardless of how its comment-
+ * stripping handles the long inline `configureServer` block.
+ *
+ * @internal — exported for tests.
+ */
+export function registerLpihMiddleware(
+  server: ViteDevServer,
+  projectRoot: string,
+  userCfg: PyreonLpihOptions,
+): void {
+  const cachePath = userCfg.cachePath ?? resolveLpihCachePath(projectRoot)
+  server.middlewares.use('/__pyreon_lpih__', (req, res) => {
+    if (req.method !== 'POST') {
+      res.statusCode = 405
+      res.end('Method Not Allowed')
+      return
+    }
+    let body = ''
+    req.on('data', (chunk: Buffer | string) => {
+      body += chunk.toString()
+      // Defensive cap — fire payloads are tiny (a few KB at most);
+      // anything larger is malicious or buggy. Drop the request.
+      if (body.length > 1024 * 1024) {
+        res.statusCode = 413
+        res.end('Payload Too Large')
+        req.destroy()
+      }
+    })
+    req.on('end', () => {
+      void writeLpihCacheFile(cachePath, body)
+        .then(() => {
+          res.statusCode = 204
+          res.end()
+        })
+        .catch((err: unknown) => {
+          // Don't crash the dev server — log + return 500 so the
+          // browser-side bridge can back off + retry next interval.
+          // oxlint-disable-next-line no-console
+          console.warn(
+            '[pyreon] LPIH cache write failed:',
+            err instanceof Error ? err.message : err,
+          )
+          res.statusCode = 500
+          res.end('LPIH cache write failed')
+        })
+    })
+  })
+}
+
+let _lpihSeq = 0
+
+/**
+ * Atomically write a LPIH cache file (tmp + rename), mirroring the
+ * `@pyreon/reactivity/lpih:writeLpihCache` implementation. The payload
+ * comes pre-serialized from the browser-side bridge — we validate the
+ * outer shape (`{ fires: [...] }`) and reject malformed bodies to stop a
+ * buggy client from corrupting the file the LSP reads.
+ *
+ * @internal — exported for tests.
+ */
+export async function writeLpihCacheFile(path: string, body: string): Promise<void> {
+  // Validate shape — must be a JSON object with `fires: array`. We re-
+  // serialize so the on-disk format is stable regardless of how the
+  // browser-side bridge encodes it.
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch {
+    throw new Error('LPIH bridge: payload is not valid JSON')
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== 'object' ||
+    !Array.isArray((parsed as { fires?: unknown }).fires)
+  ) {
+    throw new Error('LPIH bridge: payload is missing `fires` array')
+  }
+  const fs = await import('node:fs/promises')
+  const pid = typeof process !== 'undefined' && 'pid' in process ? process.pid : 0
+  const tmp = `${path}.tmp.${pid}.${++_lpihSeq}`
+  // Single try/catch covering BOTH writeFile AND rename. The previous
+  // shape only guarded the rename — if `fs.writeFile` itself threw (disk
+  // full, EIO, EACCES, transient FS error), the partial tmp file leaked
+  // on disk with a unique PID+seq name (so no conflict, but it accumulated
+  // forever). Audit caught this in the LPIH followups round.
+  try {
+    await fs.writeFile(tmp, JSON.stringify(parsed), 'utf8')
+    await fs.rename(tmp, path)
+  } catch (err) {
+    // Best-effort cleanup; original error is more useful than unlink's.
+    // Covers BOTH the writeFile-failed (tmp may not exist) and the
+    // rename-failed (tmp exists, rename didn't move it) cases —
+    // `fs.unlink` of a non-existent file throws ENOENT, which we swallow.
+    try {
+      await fs.unlink(tmp)
+    } catch {
+      /* swallow — original error is the user-facing one */
+    }
+    throw err
+  }
+}
+
+/**
+ * Build the `<script type="module">` body injected into the HTML head.
+ * The script imports devtools activation + `getFireSummaries` from
+ * `@pyreon/reactivity`, sets up a `setInterval` that POSTs every
+ * `intervalMs` ms, and registers a `beforeunload` cleanup so the timer
+ * doesn't outlive the page.
+ *
+ * Browser bundlers serve `@pyreon/reactivity` from the workspace via
+ * Vite's normal module resolution — no virtual module needed.
+ *
+ * @internal — exported for tests.
+ */
+export function buildLpihClientScript(intervalMs: number): string {
+  // Note: the script body is intentionally compact — the goal is zero
+  // visible payload in DevTools "Sources" while still being readable
+  // when someone DOES go looking. `JSON.stringify` for `intervalMs` is
+  // defense against `__proto__` / NaN / non-finite values reaching the
+  // emitted JS as a literal.
+  // CRITICAL — top-level await on the dynamic import. `<script type="module">`
+  // tags execute in document order with `defer` semantics; the head-injected
+  // LPIH script's body MUST fully evaluate (including this await) BEFORE the
+  // body-injected app entry's module body runs. Otherwise activateReactiveDevtools()
+  // would land AFTER the app has already created its module-scope signals,
+  // and `_rdRegister` (gated on `if (!_active) return undefined`) would skip
+  // them entirely — making the most common signal shape (top-of-file `const x = signal(0)`)
+  // invisible to LPIH. With the `await`, the LPIH module doesn't complete
+  // until activation finishes; the app's entry waits its turn.
+  return `<script type="module">
+  // Pyreon LPIH auto-bridge — POSTs fire summaries to /__pyreon_lpih__
+  // so the LSP (pyreon-lint --lsp) sees live fire data. Dev-only.
+  const __px = await import('@pyreon/reactivity').catch(() => null)
+  if (__px) {
+    __px.activateReactiveDevtools()
+    const __pxGet = __px.getFireSummaries
+    const __pxInterval = ${JSON.stringify(intervalMs)}
+    const __pxPost = () => {
+      const summaries = __pxGet()
+      const payload = JSON.stringify({
+        fires: summaries.map((s) => ({
+          file: s.loc.file,
+          line: s.loc.line,
+          count: s.count,
+          kind: s.kind,
+          lastFire: s.lastFire,
+          rate1s: s.rate1s,
+        })),
+      })
+      fetch('/__pyreon_lpih__', { method: 'POST', body: payload, headers: { 'content-type': 'application/json' } }).catch(() => {
+        // Dev-server might be restarting; swallow + retry next interval.
+      })
+    }
+    const __pxId = setInterval(__pxPost, __pxInterval)
+    window.addEventListener('beforeunload', () => clearInterval(__pxId))
+  }
+  // If __px is null, @pyreon/reactivity isn't in the dep graph — stay silent,
+  // LPIH is opt-in via the runtime API too. The dynamic-import catch returns
+  // null instead of letting the rejection bubble so consumers without the
+  // package don't see a console error.
+</script>`
+}
+
 // ── HMR injection ─────────────────────────────────────────────────────────────
 
 /**
@@ -981,37 +1237,312 @@ function hasMultipleArgs(args: string): boolean {
 }
 
 /**
- * Inject `{ name: "varName" }` into signal() calls that don't already have
+ * Inject `{ name?, __sourceLocation: { file, line, col } }` into
+ * `signal()` / `computed()` / `effect()` calls that don't already have
  * an options argument. Only runs in dev mode for debugging/devtools.
  *
- * `const count = signal(0)` → `const count = signal(0, { name: "count" })`
+ * Three forms covered:
+ *
+ *   `const count = signal(0)` →
+ *     `const count = signal(0, { name: "count", __sourceLocation: {...} })`
+ *
+ *   `const doubled = computed(() => count() * 2)` →
+ *     `const doubled = computed(() => count() * 2, { name: "doubled", __sourceLocation: {...} })`
+ *
+ *   `effect(() => console.log(count()))` →
+ *     `effect(() => console.log(count()), { __sourceLocation: {...} })`
+ *     (no `name` — anonymous effects have no binding to derive from)
  *
  * Module-scope signals rewritten to __hmr_signal() are naturally skipped
  * because the regex matches `signal(` not `__hmr_signal(`.
+ *
+ * **LPIH integration**: `__sourceLocation` is consumed by
+ * `@pyreon/reactivity`'s `signal()` / `computed()` / `effect()` to skip
+ * the `new Error().stack` capture in `_rdRegister` — saves ~2.2µs per
+ * creation when devtools is active. The injected literal is byte-for-byte
+ * the same info the runtime would have parsed from the stack, so behavior
+ * is identical except no stack-parse cost.
+ *
+ * **Anonymous-effect detection**: `effect(` can also appear as a property
+ * access (`obj.effect(...)`), a longer identifier (`sideEffect(...)`), or
+ * a previously-injected call (`effect(fn, { ... })`). The unbound-effect
+ * pass guards against all three:
+ *   - preceded by NOT `[A-Za-z0-9_$.]` (so `.effect`/`sideEffect` skip)
+ *   - args do NOT already contain a 2nd arg (`hasMultipleArgs` check)
+ *
+ * @param code - source text
+ * @param moduleId - the file path to embed in the injected `__sourceLocation`.
+ *                   Vite passes the resolved module ID (absolute path).
  */
-function injectSignalNames(code: string): string {
-  const re = /(?:const|let)\s+(\w+)\s*=\s*signal\(/gm
-  const matches: { start: number; end: number; name: string; args: string }[] = []
+function injectSignalNames(code: string, moduleId: string): string {
+  // Pre-pass: mask string-literal, template-literal, and comment regions
+  // so the regexes below don't false-fire on `effect(` inside docstrings,
+  // help-text strings, JS-as-text test fixtures, or comments mentioning
+  // reactive primitives. The regex runs against the MASKED code (positions
+  // are preserved), so a match's index points at real code; args extraction
+  // pulls from the ORIGINAL code for accurate output.
+  //
+  // Without this, user code like `const docs = \`effect(() => x)\`` would
+  // get `, { __sourceLocation: ... }` injected INSIDE the template literal,
+  // corrupting the help-text content at runtime.
+  const masked = _maskStringsAndComments(code)
+
+  // Pass 1: bound forms — `const X = (signal|computed|effect)(…)`.
+  // Extract `X` as the debug name + the reactive primitive kind.
+  const reBound = /(?:const|let)\s+(\w+)\s*=\s*(signal|computed|effect)\(/gm
+  // Pass 2: unbound effect — `effect(() => …)` at statement position,
+  // not following a member-access (.) or identifier char ($_a-zA-Z0-9).
+  // Reactive primitives other than `effect` are rare without binding,
+  // so we skip the bare `signal(` / `computed(` form to stay conservative.
+  const reUnboundEffect = /(?<![\w$.])effect\(/gm
+
+  type Match = {
+    start: number
+    end: number
+    name: string | null
+    args: string
+    matchIdx: number
+  }
+  const matches: Match[] = []
+  // Track call positions covered by pass 1 so pass 2 can skip them.
+  const covered = new Set<number>()
 
-  let m: RegExpExecArray | null = re.exec(code)
+  let m: RegExpExecArray | null = reBound.exec(masked)
   while (m !== null) {
     const argsStart = m.index + m[0].length
     const args = extractBalancedArgs(code, argsStart)
     if (args !== null && !hasMultipleArgs(args)) {
-      matches.push({ start: argsStart, end: argsStart + args.length, name: m[1] ?? '', args })
+      matches.push({
+        start: argsStart,
+        end: argsStart + args.length,
+        name: m[1] ?? '',
+        args,
+        matchIdx: m.index,
+      })
+      // Mark the `effect(`/`signal(`/`computed(` token start so the
+      // unbound-effect pass doesn't double-process it.
+      const tokStart = m.index + m[0].length - (m[2]?.length ?? 0) - 1
+      covered.add(tokStart)
+    }
+    m = reBound.exec(masked)
+  }
+  reBound.lastIndex = 0
+
+  m = reUnboundEffect.exec(masked)
+  while (m !== null) {
+    if (!covered.has(m.index)) {
+      const argsStart = m.index + m[0].length
+      const args = extractBalancedArgs(code, argsStart)
+      if (args !== null && !hasMultipleArgs(args)) {
+        matches.push({
+          start: argsStart,
+          end: argsStart + args.length,
+          name: null,
+          args,
+          matchIdx: m.index,
+        })
+      }
     }
-    m = re.exec(code)
+    m = reUnboundEffect.exec(masked)
   }
-  re.lastIndex = 0
+  reUnboundEffect.lastIndex = 0
+
+  if (matches.length === 0) return code
+
+  // Sort by descending start so back-to-front rewriting doesn't shift
+  // later indices (each splice leaves earlier offsets unchanged).
+  matches.sort((a, b) => b.start - a.start)
+
+  // Pre-compute line offsets ONCE — avoids O(N²) when many calls share
+  // a file. Each lookup becomes O(log N) via binary search.
+  const lineStarts = _computeLineStarts(code)
 
   let output = code
-  for (let i = matches.length - 1; i >= 0; i--) {
-    const { start, end, name, args } = matches[i] as (typeof matches)[number]
-    output = `${output.slice(0, start)}${args}, { name: ${JSON.stringify(name)} }${output.slice(end)}`
+  for (let i = 0; i < matches.length; i++) {
+    const { start, end, name, args, matchIdx } = matches[i] as Match
+    const { line, col } = _offsetToLineCol(matchIdx, lineStarts)
+    const locLiteral = `__sourceLocation: { file: ${JSON.stringify(moduleId)}, line: ${line}, col: ${col} }`
+    const inner = name !== null
+      ? `name: ${JSON.stringify(name)}, ${locLiteral}`
+      : locLiteral
+    output = `${output.slice(0, start)}${args}, { ${inner} }${output.slice(end)}`
   }
   return output
 }
 
+/**
+ * Mask string-literal / template-literal / comment regions in `code` by
+ * replacing their content with spaces. Returns a SAME-LENGTH string so
+ * regex match positions in the masked version line up with the original.
+ *
+ * Used by `injectSignalNames` to skip false-positive matches against
+ * reactive-primitive names that appear inside strings or comments. Without
+ * masking, a user's `const docs = \`effect(() => x)\`` template literal
+ * would get `, { __sourceLocation: ... }` injected INSIDE the string,
+ * corrupting runtime values.
+ *
+ * Handles:
+ *   - `"..."` / `'...'` strings (escape-aware)
+ *   - `` `...` `` template literals; interpolations `${...}` are KEPT as
+ *     code (their content can contain real `signal()` calls worth catching)
+ *   - `// ...` line comments
+ *   - `/* ... *\/` block comments
+ *
+ * Regex literals (`/foo/g`) are NOT special-cased — they're rare and the
+ * downstream extractBalancedArgs handles unmatched parens by returning null.
+ *
+ * @internal — exported for tests.
+ */
+export function _maskStringsAndComments(code: string): string {
+  const out: string[] = []
+  let i = 0
+  const n = code.length
+  while (i < n) {
+    const c = code[i]
+    const c1 = code[i + 1]
+
+    // Line comment `// ...`
+    if (c === '/' && c1 === '/') {
+      while (i < n && code[i] !== '\n') {
+        out.push(' ')
+        i++
+      }
+      continue
+    }
+    // Block comment `/* ... */`
+    if (c === '/' && c1 === '*') {
+      out.push(' ', ' ')
+      i += 2
+      while (i < n) {
+        if (code[i] === '*' && code[i + 1] === '/') {
+          out.push(' ', ' ')
+          i += 2
+          break
+        }
+        // Preserve newlines so line numbers don't shift
+        out.push(code[i] === '\n' ? '\n' : ' ')
+        i++
+      }
+      continue
+    }
+    // String literal "..." or '...'
+    if (c === '"' || c === "'") {
+      const quote = c
+      out.push(' ')
+      i++
+      while (i < n && code[i] !== quote) {
+        // Escape sequence — skip the next char too (handles `\"`, `\\`, etc.)
+        if (code[i] === '\\' && i + 1 < n) {
+          // Preserve a newline (line-continuation `\<LF>`) as a newline.
+          out.push(' ', code[i + 1] === '\n' ? '\n' : ' ')
+          i += 2
+          continue
+        }
+        // Unterminated string (legacy parsers stop at newline) — break
+        if (code[i] === '\n') break
+        out.push(' ')
+        i++
+      }
+      if (i < n && code[i] === quote) {
+        out.push(' ')
+        i++
+      }
+      continue
+    }
+    // Template literal `...` — preserve `${...}` interpolations as code
+    if (c === '`') {
+      out.push(' ')
+      i++
+      while (i < n && code[i] !== '`') {
+        if (code[i] === '\\' && i + 1 < n) {
+          out.push(' ', code[i + 1] === '\n' ? '\n' : ' ')
+          i += 2
+          continue
+        }
+        // `${...}` — keep the interpolation body as code (with nested
+        // brace tracking so we find the matching `}`).
+        if (code[i] === '$' && code[i + 1] === '{') {
+          out.push(' ', ' ')
+          i += 2
+          let depth = 1
+          while (i < n && depth > 0) {
+            if (code[i] === '{') {
+              depth++
+              out.push(code[i] ?? ' ')
+              i++
+              continue
+            }
+            if (code[i] === '}') {
+              depth--
+              if (depth === 0) {
+                out.push(' ')
+                i++
+                break
+              }
+              out.push(code[i] ?? ' ')
+              i++
+              continue
+            }
+            // Inside `${}` — pass through as code (might contain `signal(` etc).
+            out.push(code[i] ?? ' ')
+            i++
+          }
+          continue
+        }
+        // Preserve newlines so line numbers don't shift.
+        out.push(code[i] === '\n' ? '\n' : ' ')
+        i++
+      }
+      if (i < n && code[i] === '`') {
+        out.push(' ')
+        i++
+      }
+      continue
+    }
+    out.push(c ?? '')
+    i++
+  }
+  return out.join('')
+}
+
+/**
+ * Compute the 0-indexed character offset for the start of each line.
+ * `lineStarts[i]` is the offset of the FIRST character on line i+1
+ * (1-based, so `lineStarts[0]` = offset 0 = line 1).
+ *
+ * @internal — exported for tests.
+ */
+export function _computeLineStarts(code: string): number[] {
+  const starts: number[] = [0]
+  for (let i = 0; i < code.length; i++) {
+    if (code.charCodeAt(i) === 10) starts.push(i + 1) // \n
+  }
+  return starts
+}
+
+/**
+ * Convert a 0-indexed offset to `{ line: 1-based, col: 1-based }` using a
+ * pre-computed line-starts array. Binary search → O(log N) per lookup.
+ *
+ * @internal — exported for tests.
+ */
+export function _offsetToLineCol(
+  offset: number,
+  lineStarts: number[],
+): { line: number; col: number } {
+  // Binary search for the largest lineStarts[i] <= offset.
+  let lo = 0
+  let hi = lineStarts.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >>> 1
+    const v = lineStarts[mid]
+    if (v !== undefined && v <= offset) lo = mid
+    else hi = mid - 1
+  }
+  const lineStart = lineStarts[lo] ?? 0
+  return { line: lo + 1, col: offset - lineStart + 1 }
+}
+
 function injectHmr(code: string, moduleId: string): string {
   const hasSignals = SIGNAL_PREFIX_RE.test(code)
   SIGNAL_PREFIX_RE.lastIndex = 0

package/src/tests/dev-server.test.ts

@@ -54,7 +54,11 @@ afterEach(() => {
 })
 
 function bootstrap(opts?: PyreonPluginOptions) {
-  const plugin = pyreonPlugin(opts)
+  // Default `lpih: false` — these tests cover the SSR / watcher / debounce
+  // surface; LPIH auto-bridge adds its own middleware whose presence would
+  // change the `middlewares.use` call count + first-element shape. Tests
+  // that specifically exercise LPIH live in `lpih-auto-bridge.test.ts`.
+  const plugin = pyreonPlugin({ lpih: false, ...opts })
   ;(plugin.config as unknown as ConfigHook)({ root }, { command: 'serve' })
   return plugin
 }