@jxsuite/compiler 0.35.0 → 1.1.0

package/src/site/format-host.ts

@@ -1,19 +1,21 @@
 /**
  * Format-host — node-side FormatHostIO and project registry construction
  *
- * Provides the filesystem/module I/O the shared format registry needs to run inside the compiler
- * (and dev server). Format classes are auto-discovered from the project-level imports map; see
- * specs/extensions.md.
+ * Provides the filesystem/module I/O the shared extension registry needs to run inside the compiler
+ * (and dev server). Extensions are declared explicitly in project.json's `extensions` array and
+ * discovered through their jx-extension.json manifests; see specs/extensions.md.
  */
 
 import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { buildFormatRegistry } from "@jxsuite/schema/format-registry";
-import type { FormatHostIO, FormatRegistry } from "@jxsuite/schema/format-registry";
+import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { FormatHostIO, FormatRegistry, ProjectBlock } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
+export type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registry";
 
 /**
@@ -73,23 +75,136 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   };
 }
 
-/** Build the format registry for a project from its project.json imports map. */
-export async function buildProjectFormatRegistry(
+/** Build the extension registry for a project from its project.json `extensions` array. */
+export async function buildProjectExtensionRegistry(
   projectRoot: string,
   projectConfig?: ProjectConfig,
-): Promise<FormatRegistry> {
-  return buildFormatRegistry(
-    projectConfig?.imports as Record<string, string> | undefined,
+): Promise<ExtensionRegistry> {
+  return buildExtensionRegistry(
+    projectConfig?.extensions,
     createNodeFormatIO(projectRoot),
     resolve(projectRoot, "project.json"),
   );
 }
 
+/**
+ * Format-dispatch view of the project's extension registry.
+ *
+ * @deprecated Part-3 cleanup: the desktop app still imports this; use
+ *   `buildProjectExtensionRegistry(...).then((r) => r.formats)` instead.
+ */
+export async function buildProjectFormatRegistry(
+  projectRoot: string,
+  projectConfig?: ProjectConfig,
+): Promise<FormatRegistry> {
+  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
+  return registry.formats;
+}
+
+// ─── Studio extensions payload ────────────────────────────────────────────────
+
+/** One project-section contribution on the studio wire (specs/extensions.md §9/§9.1). */
+export interface ExtensionsPayloadContribution {
+  /** The $prototype-visible class name declaring the `project` block. */
+  className: string;
+  /** The class descriptor's `project` admission block. */
+  project: ProjectBlock;
+  /** The class descriptor's `$studio` block (settings section vocabulary), when declared. */
+  studio: Record<string, unknown> | null;
+  /**
+   * The section's value schema — `properties[<key>]` of the extension's project fragment — or null
+   * when the extension ships no project fragment (or it lacks the key).
+   */
+  entrySchema: Record<string, unknown> | null;
+}
+
+/** One extension package on the studio wire (the formats route's `extensions` sibling array). */
+export interface ExtensionsPayloadEntry {
+  specifier: string;
+  name: string;
+  title?: string;
+  description?: string;
+  contributions: ExtensionsPayloadContribution[];
+  /**
+   * Every manifest class of the extension with its resolved descriptor path, in declaration order
+   * (additive; lets the studio address a class by `$src` without hardcoding its package layout).
+   * Plain state classes (no admission blocks — `$prototype` targets like TableQuery or Session)
+   * carry `state: true` plus their `$studio.stateDefaults` hint (specs/extensions.md §10), so the
+   * studio can offer them in its add-state picker and seed new defs (e.g. `timing: "client"`).
+   */
+  classes: {
+    name: string;
+    path: string;
+    state?: boolean;
+    stateDefaults?: Record<string, unknown>;
+  }[];
+}
+
+/**
+ * Build the studio-facing extensions payload from a project's extension registry: per extension,
+ * its manifest identity plus every project-section contribution paired with the entry schema read
+ * from the extension's shipped project fragment. Unreadable fragments degrade to a null entrySchema
+ * (the studio renders the section without field metadata).
+ *
+ * @param {ExtensionRegistry} registry
+ * @returns {ExtensionsPayloadEntry[]}
+ */
+export function buildExtensionsPayload(registry: ExtensionRegistry): ExtensionsPayloadEntry[] {
+  const payload: ExtensionsPayloadEntry[] = [];
+  for (const ext of registry.extensions) {
+    let fragmentProperties: Record<string, Record<string, unknown>> = {};
+    if (ext.schemas.project) {
+      try {
+        const fragment = JSON.parse(readFileSync(ext.schemas.project, "utf8")) as {
+          properties?: Record<string, Record<string, unknown>>;
+        };
+        fragmentProperties = fragment.properties ?? {};
+      } catch {
+        fragmentProperties = {};
+      }
+    }
+    const contributions: ExtensionsPayloadContribution[] = [];
+    for (const cls of ext.classes) {
+      if (!cls.project) {
+        continue;
+      }
+      contributions.push({
+        className: cls.name,
+        entrySchema: fragmentProperties[cls.project.key] ?? null,
+        project: cls.project,
+        studio: cls.studio,
+      });
+    }
+    payload.push({
+      classes: ext.classes.map((cls) => {
+        const stateDefaults = cls.studio?.stateDefaults as Record<string, unknown> | undefined;
+        const isState =
+          cls.project === null &&
+          cls.server === null &&
+          cls.connector === null &&
+          cls.extensions.length === 0;
+        return {
+          name: cls.name,
+          path: cls.classPath,
+          ...(isState ? { state: true } : {}),
+          ...(stateDefaults && typeof stateDefaults === "object" ? { stateDefaults } : {}),
+        };
+      }),
+      contributions,
+      name: ext.manifest.name,
+      specifier: ext.specifier,
+      ...(ext.manifest.title === undefined ? {} : { title: ext.manifest.title }),
+      ...(ext.manifest.description === undefined ? {} : { description: ext.manifest.description }),
+    });
+  }
+  return payload;
+}
+
 /** Error message for an unregistered non-JSON extension, naming the fix. */
 export function unknownFormatError(path: string, ext: string): Error {
   return new Error(
-    `No format class imported for "${ext}" (${path}). ` +
-      `Add a format class to project.json imports, e.g. ` +
-      `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+    `No format class registered for "${ext}" (${path}). ` +
+      `Enable an extension providing this format in project.json "extensions", ` +
+      `e.g. "@jxsuite/parser".`,
   );
 }

package/src/site/head-merger.ts

@@ -63,6 +63,19 @@ export function mergeHead(
       attributes: { href: canonical, rel: "canonical" },
       tagName: "link",
     });
+    // Auto OpenGraph identity (site-architecture §8.4) — author-supplied values win.
+    if (!merged.has("meta:og:url")) {
+      merged.set("meta:og:url", {
+        attributes: { content: canonical, property: "og:url" },
+        tagName: "meta",
+      });
+    }
+  }
+  if (context.siteName && !merged.has("meta:og:site_name")) {
+    merged.set("meta:og:site_name", {
+      attributes: { content: context.siteName, property: "og:site_name" },
+      tagName: "meta",
+    });
   }
 
   return [...merged.values()];

package/src/site/image-cache.ts

@@ -6,7 +6,7 @@
  * CI environments (e.g. Cloudflare Pages) can persist it via their npm cache layer.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { execSync } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -23,6 +23,7 @@ interface CacheEntry {
 export interface CacheManifest {
   version: number; // Cache format version
   entries: Record<string, CacheEntry>; // Cached entries keyed by content+config hash
+  touched?: Set<string>; // Keys resolved during this build — runtime only, never serialized
 }
 
 // ─── Cache directory resolution ──────────────────────────────────────────────
@@ -97,25 +98,73 @@ export function cacheKey(srcPath: string, config: ImageConfig) {
 export function loadCache(projectRoot: string): CacheManifest {
   const manifestPath = resolve(getImageCacheDir(projectRoot), "manifest.json");
   if (!existsSync(manifestPath)) {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
   try {
-    return JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    parsed.touched = new Set();
+    return parsed;
   } catch {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
 }
 
 /**
  * Save the cache manifest to disk.
  *
+ * With `prune: true`, entries whose key was never touched during this build (deleted/replaced
+ * sources, superseded configs) are dropped and their variant files deleted first, so a persisted
+ * cache — and the dist copy made from it — stays bounded to images the build actually uses.
+ *
  * @param {string} projectRoot
  * @param {CacheManifest} cache
+ * @param {{ prune?: boolean }} [options]
  */
-export function saveCache(projectRoot: string, cache: CacheManifest) {
+export function saveCache(
+  projectRoot: string,
+  cache: CacheManifest,
+  options: { prune?: boolean } = {},
+) {
+  if (options.prune && cache.touched) {
+    pruneStale(cache, cache.touched);
+  }
   const cacheDir = getImageCacheDir(projectRoot);
   mkdirSync(cacheDir, { recursive: true });
-  writeFileSync(resolve(cacheDir, "manifest.json"), JSON.stringify(cache, null, 2), "utf8");
+  writeFileSync(
+    resolve(cacheDir, "manifest.json"),
+    JSON.stringify({ entries: cache.entries, version: cache.version }, null, 2),
+    "utf8",
+  );
+}
+
+/**
+ * Remove entries (and their variant files) that were not touched during this build. A file shared
+ * with a surviving entry is kept — the same source under an older config produces overlapping
+ * width/format filenames, so deleting blindly would remove files a live entry still references.
+ *
+ * @param {CacheManifest} cache
+ * @param {Set<string>} touched
+ */
+function pruneStale(cache: CacheManifest, touched: Set<string>) {
+  const keep = new Set<string>();
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      for (const variant of entry.manifest.variants ?? []) {
+        keep.add(variant.absolutePath);
+      }
+    }
+  }
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      continue;
+    }
+    for (const variant of entry.manifest.variants ?? []) {
+      if (!keep.has(variant.absolutePath)) {
+        rmSync(variant.absolutePath, { force: true });
+      }
+    }
+    delete cache.entries[key];
+  }
 }
 
 // ─── Entry access ─────────────────────────────────────────────────────────────
@@ -128,6 +177,7 @@ export function saveCache(projectRoot: string, cache: CacheManifest) {
  * @returns {ImageManifest | null}
  */
 export function getCached(cache: CacheManifest, key: string) {
+  cache.touched?.add(key);
   const entry = cache.entries[key];
   if (!entry) {
     return null;
@@ -149,6 +199,7 @@ export function setCached(
   sourcePath: string,
   manifest: ImageManifest,
 ) {
+  cache.touched?.add(key);
   cache.entries[key] = {
     manifest,
     source: sourcePath,

package/src/site/image-transform.ts

@@ -318,6 +318,7 @@ async function transformImgNode(
   }
 
   let srcset;
+  let dims: { width: number; height: number } | null = null;
 
   if (remote) {
     // Original dimensions are unknown without fetching — emit every configured width and let
@@ -332,6 +333,7 @@ async function transformImgNode(
     if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc);
 
@@ -342,6 +344,10 @@ async function transformImgNode(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
   }
 
@@ -350,6 +356,12 @@ async function transformImgNode(
     node.attributes.sizes ??= config.sizes;
   }
 
+  // Intrinsic dimensions prevent layout shift; author-supplied values win.
+  if (dims && node.attributes.width === undefined && node.attributes.height === undefined) {
+    node.attributes.width = String(dims.width);
+    node.attributes.height = String(dims.height);
+  }
+
   if (config.lazyLoad && node.attributes.loading !== "eager") {
     node.attributes.loading = "lazy";
     node.attributes.decoding = "async";
@@ -412,12 +424,14 @@ async function transformInnerHtmlImages(
     }
 
     let srcset;
+    let dims: { width: number; height: number } | null = null;
 
     if (remote) {
       srcset = buildCloudflareSrcset(src, config, Infinity, null);
     } else if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc as string);
       if (!manifest) {
@@ -427,12 +441,19 @@ async function transformInnerHtmlImages(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
     if (!srcset) {
       continue;
     }
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
+    if (dims && !/\bwidth=/.test(attrs) && !/\bheight=/.test(attrs)) {
+      extra += ` width="${dims.width}" height="${dims.height}"`;
+    }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
       if (!/\bloading=/.test(attrs)) {
         extra += ` loading="lazy"`;

package/src/site/pages-discovery.ts

@@ -3,8 +3,7 @@
  *
  * Scans the pages/ directory and builds a route table mapping URL paths to their source files,
  * layouts, and metadata. `.json` pages are native; any other extension must be claimed by a format
- * class (with the `parse` capability and a "page" document kind) registered from the project's
- * imports map.
+ * class (with the `parse` capability and a "page" document kind) provided by an enabled extension.
  *
  * Conventions (per site-architecture spec §4): pages/index.json → / pages/about.json → /about
  * pages/about/index.json → /about pages/blog/[slug].json → /blog/:slug (dynamic)
@@ -15,9 +14,9 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { parseJxDocument } from "@jxsuite/schema/parse";
 import { extname, join, relative, resolve } from "node:path";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
-import type { JxDocument, JxPathsDef } from "@jxsuite/schema/types";
-import type { ContentLoaderEntry } from "@jxsuite/parser/types";
+import type { JxDocument, JxPathsDef, ProjectConfig } from "@jxsuite/schema/types";
 
 interface Route {
   urlPattern: string; // URL pattern (e.g. "/blog/:slug")
@@ -50,9 +49,9 @@ export async function readPageDocument(
   const entry = registry?.byExtension(ext, "parse");
   if (!entry) {
     throw new Error(
-      `No format class imported for "${ext}" (${filePath}). ` +
-        `Add a format class to project.json imports, e.g. ` +
-        `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+      `No format class registered for "${ext}" (${filePath}). ` +
+        `Enable an extension providing this format in project.json "extensions", ` +
+        `e.g. "@jxsuite/parser".`,
     );
   }
   return (await entry.call("parse", source)) as JxDocument;
@@ -208,23 +207,25 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
 /**
  * Expand dynamic routes by resolving $paths from each dynamic page.
  *
- * Supports three $paths shapes (per spec §4.3): 1. Content type-based: { contentType: "blog",
- * param: "slug", field: "id" } 2. Explicit values: { values: ["en", "fr"], param: "lang" } 3. Data
- * file ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 4. Legacy array: [{ slug:
- * "hello" }, { slug: "world" }]
+ * Supports these $paths shapes (per spec §4.3): 1. Explicit values: { values: ["en", "fr"], param:
+ * "lang" } 2. Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 3.
+ * Legacy array: [{ slug: "hello" }, { slug: "world" }] 4. Extension-discriminated: any object
+ * carrying a key an enabled extension registered as its `resolvePaths` discriminator (e.g. the
+ * parser's { contentType: "blog", param: "slug" }).
  *
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
- * @param {Map<string, ContentLoaderEntry[]>} [contentTypes] - Loaded content types (from
- *   content-loader)
- * @param {FormatRegistry} [registry] - Format registry for reading non-JSON dynamic pages
+ * @param {Record<string, unknown>} [sections] - Loaded project sections (projectData results)
+ * @param {ExtensionRegistry} [registry] - Extension registry (formats view reads non-JSON pages)
+ * @param {ProjectConfig} [projectConfig] - Already-loaded project config
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
 export async function expandDynamicRoutes(
   routes: Route[],
   projectRoot: string,
-  contentTypes = new Map<string, ContentLoaderEntry[]>(),
-  registry?: FormatRegistry,
+  sections: Record<string, unknown> = {},
+  registry?: ExtensionRegistry,
+  projectConfig?: ProjectConfig,
 ) {
   const expanded: Route[] = [];
 
@@ -238,7 +239,7 @@ export async function expandDynamicRoutes(
     /** @type {Record<string, unknown>} */
     let raw;
     try {
-      raw = await readPageDocument(route.sourcePath, registry);
+      raw = await readPageDocument(route.sourcePath, registry?.formats);
     } catch {
       expanded.push(route);
       continue;
@@ -249,7 +250,13 @@ export async function expandDynamicRoutes(
       continue;
     }
 
-    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, contentTypes);
+    const pathEntries = await resolvePathEntries(
+      raw.$paths,
+      projectRoot,
+      sections,
+      registry,
+      projectConfig,
+    );
 
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
@@ -277,67 +284,72 @@ export async function expandDynamicRoutes(
 /**
  * Resolve $paths into an array of param objects.
  *
+ * Core shapes (array / `values` / `$ref`) are handled inline; any other object dispatches through
+ * the extension registry — the first key with a registered `resolvePaths` discriminator routes the
+ * whole $paths value to the owning class, with its section's loaded data as context.
+ *
  * @param {import("@jxsuite/schema/types").JxPathsDef} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Map<string, ContentLoaderEntry[]>} contentTypes
- * @returns {Record<string, unknown>[]} Array of { paramName: value } objects
+ * @param {Record<string, unknown>} sections - Loaded project sections keyed by section key
+ * @param {ExtensionRegistry} [registry]
+ * @param {ProjectConfig} [projectConfig]
+ * @returns {Promise<Record<string, unknown>[]>} Array of { paramName: value } objects
  */
-function resolvePathEntries(
+async function resolvePathEntries(
   $paths: JxPathsDef,
   projectRoot: string,
-  contentTypes: Map<string, ContentLoaderEntry[]>,
-): Record<string, unknown>[] {
+  sections: Record<string, unknown>,
+  registry?: ExtensionRegistry,
+  projectConfig?: ProjectConfig,
+): Promise<Record<string, unknown>[]> {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
   }
 
-  // Content type-based: { contentType: "blog", param: "slug", field: "id" }
-  if ("contentType" in $paths && $paths.contentType) {
-    const entries = contentTypes.get($paths.contentType);
-    if (!entries || entries.length === 0) {
-      console.warn(
-        `Warning: $paths references content type "${$paths.contentType}" but it has no entries`,
-      );
-      return [];
-    }
-    const param = $paths.param ?? "slug";
-    const field = $paths.field ?? "id";
-    return entries
-      .map((entry: ContentLoaderEntry) => ({
-        [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
-      }))
-      .filter((p: Record<string, unknown>) => p[param]);
-  }
-
   // Explicit values: { values: ["en", "fr"], param: "lang" }
   if ("values" in $paths && Array.isArray($paths.values)) {
-    const param = $paths.param ?? "value";
-    return $paths.values.map((v) => ({ [param]: v }));
+    const param = typeof $paths.param === "string" ? $paths.param : "value";
+    return ($paths.values as unknown[]).map((v) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
-  if ("$ref" in $paths && $paths.$ref) {
-    const filePath = resolve(projectRoot, $paths.$ref);
+  if ("$ref" in $paths && typeof $paths.$ref === "string" && $paths.$ref) {
+    const refPath = $paths.$ref;
+    const filePath = resolve(projectRoot, refPath);
     let data: unknown;
     try {
       data = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
     } catch (error) {
       const err = error as Error;
-      console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
+      console.warn(`Warning: $paths.$ref could not load "${refPath}": ${err.message}`);
       return [];
     }
     if (!Array.isArray(data)) {
-      console.warn(`Warning: $paths.$ref "${$paths.$ref}" must be a JSON array`);
+      console.warn(`Warning: $paths.$ref "${refPath}" must be a JSON array`);
       return [];
     }
-    const param = $paths.param ?? "id";
-    const field = $paths.field ?? "id";
+    const param = typeof $paths.param === "string" ? $paths.param : "id";
+    const field = typeof $paths.field === "string" ? $paths.field : "id";
     return (data as Record<string, unknown>[]).map((item: Record<string, unknown>) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }
 
+  // Extension-discriminated: the first key with a registered resolvePaths discriminator routes
+  // The whole value to the owning class (specs/extensions.md §8).
+  for (const key of Object.keys($paths)) {
+    const entry = registry?.byPathsDiscriminator(key);
+    if (!entry?.project) {
+      continue;
+    }
+    return (await entry.call("resolvePaths", $paths, {
+      data: sections[entry.project.key],
+      projectConfig,
+      root: projectRoot,
+    })) as Record<string, unknown>[];
+  }
+
   console.warn(`Warning: unrecognized $paths shape — skipping`);
   return [];
 }

package/src/site/preview-server.ts

@@ -0,0 +1,93 @@
+/**
+ * Preview server — `jx preview` serves an already-built dist/ directory.
+ *
+ * Dependency-free node:http static server, so the Node-run `jx` bin needs neither Bun nor the
+ * dev-server package. Maps directory URLs to index.html (the build's trailingSlash output) and
+ * falls back to <dist>/404.html when present.
+ *
+ * @module preview-server
+ */
+
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+};
+
+/**
+ * Resolve a request pathname to a file inside distDir, or null. Directory URLs (with or without a
+ * trailing slash) map to their index.html; traversal outside distDir is rejected.
+ *
+ * @param {string} distDir - Absolute dist directory
+ * @param {string} pathname - Decoded URL pathname
+ * @returns {string | null} Absolute file path to serve, or null
+ */
+export function resolvePreviewFile(distDir: string, pathname: string): string | null {
+  const safe = normalize(pathname).replaceAll("\\", "/");
+  const candidate = resolve(distDir, `.${safe.startsWith("/") ? safe : `/${safe}`}`);
+  if (candidate !== distDir && !candidate.startsWith(distDir + sep)) {
+    return null;
+  }
+  if (existsSync(candidate)) {
+    if (statSync(candidate).isDirectory()) {
+      const index = join(candidate, "index.html");
+      return existsSync(index) ? index : null;
+    }
+    return candidate;
+  }
+  // Extensionless route without trailing slash → its directory index
+  const index = join(candidate, "index.html");
+  return existsSync(index) ? index : null;
+}
+
+/**
+ * Start the preview server on the given port (0 picks a free port).
+ *
+ * @param {string} distDir - Absolute path to the built dist directory
+ * @param {number} port - Port to listen on
+ * @returns {Server} The listening node:http server
+ */
+export function startPreviewServer(distDir: string, port: number): Server {
+  const dist = resolve(distDir);
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const filePath = resolvePreviewFile(dist, decodeURIComponent(url.pathname));
+
+    if (filePath) {
+      res.writeHead(200, {
+        "Content-Type": MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+      });
+      res.end(readFileSync(filePath));
+      return;
+    }
+
+    const notFound = join(dist, "404.html");
+    if (existsSync(notFound)) {
+      res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(readFileSync(notFound));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+  });
+  server.listen(port);
+  return server;
+}