@hatchingpoint/point 0.0.11 → 0.0.13

package/README.md

@@ -13,7 +13,7 @@ point check examples/math.point
 
 Pair with the [Point Language](https://marketplace.visualstudio.com/items?itemName=hatchingpoint.point) extension in VS Code or Cursor.
 
-Point's public source language is semantic product logic. The compiler lowers that source into an internal typed core and emits TypeScript for existing JavaScript infrastructure.
+Point's public source language is semantic product logic. The compiler lowers that source into an internal typed core and emits JavaScript by default for Bun and Node. Use `point build-ts` when you need TypeScript for existing typed JavaScript infrastructure.
 
 This package is the source of truth for Point. It exposes:
 
@@ -29,6 +29,6 @@ bun run check
 bun run build
 ```
 
-`bun run build` emits TypeScript into `generated/` for React, Vue, Bun, Node, and Vite projects.
+`bun run build` emits JavaScript into `generated/` by default. Use `bun run build:ts` for TypeScript and `bun run build:ast` when debugging compiler output.
 
 When Point is extracted, this package can move into a standalone repo with the same package name and public entrypoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchingpoint/point",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "private": false,
   "type": "module",
   "description": "Point language compiler and CLI.",
@@ -24,7 +24,9 @@
   "exports": {
     ".": "./src/index.ts",
     "./cli": "./src/cli.ts",
-    "./core": "./src/core/index.ts"
+    "./core": "./src/core/index.ts",
+    "./std/json": "./src/std/json.ts",
+    "./std/http": "./src/std/http.ts"
   },
   "publishConfig": {
     "access": "public",

package/src/core/ast.ts

@@ -85,11 +85,31 @@ export interface PointSemanticProgramMetadata {
 	source: "semantic";
 }
 
+export interface PointSemanticPageLayout {
+	title: PointCoreExpression;
+	description?: PointCoreExpression;
+	main: PointCoreExpression;
+}
+
+export interface PointSemanticViewCheckboxBinding {
+	label: string;
+	target: PointCoreExpression;
+	recordParam: string;
+	fieldName: string;
+}
+
+export interface PointSemanticViewControls {
+	changeCallback: string;
+	checkboxes: PointSemanticViewCheckboxBinding[];
+}
+
 export interface PointSemanticDeclarationMetadata {
-	kind: "record" | "calculation" | "rule" | "label" | "external" | "action" | "policy" | "view" | "route" | "workflow" | "command";
+	kind: "record" | "calculation" | "rule" | "label" | "external" | "action" | "policy" | "view" | "page" | "route" | "workflow" | "command";
 	name: string;
 	outputName?: string;
 	effects?: string[];
+	pageLayout?: PointSemanticPageLayout;
+	viewControls?: PointSemanticViewControls;
 }
 
 export interface PointCoreTypeExpression {

package/src/core/check-docs.ts

@@ -0,0 +1,155 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { PointCoreDiagnostic } from "./check.ts";
+import { checkPointCore } from "./check.ts";
+import { parsePointSource } from "./parser.ts";
+
+const DEFAULT_DOCS_DIR = "docs/site";
+const POINT_FENCE = /```point\r?\n([\s\S]*?)```/g;
+const POINT_FILE_REF = /\b(?:[\w.-]+\/)*[\w.-]+\.point\b/g;
+
+export interface DocsCheckItemResult {
+	kind: "snippet" | "file";
+	source: string;
+	label: string;
+	line?: number;
+	ok: boolean;
+	diagnostics: PointCoreDiagnostic[];
+}
+
+export interface DocsCheckResult {
+	ok: boolean;
+	checked: number;
+	items: DocsCheckItemResult[];
+}
+
+export async function discoverDocsSiteMarkdown(docsDir = DEFAULT_DOCS_DIR, cwd = process.cwd()): Promise<string[]> {
+	const root = resolve(cwd, docsDir);
+	const glob = new Bun.Glob("**/*.md");
+	const files: string[] = [];
+	for await (const file of glob.scan({ cwd: root, onlyFiles: true })) {
+		files.push(`${docsDir}/${file.replaceAll("\\", "/")}`);
+	}
+	return files.sort((a, b) => a.localeCompare(b));
+}
+
+export function extractPointSnippets(markdown: string, source: string): Array<{ label: string; code: string; line: number }> {
+	const snippets: Array<{ label: string; code: string; line: number }> = [];
+	let index = 0;
+	for (const match of markdown.matchAll(POINT_FENCE)) {
+		index += 1;
+		const code = match[1]?.replace(/\s+$/, "") ?? "";
+		const line = markdown.slice(0, match.index ?? 0).split(/\r?\n/).length;
+		snippets.push({ label: `${source} snippet ${index}`, code, line });
+	}
+	return snippets;
+}
+
+export function extractPointFileReferences(markdown: string, markdownPath: string, cwd = process.cwd()): string[] {
+	const references = new Set<string>();
+	for (const match of markdown.matchAll(POINT_FILE_REF)) {
+		const candidate = match[0]!;
+		if (candidate.endsWith(".point")) references.add(candidate.replaceAll("\\", "/"));
+	}
+	const resolved: string[] = [];
+	for (const reference of references) {
+		const absolute = resolvePointFileReference(reference, markdownPath, cwd);
+		if (absolute) resolved.push(absolute);
+	}
+	return resolved.sort((a, b) => a.localeCompare(b));
+}
+
+function resolvePointFileReference(reference: string, markdownPath: string, cwd: string): string | null {
+	const candidates = [
+		resolve(cwd, reference),
+		resolve(cwd, dirname(markdownPath), reference),
+	];
+	for (const candidate of candidates) {
+		if (!existsSync(candidate)) continue;
+		return candidate.replace(resolve(cwd), "").replace(/^[/\\]/, "").replaceAll("\\", "/");
+	}
+	return null;
+}
+
+function checkPointSource(source: string, label: string, kind: "snippet" | "file", markdownSource: string, line?: number): DocsCheckItemResult {
+	try {
+		const program = parsePointSource(source);
+		const diagnostics = checkPointCore(program);
+		return { kind, source: markdownSource, label, line, ok: diagnostics.length === 0, diagnostics };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			kind,
+			source: markdownSource,
+			label,
+			line,
+			ok: false,
+			diagnostics: [
+				{
+					code: "parse-error",
+					message,
+					path: label,
+					ref: `point://docs/${label}`,
+					severity: "error",
+					span: null,
+					repair: "Fix the Point syntax in this docs snippet or referenced file.",
+				},
+			],
+		};
+	}
+}
+
+export async function checkDocs(options: { docsDir?: string; cwd?: string } = {}): Promise<DocsCheckResult> {
+	const docsDir = options.docsDir ?? DEFAULT_DOCS_DIR;
+	const cwd = options.cwd ?? process.cwd();
+	const markdownFiles = await discoverDocsSiteMarkdown(docsDir, cwd);
+	const items: DocsCheckItemResult[] = [];
+	const checkedFiles = new Set<string>();
+
+	for (const markdownPath of markdownFiles) {
+		const absoluteMarkdownPath = resolve(cwd, markdownPath);
+		const markdown = await Bun.file(absoluteMarkdownPath).text();
+
+		for (const snippet of extractPointSnippets(markdown, markdownPath)) {
+			items.push(checkPointSource(snippet.code, snippet.label, "snippet", markdownPath, snippet.line));
+		}
+
+		for (const filePath of extractPointFileReferences(markdown, markdownPath, cwd)) {
+			if (checkedFiles.has(filePath)) continue;
+			checkedFiles.add(filePath);
+			const source = await Bun.file(resolve(cwd, filePath)).text();
+			items.push(checkPointSource(source, filePath, "file", markdownPath));
+		}
+	}
+
+	return { ok: items.every((item) => item.ok), checked: items.length, items };
+}
+
+export async function runCheckDocs(options: { docsDir?: string; cwd?: string } = {}): Promise<DocsCheckResult> {
+	const result = await checkDocs(options);
+	if (result.ok) {
+		const snippets = result.items.filter((item) => item.kind === "snippet").length;
+		const files = result.items.filter((item) => item.kind === "file").length;
+		console.log(`Point docs check passed: ${snippets} snippet(s), ${files} file reference(s)`);
+		return result;
+	}
+
+	const failures = result.items.filter((item) => !item.ok);
+	console.error(
+		JSON.stringify(
+			{
+				ok: false,
+				failures: failures.map((item) => ({
+					kind: item.kind,
+					source: item.source,
+					label: item.label,
+					line: item.line,
+					diagnostics: item.diagnostics,
+				})),
+			},
+			null,
+			2,
+		),
+	);
+	process.exit(1);
+}

