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

package/dist/image-optimization/processor.d.ts

@@ -0,0 +1,140 @@
+import path from 'node:path';
+/**
+ * Check if sharp is available (returns true only if sharp is installed).
+ *
+ * Note: image processing always works now via `ts-images`; this only reports
+ * whether the optional sharp fast-path is present. Use {@link isImageBackendAvailable}
+ * to gate "can we optimize at all" — the answer is always yes.
+ */
+export declare function isSharpAvailable(): Promise<boolean>;
+/**
+ * Whether any image-processing backend is available. Always true now that
+ * `ts-images` is bundled as a hard dependency — kept as a function for
+ * symmetry with `isSharpAvailable` and so callers can future-proof against
+ * a hypothetical "headless" build that strips ts-images.
+ */
+export declare function isImageBackendAvailable(): Promise<boolean>;
+/**
+ * Process an image and generate responsive variants
+ */
+export declare function processImage(input: string | Buffer, options?: ImageOptions): Promise<ProcessedImage>;
+/**
+ * Get image metadata
+ */
+export declare function getImageMetadata(input: Buffer | string): Promise<ImageMetadata>;
+/**
+ * Resize and convert image.
+ *
+ * Tries sharp first if installed (faster on large images), falls back to
+ * `ts-images` (pure-TS codecs, always available). `ts-images` is file-
+ * oriented so we route the output through a temp file and read it back.
+ */
+export declare function resizeAndConvert(buffer: Buffer, options: {
+    width: number
+    height: number
+    format: ImageFormat
+    quality: number
+    fit: string
+  }): Promise<Buffer>;
+/**
+ * Generate srcset attribute from variants
+ */
+export declare function generateSrcSet(variants: ImageVariant[], format?: ImageFormat): string;
+/**
+ * Generate sizes attribute
+ */
+export declare function generateSizes(breakpoints?: Record<string, string>): string;
+/**
+ * Get best fallback variant (middle resolution JPEG)
+ */
+export declare function getFallbackVariant(variants: ImageVariant[]): ImageVariant | undefined;
+/**
+ * Group variants by format
+ */
+export declare function groupVariantsByFormat(variants: ImageVariant[]): Map<ImageFormat, ImageVariant[]>;
+/**
+ * Check if file is an image
+ */
+export declare function isImageFile(filePath: string): boolean;
+/**
+ * Get MIME type for format
+ */
+export declare function getMimeType(format: ImageFormat): string;
+/**
+ * Calculate total size of variants
+ */
+export declare function getTotalSize(variants: ImageVariant[]): number;
+/**
+ * Format file size for display
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * ============================================================================
+// Constants
+// ============================================================================
+ * @defaultValue `[320, 640, 768, 1024, 1280, 1536, 1920]`
+ */
+export declare const DEFAULT_WIDTHS: number[];
+export declare const DEFAULT_FORMATS: ImageFormat[];
+export declare const DEFAULT_QUALITY: 80;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageOptions {
+  widths?: number[]
+  formats?: ImageFormat[]
+  quality?: number
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+  placeholder?: 'blur' | 'dominant-color' | 'thumbhash' | 'none'
+  outputDir?: string
+  baseUrl?: string
+}
+export declare interface ProcessedImage {
+  src: string
+  variants: ImageVariant[]
+  placeholder?: string
+  width: number
+  height: number
+  aspectRatio: number
+  hash: string
+}
+export declare interface ImageVariant {
+  path: string
+  url: string
+  width: number
+  height: number
+  format: ImageFormat
+  size: number
+}
+export declare interface ImageMetadata {
+  width: number
+  height: number
+  format: string
+  hasAlpha?: boolean
+}
+export type ImageFormat = 'webp' | 'avif' | 'jpeg' | 'png';
+// ============================================================================
+// Sharp Integration
+// ============================================================================
+declare type SharpInstance = {
+  metadata(): Promise<ImageMetadata>
+  resize(width: number, height?: number, options?: { fit?: string }): SharpInstance
+  webp(options?: { quality?: number }): SharpInstance
+  avif(options?: { quality?: number }): SharpInstance
+  jpeg(options?: { quality?: number }): SharpInstance
+  png(options?: { quality?: number }): SharpInstance
+  toBuffer(): Promise<Buffer>
+  blur(sigma: number): SharpInstance
+  toFormat(format: string, options?: { quality?: number }): SharpInstance
+}
+declare type SharpModule = {
+  (input: Buffer | string): SharpInstance
+  default?: (input: Buffer | string) => SharpInstance
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+export declare class ImageProcessingError extends Error {
+  code: string;
+  constructor(message: string, code: string);
+}

package/dist/image-optimization/processor.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { generatePlaceholder as tsGeneratePlaceholder, processImage as tsProcessImage } from "ts-images";
+export const DEFAULT_WIDTHS = [320, 640, 768, 1024, 1280, 1536, 1920], DEFAULT_FORMATS = ["webp", "jpeg"], DEFAULT_QUALITY = 80;
+const IMAGE_EXTENSIONS = [".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif", ".svg"], MIME_TYPES = {
+  webp: "image/webp",
+  avif: "image/avif",
+  jpeg: "image/jpeg",
+  png: "image/png"
+};
+let sharp = null, sharpLoadAttempted = !1;
+async function loadSharp() {
+  if (sharpLoadAttempted)
+    return sharp;
+  sharpLoadAttempted = !0;
+  try {
+    const sharpModule = await import("sharp");
+    sharp = sharpModule.default || sharpModule;
+    return sharp;
+  } catch {
+    return null;
+  }
+}
+export async function isSharpAvailable() {
+  return await loadSharp() !== null;
+}
+export async function isImageBackendAvailable() {
+  return !0;
+}
+export async function processImage(input, options = {}) {
+  const {
+    widths = DEFAULT_WIDTHS,
+    formats = DEFAULT_FORMATS,
+    quality = DEFAULT_QUALITY,
+    fit = "cover",
+    placeholder = "none",
+    outputDir = ".stx/images",
+    baseUrl = "/images"
+  } = options;
+  let buffer, srcPath;
+  if (typeof input === "string") {
+    srcPath = input;
+    if (!await Bun.file(input).exists())
+      throw new ImageProcessingError(`Image not found: ${input}`, "NOT_FOUND");
+    buffer = await Bun.file(input).arrayBuffer().then((ab) => Buffer.from(ab));
+  } else {
+    srcPath = "buffer-input";
+    buffer = input;
+  }
+  const hash = crypto.createHash("sha256").update(buffer).digest("hex").slice(0, 12), metadata = await getImageMetadata(buffer), { width: originalWidth, height: originalHeight } = metadata, aspectRatio = originalWidth / originalHeight;
+  await fs.promises.mkdir(outputDir, { recursive: !0 });
+  const variants = [], baseName = path.basename(srcPath, path.extname(srcPath)), validWidths = widths.filter((w) => w <= originalWidth);
+  if (!validWidths.includes(originalWidth) && originalWidth <= Math.max(...widths))
+    validWidths.push(originalWidth);
+  validWidths.sort((a, b) => a - b);
+  for (const targetWidth of validWidths) {
+    const targetHeight = Math.round(targetWidth / aspectRatio);
+    for (const format of formats) {
+      const fileName = `${baseName}-${targetWidth}w-${hash}.${format}`, outputPath = path.join(outputDir, fileName), urlPath = `${baseUrl}/${fileName}`, processedBuffer = await resizeAndConvert(buffer, {
+        width: targetWidth,
+        height: targetHeight,
+        format,
+        quality,
+        fit
+      });
+      await Bun.write(outputPath, processedBuffer);
+      variants.push({
+        path: outputPath,
+        url: urlPath,
+        width: targetWidth,
+        height: targetHeight,
+        format,
+        size: processedBuffer.length
+      });
+    }
+  }
+  let placeholderData;
+  if (placeholder !== "none")
+    placeholderData = await generatePlaceholder(buffer, placeholder);
+  return {
+    src: srcPath,
+    variants,
+    placeholder: placeholderData,
+    width: originalWidth,
+    height: originalHeight,
+    aspectRatio,
+    hash
+  };
+}
+export async function getImageMetadata(input) {
+  const buffer = typeof input === "string" ? Buffer.from(await Bun.file(input).arrayBuffer()) : input, s = await loadSharp();
+  if (s) {
+    const meta = await s(buffer).metadata();
+    return {
+      width: meta.width || 0,
+      height: meta.height || 0,
+      format: meta.format || "unknown",
+      hasAlpha: meta.hasAlpha
+    };
+  }
+  return parseImageHeaders(buffer);
+}
+function parseImageHeaders(buffer) {
+  if (buffer[0] === 137 && buffer[1] === 80 && buffer[2] === 78 && buffer[3] === 71) {
+    const width = buffer.readUInt32BE(16), height = buffer.readUInt32BE(20);
+    return { width, height, format: "png", hasAlpha: !0 };
+  }
+  if (buffer[0] === 255 && buffer[1] === 216) {
+    let offset = 2;
+    while (offset < buffer.length) {
+      if (buffer[offset] !== 255)
+        break;
+      const marker = buffer[offset + 1];
+      if (marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204) {
+        const height = buffer.readUInt16BE(offset + 5);
+        return { width: buffer.readUInt16BE(offset + 7), height, format: "jpeg", hasAlpha: !1 };
+      }
+      const length = buffer.readUInt16BE(offset + 2);
+      offset += 2 + length;
+    }
+  }
+  if (buffer.toString("utf8", 0, 4) === "RIFF" && buffer.toString("utf8", 8, 12) === "WEBP") {
+    const chunk = buffer.toString("utf8", 12, 16);
+    if (chunk === "VP8 ") {
+      const width = buffer.readUInt16LE(26) & 16383, height = buffer.readUInt16LE(28) & 16383;
+      return { width, height, format: "webp", hasAlpha: !1 };
+    }
+    if (chunk === "VP8L") {
+      const bits = buffer.readUInt32LE(21), width = (bits & 16383) + 1, height = (bits >> 14 & 16383) + 1;
+      return { width, height, format: "webp", hasAlpha: !0 };
+    }
+  }
+  if (buffer.toString("utf8", 0, 3) === "GIF") {
+    const width = buffer.readUInt16LE(6), height = buffer.readUInt16LE(8);
+    return { width, height, format: "gif", hasAlpha: !0 };
+  }
+  throw new ImageProcessingError("Unable to parse image dimensions", "PARSE_ERROR");
+}
+export async function resizeAndConvert(buffer, options) {
+  const s = await loadSharp();
+  if (s) {
+    let instance = s(buffer).resize(options.width, options.height, { fit: options.fit });
+    switch (options.format) {
+      case "webp":
+        instance = instance.webp({ quality: options.quality });
+        break;
+      case "avif":
+        instance = instance.avif({ quality: options.quality });
+        break;
+      case "jpeg":
+        instance = instance.jpeg({ quality: options.quality });
+        break;
+      case "png":
+        instance = instance.png({ quality: options.quality });
+        break;
+    }
+    return instance.toBuffer();
+  }
+  const tempOut = path.join(os.tmpdir(), `stx-img-${crypto.randomBytes(8).toString("hex")}.${options.format}`);
+  try {
+    await tsProcessImage({
+      input: buffer,
+      output: tempOut,
+      format: options.format,
+      quality: options.quality,
+      resize: {
+        width: options.width,
+        height: options.height,
+        fit: options.fit
+      }
+    });
+    return Buffer.from(await Bun.file(tempOut).arrayBuffer());
+  } finally {
+    await fs.promises.unlink(tempOut).catch(() => {});
+  }
+}
+async function generatePlaceholder(buffer, type) {
+  const s = await loadSharp();
+  if (type === "blur" && s) {
+    const base64 = (await s(buffer).resize(20).blur(10).toBuffer()).toString("base64"), meta = await getImageMetadata(buffer);
+    return `data:${MIME_TYPES[meta.format] || "image/jpeg"};base64,${base64}`;
+  }
+  if (type === "dominant-color" && s) {
+    const { dominant } = await s(buffer).resize(1, 1).toBuffer().then(async (b) => {
+      const meta = await s(b).metadata();
+      return { dominant: { r: 128, g: 128, b: 128 } };
+    }).catch(() => ({ dominant: { r: 128, g: 128, b: 128 } }));
+    return `rgb(${dominant.r}, ${dominant.g}, ${dominant.b})`;
+  }
+  const meta = await getImageMetadata(buffer), tempIn = path.join(os.tmpdir(), `stx-ph-${crypto.randomBytes(8).toString("hex")}.${meta.format === "unknown" ? "bin" : meta.format}`);
+  try {
+    await Bun.write(tempIn, buffer);
+    const tsStrategy = type === "blur" ? "blur" : type === "thumbhash" ? "thumbhash" : "dominant-color", ph = await tsGeneratePlaceholder(tempIn, {
+      strategy: tsStrategy,
+      width: tsStrategy === "thumbhash" ? void 0 : 32
+    });
+    if (type === "dominant-color" && ph.dominantColor)
+      return ph.dominantColor;
+    if (ph.dataURL)
+      return ph.dataURL;
+    return "rgb(128, 128, 128)";
+  } catch {
+    return "rgb(128, 128, 128)";
+  } finally {
+    await fs.promises.unlink(tempIn).catch(() => {});
+  }
+}
+export function generateSrcSet(variants, format) {
+  return (format ? variants.filter((v) => v.format === format) : variants).sort((a, b) => a.width - b.width).map((v) => `${v.url} ${v.width}w`).join(", ");
+}
+export function generateSizes(breakpoints) {
+  if (!breakpoints || Object.keys(breakpoints).length === 0)
+    return "100vw";
+  return Object.entries(breakpoints).sort((a, b) => {
+    const aVal = Number.parseInt(a[0].replace(/\D/g, "")) || 0;
+    return (Number.parseInt(b[0].replace(/\D/g, "")) || 0) - aVal;
+  }).map(([bp, size]) => `(max-width: ${bp}) ${size}`).join(", ") + ", 100vw";
+}
+export function getFallbackVariant(variants) {
+  const jpegs = variants.filter((v) => v.format === "jpeg");
+  if (jpegs.length === 0)
+    return variants[Math.floor(variants.length / 2)];
+  const sorted = jpegs.sort((a, b) => a.width - b.width);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+export function groupVariantsByFormat(variants) {
+  const grouped = new Map;
+  for (const variant of variants) {
+    const existing = grouped.get(variant.format) || [];
+    existing.push(variant);
+    grouped.set(variant.format, existing);
+  }
+  return grouped;
+}
+export function isImageFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return IMAGE_EXTENSIONS.includes(ext);
+}
+export function getMimeType(format) {
+  return MIME_TYPES[format] || "application/octet-stream";
+}
+export function getTotalSize(variants) {
+  return variants.reduce((sum, v) => sum + v.size, 0);
+}
+export function formatSize(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1048576)
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1048576).toFixed(2)} MB`;
+}
+
+export class ImageProcessingError extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "ImageProcessingError";
+    this.code = code;
+  }
+}

package/dist/image-optimization/serve.d.ts

@@ -0,0 +1,54 @@
+import { type ImageFormat } from './processor';
+/**
+ * Probe the request URL and return a Response if it matches the image
+ * route, or `null` if the caller should keep trying other handlers.
+ *
+ * Designed to be a drop-in inside any Bun/fetch-style server:
+ *
+ *   const imgResponse = await handleImageRequest(request, { publicDir })
+ *   if (imgResponse) return imgResponse
+ *   // …other routes
+ */
+export declare function handleImageRequest(request: Request, options: ImageServeOptions): Promise<Response | null>;
+/**
+ * Wrap {@link handleImageRequest} into a self-contained route handler.
+ *
+ * Most router slots type their handlers as `(req: Request) => Promise<Response>`
+ * — they don't accept `null` inside the Promise the way the chainable
+ * `handleImageRequest` returns it. Use this factory when plugging into a
+ * router slot of that shape:
+ *
+ *   const handler = createImageHandler({ publicDir: 'public' })
+ *   router.get('/_stx/img', handler)
+ *
+ * When the request URL doesn't match the configured route path, the
+ * returned handler responds with `404 Not Found`. Use the lower-level
+ * `handleImageRequest` directly if you want to chain to a fallback.
+ */
+export declare function createImageHandler(options: ImageServeOptions): (request: Request) => Promise<Response>;
+// ============================================================================
+// Public types
+// ============================================================================
+export declare interface ImageServeOptions {
+  publicDir: string
+  cacheDir?: string
+  maxWidth?: number
+  maxHeight?: number
+  defaultQuality?: number
+  defaultFit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+  routePath?: string
+}
+// ============================================================================
+// Parsing & validation
+// ============================================================================
+declare type ParseResult = | {
+    ok: true
+    srcFsPath: string
+    srcUrl: string
+    width: number
+    height: number
+    format: ImageFormat
+    quality: number
+    fit: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+  }
+  | { ok: false, error: string, status: number }

package/dist/image-optimization/serve.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { getMimeType } from "./processor.js";
+const VALID_FORMATS = new Set(["webp", "avif", "jpeg", "png"]), VALID_FITS = new Set(["cover", "contain", "fill", "inside", "outside"]), SOURCE_EXTS = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"]), DEFAULT_MAX_DIMENSION = 4096, DEFAULT_QUALITY = 80, DEFAULT_FIT = "cover";
+export async function handleImageRequest(request, options) {
+  const routePath = options.routePath ?? "/_stx/img", url = new URL(request.url);
+  if (url.pathname !== routePath)
+    return null;
+  const parsed = parseRequest(url, options);
+  if (!parsed.ok)
+    return new Response(parsed.error, { status: parsed.status, headers: { "Content-Type": "text/plain" } });
+  const { srcFsPath, srcUrl, width, height, format, quality, fit } = parsed;
+  let srcStat;
+  try {
+    srcStat = fs.statSync(srcFsPath);
+  } catch {
+    return new Response(`Source image not found: ${srcUrl}`, {
+      status: 404,
+      headers: { "Content-Type": "text/plain" }
+    });
+  }
+  if (!srcStat.isFile())
+    return new Response("Not a file", { status: 404, headers: { "Content-Type": "text/plain" } });
+  const cacheDir = options.cacheDir ?? ".stx/cache/img";
+  await fs.promises.mkdir(cacheDir, { recursive: !0 });
+  const fingerprint = `${srcFsPath}:${srcStat.mtimeMs}:${srcStat.size}`, paramKey = `${width}x${height}:${format}:${quality}:${fit}`, cacheKey = crypto.createHash("sha256").update(`${fingerprint}|${paramKey}`).digest("hex").slice(0, 16), cachePath = path.join(cacheDir, `${cacheKey}.${format}`), headers = {
+    "Content-Type": getMimeType(format),
+    "Cache-Control": "public, max-age=31536000, immutable",
+    ETag: `"${cacheKey}"`,
+    "X-Stx-Image-Cache": "HIT"
+  };
+  if (request.headers.get("if-none-match") === `"${cacheKey}"`)
+    return new Response(null, { status: 304, headers });
+  const cached = Bun.file(cachePath);
+  if (await cached.exists())
+    return new Response(cached, { headers });
+  try {
+    const sourceBuffer = Buffer.from(await Bun.file(srcFsPath).arrayBuffer()), { resizeAndConvert } = await loadResize(), outputBuffer = await resizeAndConvert(sourceBuffer, { width, height, format, quality, fit });
+    await Bun.write(cachePath, outputBuffer);
+    headers["X-Stx-Image-Cache"] = "MISS";
+    return new Response(new Uint8Array(outputBuffer), { headers });
+  } catch (err) {
+    const msg = err.message;
+    return new Response(`Image processing failed: ${msg}`, {
+      status: 500,
+      headers: { "Content-Type": "text/plain" }
+    });
+  }
+}
+export function createImageHandler(options) {
+  return async (request) => {
+    return await handleImageRequest(request, options) ?? new Response("Not Found", {
+      status: 404,
+      headers: { "Content-Type": "text/plain" }
+    });
+  };
+}
+function parseRequest(url, options) {
+  const srcUrl = url.searchParams.get("src");
+  if (!srcUrl)
+    return { ok: !1, error: "Missing required param: src", status: 400 };
+  if (!srcUrl.startsWith("/"))
+    return { ok: !1, error: "src must be an absolute URL path (start with /)", status: 400 };
+  if (srcUrl.startsWith("//"))
+    return { ok: !1, error: "src must be a local path", status: 400 };
+  const srcExt = path.extname(srcUrl).toLowerCase();
+  if (!SOURCE_EXTS.has(srcExt))
+    return { ok: !1, error: `Unsupported source extension: ${srcExt}`, status: 400 };
+  const publicDir = path.resolve(options.publicDir), candidate = path.resolve(publicDir, srcUrl.slice(1));
+  if (!candidate.startsWith(`${publicDir}${path.sep}`) && candidate !== publicDir)
+    return { ok: !1, error: "src is outside publicDir", status: 400 };
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_DIMENSION, maxHeight = options.maxHeight ?? DEFAULT_MAX_DIMENSION, widthParam = url.searchParams.get("w"), heightParam = url.searchParams.get("h"), width = widthParam ? Number.parseInt(widthParam, 10) : 0, height = heightParam ? Number.parseInt(heightParam, 10) : 0;
+  if (widthParam && (!Number.isFinite(width) || width <= 0))
+    return { ok: !1, error: "Invalid w (must be positive integer)", status: 400 };
+  if (heightParam && (!Number.isFinite(height) || height <= 0))
+    return { ok: !1, error: "Invalid h (must be positive integer)", status: 400 };
+  if (!widthParam && !heightParam)
+    return { ok: !1, error: "At least one of w or h is required", status: 400 };
+  const clampedWidth = Math.min(width || maxWidth, maxWidth), clampedHeight = Math.min(height || maxHeight, maxHeight), formatParam = url.searchParams.get("f") || "webp";
+  if (!VALID_FORMATS.has(formatParam))
+    return { ok: !1, error: `Invalid f (must be one of: ${[...VALID_FORMATS].join(", ")})`, status: 400 };
+  const format = formatParam, qualityParam = url.searchParams.get("q"), quality = qualityParam ? Number.parseInt(qualityParam, 10) : options.defaultQuality ?? DEFAULT_QUALITY;
+  if (!Number.isFinite(quality) || quality < 1 || quality > 100)
+    return { ok: !1, error: "Invalid q (must be 1-100)", status: 400 };
+  const fitParam = url.searchParams.get("fit") || options.defaultFit || DEFAULT_FIT;
+  if (!VALID_FITS.has(fitParam))
+    return { ok: !1, error: `Invalid fit (must be one of: ${[...VALID_FITS].join(", ")})`, status: 400 };
+  return {
+    ok: !0,
+    srcFsPath: candidate,
+    srcUrl,
+    width: clampedWidth,
+    height: clampedHeight,
+    format,
+    quality,
+    fit: fitParam
+  };
+}
+async function loadResize() {
+  return await import("./processor.js");
+}

package/dist/import-rebase.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Absolutise the relative import specifiers in `code`, as written in
+ * `sourceFile`.
+ *
+ * The path is emitted with forward slashes on every platform: it goes into
+ * JavaScript source, where a Windows backslash would be an escape character.
+ */
+export declare function absolutizeRelativeImports(code: string, sourceFile: string): string;
+/**
+ * The same, applied only inside `<script>` blocks of a template.
+ *
+ * A template is markup as well as code, and a string like `'../foo'` in an
+ * attribute or in prose is not an import. Scoping to script blocks keeps the
+ * rewrite to the only place an import specifier can appear.
+ */
+export declare function absolutizeTemplateImports(template: string, sourceFile: string): string;

package/dist/import-rebase.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+const SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])(\.\.?\/[^'"]*)\2/g, SCRIPT_BLOCK = /(<script\b[^>]*>)([\s\S]*?)(<\/script>)/gi;
+export function absolutizeRelativeImports(code, sourceFile) {
+  if (!sourceFile || !code.includes("/"))
+    return code;
+  const dir = path.dirname(sourceFile);
+  return code.replace(SPECIFIER, (match, lead, quote, request) => {
+    const resolved = path.resolve(dir, request);
+    return `${lead}${quote}${resolved.split(path.sep).join("/")}${quote}`;
+  });
+}
+export function absolutizeTemplateImports(template, sourceFile) {
+  if (!sourceFile || !template.includes("<script"))
+    return template;
+  return template.replace(SCRIPT_BLOCK, (_match, open, body, close) => `${open}${absolutizeRelativeImports(body, sourceFile)}${close}`);
+}

package/dist/imported-signals.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Does a client script reach signal APIs through a module it imports?
+ *
+ * Every signal decision in the pipeline is a syntactic scan for `state(`,
+ * `derived(`, `effect(` and friends in the script's own text. That is exact
+ * for a script that declares its own signals and blind to one that factors
+ * them out:
+ *
+ * ```stx
+ * <script client>
+ *   import { makeProbe } from '../functions/probe-factory'
+ *   const { signal } = makeProbe()   // <- names no signal API
+ * </script>
+ * ```
+ *
+ * With no match, the page is treated as static: `{{ signal() }}` is evaluated
+ * server-side (undefined, so empty), no setup function is generated, and
+ * `<body>` gets no `data-stx` for the runtime to invoke. Nothing logs. The
+ * page renders its static half and every binding is inert, which reads as a
+ * data problem rather than a hydration one. stacksjs/stacks#2394.
+ *
+ * The bundler resolves this authoritatively, but it is async and expensive,
+ * and the gate that decides whether to preserve `{{ }}` for the client is
+ * synchronous and runs once per template, partial and component. So this walks
+ * the same edges the bundler would, cheaply: read the imported file, look for
+ * the same API calls, recurse a bounded distance.
+ *
+ * Deliberately a subset of what bundling sees - relative specifiers only, a
+ * few levels deep. Anything it misses is caught later by the async
+ * bundle-and-retest in signal-processing.ts, which can only ever be MORE
+ * permissive. The reverse (a gate that says signals where the setup pass finds
+ * none) would leave a literal mustache on the page, so the two must lean this
+ * way round.
+ *
+ * @module imported-signals
+ */
+/**
+ * Whether `script` declares signals somewhere in the modules it imports.
+ *
+ * `fromFile` is the file the script lives in; without it nothing can be
+ * resolved and this returns false, which is the pre-existing behaviour.
+ */
+export declare function importsSignalDeclarations(script: string, fromFile: string | undefined, depth?: number, seen?: Set<string>): boolean;

package/dist/imported-signals.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+const SIGNAL_API_CALL = /\b(?:state|derived|effect|ref|reactive|computed|watch|watchEffect)\s*(?:<[^<>()]*>)?\s*\(/, RELATIVE_IMPORT = /(?:^|\n)\s*(?:import|export)\s+(?:[^'"]*?\sfrom\s+)?['"](\.[^'"]*)['"]/g, EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", "/index.ts", "/index.js"], MAX_DEPTH = 3;
+function resolveImport(specifier, fromFile) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  for (const extension of EXTENSIONS) {
+    const candidate = base + extension;
+    try {
+      if (fs.statSync(candidate).isFile())
+        return candidate;
+    } catch {}
+  }
+  return null;
+}
+export function importsSignalDeclarations(script, fromFile, depth = 0, seen = new Set) {
+  if (!fromFile || depth >= MAX_DEPTH)
+    return !1;
+  for (const match of script.matchAll(RELATIVE_IMPORT)) {
+    const resolved = resolveImport(match[1], fromFile);
+    if (!resolved || seen.has(resolved))
+      continue;
+    seen.add(resolved);
+    let source;
+    try {
+      source = fs.readFileSync(resolved, "utf8");
+    } catch {
+      continue;
+    }
+    if (SIGNAL_API_CALL.test(source))
+      return !0;
+    if (importsSignalDeclarations(source, resolved, depth + 1, seen))
+      return !0;
+  }
+  return !1;
+}