@stacksjs/stx 0.2.154 → 0.2.156

package/dist/streaming.d.ts

@@ -1,3 +1,52 @@
+/**
+ * Streaming and Hydration Module
+ *
+ * This module provides:
+ * - Template streaming for progressive rendering
+ * - Island-based partial hydration support
+ * - Section-based template composition
+ *
+ * ## Section Pattern
+ *
+ * Sections use HTML comments for markers:
+ * ```html
+ * <!-- @section:name -->
+ *   Content here
+ * <!-- @endsection:name -->
+ * ```
+ *
+ * **Note**: HTML comments are used because:
+ * - They're valid in any position in HTML
+ * - They don't affect the DOM structure
+ * - They're stripped during minification
+ *
+ * Alternative using data attributes (for JS-based extraction):
+ * ```html
+ * <template data-section="name">Content</template>
+ * ```
+ *
+ * ## Island Hydration
+ *
+ * Islands are client-side interactive regions in server-rendered content:
+ * ```html
+ * @island('counter', 'eager')
+ *   <div>Count: {{ count }}</div>
+ * @endisland
+ * ```
+ *
+ * Priority levels:
+ * - `eager` - Hydrate immediately on page load
+ * - `lazy` (default) - Hydrate when visible (IntersectionObserver)
+ * - `idle` - Hydrate during browser idle time (requestIdleCallback)
+ *
+ * ## Streaming
+ *
+ * Current implementation returns full content in a single chunk.
+ * True chunked streaming requires:
+ * 1. HTTP/2 or chunked transfer encoding
+ * 2. Identifying suspense boundaries
+ * 3. Streaming each section as it completes
+ */
 import type { CustomDirective, StreamRenderer, StxOptions } from './types';
 /**
  * Stream a template with data using chunked transfer encoding.
@@ -30,6 +79,44 @@ export declare function streamTemplate(templatePath: string, data?: Record<strin
  * cluster). See stacksjs/stx#1711.
  */
 export declare function buildSuspenseResolveScript(name: string, promise: Promise<string>): Promise<string>;
+/**
+ * Client receiver for streamed boundaries. Emitted once, right after the shell:
+ * defines `window.__stxSuspense.resolve(id, html)`, which swaps the boundary's
+ * fallback placeholder (`[data-suspense="id"]`) for the streamed content.
+ * Idempotent (`|| { … }`) so multiple streamed renders on one document — or a
+ * re-run after SPA nav — don't clobber an in-flight receiver.
+ */
+export declare const SUSPENSE_RESOLVER_RUNTIME: string;
+/** A deferred streaming boundary: its `render` does the server-side async work. */
+export interface StreamBoundary {
+    /** Boundary id — matches the `data-suspense="<id>"` placeholder in the shell. */
+    id: string;
+    /**
+     * Server-side async render for this boundary: fetch + render, resolving to the
+     * final HTML. Runs AFTER the shell has been flushed, so the slow data work
+     * here doesn't block first paint.
+     */
+    render: () => Promise<string>;
+}
+/**
+ * Render a streaming-SSR page (#1746 Phase 3). Flushes the shell — which carries
+ * each boundary's fallback in a `[data-suspense="<id>"]` placeholder — to the
+ * browser immediately, then streams each boundary's HTML as its server-side
+ * async `render()` resolves, in completion order. The browser paints the shell
+ * at once and each slow region swaps in when its data is ready.
+ *
+ * Per-boundary errors are isolated (`buildSuspenseResolveScript` emits an error
+ * UI into that boundary instead of failing the whole stream). Pair with
+ * `streamToResponse` to get a chunked HTTP `Response`.
+ */
+export interface RenderStreamingOptions {
+    /**
+     * Per-boundary timeout in ms. A boundary whose `render()` doesn't resolve in
+     * time is rejected (→ an error UI in its placeholder) so a hung data source
+     * can't keep the stream open forever. `0` (default) = no timeout.
+     */
+    timeoutMs?: number;
+}
 export declare function renderStreamingPage(shellHtml: string, boundaries?: StreamBoundary[], options?: RenderStreamingOptions): ReadableStream<string>;
 /**
  * Declarative streaming-SSR sugar (#1746 Phase 3). Extracts each
@@ -66,6 +153,27 @@ export declare function streamTemplateSimple(templatePath: string, data?: Record
  * @param options stx options
  */
 export declare function createStreamRenderer(templatePath: string, options?: StxOptions): Promise<StreamRenderer>;
