@aerobuilt/core 0.3.1 → 0.3.3

package/dist/{build-script-analysis-Bd9EyItC.mjs → build-script-analysis-1t1wROdQ.mjs}

@@ -26,6 +26,67 @@ function isDirectiveAttr(attrName, config = defaultConfig) {
 	return prefixes.some((p) => attrName.startsWith(p));
 }
 
+//#endregion
+//#region src/compiler/constants.ts
+/**
+* Shared constants for the Aero compiler (parser, codegen, helpers).
+*
+* @remarks
+* Attribute names are used with optional `data-` prefix (e.g. `data-each`). Script taxonomy uses
+* `is:build`, `is:inline`, `is:blocking`; default scripts are treated as client (virtual module).
+* When changing script taxonomy (is:build, is:inline, etc.), update all consumers per
+* _reference/script-taxonomy-sync.md.
+*/
+/** Prefix for data attributes (e.g. `data-each` → ATTR_PREFIX + ATTR_EACH). */
+const ATTR_PREFIX = "data-";
+/** Attribute for spreading props onto a component: `data-props` or `data-props="{ ... }"`. */
+const ATTR_PROPS = "props";
+/** Attribute for iteration: `data-each="{ item in items }"`. */
+const ATTR_EACH = "each";
+const ATTR_IF = "if";
+const ATTR_ELSE_IF = "else-if";
+const ATTR_ELSE = "else";
+/** Slot name (on `<slot>` or content). */
+const ATTR_NAME = "name";
+const ATTR_SLOT = "slot";
+/** Script runs at build time; extracted and becomes render function body. */
+const ATTR_IS_BUILD = "is:build";
+/** Script left in template in place; not extracted. */
+const ATTR_IS_INLINE = "is:inline";
+/** Script hoisted to head; extracted. */
+const ATTR_IS_BLOCKING = "is:blocking";
+/** Script/style receives data from template: `pass:data="{ config }"` or `pass:data="{ ...theme }"`. */
+const ATTR_PASS_DATA = "pass:data";
+/** Script external source (HTML attribute). */
+const ATTR_SRC = "src";
+const TAG_SLOT = "slot";
+/** Default slot name when no name is given. */
+const SLOT_NAME_DEFAULT = "default";
+/** Matches `item in items` for data-each (captures: loop variable, iterable expression). */
+const EACH_REGEX = /^(\w+)\s+in\s+(.+)$/;
+/** Matches tag names ending with `-component` or `-layout`. */
+const COMPONENT_SUFFIX_REGEX = /-(component|layout)$/;
+/** Self-closing tag: `<tag ... />`. */
+const SELF_CLOSING_TAG_REGEX = /<([a-z0-9-]+)([^>]*?)\/>/gi;
+const SELF_CLOSING_TAIL_REGEX = /\/>$/;
+/** HTML void elements that have no closing tag. */
+const VOID_TAGS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+
 //#endregion
 //#region src/compiler/build-script-analysis.ts
 /**
@@ -128,6 +189,92 @@ function analyzeBuildScript(script) {
 	};
 }
 /**
+* Extract the props type name from a build script that uses `Aero.props as TypeName`
+* or `const { ... } = Aero.props as TypeName`.
+*
+* @param script - Raw build script content (JS or TS).
+* @returns The type name and whether it was from destructuring, or null if not found.
+*/
+function getPropsTypeFromBuildScript(script) {
+	if (!script.trim()) return null;
+	const result = parseSync(BUILD_SCRIPT_FILENAME, script, {
+		sourceType: "module",
+		range: true,
+		lang: "ts"
+	});
+	if (result.errors.length > 0) return null;
+	const body = result.program.body;
+	if (!body) return null;
+	for (const stmt of body) {
+		const found = findPropsTypeInNode(stmt);
+		if (found) return found;
+	}
+	return null;
+}
+function findPropsTypeInNode(node) {
+	if (!node || typeof node !== "object") return null;
+	const n = node;
+	if (n.type === "TSAsExpression") {
+		const expr = n.expression;
+		const typeAnnotation = n.typeAnnotation;
+		if (isAeroProps(expr)) {
+			const typeName = getTypeNameFromAnnotation(typeAnnotation);
+			if (typeName) return {
+				typeName,
+				isFromDestructuring: false
+			};
+		}
+		return null;
+	}
+	if (n.type === "VariableDeclaration") {
+		const declarations = n.declarations;
+		for (const decl of declarations ?? []) {
+			const d = decl;
+			const init = d.init;
+			const id = d.id;
+			const isDestructuring = id && typeof id === "object" && id.type === "ObjectPattern";
+			const found = findPropsTypeInNode(init);
+			if (found) return {
+				...found,
+				isFromDestructuring: !!isDestructuring
+			};
+		}
+		return null;
+	}
+	for (const key of [
+		"init",
+		"expression",
+		"argument",
+		"body",
+		"consequent",
+		"alternate"
+	]) {
+		const child = n[key];
+		if (Array.isArray(child)) for (const c of child) {
+			const found = findPropsTypeInNode(c);
+			if (found) return found;
+		}
+		else if (child) {
+			const found = findPropsTypeInNode(child);
+			if (found) return found;
+		}
+	}
+	return null;
+}
+function isAeroProps(expr) {
+	if (expr?.type !== "MemberExpression") return false;
+	const obj = expr.object;
+	const prop = expr.property;
+	const objName = obj?.type === "Identifier" ? obj.name : obj?.name;
+	const propName = prop?.type === "Identifier" ? prop.name : prop?.name;
+	return objName === "Aero" && propName === "props";
+}
+function getTypeNameFromAnnotation(annotation) {
+	if (!annotation) return null;
+	if (annotation.type === "TSTypeReference") return annotation.typeName?.name;
+	return null;
+}
+/**
 * Analyze build script for editor use: same as analyzeBuildScript but returns imports with
 * source ranges (full statement and per-binding) so the extension can map to vscode.Range.
 *
@@ -190,4 +337,4 @@ function analyzeBuildScriptForEditor(script) {
 }
 
 //#endregion
-export { compileInterpolationFromSegments as a, isDirectiveAttr as i, analyzeBuildScriptForEditor as n, tokenizeCurlyInterpolation as o, DEFAULT_DIRECTIVE_PREFIXES as r, analyzeBuildScript as t };
+export { VOID_TAGS as C, tokenizeCurlyInterpolation as D, compileInterpolationFromSegments as E, TAG_SLOT as S, isDirectiveAttr as T, COMPONENT_SUFFIX_REGEX as _, ATTR_ELSE as a, SELF_CLOSING_TAIL_REGEX as b, ATTR_IS_BLOCKING as c, ATTR_NAME as d, ATTR_PASS_DATA as f, ATTR_SRC as g, ATTR_SLOT as h, ATTR_EACH as i, ATTR_IS_BUILD as l, ATTR_PROPS as m, analyzeBuildScriptForEditor as n, ATTR_ELSE_IF as o, ATTR_PREFIX as p, getPropsTypeFromBuildScript as r, ATTR_IF as s, analyzeBuildScript as t, ATTR_IS_INLINE as u, EACH_REGEX as v, DEFAULT_DIRECTIVE_PREFIXES as w, SLOT_NAME_DEFAULT as x, SELF_CLOSING_TAG_REGEX as y };

package/dist/entry-editor.d.mts

@@ -3,8 +3,7 @@ import { InterpolationSegment, LiteralSegment, Segment, TokenizeOptions, compile
 //#region src/compiler/directive-attributes.d.ts
 /**
  * Classifier for directive attributes (Alpine.js, HTMX, Vue, etc.) that should
- * skip { } interpolation in the compiler. Replaces ALPINE_ATTR_REGEX with a
- * declarative list for clearer semantics and easier extension.
+ * skip { } interpolation in the compiler.
  *
  * @packageDocumentation
  */
