@hatchingpoint/point 0.0.12 → 0.0.14

package/src/core/packages.ts

@@ -0,0 +1,230 @@
+import { createRequire } from "node:module";
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+export const POINT_MANIFEST = "point.json";
+export const POINT_LOCK = "point.lock";
+export const LOCK_SCHEMA = "point.lock.v1";
+
+export interface PointManifest {
+	name: string;
+	version: string;
+	dependencies?: Record<string, string>;
+}
+
+export interface PointLock {
+	schemaVersion: typeof LOCK_SCHEMA;
+	packages: Record<string, PointLockPackage>;
+}
+
+export interface PointLockPackage {
+	version: string;
+	path?: string;
+	dependencies?: Record<string, string>;
+}
+
+export type DependencySpecKind = "workspace" | "file" | "npm";
+
+export interface ParsedDependencySpec {
+	kind: DependencySpecKind;
+	locator: string;
+}
+
+export interface ParsedNpmLocator {
+	name: string;
+	version?: string;
+}
+
+export function parseNpmLocator(locator: string): ParsedNpmLocator {
+	if (locator.startsWith("@")) {
+		const slash = locator.indexOf("/");
+		if (slash < 0) {
+			throw new Error(`Invalid npm package name "${locator}". Scoped packages use @scope/name.`);
+		}
+		const rest = locator.slice(slash + 1);
+		const versionAt = rest.indexOf("@");
+		if (versionAt >= 0) {
+			return { name: `${locator.slice(0, slash + 1 + versionAt)}`, version: rest.slice(versionAt + 1) };
+		}
+		return { name: locator };
+	}
+	const versionAt = locator.lastIndexOf("@");
+	if (versionAt > 0) {
+		return { name: locator.slice(0, versionAt), version: locator.slice(versionAt + 1) };
+	}
+	return { name: locator };
+}
+
+export function parseDependencySpec(spec: string): ParsedDependencySpec {
+	if (spec.startsWith("workspace:")) return { kind: "workspace", locator: spec.slice("workspace:".length) };
+	if (spec.startsWith("file:")) return { kind: "file", locator: spec.slice("file:".length) };
+	if (spec.startsWith("npm:")) return { kind: "npm", locator: spec.slice("npm:".length) };
+	throw new Error(`Invalid dependency spec "${spec}". Use workspace:<path>, file:<path>, or npm:<package>[@version].`);
+}
+
+export async function readPointManifest(cwd = process.cwd()): Promise<PointManifest> {
+	const path = join(cwd, POINT_MANIFEST);
+	if (!existsSync(path)) throw new Error(`Missing ${POINT_MANIFEST} in ${cwd}`);
+	return Bun.file(path).json() as Promise<PointManifest>;
+}
+
+export async function writePointManifest(manifest: PointManifest, cwd = process.cwd()): Promise<void> {
+	const path = join(cwd, POINT_MANIFEST);
+	await Bun.write(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export async function readPointLock(cwd = process.cwd()): Promise<PointLock | null> {
+	const path = join(cwd, POINT_LOCK);
+	if (!existsSync(path)) return null;
+	const lock = (await Bun.file(path).json()) as PointLock;
+	if (lock.schemaVersion !== LOCK_SCHEMA) {
+		throw new Error(`Unsupported ${POINT_LOCK} schema: ${lock.schemaVersion}`);
+	}
+	return lock;
+}
+
+export async function writePointLock(lock: PointLock, cwd = process.cwd()): Promise<void> {
+	const path = join(cwd, POINT_LOCK);
+	await Bun.write(path, `${JSON.stringify(lock, null, 2)}\n`);
+}
+
+export function normalizePackagePath(cwd: string, rawPath: string): string {
+	const absolute = resolve(cwd, rawPath);
+	if (!existsSync(absolute)) {
+		throw new Error(`Dependency path does not exist: ${rawPath}`);
+	}
+	return relative(cwd, absolute).split("\\").join("/") || ".";
+}
+
+export function locatePointPackageRoot(pkgDir: string): string {
+	if (existsSync(join(pkgDir, POINT_MANIFEST))) return pkgDir;
+	const srcDir = join(pkgDir, "src");
+	if (existsSync(srcDir) && readdirSync(srcDir).some((name) => name.endsWith(".point"))) return pkgDir;
+	if (readdirSync(pkgDir).some((name) => name.endsWith(".point"))) return pkgDir;
+	throw new Error(`Point package at ${pkgDir} has no ${POINT_MANIFEST} or src/*.point modules`);
+}
+
+export function resolveNpmPackagePath(cwd: string, packageName: string): string | null {
+	const direct = join(cwd, "node_modules", ...packageName.split("/"));
+	if (existsSync(join(direct, "package.json"))) return direct;
+	try {
+		const req = createRequire(join(cwd, "package.json"));
+		const pkgJson = req.resolve(`${packageName}/package.json`);
+		return resolve(pkgJson, "..");
+	} catch {
+		return null;
+	}
+}
+
+async function readInstalledNpmVersion(pkgDir: string): Promise<string | null> {
+	const pkgJsonPath = join(pkgDir, "package.json");
+	if (!existsSync(pkgJsonPath)) return null;
+	const pkg = (await Bun.file(pkgJsonPath).json()) as { version?: string };
+	return pkg.version ?? null;
+}
+
+export async function ensureNpmPackage(cwd: string, packageName: string, version?: string): Promise<string> {
+	const installed = resolveNpmPackagePath(cwd, packageName);
+	if (installed) {
+		const installedVersion = await readInstalledNpmVersion(installed);
+		if (!version || installedVersion === version) return installed;
+	}
+	const installSpec = version ? `${packageName}@${version}` : packageName;
+	const result = await Bun.$`npm install ${installSpec} --prefix ${cwd} --no-save --no-package-lock`.quiet().nothrow();
+	if (result.exitCode !== 0) {
+		const detail = result.stderr.toString().trim() || result.stdout.toString().trim();
+		throw new Error(`npm install failed for ${installSpec}: ${detail || "unknown error"}`);
+	}
+	const resolved = resolveNpmPackagePath(cwd, packageName);
+	if (!resolved) {
+		throw new Error(`npm package "${packageName}" was not found under node_modules/ after install`);
+	}
+	if (version) {
+		const installedVersion = await readInstalledNpmVersion(resolved);
+		if (installedVersion && installedVersion !== version) {
+			throw new Error(`npm package "${packageName}" resolved to ${installedVersion}, expected ${version}`);
+		}
+	}
+	return resolved;
+}
+
+export async function resolveNpmDependencySpec(spec: string, cwd = process.cwd()): Promise<PointLockPackage> {
+	const parsed = parseDependencySpec(spec);
+	if (parsed.kind !== "npm") throw new Error(`Expected npm: spec, got ${spec}`);
+	const { name, version } = parseNpmLocator(parsed.locator);
+	const pkgDir = await ensureNpmPackage(cwd, name, version);
+	locatePointPackageRoot(pkgDir);
+	const npmVersion = (await readInstalledNpmVersion(pkgDir)) ?? version ?? "npm";
+	return { version: npmVersion, path: normalizePackagePath(cwd, pkgDir) };
+}
+
+export async function resolveDependencySpec(spec: string, cwd = process.cwd()): Promise<PointLockPackage> {
+	const parsed = parseDependencySpec(spec);
+	if (parsed.kind === "npm") return resolveNpmDependencySpec(spec, cwd);
+	const path = normalizePackagePath(cwd, parsed.locator);
+	return { version: parsed.kind, path };
+}
+
+export async function resolveLockFromManifest(manifest: PointManifest, cwd = process.cwd()): Promise<PointLock> {
+	const packages: Record<string, PointLockPackage> = {
+		[manifest.name]: {
+			version: manifest.version,
+			dependencies: manifest.dependencies ?? {},
+		},
+	};
+	for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
+		packages[name] = await resolveDependencySpec(spec, cwd);
+		const entry = packages[name];
+		if (!entry.path) continue;
+		const nestedManifestPath = join(cwd, entry.path, POINT_MANIFEST);
+		if (!existsSync(nestedManifestPath)) continue;
+		const nested = (await Bun.file(nestedManifestPath).json()) as PointManifest;
+		packages[nested.name] = {
+			version: nested.version,
+			dependencies: nested.dependencies ?? {},
+		};
+	}
+	return { schemaVersion: LOCK_SCHEMA, packages };
+}
+
+export async function addPointDependency(name: string, spec: string, cwd = process.cwd()): Promise<{ manifest: PointManifest; lock: PointLock }> {
+	if (!name || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+		throw new Error(`Invalid dependency name "${name}". Use an identifier like std or point-logic.`);
+	}
+	parseDependencySpec(spec);
+	const manifest = await readPointManifest(cwd);
+	manifest.dependencies = { ...(manifest.dependencies ?? {}), [name]: spec };
+	const lock = await resolveLockFromManifest(manifest, cwd);
+	await writePointManifest(manifest, cwd);
+	await writePointLock(lock, cwd);
+	return { manifest, lock };
+}
+
+export function packageRootFromLock(lock: PointLock | null, packageName: string): string | null {
+	const entry = lock?.packages[packageName];
+	if (entry?.path) return entry.path;
+	if (!lock && packageName === "std") return "std";
+	return null;
+}
+
+function modulePathCandidates(root: string, modulePath: string): string[] {
+	const segments = modulePath.replaceAll(".", "/");
+	return [`${root}/${segments}.point`, `${root}/src/${segments}.point`];
+}
+
+export function modulePathFromLock(lock: PointLock | null, moduleName: string, cwd = process.cwd()): string {
+	const dot = moduleName.indexOf(".");
+	if (dot < 0) {
+		throw new Error(`Use declarations without from must target package modules: ${moduleName}`);
+	}
+	const packageName = moduleName.slice(0, dot);
+	const modulePath = moduleName.slice(dot + 1);
+	const root = packageRootFromLock(lock, packageName);
+	if (!root) {
+		throw new Error(`Unknown package "${packageName}" in ${moduleName}. Add it with: point add ${packageName} <spec>`);
+	}
+	for (const candidate of modulePathCandidates(root, modulePath)) {
+		if (existsSync(join(cwd, candidate))) return candidate;
+	}
+	return modulePathCandidates(root, modulePath)[0]!;
+}

package/src/core/run-bridge.ts

@@ -0,0 +1,93 @@
+import type { PointCoreProgram } from "./ast.ts";
+import { emitPointCoreJavaScript } from "./emit-javascript.ts";
+import { isPureLogicProgram } from "./emit-python.ts";
+
+/** Pure logic with no imports or externals can run in-memory without a temp module file. */
+export function canBundleRunInMemory(program: PointCoreProgram): boolean {
+	if (!isPureLogicProgram(program)) return false;
+	if (program.declarations.some((declaration) => declaration.kind === "import" || declaration.kind === "external")) return false;
+	if (program.semanticSource?.uses?.length) return false;
+	const emitted = emitPointCoreJavaScript(program);
+	if (/^\s*import\s/m.test(emitted)) return false;
+	return !hasUnresolvedCallTargets(emitted);
+}
+
+const BUILTIN_CALL_TARGETS = new Set([
+	"Array",
+	"Boolean",
+	"JSON",
+	"Math",
+	"Number",
+	"Object",
+	"Promise",
+	"String",
+	"console",
+	"fetch",
+	"parseInt",
+	"parseFloat",
+]);
+
+const NON_CALL_KEYWORDS = new Set([
+	"async",
+	"await",
+	"catch",
+	"delete",
+	"export",
+	"for",
+	"function",
+	"if",
+	"import",
+	"instanceof",
+	"new",
+	"return",
+	"switch",
+	"throw",
+	"typeof",
+	"void",
+	"while",
+	"with",
+	"yield",
+]);
+
+function hasUnresolvedCallTargets(source: string): boolean {
+	const defined = new Set<string>();
+	for (const match of source.matchAll(/(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g)) defined.add(match[1]!);
+	for (const match of source.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+		const name = match[1]!;
+		if (NON_CALL_KEYWORDS.has(name) || BUILTIN_CALL_TARGETS.has(name) || defined.has(name)) continue;
+		return true;
+	}
+	return false;
+}
+
+export function bundleJavaScriptForEval(source: string): { body: string; exports: string[] } {
+	const exports: string[] = [];
+	const bodyLines: string[] = [];
+	for (const line of source.split(/\r?\n/)) {
+		if (/^\s*import\s/.test(line)) continue;
+		const fnMatch = line.match(/^export\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)/);
+		if (fnMatch) {
+			exports.push(fnMatch[2]!);
+			bodyLines.push(line.replace(/^export\s+/, ""));
+			continue;
+		}
+		const bindingMatch = line.match(/^export\s+(const|let|var)\s+([A-Za-z_$][\w$]*)/);
+		if (bindingMatch) {
+			exports.push(bindingMatch[2]!);
+			bodyLines.push(line.replace(/^export\s+/, ""));
+			continue;
+		}
+		bodyLines.push(line);
+	}
+	return { body: bodyLines.join("\n"), exports };
+}
+
+export async function executeBundledEntry(program: PointCoreProgram, entryName: string): Promise<unknown> {
+	const { body, exports } = bundleJavaScriptForEval(emitPointCoreJavaScript(program));
+	if (!exports.includes(entryName)) throw new Error(`Entrypoint ${entryName} was not emitted.`);
+	const factory = new Function(`"use strict";\n${body}\nreturn { ${exports.join(", ")} };`);
+	const mod = factory() as Record<string, unknown>;
+	const entry = mod[entryName];
+	if (typeof entry !== "function") throw new Error(`Entrypoint ${entryName} was not a function.`);
+	return await (entry as () => unknown)();
+}

package/src/core/semantic-source.ts

@@ -1,7 +1,7 @@
 export function isSemanticPointSyntax(source: string): boolean {
 	return source
 		.split(/\r?\n/)
-		.some((line) => /^(use|record|calculation|rule|label|external|action|policy|view|route|workflow|command)\s+/.test(line.trim()));
+		.some((line) => /^(use|record|calculation|rule|label|external|action|policy|view|page|route|workflow|command)\s+/.test(line.trim()));
 }
 
 export function assertSemanticPointSource(source: string) {
@@ -12,7 +12,7 @@ export function assertSemanticPointSource(source: string) {
 	for (const [index, line] of lines.entries()) {
 		const trimmed = line.trim();
 		if (!trimmed || trimmed.startsWith("//")) continue;
-		if (/^(record|calculation|rule|label|external|action|policy|view|route|workflow|command)\s+/.test(trimmed)) hasSemanticDeclaration = true;
+		if (/^(record|calculation|rule|label|external|action|policy|view|page|route|workflow|command)\s+/.test(trimmed)) hasSemanticDeclaration = true;
 		if (oldStyleTopLevel.test(trimmed)) {
 			throw new Error(
 				`Point source uses internal core syntax at ${index + 1}:1. Use record, calculation, rule, or label instead.`,

package/src/core/test-only/legacy-lowering.ts

@@ -1,5 +1,7 @@
 import type { PointCoreProgram } from "../ast.ts";
 import { assertSemanticPointSource, isSemanticPointSyntax } from "../semantic-source.ts";
+import { desugarSemanticProgram } from "../../semantic/desugar.ts";
+import { parseSemanticSource } from "../../semantic/parse.ts";
 import { parsePointCore } from "./core-text-parser.ts";
 
 /** Legacy string-lowering path retained for migration parity tests only. */
@@ -11,10 +13,27 @@ export function parsePointSourceLegacy(source: string): PointCoreProgram {
 function parsePointSourceViaLowering(source: string): PointCoreProgram {
 	const lowered = lowerSemanticPointSyntax(source);
 	const program = parsePointCore(lowered);
-	if (isSemanticPointSyntax(source)) attachSemanticMetadata(program, source);
+	if (isSemanticPointSyntax(source)) {
+		attachSemanticMetadata(program, source);
+		enrichPageLayouts(program, source);
+	}
 	return program;
 }
 
+function enrichPageLayouts(program: PointCoreProgram, source: string): void {
+	const desugared = desugarSemanticProgram(parseSemanticSource(source));
+	const pageFunctions = desugared.declarations.filter(
+		(declaration): declaration is Extract<(typeof desugared.declarations)[number], { kind: "function" }> =>
+			declaration.kind === "function" && declaration.semantic?.kind === "page",
+	);
+	for (const declaration of program.declarations) {
+		if (declaration.kind !== "function" || declaration.semantic?.kind !== "page") continue;
+		const match = pageFunctions.find((candidate) => candidate.name === declaration.name);
+		if (!match?.semantic?.pageLayout) continue;
+		declaration.semantic.pageLayout = match.semantic.pageLayout;
+	}
+}
+
 function lowerSemanticPointSyntax(source: string): string {
 	if (!isSemanticPointSyntax(source)) return source;
 	const lines = source.split(/\r?\n/);
@@ -87,6 +106,12 @@ function lowerSemanticPointSyntax(source: string): string {
 			index = lowered.next;
 			continue;
 		}
+		if (trimmed.startsWith("page ")) {
+			const lowered = lowerPage(lines, index, records, externalBindings);
+			output.push(...lowered.lines);
+			index = lowered.next;
+			continue;
+		}
 		if (trimmed.startsWith("route ")) {
 			const lowered = lowerRoute(lines, index, records, externalBindings);
 			output.push(...lowered.lines);
@@ -120,7 +145,7 @@ function assertSemanticPointSource(source: string) {
 	for (const [index, line] of lines.entries()) {
 		const trimmed = line.trim();
 		if (!trimmed || trimmed.startsWith("//")) continue;
-		if (/^(record|calculation|rule|label|external|action|policy|view|route|workflow|command)\s+/.test(trimmed)) hasSemanticDeclaration = true;
+		if (/^(record|calculation|rule|label|external|action|policy|view|page|route|workflow|command)\s+/.test(trimmed)) hasSemanticDeclaration = true;
 		if (oldStyleTopLevel.test(trimmed)) {
 			throw new Error(
 				`Point source uses internal core syntax at ${index + 1}:1. Use record, calculation, rule, or label instead.`,
@@ -534,6 +559,44 @@ function lowerView(
 	};
 }
 
+function lowerPage(
+	lines: string[],
+	start: number,
+	records: Map<string, Map<string, string>>,
+	externalBindings: Map<string, string> = new Map(),
+): { lines: string[]; next: number } {
+	const label = (lines[start] ?? "").trim().slice("page ".length).trim();
+	const body = collectSemanticBody(lines, start + 1);
+	const params: string[] = [];
+	const paramTypes = new Map<string, string>();
+	const bindings = new Map<string, string>(externalBindings);
+	let mainExpression: string | undefined;
+
+	for (const line of body.lines) {
+		if (line.startsWith("input ")) {
+			const param = parseTypedBinding(line.slice("input ".length));
+			const paramName = toIdentifier(param.name);
+			params.push(`${paramName}: ${param.type}`);
+			paramTypes.set(paramName, param.type);
+			bindings.set(param.name, paramName);
+			continue;
+		}
+		if (line.startsWith("title ") || line.startsWith("description ")) continue;
+		if (line.startsWith("main render ")) {
+			mainExpression = lowerExpression(line.slice("main render ".length), paramTypes, records, bindings);
+			continue;
+		}
+		throw new Error(`Unknown page statement: ${line}`);
+	}
+
+	if (!mainExpression) throw new Error(`Page ${label} requires main render`);
+
+	return {
+		lines: [`fn ${semanticFunctionName(label, "page", "page")}(${params.join(", ")}): Text {`, `  return ${mainExpression}`, "}", ""],
+		next: body.next,
+	};
+}
+
 function lowerRoute(
 	lines: string[],
 	start: number,
@@ -745,6 +808,7 @@ function collectSemanticDeclarationInfo(source: string): SemanticDeclarationInfo
 			trimmed.startsWith("action ") ||
 			trimmed.startsWith("policy ") ||
 			trimmed.startsWith("view ") ||
+			trimmed.startsWith("page ") ||
 			trimmed.startsWith("route ") ||
 			trimmed.startsWith("workflow ") ||
 			trimmed.startsWith("command ")
@@ -761,7 +825,9 @@ function collectSemanticDeclarationInfo(source: string): SemanticDeclarationInfo
 								? "policy"
 								: trimmed.startsWith("view ")
 									? "view"
-									: trimmed.startsWith("route ")
+									: trimmed.startsWith("page ")
+										? "page"
+										: trimmed.startsWith("route ")
 										? "route"
 										: trimmed.startsWith("workflow ")
 											? "workflow"
@@ -771,7 +837,7 @@ function collectSemanticDeclarationInfo(source: string): SemanticDeclarationInfo
 			const body = collectSemanticBody(lines, index + 1);
 			const params = new Map<string, string>();
 			let outputName =
-				kind === "label" ? "label" : kind === "policy" ? "policy" : kind === "view" ? "view" : kind === "route" ? "route" : "result";
+				kind === "label" ? "label" : kind === "policy" ? "policy" : kind === "view" ? "view" : kind === "page" ? "page" : kind === "route" ? "route" : "result";
 			const effects: string[] = [];
 			for (const line of body.lines) {
 				if (line.startsWith("input ")) {
@@ -840,6 +906,7 @@ function collectCallableBindings(source: string): Map<string, string> {
 			declaration.kind === "action" ||
 			declaration.kind === "policy" ||
 			declaration.kind === "view" ||
+			declaration.kind === "page" ||
 			declaration.kind === "route" ||
 			declaration.kind === "workflow" ||
 			declaration.kind === "command"
@@ -870,7 +937,7 @@ function collectSemanticBody(lines: string[], start: number): { lines: string[];
 }
 
 function isSemanticTopLevel(line: string): boolean {
-	return /^(module|use|record|calculation|rule|label|external|action|policy|view|route|workflow|command|type|fn|let|var|import)\s+/.test(line);
+	return /^(module|use|record|calculation|rule|label|external|action|policy|view|page|route|workflow|command|type|fn|let|var|import)\s+/.test(line);
 }
 
 function isSemanticLoopBoundary(line: string): boolean {
@@ -973,7 +1040,7 @@ function toIdentifier(label: string): string {
 function semanticFunctionName(
 	label: string,
 	outputName: string,
-	kind: "calculation" | "rule" | "label" | "action" | "policy" | "view" | "route" | "workflow" | "command",
+	kind: "calculation" | "rule" | "label" | "action" | "policy" | "view" | "page" | "route" | "workflow" | "command",
 ): string {
 	const base = toIdentifier(label);
 	const suffix =
@@ -983,7 +1050,9 @@ function semanticFunctionName(
 				? "Policy"
 				: kind === "view"
 					? "View"
-					: kind === "route"
+					: kind === "page"
+						? "Page"
+						: kind === "route"
 						? "Route"
 						: kind === "workflow"
 							? "Workflow"

package/src/semantic/ast.ts

@@ -24,6 +24,7 @@ export type PointSemanticDeclaration =
 	| PointSemanticActionDeclaration
 	| PointSemanticPolicyDeclaration
 	| PointSemanticViewDeclaration
+	| PointSemanticPageDeclaration
 	| PointSemanticRouteDeclaration
 	| PointSemanticWorkflowDeclaration
 	| PointSemanticCommandDeclaration;
@@ -123,6 +124,16 @@ export interface PointSemanticViewDeclaration {
 	span?: PointSourceSpan;
 }
 
+export interface PointSemanticPageDeclaration {
+	kind: "page";
+	name: string;
+	inputs: PointSemanticBinding[];
+	title: PointSemanticExpression;
+	description?: PointSemanticExpression;
+	main: PointSemanticExpression;
+	span?: PointSourceSpan;
+}
+
 export interface PointSemanticRouteDeclaration {
 	kind: "route";
 	name: string;
@@ -182,7 +193,9 @@ export type PointSemanticPolicyStatement =
 
 export type PointSemanticViewStatement =
 	| { kind: "render"; value: PointSemanticExpression; span?: PointSourceSpan }
-	| { kind: "whenRender"; condition: PointSemanticExpression; value: PointSemanticExpression; span?: PointSourceSpan };
+	| { kind: "whenRender"; condition: PointSemanticExpression; value: PointSemanticExpression; span?: PointSourceSpan }
+	| { kind: "bindCheckbox"; label: string; target: PointSemanticExpression; span?: PointSourceSpan }
+	| { kind: "onChangeCall"; callback: string; span?: PointSourceSpan };
 
 export type PointSemanticRouteStatement = { kind: "return"; value: PointSemanticExpression; span?: PointSourceSpan };
 

package/src/semantic/callables.ts

@@ -4,6 +4,7 @@ const CALLABLE_KEYWORDS = [
 	"label",
 	"action",
 	"view",
+	"page",
 	"route",
 	"workflow",
 	"command",
@@ -47,5 +48,5 @@ function collectBody(lines: string[], start: number): { lines: string[]; next: n
 }
 
 function isTopLevel(line: string): boolean {
-	return /^(module|use|record|calculation|rule|label|external|action|policy|view|route|workflow|command)\s+/.test(line);
+	return /^(module|use|record|calculation|rule|label|external|action|policy|view|page|route|workflow|command)\s+/.test(line);
 }

package/src/semantic/context.ts

@@ -27,6 +27,7 @@ export type PointSemanticSymbolKind =
 	| "action"
 	| "policy"
 	| "view"
+	| "page"
 	| "route"
 	| "workflow"
 	| "command"
@@ -215,6 +216,15 @@ function callableDeclaration(declaration: PointSemanticDeclaration):
 	if (declaration.kind === "view" || declaration.kind === "route" || declaration.kind === "workflow" || declaration.kind === "command") {
 		return { kind: declaration.kind, name: declaration.name, inputs: declaration.inputs, output: declaration.output, declaration };
 	}
+	if (declaration.kind === "page") {
+		return {
+			kind: "page",
+			name: declaration.name,
+			inputs: declaration.inputs,
+			output: { name: "page", type: { kind: "typeRef", name: "Page", args: [] } },
+			declaration,
+		};
+	}
 	return null;
 }
 
@@ -313,7 +323,7 @@ function relatedRefsFor(symbol: PointSemanticSymbol, index: PointSemanticIndex):
 		const ownerPath = symbol.path.split(".").slice(0, 2).join(".");
 		return index.refs.filter((candidate) => candidate.path.startsWith(`${ownerPath}.`) && candidate.ref !== symbol.ref).map((candidate) => candidate.ref);
 	}
-	if (symbol.kind === "record" || symbol.kind === "calculation" || symbol.kind === "rule" || symbol.kind === "label" || symbol.kind === "action" || symbol.kind === "policy" || symbol.kind === "view" || symbol.kind === "route" || symbol.kind === "workflow" || symbol.kind === "command" || symbol.kind === "external") {
+	if (symbol.kind === "record" || symbol.kind === "calculation" || symbol.kind === "rule" || symbol.kind === "label" || symbol.kind === "action" || symbol.kind === "policy" || symbol.kind === "view" || symbol.kind === "page" || symbol.kind === "route" || symbol.kind === "workflow" || symbol.kind === "command" || symbol.kind === "external") {
 		return index.refs.filter((candidate) => candidate.path.startsWith(`${symbol.path}.`)).map((candidate) => candidate.ref);
 	}
 	return [];
@@ -332,6 +342,7 @@ function summaryFor(symbol: PointSemanticSymbol): 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 ${symbol.type}.`;
+	if (symbol.kind === "page") return `Semantic page ${symbol.name} returns a Next.js page shell (${symbol.type}).`;
 	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}.`;