+/**
+ * Custom directive for marking suspense boundaries in streaming templates.
+ *
+ * Usage:
+ * ```html
+ * @suspense('heavy-content')
+ *   <div>This content will stream after the shell</div>
+ * @endsuspense
+ * ```
+ *
+ * The content inside suspense boundaries will be:
+ * 1. Replaced with a placeholder in the initial shell
+ * 2. Processed in parallel with other suspense boundaries
+ * 3. Streamed to the client as it resolves
+ * 4. Injected into the placeholder via client-side JavaScript
+ */
+export declare const streamingSuspenseDirective: CustomDirective;
+/**
+ * Custom directive for creating islands (for partial hydration)
+ */
+export declare const islandDirective: CustomDirective;
 /**
  * Register streaming and hydration directives
  */
@@ -77,7 +185,6 @@ export declare function registerStreamingDirectives(options?: StxOptions): Custo
  * @param filePath Template file path
  * @param _options stx options
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function processSectionDirectives(content: string, context: Record<string, any>, filePath: string, _options?: StxOptions): Promise<string>;
 /**
  * Wrap a ReadableStream<string> in a proper Response with chunked transfer encoding headers.
@@ -99,6 +206,17 @@ export declare function processSectionDirectives(content: string, context: Recor
  * @returns A Response with proper streaming headers
  */
 export declare function streamToResponse(stream: ReadableStream<string>, init?: ResponseInit): Response;
+/**
+ * Configuration for hydration runtime generation
+ */
+export interface HydrationRuntimeConfig {
+    /** Include full runtime or just the loader */
+    mode: 'full' | 'loader';
+    /** Component registry mapping island names to component paths */
+    components?: Record<string, string>;
+    /** Whether to use dynamic imports */
+    dynamicImports?: boolean;
+}
 /**
  * Generate client-side hydration runtime script.
  *
@@ -118,59 +236,3 @@ export declare function streamToResponse(stream: ReadableStream<string>, init?:
  * ```
  */
 export declare function generateHydrationRuntime(config?: HydrationRuntimeConfig): string;
-/**
- * Client receiver for streamed boundaries. Emitted once, right after the shell:
- * defines `window.__stxSuspense.resolve(id, html)`, which swaps the boundary's
- * fallback placeholder (`[data-suspense="id"]`) for the streamed content.
- * Idempotent (`|| { … }`) so multiple streamed renders on one document — or a
- * re-run after SPA nav — don't clobber an in-flight receiver.
- */
-export declare const SUSPENSE_RESOLVER_RUNTIME: string;
-/**
- * Custom directive for marking suspense boundaries in streaming templates.
- *
- * Usage:
- * ```html
- * @suspense('heavy-content')
- *   <div>This content will stream after the shell</div>
- * @endsuspense
- * ```
- *
- * The content inside suspense boundaries will be:
- * 1. Replaced with a placeholder in the initial shell
- * 2. Processed in parallel with other suspense boundaries
- * 3. Streamed to the client as it resolves
- * 4. Injected into the placeholder via client-side JavaScript
- */
-export declare const streamingSuspenseDirective: CustomDirective;
-/**
- * Custom directive for creating islands (for partial hydration)
- */
-export declare const islandDirective: CustomDirective;
-/** A deferred streaming boundary: its `render` does the server-side async work. */
-export declare interface StreamBoundary {
-  id: string
-  render: () => Promise<string>
-}
-/**
- * Render a streaming-SSR page (#1746 Phase 3). Flushes the shell — which carries
- * each boundary's fallback in a `[data-suspense="<id>"]` placeholder — to the
- * browser immediately, then streams each boundary's HTML as its server-side
- * async `render()` resolves, in completion order. The browser paints the shell
- * at once and each slow region swaps in when its data is ready.
- *
- * Per-boundary errors are isolated (`buildSuspenseResolveScript` emits an error
- * UI into that boundary instead of failing the whole stream). Pair with
- * `streamToResponse` to get a chunked HTTP `Response`.
- */
-export declare interface RenderStreamingOptions {
-  timeoutMs?: number
-}
-/**
- * Configuration for hydration runtime generation
- */
-export declare interface HydrationRuntimeConfig {
-  mode: 'full' | 'loader'
-  components?: Record<string, string>
-  dynamicImports?: boolean
-}

