@stacksjs/stx 0.2.154 → 0.2.156

package/dist/build-externalize.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+export const EXTERNALIZED_ASSET_DIR = "_stx";
+function contentHash(source) {
+  return Bun.hash(source).toString(16).slice(0, 8);
+}
+function listHtmlFiles(dir) {
+  const found = [], walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: !0 })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory())
+        walk(full);
+      else if (entry.isFile() && full.endsWith(".html"))
+        found.push(full);
+    }
+  };
+  if (fs.existsSync(dir))
+    walk(dir);
+  return found;
+}
+export function externalizeSharedAssets(outDir) {
+  const result = { pages: 0, assets: 0, bytesInlined: 0 }, assetDir = path.join(outDir, EXTERNALIZED_ASSET_DIR), written = new Set, writeAsset = (filename, contents) => {
+    if (written.has(filename))
+      return;
+    written.add(filename);
+    fs.mkdirSync(assetDir, { recursive: !0 });
+    fs.writeFileSync(path.join(assetDir, filename), contents);
+    result.assets++;
+  };
+  for (const file of listHtmlFiles(outDir)) {
+    const original = fs.readFileSync(file, "utf8");
+    let html = original;
+    html = html.replace(/<script\b([^>]*\bdata-stx-runtime\b[^>]*)>([\s\S]*?)<\/script>/gi, (whole, attrs, body) => {
+      if (/\bsrc\s*=/.test(attrs) || !body.trim())
+        return whole;
+      const filename = `runtime.${contentHash(body)}.js`;
+      writeAsset(filename, body);
+      result.bytesInlined += body.length;
+      return `<script data-stx-runtime src="/${EXTERNALIZED_ASSET_DIR}/${filename}"></script>`;
+    });
+    html = html.replace(/<script\b([^>]*\bdata-stx-router\b[^>]*)>([\s\S]*?)<\/script>/gi, (whole, attrs, body) => {
+      if (/\bsrc\s*=/.test(attrs) || !body.trim())
+        return whole;
+      const filename = `router.${contentHash(body)}.js`;
+      writeAsset(filename, body);
+      result.bytesInlined += body.length;
+      return `<script data-stx-router src="/${EXTERNALIZED_ASSET_DIR}/${filename}"></script>`;
+    });
+    html = html.replace(/<style\b([^>]*\bdata-crosswind=(?:"generated"|'generated')[^>]*)>([\s\S]*?)<\/style>/gi, (whole, _attrs, css) => {
+      if (!css.trim())
+        return whole;
+      const filename = `crosswind.${contentHash(css)}.css`;
+      writeAsset(filename, css);
+      result.bytesInlined += css.length;
+      return `<link data-crosswind="generated" rel="stylesheet" href="/${EXTERNALIZED_ASSET_DIR}/${filename}">`;
+    });
+    if (html !== original) {
+      fs.writeFileSync(file, html);
+      result.pages++;
+    }
+  }
+  return result;
+}

package/dist/build-id.d.ts

@@ -1,23 +1,3 @@
-/**
- * The current process's build id.
- *
- * Stable for the lifetime of the process, which is the unit that matters: a
- * `bun --watch` restart produces a new process and therefore a new id, while a
- * production build stamps every page it renders with one value.
- *
- * `STX_BUILD_ID` overrides it, for deployments that render across several
- * processes and need them to agree.
- */
-export declare function getBuildId(): string;
-/** @internal test-only — force the id, or with `null` restore generation. */
-export declare function __setBuildIdForTest(id: string | null): void;
-/**
- * Add `<meta name="stx-build">` to `<head>` if it isn't already there.
- *
- * Idempotent, and a no-op for output with no `<head>` — SPA fragments carry the
- * id in a response header instead, since they have nowhere to put a meta.
- */
-export declare function injectBuildId(html: string, buildId?: string): string;
 /**
  * Per-process build identity, used to detect runtime/fragment skew
  * (stacksjs/stx#1772).
@@ -44,6 +24,26 @@ export declare function injectBuildId(html: string, buildId?: string): string;
  * @module build-id
  */
 /** `<meta name="stx-build">` on every rendered page. */
-export declare const BUILD_ID_META: 'stx-build';
+export declare const BUILD_ID_META = "stx-build";
 /** Response header carrying the id that rendered an SPA fragment. */
