@stacksjs/stx 0.2.155 → 0.2.157

package/dist/index.d.ts

@@ -44,6 +44,38 @@ export {
   useStorage,
   type UseStorageOptions,
 } from './composables/use-storage';
+// View composers were unreachable: `runComposers` is wired into the render
+// pipeline (process.ts:1206) and runs on every render, but the two functions that
+// PUT anything in the registry were never exported, so the registry was always
+// empty and the whole layer was dead weight. The module's own docblock tells you
+// to `import { composer } from 'stx'`, which threw. The existing test suite
+// imported from './view-composers' directly, so nothing exercised the public
+// surface and the gap stayed invisible. See #1860.
+export {
+  clearComposers,
+  composer,
+  composerPattern,
+  runComposers,
+  type ViewComposerCallback,
+} from './view-composers';
+// useForm and the `v` validator builder shipped unreachable: the module's
+// docblock says `import { useForm, v } from 'stx'` (forms-validation.ts:9),
+// and that import threw. process.ts reached the module lazily for directive
+// processing only, so the form primitive itself had no way in. See #1856.
+//
+// `defineForm` is the deprecated pre-#1843 spelling, exported alongside so an
+// app does not have to rename in the same release it upgrades in.
+export {
+  defineForm,
+  useForm,
+  v,
+  Validator,
+  type ValidatorFn,
+  type AsyncValidatorFn,
+  type ValidatorRule,
+  type FieldState,
+  type FormState,
+} from './forms-validation';
 export { formatSize, getTotalSize } from './deploy/index';
 export { type ImageRenderResult, type ImageVariant, type ProcessedImage, clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from './image-optimization/index';
 export { type AnalysisResult } from './analyzer';
@@ -96,6 +128,16 @@ export * from './defer';
 export * from './deploy/index';
 export * from './dev-server';
 export * from './document-shell';
+export * from './fragment-container';
+// DevTools entry points. Exported selectively rather than with a wildcard:
+// devtools.ts also exports registerStore, which would collide with
+// state-management's function of the same name. Their own docblock says
+// `import { enableDevTools } from 'stx'`, and that import threw — so devtools
+// could not be turned on from the package entry at all. See #1873.
+export { disableDevTools, enableDevTools } from './devtools';
+// composables.ts:161 documents `import { onUpdate } from 'stx'`; it was
+// reachable only through the stx/composables subpath.
+export { onUpdate } from './composables';
 export * from './directive-api';
 export * from './docs';
 export * from './edge-runtime';
@@ -137,6 +179,10 @@ export * from './suspense';
 export * from './teleport';
 export * from './transitions';
 export * from './type-checker';
+// Type-checking the TypeScript inside .stx script blocks, and the CLI behind
+// `stx typecheck` (#1852). Distinct from ./type-checker, which is a bespoke
+// checker for template EXPRESSIONS.
+export * from './typecheck';
 export * from './web-components';
 export * from './virtual-scrolling';
 export * from './partial-hydration';
@@ -178,6 +224,26 @@ export { definePlugin, pluginManager } from './plugin-system';
 // These modules are exported first to establish their types
 export * from './render';
 export { extractClassNames, generateCrosswindCSS, getCrosswindServeAsset, injectCrosswindCSS } from './dev-server/crosswind';
+// One crosswind merge shared by every render path (#1867)
+export { deepMergeThemes, mergeCrosswindConfig, type MergedCrosswindConfig } from './crosswind-config';
+// Dev-mode invalidation for the store/composable bundles (#1877)
+export { clearStoreCache, getStoreScript } from './store-loader';
+export { clearComposableCache } from './composable-loader';
+// Generated union of layouts on disk (#1879)
+export { discoverLayoutNames, generateLayoutTypes, LAYOUT_TYPES_FILE, renderLayoutTypes } from './layout-types';
+// Typed route paths (#1887). Without this export the generated augmentation is
+// dangling again, for exactly the reason `stx/routes` was.
+export {
+  $path,
+  type CheckHref,
+  type KnownRoutes,
+  type RouteHref,
+  type RouteParams,
+  type RoutePath,
+  type RoutePattern,
+  type RoutePatternUsedAsHref,
+  type UnknownRoute,
+} from './route-types';
 export { runDoctor, formatDoctorReport, findPantryPackage } from './doctor';
 export {
   applyTranslations,

package/dist/index.js

@@ -6,6 +6,18 @@ export {
   useSessionStorage,
   useStorage
 } from "./composables/use-storage.js";
+export {
+  clearComposers,
+  composer,
+  composerPattern,
+  runComposers
+} from "./view-composers.js";
+export {
+  defineForm,
+  useForm,
+  v,
+  Validator
+} from "./forms-validation.js";
 export { formatSize, getTotalSize } from "./deploy/index.js";
 export { clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from "./image-optimization/index.js";
 export { fileExists } from "./utils.js";
@@ -44,6 +56,9 @@ export * from "./defer.js";
 export * from "./deploy/index.js";
 export * from "./dev-server.js";
 export * from "./document-shell.js";
+export * from "./fragment-container.js";
+export { disableDevTools, enableDevTools } from "./devtools.js";
+export { onUpdate } from "./composables.js";
 export * from "./directive-api.js";
 export * from "./docs.js";
 export * from "./edge-runtime.js";
@@ -84,6 +99,7 @@ export * from "./suspense.js";
 export * from "./teleport.js";
 export * from "./transitions.js";
 export * from "./type-checker.js";
+export * from "./typecheck.js";
 export * from "./web-components.js";
 export * from "./virtual-scrolling.js";
 export * from "./partial-hydration.js";
@@ -119,6 +135,13 @@ export * from "./dynamic-components.js";
 export { definePlugin, pluginManager } from "./plugin-system.js";
 export * from "./render.js";
 export { extractClassNames, generateCrosswindCSS, getCrosswindServeAsset, injectCrosswindCSS } from "./dev-server/crosswind.js";
+export { deepMergeThemes, mergeCrosswindConfig } from "./crosswind-config.js";
+export { clearStoreCache, getStoreScript } from "./store-loader.js";
+export { clearComposableCache } from "./composable-loader.js";
+export { discoverLayoutNames, generateLayoutTypes, LAYOUT_TYPES_FILE, renderLayoutTypes } from "./layout-types.js";
+export {
+  $path
+} from "./route-types.js";
 export { runDoctor, formatDoctorReport, findPantryPackage } from "./doctor.js";
 export {
   applyTranslations,

package/dist/internal-markdown.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Internal markdown utilities to replace ts-md dependency
+ * Provides frontmatter parsing and markdown to HTML conversion
+ */
+export interface FrontmatterResult {
+    data: Record<string, unknown>;
+    content: string;
+}
+export interface MarkdownOptions {
+    gfm?: boolean;
+    breaks?: boolean;
+}
 /**
  * Parse YAML frontmatter from markdown content
  * Frontmatter is delimited by --- at the start of the file
@@ -8,11 +20,3 @@ export declare function parseFrontmatter(content: string): FrontmatterResult;
  * Simple implementation that handles common markdown patterns
  */
 export declare function parseMarkdown(content: string, options?: MarkdownOptions): string;
-export declare interface FrontmatterResult {
-  data: Record<string, unknown>
-  content: string
-}
-export declare interface MarkdownOptions {
-  gfm?: boolean
-  breaks?: boolean
-}

package/dist/island-chunking.d.ts

@@ -1,3 +1,33 @@
+/** One extracted island chunk: a content hash and the IIFE it holds. */
+export interface IslandChunk {
+    /** Content hash of `code` — the chunk's filename stem (`/_stx/islands/<hash>.js`). */
+    hash: string;
+    /** The island setup IIFE (trimmed) to write to the chunk file. */
+    code: string;
+}
+export interface ExtractIslandChunksResult {
+    /** HTML with each inline island IIFE replaced by a `data-stx-src` reference. */
+    html: string;
+    /** The unique chunks to write (deduped by content hash within the page). */
+    chunks: IslandChunk[];
+}
+export interface ExtractIslandChunksOptions {
+    /**
+     * Stamp `data-stx-integrity="sha384-…"` (Subresource Integrity) on each
+     * chunked tag so the runtime can pin the chunk against tampering and a strict
+     * CSP can require SRI. Default `false` — only enable when chunks are served
+     * byte-for-byte unchanged (no CDN/proxy transform), else the hash won't match
+     * and the island silently won't hydrate.
+     */
+    integrity?: boolean;
+    /**
+     * Minify each chunk's JS (whitespace only) before hashing/writing, so the
+     * lazily-loaded bytes aren't padded with source whitespace. Default `false`;
+     * the SSG passes its `minify` flag. Hashing happens over the minified bytes,
+     * so the content hash + SRI always match what's served.
+     */
+    minify?: boolean;
+}
 /**
  * Lift inline island IIFEs into content-hashed chunks. Pure: no filesystem
  * access — the caller writes `result.chunks` and `result.html`.
@@ -16,16 +46,3 @@ export declare function extractIslandChunks(html: string, options?: ExtractIslan
  * not used within N seconds" console warning for below-the-fold islands.
  */
 export declare function injectIslandChunkPrefetch(html: string): string;
-/** One extracted island chunk: a content hash and the IIFE it holds. */
-export declare interface IslandChunk {
-  hash: string
-  code: string
-}
-export declare interface ExtractIslandChunksResult {
-  html: string
-  chunks: IslandChunk[]
-}
-export declare interface ExtractIslandChunksOptions {
-  integrity?: boolean
-  minify?: boolean
-}

package/dist/keep-alive.d.ts

@@ -1,3 +1,66 @@
+/**
+ * STX Keep-Alive
+ *
+ * Caches component instances to preserve state when toggling visibility.
+ * Similar to Vue's <KeepAlive> component.
+ *
+ * @module keep-alive
+ *
+ * @example
+ * ```html
+ * @keepAlive
+ *   @if (currentTab === 'settings')
+ *     <SettingsPanel />
+ *   @elseif (currentTab === 'profile')
+ *     <ProfilePanel />
+ *   @endif
+ * @endkeepAlive
+ * ```
+ *
+ * With options:
+ * ```html
+ * @keepAlive(max: 10, include: 'Settings,Profile', exclude: 'Debug')
+ *   <component :is="currentComponent" />
+ * @endkeepAlive
+ * ```
+ */
+export interface KeepAliveOptions {
+    /** Maximum number of component instances to cache */
+    max?: number;
+    /** Comma-separated list of component names to include */
+    include?: string;
+    /** Comma-separated list of component names to exclude */
+    exclude?: string;
+    /** Custom cache key */
+    id?: string;
+}
+export interface CachedComponent {
+    /** Component identifier */
+    key: string;
+    /** Cached HTML content */
+    html: string;
+    /** Cached state data */
+    state: Record<string, unknown>;
+    /** Timestamp when cached */
+    cachedAt: number;
+    /** Scroll positions */
+    scrollPositions: Map<string, {
+        top: number;
+        left: number;
+    }>;
+}
+export interface KeepAliveCache {
+    /** Unique cache ID */
+    id: string;
+    /** Cached components (LRU order) */
+    cache: Map<string, CachedComponent>;
+    /** Maximum cache size */
+    max: number;
+    /** Include filter */
+    include: string[] | null;
+    /** Exclude filter */
+    exclude: string[] | null;
+}
 /**
  * Process @keepAlive directives in templates.
  *
@@ -30,59 +93,16 @@ export declare function generateKeepAliveRuntime(): string;
  * Hook called when a component is activated from cache.
  * Use in client-side scripts.
  */
-export declare function onActivated(callback: (detail: { key: string; keepAliveId: string; cachedAt: number }) => void): void;
+export declare function onActivated(callback: (detail: {
+    key: string;
+    keepAliveId: string;
+    cachedAt: number;
+}) => void): void;
 /**
  * Hook called when a component is deactivated and cached.
  * Use in client-side scripts.
  */
-export declare function onDeactivated(callback: (detail: { key: string; keepAliveId: string }) => void): void;
-/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
-/**
- * STX Keep-Alive
- *
- * Caches component instances to preserve state when toggling visibility.
- * Similar to Vue's <KeepAlive> component.
- *
- * @module keep-alive
- *
- * @example
- * ```html
- * @keepAlive
- *   @if (currentTab === 'settings')
- *     <SettingsPanel />
- *   @elseif (currentTab === 'profile')
- *     <ProfilePanel />
- *   @endif
- * @endkeepAlive
- * ```
- *
- * With options:
- * ```html
- * @keepAlive(max: 10, include: 'Settings,Profile', exclude: 'Debug')
- *   <component :is="currentComponent" />
- * @endkeepAlive
- * ```
- */
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface KeepAliveOptions {
-  max?: number
-  include?: string
-  exclude?: string
-  id?: string
-}
-export declare interface CachedComponent {
-  key: string
-  html: string
-  state: Record<string, unknown>
-  cachedAt: number
-  scrollPositions: Map<string, { top: number; left: number }>
-}
-export declare interface KeepAliveCache {
-  id: string
-  cache: Map<string, CachedComponent>
-  max: number
-  include: string[] | null
-  exclude: string[] | null
-}
+export declare function onDeactivated(callback: (detail: {
+    key: string;
+    keepAliveId: string;
+}) => void): void;

package/dist/layout-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generate a union of the layouts that exist on disk, so naming one wrong is a
+ * type error rather than an unlayouted page (stacksjs/stx#1879 ask 3).
+ *
+ * `definePageMeta({ layout: 'app' })` now selects a layout, which makes the
+ * name a load-bearing string — and a typo produces exactly the same render as a
+ * correct name pointing at a missing file. Nuxt types `layout` as a union of
+ * the files on disk for this reason; the failure is caught before the build,
+ * not by reading the console afterwards.
+ *
+ * ## Why this augments the real package, not a synthetic specifier
+ *
+ * The augmentation targets `@stacksjs/stx`, where `KnownLayouts` is really
+ * declared and really referenced by `PageMeta['layout']`.
+ *
+ * That mattered because the route-type generator used to emit
+ * `declare module "stx/routes"` — a specifier nothing in the source tree
+ * declares or imports, which TypeScript reads as an ambient module declaration
+ * rather than an augmentation. It parsed, shipped, and constrained nothing: the
+ * same "typed and never read" shape #1879 is about, one level up. Routes now
+ * use this same target (#1887); the reasoning below is what kept this file from
+ * repeating it.
+ *
+ * @module layout-types
+ */
+/** The name of the generated declaration file, inside the state directory. */
+export declare const LAYOUT_TYPES_FILE = "layout-types.d.ts";
+/**
+ * Layout names in `layoutsDir`, without the `.stx` extension.
+ *
+ * Nested layouts keep their path (`admin/settings`), matching what the layout
+ * resolver accepts. `_layout.stx` files are excluded: they are applied by
+ * directory position, never named.
+ */
+export declare function discoverLayoutNames(layoutsDir: string): string[];
+/** The declaration text for a set of layout names. */
+export declare function renderLayoutTypes(names: readonly string[]): string;
+/**
+ * Write the declaration for `layoutsDir` into `outputDir`.
+ *
+ * Best-effort and idempotent: an unwritable state directory is not a build
+ * failure, and an unchanged file is left alone so watchers do not see a write
+ * on every render.
+ */
+export declare function generateLayoutTypes(layoutsDir: string | undefined, outputDir: string): string[];

package/dist/layout-types.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+export const LAYOUT_TYPES_FILE = "layout-types.d.ts";
+export function discoverLayoutNames(layoutsDir) {
+  const names = [], walk = (dir, prefix) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: !0 });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith("."))
+        continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory())
+        walk(full, prefix ? `${prefix}/${entry.name}` : entry.name);
+      else if (entry.isFile() && entry.name.endsWith(".stx") && entry.name !== "_layout.stx") {
+        const base = entry.name.slice(0, -4);
+        names.push(prefix ? `${prefix}/${base}` : base);
+      }
+    }
+  };
+  walk(layoutsDir, "");
+  return names.sort();
+}
+export function renderLayoutTypes(names) {
+  const lines = [
+    "// Auto-generated by stx \u2014 do not edit.",
+    "//",
+    "// Makes `definePageMeta({ layout })` reject a name with no layout behind it.",
+    "// Include this file in your tsconfig (it lives in the stx state directory,",
+    "// `.stx/` by default) for the check to apply.",
+    ""
+  ];
+  if (names.length === 0) {
+    lines.push("// No layouts found \u2014 `layout` stays typed as `string`.", "export {}", "");
+    return lines.join(`
+`);
+  }
+  lines.push("declare module '@stacksjs/stx' {", "  interface KnownLayouts {", ...names.map((name) => `    '${name}': true`), "  }", "}", "", "export {}", "");
+  return lines.join(`
+`);
+}
+export function generateLayoutTypes(layoutsDir, outputDir) {
+  if (!layoutsDir)
+    return [];
+  const abs = path.isAbsolute(layoutsDir) ? layoutsDir : path.resolve(process.cwd(), layoutsDir), names = discoverLayoutNames(abs), contents = renderLayoutTypes(names), target = path.join(outputDir, LAYOUT_TYPES_FILE);
+  try {
+    if (fs.existsSync(target) && fs.readFileSync(target, "utf8") === contents)
+      return names;
+    fs.mkdirSync(outputDir, { recursive: !0 });
+    fs.writeFileSync(target, contents);
+  } catch {}
+  return names;
+}

