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

package/dist/runtime-injection.js

@@ -0,0 +1,156 @@
+import { headInsertionPoint } from "./head-injection.js";
+import { BROWSER_CORE_IMPORTS } from "./browser-core-imports.js";
+import { getOwnedRouteMatchers } from "./owned-routes.js";
+import { toScriptJson } from "./script-json.js";
+import { findBodyOpenTag, replaceBodyOpenTag } from "./find-body-tag.js";
+import { getTooltipRuntime } from "./builtins/tooltip.js";
+export function injectBrowserRuntime(template) {
+  const alreadyBootstrapped = /import\s+['"]@stacksjs\/browser['"]/.test(template), pageSuppliesGlobal = /\bStacksBrowser\s*=[^=]/.test(template);
+  if (alreadyBootstrapped || pageSuppliesGlobal)
+    return template;
+  const clientScriptRegex = /<script\b(?![^>]*\bserver\b)[^>]*>([\s\S]*?)<\/script>/gi;
+  let clientCode = "", match;
+  while ((match = clientScriptRegex.exec(template)) !== null)
+    clientCode += match[1] + `
+`;
+  const templateExprRegex = /\{\{([\s\S]*?)\}\}/g;
+  while ((match = templateExprRegex.exec(template)) !== null)
+    clientCode += match[1] + `
+`;
+  if (!clientCode.trim())
+    return template;
+  const usesCoreSymbols = BROWSER_CORE_IMPORTS.some((sym) => {
+    return new RegExp(`\\b${sym}\\b`).test(clientCode);
+  }), jsBuiltins = new Set(["Promise", "Object", "Array", "Map", "Set", "Date", "Error", "JSON", "Math", "Number", "String", "RegExp", "Symbol", "WeakMap", "WeakSet", "Proxy", "Reflect", "Intl", "URL", "URLSearchParams", "FormData", "Headers", "Request", "Response", "AbortController", "EventTarget", "Element", "Document", "Node", "Window", "Console", "Storage", "Navigator", "Blob", "File", "FileReader", "HTMLElement", "SVGElement", "Event", "CustomEvent", "DOMParser", "XMLSerializer", "WebSocket", "Worker", "SharedWorker", "IntersectionObserver", "MutationObserver", "ResizeObserver", "PerformanceObserver", "Notification", "Bun", "Buffer", "Process"]), modelPattern = /\b([A-Z][a-zA-Z0-9]*)\s*\.\s*(all|find|first|get|where|orderBy|orderByDesc|limit|select|pluck|create|update|delete)\s*\(/g;
+  let modelMatch, usesModels = !1;
+  while ((modelMatch = modelPattern.exec(clientCode)) !== null)
+    if (!jsBuiltins.has(modelMatch[1])) {
+      usesModels = !0;
+      break;
+    }
+  if (!usesCoreSymbols && !usesModels)
+    return template;
+  const browserScript = `<script type="module">
+// STX: Auto-load @stacksjs/browser (auto-initializes API and loads models)
+import '@stacksjs/browser'
+</script>`;
+  if (template.includes("</head>")) {
+    const headEndPos = template.indexOf("</head>"), firstScriptPos = template.slice(0, headEndPos).indexOf("<script");
+    if (firstScriptPos !== -1)
+      return template.slice(0, firstScriptPos) + browserScript + `
+` + template.slice(firstScriptPos);
+    return template.replace("</head>", `${browserScript}
+</head>`);
+  }
+  if (findBodyOpenTag(template))
+    return replaceBodyOpenTag(template, (tag) => `${tag}
+${browserScript}`);
+  return browserScript + `
+` + template;
+}
+export function pageShipsSignalsRuntime(fullPageHtml) {
+  return fullPageHtml.includes("data-stx-runtime");
+}
+export function outputNeedsSignalsRuntime(html) {
+  const reach = /window\.stx\s*\.\s*[A-Za-z_$]|\}\s*=\s*window\.stx\s*;/g;
+  for (let m = reach.exec(html);m !== null; m = reach.exec(html)) {
+    const preceding = html.slice(Math.max(0, m.index - 80), m.index);
+    if (/if\s*\(\s*window\.stx\s*\)|window\.stx\s*&&/.test(preceding))
+      continue;
+    return !0;
+  }
+  return !1;
+}
+function placeRuntimeTag(template, runtimeScript) {
+  const firstScript = template.indexOf("<script"), doctype = template.search(/<!doctype\b/i);
+  if (firstScript !== -1 && (doctype === -1 || firstScript > doctype))
+    return template.slice(0, firstScript) + runtimeScript + `
+` + template.slice(firstScript);
+  const headAt = headInsertionPoint(template);
+  if (headAt !== null)
+    return `${template.slice(0, headAt)}
+${runtimeScript}${template.slice(headAt)}`;
+  if (template.includes("</head>")) {
+    const idx = template.indexOf("</head>");
+    return template.slice(0, idx) + runtimeScript + `
+` + template.slice(idx);
+  }
+  if (findBodyOpenTag(template))
+    return replaceBodyOpenTag(template, (tag) => `${tag}
+${runtimeScript}`);
+  return `${runtimeScript}
+${template}`;
+}
+export async function injectSignalsRuntime(template, options) {
+  if (template.includes("data-stx-runtime") || template.includes("window.stx.state") || template.includes("STX Signals Runtime"))
+    return template;
+  if (options.buildMode === "serve")
+    return placeRuntimeTag(template, '<script data-stx-runtime src="/_stx/runtime.js"></script>');
+  if (options.buildMode === "compile")
+    return placeRuntimeTag(template, '<script data-stx-runtime src="/__stx/runtime.__STX_HASH__.js"></script>');
+  const { getCachedSignalsRuntime } = await import("./caching.js"), runtime = await getCachedSignalsRuntime(options.debug);
+  return placeRuntimeTag(template, `<script data-stx-scoped data-stx-runtime>${runtime}</script>`);
+}
+export function outputNeedsTooltipRuntime(html) {
+  return /<[a-z][^>]*?\sx-tooltip\s*=/i.test(html);
+}
+export function injectTooltipRuntime(html) {
+  if (html.includes("data-stx-tooltip-runtime") || !outputNeedsTooltipRuntime(html))
+    return html;
+  const tag = `<script data-stx-scoped data-stx-tooltip-runtime>${getTooltipRuntime()}</script>`, bodyIdx = html.lastIndexOf("</body>");
+  if (bodyIdx === -1)
+    return `${html}
+${tag}`;
+  return `${html.slice(0, bodyIdx)}${tag}
+${html.slice(bodyIdx)}`;
+}
+const ROUTER_SCRIPT_TAG = /<script\b[^>]*\sdata-stx-router(?=[\s=>])/i;
+export function hasRouterScript(template) {
+  return ROUTER_SCRIPT_TAG.test(template) || template.includes("__stxRouter)return") || template.includes("__stxRouter=true");
+}
+export async function injectRouterScript(template, options) {
+  if (!template.includes("</body>"))
+    return template;
+  if (hasRouterScript(template))
+    return template;
+  const routerConfig = options?.router;
+  let configScript = "";
+  {
+    const configObj = {};
+    if (routerConfig) {
+      if (routerConfig.container)
+        configObj.container = routerConfig.container;
+      if (routerConfig.interceptAllLinks !== void 0)
+        configObj.interceptAllLinks = routerConfig.interceptAllLinks;
+      if (routerConfig.progress !== void 0)
+        configObj.progress = routerConfig.progress;
+      if (routerConfig.viewTransitions !== void 0)
+        configObj.viewTransitions = routerConfig.viewTransitions;
+      if (routerConfig.viewTransitionDuration !== void 0)
+        configObj.viewTransitionDuration = routerConfig.viewTransitionDuration;
+      if (routerConfig.viewTransitionEasing !== void 0)
+        configObj.viewTransitionEasing = routerConfig.viewTransitionEasing;
+      if (routerConfig.scrollToTop !== void 0)
+        configObj.scrollToTop = routerConfig.scrollToTop;
+      if (routerConfig.prefetch !== void 0)
+        configObj.prefetch = routerConfig.prefetch;
+      if (routerConfig.cache !== void 0)
+        configObj.cache = routerConfig.cache;
+      if (routerConfig.progressColor !== void 0)
+        configObj.progressColor = routerConfig.progressColor;
+      if (routerConfig.progressHeight !== void 0)
+        configObj.progressHeight = routerConfig.progressHeight;
+    }
+    try {
+      const owned = await getOwnedRouteMatchers(options?.pagesDir);
+      if (owned.length > 0)
+        configObj.ownedRoutes = owned;
+    } catch {}
+    if (Object.keys(configObj).length > 0)
+      configScript = `<script>window.__stxRouterConfig=${toScriptJson(configObj)};</script>
+`;
+  }
+  const { getCachedRouterScript } = await import("./caching.js"), routerScript = options?.buildMode === "compile" ? '<script data-stx-router src="/__stx/router.__STX_HASH__.js"></script>' : options?.buildMode === "serve" ? '<script data-stx-router src="/_stx/router.js"></script>' : `<script data-stx-router>${await getCachedRouterScript()}</script>`, bodyCloseIdx = template.lastIndexOf("</body>");
+  return template.slice(0, bodyCloseIdx) + configScript + routerScript + `
+</body>` + template.slice(bodyCloseIdx + 7);
+}

package/dist/runtime.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Get a store by name
+ *
+ * @example
+ * ```ts
+ * const appStore = useStore('appStore')
+ * console.log(appStore.state.count)
+ *
+ * appStore.setState({ count: appStore.state.count + 1 })
+ * ```
+ */
+export declare function useStore<T = unknown>(name: string): StoreRef<T>;
+/**
+ * @deprecated Use `useStore` — it now throws if the store is not found.
+ */
+export declare function useStoreOrThrow<T = unknown>(name: string): StoreRef<T>;
+/**
+ * Check if a store exists
+ */
+export declare function hasStore(name: string): boolean;
+/**
+ * Get all store names
+ */
+export declare function getStoreNames(): string[];
+/**
+ * Wait for a store to be ready (for async initialization)
+ */
+export declare function waitForStore<T = unknown>(name: string, timeout?: number): Promise<StoreRef<T>>;
+/**
+ * Get current route parameters
+ *
+ * @example
+ * ```ts
+ * // URL: /users/123
+ * const params = useRouteParams()
+ * console.log(params.id) // '123'
+ * ```
+ */
+export declare function useRouteParams(): RouteParams;
+/**
+ * Get a specific route parameter
+ *
+ * @example
+ * ```ts
+ * const userId = useRouteParam('id')
+ * ```
+ */
+export declare function useRouteParam(name: string): string | undefined;
+/**
+ * Get a route parameter or throw if missing
+ */
+export declare function useRouteParamOrThrow(name: string): string;
+/**
+ * Get state passed from middleware
+ *
+ * @example
+ * ```ts
+ * // In middleware:
+ * ctx.state.user = { id: 1, name: 'John' }
+ *
+ * // In component:
+ * const state = useMiddlewareState()
+ * console.log(state.user)
+ * ```
+ */
+export declare function useMiddlewareState<T = MiddlewareState>(): T;
+/**
+ * Get a specific middleware state value
+ */
+export declare function useMiddlewareValue<T = unknown>(key: string): T | undefined;
+/**
+ * @internal
+ * Initialize the store registry
+ */
+export declare function initStoreRegistry(): void;
+/**
+ * @internal
+ * Register a store in the registry
+ */
+export declare function registerStore(name: string, store: StoreRef): void;
+/**
+ * @internal
+ * Get serialized store state for hydration
+ */
+export declare function getHydratedStoreState(): Record<string, unknown> | null;
+/**
+ * @internal
+ * Set route params (called by router)
+ */
+export declare function setRouteParams(params: RouteParams): void;
+/**
+ * @internal
+ * Set middleware state (called by middleware runner)
+ */
+export declare function setMiddlewareState(state: MiddlewareState): void;
+/**
+ * Check if running on the server
+ */
+export declare function isServer(): boolean;
+/**
+ * Check if running on the client
+ */
+export declare function isClient(): boolean;
+/**
+ * Run callback only on client
+ *
+ * @example
+ * ```ts
+ * onClient(() => {
+ *   document.title = 'Hello'
+ * })
+ * ```
+ */
+export declare function onClient(callback: () => void): void;
+/**
+ * Run callback only on server
+ */
+export declare function onServer(callback: () => void): void;
+// =============================================================================
+// Store Access
+// =============================================================================
+export declare interface StoreRef<T = unknown> {
+  state: T
+  getState: () => T
+  setState: (updater: Partial<T> | ((state: T) => Partial<T>)) => void
+  subscribe: (listener: (state: T) => void) => () => void
+  reset: () => void
+}
+// =============================================================================
+// Route Params
+// =============================================================================
+export declare interface RouteParams {
+  [key: string]: string
+}
+// =============================================================================
+// Middleware State
+// =============================================================================
+export declare interface MiddlewareState {
+  [key: string]: unknown
+}

package/dist/runtime.js

@@ -0,0 +1,94 @@
+const STX_STORES_KEY = "__STX_STORES__", STX_ROUTE_PARAMS_KEY = "__STX_ROUTE_PARAMS__", STX_MIDDLEWARE_STATE_KEY = "__STX_MIDDLEWARE_STATE__", STX_HYDRATE_STORES_KEY = "__STX_HYDRATE_STORES__", STX_STORE_STATE_KEY = "__STX_STORE_STATE__";
+function getGlobal(key, defaultValue) {
+  if (typeof window > "u")
+    return defaultValue;
+  return window[key] ?? defaultValue;
+}
+function setGlobal(key, value) {
+  if (typeof window > "u")
+    return;
+  window[key] = value;
+}
+export function useStore(name) {
+  const store = getGlobal(STX_STORES_KEY, {})[name];
+  if (!store)
+    throw Error(`Store "${name}" not found. Make sure it's defined with defineStore().`);
+  return store;
+}
+export function useStoreOrThrow(name) {
+  return useStore(name);
+}
+export function hasStore(name) {
+  const stores = getGlobal(STX_STORES_KEY, {});
+  return name in stores;
+}
+export function getStoreNames() {
+  const stores = getGlobal(STX_STORES_KEY, {});
+  return Object.keys(stores);
+}
+export function waitForStore(name, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now(), check = () => {
+      const store = useStore(name);
+      if (store)
+        resolve(store);
+      else if (Date.now() - startTime > timeout)
+        reject(Error(`Timeout waiting for store "${name}"`));
+      else
+        requestAnimationFrame(check);
+    };
+    check();
+  });
+}
+export function useRouteParams() {
+  return getGlobal(STX_ROUTE_PARAMS_KEY, {});
+}
+export function useRouteParam(name) {
+  return useRouteParams()[name];
+}
+export function useRouteParamOrThrow(name) {
+  const value = useRouteParam(name);
+  if (value === void 0)
+    throw Error(`Route parameter "${name}" not found`);
+  return value;
+}
+export function useMiddlewareState() {
+  return getGlobal(STX_MIDDLEWARE_STATE_KEY, {});
+}
+export function useMiddlewareValue(key) {
+  return useMiddlewareState()[key];
+}
+export function initStoreRegistry() {
+  if (typeof window > "u")
+    return;
+  if (!getGlobal(STX_STORES_KEY, null))
+    setGlobal(STX_STORES_KEY, {});
+}
+export function registerStore(name, store) {
+  const stores = getGlobal(STX_STORES_KEY, {});
+  stores[name] = store;
+  setGlobal(STX_STORES_KEY, stores);
+}
+export function getHydratedStoreState() {
+  return getGlobal(STX_STORE_STATE_KEY, null);
+}
+export function setRouteParams(params) {
+  setGlobal(STX_ROUTE_PARAMS_KEY, params);
+}
+export function setMiddlewareState(state) {
+  setGlobal(STX_MIDDLEWARE_STATE_KEY, state);
+}
+export function isServer() {
+  return typeof window > "u";
+}
+export function isClient() {
+  return typeof window < "u";
+}
+export function onClient(callback) {
+  if (isClient())
+    callback();
+}
+export function onServer(callback) {
+  if (isServer())
+    callback();
+}

