@stacksjs/stx 0.2.9 → 0.2.11

package/dist/reactive.d.ts

@@ -1,18 +1,4 @@
-/**
- * Process reactive directives in a template.
- *
- * Transforms `x-data`, `x-model`, `x-show`, etc. into client-side reactivity.
- *
- * @param template - The HTML template string
- * @param context - Template context
- * @param filePath - Source file path for error messages
- * @returns Processed template with reactive runtime script
- */
-export declare function processReactiveDirectives(template: string, _context: Record<string, unknown>, _filePath: string): string;
-/**
- * Check if a template contains reactive directives
- */
-export declare function hasReactiveDirectives(template: string): boolean;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * Reactive Directives Module
  *
@@ -82,7 +68,7 @@ export declare interface ReactiveScope {
 }
 export declare interface ReactiveBinding {
   elementId: string
-  type: 'model' | 'show' | 'hide' | 'text' | 'html' | 'bind' | 'class' | 'style'
+  type: 'model' | 'show' | 'hide' | 'text' | 'html' | 'bind' | 'class' | 'style' | 'event'
   expression: string
   attribute?: string
   inputType?: string

package/dist/reactivity.d.ts

@@ -207,6 +207,7 @@ export type DefineComponent<Props = {}, RawBindings = {}, D = any> = {
 /** Generic component type */
 export type Component<Props = any> = DefineComponent<Props>;
 /** Subscriber callback */
+// eslint-disable-next-line pickier/no-unused-vars
 export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void;
 /** Lifecycle hook callback */
 export type LifecycleHook = () => void | Promise<void>;

package/dist/router.d.ts

@@ -8,4 +8,4 @@ export declare interface RouterOptions {
   pagesDir?: string
   extensions?: string[]
 }
-export { findErrorPage, formatRoutes, generateRouteTypes, matchRoute } from 'stx-router';
+export { findErrorPage, formatRoutes, generateRouteManifest, generateRouteTypes, matchRoute } from 'stx-router';

package/dist/runtime-injection.d.ts

@@ -0,0 +1,20 @@
+import type { StxOptions } from './types';
+/**
+ * Inject @stacksjs/browser initialization script into the template.
+ * This sets up window.StacksBrowser for auto-imports to work.
+ *
+ * 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;
+/**
+ * Inject STX signals runtime into the template.
+ * The runtime provides client-side reactivity.
+ */
+export declare function injectSignalsRuntime(template: string, options: StxOptions): Promise<string>;
+/**
+ * Inject the SPA router script into the template.
+ * The router is provided by the canonical router in packages/router/src/client.ts.
+ * It guards against double-initialization so it's safe to inject alongside @stxRouter.
+ */
+export declare function injectRouterScript(template: string, options?: StxOptions): Promise<string>;

package/dist/runtime.d.ts

@@ -9,9 +9,9 @@
  * appStore.setState({ count: appStore.state.count + 1 })
  * ```
  */
-export declare function useStore<T = unknown>(name: string): StoreRef<T> | null;
+export declare function useStore<T = unknown>(name: string): StoreRef<T>;
 /**
- * Get a store, throwing if not found
+ * @deprecated Use `useStore` — it now throws if the store is not found.
  */
 export declare function useStoreOrThrow<T = unknown>(name: string): StoreRef<T>;
 /**

package/dist/script-classifier.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Classify a `<script>` tag as signals, client, or server.
+ *
+ * Classification rules (in priority order):
+ * 1. Explicit `server` attribute → server
+ * 2. Uses signals API (state, derived, effect, etc.) → signals
+ * 3. Has `client` attribute, `type="module"`, or `src=` → client
+ * 4. Everything else → server (executed at build time for variable extraction)
+ */
+export declare function classifyScript(attrs: string, content: string, fullTag: string): ScriptClassification;
+/**
+ * Classify all `<script>` tags in a template.
+ *
+ * Returns arrays of scripts grouped by type.
+ */
+export declare function classifyAllScripts(content: string): {
+  signals: ScriptClassification[]
+  client: ScriptClassification[]
+  server: ScriptClassification[]
+};
+export declare interface ScriptClassification {
+  type: ScriptType
+  fullTag: string
+  content: string
+  attrs: string
+}
+/**
+ * Script Classification
+ *
+ * Single source of truth for classifying `<script>` tags in `.stx` files.
+ * Used by bun-plugin, dev-server, and process.ts to ensure consistent behavior.
+ *
+ * @module script-classifier
+ */
+export type ScriptType = 'signals' | 'client' | 'server';

package/dist/script-validation.d.ts

@@ -0,0 +1,16 @@
+import type { StrictModeConfig } from './types';
+/**
+ * Validate client script content for prohibited DOM API patterns.
+ * When strict mode is enabled with `failOnViolation`, throws an error.
+ * Otherwise, emits warnings.
+ *
+ * @param content - The script content to validate
+ * @param filePath - The file path for error reporting
+ * @param strict - Strict mode configuration
+ */
+export declare function validateClientScript(content: string, filePath: string, strict?: boolean | StrictModeConfig): void;
+/**
+ * Prohibited DOM API patterns in client scripts.
+ * STX provides Vue-style alternatives via the STX global object.
+ */
+export declare const PROHIBITED_DOM_PATTERNS: readonly [unknown];

package/dist/server-bindings.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Process server-side `:attr="expr"` bindings in a template.
+ *
+ * Called after server scripts have executed and before expression processing,
+ * so the context contains all server-side variables.
+ */
+export declare function processServerBindings(template: string, context: Record<string, any>): string;

package/dist/server-components.d.ts

@@ -39,6 +39,10 @@ export declare function renderClientComponent(name: string, options?: RenderOpti
  * Render any registered component.
  */
 export declare function renderComponent(name: string, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Clean up resolved/errored suspense states to prevent memory leaks.
+ */
+export declare function cleanupSuspenseStates(): void;
 /**
  * Create a suspense boundary.
  */

package/dist/signal-processing.d.ts

@@ -0,0 +1,109 @@
+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 declare function scanScriptTags(html: string, opts?: { skipAttrs?: RegExp }): Array<{ fullMatch: string, attrs: string, body: string, start: number, end: number }>;
+/**
+ * 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): 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.
+ *
+ * Converts:
+ *   @if(loading())
+ *     <div>Loading...</div>
+ *   @endif
+ *
+ * To:
+ *   <template @if="loading()">
+ *     <div>Loading...</div>
+ *   </template>
+ *
+ * Note: Uses <template> wrapper for blocks with multiple children or text nodes.
+ */
+export declare function convertSignalDirectivesToAttributes(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): 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,
+ * injects the signals runtime and browser runtime.
+ */
+export declare function processSignals(template: string, options: StxOptions, filePath?: string): Promise<string>;
+/**
+ * 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 declare interface ParsedLoopExpression {
+  style: 'as' | 'in' | 'unknown'
+  iterable: string | null
+  itemVar: string | null
+  indexVar: string | null
+}

package/dist/signals-api.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Creates a reactive state signal.
+ *
+ * State signals are the foundation of STX reactivity. They hold a value that,
+ * when changed, automatically updates any derived signals or effects that
+ * depend on it.
+ *
+ * @param initialValue - The initial value for the signal
+ * @returns A signal that can be read, set, and subscribed to
+ *
+ * @example Basic usage
+ * ```typescript
+ * const count = state(0)
+ *
+ * // Read the value
+ * console.log(count())  // 0
+ *
+ * // Set a new value
+ * count.set(5)
+ * console.log(count())  // 5
+ *
+ * // Update based on current value
+ * count.update(n => n + 1)
+ * console.log(count())  // 6
+ * ```
+ *
+ * @example With objects
+ * ```typescript
+ * const user = state({ name: 'Alice', age: 30 })
+ *
+ * // Update the whole object
+ * user.set({ name: 'Bob', age: 25 })
+ *
+ * // Or update a property (creates new object for immutability)
+ * user.update(u => ({ ...u, age: u.age + 1 }))
+ * ```
+ *
+ * @example With arrays
+ * ```typescript
+ * const items = state<string[]>([])
+ *
+ * // Add an item
+ * items.update(arr => [...arr, 'new item'])
+ *
+ * // Remove an item
+ * items.update(arr => arr.filter(i => i !== 'remove me'))
+ * ```
+ */
+export declare function state<T>(initialValue: T): Signal<T>;
+/**
+ * Creates a derived signal that automatically computes its value from other signals.
+ *
+ * Derived signals are lazy - they only recompute when read after a dependency
+ * has changed. They're perfect for computed values that depend on other state.
+ *
+ * @param compute - A function that computes the derived value
+ * @returns A read-only signal with the computed value
+ *
+ * @example Basic derived value
+ * ```typescript
+ * const count = state(5)
+ * const doubled = derived(() => count() * 2)
+ *
+ * console.log(doubled())  // 10
+ * count.set(10)
+ * console.log(doubled())  // 20
+ * ```
+ *
+ * @example Combining multiple signals
+ * ```typescript
+ * const firstName = state('John')
+ * const lastName = state('Doe')
+ *
+ * const fullName = derived(() => `${firstName()} ${lastName()}`)
+ * console.log(fullName())  // "John Doe"
+ * ```
+ *
+ * @example Filtering and transforming
+ * ```typescript
+ * const items = state([1, 2, 3, 4, 5])
+ * const filter = state('even')
+ *
+ * const filteredItems = derived(() => {
+ *   const list = items()
+ *   return filter() === 'even'
+ *     ? list.filter(n => n % 2 === 0)
+ *     : list.filter(n => n % 2 !== 0)
+ * })
+ * ```
+ */
+export declare function derived<T>(compute: () => T): DerivedSignal<T>;
+/**
+ * Creates a side effect that runs when its dependencies change.
+ *
+ * Effects automatically track which signals they read and re-run whenever
+ * those signals change. They're perfect for syncing state with external
+ * systems, logging, or triggering side effects.
+ *
+ * @param fn - The effect function to run
+ * @param options - Optional configuration
+ * @returns A cleanup function to stop the effect
+ *
+ * @example Basic effect
+ * ```typescript
+ * const count = state(0)
+ *
+ * effect(() => {
+ *   console.log(`Count changed to: ${count()}`)
+ * })
+ *
+ * count.set(1)  // Logs: "Count changed to: 1"
+ * count.set(2)  // Logs: "Count changed to: 2"
+ * ```
+ *
+ * @example Effect with cleanup
+ * ```typescript
+ * const isActive = state(true)
+ *
+ * effect(() => {
+ *   if (isActive()) {
+ *     const interval = setInterval(() => console.log('tick'), 1000)
+ *     // Return cleanup function
+ *     return () => clearInterval(interval)
+ *   }
+ * })
+ * ```
+ *
+ * @example Fetching data
+ * ```typescript
+ * const userId = state(1)
+ * const user = state(null)
+ *
+ * effect(async () => {
+ *   const id = userId()
+ *   const response = await fetch(`/api/users/${id}`)
+ *   user.set(await response.json())
+ * })
+ * ```
+ */
+export declare function effect(fn: () => void | CleanupFn, options?: EffectOptions): CleanupFn;
+/**
+ * Batches multiple signal updates into a single effect run.
+ *
+ * Use this when updating multiple signals at once to avoid redundant
+ * effect executions.
+ *
+ * @param fn - Function containing multiple signal updates
+ *
+ * @example
+ * ```typescript
+ * const firstName = state('John')
+ * const lastName = state('Doe')
+ *
+ * // Without batch: effect runs twice
+ * // With batch: effect runs once
+ * batch(() => {
+ *   firstName.set('Jane')
+ *   lastName.set('Smith')
+ * })
+ * ```
+ */
+export declare function batch(fn: () => void): void;
+/**
+ * Registers a callback to run when the component mounts (is inserted into the DOM).
+ *
+ * @param callback - Function to run on mount. Can return a cleanup function.
+ *
+ * @example
+ * ```typescript
+ * onMount(() => {
+ *   console.log('Component is now in the DOM')
+ *
+ *   // Optional: return cleanup function
+ *   return () => console.log('Cleanup on unmount')
+ * })
+ * ```
+ *
+ * @example Fetching initial data
+ * ```typescript
+ * const data = state(null)
+ *
+ * onMount(async () => {
+ *   data.set(await fetchInitialData())
+ * })
+ * ```
+ */
+export declare function onMount(callback: LifecycleCallback): void;
+/**
+ * Registers a callback to run when the component is destroyed (removed from the DOM).
+ *
+ * @param callback - Function to run on destroy
+ *
+ * @example
+ * ```typescript
+ * onDestroy(() => {
+ *   console.log('Component is being removed')
+ *   // Clean up subscriptions, timers, etc.
+ * })
+ * ```
+ */
+export declare function onDestroy(callback: LifecycleCallback): void;
+/**
+ * Checks if a value is a signal.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a signal
+ *
+ * @example
+ * ```typescript
+ * const count = state(0)
+ * isSignal(count)  // true
+ * isSignal(5)      // false
+ * ```
+ */
+export declare function isSignal(value: unknown): value is Signal<unknown>;
+/**
+ * Checks if a value is a derived signal.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a derived signal
+ */
+export declare function isDerived(value: unknown): value is DerivedSignal<unknown>;
+/**
+ * Unwraps a signal to get its raw value.
+ * If the value is not a signal, returns it as-is.
+ *
+ * @param value - A signal or plain value
+ * @returns The unwrapped value
+ *
+ * @example
+ * ```typescript
+ * const count = state(5)
+ * untrack(count)  // 5
+ * untrack(10)     // 10
+ * ```
+ */
+export declare function untrack<T>(value: T | Signal<T> | DerivedSignal<T>): T;
+/**
+ * Reads a signal's value without tracking it as a dependency.
+ *
+ * Use this when you need to read a signal inside an effect but don't want
+ * the effect to re-run when that signal changes.
+ *
+ * @param fn - Function to run without tracking
+ * @returns The function's return value
+ *
+ * @example
+ * ```typescript
+ * const count = state(0)
+ * const other = state(0)
+ *
+ * effect(() => {
+ *   // This effect only re-runs when `count` changes
+ *   console.log(count())
+ *
+ *   // Reading `other` without tracking
+ *   const otherValue = peek(() => other())
+ * })
+ * ```
+ */
+export declare function peek<T>(fn: () => T): T;
+/**
+ * A reactive state signal.
+ *
+ * Call it to read the value, use `.set()` to write, or `.update()` to transform.
+ *
+ * @example
+ * ```typescript
+ * const count = state(0)
+ * count()           // Read: 0
+ * count.set(5)      // Write: 5
+ * count.update(n => n + 1)  // Update: 6
+ * ```
+ */
+export declare interface Signal<T> {
+  (): T
+  set(value: T): void
+  update(fn: (current: T) => T): void
+  subscribe(callback: (value: T, prev: T) => void): () => void
+  readonly _isSignal: true
+}
+/**
+ * A derived (computed) signal that automatically updates when dependencies change.
+ *
+ * @example
+ * ```typescript
+ * const doubled = derived(() => count() * 2)
+ * doubled()  // Read the computed value
+ * ```
+ */
+export declare interface DerivedSignal<T> {
+  (): T
+  readonly _isDerived: true
+}
+/**
+ * Options for creating effects.
+ */
+export declare interface EffectOptions {
+  immediate?: boolean
+  name?: string
+}
+/**
+ * Cleanup function returned by effects.
+ */
+export type CleanupFn = () => void;
+/**
+ * Lifecycle hook callback.
+ */
+export type LifecycleCallback = () => void | CleanupFn | Promise<void>;