package/src/core/check.ts

@@ -28,7 +28,7 @@ type DiagnosticMetadata = Partial<Pick<PointCoreDiagnostic, "expected" | "actual
 type ScopeEntry = { type: PointCoreTypeExpression; mutable: boolean };
 type Scope = Map<string, ScopeEntry>;
 
-const PRIMITIVE_TYPES = new Set(["Text", "Int", "Float", "Bool", "Void", "List", "Maybe", "Error", "Or"]);
+const PRIMITIVE_TYPES = new Set(["Text", "Int", "Float", "Bool", "Void", "List", "Maybe", "Error", "Or", "Page", "Handler"]);
 
 export function checkPointCore(program: PointCoreProgram): PointCoreDiagnostic[] {
 	const checker = new CoreChecker(program);
@@ -125,6 +125,7 @@ class CoreChecker {
 				}
 				return;
 			}
+			if (fn.semantic?.kind === "page" || fn.semantic?.kind === "view") return;
 			this.checkExpressionAssignable(statement.value, fn.returnType, `fn.${fn.name}.return`, locals);
 			return;
 		}
@@ -531,7 +532,14 @@ class CoreChecker {
 				repair: "Use syntax such as User or Error.",
 			});
 		}
-		if (type.name !== "List" && type.name !== "Maybe" && type.name !== "Or" && type.args.length > 0 && !this.typeDeclarations.has(String(type.name))) {
+		if (type.name === "Handler" && type.args.length !== 1) {
+			this.push("invalid-type-arity", "Handler requires one type argument", path, type.span, {
+				expected: "Handler T",
+				actual: formatType(type),
+				repair: "Use Handler Listing Signals or another record type.",
+			});
+		}
+		if (type.name !== "List" && type.name !== "Maybe" && type.name !== "Or" && type.name !== "Handler" && type.args.length > 0 && !this.typeDeclarations.has(String(type.name))) {
 			this.push("invalid-type-arity", `${type.name} does not accept type arguments`, path, type.span, {
 				expected: String(type.name),
 				actual: formatType(type),

package/src/core/cli.ts

@@ -6,14 +6,19 @@ import { createPointCoreIndex, createPointCoreRepairPlan, explainPointCoreRef }
 import { createSemanticIndex, explainSemanticRef, mapPublicDiagnostics } from "../semantic/context.ts";
 import { emitPointCoreTypeScript } from "./emit-typescript.ts";
 import { emitPointCoreJavaScript } from "./emit-javascript.ts";
+import { emitPointCorePython, isPureLogicProgram } from "./emit-python.ts";
 import { formatPointSource } from "./format.ts";
 import { isCacheHit, isIncrementalEnabled, readBuildCache, recordCacheEntry, writeBuildCache } from "./incremental.ts";
 import { parsePointSource } from "./parser.ts";
+import { runCheckDocs } from "./check-docs.ts";
+import { addPointDependency, modulePathFromLock, POINT_LOCK, POINT_MANIFEST, readPointLock } from "./packages.ts";
 import { runPointLspServer } from "../lsp/server.ts";
 
 const DEFAULT_INPUT = "examples/math.point";
 const DEFAULT_OUTPUT = "generated/math.ast.json";
+const DEFAULT_JS_OUTPUT = "generated/math.js";
 const DEFAULT_TS_OUTPUT = "generated/math.ts";
+const DEFAULT_PY_OUTPUT = "generated/math.py";
 const DEFAULT_PATTERNS = ["examples/**/*.point", "std/**/*.point", "compiler/**/*.point"];
 const GENERATED_DIR = "generated";
 
@@ -34,6 +39,23 @@ export async function main() {
 		return;
 	}
 
+	if (command === "check-docs") {
+		await runCheckDocs();
+		return;
+	}
+
+	if (command === "add") {
+		const dependencyName = input;
+		const spec = output;
+		if (!dependencyName || !spec) {
+			throw new Error("Usage: point add <name> <spec>  (spec: workspace:<path> | file:<path> | npm:<package>)");
+		}
+		const { manifest, lock } = await addPointDependency(dependencyName, spec);
+		console.log(`Point add updated ${POINT_MANIFEST} and ${POINT_LOCK}: ${dependencyName} -> ${spec}`);
+		console.log(JSON.stringify({ name: manifest.name, dependencies: manifest.dependencies, lockPackages: Object.keys(lock.packages) }, null, 2));
+		return;
+	}
+
 	const inputPath = resolve(process.cwd(), input);
 	const source = await Bun.file(inputPath).text();
 	const program = parsePointSource(source);
@@ -101,15 +123,27 @@ export async function main() {
 		return;
 	}
 
-	if (command === "build") {
+	if (command === "build" || command === "build-js") {
+		if (diagnostics.length > 0) {
+			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
+			process.exit(1);
+		}
+		const outputPath = resolve(process.cwd(), output === DEFAULT_OUTPUT ? DEFAULT_JS_OUTPUT : output);
+		await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
+		await Bun.write(outputPath, emitPointCoreJavaScript(program));
+		console.log(`Point core JavaScript build wrote ${outputPath.replaceAll("\\", "/")}`);
+		return;
+	}
+
+	if (command === "build-ast") {
 		if (diagnostics.length > 0) {
 			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
 			process.exit(1);
 		}
-		const outputPath = resolve(process.cwd(), output);
+		const outputPath = resolve(process.cwd(), output === DEFAULT_OUTPUT ? DEFAULT_OUTPUT : output);
 		await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
 		await Bun.write(outputPath, `${JSON.stringify(program, null, 2)}\n`);
-		console.log(`Point core build wrote ${output}`);
+		console.log(`Point core AST build wrote ${outputPath.replaceAll("\\", "/")}`);
 		return;
 	}
 
@@ -125,15 +159,15 @@ export async function main() {
 		return;
 	}
 
-	if (command === "build-js") {
+	if (command === "build-py") {
 		if (diagnostics.length > 0) {
 			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
 			process.exit(1);
 		}
-		const outputPath = resolve(process.cwd(), output === DEFAULT_OUTPUT ? DEFAULT_TS_OUTPUT.replace(/\.ts$/, ".js") : output);
+		const outputPath = resolve(process.cwd(), output === DEFAULT_OUTPUT ? DEFAULT_PY_OUTPUT : output);
 		await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
-		await Bun.write(outputPath, emitPointCoreJavaScript(program));
-		console.log(`Point core JavaScript build wrote ${outputPath.replaceAll("\\", "/")}`);
+		await Bun.write(outputPath, emitPointCorePython(program));
+		console.log(`Point core Python build wrote ${outputPath.replaceAll("\\", "/")}`);
 		return;
 	}
 
@@ -142,8 +176,8 @@ export async function main() {
 			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
 			process.exit(1);
 		}
-		const runOutput = resolve(tmpdir(), `point-run-${Date.now()}.ts`);
-		await Bun.write(runOutput, emitPointCoreTypeScript(program));
+		const runOutput = resolve(tmpdir(), `point-run-${Date.now()}.js`);
+		await Bun.write(runOutput, emitPointCoreJavaScript(program));
 		let entryName: string | null = null;
 		try {
 			const mod = await import(pathToFileUrl(runOutput));
@@ -177,8 +211,9 @@ export async function main() {
 async function runProjectCommand(command: string) {
 	const inputs = await discoverInputs();
 	if (inputs.length === 0) throw new Error(`No Point core files matched ${DEFAULT_PATTERNS.join(", ")}`);
-	const results = await Promise.all(inputs.map((input) => loadCoreFile(input)));
-	const graph = createModuleGraph(results);
+	const lock = await readPointLock();
+	const results = await Promise.all(inputs.map((input) => loadCoreFile(input, lock)));
+	const graph = createModuleGraph(results, lock);
 	const orderedResults = orderByDependencies(results, graph);
 
 	if (command === "fmt-all") {
@@ -223,7 +258,7 @@ async function runProjectCommand(command: string) {
 		return;
 	}
 
-	if (command === "build-all") {
+	if (command === "build-all" || command === "build-js-all") {
 		const diagnostics = orderedResults.flatMap((result) =>
 			checkPointCore(programWithDependencyDeclarations(result, graph)).map((diagnostic) => ({ ...diagnostic, file: result.input })),
 		);
@@ -232,12 +267,30 @@ async function runProjectCommand(command: string) {
 			process.exit(1);
 		}
 		for (const result of orderedResults) {
-			const output = outputFor(result.input);
+			const output = jsOutputFor(result.input);
+			const outputPath = resolve(process.cwd(), output);
+			await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
+			await Bun.write(outputPath, emitPointCoreJavaScript(programWithTypeScriptImports(result, graph)));
+		}
+		console.log(`Point core JavaScript build wrote ${results.length} files`);
+		return;
+	}
+
+	if (command === "build-ast-all") {
+		const diagnostics = orderedResults.flatMap((result) =>
+			checkPointCore(programWithDependencyDeclarations(result, graph)).map((diagnostic) => ({ ...diagnostic, file: result.input })),
+		);
+		if (diagnostics.length > 0) {
+			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
+			process.exit(1);
+		}
+		for (const result of orderedResults) {
+			const output = astOutputFor(result.input);
 			const outputPath = resolve(process.cwd(), output);
 			await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
 			await Bun.write(outputPath, `${JSON.stringify(result.program, null, 2)}\n`);
 		}
-		console.log(`Point core build wrote ${results.length} files`);
+		console.log(`Point core AST build wrote ${results.length} files`);
 		return;
 	}
 
@@ -259,7 +312,7 @@ async function runProjectCommand(command: string) {
 		return;
 	}
 
-	if (command === "build-js-all") {
+	if (command === "build-py-all") {
 		const diagnostics = orderedResults.flatMap((result) =>
 			checkPointCore(programWithDependencyDeclarations(result, graph)).map((diagnostic) => ({ ...diagnostic, file: result.input })),
 		);
@@ -267,13 +320,15 @@ async function runProjectCommand(command: string) {
 			console.error(JSON.stringify({ ok: false, diagnostics }, null, 2));
 			process.exit(1);
 		}
-		for (const result of orderedResults) {
-			const output = jsOutputFor(result.input);
+		const pureLogicResults = orderedResults.filter((result) => isPureLogicProgram(result.program));
+		for (const result of pureLogicResults) {
+			const output = pyOutputFor(result.input);
 			const outputPath = resolve(process.cwd(), output);
 			await Bun.$`mkdir -p ${dirname(outputPath)}`.quiet();
-			await Bun.write(outputPath, emitPointCoreJavaScript(programWithTypeScriptImports(result, graph)));
+			await Bun.write(outputPath, emitPointCorePython(programWithTypeScriptImports(result, graph)));
 		}
-		console.log(`Point core JavaScript build wrote ${results.length} files`);
+		const skipped = results.length - pureLogicResults.length;
+		console.log(`Point core Python build wrote ${pureLogicResults.length} files${skipped ? ` (${skipped} skipped)` : ""}`);
 		return;
 	}
 
@@ -358,8 +413,8 @@ async function runPointTests(program: PointCoreProgram, input: string): Promise<
 			(declaration.semantic?.name.startsWith("test") || declaration.name.startsWith("test")),
 	);
 	if (tests.length === 0) return { file: input, ok: true, tests: [] };
-	const testOutput = resolve(tmpdir(), `point-test-${Date.now()}-${Math.random().toString(16).slice(2)}.ts`);
-	await Bun.write(testOutput, emitPointCoreTypeScript(program));
+	const testOutput = resolve(tmpdir(), `point-test-${Date.now()}-${Math.random().toString(16).slice(2)}.js`);
+	await Bun.write(testOutput, emitPointCoreJavaScript(program));
 	const mod = await import(pathToFileUrl(testOutput));
 	const results = [];
 	for (const test of tests) {
@@ -388,9 +443,9 @@ export function findRunEntryName(program: PointCoreProgram): string | null {
 	return preferred?.name ?? null;
 }
 
-async function loadCoreFile(input: string) {
+async function loadCoreFile(input: string, lock: Awaited<ReturnType<typeof readPointLock>>) {
 	const source = await Bun.file(resolve(process.cwd(), input)).text();
-	return { input, source, program: parsePointSource(source), uses: parseUseDeclarations(source, input) };
+	return { input, source, program: parsePointSource(source), uses: parseUseDeclarations(source, input, lock) };
 }
 
 type CoreFile = Awaited<ReturnType<typeof loadCoreFile>>;
@@ -402,15 +457,15 @@ interface UseDeclaration {
 	input: string;
 }
 
-function parseUseDeclarations(source: string, input: string): UseDeclaration[] {
+function parseUseDeclarations(source: string, input: string, lock: Awaited<ReturnType<typeof readPointLock>>): UseDeclaration[] {
 	return source
 		.split(/\r?\n/)
 		.map((line) => line.trim().match(/^use\s+([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*)(?:\s+from\s+"([^"]+)")?$/))
 		.filter((match): match is RegExpMatchArray => Boolean(match))
-		.map((match) => ({ moduleName: match[1]!, from: match[2] ?? stdPathFor(match[1]!), input }));
+		.map((match) => ({ moduleName: match[1]!, from: match[2] ?? modulePathFromLock(lock, match[1]!), input }));
 }
 
-function createModuleGraph(results: CoreFile[]): ModuleGraph {
+function createModuleGraph(results: CoreFile[], lock: Awaited<ReturnType<typeof readPointLock>>): ModuleGraph {
 	const byInput = new Map(results.map((result) => [normalizeInput(result.input), result]));
 	const graph: ModuleGraph = new Map();
 	for (const result of results) {
@@ -474,11 +529,6 @@ function resolveDependencyInput(input: string, from: string): string {
 	return resolve(base, from).replace(resolve(process.cwd()), "").replace(/^[/\\]/, "");
 }
 
-function stdPathFor(moduleName: string): string {
-	if (!moduleName.startsWith("std.")) throw new Error(`Use declarations without from must target std modules: ${moduleName}`);
-	return `${moduleName.replace(/^std\./, "std/").replaceAll(".", "/")}.point`;
-}
-
 function normalizeInput(input: string): string {
 	return input.replaceAll("\\", "/");
 }
@@ -498,6 +548,15 @@ function jsOutputFor(input: string): string {
 	return `${GENERATED_DIR}/${name}.js`;
 }
 
+function astOutputFor(input: string): string {
+	return outputFor(input);
+}
+
+function pyOutputFor(input: string): string {
+	const name = outputBaseName(input);
+	return `${GENERATED_DIR}/${name}.py`;
+}
+
 function outputBaseName(input: string): string {
 	return normalizeInput(input).split("/").pop()?.replace(/\.point$/, "") ?? "program";
 }

package/src/core/context.ts

@@ -27,6 +27,7 @@ export type PointCoreSymbolKind =
 	| "action"
 	| "policy"
 	| "view"
+	| "page"
 	| "route"
 	| "workflow"
 	| "command";
@@ -325,6 +326,7 @@ function relatedRefsFor(symbol: PointCoreSymbol, index: PointCoreIndex): string[
 		symbol.kind === "action" ||
 		symbol.kind === "policy" ||
 		symbol.kind === "view" ||
+		symbol.kind === "page" ||
 		symbol.kind === "route" ||
 		symbol.kind === "workflow" ||
 		symbol.kind === "command"
@@ -351,6 +353,7 @@ function summaryFor(symbol: PointCoreSymbol): string {
 	if (symbol.kind === "action") return `Semantic action ${symbol.name} returns ${symbol.type}; effects: ${(symbol.effects ?? []).join(", ") || "none"}.`;
 	if (symbol.kind === "policy") return `Semantic policy ${symbol.name} returns ${symbol.type}.`;
 	if (symbol.kind === "view") return `Semantic view ${symbol.name} returns React JSX.`;
+	if (symbol.kind === "page") return `Semantic page ${symbol.name} returns a Next.js page shell as React JSX.`;
 	if (symbol.kind === "route") return `Semantic route ${symbol.name} returns ${symbol.type}.`;
 	if (symbol.kind === "workflow") return `Semantic workflow ${symbol.name} returns ${symbol.type}.`;
 	if (symbol.kind === "command") return `Semantic command ${symbol.name} returns ${symbol.type}.`;

package/src/core/emit-javascript.ts

@@ -8,6 +8,8 @@ import type {
 	PointCoreTypeDeclaration,
 	PointCoreValueDeclaration,
 } from "./ast.ts";
+import type { PointSemanticRouteDeclaration } from "../semantic/ast.ts";
+import { semanticFunctionName } from "../semantic/naming.ts";
 
 const BINARY_OPERATORS: Record<string, string> = {
 	and: "&&",
@@ -16,13 +18,22 @@ const BINARY_OPERATORS: Record<string, string> = {
 
 /** Emit JavaScript from a core AST program (no type syntax). Production path: parsePointSource → check → emit. */
 export function emitPointCoreJavaScript(program: PointCoreProgram): string {
+	const routes = program.semanticSource?.declarations.filter((declaration): declaration is PointSemanticRouteDeclaration => declaration.kind === "route") ?? [];
+	const routeServeCommand = program.declarations.find((declaration) => declaration.kind === "function" && isRouteServeCommand(declaration));
 	const lines: string[] = [];
 	lines.push("// Generated by Point. Do not edit directly.");
 	if (program.module) lines.push(`// Point module: ${program.module}`);
 	lines.push("");
 	for (const declaration of program.declarations) {
+		if (declaration.kind === "function" && declaration.semantic?.kind === "command" && routes.length > 0 && isRouteServeCommand(declaration)) {
+			lines.push(...emitRouteServeCommand(declaration), "");
+			continue;
+		}
 		lines.push(...emitDeclaration(declaration), "");
 	}
+	if (routes.length > 0 && routeServeCommand) {
+		lines.push(...emitRouteServerRuntime(routes), "");
+	}
 	return `${trimTrailingBlankLines(lines).join("\n")}\n`;
 }
 
@@ -41,9 +52,13 @@ function emitDeclaration(declaration: PointCoreDeclaration): string[] {
 
 function emitFunction(declaration: PointCoreFunctionDeclaration): string[] {
 	const asyncPrefix = declaration.semantic?.kind === "action" || declaration.semantic?.kind === "workflow" || declaration.semantic?.kind === "command" ? "async " : "";
+	const bodyLines =
+		declaration.semantic?.kind === "page" && declaration.semantic.pageLayout
+			? [`return ${emitExpression(declaration.semantic.pageLayout.main)};`]
+			: declaration.body.flatMap((statement) => emitStatement(statement, declaration.semantic?.kind));
 	return [
 		`export ${asyncPrefix}function ${declaration.name}(${declaration.params.map(emitParam).join(", ")}) {`,
-		...indentLines(declaration.body.flatMap((statement) => emitStatement(statement, declaration.semantic?.kind))),
+		...indentLines(bodyLines),
 		"}",
 	];
 }
@@ -122,3 +137,54 @@ function trimTrailingBlankLines(lines: string[]): string[] {
 	while (lines.at(-1) === "") lines.pop();
 	return lines;
 }
+
+function isRouteServeCommand(declaration: PointCoreFunctionDeclaration): boolean {
+	return declaration.semantic?.name === "serve store readiness" || declaration.name === "serveStoreReadinessCommand";
+}
+
+function emitRouteServeCommand(declaration: PointCoreFunctionDeclaration): string[] {
+	const asyncPrefix = declaration.semantic?.kind === "command" ? "async " : "";
+	return [
+		`export ${asyncPrefix}function ${declaration.name}(${declaration.params.map(emitParam).join(", ")}) {`,
+		"  const port = Number(process.env.PORT ?? 3456);",
+		"  const server = Bun.serve({ port, fetch: createPointRouteFetchHandler() });",
+		"  console.log(`Store readiness listening on http://localhost:${server.port}`);",
+		"  await new Promise(() => {});",
+		"}",
+	];
+}
+
+function emitRouteServerRuntime(routes: PointSemanticRouteDeclaration[]): string[] {
+	const matchers = routes.map((route) => {
+		const handlerName = semanticFunctionName(route.name, "route", "route");
+		const pattern = route.path.replace(/:[A-Za-z][A-Za-z0-9_]*/g, "([^/]+)").replace(/\//g, "\\/");
+		const argExpressions = route.inputs.map((_input, index) => `match[${index + 1}]`);
+		return {
+			method: route.method.toUpperCase(),
+			pattern,
+			handlerName,
+			argExpressions,
+		};
+	});
+	const matchLines = matchers.flatMap((matcher) => [
+		`  if (req.method === ${JSON.stringify(matcher.method)} && new RegExp(${JSON.stringify(`^${matcher.pattern}$`)}).test(url.pathname)) {`,
+		`    const match = url.pathname.match(new RegExp(${JSON.stringify(`^${matcher.pattern}$`)}));`,
+		`    const body = ${matcher.handlerName}(${matcher.argExpressions.join(", ")});`,
+		'    return new Response(typeof body === "string" ? body : body, { headers: { "content-type": "application/json" } });',
+		"  }",
+	]);
+	return [
+		"export function createPointRouteFetchHandler() {",
+		"  return async (req) => {",
+		"    const url = new URL(req.url);",
+		...matchLines,
+		'    return new Response(JSON.stringify({ error: "Not found" }), { status: 404, headers: { "content-type": "application/json" } });',
+		"  };",
+		"}",
+		"",
+		"export function startRoutesServer() {",
+		"  const port = Number(process.env.PORT ?? 3456);",
+		"  return Bun.serve({ port, fetch: createPointRouteFetchHandler() });",
+		"}",
+	];
+}