-export declare const BUILD_ID_HEADER: 'X-STX-Build';
+export declare const BUILD_ID_HEADER = "X-STX-Build";
+/**
+ * The current process's build id.
+ *
+ * Stable for the lifetime of the process, which is the unit that matters: a
+ * `bun --watch` restart produces a new process and therefore a new id, while a
+ * production build stamps every page it renders with one value.
+ *
+ * `STX_BUILD_ID` overrides it, for deployments that render across several
+ * processes and need them to agree.
+ */
+export declare function getBuildId(): string;
+/** @internal test-only — force the id, or with `null` restore generation. */
+export declare function __setBuildIdForTest(id: string | null): void;
+/**
+ * Add `<meta name="stx-build">` to `<head>` if it isn't already there.
+ *
+ * Idempotent, and a no-op for output with no `<head>` — SPA fragments carry the
+ * id in a response header instead, since they have nowhere to put a meta.
+ */
+export declare function injectBuildId(html: string, buildId?: string): string;

package/dist/build-message.d.ts

@@ -1,10 +1,81 @@
 /**
- * Render a build failure as `path:line:column: message`, falling back to the
- * plain message when no position is available.
+ * Make a Bun build failure say where it happened (stacksjs/stx#1810).
+ *
+ * A single unparseable view produced `BuildMessage: Unexpected ===` and nothing
+ * else — no path, no line — leaving the reporter to binary-search the scanned
+ * views by hand.
+ *
+ * The location was never missing. Bun computes it and puts it on
+ * `BuildMessage.position`; it is `.message` and `.toString()` that omit it. And
+ * because `BuildMessage` is not an `instanceof Error` and carries no `.stack`,
+ * the usual `error instanceof Error ? error.message : String(error)` idiom —
+ * which this codebase uses in a dozen places — reduces it to exactly that bare
+ * string.
+ *
+ * Two further wrinkles this handles:
+ *
+ *  - `Bun.build()` does not throw a BuildMessage. It throws an AggregateError
+ *    whose `.errors` holds them, so the useful detail is one level down.
+ *  - `Bun.Transpiler.transformSync()` reports `position.file` as its synthetic
+ *    entry name, never the real path. The caller knows the real one, so it is
+ *    threaded in rather than trusted from the message.
+ */
+/**
+ * One failure, with its position kept separate rather than baked into a string.
+ *
+ * A terminal wants `path:line:col: message`; a dev-server overlay wants to draw
+ * a code frame and put a caret under the column. Both are rendered from this,
+ * so the two cannot drift into disagreeing about where the error is (#1884).
+ */
+export interface BuildFailureDetail {
+    file?: string;
+    line?: number;
+    column?: number;
+    message: string;
+    /** The offending source line, when Bun reported one. */
+    lineText?: string;
+}
+/**
+ * Pull every failure out of whatever was thrown, with positions intact.
  *
  * @param error whatever was thrown — BuildMessage, AggregateError, Error, or
  * anything else
  * @param sourcePath the real file being compiled. Preferred over the position's
  * own `file`, which is a synthetic entry name on the transpiler path.
  */
+export declare function describeBuildFailure(error: unknown, sourcePath?: string): BuildFailureDetail[];
+/**
+ * Render a build failure as `path:line:column: message`, falling back to the
+ * plain message when no position is available.
+ */
 export declare function formatBuildFailure(error: unknown, sourcePath?: string): string;
+/**
+ * Find a failure's line in the ORIGINAL source.
+ *
+ * The client-script bundler compiles a temp entry under `.stx/bundle-tmp`, so
+ * Bun's `position.line` counts lines in THAT file — for a `<script client>`
+ * block halfway down a page it is off by however many lines precede the block,
+ * and for an unresolved import it comes back as `-1`. Pointing an overlay at
+ * that line is worse than pointing at none: it sends the reader to code that is
+ * fine.
+ *
+ * `lineText` is the one thing that survives the move. If it occurs exactly once
+ * in the source, that is the line. Ambiguous or absent yields nothing, which the
+ * caller renders as a message with no frame.
+ */
+export declare function locateFailureLine(source: string, lineText?: string): number | undefined;
+/** One line of a code frame. */
+export interface CodeFrameLine {
+    number: number;
+    text: string;
+    /** The line the error is on. */
+    isError: boolean;
+}
+/**
+ * The lines around a failure, for an overlay to draw.
+ *
+ * Returns the offending line plus `context` lines either side, which is what
+ * turns "Could not resolve" into something a reader can act on without opening
+ * the file. Empty when there is no line to centre on.
+ */
+export declare function buildCodeFrame(source: string, line?: number, context?: number): CodeFrameLine[];

