@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/runtime-globals.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Runtime Globals
+ *
+ * The single source of truth for the stx APIs destructured off `window.stx` at
+ * the top of every generated client script, so user code can write `state(...)`
+ * or `onMount(...)` without importing anything.
+ *
+ * This list used to be hardcoded separately in three places — the `@include`
+ * component wrapper, the page setup function, and the `<Component />` client
+ * script wrapper. They drifted, so which APIs existed depended on which kind of
+ * script you happened to be writing, and the failure was a bare `ReferenceError`
+ * at runtime with nothing at build time: `nextTick()` resolved in a component
+ * script but threw in a page, `onMounted()` resolved in a page but threw in an
+ * `@include`d component. See #1785.
+ *
+ * Two entries were also phantoms - `inject` and `nextTick` were destructured by
+ * one site but never defined on `window.stx` at all, so they silently evaluated
+ * to `undefined` and threw "is not a function" when called. Both are now
+ * implemented by the signals runtime (`inject` as of #1804).
+ *
+ * This list is also the source of `STX_AUTO_IMPORTS` (client-script.ts), which
+ * used to be a fourth hand-maintained copy for the classic `<script client>`
+ * path. It had drifted to 82 names against a runtime surface of 66, so 16 names
+ * — `h`, `Fragment`, `createStore`, `useMeta`, `getCurrentInstance` and others —
+ * were destructured off `window.stx` for every client script and silently bound
+ * to `undefined`, failing at the call site as "undefined is not a function" with
+ * nothing pointing at the missing name. One list, one guard (#1804).
+ *
+ * Adding a runtime global is now a one-line change here. `runtime-globals.test.ts`
+ * asserts every name actually exists on `window.stx` and that all three call
+ * sites emit the same set, which is what keeps this from drifting again.
+ *
+ * @module runtime-globals
+ */
+/**
+ * Public stx APIs made available as bare identifiers inside client scripts.
+ *
+ * Sorted for a stable diff. Internal `window.stx` members (`_scopes`,
+ * `_cleanupContainer`, …) are deliberately excluded — they are runtime
+ * plumbing, not part of the authoring surface.
+ */
+export declare const STX_RUNTIME_GLOBALS: readonly string[];
+/**
+ * Names a call site declares itself and therefore must NOT also destructure.
+ *
+ * The `<Component />` wrapper defines scope-aware `onMount`/`onDestroy` that
+ * push into that component's own callback arrays:
+ *
+ *   const onMount = (fn) => __scopeVars.__mountCallbacks.push(fn)
+ *
+ * Destructuring the same names first makes that a duplicate `const` — a
+ * SyntaxError, which surfaces as the whole chunk silently failing to minify (and
+ * failing to run). This omission is deliberate, unlike the accidental drift
+ * #1785 fixed, so it is declared here rather than left implicit.
+ */
+export declare const COMPONENT_SCOPE_LOCAL_GLOBALS: readonly string[];
+/**
+ * Build the destructuring statement that pulls {@link STX_RUNTIME_GLOBALS} into
+ * a generated client script's scope.
+ *
+ * @param declaration `var` for scripts that reassign a binding (the `@include`
+ * wrapper rebinds `onDestroy` to tee into its teardown channel — an assignment,
+ * which `var` permits), `const` otherwise.
+ * @param exclude names the generated wrapper or user script declares itself.
+ * A local declaration is intentionally allowed to shadow a runtime convenience
+ * global, just as an explicit import would. Omitting it from this destructure
+ * prevents duplicate-binding syntax errors.
+ * @param source optionally limits bindings to identifiers referenced by one
+ * component script. Page-level callers omit it and retain the full authoring
+ * surface.
+ */
+export declare function buildRuntimeGlobalsDestructure(declaration?: 'const' | 'var', exclude?: readonly string[], source?: string): string;
+/**
+ * Runtime globals that are COMPILE-TIME macros rather than reactive APIs.
+ *
+ * Calling one of these does not make a script reactive — they are consumed by
+ * the compiler and produce no runtime subscription — so the auto-mount test
+ * below must not treat them as evidence that a block needs mounting.
+ */
+export declare const COMPILE_TIME_ONLY_GLOBALS: readonly string[];
+/**
+ * Public authoring primitives that are NOT reachable as a bare identifier in a
+ * `<script client>` block, each tagged with WHY — so the client/server boundary
+ * is discoverable in source instead of inferred from a `ReferenceError` at
+ * runtime (stacksjs/stx#1846).
+ *
+ * Paired with the export-side guard in `authoring-surface.test.ts`: a newly
+ * exported composable that is reachable by neither client path — a bare global
+ * in {@link STX_RUNTIME_GLOBALS} (path 1), nor the demand-bundle allowlist
+ * `SERVER_ONLY_COMPOSABLES` (path 2) — must be classified here, or the test
+ * fails. Same "force a decision" contract that COMPILE_TIME_ONLY_GLOBALS and
+ * DELIBERATELY_NOT_GLOBAL already apply in their own directions.
+ *
+ * `client-gap` is deliberately distinct from `server-only`: it marks a primitive
+ * that SHOULD be callable from a client script but is not yet wired into either
+ * client path — a tracked gap, not a boundary.
+ *
+ * `isomorphic-import` is distinct again: the primitive is pure and WOULD run in a
+ * browser, but the project has decided it is not part of the auto-delivered
+ * client surface — an app imports it explicitly. Not a gap to close; a boundary
+ * drawn on purpose.
+ */
+export type NonClientCategory = 'server-only' | 'builtin-component' | 'compile-time-directive' | 'browser-composable' | 'client-gap' | 'isomorphic-import';
+export declare const NON_CLIENT_PRIMITIVES: Readonly<Record<string, {
+    category: NonClientCategory;
+    reason: string;
+}>>;
+/**
+ * Names whose presence in a client script means it needs the signals runtime
+ * and an `stx.mount()` wrapper.
+ *
+ * DERIVED, not hand-maintained (stacksjs/stx#1819). This was a literal regex
+ * alternation of 36 names against 71 runtime globals, so a block built out of
+ * the newer reactive composables — `useStore`, `useQuery`, `useMutation`,
+ * `useCookie`, `watchMultiple` and a dozen more — was classified as "not using
+ * signals", skipped mounting, and fell through to the legacy IIFE path with no
+ * reactivity at all.
+ *
+ * Exactly the drift #1804 removed for STX_AUTO_IMPORTS, one file away.
+ */
+export declare const REACTIVE_RUNTIME_GLOBALS: readonly string[];
+/**
+ * Does this script call anything that needs the reactive runtime?
+ *
+ * Matches a CALL, not a mention: a bare word can be a property, a string or a
+ * comment. Tolerates a generic argument list, since `state<Foo>(…)` is valid
+ * TypeScript and common.
+ */
+export declare function usesReactiveRuntime(source: string): boolean;
+/**
+ * Does this template have a reactive context — a signal, a bound attribute, a
+ * reactive directive, or a client script — that will own its event handlers?
+ *
+ * This is the question `processEventDirectives` (events.ts) needs. It decides
+ * whether to leave `@click` in the markup for the signals runtime to bind, or to
+ * strip it and bind it imperatively through `__stx_runHandler`.
+ *
+ * It used to answer that with its own regex matching only `state`/`derived`/
+ * `effect` plus four directives, so a client block built out of `useStore` (or
+ * any of the other ~65 reactive globals) failed it. The handler was stripped and
+ * rebound to code that resolves it through a `[data-stx-scope]` ancestor that
+ * page-level client blocks never get, then fell back to evaluating the bare
+ * name — which lives inside the setup closure and is not a global. Every handler
+ * on the page died with a ReferenceError on click (#1824).
+ *
+ * Note this is NOT the same question as {@link templateNeedsRuntime}: a template
+ * whose only client-side behaviour is `<button @click="doIt()">` needs the
+ * runtime injected, but has no reactive scope to own the handler, so events.ts
+ * must still bind it imperatively. Conflating the two makes that fallback
+ * unreachable.
+ */
+export declare function templateHasReactiveContext(template: string, filePath?: string): boolean;
+/**
+ * Will this template get the client signals runtime?
+ *
+ * A reactive context needs it, and so does a lone event handler — something has
+ * to bind that, and the runtime is what binds it when a reactive scope exists.
+ *
+ * This had three independent implementations that disagreed, and every
+ * disagreement was a bug: `hasSignalsSyntax` (signal-processing.ts) decides
+ * whether to INJECT the runtime; the auto-mount test (client-script.ts) decides
+ * whether to wrap a client block in `stx.mount()` — when it said yes and the
+ * first said no, the page emitted `stx.mount(...)` with nothing to mount onto
+ * (#1819, #1820); and events.ts asked the related-but-distinct question above
+ * (#1824).
+ *
+ * They live here because events.ts is a leaf module and importing
+ * signal-processing.ts would close a cycle through client-script.ts.
+ */
+export declare function templateNeedsRuntime(template: string, filePath?: string): boolean;
+/**
+ * Colon attributes that are DIRECTIVES, not attribute bindings.
+ *
+ * `:href` and `:disabled` name a real HTML attribute and can be resolved to one.
+ * `:if`, `:for` and `:text` do not — they are instructions to the conditional
+ * processor, the loop runtime and the text binder, and the element carries no
+ * attribute of that name at any point.
+ *
+ * The distinction had never been written down, so `processServerBindings`
+ * evaluated every `:name="expr"` alike. It went unnoticed because its tag regex
+ * required each attribute chunk to start with whitespace and be a single
+ * character, so it never matched a real tag with a real attribute — the pass was
+ * effectively dead. Fixing that regex (0.2.173) switched it on for everything at
+ * once, and `<p :if="error">` started rendering as `<p if="Bad creds">`: the
+ * attribute leaked into the markup AND the conditional stopped applying, so a
+ * falsy condition no longer removed the element. Same for `:show`, `:text`,
+ * `:html`, `:model` and `:key`.
+ *
+ * `:class` and `:style` are deliberately absent: they DO resolve to real
+ * attributes, and `processServerBindings` has specific handling for them.
+ */
+export declare const RUNTIME_OWNED_COLON_ATTRS: readonly string[];
+/** Is this colon attribute a directive rather than something to resolve? */
+export declare function isRuntimeOwnedColonAttr(name: string): boolean;
+/**
+ * `x-` attributes the signals runtime consumes itself.
+ *
+ * The runtime treats any unrecognised `x-foo` as a generic attribute binding
+ * (`x-href`, `x-src`, `x-alt` all work that way), so the ones it handles
+ * through their own code paths have to be excluded — that exclusion is what
+ * this list is.
+ *
+ * It is also what decides whether a component may carry the attribute, which
+ * is why it lives here rather than only inside the generated runtime. Those
+ * were two hand-maintained lists, and they disagreed about exactly two names:
+ * `x-tooltip` and `x-tooltip-position`, the most recently added pair (#1673).
+ * Putting one on a COMPONENT rewrote it to `:tooltip="Settings"`, a signal
+ * binding over an identifier that does not exist — so the tooltip silently
+ * vanished AND the page reported a hydration invariant failure naming the
+ * tooltip's text rather than the tooltip (#1830). The same attribute on a
+ * plain element worked, which made it unguessable from the authoring side.
+ */
+export declare const RUNTIME_HANDLED_X_ATTRS: readonly string[];
+/**
+ * `x-` attributes owned by the Alpine-style reactive bridge, not the signals
+ * runtime. They never reach `X_HANDLED`, but must still survive on a component
+ * for the bridge to find them on the rendered element.
+ */
+export declare const ALPINE_BRIDGE_X_ATTRS: readonly string[];
+/**
+ * Every `x-` attribute that must reach the rendered DOM element untouched when
+ * it is written on a component, rather than being captured as a prop binding.
+ */
+export declare const COMPONENT_PASSTHROUGH_X_ATTRS: readonly string[];
+/** The `X_HANDLED` lookup the generated runtime embeds, as JS source. */
+export declare function runtimeHandledXAttrsLiteral(): string;
+/**
+ * Drop cached blanked documents.
+ *
+ * Nothing in the framework calls this, and nothing needs to. Entries are keyed
+ * on the input document itself, so an edited template is a different key and
+ * can never be answered with a stale result -- there is no invalidation to
+ * perform. It exists for callers that want a cold cache, such as tests.
+ */
+export declare function clearBlankCache(): void;
+export declare function blankInertHtmlRegions(html: string): string;

package/dist/runtime-globals.js

@@ -0,0 +1,230 @@
+import { importsSignalDeclarations } from "./imported-signals.js";
+export const STX_RUNTIME_GLOBALS = [
+  "batch",
+  "computed",
+  "configureFetch",
+  "defineEmits",
+  "defineExpose",
+  "definePageMeta",
+  "defineProps",
+  "defineSlots",
+  "defineStore",
+  "derived",
+  "effect",
+  "goBack",
+  "goForward",
+  "inject",
+  "invalidateRoute",
+  "isDerived",
+  "isSignal",
+  "navigate",
+  "nextTick",
+  "onBeforeMount",
+  "onBeforeUnmount",
+  "onDestroy",
+  "onMount",
+  "onMounted",
+  "onUnmounted",
+  "peek",
+  "provide",
+  "reactive",
+  "ref",
+  "refresh",
+  "registerStoresClient",
+  "setRouteParams",
+  "state",
+  "untrack",
+  "useAsync",
+  "useClickOutside",
+  "useColorMode",
+  "useCookie",
+  "useCounter",
+  "useDark",
+  "useDebounce",
+  "useDebouncedValue",
+  "useEventListener",
+  "useFetch",
+  "useFocus",
+  "useHead",
+  "useId",
+  "useInterval",
+  "useLocalStorage",
+  "useMediaQuery",
+  "useMutation",
+  "useOptimistic",
+  "usePreferredContrast",
+  "usePreferredDark",
+  "usePreferredLight",
+  "usePreferredReducedMotion",
+  "useQuery",
+  "useReactiveProp",
+  "useRef",
+  "useRoute",
+  "useRouteParam",
+  "useRouteParams",
+  "useScrollLock",
+  "useSearchParams",
+  "useSeoMeta",
+  "useSessionStorage",
+  "useSlots",
+  "useStore",
+  "useThrottle",
+  "useTimeout",
+  "useToggle",
+  "useWebSocket",
+  "watch",
+  "watchEffect",
+  "watchMultiple",
+  "withDefaults"
+], COMPONENT_SCOPE_LOCAL_GLOBALS = ["onMount", "onDestroy"];
+export function buildRuntimeGlobalsDestructure(declaration = "const", exclude = [], source) {
+  let names = exclude.length ? STX_RUNTIME_GLOBALS.filter((name) => !exclude.includes(name)) : STX_RUNTIME_GLOBALS;
+  if (source !== void 0)
+    names = names.filter((name) => {
+      const escaped = name.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+      return new RegExp(`(^|[^\\w$])${escaped}(?![\\w$])`).test(source);
+    });
+  return `${declaration} { ${names.join(", ")} } = window.stx;`;
+}
+export const COMPILE_TIME_ONLY_GLOBALS = [
+  "defineEmits",
+  "defineExpose",
+  "definePageMeta",
+  "defineProps",
+  "defineSlots",
+  "withDefaults"
+], NON_CLIENT_PRIMITIVES = {
+  redirect: { category: "server-only", reason: "returns an HTTP Response for <script server>/edge/build; use navigate() on the client." },
+  useAsyncData: { category: "browser-composable", reason: "inlined on demand from src/composables when a script references it; reachable, not a bare global." },
+  Teleport: { category: "compile-time-directive", reason: "template tag resolved by processTeleportDirectives; not a script callable." },
+  StxModalBuiltin: { category: "builtin-component", reason: "builtin component used as a template tag; drive open/close from the modal store." },
+  StxToastBuiltin: { category: "builtin-component", reason: "builtin component used as a template tag; push toasts via the toast store." },
+  useForm: { category: "browser-composable", reason: "reactive form primitive; lives in src/composables/use-form.ts and is inlined on demand when a <script client> references it (#1846)." },
+  defineForm: { category: "browser-composable", reason: "deprecated alias of useForm, kept for a minor (#1843). Same delivery path \u2014 inlined on demand from src/composables/use-form.ts." },
+  validateFields: { category: "isomorphic-import", reason: "pure validation helper; import it directly, not auto-delivered to <script client> (per client-api-delivery.test.ts)." },
+  validateField: { category: "isomorphic-import", reason: "singular pure validation helper; same explicit-import boundary as validateFields." }
+}, REACTIVE_RUNTIME_GLOBALS = STX_RUNTIME_GLOBALS.filter((name) => !COMPILE_TIME_ONLY_GLOBALS.includes(name));
+export function usesReactiveRuntime(source) {
+  if (!source)
+    return !1;
+  return REACTIVE_RUNTIME_GLOBALS.some((name) => new RegExp(`\\b${name}\\s*(?:<[^>]*>)?\\s*\\(`).test(source));
+}
+const TEMPLATE_REACTIVE_PATTERNS = [
+  /@if\s*=/,
+  /@for\s*=/,
+  /@show\s*=/,
+  /@model\s*=/,
+  /@bind:/,
+  /@class\s*=/,
+  /@style\s*=/,
+  /\bx-data\s*=/,
+  /\bstate\s*(?:<[^>]*>)?\s*\(/,
+  /\bderived\s*(?:<[^>]*>)?\s*\(/,
+  /\beffect\s*(?:<[^>]*>)?\s*\(/,
+  /\bref\s*(?:<[^>]*>)?\s*\(/,
+  /\bcomputed\s*(?:<[^>]*>)?\s*\(/,
+  /\breactive\s*(?:<[^>]*>)?\s*\(/,
+  /\bwatch\s*(?:<[^>]*>)?\s*\(/,
+  /\bwatchEffect\s*(?:<[^>]*>)?\s*\(/,
+  /\s:[a-z][\w-]*\s*=\s*["']/i,
+  /\s:(?:if|else-if|else|for|show|text|html|model)\s*=/,
+  /data-stx(?:-auto)?(?![-\w])/,
+  /data-stx-scoped/
+], HAS_EVENT_HANDLER = /\s@[a-z][\w.:-]*\s*=/i;
+export function templateHasReactiveContext(template, filePath) {
+  if (!template)
+    return !1;
+  const live = blankInertHtmlRegions(template);
+  return liveTemplateHasReactiveContext(live, filePath);
+}
+function liveTemplateHasReactiveContext(live, filePath) {
+  if (TEMPLATE_REACTIVE_PATTERNS.some((pattern) => pattern.test(live)))
+    return !0;
+  if (usesReactiveRuntime(live))
+    return !0;
+  return scriptsImportSignals(live, filePath);
+}
+function scriptsImportSignals(template, filePath) {
+  if (!filePath)
+    return !1;
+  for (const match of template.matchAll(/<script\b(?![^>]*\bserver\b)(?![^>]*\bsrc\s*=)[^>]*>([\s\S]*?)<\/script\s*>/gi))
+    if (importsSignalDeclarations(match[1], filePath))
+      return !0;
+  return !1;
+}
+export function templateNeedsRuntime(template, filePath) {
+  if (!template)
+    return !1;
+  const live = blankInertHtmlRegions(template);
+  return HAS_EVENT_HANDLER.test(live) || liveTemplateHasReactiveContext(live, filePath);
+}
+export const RUNTIME_OWNED_COLON_ATTRS = [
+  "if",
+  "else-if",
+  "elseif",
+  "else",
+  "for",
+  "show",
+  "key",
+  "text",
+  "html",
+  "model",
+  "ref"
+];
+export function isRuntimeOwnedColonAttr(name) {
+  return RUNTIME_OWNED_COLON_ATTRS.includes(name.toLowerCase());
+}
+export const RUNTIME_HANDLED_X_ATTRS = [
+  "x-text",
+  "x-html",
+  "x-model",
+  "x-show",
+  "x-if",
+  "x-for",
+  "x-cloak",
+  "x-ref",
+  "x-data",
+  "x-bind",
+  "x-class",
+  "x-style",
+  "x-tooltip",
+  "x-tooltip-position"
+], ALPINE_BRIDGE_X_ATTRS = [
+  "x-init",
+  "x-transition",
+  "x-effect",
+  "x-on"
+], COMPONENT_PASSTHROUGH_X_ATTRS = [
+  ...RUNTIME_HANDLED_X_ATTRS,
+  ...ALPINE_BRIDGE_X_ATTRS
+];
+export function runtimeHandledXAttrsLiteral() {
+  return `{${RUNTIME_HANDLED_X_ATTRS.map((n) => `'${n}':1`).join(",")}}`;
+}
+const BLANK_CACHE_MIN_BYTES = 65536, BLANK_CACHE_MAX_ENTRIES = 4, blankCache = new Map;
+export function clearBlankCache() {
+  blankCache.clear();
+}
+export function blankInertHtmlRegions(html) {
+  if (!html)
+    return html;
+  if (!html.includes("<!--") && !/<(?:pre|code)\b/i.test(html))
+    return html;
+  const cacheable = html.length >= BLANK_CACHE_MIN_BYTES;
+  if (cacheable) {
+    const hit = blankCache.get(html);
+    if (hit !== void 0)
+      return hit;
+  }
+  const blankText = (segment) => segment.replace(/(<[^>]*>)|([^<]+)/g, (_match, tag, text) => tag ?? " ".repeat(text.length)), blanked = html.replace(/(<pre\b[^>]*>)([\s\S]*?)(<\/pre>)/gi, (_m, open, body, close) => open + blankText(body) + close).replace(/(<code\b[^>]*>)([\s\S]*?)(<\/code>)/gi, (_m, open, body, close) => open + blankText(body) + close).replace(/<!--[\s\S]*?-->/g, (match) => " ".repeat(match.length));
+  if (cacheable) {
+    while (blankCache.size >= BLANK_CACHE_MAX_ENTRIES) {
+      const oldest = blankCache.keys().next();
+      if (oldest.done)
+        break;
+      blankCache.delete(oldest.value);
+    }
+    blankCache.set(html, blanked);
+  }
+  return blanked;
+}

package/dist/runtime-injection.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Runtime Injection Module
+ *
+ * Handles injecting the signals runtime, browser runtime, and SPA router
+ * script into rendered HTML templates.
+ *
+ * @module runtime-injection
+ */
+import type { StxOptions } from './types';
+/**
+ * Inject an @stacksjs/browser initialization input into a template that will
+ * continue through STX client-script processing. The later bundling pass turns
+ * this package specifier into browser-ready code.
+ *
+ * IMPORTANT: Only checks CLIENT scripts (not <script server>).
+ * Server scripts should use the server ORM directly, not browser functions.
+ */
+export declare function injectBrowserRuntime(template: string): string;
+/**
+ * Does this rendered page ship the signals runtime?
+ *
+ * Answers the question the SPA router cannot: a fragment never carries the
+ * runtime, so swapping one into a page that has none leaves it permanently
+ * unhydrated. The router used to guess from markers in the fragment markup and
+ * missed the shape that has no markers at all — reactive syntax with no setup
+ * function, whose only stamp is `data-stx-auto` on `<body>`, which the fragment
+ * excludes (stacksjs/stx#1827). The server knows, because it is the thing that
+ * decided; it reports the answer in `X-STX-Runtime` on fragment responses.
+ *
+ * Deliberately keyed on the same marker `injectSignalsRuntime` writes and
+ * checks below, so the two cannot disagree about what "has a runtime" means.
+ * Pass the FULL page, before it is reduced to the container's inner content.
+ */
+export declare function pageShipsSignalsRuntime(fullPageHtml: string): boolean;
+/**
+ * Does this rendered output contain a script that will THROW without the
+ * signals runtime?
+ *
+ * The safety net for stacksjs/stx#1820. Two independent decisions used to be
+ * made about the same page — `hasSignalsSyntax` decided whether to inject the
+ * runtime, and the client-script pass separately decided to emit
+ * `window.stx.mount(...)` — and nothing reconciled them. When they disagreed
+ * the page died on its first client line with "Cannot read properties of
+ * undefined (reading 'mount')", taking every handler defined in that block
+ * with it.
+ *
+ * Widening the gate does not fix that; it only makes the disagreement rarer,
+ * and it has already been widened twice. The gate is also evaluated against a
+ * template `processEventDirectives` has already rewritten, so an `@event=`
+ * page cannot match it however many patterns are added. This asks the opposite
+ * question, of the finished output, where no ordering can hide the answer: did
+ * we emit something that requires the runtime?
+ *
+ * Keyed on an UNGUARDED reach for `window.stx`, because that is precisely what
+ * throws. The guarded spellings the compiler also emits are all safe and must
+ * not trigger injection:
+ *
+ *   var { state } = window.stx || window;   // falls back
+ *   var s = window.stx || {};               // falls back
+ *   window.stx = window.stx || {};          // self-initializing
+ *   if (window.stx) window.stx._latestSetup = null;   // guarded
+ *
+ * The appearance bootstrap is the reason this runs before that directive is
+ * processed: it emits a self-contained `data-stx-scoped` script on pages with
+ * no reactivity at all, so keying on the presence of a client script — the
+ * obvious invariant, and the one the issue suggested — would pull the runtime
+ * onto every static page that sets a theme.
+ */
+export declare function outputNeedsSignalsRuntime(html: string): boolean;
+/**
+ * Inject STX signals runtime into the template.
+ * The runtime provides client-side reactivity.
+ */
+export declare function injectSignalsRuntime(template: string, options: StxOptions): Promise<string>;
+/**
+ * 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 declare function outputNeedsTooltipRuntime(html: string): boolean;
+/**
+ * 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 declare function injectTooltipRuntime(html: string): string;
+/** Whether `template` already carries the SPA router. */
+export declare function hasRouterScript(template: string): boolean;
+export declare function injectRouterScript(template: string, options?: StxOptions): Promise<string>;