@@ -30,6 +29,10 @@ declare const DEFAULT_DIRECTIVE_PREFIXES: string[];
  */
 declare function isDirectiveAttr(attrName: string, config?: DirectiveAttrConfig): boolean;
 //#endregion
+//#region src/compiler/constants.d.ts
+/** Matches tag names ending with `-component` or `-layout`. */
+declare const COMPONENT_SUFFIX_REGEX: RegExp;
+//#endregion
 //#region src/compiler/build-script-analysis.d.ts
 /**
  * AST-based analysis of Aero build scripts: extract imports and getStaticPaths export.
@@ -62,6 +65,19 @@ interface BuildScriptImportForEditor extends BuildScriptImport {
 interface BuildScriptAnalysisForEditorResult {
   imports: BuildScriptImportForEditor[];
 }
+/** Result of getPropsTypeFromBuildScript: the type name used in `Aero.props as TypeName`. */
+interface PropsTypeResult {
+  typeName: string;
+  isFromDestructuring: boolean;
+}
+/**
+ * Extract the props type name from a build script that uses `Aero.props as TypeName`
+ * or `const { ... } = Aero.props as TypeName`.
+ *
+ * @param script - Raw build script content (JS or TS).
+ * @returns The type name and whether it was from destructuring, or null if not found.
+ */
+declare function getPropsTypeFromBuildScript(script: string): PropsTypeResult | null;
 /**
  * Analyze build script for editor use: same as analyzeBuildScript but returns imports with
  * source ranges (full statement and per-binding) so the extension can map to vscode.Range.
@@ -71,4 +87,4 @@ interface BuildScriptAnalysisForEditorResult {
  */
 declare function analyzeBuildScriptForEditor(script: string): BuildScriptAnalysisForEditorResult;
 //#endregion
-export { type BuildScriptAnalysisForEditorResult, type BuildScriptImportForEditor, DEFAULT_DIRECTIVE_PREFIXES, type DirectiveAttrConfig, type InterpolationSegment, type LiteralSegment, type Segment, type TokenizeOptions, analyzeBuildScriptForEditor, compileInterpolationFromSegments, isDirectiveAttr, tokenizeCurlyInterpolation };
+export { type BuildScriptAnalysisForEditorResult, type BuildScriptImportForEditor, COMPONENT_SUFFIX_REGEX, DEFAULT_DIRECTIVE_PREFIXES, type DirectiveAttrConfig, type InterpolationSegment, type LiteralSegment, type PropsTypeResult, type Segment, type TokenizeOptions, analyzeBuildScriptForEditor, compileInterpolationFromSegments, getPropsTypeFromBuildScript, isDirectiveAttr, tokenizeCurlyInterpolation };

