@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/build-views.js

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import path from "node:path";
+import { extractVariables } from "./variable-extractor.js";
+import { defaultConfig } from "./config.js";
+import { processDirectives } from "./process.js";
+export async function renderView(templatePath, props = {}, options = {}) {
+  const content = await Bun.file(templatePath).text(), scriptMatch = content.match(/<script\s+server\s*>([\s\S]*?)<\/script>/i), scriptContent = scriptMatch ? scriptMatch[1] : "";
+  let templateContent = scriptMatch ? content.replace(/<script\s+server\s*>[\s\S]*?<\/script>/i, "") : content;
+  templateContent = templateContent.replace(/<script\s+client\s*>/gi, "<script>");
+  const context = {
+    __filename: templatePath,
+    __dirname: path.dirname(templatePath),
+    props,
+    ...props
+  };
+  if (scriptContent)
+    await extractVariables(scriptContent, context, templatePath);
+  const config = {
+    ...defaultConfig,
+    ...options
+  };
+  return await processDirectives(templateContent, context, templatePath, config, new Set);
+}
+export async function buildViews(options) {
+  const startTime = performance.now(), result = {
+    success: !0,
+    views: [],
+    errors: [],
+    duration: 0
+  }, {
+    viewsDir,
+    outputDir,
+    componentsDir = path.join(viewsDir, "components"),
+    layoutsDir = path.join(viewsDir, "layouts"),
+    partialsDir = path.join(viewsDir, "partials"),
+    globalProps = {},
+    placeholders = {},
+    views,
+    debug = !1,
+    generateManifest = !0
+  } = options;
+  if (debug) {
+    console.log("Building STX views...");
+    console.log(`  Source: ${viewsDir}`);
+    console.log(`  Output: ${outputDir}`);
+  }
+  fs.mkdirSync(outputDir, { recursive: !0 });
+  const stxOptions = {
+    componentsDir,
+    layoutsDir,
+    partialsDir,
+    debug
+  };
+  let viewsToBuild;
+  if (views && views.length > 0)
+    viewsToBuild = views;
+  else
+    viewsToBuild = fs.readdirSync(viewsDir).filter((f) => f.endsWith(".stx")).map((f) => ({ input: f }));
+  for (const view of viewsToBuild) {
+    const inputPath = path.join(viewsDir, view.input), outputName = view.output || view.input.replace(/\.stx$/, ".html"), outputPath = path.join(outputDir, outputName);
+    if (debug)
+      console.log(`  Building ${view.input}...`);
+    try {
+      const props = {
+        ...globalProps,
+        ...view.props,
+        ...placeholders
+      }, html = await renderView(inputPath, props, stxOptions);
+      await Bun.write(outputPath, html);
+      result.views.push(outputName);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      result.errors.push({ file: view.input, error: errorMessage });
+      result.success = !1;
+      if (debug)
+        console.error(`    Error: ${errorMessage}`);
+    }
+  }
+  if (generateManifest) {
+    const manifest = {
+      buildTime: new Date().toISOString(),
+      views: result.views,
+      placeholders,
+      errors: result.errors.length > 0 ? result.errors : void 0
+    };
+    await Bun.write(path.join(outputDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  }
+  result.duration = performance.now() - startTime;
+  if (debug)
+    if (result.success)
+      console.log(`
+\u2705 Built ${result.views.length} views in ${result.duration.toFixed(0)}ms`);
+    else
+      console.log(`
+\u26A0\uFE0F Built ${result.views.length} views with ${result.errors.length} errors`);
+  return result;
+}
+export function watchViews(options, callback) {
+  const watcher = fs.watch(options.viewsDir, { recursive: !0 }, async (eventType, filename) => {
+    if (!filename)
+      return;
+    if (filename.endsWith(".stx") || filename.endsWith(".ts") || filename.endsWith(".js")) {
+      if (options.debug)
+        console.log(`
+File changed: ${filename}, rebuilding...`);
+      const result = await buildViews(options);
+      callback?.(result);
+    }
+  });
+  return {
+    close: () => watcher.close()
+  };
+}
+export async function renderEmail(templatePath, props = {}, options = {}) {
+  const emailOptions = {
+    ...options,
+    skipDefaultSeoTags: !0,
+    skipSignalsRuntime: !0
+  };
+  let html = await renderView(templatePath, props, emailOptions);
+  html = await inlineCssClasses(html);
+  html = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+  html = html.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
+  html = html.replace(/<!--\s*stx SEO Tags\s*-->/gi, "");
+  html = html.replace(/\n\s*\n\s*\n/g, `
+
+`).trim();
+  const text = htmlToPlainText(html);
+  return { html, text };
+}
+async function inlineCssClasses(html) {
+  try {
+    const { generateCss, extractClassNames } = await import("./dev-server/ts-css.js");
+    if (extractClassNames(html).size === 0)
+      return html;
+    const css = await generateCss(html);
+    if (!css)
+      return html;
+    const classStyles = parseCssToMap(css);
+    if (classStyles.size === 0)
+      return html;
+    return html.replace(/(<[a-z][a-z0-9]*)((?:\s+[a-z][a-z0-9-]*(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*))?)*\s+)class\s*=\s*"([^"]*)"((?:\s+[a-z][a-z0-9-]*(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*))?)*\s*)(\/?>)/gi, (_match, tag, beforeClass, classValue, afterClass, closing) => {
+      const classNames = classValue.split(/\s+/).filter(Boolean), inlineProps = [];
+      for (const cls of classNames) {
+        const styles = classStyles.get(cls);
+        if (styles)
+          inlineProps.push(styles);
+      }
+      if (inlineProps.length === 0)
+        return `${tag}${beforeClass}class="${classValue}"${afterClass}${closing}`;
+      const inlineStyle = inlineProps.join("; "), existingStyleMatch = `${beforeClass}${afterClass}`.match(/style\s*=\s*"([^"]*)"/);
+      if (existingStyleMatch) {
+        const merged = `${inlineStyle}; ${existingStyleMatch[1]}`, updatedBefore = beforeClass.replace(/style\s*=\s*"[^"]*"/, `style="${merged}"`), updatedAfter = afterClass.replace(/style\s*=\s*"[^"]*"/, `style="${merged}"`);
+        return `${tag}${updatedBefore}class="${classValue}"${updatedAfter}${closing}`;
+      }
+      return `${tag}${beforeClass}class="${classValue}" style="${inlineStyle}"${afterClass}${closing}`;
+    });
+  } catch {
+    return html;
+  }
+}
+function parseCssToMap(css) {
+  const map = new Map, ruleRegex = /\.([a-zA-Z0-9_-]+(?:\\:[a-zA-Z0-9_-]+)*)\s*\{([^}]+)\}/g;
+  let match = ruleRegex.exec(css);
+  while (match !== null) {
+    const className = match[1].replace(/\\/g, ""), properties = match[2].split(";").map((p) => p.trim()).filter(Boolean).join("; ");
+    if (properties)
+      map.set(className, properties);
+    match = ruleRegex.exec(css);
+  }
+  return map;
+}
+function htmlToPlainText(html) {
+  return html.replace(/<br\s*\/?>/gi, `
+`).replace(/<\/(p|div|h[1-6]|li|tr)>/gi, `
+`).replace(/<\/td>/gi, "\t").replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&copy;/g, "(c)").replace(/&middot;/g, "-").replace(/\n\s*\n\s*\n/g, `
+
+`).trim();
+}
+export default buildViews;