package/dist/lazy-module.d.ts

@@ -1 +1,11 @@
+/**
+ * Deduplicate cold dynamic imports across concurrent template renders.
+ *
+ * Bun normally caches evaluated modules, but separate first-use import()
+ * calls can still enter its TypeScript compilation path concurrently. A dev
+ * server prewarming several routes exposed that race as partial module builds
+ * such as "Unexpected end of file" from forms-validation.ts. Keeping the
+ * pending promise makes first compilation single-flight while preserving lazy
+ * loading and the circular-dependency boundaries that require import().
+ */
 export declare function importOnce<T>(key: string, importer: () => Promise<T>): Promise<T>;

package/dist/loops.d.ts

@@ -1,3 +1,46 @@
+/**
+ * Module for processing loop directives (@foreach, @for, @while, @forelse)
+ *
+ * Supports loop control directives:
+ * - `@break` - Exit the loop immediately
+ * - `@break(condition)` - Exit if condition is true
+ * - `@continue` - Skip to next iteration
+ * - `@continue(condition)` - Skip if condition is true
+ *
+ * @foreach syntax variants:
+ * - `@foreach(items as item)` - Basic iteration
+ * - `@foreach(items as index => item)` - With index variable
+ *
+ * @example Basic iteration
+ * ```html
+ * @foreach(items as item)
+ *   {{ item.name }}
+ * @endforeach
+ * ```
+ *
+ * @example With index variable
+ * ```html
+ * @foreach(items as index => item)
+ *   {{ index }}: {{ item.name }}
+ *   @if(index === 0)
+ *     (first item)
+ *   @endif
+ * @endforeach
+ * ```
+ *
+ * @example With loop control
+ * ```html
+ * @foreach(items as item)
+ *   @if(item.skip)
+ *     @continue
+ *   @endif
+ *   @if(item.stop)
+ *     @break
+ *   @endif
+ *   {{ item.name }}
+ * @endforeach
+ * ```
+ */
 import type { StxOptions } from './types';
 /**
  * Process loops (@foreach, @for, @while, @forelse)
@@ -22,4 +65,27 @@ import type { StxOptions } from './types';
  * @param filePath - Path to template file for error messages
  * @param options - Optional stx configuration
  */