package/dist/entry-editor.mjs

@@ -1,3 +1,3 @@
-import { a as compileInterpolationFromSegments, i as isDirectiveAttr, n as analyzeBuildScriptForEditor, o as tokenizeCurlyInterpolation, r as DEFAULT_DIRECTIVE_PREFIXES } from "./build-script-analysis-Bd9EyItC.mjs";
+import { D as tokenizeCurlyInterpolation, E as compileInterpolationFromSegments, T as isDirectiveAttr, _ as COMPONENT_SUFFIX_REGEX, n as analyzeBuildScriptForEditor, r as getPropsTypeFromBuildScript, w as DEFAULT_DIRECTIVE_PREFIXES } from "./build-script-analysis-1t1wROdQ.mjs";
 
-export { DEFAULT_DIRECTIVE_PREFIXES, analyzeBuildScriptForEditor, compileInterpolationFromSegments, isDirectiveAttr, tokenizeCurlyInterpolation };
+export { COMPONENT_SUFFIX_REGEX, DEFAULT_DIRECTIVE_PREFIXES, analyzeBuildScriptForEditor, compileInterpolationFromSegments, getPropsTypeFromBuildScript, isDirectiveAttr, tokenizeCurlyInterpolation };

package/dist/vite/index.mjs

@@ -1,5 +1,5 @@
 import { a as isDynamicRoutePattern, i as expandRoutePattern, n as resolvePageName, o as toPosix, s as toPosixRelative, t as pagePathToKey } from "../routing-Bai79LCq.mjs";
-import { a as compileInterpolationFromSegments, i as isDirectiveAttr, o as tokenizeCurlyInterpolation, t as analyzeBuildScript } from "../build-script-analysis-Bd9EyItC.mjs";
+import { C as VOID_TAGS, D as tokenizeCurlyInterpolation, E as compileInterpolationFromSegments, S as TAG_SLOT, T as isDirectiveAttr, _ as COMPONENT_SUFFIX_REGEX, a as ATTR_ELSE, b as SELF_CLOSING_TAIL_REGEX, c as ATTR_IS_BLOCKING, d as ATTR_NAME, f as ATTR_PASS_DATA, g as ATTR_SRC, h as ATTR_SLOT, i as ATTR_EACH, l as ATTR_IS_BUILD, m as ATTR_PROPS, o as ATTR_ELSE_IF, p as ATTR_PREFIX, s as ATTR_IF, t as analyzeBuildScript, u as ATTR_IS_INLINE, v as EACH_REGEX, x as SLOT_NAME_DEFAULT, y as SELF_CLOSING_TAG_REGEX } from "../build-script-analysis-1t1wROdQ.mjs";
 import { loadTsconfigAliases, mergeWithDefaultAliases } from "../utils/aliases.mjs";
 import { redirectsToRouteRules } from "../utils/redirects.mjs";
 import { createRequire } from "node:module";
@@ -7,6 +7,7 @@ import { ViteImageOptimizer } from "vite-plugin-image-optimizer";
 import { nitro } from "nitro/vite";
 import { parseHTML } from "linkedom";
 import path from "path";
+import { transformSync } from "oxc-transform";
 import path$1 from "node:path";
 import { minify } from "html-minifier-next";
 import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -64,17 +65,18 @@ function extractKeyFromEntry(entry) {
 /** Virtual URL prefix for extracted client scripts (e.g. `/@aero/client/client/pages/home.js`). Root-relative; no filesystem path. */
 const CLIENT_SCRIPT_PREFIX = "/@aero/client/";
 /**
-* Virtual URL for one client script. Single script uses `.js`, multiple use `.0.js`, `.1.js`, etc.
+* Virtual URL for one client script.
+* Single script uses `.ts`, multiple use `.0.ts`, `.1.ts`, etc.
 * Use this in the Vite transform and static build so URL generation is consistent.
 */
 function getClientScriptVirtualUrl(baseName, index, total) {
-	const suffix = total === 1 ? ".js" : `.${index}.js`;
+	const suffix = total === 1 ? ".ts" : `.${index}.ts`;
 	return CLIENT_SCRIPT_PREFIX + baseName + suffix;
 }
 /** Virtual module ID requested by the app; resolved to `RESOLVED_*` so `load()` can re-export from the real runtime instance. */
-const RUNTIME_INSTANCE_MODULE_ID = "virtual:aero/runtime-instance";
+const RUNTIME_INSTANCE_MODULE_ID = "virtual:aero/runtime-instance.ts";
 /** Resolved ID (with `\0` prefix) so Vite treats it as an internal module. */
-const RESOLVED_RUNTIME_INSTANCE_MODULE_ID = "\0virtual:aero/runtime-instance";
+const RESOLVED_RUNTIME_INSTANCE_MODULE_ID = "\0virtual:aero/runtime-instance.ts";
 /** Prefix for virtual empty-CSS modules used when Vite requests .html?html-proxy&inline-css (Aero .html are JS, not HTML with styles). */
 const AERO_EMPTY_INLINE_CSS_PREFIX = "\0aero:empty-inline-css:";
 /** Prefix for virtual HTML template modules. Resolving .html to this id returns compiled JS so vite:build-html never sees raw/compiled HTML. */
@@ -117,65 +119,6 @@ function resolveDirs(dirs) {
 	};
 }
 
