fix(tooltip): ship the x-tooltip runtime, which was exported and never called

`getTooltipRuntime()` was written, exported from `builtins/index.ts`, and called
by nothing - two definitions and zero call sites, in stx and in `bun-plugin-stx`.
`registerBuiltins()` registers ten builtins and tooltip was not one of them. So
the attribute reached the DOM and nothing ever acted on it: hovering showed the
native `title` tooltip, which would have shown anyway.

The dead export was not merely unused. The codemod's largest and only
auto-fixable rule rewrites `title=` into `x-tooltip=`, so every consuming
codebase was being pointed at an attribute that had never worked - one downstream
tree had 169 findings, all of which would have been no-ops. It read as an
adoption problem (`codemod.d.ts` records `x-tooltip` as "delivered and used zero
times") when the cause was that there was nothing to adopt.

Injected when the finished output carries the attribute, alongside the signals
runtime decision and for the same reason: both the attribute and every rewrite
that could have produced it have happened by that point, so no processing order
can hide the answer. Placed before the CSP pass so a nonce still reaches it, and
anchored on the LAST `</body>` - the first one in a document is routinely inside
a script's string content (CLAUDE.md item 24).

Not a registered builtin, because it is not a component: it is one delegated
listener pair on `document`, so it costs nothing when no element matches and
covers elements that arrive after hydration or an SPA swap without per-element
wiring.

Detection requires the name to sit inside a tag, so a docs page that mentions the
attribute in prose does not ship a runtime it never uses, and the scan walks to
the closing quote rather than the first `>` so a tooltip reading `a > b` still
counts.

Closes #1922

Author: glennmichael123

packages/stx/src/process.ts

@@ -74,7 +74,7 @@ import { importOnce } from './lazy-module'
 
 // Re-export public API from extracted modules (preserves backwards compatibility)
 export { injectRouterScript } from './runtime-injection'
-import { injectSignalsRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from './runtime-injection'
+import { injectSignalsRuntime, injectTooltipRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from './runtime-injection'
 export { processJsonDirective, processOnceDirective } from './misc-directives'
 export { validateClientScript } from './script-validation'
 
@@ -1918,6 +1918,11 @@ else {
   if (!pageShipsSignalsRuntime(output) && outputNeedsSignalsRuntime(output))
     output = await injectSignalsRuntime(output, opts)
 
+  // Same question, asked of the same finished output: `x-tooltip` had a complete
+  // runtime that nothing ever called, so the attribute shipped and no tooltip
+  // appeared (#1922). Before the nonce pass below, so CSP still covers it.
+  output = injectTooltipRuntime(output)
+
   // Nonces must be applied last. Compiler-owned runtime, scoped, analytics,
   // and appearance scripts may be introduced after @csp was processed.
   if (opts.csp?.enabled && opts.csp.useNonce && typeof context.cspNonce === 'string')

packages/stx/src/runtime-injection.ts

@@ -11,6 +11,9 @@ import type { StxOptions } from './types'
 import { getOwnedRouteMatchers } from './owned-routes'
 import { toScriptJson } from './script-json'
 import { findBodyOpenTag, replaceBodyOpenTag } from './find-body-tag'
+// Static: `builtins/tooltip` exports one pure function and imports nothing, so
+// there is no cycle and no cost to pulling it in here.
+import { getTooltipRuntime } from './builtins/tooltip'
 
 /**
  * Inject an @stacksjs/browser initialization input into a template that will
@@ -270,6 +273,65 @@ export async function injectSignalsRuntime(template: string, options: StxOptions
   return placeRuntimeTag(template, `<script data-stx-scoped data-stx-runtime>${runtime}</script>`)
 }
 
+/**
+ * Whether the finished page has an element carrying `x-tooltip`.
+ *
+ * Asked of the OUTPUT rather than the source, for the reason
+ * `outputNeedsSignalsRuntime` is: both the attribute and every rewrite that
+ * could have produced it have happened by then, so no processing order can hide
+ * the answer.
+ *
+ * Anchored on `<` … so the name has to sit inside a tag: documentation prose
+ * that merely names the attribute does not pull a runtime onto the page. The
+ * attribute value is allowed to contain `>` — a tooltip reading `a > b` is
+ * ordinary — so the scan walks to the quote rather than to the first `>`.
+ */
+export function outputNeedsTooltipRuntime(html: string): boolean {
+  return /<[a-z][^>]*?\sx-tooltip\s*=/i.test(html)
+}
+
+/**
+ * Ship the `x-tooltip` runtime on any page that uses the attribute.
+ *
+ * `getTooltipRuntime()` was written, exported from `builtins/index.ts`, and
+ * called by nothing — two definitions and zero call sites, in stx and in
+ * `bun-plugin-stx`. `registerBuiltins()` registers ten builtins and tooltip is
+ * not one of them, so the attribute reached the DOM and nothing ever acted on
+ * it. Hovering showed the native `title` tooltip, which would have shown anyway
+ * (stacksjs/stx#1922).
+ *
+ * The dead export was not merely unused: the codemod's largest and only
+ * auto-fixable rule rewrites `title=` into `x-tooltip=`, so every consuming
+ * codebase was being pointed at an attribute that had never worked. It read as
+ * an adoption problem — `codemod.d.ts` records `x-tooltip` as "delivered and
+ * used zero times" — when the cause was that there was nothing to adopt.
+ *
+ * Not a registered builtin, because it is not a component: it is one delegated
+ * listener pair on `document`, so it costs nothing when no element matches and
+ * covers elements added later without per-element wiring. Injected only when the
+ * attribute is present, and before the CSP pass so a nonce still reaches it.
+ */
+export function injectTooltipRuntime(html: string): string {
+  if (html.includes('data-stx-tooltip-runtime') || !outputNeedsTooltipRuntime(html))
+    return html
+
+  const tag = `<script data-stx-scoped data-stx-tooltip-runtime>${getTooltipRuntime()}</script>`
+
+  /*
+   * `lastIndexOf`, never `.replace('</body>', …)`.
+   *
+   * The FIRST `</body>` in a document is routinely inside a script's string
+   * content — the router runtime and the x-element runtime both contain one —
+   * and replacing that occurrence injects this script into the middle of
+   * another one, breaking the page. See CLAUDE.md item 24.
+   */
+  const bodyIdx = html.lastIndexOf('</body>')
+  if (bodyIdx === -1)
+    return `${html}\n${tag}`
+
+  return `${html.slice(0, bodyIdx)}${tag}\n${html.slice(bodyIdx)}`
+}
+
 /**
  * Inject the SPA router script into the template.
  * The router is provided by the canonical router in packages/router/src/client.ts.

packages/stx/test/tooltip-runtime.test.ts

@@ -0,0 +1,146 @@
+/**
+ * `x-tooltip` ships the runtime that makes it work (stacksjs/stx#1922).
+ *
+ * `getTooltipRuntime()` was written, exported from `builtins/index.ts`, and
+ * called by nothing — two definitions and zero call sites, in stx and in
+ * `bun-plugin-stx`. `registerBuiltins()` registers ten builtins and tooltip was
+ * not one of them. So the attribute reached the DOM and nothing ever acted on
+ * it: hovering showed the native `title` tooltip, which would have shown anyway.
+ *
+ * The dead export was not merely unused. The codemod's largest and only
+ * auto-fixable rule rewrites `title=` into `x-tooltip=`, so every consuming
+ * codebase was being pointed at an attribute that had never worked — one
+ * downstream tree had 169 findings, all of which would have been no-ops. It read
+ * as an adoption problem (`codemod.d.ts` records `x-tooltip` as "delivered and
+ * used zero times") when the cause was that there was nothing to adopt.
+ *
+ * Asked of the finished OUTPUT, for the reason `outputNeedsSignalsRuntime` is:
+ * both the attribute and every rewrite that could have produced it have happened
+ * by then, so no processing order can hide the answer.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { getTooltipRuntime } from '../src/builtins/tooltip'
+import { processDirectives } from '../src/process'
+import { injectTooltipRuntime, outputNeedsTooltipRuntime } from '../src/runtime-injection'
+
+async function render(body: string): Promise<string> {
+  return processDirectives(
+    `<!DOCTYPE html><html><body>${body}</body></html>`,
+    {},
+    `${import.meta.dir}/tooltip-fixture.stx`,
+    { debug: false, cache: false } as any,
+    new Set(),
+  )
+}
+
+describe('a page that uses x-tooltip', () => {
+  it('gets the runtime', async () => {
+    const html = await render(`<button x-tooltip="Bold" title="Bold">B</button>`)
+
+    expect(html).toContain('data-stx-tooltip-runtime')
+  })
+
+  it('gets the real runtime, not just a marker', async () => {
+    // The whole defect was a runtime that existed and was never delivered. A
+    // tag with the right attribute and no code in it would reproduce it exactly.
+    const html = await render(`<button x-tooltip="Bold">B</button>`)
+
+    expect(html).toContain('stx-tooltip')
+    expect(html).toContain('mouseover')
+    expect(html).toContain('[x-tooltip]')
+  })
+
+  it('keeps the attribute, since the runtime reads it from the DOM', async () => {
+    const html = await render(`<button x-tooltip="Bold" title="Bold">B</button>`)
+
+    expect(html).toContain('x-tooltip="Bold"')
+  })
+
+  it('injects it once, not once per element', async () => {
+    const html = await render(
+      `<button x-tooltip="One">1</button><button x-tooltip="Two">2</button>`,
+    )
+
+    expect(html.split('data-stx-tooltip-runtime').length - 1).toBe(1)
+  })
+})
+
+describe('a page that does not', () => {
+  it('gets nothing', async () => {
+    const html = await render(`<p>no tooltips here</p>`)
+
+    expect(html).not.toContain('data-stx-tooltip-runtime')
+  })
+})
+
+describe('deciding whether the attribute is present', () => {
+  it('requires it to be inside a tag', () => {
+    // Documentation that names the attribute is prose, not markup — the same
+    // distinction `blankInertHtmlRegions` draws for the signals runtime, and the
+    // reason a docs page does not ship a runtime it never uses (#1835).
+    expect(outputNeedsTooltipRuntime('<p>Use x-tooltip="..." to add one.</p>')).toBe(false)
+    expect(outputNeedsTooltipRuntime('<button x-tooltip="Save">S</button>')).toBe(true)
+  })
+
+  it('allows a `>` inside the tooltip text', () => {
+    // A tooltip reading `a > b` is ordinary, and stopping the scan at the first
+    // `>` would miss it — the same trap that silently killed bindings in #1771.
+    expect(outputNeedsTooltipRuntime('<button x-tooltip="a > b">x</button>')).toBe(true)
+  })
+})
+
+describe('where the runtime is placed', () => {
+  it('goes before the LAST </body>, never the first', () => {
+    /*
+     * CLAUDE.md item 24. The first `</body>` in a document is routinely inside
+     * a script's string content — the router and x-element runtimes both carry
+     * one — so `.replace('</body>', …)` injects into the middle of another
+     * script and breaks the page. This fixture is that shape exactly.
+     */
+    const page = `<html><body><script>var t = "</body>";</script>`
+      + `<button x-tooltip="Save">S</button></body></html>`
+
+    const out = injectTooltipRuntime(page)
+    const runtimeAt = out.indexOf('data-stx-tooltip-runtime')
+    const decoyAt = out.indexOf('var t =')
+
+    expect(runtimeAt).toBeGreaterThan(decoyAt)
+    expect(out).toContain('var t = "</body>";')
+    expect(runtimeAt).toBeLessThan(out.lastIndexOf('</body>'))
+  })
+
+  it('appends when there is no body to close', () => {
+    // A fragment has no `</body>`. Dropping the runtime there would make the
+    // attribute silently dead again, which is the bug.
+    const out = injectTooltipRuntime(`<button x-tooltip="Save">S</button>`)
+
+    expect(out).toContain('data-stx-tooltip-runtime')
+  })
+
+  it('does not add a second copy to a page that already has one', () => {
+    const once = injectTooltipRuntime(`<button x-tooltip="Save">S</button>`)
+
+    expect(injectTooltipRuntime(once)).toBe(once)
+  })
+})
+
+describe('the runtime source itself', () => {
+  it('binds by delegation, so elements added later are covered', () => {
+    // Delegation is why this is not a registered builtin: one listener pair on
+    // `document` costs nothing when nothing matches, and needs no per-element
+    // wiring for content that arrives after hydration or an SPA swap.
+    const source = getTooltipRuntime()
+
+    expect(source).toContain('document.addEventListener')
+    expect(source).toContain('closest("[x-tooltip]")')
+  })
+
+  it('responds to keyboard focus, not only to hover', () => {
+    // A tooltip only reachable by mouse is not reachable by everyone.
+    const source = getTooltipRuntime()
+
+    expect(source).toContain('focusin')
+    expect(source).toContain('focusout')
+  })
+})