package/dist/safe-evaluator.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Safe expression evaluator that reduces security risks from using new Function()
+ */
+/**
+ * Safe evaluator configuration options
+ */
+export interface SafeEvaluatorConfig {
+    /** Maximum depth for object sanitization (default: 10) */
+    maxSanitizeDepth: number;
+    /**
+     * Allow bracket notation with string literals like `obj["key"]` (default: false).
+     *
+     * SECURITY WARNING: Enabling bracket notation broadens the attack surface.
+     * Bracket notation can access properties that dot-notation filters block
+     * (e.g. `obj["__proto__"]`, `obj["constructor"]`), and a dynamic key path
+     * assembled at runtime (`obj[userInput]`) cannot be statically proven safe.
+     * Only enable when all bracket keys are known string literals authored by
+     * the template writer — never based on untrusted input.
+     */
+    allowBracketNotation: boolean;
+}
+/**
+ * Configure the safe evaluator
+ *
+ * @example
+ * ```typescript
+ * configureSafeEvaluator({
+ *   maxSanitizeDepth: 20,
+ *   allowBracketNotation: true
+ * })
+ * ```
+ */
+export declare function configureSafeEvaluator(config: Partial<SafeEvaluatorConfig>): void;
+/**
+ * Reset configuration to defaults
+ */
+export declare function resetSafeEvaluatorConfig(): void;
+/**
+ * Get current configuration
+ */
+export declare function getSafeEvaluatorConfig(): SafeEvaluatorConfig;
+/**
+ * Sanitize an expression by checking for dangerous patterns
+ */
+export declare function sanitizeExpression(expression: string): string;
+/**
+ * Create a safer context object that only exposes safe properties
+ */
+export declare function createSafeContext(context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Safely evaluate an expression with the given context
+ *
+ * @param expression - The JavaScript expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns The result of the expression evaluation, or undefined on error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = safeEvaluate('name.toUpperCase()', { name: 'hello' })
+ *
+ * // With type parameter for typed result
+ * const count = safeEvaluate<number>('items.length', { items: [1, 2, 3] })
+ * ```
+ */
+export declare function safeEvaluate<T = unknown>(expression: string, context: Record<string, unknown>): T | undefined;
+/**
+ * Check if an expression is safe to evaluate
+ */
+export declare function isExpressionSafe(expression: string): boolean;
+/**
+ * Return the reason an expression is unsafe, or `null` if it passes all
+ * sanitization checks. Useful for tooling and debugging — lets callers
+ * report a structured reason without `try/catch`ing sanitize errors.
+ *
+ * @example
+ * getExpressionSafetyReason('eval(x)') // → 'matched pattern /\\beval\\b/'
+ * getExpressionSafetyReason('a + b')   // → null
+ */
+export declare function getExpressionSafetyReason(expression: string): string | null;
+/**
+ * Safely evaluate an expression and return a boolean result
+ * Used for conditional expressions in @if, @unless, etc.
+ *
+ * @param expression - The condition expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Boolean result, defaults to false on error
+ */
+export declare function safeEvaluateCondition(expression: string, context: Record<string, unknown>): boolean;
+/**
+ * Safely evaluate an expression that returns an array
+ * Used for loop iterations in @foreach, @for, etc.
+ *
+ * @param expression - The array expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Array result, defaults to empty array on error
+ */
+export declare function safeEvaluateArray(expression: string, context: Record<string, unknown>): unknown[];
+/**
+ * Safely evaluate an expression that returns an object
+ * Used for props, attributes, configuration objects
+ *
+ * @param expression - The object expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Object result, defaults to empty object on error
+ */
+export declare function safeEvaluateObject(expression: string, context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The variables an expression actually reads from its surrounding scope.
+ *
+ * Deliberately not every identifier in the string. A property name is not a
+ * variable, and treating it as one is how `:label="section.label"` came to be
+ * misclassified: the section had no `label`, the expression evaluated to
+ * `undefined`, and the check for "does this reference something the server
+ * does not have?" found `label` — a key, not a binding — reported it as
+ * unresolved, and shipped the expression to the client as a reactive prop.
+ *
+ * On the client it could never resolve either: `section` is a server-side
+ * `@foreach` variable that does not exist in the browser. So every page with a
+ * component in a loop and one absent optional prop logged stx's own hydration
+ * invariant, once per prop, forever.
+ *
+ * Three things are stripped before identifiers are read: string contents, so a
+ * word inside a quote is not a variable; member access after `.` or `?.`, so a
+ * property is not a variable; and object-literal keys, for the same reason.
+ * What is left is the free variables, which is the question actually being
+ * asked.
+ */
+export declare function freeIdentifiers(expression: string): string[];
+/**
+ * Whether `name` can be a `new Function` parameter name.
+ *
+ * Rejects the three classes JS refuses: non-identifiers (`data-id`, `1bad`),
+ * reserved words (`class`, `true`, `if`) and strict-mode-reserved words
+ * (`let`, `static`) -- the bodies here are always strict.
+ *
+ * Exported because every caller that spreads a template context into
+ * `new Function` needs exactly this test, and a near-miss copy is worse than
+ * none: an `isIdentifier`-only filter in variable-extractor.ts let `true`
+ * through, and one such key threw before the function was built, so the whole
+ * server script of six shipped components fell back to static extraction on
+ * every render (stacksjs/stx#1945 profiling, found via the fallback's cost).
+ */
+export declare function isUsableParamName(name: string): boolean;
+export declare function createSafeFunction(expression: string, contextKeys: string[]): (...args: unknown[]) => unknown;
+export declare function safeEvaluateCode(code: string, context: Record<string, unknown>): unknown;
+/**
+ * Validate a for loop expression for safety
+ * Checks for dangerous patterns like eval, Function, import, etc.
+ *
+ * @param expression - The for loop expression (e.g., "let i = 0; i < n; i++")
+ * @returns true if safe, false if potentially dangerous
+ */
+export declare function isForExpressionSafe(expression: string): boolean;
+/**
+ * Create a safe loop function with iteration limits
+ *
+ * @param loopType - 'for' or 'while'
+ * @param expression - The loop expression or condition
+ * @param body - The loop body template
+ * @param contextKeys - Variable names available in context
+ * @param maxIterations - Maximum iterations allowed (for while loops)
+ * @returns A function that executes the loop safely
+ */
+export declare function createSafeLoopFunction(loopType: 'for' | 'while', expression: string, body: string, contextKeys: string[], maxIterations?: number): (...args: unknown[]) => string;