-//#endregion
-//#region src/compiler/constants.ts
-/**
-* Shared constants for the Aero compiler (parser, codegen, helpers).
-*
-* @remarks
-* Attribute names are used with optional `data-` prefix (e.g. `data-each`). Script taxonomy uses
-* `is:build`, `is:inline`, `is:blocking`; default scripts are treated as client (virtual module).
-*/
-/** Prefix for data attributes (e.g. `data-each` → ATTR_PREFIX + ATTR_EACH). */
-const ATTR_PREFIX = "data-";
-/** Attribute for spreading props onto a component: `data-props` or `data-props="{ ... }"`. */
-const ATTR_PROPS = "props";
-/** Attribute for iteration: `data-each="{ item in items }"`. */
-const ATTR_EACH = "each";
-const ATTR_IF = "if";
-const ATTR_ELSE_IF = "else-if";
-const ATTR_ELSE = "else";
-/** Slot name (on `<slot>` or content). */
-const ATTR_NAME = "name";
-const ATTR_SLOT = "slot";
-/** Script runs at build time; extracted and becomes render function body. */
-const ATTR_IS_BUILD = "is:build";
-/** Script left in template in place; not extracted. */
-const ATTR_IS_INLINE = "is:inline";
-/** Script hoisted to head; extracted. */
-const ATTR_IS_BLOCKING = "is:blocking";
-/** Script/style receives data from template: `pass:data="{ config }"` or `pass:data="{ ...theme }"`. */
-const ATTR_PASS_DATA = "pass:data";
-/** Script external source (HTML attribute). */
-const ATTR_SRC = "src";
-const TAG_SLOT = "slot";
-/** Default slot name when no name is given. */
-const SLOT_NAME_DEFAULT = "default";
-/** Matches `item in items` for data-each (captures: loop variable, iterable expression). */
-const EACH_REGEX = /^(\w+)\s+in\s+(.+)$/;
-/** Matches tag names ending with `-component` or `-layout`. */
-const COMPONENT_SUFFIX_REGEX = /-(component|layout)$/;
-/** Self-closing tag: `<tag ... />`. */
-const SELF_CLOSING_TAG_REGEX = /<([a-z0-9-]+)([^>]*?)\/>/gi;
-const SELF_CLOSING_TAIL_REGEX = /\/>$/;
-/** HTML void elements that have no closing tag. */
-const VOID_TAGS = new Set([
-	"area",
-	"base",
-	"br",
-	"col",
-	"embed",
-	"hr",
-	"img",
-	"input",
-	"link",
-	"meta",
-	"param",
-	"source",
-	"track",
-	"wbr"
-]);
-
 //#endregion
 //#region src/compiler/parser.ts
 /** Serialize element attributes to a string, excluding given names (case-insensitive). Values are XML-escaped. */
@@ -627,6 +570,11 @@ var Resolver = class {
 
 //#endregion
 //#region src/compiler/codegen.ts
+/** Strip TypeScript syntax from a script string, returning plain JavaScript. */
+function stripTypes(code, filename = "script.ts") {
+	if (!code.trim()) return code;
+	return transformSync(filename, code, { typescript: { onlyRemoveTypeImports: true } }).code.replace(/(?:^|\n)\s*export\s*\{\s*\}\s*;?/g, "");
+}
 /** Internal lowerer: walks DOM nodes and builds IR; used by compile(). */
 var Lowerer = class {
 	resolver;
@@ -1012,7 +960,7 @@ function compile(parsed, options) {
 	const lowerer = new Lowerer(resolver);
 	let script = parsed.buildScript ? parsed.buildScript.content : "";
 	const analysis = analyzeBuildScript(script);
-	script = analysis.scriptWithoutImportsAndGetStaticPaths;
+	script = stripTypes(analysis.scriptWithoutImportsAndGetStaticPaths);
 	const getStaticPathsFn = analysis.getStaticPathsFn;
 	const importsLines = [];
 	const quote = "\"";
@@ -1067,15 +1015,18 @@ function compile(parsed, options) {
 		} else if (isHead) headScripts.push(tagExpr);
 		else rootScripts.push(`scripts?.add(${tagExpr});`);
 	}
-	if (options.blockingScripts) for (const blockingScript of options.blockingScripts) if (blockingScript.passDataExpr) {
-		const jsMapExpr = `Object.entries(${validateSingleBracedExpression(blockingScript.passDataExpr, {
-			directive: "pass:data",
-			tagName: "script"
-		})}).map(([k, v]) => "\\nconst " + k + " = " + JSON.stringify(v) + ";").join("")`;
-		headScripts.push(`\`<script${blockingScript.attrs ? " " + blockingScript.attrs : ""}>\${${jsMapExpr}}${blockingScript.content.replace(/`/g, "\\`")}<\/script>\``);
-	} else {
-		const escapedContent = blockingScript.content.replace(/'/g, "\\'");
-		headScripts.push(`'<script${blockingScript.attrs ? " " + blockingScript.attrs : ""}>${escapedContent}<\/script>'`);
+	if (options.blockingScripts) for (const blockingScript of options.blockingScripts) {
+		const strippedContent = stripTypes(blockingScript.content, "blocking.ts");
+		if (blockingScript.passDataExpr) {
+			const jsMapExpr = `Object.entries(${validateSingleBracedExpression(blockingScript.passDataExpr, {
+				directive: "pass:data",
+				tagName: "script"
+			})}).map(([k, v]) => "\\nconst " + k + " = " + JSON.stringify(v) + ";").join("")`;
+			headScripts.push(`\`<script${blockingScript.attrs ? " " + blockingScript.attrs : ""}>\${${jsMapExpr}}${strippedContent.replace(/`/g, "\\`")}<\/script>\``);
+		} else {
+			const escapedContent = strippedContent.replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+			headScripts.push(`\`<script${blockingScript.attrs ? " " + blockingScript.attrs : ""}>${escapedContent}<\/script>\``);
+		}
 	}
 	const renderFn = emitRenderFunction(script, bodyCode, {
 		getStaticPathsFn: getStaticPathsFn || void 0,
@@ -1085,6 +1036,109 @@ function compile(parsed, options) {
 	});
 	return importsCode + "\n" + renderFn;
 }