package/dist/build.d.ts

@@ -0,0 +1,31 @@
+import type { BuildMode } from './build-mode-detector';
+import type { ProductionBuildOptions, ProductionBuildResult } from './production-builder';
+import type { SSGConfig, SSGResult } from './ssg';
+/**
+ * Unified build entry point for stx applications.
+ *
+ * Build mode is determined by the `ssr` field in `stx.config.ts`:
+ *
+ * - **`ssr: false`** (default) → SSG → `dist/` (flat HTML files for S3 + CloudFront).
+ *   `<script server>` blocks are executed at build time and their output is
+ *   baked into the static HTML. The server block is stripped from the output.
+ *
+ * - **`ssr: true`** → SSR → `.output/` (server bundle for EC2 behind CloudFront).
+ *   `<script server>` blocks run per-request on the Bun server.
+ *
+ * `<script server>` works in both modes — the `ssr` flag controls *when* it
+ * runs (build time vs request time), not whether it's allowed.
+ */
+export declare function buildApp(options?: UnifiedBuildOptions): Promise<UnifiedBuildResult>;
+export declare interface UnifiedBuildOptions {
+  root?: string
+  debug?: boolean
+  ssg?: Partial<SSGConfig>
+  ssr?: Partial<ProductionBuildOptions>
+}
+export declare interface UnifiedBuildResult {
+  mode: BuildMode
+  ssg?: SSGResult
+  ssr?: ProductionBuildResult
+  duration: number
+}

