@stacksjs/stx 0.2.155 → 0.2.157

package/dist/sfc-template.d.ts

@@ -1,5 +1,3 @@
-export declare function isClientTemplateTag(openingTag: string): boolean;
-export declare function findSfcTemplateBlock(source: string): SfcTemplateBlock | null;
 /**
  * Locate the explicit wrapper `<template>` in an STX single-file component.
  *
@@ -8,10 +6,12 @@ export declare function findSfcTemplateBlock(source: string): SfcTemplateBlock |
  * and must stay in the rendered body. Keeping this distinction in one scanner
  * avoids subtle regex boundary bugs for punctuation-prefixed attributes.
  */
-export declare interface SfcTemplateBlock {
-  start: number
-  openEnd: number
-  closeStart: number
-  end: number
-  content: string
+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/signal-processing.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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
@@ -14,7 +23,28 @@ import type { StxOptions } from './types';
  * `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 }>;
+export declare function scanScriptTags(html: string, opts?: {
+    skipAttrs?: RegExp;
+}): Array<{
+    fullMatch: string;
+    attrs: string;
+    body: string;
+    start: number;
+    end: number;
+}>;
+/**
+ * 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.
  *
@@ -118,7 +148,10 @@ export declare function preEvalLiteralReactiveIfs(template: string): string;
  *   </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 }>;
+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.
@@ -160,16 +193,3 @@ export declare function findMarkupIndexOutsideScripts(html: string, pattern: Reg
  * Type-only specifiers are erased: they have no runtime binding to alias.
  */
 export declare function rewriteStxImportSpecifiers(specifiers: string): 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

@@ -1,3 +1,109 @@
+/**
+ * STX Signals API — module-import path for reactive primitives.
+ * =============================================================
+ *
+ * This module exports `state`, `derived`, `effect`, `batch`, `untrack`,
+ * `peek`, `isSignal`, `isDerived`, `onMount`, `onDestroy` as standalone
+ * TypeScript functions. They have their own subscriber sets, effect
+ * tracking, and batching — fully self-contained reactivity.
+ *
+ * ## Why this exists alongside `signals.ts`
+ *
+ * stx ships TWO independent reactive implementations:
+ *
+ *   1. **This file (`signals-api.ts`)** — module-import path. Used by
+ *      composables, stores, SSR/server code, and tests that import
+ *      from `'@stacksjs/stx'` and run in Node (or browser) without
+ *      going through the stx bundler.
+ *
+ *   2. **The runtime template literal in `signals.ts`** — generated as
+ *      a JS string and injected into client pages. Owns its own
+ *      subscribers; populates `window.stx.{state, derived, …}`.
+ *
+ * The stx bundler rewrites `<script client>` imports of these symbols
+ * to destructure from `window.stx`. So a `const count = state(0)` in a
+ * client script ends up using the runtime version (#2). The same call
+ * in an unbundled context — a composable test, an SSR helper — uses
+ * this file (#1).
+ *
+ * **Important**: signals created in one impl are invisible to the other.
+ * A `state()` returned by this module cannot be `.set()`-ed from inside
+ * a client page's `<script>` block (and vice versa). The two reactive
+ * worlds are disjoint by design — they exist because bundled and
+ * non-bundled contexts need different code-generation strategies.
+ *
+ * ## Parity contract
+ *
+ * Both implementations expose the same public surface and must behave
+ * equivalently. Pinned by `test/reactivity/dual-impl-parity.test.ts`,
+ * which executes the same suite against both. When parity drifts, fix
+ * the lagging side — don't update only one.
+ *
+ * See stacksjs/stx#1712 for the architectural rationale.
+ *
+ * @module signals-api
+ */
+/**
+ * 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 interface Signal<T> {
+    /** Read the current value */
+    (): T;
+    /** Vue-compatible value accessor */
+    value: T;
+    /** Set a new value */
+    set(value: T): void;
+    /** Update the value using a function */
+    update(fn: (current: T) => T): void;
+    /** Subscribe to changes (returns unsubscribe function) */
+    subscribe(callback: (value: T, prev: T) => void): () => void;
+    /** Internal marker */
+    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 interface DerivedSignal<T> {
+    /** Read the current computed value */
+    (): T;
+    /** Vue-compatible read-only value accessor */
+    readonly value: T;
+    /** Internal marker */
+    readonly _isDerived: true;
+}
+/**
+ * Options for creating effects.
+ */
+export interface EffectOptions {
+    /** Run the effect immediately (default: true) */
+    immediate?: boolean;
+    /** Name for debugging */
+    name?: string;
+}
+/**
+ * Cleanup function returned by effects.
+ */
+export type CleanupFn = () => void;
+/**
+ * Lifecycle hook callback.
+ */
+export type LifecycleCallback = () => void | CleanupFn | Promise<void>;
 /**
  * Creates a reactive state signal.
  *
@@ -228,7 +334,10 @@ export declare function runDestroyCallbacks(): void;
  * How many callbacks are queued. Exposed for tests and diagnostics — a queue
  * that only ever grows is the shape of the defect above.
  */
-export declare function pendingLifecycleCounts(): { mount: number, destroy: number };
+export declare function pendingLifecycleCounts(): {
+    mount: number;
+    destroy: number;
+};
 /**
  * Checks if a value is a signal.
  *
@@ -289,6 +398,13 @@ export declare function untrack<T>(value: T | Signal<T> | DerivedSignal<T>): T;
  * ```
  */
 export declare function peek<T>(fn: () => T): T;
+/**
+ * The function returned by {@link useOptimistic} to apply an optimistic update.
+ * Returns a `settle` function that removes this specific optimistic entry (call
+ * it to roll back, e.g. in a `catch`). If a `settleWhen` promise is passed, the
+ * entry is removed automatically when that promise settles (success or error).
+ */
+export type AddOptimistic<A> = (action: A, settleWhen?: PromiseLike<unknown>) => () => void;
 /**
  * React-19-style optimistic state, adapted to signals.
  *
@@ -323,60 +439,3 @@ export declare function peek<T>(fn: () => T): T;
  * @see stacksjs/stx#1742
  */
 export declare function useOptimistic<T, A>(base: Signal<T> | DerivedSignal<T> | (() => T) | T, reducer: (current: T, action: A) => T): [DerivedSignal<T>, AddOptimistic<A>];
-/**
- * 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
-  value: 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 value: 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>;
-/**
- * The function returned by {@link useOptimistic} to apply an optimistic update.
- * Returns a `settle` function that removes this specific optimistic entry (call
- * it to roll back, e.g. in a `catch`). If a `settleWhen` promise is passed, the
- * entry is removed automatically when that promise settles (success or error).
- */
-export type AddOptimistic<A> = (action: A, settleWhen?: PromiseLike<unknown>) => () => void;

package/dist/signals-api.js

@@ -82,7 +82,8 @@ export function effect(fn, options = {}) {
     activeEffect = runEffect;
     effectStack.push(runEffect);
     try {
-      cleanup = fn();
+      const result = fn();
+      cleanup = typeof result === "function" ? result : void 0;
     } finally {
       effectStack.pop();
       activeEffect = prevEffect;
@@ -117,16 +118,18 @@ export function onDestroy(callback) {
   destroyCallbacks.push(callback);
 }
 export function runMountCallbacks() {
-  drain(mountCallbacks, "onMount");
+  drain(mountCallbacks, "onMount", destroyCallbacks);
 }
 export function runDestroyCallbacks() {
   drain(destroyCallbacks, "onDestroy");
 }
-function drain(queue, label) {
+function drain(queue, label, sink) {
   const pending = queue.splice(0, queue.length);
   for (const callback of pending)
     try {
-      callback();
+      const cleanup = callback();
+      if (sink && typeof cleanup === "function")
+        sink.push(cleanup);
     } catch (error) {
       console.error(`[stx] ${label} callback threw:`, error);
     }

package/dist/signals.d.ts

@@ -1,4 +1,14 @@
+/**
+ * STX Signals - Reactive State Management
+ * =========================================
+ *
+ * This module re-exports the build-time signals API from signals-api.ts
+ * and provides the client runtime string generators.
+ *
+ * @module signals
+ */
 import { state, derived, effect, batch, onMount, onDestroy, isSignal, isDerived, untrack, peek } from './signals-api';
+export * from './signals-api';
 /**
  * Generates the browser runtime for STX signals.
  *
@@ -14,21 +24,18 @@ export declare function generateSignalsRuntime(): string;
  * @returns Human-readable JavaScript runtime code
  */
 export declare function generateSignalsRuntimeDev(): string;
-export * from './signals-api';
-// =============================================================================
-// Default Export
-// =============================================================================
-export default {
-  state,
-  derived,
-  effect,
-  batch,
-  onMount,
-  onDestroy,
-  isSignal,
-  isDerived,
-  untrack,
-  peek,
-  generateSignalsRuntime,
-  generateSignalsRuntimeDev
+declare const _default: {
+    state: typeof state;
+    derived: typeof derived;
+    effect: typeof effect;
+    batch: typeof batch;
+    onMount: typeof onMount;
+    onDestroy: typeof onDestroy;
+    isSignal: typeof isSignal;
+    isDerived: typeof isDerived;
+    untrack: typeof untrack;
+    peek: typeof peek;
+    generateSignalsRuntime: typeof generateSignalsRuntime;
+    generateSignalsRuntimeDev: typeof generateSignalsRuntimeDev;
 };
+export default _default;