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

package/dist/server-components.js

@@ -0,0 +1,427 @@
+const componentRegistry = new Map, componentCache = new Map;
+export function registerServerComponent(component) {
+  componentRegistry.set(component.name, {
+    component,
+    type: "server"
+  });
+}
+export function registerClientComponent(component) {
+  componentRegistry.set(component.name, {
+    component,
+    type: "client"
+  });
+}
+export function getComponent(name) {
+  return componentRegistry.get(name);
+}
+export function hasComponent(name) {
+  return componentRegistry.has(name);
+}
+export function getComponentNames() {
+  return Array.from(componentRegistry.keys());
+}
+export function clearComponents() {
+  componentRegistry.clear();
+  componentCache.clear();
+}
+function generateCacheKey(name, props) {
+  const propsHash = JSON.stringify(props);
+  return `${name}:${hashString(propsHash)}`;
+}
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0;i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash | 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+function getCached(name, props, config) {
+  if (!config?.enabled)
+    return null;
+  const key = (config.keyGenerator || ((p) => generateCacheKey(name, p)))(props), cached = componentCache.get(key);
+  if (!cached)
+    return null;
+  const now = Date.now(), ttl = config.ttl || 60000;
+  if (now - cached.timestamp > ttl) {
+    if (config.staleWhileRevalidate)
+      return { html: cached.html, data: cached.data };
+    componentCache.delete(key);
+    return null;
+  }
+  return { html: cached.html, data: cached.data };
+}
+function setCached(name, props, html, data, config) {
+  if (!config?.enabled)
+    return;
+  const key = (config.keyGenerator || ((p) => generateCacheKey(name, p)))(props);
+  componentCache.set(key, {
+    html,
+    timestamp: Date.now(),
+    data
+  });
+}
+export function clearComponentCache(name) {
+  if (name) {
+    for (const key of componentCache.keys())
+      if (key.startsWith(`${name}:`))
+        componentCache.delete(key);
+  } else
+    componentCache.clear();
+}
+export async function renderServerComponent(name, options = {}) {
+  const startTime = performance.now(), { props = {}, signal } = options, entry = componentRegistry.get(name);
+  if (!entry)
+    throw Error(`Server component "${name}" not found`);
+  if (entry.type !== "server")
+    throw Error(`Component "${name}" is not a server component`);
+  const component = entry.component, cached = getCached(name, props, component.cache);
+  if (cached)
+    return {
+      html: cached.html,
+      renderTime: performance.now() - startTime,
+      data: cached.data,
+      dependencies: component.dependencies || [],
+      cached: !0
+    };
+  if (signal?.aborted)
+    throw Error("Render aborted");
+  try {
+    let data = { ...props };
+    if (component.loader)
+      data = {
+        ...data,
+        ...await component.loader(props)
+      };
+    const html = await processServerTemplate(component.template, data);
+    setCached(name, props, html, data, component.cache);
+    return {
+      html,
+      renderTime: performance.now() - startTime,
+      data,
+      dependencies: component.dependencies || [],
+      cached: !1
+    };
+  } catch (error) {
+    if (component.errorBoundary)
+      return {
+        html: await processServerTemplate(component.errorBoundary, {
+          error: error instanceof Error ? error.message : String(error),
+          ...props
+        }),
+        renderTime: performance.now() - startTime,
+        dependencies: component.dependencies || [],
+        cached: !1
+      };
+    throw error;
+  }
+}
+export async function renderClientComponent(name, options = {}) {
+  const startTime = performance.now(), { props = {} } = options, entry = componentRegistry.get(name);
+  if (!entry)
+    throw Error(`Client component "${name}" not found`);
+  if (entry.type !== "client")
+    throw Error(`Component "${name}" is not a client component`);
+  const component = entry.component, id = `cc-${name}-${Math.random().toString(36).slice(2, 9)}`, innerHtml = await processServerTemplate(component.template, props), clientPropsData = {};
+  if (component.clientProps) {
+    for (const prop of component.clientProps)
+      if (prop in props)
+        clientPropsData[prop] = props[prop];
+  }
+  const html = `<div data-client-component="${name}" data-component-id="${id}" data-priority="${component.priority || "lazy"}">
+${innerHtml}
+<script type="application/json" data-component-props="${id}">${JSON.stringify(clientPropsData)}</script>
+</div>`, hydrationScript = component.clientScript ? `<script type="module" data-component-script="${id}">${component.clientScript}</script>` : void 0;
+  return {
+    html,
+    renderTime: performance.now() - startTime,
+    data: props,
+    dependencies: [],
+    cached: !1,
+    hydrationScript
+  };
+}
+export async function renderComponent(name, options = {}) {
+  const entry = componentRegistry.get(name);
+  if (!entry)
+    throw Error(`Component "${name}" not found`);
+  if (entry.type === "server")
+    return renderServerComponent(name, options);
+  else
+    return renderClientComponent(name, options);
+}
+const suspenseStates = new Map;
+export function cleanupSuspenseStates() {
+  for (const [id, state] of suspenseStates)
+    if (state.status === "resolved" || state.status === "error")
+      suspenseStates.delete(id);
+}
+export function createSuspenseBoundary(id, fallback) {
+  const state = {
+    id,
+    status: "pending"
+  };
+  suspenseStates.set(id, state);
+  return {
+    wrap: async (promise) => {
+      state.promise = promise;
+      try {
+        state.result = await promise;
+        state.status = "resolved";
+        return state.result;
+      } catch (error) {
+        state.error = error instanceof Error ? error : Error(String(error));
+        state.status = "error";
+        throw error;
+      }
+    },
+    getFallback: () => fallback
+  };
+}
+export function getSuspenseState(id) {
+  return suspenseStates.get(id);
+}
+export function clearSuspenseState(id) {
+  if (id)
+    suspenseStates.delete(id);
+  else
+    suspenseStates.clear();
+}
+export function createStreamingRenderer(components, options = {}) {
+  return {
+    renderToStream: () => {
+      return new ReadableStream({
+        async start(controller) {
+          for (const name of components)
+            try {
+              const result = await renderComponent(name, options);
+              controller.enqueue(result.html);
+              if (result.hydrationScript)
+                controller.enqueue(result.hydrationScript);
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              controller.enqueue(`<!-- Error rendering ${name}: ${message} -->`);
+            }
+          controller.close();
+        }
+      });
+    },
+    renderToString: async () => {
+      const parts = [];
+      for (const name of components)
+        try {
+          const result = await renderComponent(name, options);
+          parts.push(result.html);
+          if (result.hydrationScript)
+            parts.push(result.hydrationScript);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          parts.push(`<!-- Error rendering ${name}: ${message} -->`);
+        }
+      return parts.join(`
+`);
+    }
+  };
+}
+async function processServerTemplate(template, context) {
+  let result = template;
+  result = result.replace(/@foreach\s*\((\w+(?:\.\w+)*)\s+as\s+(\w+)\)([\s\S]*?)@endforeach/g, (_match, arrayExpr, itemVar, content) => {
+    const array = getNestedValue(context, arrayExpr.trim());
+    if (!Array.isArray(array))
+      return "";
+    return array.map((item, index) => {
+      const itemContext = { ...context, [itemVar]: item, loop: { index, first: index === 0, last: index === array.length - 1 } };
+      return processServerTemplateSync(content, itemContext);
+    }).join("");
+  });
+  result = result.replace(/@if\s*\(([^)]+)\)([\s\S]*?)@endif/g, (_match, condition, content) => {
+    return evaluateCondition(condition.trim(), context) ? content : "";
+  });
+  result = result.replace(/\{\{([^}]+)\}\}/g, (match, expr) => {
+    const trimmed = expr.trim();
+    if (trimmed.startsWith("await ")) {
+      const varName = trimmed.slice(6).split("(")[0].trim();
+      return String(context[varName] ?? match);
+    }
+    const parts = trimmed.split(".");
+    let value = context;
+    for (const part of parts) {
+      if (value === null || value === void 0)
+        break;
+      value = value[part];
+    }
+    if (value === void 0 || value === null)
+      return "";
+    return escapeHtmlValue(String(value));
+  });
+  return result;
+}
+function processServerTemplateSync(template, context) {
+  let result = template;
+  result = result.replace(/\{\{([^}]+)\}\}/g, (_match, expr) => {
+    const value = getNestedValue(context, expr.trim());
+    if (value === void 0 || value === null)
+      return "";
+    return escapeHtmlValue(String(value));
+  });
+  return result;
+}
+function getNestedValue(obj, path) {
+  const parts = path.split(".");
+  let value = obj;
+  for (const part of parts) {
+    if (value === null || value === void 0)
+      return;
+    value = value[part];
+  }
+  return value;
+}
+function evaluateCondition(condition, context) {
+  const value = getNestedValue(context, condition);
+  return Boolean(value);
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function escapeHtmlValue(str) {
+  return escapeHtml(str).replace(/\{{2,}/g, (match) => Array.from({ length: match.length }, () => "&#123;").join("&#8288;")).replace(/\{(?=!)/g, "&#123;&#8288;");
+}
+export const serverComponentDirective = {
+  name: "serverComponent",
+  hasEndTag: !0,
+  handler: (content, params, _context, _filePath) => {
+    if (!params || params.length === 0)
+      throw Error("@serverComponent requires a name parameter");
+    const name = params[0].replace(/['"`]/g, ""), id = `sc-${name}-${Math.random().toString(36).slice(2, 9)}`;
+    registerServerComponent({
+      name,
+      template: content
+    });
+    return `<div data-server-component="${name}" data-component-id="${id}">${content}</div>`;
+  }
+}, clientComponentDirective = {
+  name: "clientComponent",
+  hasEndTag: !0,
+  handler: (content, params, _context, _filePath) => {
+    if (!params || params.length === 0)
+      throw Error("@clientComponent requires a name parameter");
+    const name = params[0].replace(/['"`]/g, ""), priority = params[1]?.replace(/['"`]/g, ""), id = `cc-${name}-${Math.random().toString(36).slice(2, 9)}`, scriptMatch = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i), clientScript = scriptMatch ? scriptMatch[1] : void 0, templateContent = scriptMatch ? content.replace(scriptMatch[0], "") : content;
+    registerClientComponent({
+      name,
+      template: templateContent,
+      clientScript,
+      priority: priority || "lazy"
+    });
+    return `<div data-client-component="${name}" data-component-id="${id}" data-priority="${priority || "lazy"}">
+${templateContent}
+</div>`;
+  }
+}, suspenseDirective = {
+  name: "suspense",
+  hasEndTag: !0,
+  handler: (content, params, _context, _filePath) => {
+    const fallback = params[0]?.replace(/['"`]/g, "") || "Loading...", id = `suspense-${Math.random().toString(36).slice(2, 9)}`;
+    createSuspenseBoundary(id, fallback);
+    return `<div data-suspense="${id}" data-fallback="${escapeHtml(fallback)}">
+${content}
+</div>`;
+  }
+};
+export function registerServerComponentDirectives() {
+  return [
+    serverComponentDirective,
+    clientComponentDirective,
+    suspenseDirective
+  ];
+}
+export function generateServerComponentsRuntime() {
+  return `
+(function() {
+  'use strict';
+
+  const stxServerComponents = {
+    components: new Map(),
+
+    registerComponent(name, hydrator) {
+      this.components.set(name, hydrator);
+    },
+
+    hydrateComponent(element) {
+      const name = element.dataset.clientComponent;
+      const id = element.dataset.componentId;
+      const hydrator = this.components.get(name);
+
+      if (!hydrator) {
+        console.warn('[stx] No hydrator for component:', name);
+        return;
+      }
+
+      const propsEl = element.querySelector('[data-component-props="' + id + '"]');
+      const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+
+      try {
+        hydrator(element, props);
+        element.dataset.hydrated = 'true';
+      }
+catch (error) {
+        console.error('[stx] Hydration error:', name, error);
+      }
+    },
+
+    hydrateAll() {
+      const components = document.querySelectorAll('[data-client-component]');
+      const eager = [];
+      const lazy = [];
+      const idle = [];
+
+      components.forEach(el => {
+        const priority = el.dataset.priority || 'lazy';
+        if (priority === 'eager') eager.push(el);
+        else if (priority === 'idle') idle.push(el);
+        else lazy.push(el);
+      });
+
+      // Hydrate eager immediately
+      eager.forEach(el => this.hydrateComponent(el));
+
+      // Hydrate lazy on intersection
+      if (lazy.length && 'IntersectionObserver' in window) {
+        const observer = new IntersectionObserver(entries => {
+          entries.forEach(entry => {
+            if (entry.isIntersecting) {
+              observer.unobserve(entry.target);
+              this.hydrateComponent(entry.target);
+            }
+          });
+        }, { rootMargin: '50px' });
+        lazy.forEach(el => observer.observe(el));
+      }
+else {
+        lazy.forEach(el => this.hydrateComponent(el));
+      }
+
+      // Hydrate idle during browser idle
+      if (idle.length && 'requestIdleCallback' in window) {
+        requestIdleCallback(() => {
+          idle.forEach(el => this.hydrateComponent(el));
+        });
+      }
+else {
+        setTimeout(() => {
+          idle.forEach(el => this.hydrateComponent(el));
+        }, 100);
+      }
+    }
+  };
+
+  window.__stxServerComponents = stxServerComponents;
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => stxServerComponents.hydrateAll());
+  }
+else {
+    stxServerComponents.hydrateAll();
+  }
+})();`;
+}

package/dist/sfc-template.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Locate the explicit wrapper `<template>` in an STX single-file component.
+ *
+ * A bare `<template>` can be an SFC wrapper, while a template carrying a
+ * client directive (`:for`, `@if`, `x-else`, slots, or an id) is runtime DOM
+ * and must stay in the rendered body. Keeping this distinction in one scanner
+ * avoids subtle regex boundary bugs for punctuation-prefixed attributes.
+ */
+export interface SfcTemplateBlock {
+    start: number;
+    openEnd: number;
+    closeStart: number;
+    end: number;
+    content: string;
+}
+export declare function isClientTemplateTag(openingTag: string): boolean;
+export declare function findSfcTemplateBlock(source: string): SfcTemplateBlock | null;

package/dist/sfc-template.js

@@ -0,0 +1,32 @@
+const TEMPLATE_TAG_RE = /<\/?template\b[^>]*>/gi, CLIENT_TEMPLATE_ATTRIBUTE_RE = /(?:^|\s)(?:id\s*=|(?:x-|[@:])(?:for|if|else(?:-if)?)(?=\s|=|$)|#[\w-]+(?:\s*=|\s|$)|v-slot(?::[\w-]+)?(?=\s|=|$)|slot\s*=)/i;
+export function isClientTemplateTag(openingTag) {
+  const attrs = openingTag.replace(/^<template\b/i, "").replace(/>$/, "");
+  return CLIENT_TEMPLATE_ATTRIBUTE_RE.test(attrs);
+}
+export function findSfcTemplateBlock(source) {
+  TEMPLATE_TAG_RE.lastIndex = 0;
+  let opening;
+  while ((opening = TEMPLATE_TAG_RE.exec(source)) !== null) {
+    if (opening[0].startsWith("</") || isClientTemplateTag(opening[0]))
+      continue;
+    const start = opening.index, openEnd = TEMPLATE_TAG_RE.lastIndex;
+    let depth = 1, nested;
+    while ((nested = TEMPLATE_TAG_RE.exec(source)) !== null)
+      if (nested[0].startsWith("</")) {
+        depth--;
+        if (depth === 0) {
+          const closeStart = nested.index;
+          return {
+            start,
+            openEnd,
+            closeStart,
+            end: TEMPLATE_TAG_RE.lastIndex,
+            content: source.slice(openEnd, closeStart)
+          };
+        }
+      } else
+        depth++;
+    return null;
+  }
+  return null;
+}

package/dist/signal-processing.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Signal Processing Module
+ *
+ * Handles detection, conversion, and setup of STX signals in templates.
+ * Converts directive-style syntax (@if, @for) to attribute-style for the
+ * client-side signals runtime, and wraps signal scripts in setup functions.
+ *
+ * @module signal-processing
+ */
+import type { StxOptions } from './types';
+/**
+ * Scan a template for `<script>` tags in browser order: each opening tag is
+ * closed by the **first** subsequent `</script>` (case-insensitive), and the
+ * scanner then continues from after that close tag. This matches how HTML
+ * parsers tokenize `<script>` as a RAWTEXT element — they don't re-scan the
+ * body for more `<script` openings.
+ *
+ * A plain regex like `/<script[^>]*>([\s\S]*?)<\/script>/g` doesn't give you
+ * this property: if a script body contains the literal text `<script client>`
+ * (e.g. inside a JS comment), the regex matches it as a fresh script tag,
+ * which breaks downstream TypeScript transpilation and directive parsing.
+ *
+ * `skipAttrs` lets callers drop tags whose attribute string contains certain
+ * patterns (e.g. `server`, `src=`, `data-stx-scoped`).
+ */
+export interface ScannedScriptTag {
+    readonly fullMatch: string;
+    readonly attrs: string;
+    readonly body: string;
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Drop cached script scans.
+ *
+ * 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 clearScriptScanCache(): void;
+export declare function scanScriptTags(html: string, opts?: {
+    skipAttrs?: RegExp;
+}): ScannedScriptTag[];
+/**
+ * Parsed form of a loop expression (`@for` / `@foreach` argument).
+ *
+ * `style: 'as'` — "iterable as item" / "iterable as idx => item" / "iterable as (item, idx)"
+ * `style: 'in'` — "item in iterable" / "(item, idx) in iterable" / "item of iterable"
+ * `style: 'unknown'` — fell through all parsers; iterable is `null`
+ */
+export interface ParsedLoopExpression {
+    style: 'as' | 'in' | 'unknown';
+    iterable: string | null;
+    itemVar: string | null;
+    indexVar: string | null;
+}
+/**
+ * Parse a loop argument — accepts every syntax stx supports at runtime.
+ *
+ * ```
+ * parseLoopExpression('items as item')                → { style:'as', iterable:'items',     itemVar:'item', indexVar:null }
+ * parseLoopExpression('items as idx => item')         → { style:'as', iterable:'items',     itemVar:'item', indexVar:'idx' }
+ * parseLoopExpression('items as item, idx')           → { style:'as', iterable:'items',     itemVar:'item', indexVar:'idx' }
+ * parseLoopExpression('items as (item, idx)')         → { style:'as', iterable:'items',     itemVar:'item', indexVar:'idx' }
+ * parseLoopExpression('obj.list as item')             → { style:'as', iterable:'obj.list',  itemVar:'item', indexVar:null }
+ * parseLoopExpression('item in items')                → { style:'in', iterable:'items',     itemVar:'item', indexVar:null }
+ * parseLoopExpression('(item, idx) in items')         → { style:'in', iterable:'items',     itemVar:'item', indexVar:'idx' }
+ * parseLoopExpression('item of items')                → { style:'in', iterable:'items',     itemVar:'item', indexVar:null }
+ * ```
+ */
+export declare function parseLoopExpression(expr: string): ParsedLoopExpression;
+/**
+ * Check if template uses STX signals syntax.
+ *
+ * STX directives work seamlessly on both server and client:
+ * - `@if`, `@else` - Conditional rendering
+ * - `@for` - List iteration
+ * - `@show` - Toggle visibility (keeps element in DOM)
+ * - `@model` - Two-way binding
+ * - `@bind:attr` - Dynamic attribute binding
+ * - `@class`, `@style` - Dynamic class/style binding
+ * - `@click`, `@submit` - Event handling
+ * - Scripts containing `state(`, `derived(`, `effect(` - Signal APIs
+ *
+ * Server-side directives are processed at build time.
+ * Remaining directives with reactive values are handled by the client runtime.
+ */
+export declare function hasSignalsSyntax(template: string, filePath?: string): boolean;
+/**
+ * Convert @if(expr)...@endif directive blocks to attribute-style for signal templates.
+ *
+ * This allows the signals runtime to handle reactive conditionals instead of
+ * evaluating them at build time with mock values. `@if`/`v-if` (which compiles to
+ * `@if`) thus behave as interchangeable sugar for `:if` on signal pages — including
+ * `@if`/`@elseif`/`@else` chains, which become a reactive sibling chain driven by
+ * the runtime's `findIfChain`/`bindIfChain` (it already understands `@else-if`/`@else`).
+ *
+ * Converts:
+ *   @if(loading())
+ *     <div>Loading...</div>
+ *   @endif
+ *
+ * To:
+ *   <template @if="loading()">
+ *     <div>Loading...</div>
+ *   </template>
+ *
+ * And a branching chain:
+ *   @if(a()) <p>A</p> @elseif(b()) <p>B</p> @else <p>C</p> @endif
+ *
+ * To adjacent siblings the runtime walks via nextElementSibling:
+ *   <p @if="a()">A</p>
+ *   <p @else-if="b()">B</p>
+ *   <p @else>C</p>
+ *
+ * Note: Uses <template> wrapper for branches with multiple children or text nodes.
+ */
+export declare function convertSignalDirectivesToAttributes(template: string, context?: Record<string, any>): string;
+/**
+ * SSR pre-eval for literal-valued reactive conditional attributes
+ * (stacksjs/stx#1739, Phase A).
+ *
+ * The reactive `:if` / `:show` family (and the `x-if` / `x-show` /
+ * attribute-form `@if` aliases) is normally bound at runtime via
+ * `bindIf` / `bindShow`. When the attribute value is a pure literal
+ * — feature-flag constants like `:if="false"`, dev-only debug blocks
+ * like `:if="true"`, etc. — there's no reason to ship the element +
+ * runtime binding. Pre-evaluate and:
+ *
+ *   - truthy literal ⇒ strip the attribute, keep the element
+ *   - falsy literal  ⇒ drop the element entirely (children included)
+ *
+ * Phase A intentionally handles ONE element at a time — `:else-if` /
+ * `:else` chain rebalancing is Phase B. So `:if="false"` with a sibling
+ * `:else` still drops the if-element; the else still emits as it would
+ * have, and the runtime picks correctly (chains where the first
+ * branch is gone become "always show the else branch").
+ *
+ * Skips:
+ *   - non-literal expressions (let the runtime own them)
+ *   - the block-form `@if(...)@endif` directive — that has its own
+ *     server-side handler (`processConditionals`)
+ *   - elements inside `<script>` / `<style>` bodies
+ */
+export declare function preEvalLiteralReactiveIfs(template: string): string;
+/**
+ * Convert @for(item in items())...@endfor directive blocks to attribute-style.
+ *
+ * Converts:
+ *   @for(item in items())
+ *     <div>{{ item.name }}</div>
+ *   @endfor
+ *
+ * To:
+ *   <template @for="item in items()">
+ *     <div>{{ item.name }}</div>
+ *   </template>
+ */
+export declare function convertSignalLoopsToAttributes(template: string, context?: Record<string, any>): string;
+export declare function processScriptSetup(template: string, filePath?: string, serverData?: Record<string, unknown>): Promise<{
+    output: string;
+    setupCode: string | null;
+}>;
+/**
+ * Extract exported variable names from setup script.
+ * Returns variables that should be exposed to the template.
+ * Only extracts TOP-LEVEL declarations, not variables inside nested functions.
+ */
+export declare function extractExports(setupContent: string): string;
+/**
+ * Main orchestrator for signal processing.
+ *
+ * Detects signal syntax, wraps scripts in setup functions, and injects the
+ * signals runtime. Browser helpers and model bootstraps enter the same client
+ * bundle as the setup code, so rendered pages never depend on bare specifiers.
+ */
+export declare function processSignals(template: string, options: StxOptions, filePath?: string, serverData?: Record<string, unknown>): Promise<string>;
+/**
+ * Index of the first `pattern` match in `html` that is not inside a `<script>`
+ * or `<style>` block, or -1 when every match is embedded.
+ *
+ * Markup landmarks cannot be located with a plain `indexOf` / `String.replace`
+ * once a runtime has been inlined: those scripts are hundreds of kilobytes of
+ * JavaScript that legitimately mention `<body>` and `</head>` in comments,
+ * strings and regex literals. Anchoring on the first textual hit splices
+ * generated markup into the middle of a script tag, which both corrupts the
+ * script and — when the inserted markup contains `</script>` — silently ends
+ * the tag early.
+ */
+export declare function findMarkupIndexOutsideScripts(html: string, pattern: RegExp): number;
+/**
+ * Turn the specifier list of an `import { … } from 'stx'` into local aliases.
+ *
+ * The setup function already destructures the stx API from `window.stx`, so a
+ * plain `{ state }` specifier needs nothing. A RENAMED one does: when the
+ * bundler inlines a composable that imports a name the outer script already
+ * binds, it emits `import { state as state2 } from '@stacksjs/stx'`. Dropping
+ * that line loses the mapping and every `state2(…)` call in the inlined module
+ * throws `state2 is not defined` — which aborts the whole setup, so no
+ * directive on the page ever binds.
+ *
+ * Type-only specifiers are erased: they have no runtime binding to alias.
+ */
+export declare function rewriteStxImportSpecifiers(specifiers: string): string;
+/**
+ * Strip the runtime imports a bundled client script carries, keeping aliases.
+ *
+ * Every wrapper that hosts bundled client code destructures the stx API from
+ * `window.stx` first, so a plain specifier needs no binding and the line can
+ * go. A renamed one (`state as state2`) must survive as a local alias or the
+ * inlined module's calls throw.
+ *
+ * Shared by all three wrapping paths — the merged page setup below, the
+ * component renderer in utils.ts, and the include/partial renderer in
+ * includes.ts. It lives in one place because it did not: includes.ts had no
+ * strip at all, so a partial whose `<script client>` imported a composable
+ * that imports from 'stx' emitted a bare `import` into a classic script and
+ * threw `SyntaxError: Cannot use import statement outside a module`, killing
+ * that scope's hydration on every page the partial appeared on.
+ */
+export declare function stripStxRuntimeImports(code: string): string;