package/dist/build.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { loadStxConfig } from "./config.js";
+export async function buildApp(options = {}) {
+  const startTime = performance.now(), root = options.root || process.cwd(), config = await loadStxConfig(), mode = config.ssr ? "ssr" : "ssg";
+  console.log(`[stx build] Mode: ${mode.toUpperCase()}${config.ssr ? " (ssr: true in stx.config.ts)" : " (default \u2014 ssr is false)"}`);
+  let ssgResult, ssrResult;
+  if (mode === "ssg") {
+    const { generateStaticSite } = await import("./ssg.js");
+    ssgResult = await generateStaticSite({
+      pagesDir: path.join(config.root || ".", config.pagesDir || config.build?.pagesDir || "pages"),
+      publicDir: config.publicDir || config.build?.publicDir || "public",
+      outputDir: config.build?.outputDir || "dist",
+      generate404: config.build?.generate404 ?? !0,
+      minify: config.build?.minify ?? !0,
+      cleanOutput: config.build?.cleanOutput ?? !0,
+      router: config.router,
+      ...options.ssg
+    });
+  } else {
+    const { buildForProduction } = await import("./production-builder.js");
+    ssrResult = await buildForProduction({
+      outputDir: ".output",
+      debug: options.debug,
+      ...options.ssr
+    });
+  }
+  const duration = Math.round(performance.now() - startTime);
+  return {
+    mode,
+    ssg: ssgResult,
+    ssr: ssrResult,
+    duration
+  };
+}

package/dist/builtins/attrs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ *
+ * Names come back spelled the way the author wrote them: prop resolution
+ * camelizes static attributes so a `.stx` component can destructure them, and
+ * `staticNames` carries the original for exactly this case. Values are escaped —
+ * a static attribute can still hold hostile text (`aria-label="<script>…"`).
+ *
+ * Boolean props render as bare attributes when true and are dropped when false,
+ * matching how HTML boolean attributes work.
+ *
+ * @param props - The component's resolved props.
+ * @param consumed - Prop names the builtin has already rendered itself.
+ */
+export declare function forwardStaticAttrs(props: ResolvedProps, consumed: Set<string>): string[];
+/**
+ * Render the server-evaluated `:prop` bindings a builtin did not consume.
+ *
+ * Only `static` was ever forwarded, so `<StxLink to="/x" :title="pageTitle">`
+ * emitted an `<a>` with no title and no warning — the binding was resolved,
+ * stored, and thrown away (stacksjs/stx#1930). Client-reactive `:prop` and
+ * `@event` bindings already reach the element by another route (the component
+ * renderer re-applies them to the root), which is what made the gap specific to
+ * the server-evaluated ones and easy to miss.
+ *
+ * `null`, `undefined` and `false` DROP the attribute rather than rendering the
+ * word — that is what makes `:aria-current="active ? 'page' : null"` express
+ * "this attribute is conditional", which is the whole reason to reach for a
+ * binding instead of a literal. `true` renders bare, as HTML booleans do.
+ *
+ * @param props - The component's resolved props.
+ * @param consumed - Prop names the builtin has already rendered itself.
+ */
+export declare function forwardResolvedAttrs(props: ResolvedProps, consumed: Set<string>): string[];