+/**
+* Compile an HTML template source into a JavaScript module string. Single entry for parse + compile.
+* When optional `parsed` is provided (e.g. after registering client scripts in the plugin), it is used to avoid parsing twice.
+*
+* @param htmlSource - Raw HTML template string.
+* @param options - CompileOptions (root, resolvePath, importer, optional script overrides).
+* @param parsed - Optional pre-parsed result; when provided, used instead of parsing htmlSource again.
+* @returns Module source (async render function + optional getStaticPaths).
+*/
+function compileTemplate(htmlSource, options, parsed) {
+	const p = parsed ?? parse(htmlSource);
+	return compile(p, {
+		...options,
+		clientScripts: options.clientScripts ?? p.clientScripts,
+		inlineScripts: options.inlineScripts ?? p.inlineScripts,
+		blockingScripts: options.blockingScripts ?? p.blockingScripts
+	});
+}
+
+//#endregion
+//#region src/vite/rewrite.ts
+/** Route path to output file path (e.g. '' → index.html, about → about/index.html). */
+function toOutputFile(routePath) {
+	if (routePath === "") return "index.html";
+	if (routePath === "404") return "404.html";
+	return toPosix(path$1.join(routePath, "index.html"));
+}
+/** Relative path from fromDir to targetPath, always starting with ./ when non-empty. */
+function normalizeRelativeLink(fromDir, targetPath) {
+	const rel = path$1.posix.relative(fromDir, targetPath);
+	if (!rel) return "./";
+	if (rel.startsWith(".")) return rel;
+	return `./${rel}`;
+}
+/** Relative path to a route (directory index); appends trailing slash for non-root routes. */
+function normalizeRelativeRouteLink(fromDir, routePath) {
+	const targetDir = routePath === "" ? "" : routePath;
+	const rel = path$1.posix.relative(fromDir, targetDir);
+	let res = !rel ? "./" : rel.startsWith(".") ? rel : `./${rel}`;
+	if (routePath !== "" && routePath !== "404" && !res.endsWith("/")) res += "/";
+	return res;
+}
+function normalizeRoutePathFromHref(value) {
+	if (value === "/") return "";
+	return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function isSkippableUrl$1(value) {
+	if (!value) return true;
+	return SKIP_PROTOCOL_REGEX.test(value);
+}
+const ASSET_IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)(\?|$)/i;
+/** Rewrite one absolute URL to dist-relative using manifest and route set; leaves API and external URLs unchanged. */
+function rewriteAbsoluteUrl(value, fromDir, manifest, routeSet, apiPrefix = DEFAULT_API_PREFIX) {
+	if (value.startsWith(apiPrefix)) return value;
+	const noQuery = value.split(/[?#]/)[0] || value;
+	const suffix = value.slice(noQuery.length);
+	const manifestKey = noQuery.replace(/^\//, "");
+	let manifestEntry = manifest[noQuery] ?? manifest[manifestKey];
+	if (!manifestEntry && noQuery.startsWith("assets/")) {
+		const entry = Object.values(manifest).find((e) => e?.file === noQuery || e?.file === manifestKey);
+		if (entry) manifestEntry = entry;
+	}
+	if (manifestEntry?.file) return normalizeRelativeLink(fromDir, manifestEntry.assets?.find((a) => ASSET_IMAGE_EXT.test(a)) ?? manifestEntry.file) + suffix;
+	if (noQuery.startsWith("/assets/")) return normalizeRelativeLink(fromDir, noQuery.replace(/^\//, "")) + suffix;
+	const route = normalizeRoutePathFromHref(noQuery);
+	if (routeSet.has(route) || route === "") return (route === "404" ? normalizeRelativeLink(fromDir, toOutputFile(route)) : normalizeRelativeRouteLink(fromDir, route)) + suffix;
+	return normalizeRelativeLink(fromDir, noQuery.replace(/^\//, "")) + suffix;
+}
+/** Rewrite script src (virtual client → hashed asset) and LINK_ATTRS in rendered HTML; add doctype. */
+function rewriteRenderedHtml(html, outputFile, manifest, routeSet, apiPrefix = DEFAULT_API_PREFIX) {
+	const fromDir = path$1.posix.dirname(outputFile);
+	const { document } = parseHTML(html);
+	for (const script of Array.from(document.querySelectorAll("script[src]"))) {
+		const src = script.getAttribute("src") || "";
+		if (src.startsWith(CLIENT_SCRIPT_PREFIX)) {
+			const newSrc = rewriteAbsoluteUrl(src, fromDir, manifest, routeSet, apiPrefix);
+			script.setAttribute("src", newSrc);
+			script.setAttribute("type", "module");
+			script.removeAttribute("defer");
+			continue;
+		}
+		if (script.getAttribute("type") === "module") script.removeAttribute("defer");
+	}
+	for (const el of Array.from(document.querySelectorAll("*"))) for (const attrName of LINK_ATTRS) {
+		if (!el.hasAttribute(attrName)) continue;
+		const current = (el.getAttribute(attrName) || "").trim();
+		if (!current || isSkippableUrl$1(current)) continue;
+		if (!current.startsWith("/")) continue;
+		el.setAttribute(attrName, rewriteAbsoluteUrl(current, fromDir, manifest, routeSet, apiPrefix));
+	}
+	const htmlTag = document.documentElement;
+	if (htmlTag) return addDoctype(htmlTag.outerHTML);
+	return addDoctype(document.toString());
+}
+/** Prepend `<!doctype html>` if missing. */
+function addDoctype(html) {
+	return /^\s*<!doctype\s+html/i.test(html) ? html : `<!doctype html>\n${html}`;
+}
+function readManifest(distDir) {
+	const manifestPath = path$1.join(distDir, ".vite", "manifest.json");
+	if (!fs.existsSync(manifestPath)) return {};
+	return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+}
 
 //#endregion
 //#region src/vite/build.ts
@@ -1132,12 +1186,6 @@ function toRouteFromPageName(pageName) {
 	if (pageName.endsWith("/index")) return pageName.slice(0, -6);
 	return pageName;
 }
-/** Route path to output file path (e.g. '' → index.html, about → about/index.html). */
-function toOutputFile(routePath) {
-	if (routePath === "") return "index.html";
-	if (routePath === "404") return "404.html";
-	return toPosix(path$1.join(routePath, "index.html"));
-}
 /**
 * Generate sitemap.xml from route paths. Only called when site URL is set.
 * Excludes 404. Writes to distDir/sitemap.xml.
@@ -1152,34 +1200,15 @@ function writeSitemap(routePaths, site, distDir) {
 function escapeXml(s) {
 	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
-/** Relative path from fromDir to targetPath, always starting with ./ when non-empty. */
-function normalizeRelativeLink(fromDir, targetPath) {
-	const rel = path$1.posix.relative(fromDir, targetPath);
-	if (!rel) return "./";
-	if (rel.startsWith(".")) return rel;
-	return `./${rel}`;
-}
-/** Relative path to a route (directory index); appends trailing slash for non-root routes. */
-function normalizeRelativeRouteLink(fromDir, routePath) {
-	const targetDir = routePath === "" ? "" : routePath;
-	const rel = path$1.posix.relative(fromDir, targetDir);
-	let res = !rel ? "./" : rel.startsWith(".") ? rel : `./${rel}`;
-	if (routePath !== "" && routePath !== "404" && !res.endsWith("/")) res += "/";
-	return res;
-}
-function normalizeRoutePathFromHref(value) {
-	if (value === "/") return "";
-	return value.replace(/^\/+/, "").replace(/\/+$/, "");
+/** Root-relative path for manifest key (posix). */
+function toManifestKey(root, filePath) {
+	return toPosixRelative(filePath, root);
 }
 /** True if URL is empty or matches SKIP_PROTOCOL_REGEX (external, hash, etc.). */
 function isSkippableUrl(value) {
 	if (!value) return true;
 	return SKIP_PROTOCOL_REGEX.test(value);
 }
-/** Root-relative path for manifest key (posix). */
-function toManifestKey(root, filePath) {
-	return toPosixRelative(filePath, root);
-}
 /** Resolve script/link src or href to absolute path; returns null for external/skippable or unresolvable. */
 function resolveTemplateAssetPath(rawValue, templateFile, root, resolvePath) {
 	if (!rawValue || isSkippableUrl(rawValue)) return null;
@@ -1299,60 +1328,6 @@ function walkFiles(dir) {
 	}
 	return files;
 }
-/** Prepend `<!doctype html>` if missing. */
-function addDoctype(html) {
-	return /^\s*<!doctype\s+html/i.test(html) ? html : `<!doctype html>\n${html}`;
-}
-/** Image extensions: when a manifest entry's .file is a .js chunk but .assets lists the real image, use it. */
-const ASSET_IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)(\?|$)/i;
-/** Rewrite one absolute URL to dist-relative using manifest and route set; leaves API and external URLs unchanged. */
-function rewriteAbsoluteUrl(value, fromDir, manifest, routeSet, apiPrefix = DEFAULT_API_PREFIX) {
-	if (value.startsWith(apiPrefix)) return value;
-	const noQuery = value.split(/[?#]/)[0] || value;
-	const suffix = value.slice(noQuery.length);
-	const manifestKey = noQuery.replace(/^\//, "");
-	let manifestEntry = manifest[noQuery] ?? manifest[manifestKey];
-	if (!manifestEntry && noQuery.startsWith("assets/")) {
-		const entry = Object.values(manifest).find((e) => e?.file === noQuery || e?.file === manifestKey);
-		if (entry) manifestEntry = entry;
-	}
-	if (manifestEntry?.file) return normalizeRelativeLink(fromDir, manifestEntry.assets?.find((a) => ASSET_IMAGE_EXT.test(a)) ?? manifestEntry.file) + suffix;
-	if (noQuery.startsWith("/assets/")) return normalizeRelativeLink(fromDir, noQuery.replace(/^\//, "")) + suffix;
-	const route = normalizeRoutePathFromHref(noQuery);
-	if (routeSet.has(route) || route === "") return (route === "404" ? normalizeRelativeLink(fromDir, toOutputFile(route)) : normalizeRelativeRouteLink(fromDir, route)) + suffix;
-	return normalizeRelativeLink(fromDir, noQuery.replace(/^\//, "")) + suffix;
-}
-/** Rewrite script src (virtual client → hashed asset) and LINK_ATTRS in rendered HTML; add doctype. */
-function rewriteRenderedHtml(html, outputFile, manifest, routeSet, apiPrefix = DEFAULT_API_PREFIX) {
-	const fromDir = path$1.posix.dirname(outputFile);
-	const { document } = parseHTML(html);
-	for (const script of Array.from(document.querySelectorAll("script[src]"))) {
-		const src = script.getAttribute("src") || "";
-		if (src.startsWith(CLIENT_SCRIPT_PREFIX)) {
-			const newSrc = rewriteAbsoluteUrl(src, fromDir, manifest, routeSet, apiPrefix);
-			script.setAttribute("src", newSrc);
-			script.setAttribute("type", "module");
-			script.removeAttribute("defer");
-			continue;
-		}
-		if (script.getAttribute("type") === "module") script.removeAttribute("defer");
-	}
-	for (const el of Array.from(document.querySelectorAll("*"))) for (const attrName of LINK_ATTRS) {
-		if (!el.hasAttribute(attrName)) continue;
-		const current = (el.getAttribute(attrName) || "").trim();
-		if (!current || isSkippableUrl(current)) continue;
-		if (!current.startsWith("/")) continue;
-		el.setAttribute(attrName, rewriteAbsoluteUrl(current, fromDir, manifest, routeSet, apiPrefix));
-	}
-	const htmlTag = document.documentElement;
-	if (htmlTag) return addDoctype(htmlTag.outerHTML);
-	return addDoctype(document.toString());
-}
-function readManifest(distDir) {
-	const manifestPath = path$1.join(distDir, ".vite", "manifest.json");
-	if (!fs.existsSync(manifestPath)) return {};
-	return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-}
 /**
 * Render all static pages into outDir: discover pages, expand dynamic routes via getStaticPaths, run Vite in middleware mode, rewrite URLs, optionally minify.
 *
@@ -1591,7 +1566,7 @@ function clientGlobPrefix(clientDir) {
 * Ensures template resolution works for custom dirs (e.g. dirs.client === 'frontend').
 * runtimeImportPath: path that resolves to @aerobuilt/core/runtime from the generated file (e.g. relative to .aero/ for SSR).
 */
-function getRuntimeInstanceVirtualSource(clientDir, runtimeImportPath = "@aerobuilt/core/runtime") {
+function getRuntimeInstanceVirtualSource(clientDir, runtimeImportPath = "aerobuilt/runtime") {
 	const prefix = clientGlobPrefix(clientDir);
 	const componentsPattern = `${prefix}/components/**/*.html`;
 	const layoutsPattern = `${prefix}/layouts/*.html`;
@@ -1637,7 +1612,10 @@ function createAeroVirtualsPlugin(state) {
 			discoverClientScriptContentMap(state.config.root, state.dirs.client).forEach((entry, url) => state.clientScripts.set(url, entry));
 		},
 		async resolveId(id, importer) {
-			if (id === RUNTIME_INSTANCE_MODULE_ID) return state.generatedRuntimeInstancePath ?? RESOLVED_RUNTIME_INSTANCE_MODULE_ID;
+			if (id === RUNTIME_INSTANCE_MODULE_ID) {
+				if (state.config?.command === "build" && state.generatedRuntimeInstancePath) return state.generatedRuntimeInstancePath;
+				return RESOLVED_RUNTIME_INSTANCE_MODULE_ID;
+			}
 			if (id.startsWith(CLIENT_SCRIPT_PREFIX)) return "\0" + id;
 			if (id.startsWith("\0" + CLIENT_SCRIPT_PREFIX)) return id;
 			if (id.startsWith(AERO_HTML_VIRTUAL_PREFIX)) return id;
@@ -1665,19 +1643,20 @@ function createAeroVirtualsPlugin(state) {
 				if (!state.config || !state.aliasResult) return null;
 				this.addWatchFile(filePath);
 				try {
-					const parsed = parse(readFileSync(filePath, "utf-8"));
+					const code = readFileSync(filePath, "utf-8");
+					const parsed = parse(code);
 					const baseName = toPosixRelative(filePath, state.config.root).replace(/\.html$/i, "");
 					registerClientScriptsToMap(parsed, baseName, state.clientScripts);
 					for (let i = 0; i < parsed.clientScripts.length; i++) parsed.clientScripts[i].content = getClientScriptVirtualUrl(baseName, i, parsed.clientScripts.length);
 					return {
-						code: compile(parsed, {
+						code: compileTemplate(code, {
 							root: state.config.root,
 							clientScripts: parsed.clientScripts,
 							blockingScripts: parsed.blockingScripts,
 							inlineScripts: parsed.inlineScripts,
 							resolvePath: state.aliasResult.resolve,
 							importer: filePath
-						}),
+						}, parsed),
 						map: null
 					};
 				} catch {
@@ -1714,14 +1693,14 @@ function createAeroTransformPlugin(state) {
 					for (let i = 0; i < parsed.clientScripts.length; i++) parsed.clientScripts[i].content = getClientScriptVirtualUrl(baseName, i, parsed.clientScripts.length);
 				}
 				return {
-					code: compile(parsed, {
+					code: compileTemplate(code, {
 						root: state.config.root,
 						clientScripts: parsed.clientScripts,
 						blockingScripts: parsed.blockingScripts,
 						inlineScripts: parsed.inlineScripts,
 						resolvePath: state.aliasResult.resolve,
 						importer: id
-					}),
+					}, parsed),
 					map: null
 				};
 			} catch (err) {

package/env.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Ambient type declarations for Aero templates.
+ *
+ * Include in your project by adding `"types": ["@aerobuilt/core/env"]` to tsconfig.json,
+ * or via a triple-slash directive: `/// <reference types="@aerobuilt/core/env" />`
+ *
+ * These declarations type the globals available inside `<script is:build>` blocks.
+ *
+ * Single source of truth: the language server generates its preamble from this file.
+ * When changing globals (Aero, renderComponent, *.html, aero:content), run:
+ *   pnpm --dir packages/language-server exec npm run prebuild
+ */
+
+/**
+ * The `Aero` context object available in build scripts. Provides access to
+ * component props, request data, and rendering utilities.
+ *
+ * Use `Aero.props` (capital A). The lowercase `aero` is not defined at runtime.
+ */
+declare const Aero: {
+	/** Props passed to the current component or page. */
+	props: Record<string, any>
+	/** Named slot content (key to HTML string). */
+	slots: Record<string, string>
+	/** The incoming request (available during SSR). */
+	request: Request
+	/** The request URL. */
+	url: URL
+	/** Dynamic route parameters (e.g. `{ id: '42' }` for `/posts/[id]`). */
+	params: Record<string, string>
+	/** Canonical site URL from `aero.config` (e.g. `'https://example.com'`). */
+	site?: string
+}
+
+/**
+ * Render a child component and return its HTML.
+ *
+ * @param component - The imported component (default import from an `.html` file).
+ * @param props - Props to pass to the component.
+ * @param slots - Named slot content.
+ * @returns The rendered HTML string.
+ */
+declare function renderComponent(
+	component: any,
+	props?: Record<string, any>,
+	slots?: Record<string, string>,
+): Promise<string>
+
+/** Allows importing `.html` component files in build scripts. */
+declare module '*.html' {
+	const component: string
+	export default component
+}
+
+/** Content collections: getCollection, render. Used by the language server for IntelliSense. */
+declare module 'aero:content' {
+	interface CollectionEntry {
+		id: string
+		data: Record<string, any>
+		body?: string
+	}
+	export function getCollection(name: string): Promise<CollectionEntry[]>
+	export function render(
+		entry: CollectionEntry | Record<string, any>,
+	): Promise<{ html: string }>
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@aerobuilt/core",
-  "version": "0.3.1",
-  "type": "module",
+  "version": "0.3.3",
+  "private": false,
+  "homepage": "https://github.com/aerobuilt/aero",
   "license": "MIT",
   "author": "Jamie Wilson",
   "repository": {
@@ -9,12 +10,12 @@
     "url": "https://github.com/aerobuilt/aero.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/aerobuilt/aero",
-  "private": false,
-  "types": "./dist/entry-dev.d.mts",
   "files": [
-    "dist"
+    "dist",
+    "env.d.ts"
   ],
+  "type": "module",
+  "types": "./dist/entry-dev.d.mts",
   "exports": {
     ".": {
       "types": "./dist/entry-dev.d.mts",
@@ -48,19 +49,27 @@
     "./editor": {
       "types": "./dist/entry-editor.d.mts",
       "default": "./dist/entry-editor.mjs"
-    }
+    },
+    "./env": "./env.d.ts"
   },
   "dependencies": {
     "get-tsconfig": "^4.13.6",
-    "oxc-resolver": "^11.19.0",
     "html-minifier-next": "^5.1.1",
     "linkedom": "^0.18.12",
     "nitro": "^3.0.1-alpha.2",
     "oxc-parser": "^0.115.0",
+    "oxc-resolver": "^11.19.0",
+    "oxc-transform": "^0.116.0",
     "sharp": "^0.34.5",
     "svgo": "^4.0.0",
     "vite-plugin-image-optimizer": "^2.0.3",
-    "@aerobuilt/interpolation": "0.3.1"
+    "@aerobuilt/interpolation": "0.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsdown": "^0.21.0-beta.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "vite": "^8.0.0-0"
@@ -70,12 +79,6 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@types/node": "^25.3.0",
-    "tsdown": "^0.21.0-beta.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
-  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",