package/dist/build-message.js

@@ -9,18 +9,57 @@ function unwrap(error) {
     return error.errors;
   return [error];
 }
-export function formatBuildFailure(error, sourcePath) {
-  const parts = [];
+export function describeBuildFailure(error, sourcePath) {
+  const details = [];
   for (const item of unwrap(error)) {
     if (isBuildMessageLike(item)) {
-      const position = item.position || void 0, file = sourcePath || position?.file, where = file ? `${file}${position?.line ? `:${position.line}${position.column ? `:${position.column}` : ""}` : ""}` : "", snippet = position?.lineText ? `
-    ${position.lineText.trim()}` : "";
-      parts.push(where ? `${where}: ${item.message}${snippet}` : `${item.message}${snippet}`);
+      const position = item.position || void 0;
+      details.push({
+        file: sourcePath || position?.file,
+        line: position?.line,
+        column: position?.column,
+        message: item.message ?? "",
+        lineText: position?.lineText
+      });
       continue;
     }
-    const message = item instanceof Error ? item.message : String(item);
-    parts.push(sourcePath ? `${sourcePath}: ${message}` : message);
+    details.push({
+      file: sourcePath,
+      message: item instanceof Error ? item.message : String(item)
+    });
   }
-  return parts.join(`
+  return details;
+}
+export function formatBuildFailure(error, sourcePath) {
+  return describeBuildFailure(error, sourcePath).map((detail) => {
+    const where = detail.file ? `${detail.file}${detail.line ? `:${detail.line}${detail.column ? `:${detail.column}` : ""}` : ""}` : "", snippet = detail.lineText ? `
+    ${detail.lineText.trim()}` : "";
+    return where ? `${where}: ${detail.message}${snippet}` : `${detail.message}${snippet}`;
+  }).join(`
+`);
+}
+export function locateFailureLine(source, lineText) {
+  const needle = lineText?.trim();
+  if (!needle)
+    return;
+  const lines = source.split(`
 `);
+  let found;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].trim() !== needle)
+      continue;
+    if (found !== void 0)
+      return;
+    found = i + 1;
+  }
+  return found;
+}
+export function buildCodeFrame(source, line, context = 2) {
+  if (!line || line < 1)
+    return [];
+  const lines = source.split(`
+`), start = Math.max(1, line - context), end = Math.min(lines.length, line + context), frame = [];
+  for (let n = start;n <= end; n++)
+    frame.push({ number: n, text: lines[n - 1] ?? "", isError: n === line });
+  return frame;
 }

package/dist/builtins/attrs.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Attribute pass-through for builtin components.
+ *
+ * `<StxLink>`, `<StxImage>` and `<SafeImage>` all consume the props they know
+ * about and forward whatever is left onto the element they render, so an author
+ * can write `<StxLink to="/x" aria-label="Shop" data-testid="nav">` and have the
+ * last two land on the `<a>`. Each of them grew its own copy of that loop, which
+ * meant each of them independently forwarded the *camelized* prop key — emitting
+ * `ariaLabel="Shop"`, an attribute no browser knows.
+ *
+ * One implementation, so the naming round-trip is right in one place.
+ *
+ * @module builtins/attrs
+ */
 import type { ResolvedProps } from '../component-registry';
 /**
  * Render the static props a builtin did not consume as HTML attributes.

package/dist/builtins/drawer.d.ts

@@ -1,2 +1,24 @@
+/**
+ * StxDrawer Builtin Component
+ *
+ * Renders a hidden slide-in panel with slot content. Opened/closed via
+ * the runtime `drawer.open(id)` / `drawer.close(id)` / `drawer.toggle(id)` globals.
+ *
+ * Usage:
+ *   <StxDrawer id="settings" side="right" size="md">
+ *     <h2>Settings</h2>
+ *     <p>Drawer content here</p>
+ *   </StxDrawer>
+ *
+ * Props:
+ *   - id (required) — unique drawer identifier
+ *   - side — 'left' | 'right' (default: 'right')
+ *   - size — 'sm' | 'md' | 'lg' | 'xl' (default: 'md')
+ *   - closeOnBackdrop — whether clicking backdrop closes drawer (default: true)
+ *   - closeOnEscape — whether Escape key closes drawer (default: true)
+ *   - overlay — whether to show backdrop overlay (default: true)
+ *
+ * @module builtins/drawer
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxDrawerBuiltin: BuiltinComponentDef;

package/dist/builtins/icon.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Icon Builtin Component
+ *
+ * Renders an inline SVG from the Iconify icon library at template processing
+ * time. No client-side runtime needed — the SVG is baked into the HTML.
+ *
+ * Usage:
+ *   <Icon name="house" />
+ *   <Icon name="lucide:house" size="20" class="text-gray-500" />
+ *   <Icon name="chevron-right" size="16" color="red" />
+ *
+ * Default collection: lucide. Override with prefix: <Icon name="heroicons:home" />
+ *
+ * @module builtins/icon
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 /**
  * Resolve the on-disk path of an icon collection JSON.
@@ -14,10 +29,9 @@ import type { BuiltinComponentDef } from '../component-registry';
  * node_modules in apps that vendor there).
  */
 export declare function resolveCollectionPath(prefix: string): string | null;
+export declare const IconBuiltin: BuiltinComponentDef;
 /**
  * Pre-load icon collections so they're available synchronously during render.
  * Call this before template processing starts.
  */
 export declare function preloadIconCollection(prefix?: string): Promise<void>;
-export declare const IconBuiltin: BuiltinComponentDef;
-declare type IconCollection = Record<string, { body: string, width?: number, height?: number }>;

package/dist/builtins/index.d.ts

@@ -1,18 +1,3 @@
-import { IconBuiltin } from './icon';
-import { SafeImageBuiltin } from './safe-image';
-import { StxDrawerBuiltin } from './drawer';
-import { StxImageBuiltin } from './stx-image';
-import { StxLinkBuiltin } from './stx-link';
-import { StxLoadingIndicatorBuiltin } from './stx-loading-indicator';
-import { StxModalBuiltin } from './modal';
-import { StxToastBuiltin } from './toast';
-import { SuspenseBuiltin } from './suspense';
-import { TransitionGroupBuiltin } from './transition-group';
-/**
- * Register all builtin components with the singleton registry.
- * Call this once during framework initialization.
- */
-export declare function registerBuiltins(): void;
 /**
  * Builtin Components Barrel
  *
@@ -33,3 +18,8 @@ export { IconBuiltin, preloadIconCollection } from './icon';
 export { getTooltipRuntime } from './tooltip';
 export { SuspenseBuiltin } from './suspense';
 export { TransitionGroupBuiltin } from './transition-group';
+/**
+ * Register all builtin components with the singleton registry.
+ * Call this once during framework initialization.
+ */
+export declare function registerBuiltins(): void;

package/dist/builtins/modal.d.ts

@@ -1,2 +1,26 @@
+/**
+ * StxModal Builtin Component
+ *
+ * Renders a hidden modal dialog with slot content. Opened/closed via
+ * the runtime `modal.open(id)` / `modal.close(id)` globals.
+ *
+ * Usage:
+ *   <StxModal id="settings">
+ *     <h2>Settings</h2>
+ *     <p>Modal content here</p>
+ *   </StxModal>
+ *
+ *   <StxModal id="delete-confirm" size="sm" closeOnBackdrop="false">
+ *     <h3>Are you sure?</h3>
+ *   </StxModal>
+ *
+ * Props:
+ *   - id (required) — unique modal identifier
+ *   - size — 'sm' | 'md' | 'lg' | 'xl' | 'full' (default: 'md')
+ *   - closeOnBackdrop — whether clicking backdrop closes modal (default: true)
+ *   - closeOnEscape — whether Escape key closes modal (default: true)
+ *
+ * @module builtins/modal
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxModalBuiltin: BuiltinComponentDef;

package/dist/builtins/safe-image.d.ts

@@ -1,2 +1,44 @@
+/**
+ * SafeImage Builtin Component
+ *
+ * Drop-in `<img>` replacement with a declarative broken-image fallback.
+ * Third-party image URLs (external-CDN avatars, user content that gets
+ * deleted, seed data pointing at links that 404) fail frequently in
+ * production; without intervention the browser draws the alt text inside
+ * whatever layout frame the `<img>` had — round avatar frames in
+ * particular look broken.
+ *
+ * SafeImage wires an inline `onerror=` handler that swaps to a fallback
+ * image (and optionally swaps the class string) when the primary src
+ * fails to load.
+ *
+ * Usage:
+ *   <SafeImage src="/avatars/u.png" alt="User" fallback="/avatars/default.svg" />
+ *   <SafeImage :src="judge.photo" :alt="judge.name"
+ *              className="h-12 w-12 rounded-full grayscale filter"
+ *              fallbackClassName="h-12 w-12 rounded-full"
+ *              fallback="/images/avatars/default-judge.svg" />
+ *
+ * Why inline `onerror=` rather than a delegated capture-phase listener:
+ * `error` events don't bubble, so a listener attached by a component's
+ * `<script client>` IIFE runs AFTER the element's first load attempt —
+ * cached 404s and offline first paint slip past it. The inline HTML
+ * `onerror=` attribute is parsed-and-attached synchronously with the
+ * element by the browser's HTML parser, before the image request fires.
+ * That's the only race-free option for the error path.
+ *
+ * Why a single window-level handler rather than per-instance inline
+ * closures: keeps rendered HTML small (a ~35-byte attribute vs. a
+ * ~120-byte inline function body per `<img>`). The handler is emitted
+ * once per page render (gated on a render-context flag) and registered
+ * once per browser session (gated on the `window.__stxSafeImageHandler`
+ * existence check, so it's also idempotent across SPA navigation).
+ * Per-instance config travels via `data-*` attributes, so the handler
+ * stays stateless.
+ *
+ * Resolves stacksjs/stx#1732.
+ *
+ * @module builtins/safe-image
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const SafeImageBuiltin: BuiltinComponentDef;

package/dist/builtins/stx-image.d.ts

@@ -1,2 +1,29 @@
+/**
+ * StxImage Builtin Component
+ *
+ * Full-featured image component matching NuxtImage capabilities:
+ *
+ * - Auto `loading="lazy"` + `decoding="async"`
+ * - Responsive `srcset` + `sizes` auto-generation from breakpoints
+ * - Density descriptors (`1x`, `2x`, `3x`)
+ * - `<picture>` wrapper with format negotiation (avif, webp fallback)
+ * - Blur-up / color / empty placeholder modes
+ * - Aspect ratio preservation (CLS prevention)
+ * - Preload hint injection (`<link rel="preload">`)
+ * - CDN provider support (Cloudinary, imgix, custom)
+ *
+ * Usage:
+ *   <StxImage src="/images/hero.jpg" alt="Hero" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" width="800" height="600" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" sizes="sm:100vw md:50vw lg:33vw" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" densities="1x 2x" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" format="webp" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" placeholder="blur" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" placeholder="thumbhash" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" preload />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" provider="cloudinary" />
+ *
+ * @module builtins/stx-image
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxImageBuiltin: BuiltinComponentDef;

package/dist/builtins/stx-link.d.ts

@@ -1,2 +1,11 @@
+/**
+ * StxLink Builtin Component
+ *
+ * Renders a client-side navigation-aware `<a>` element with support for
+ * active class management, prefetching, and reactive href bindings.
+ * Produces plain HTML — no wrapper component or custom element overhead.
+ *
+ * @module builtins/stx-link
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxLinkBuiltin: BuiltinComponentDef;

package/dist/builtins/stx-loading-indicator.d.ts

@@ -1,2 +1,13 @@
+/**
+ * StxLoadingIndicator Builtin Component
+ *
+ * Renders a fixed-position progress bar at the top of the viewport that
+ * activates on navigation. Includes shimmer animation, automatic
+ * link-click interception, and a global `window.stxLoading` API.
+ *
+ * Ported from the inline implementation in component-processing.ts.
+ *
+ * @module builtins/stx-loading-indicator
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxLoadingIndicatorBuiltin: BuiltinComponentDef;

package/dist/builtins/suspense.d.ts

@@ -1,2 +1,30 @@
+/**
+ * Suspense Builtin Component (stacksjs/stx#1742)
+ *
+ * A client loading boundary. Renders three regions that the signals runtime
+ * (`bindSuspense`) toggles based on the aggregated state of descendant suspense
+ * queries (`useQuery` / `useFetch` with `{ suspense: true }`):
+ *
+ *   - `[data-stx-suspense-fallback]` — shown while any descendant query loads
+ *   - `[data-stx-suspense-error]`    — shown when a descendant query errors
+ *   - `[data-stx-suspense-content]`  — shown once all descendant queries resolve
+ *
+ * The default slot is the content; `fallback` / `errorFallback` come from props
+ * or from `slot="fallback"` / `slot="error"` elements in the slot content.
+ *
+ * ```stx
+ * <Suspense fallback="Loading…">
+ *   <CommentsList />   <!-- uses useQuery(url, { suspense: true }) -->
+ * </Suspense>
+ *
+ * <Suspense>
+ *   <template slot="fallback"><Skeleton count="2" /></template>
+ *   <template slot="error">Couldn't load comments.</template>
+ *   <CommentsList />
+ * </Suspense>
+ * ```
+ *
+ * @module builtins/suspense
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const SuspenseBuiltin: BuiltinComponentDef;

package/dist/builtins/toast.d.ts

@@ -1,2 +1,19 @@
+/**
+ * StxToast Builtin Component
+ *
+ * Renders a fixed-position toast notification container. The runtime
+ * `toast()` global (success / error / info / warning / dismiss) creates
+ * and animates individual toast elements inside this container.
+ *
+ * Usage:
+ *   <StxToast />
+ *   <StxToast position="top-right" max="5" />
+ *   <StxToast position="bottom-left" />
+ *
+ * Positions: top-right (default), top-left, top-center,
+ *            bottom-right, bottom-left, bottom-center
+ *
+ * @module builtins/toast
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const StxToastBuiltin: BuiltinComponentDef;

package/dist/builtins/transition-group.d.ts

@@ -1,2 +1,27 @@
+/**
+ * TransitionGroup Builtin Component (stacksjs/stx#1742)
+ *
+ * Class-driven enter/leave + FLIP move animations for a keyed list. Renders a
+ * single wrapper element marked `data-stx-transition-group="<name>"`; the
+ * signals runtime's `bindFor` animates the list items inside it when they are
+ * added, removed, or reordered.
+ *
+ * The default slot must contain a single `:for` (or `x-for`) element whose
+ * rendered items become the wrapper's direct children:
+ *
+ * ```stx
+ * <TransitionGroup name="card" tag="ul" class="space-y-2">
+ *   <li :for="r in reviews()" :key="r.id" class="card">{{ r.title }}</li>
+ * </TransitionGroup>
+ * ```
+ *
+ * With `name="card"`, supply the transition classes (e.g. via crosswind/CSS):
+ * `card-enter-from` / `card-enter-active` / `card-enter-to`,
+ * `card-leave-from` / `card-leave-active` / `card-leave-to`, and `card-move`
+ * (applied to elements that shift position during a reorder). The first render
+ * does not animate; subsequent list changes do.
+ *
+ * @module builtins/transition-group
+ */
 import type { BuiltinComponentDef } from '../component-registry';
 export declare const TransitionGroupBuiltin: BuiltinComponentDef;

package/dist/caching.d.ts

@@ -1,4 +1,13 @@
 import type { StxOptions } from './types';
+/**
+ * Cache entry structure
+ */
+interface CacheEntry {
+    output: string;
+    mtime: number;
+    dependencies: Set<string>;
+}
+export declare const templateCache: Map<string, CacheEntry>;
 /**
  * Read a file with mtime-based caching.
  * Returns cached content if file hasn't been modified since last read.
@@ -21,6 +30,8 @@ export declare function invalidateFileCache(filePath: string): void;
  * Invalidate all files matching a pattern from the content cache.
  */
 export declare function invalidateFileCacheByDir(dirPath: string): void;
+/** The two runtime generators caching depends on (subset of `./signals`). */
+type SignalsGenerators = Pick<typeof import('./signals'), 'generateSignalsRuntime' | 'generateSignalsRuntimeDev'>;
 /** @internal test-only — inject (or, with `null`, restore) the signals generators. */
 export declare function __setSignalsGeneratorsForTest(generators: SignalsGenerators | null): void;
 /**
@@ -55,18 +66,4 @@ export declare function cacheTemplate(filePath: string, output: string, dependen
  * @returns A 16-character hex string suitable for use as a filename
  */
 export declare function hashFilePath(filePath: string): string;
-// Memory cache for compiled templates
-export declare const templateCache: Map<string, CacheEntry>;
-/**
- * Cache entry structure
- */
-declare interface CacheEntry {
-  output: string
-  mtime: number
-  dependencies: Set<string>
-}
-/** The two runtime generators caching depends on (subset of `./signals`). */
-declare type SignalsGenerators = Pick<
-  typeof import('./signals'),
-  'generateSignalsRuntime' | 'generateSignalsRuntimeDev'
->;
+export {};