package/dist/builtins/attrs.js

@@ -0,0 +1,39 @@
+import { escapeAttr } from "./escape.js";
+import { BOOLEAN_ATTRIBUTE_SENTINEL, stripControlChars } from "../prop-sentinels.js";
+export function forwardStaticAttrs(props, consumed) {
+  const attrs = [];
+  for (const [key, value] of Object.entries(props.static)) {
+    if (consumed.has(key))
+      continue;
+    const name = props.staticNames?.[key] ?? key;
+    if (typeof value === "boolean") {
+      if (value)
+        attrs.push(escapeAttr(name));
+      continue;
+    }
+    if (value === BOOLEAN_ATTRIBUTE_SENTINEL) {
+      attrs.push(escapeAttr(name));
+      continue;
+    }
+    attrs.push(`${escapeAttr(name)}="${escapeAttr(stripControlChars(String(value)))}"`);
+  }
+  return attrs;
+}
+export function forwardResolvedAttrs(props, consumed) {
+  const attrs = [];
+  for (const [key, value] of Object.entries(props.serverDynamic ?? {})) {
+    if (consumed.has(key))
+      continue;
+    if (value === null || value === void 0 || value === !1)
+      continue;
+    const name = props.serverDynamicNames?.[key] ?? key;
+    if (value === !0) {
+      attrs.push(escapeAttr(name));
+      continue;
+    }
+    if (typeof value === "object")
+      continue;
+    attrs.push(`${escapeAttr(name)}="${escapeAttr(stripControlChars(String(value)))}"`);
+  }
+  return attrs;
+}

package/dist/builtins/drawer.d.ts

@@ -0,0 +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/drawer.js

@@ -0,0 +1,37 @@
+import { escapeAttr } from "./escape.js";
+function resolveProp(props, key) {
+  if (props.serverDynamic[key] !== void 0)
+    return String(props.serverDynamic[key]);
+  const val = props.static[key];
+  if (typeof val === "string")
+    return val;
+  return;
+}
+const SIZE_WIDTHS = {
+  sm: "16rem",
+  md: "24rem",
+  lg: "32rem",
+  xl: "40rem"
+};
+export const StxDrawerBuiltin = {
+  name: "StxDrawer",
+  aliases: ["stx-drawer"],
+  render(props, slotContent, _ctx) {
+    const rawId = resolveProp(props, "id");
+    if (!rawId) {
+      console.warn('[stx] <StxDrawer> requires an "id" prop');
+      return "<!-- StxDrawer: missing id prop -->";
+    }
+    const id = escapeAttr(rawId), side = resolveProp(props, "side") || "right", size = resolveProp(props, "size") || "md", closeOnBackdrop = resolveProp(props, "closeOnBackdrop") !== "false", closeOnEscape = resolveProp(props, "closeOnEscape") !== "false", overlay = resolveProp(props, "overlay") !== "false", width = SIZE_WIDTHS[size] || SIZE_WIDTHS.md, isLeft = side === "left", positionStyle = isLeft ? "left:0" : "right:0", translateHidden = isLeft ? "translateX(-100%)" : "translateX(100%)", animName = isLeft ? "stx-drawer-slide-left" : "stx-drawer-slide-right";
+    return `<div id="stx-drawer-${id}" class="stx-drawer-backdrop" data-stx-drawer="${id}" data-close-backdrop="${closeOnBackdrop}" data-close-escape="${closeOnEscape}" style="display:none;position:fixed;inset:0;z-index:99999;${overlay ? "background:rgba(0,0,0,0.5);backdrop-filter:blur(2px)" : "background:transparent;pointer-events:none"};opacity:0;transition:opacity 0.2s ease" role="dialog" aria-modal="true">
+  <div class="stx-drawer-panel" style="position:fixed;top:0;bottom:0;${positionStyle};width:${width};max-width:100vw;transform:${translateHidden};transition:transform 0.3s cubic-bezier(0.4,0,0.2,1);background:var(--stx-drawer-bg,#fff);color:var(--stx-drawer-text,#1f2937);box-shadow:0 20px 60px rgba(0,0,0,0.3);overflow-y:auto;pointer-events:auto">
+    <div style="padding:1.5rem">${slotContent}</div>
+  </div>
+</div>
+<style>
+@media(prefers-color-scheme:dark){[data-stx-drawer]{--stx-drawer-bg:#1f2937;--stx-drawer-text:#f3f4f6}}
+.stx-drawer-backdrop[data-stx-drawer-open]{display:block!important;opacity:1}
+.stx-drawer-backdrop[data-stx-drawer-open] .stx-drawer-panel{transform:translateX(0)}
+</style>`;
+  }
+};