+/**
+ * Split `@foreach(...)` / `@forelse(...)` params into the collection and the
+ * item binding.
+ *
+ * Two spellings are documented and only one was implemented. Blade's
+ * `items as item` worked; the JS-natural `item in items` — which
+ * docs/SCRIPT_VARIABLES.md shows, and which matches the `:for="item in items"`
+ * client directive — did not, and the failure was silent. An unrecognised
+ * binding was skipped with `continue`, so the directive text survived into the
+ * built page and every `{{ }}` inside it resolved against a variable that never
+ * existed. The reported page shipped `data-variant-row="{{ p.id }}"` to the
+ * browser: a literal no selector matches and no binding resolves
+ * (stacksjs/stx#1842).
+ *
+ * The operands are the other way round between the two forms, which is the
+ * whole reason this needs saying once rather than at each call site. Vue's
+ * parenthesised `(item, index)` maps onto the comma form the item parser
+ * already understands.
+ */
+export declare function parseLoopBinding(params: string): {
+    arrayExpr: string;
+    itemVar: string;
+} | null;
 export declare function processLoops(template: string, context: Record<string, any>, filePath: string, options?: StxOptions): string;

package/dist/loops.js

@@ -4,6 +4,33 @@ import { processExpressions } from "./expressions.js";
 import { findDirectiveBlocks, findMatchingDelimiter } from "./parser/index.js";
 import { createSafeFunction, isExpressionSafe, isForExpressionSafe, sanitizeExpression, safeEvaluate, safeEvaluateObject } from "./safe-evaluator.js";
 const DEFAULT_MAX_WHILE_ITERATIONS = 1000, DEFAULT_USE_ALT_LOOP_VARIABLE = !1;