package/dist/stx-virtual-ts.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Pull the script blocks out of a `.stx` source, with the line each body starts on.
+ *
+ * `<script server>` and `<script client>` are recognised by attribute. A bare
+ * `<script>` is reported as `plain`: it ships to the browser verbatim without
+ * the auto-import preamble, so it is a different checking context and callers
+ * may want to skip it.
+ */
+export declare function extractScriptBlocks(source: string): ScriptBlock[];
+/**
+ * Blank out everything an expression cannot appear in, preserving offsets.
+ *
+ * Scripts, styles, HTML comments and `@verbatim` blocks are replaced with
+ * spaces so that scanning for `{{ }}` never has to reason about nesting, while
+ * every surviving character keeps its original line and column.
+ */
+export declare function maskNonTemplateRegions(source: string): string;
+/**
+ * Split a filter chain off an interpolation, returning the head expression.
+ *
+ * `{{ name | upper }}` is stx syntax, not TypeScript — the pipe is a filter
+ * separator (`expressions.ts`). Only the part before the first top-level `|`
+ * is TypeScript, and `||` is a real operator that must survive.
+ */
+export declare function stripFilterChain(expression: string): string;
+export declare function substituteInterpolations(value: string): string;
+/**
+ * Every checkable expression in the markup, with the position it occupies.
+ *
+ * Interpolations escaped as `@{{ … }}` are skipped: that syntax exists to emit
+ * the braces literally.
+ */
+export declare function extractTemplateExpressions(source: string): TemplateExpression[];
+export declare function collectTemplateBindings(source: string): TemplateBinding[];
+/**
+ * Top-level names a script block declares.
+ *
+ * Used to give template expressions a scope without inlining a block that
+ * would collide with another one.
+ */
+export declare function collectBlockDeclarations(code: string): string[];
+/** Ambient declarations for the globals the stx runtime injects. */
+export declare function runtimeGlobalDeclarations(): string;
+export declare function serverContextDeclarations(): string;
+/**
+ * Names declared by both a server block and a client/plain block.
+ *
+ * The editor gets one buffer per file, so blocks cannot be given separate
+ * modules the way the CLI does — they all land at top level and a name declared
+ * on both sides reads as a redeclaration. That is a false signal, and this is
+ * what lets the plugin suppress exactly those and nothing else.
+ */
+export declare function crossScopeCollisions(blocks: readonly ScriptBlock[]): string[];
+/**
+ * Render one template expression as a checkable statement.
+ *
+ * Returns `null` for the shapes that cannot be modelled without inventing
+ * errors — `@click="open = !open"` assigns to what TypeScript sees as a
+ * `const`, and that form is documented stx syntax, not a mistake.
+ */
+export declare function expressionStatement(expression: TemplateExpression): { text: string, prefixLength: number } | null;
+/**
+ * Build one line-aligned TypeScript buffer for a whole `.stx` file.
+ *
+ * Every script body is written at the line index it already occupies, so a
+ * diagnostic's line and column are the `.stx` file's line and column with no
+ * translation. Synthetic content is appended past the end of the file and
+ * carried by {@link VirtualFile.lineMap}, so a diagnostic there still resolves
+ * to a real position — or to nothing, for the ambient declarations, which is
+ * how the caller knows to drop it.
+ */
+export declare function buildVirtualTypeScript(source: string, options?: BuildVirtualOptions): VirtualFile;
+/** Offsets at which each 1-based line starts. */
+export declare function lineStarts(text: string): number[];
+/** Offset → 1-based line and column. */
+export declare function offsetToPosition(starts: readonly number[], offset: number): { line: number, column: number };
+/** 1-based line and column → offset, clamped to the line. */
+export declare function positionToOffset(starts: readonly number[], line: number, column: number): number;
+/**
+ * Translate a position in a virtual buffer back to the `.stx` file.
+ *
+ * Returns `null` for the ambient declarations appended past the end of the
+ * file — they correspond to nothing the author wrote, so a diagnostic there
+ * must be dropped rather than pointed at an arbitrary line.
+ */
+export declare function resolvePosition(virtual: VirtualFile, line: number, column: number): ResolvedPosition | null;
+/**
+ * Placeholder for a server interpolation spliced into a client expression.
+ *
+ * `:show="photos()[{{ idx }}]"` is real stx — the server fills `{{ idx }}` in
+ * before the client ever parses the attribute. Left in place it is a syntax
+ * error, so it is replaced with a declared `any`; the interpolation itself is
+ * still extracted and checked on its own.
+ */
+export declare const INTERPOLATION_PLACEHOLDER: '__stx_interpolated';
+/** Name of the generated helper that reads an iterable's element type. */
+export declare const ELEMENT_HELPER: '__StxElement';
+/** Name of the generated helper that models a template's signal auto-unwrap. */
+export declare const UNWRAP_HELPER: '__StxTemplateValue';
+/**
+ * Context the server injects into a `<script server>` block.
+ *
+ * Mirrors what `serve.ts` puts in scope. Declaring these is what lets the
+ * checker report a genuine typo instead of suppressing every unresolved name.
+ */
+export declare const STX_SERVER_CONTEXT: readonly ['params', 'query', 'cookies', 'host', 'ip', 'setResponseStatus', 'setResponseHeader', 'request', 'url', 'definePageMeta'];
+/**
+ * Names the template engine puts in scope for every page.
+ *
+ * Declared rather than suppressed. The editor plugin used to drop every
+ * "Cannot find name" whose message mentioned one of a hardcoded list, which
+ * also dropped genuine typos; giving the names a declaration means an
+ * unrecognised one is still an error (#1852 ask 3).
+ */
+export declare const STX_TEMPLATE_GLOBALS: readonly ['$env', '$user', '$slot', '$slots', '$attrs', '$props', '$page', '$route', '$loop', '$errors', '$csrf', 'props', 'slot'];
+export declare interface ScriptBlock {
+  kind: ScriptKind
+  code: string
+  startLine: number
+  attrs: string
+}
+/** A `{{ }}` interpolation or a directive attribute value. */
+export declare interface TemplateExpression {
+  code: string
+  line: number
+  column: number
+  kind: 'interpolation' | 'directive'
+  attribute?: string
+}
+/** A synthetic line's origin, for diagnostics that land outside the source. */
+export declare interface MappedLine {
+  line: number
+  column: number
+  expression?: TemplateExpression
+  prefixLength?: number
+}
+export declare interface VirtualFile {
+  text: string
+  lineMap: Map<number, MappedLine>
+  sourceLineCount: number
+}
+/**
+ * Names a template introduces that no script block declares.
+ *
+ * Loop bindings are collected for the whole file rather than tracked per
+ * subtree. That is deliberately over-permissive: using a loop variable outside
+ * its loop goes unreported, which is a missing error, whereas scoping it
+ * precisely without an HTML parser would invent errors that are not there.
+ */
+export declare interface TemplateBinding {
+  name: string
+  iterable?: string
+}
+export declare interface BuildVirtualOptions {
+  templateExpressions?: boolean
+  globals?: boolean
+  runtimeGlobals?: boolean
+}
+/** Where a diagnostic in a virtual buffer belongs in the `.stx` file. */
+export declare interface ResolvedPosition {
+  line: number
+  column: number
+  expression?: TemplateExpression
+}
+export type ScriptKind = 'server' | 'client' | 'plain';