package/dist/builtins/escape.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared HTML-attribute escaping for builtin components.
+ *
+ * Builtins interpolate prop values directly into their rendered markup. Any value
+ * that can come from untrusted data (a `:prop="userData.x"` lands in
+ * `serverDynamic`) must be escaped before it goes into an attribute, or a value
+ * like `x" onload="alert(1)` breaks out of the attribute — an XSS sink.
+ *
+ * Escapes the five attribute-significant characters. Safe for both double- and
+ * single-quoted attribute contexts.
+ */
+export declare function escapeAttr(value: string): string;

package/dist/builtins/escape.js

@@ -0,0 +1,3 @@
+export function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/builtins/icon.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * Two packaging conventions are accepted. `@iconify/json` ships every
+ * collection in one ~120MB dependency; `@iconify-json/<prefix>` ships a single
+ * collection in about a megabyte and is what most projects actually install.
+ * Supporting only the monolith meant an app with `@iconify-json/lucide`
+ * installed rendered nothing at all for every icon on every page, with no
+ * error to explain it.
+ *
+ * Each convention is checked through the package resolver first, then against
+ * `node_modules/` and Stacks-style `pantry/` (which sits parallel to
+ * 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.
+ *
+ * Silent when the collection is not installed. Callers preload on the chance a
+ * template wants it, so an absent collection here is a normal outcome and not
+ * a problem to report; the render path still says so if a template actually
+ * asks for one that is missing. Pass `speculative: false` when the caller knows
+ * the collection is required.
+ */
+export declare function preloadIconCollection(prefix?: string, options?: {
+    speculative?: boolean;
+}): Promise<void>;

package/dist/builtins/icon.js

@@ -0,0 +1,100 @@
+var {require}=import.meta;import { escapeAttr } from "./escape.js";
+import { existsSync, readFileSync } from "node:fs";
+const collectionCache = new Map, warnedMissingCollections = new Set;
+function warnMissingCollection(prefix) {
+  if (warnedMissingCollections.has(prefix))
+    return;
+  warnedMissingCollections.add(prefix);
+  console.warn(`[stx] icon collection "${prefix}" is not installed, so its icons render as nothing. Install it with \`bun add -d @iconify-json/${prefix}\`.`);
+}
+export function resolveCollectionPath(prefix) {
+  const cwd = process.cwd();
+  for (const candidate of [
+    `${cwd}/node_modules/@iconify-json/${prefix}/icons.json`,
+    `${cwd}/pantry/@iconify-json/${prefix}/icons.json`,
+    `${cwd}/node_modules/@iconify/json/json/${prefix}.json`,
+    `${cwd}/pantry/@iconify/json/json/${prefix}.json`
+  ])
+    if (existsSync(candidate))
+      return candidate;
+  for (const specifier of [
+    `@iconify-json/${prefix}/icons.json`,
+    `@iconify/json/json/${prefix}.json`
+  ])
+    try {
+      return require.resolve(specifier);
+    } catch {}
+  return null;
+}
+function loadCollectionSync(prefix) {
+  if (collectionCache.has(prefix))
+    return collectionCache.get(prefix);
+  const jsonPath = resolveCollectionPath(prefix);
+  if (!jsonPath) {
+    warnMissingCollection(prefix);
+    return null;
+  }
+  try {
+    const data = JSON.parse(readFileSync(jsonPath, "utf8"));
+    collectionCache.set(prefix, data.icons);
+    return data.icons;
+  } catch {
+    return null;
+  }
+}
+async function loadCollection(prefix, speculative = !1) {
+  if (collectionCache.has(prefix))
+    return collectionCache.get(prefix);
+  const jsonPath = resolveCollectionPath(prefix);
+  if (!jsonPath) {
+    if (!speculative)
+      warnMissingCollection(prefix);
+    return null;
+  }
+  try {
+    const data = await Bun.file(jsonPath).json();
+    collectionCache.set(prefix, data.icons);
+    return data.icons;
+  } catch {
+    return null;
+  }
+}
+function resolveProp(props, key) {
+  if (props.serverDynamic[key] !== void 0)
+    return String(props.serverDynamic[key]);
+  if (props.static[key] !== void 0)
+    return String(props.static[key]);
+  if (props.clientReactive[key] !== void 0)
+    return props.clientReactive[key];
+  return;
+}
+export const IconBuiltin = {
+  name: "Icon",
+  aliases: ["icon", "stx-icon"],
+  render(props, _slotContent, _ctx) {
+    const nameRaw = resolveProp(props, "name") ?? resolveProp(props, "icon");
+    if (!nameRaw)
+      return "<!-- Icon: missing name/icon prop -->";
+    let collection = "lucide", iconName = nameRaw;
+    if (nameRaw.includes(":")) {
+      const parts = nameRaw.split(":");
+      collection = parts[0];
+      iconName = parts[1];
+    }
+    const size = escapeAttr(resolveProp(props, "size") || "24"), color = escapeAttr(resolveProp(props, "color") || "currentColor"), className = escapeAttr(resolveProp(props, "class") || ""), style = escapeAttr(resolveProp(props, "style") || ""), icons = collectionCache.get(collection) ?? loadCollectionSync(collection);
+    if (!icons)
+      return `<!-- Icon: collection "${collection}" not loaded -->`;
+    const iconData = icons[iconName];
+    if (!iconData)
+      return `<!-- Icon: "${iconName}" not found in ${collection} -->`;
+    const width = iconData.width || 24, height = iconData.height || 24, viewBox = `0 0 ${width} ${height}`;
+    let body = iconData.body;
+    if (color !== "currentColor")
+      body = body.replace(/currentColor/g, color);
+    const classAttr = className ? ` class="${className}"` : "", styleAttr = style ? ` style="${style}"` : "";
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${viewBox}" fill="none"${classAttr}${styleAttr}>${body}</svg>`;
+  }
+};
+export async function preloadIconCollection(prefix = "lucide", options = {}) {
+  await loadCollection(prefix, options.speculative ?? !0);
+}

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

@@ -0,0 +1,16 @@
+import type { ImageDeliveryManifest } from 'ts-images/delivery';
+/** Return build-time delivery metadata for one public image URL. */
+export declare function getImageDelivery(src: string): ImageDeliveryManifest | undefined;
+/** Clear process-global delivery state between builds and tests. */
+export declare function clearImageDeliveryCatalog(): void;
+/**
+ * Optimize every raster in the public directory before templates render.
+ *
+ * The builtin render pass is synchronous, so it consumes this in-memory
+ * catalog. Its content fingerprint is folded into the SSG cache key to ensure
+ * changing image bytes can never reuse HTML pointing at an older asset hash.
+ */
+export declare function prepareImageDelivery(publicDir: string, outputDir: string): Promise<{
+    count: number;
+    fingerprint: string;
+}>;