+function preEvaluateIncludeData(content, ctx) {
+  const pattern = /@(include|partial)\s*\(\s*(['"])([^'"]+)\2\s*,\s*/g;
+  let result = "", lastIndex = 0, match;
+  while ((match = pattern.exec(content)) !== null) {
+    const argsStart = match.index + match[0].length, openParen = match.index + match[0].indexOf("("), close = findMatchingDelimiter(content, "(", ")", openParen);
+    if (close === -1)
+      continue;
+    const varsString = content.slice(argsStart, close).trim();
+    if (!varsString)
+      continue;
+    if (!Object.keys(ctx).some((name) => new RegExp(`(?:^|[^\\w$.])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w$])`).test(varsString)))
+      continue;
+    let frozen;
+    try {
+      const evaluated = safeEvaluateObject(varsString, ctx);
+      if (!evaluated || typeof evaluated !== "object")
+        continue;
+      frozen = JSON.stringify(evaluated);
+    } catch {
+      continue;
+    }
+    result += content.slice(lastIndex, argsStart) + frozen;
+    lastIndex = close;
+    pattern.lastIndex = close;
+  }
+  return lastIndex === 0 ? content : result + content.slice(lastIndex);
+}
 function preEvaluateComponentProps(content, ctx) {
   const componentPat = /@component\s*\(/g;
   let result = content, match;
@@ -222,10 +249,10 @@ function findOutermostForelse(template) {
     }
     if (closeParen === -1)
       continue;
-    const params = template.substring(openParen + 1, closeParen), asIndex = params.indexOf(" as ");
-    if (asIndex === -1)
+    const params = template.substring(openParen + 1, closeParen), binding = parseLoopBinding(params);
+    if (!binding)
       continue;
-    const arrayExpr = params.substring(0, asIndex).trim(), itemVar = params.substring(asIndex + 4).trim(), contentStart = closeParen + 1;
+    const { arrayExpr, itemVar } = binding, contentStart = closeParen + 1;
     let depth = 1, searchPos = contentStart;
     const nestedForelseRegex = /@forelse\s*\(/g, endForelseRegex = /@endforelse/g;
     let endForelsePos = -1;
@@ -310,6 +337,18 @@ function processForelse(template, context) {
   }
   return output;
 }
+export function parseLoopBinding(params) {
+  const asIndex = params.indexOf(" as ");
+  if (asIndex !== -1) {
+    const arrayExpr = params.slice(0, asIndex).trim(), itemVar = params.slice(asIndex + 4).trim();
+    return arrayExpr && itemVar ? { arrayExpr, itemVar } : null;
+  }
+  const inMatch = /^\s*(.+?)\s+in\s+([\s\S]+)$/.exec(params);
+  if (!inMatch)
+    return null;
+  const itemVar = inMatch[1].trim().replace(/^\(([\s\S]*)\)$/, "$1").trim(), arrayExpr = inMatch[2].trim();
+  return itemVar && arrayExpr ? { arrayExpr, itemVar } : null;
+}
 export function processLoops(template, context, filePath, options) {
   let output = template;
   output = processForelse(output, context);
@@ -333,10 +372,10 @@ export function processLoops(template, context, filePath, options) {
       }
       if (closeParen === -1)
         continue;
-      const params = template.substring(openParen + 1, closeParen), asIndex = params.indexOf(" as ");
-      if (asIndex === -1)
+      const params = template.substring(openParen + 1, closeParen), binding = parseLoopBinding(params);
+      if (!binding)
         continue;
-      const start = foreachStart, arrayExpr = params.substring(0, asIndex), itemVar = params.substring(asIndex + 4), contentStart = closeParen + 1;
+      const start = foreachStart, { arrayExpr, itemVar } = binding, contentStart = closeParen + 1;
       let depth = 1, searchPos = contentStart;
       const nestedForeachRegex = /@foreach\s*\(/g, endforeachRegex = /@endforeach/g;
       while (depth > 0 && searchPos < template.length) {
@@ -387,6 +426,7 @@ export function processLoops(template, context, filePath, options) {
             array = Object.entries(array);
             isObjectEntries = !0;
           } else {
+            console.warn(`[stx] @foreach(${trimmedArrayExpr}) in ${filePath}: ${trimmedArrayExpr} is not iterable server-side, so the loop rendered nothing. ` + "Values a server loop reads must come from <script server> or the page context \u2014 " + "a plain <script> runs in the browser.");
             const errorMsg = inlineError("Foreach", `Error in @foreach: ${trimmedArrayExpr} is not iterable`, ErrorCodes.TYPE_ERROR);
             result = result.substring(0, start) + errorMsg + result.substring(end);
             continue;
@@ -468,6 +508,7 @@ export function processLoops(template, context, filePath, options) {
           processedContent = processExpressions(processedContent, itemContext, filePath);
           processedContent = processPropBindings(processedContent, itemContext);
           processedContent = preEvaluateComponentProps(processedContent, itemContext);
+          processedContent = preEvaluateIncludeData(processedContent, itemContext);
           loopResult += processedContent;
         }
         result = result.substring(0, start) + loopResult + result.substring(end);

package/dist/markdown.d.ts

@@ -2,7 +2,6 @@
  * Process markdown directives in templates
  * Converts markdown content to HTML
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function processMarkdownDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;
 /**
  * Custom directive handler for markdown