rastack 0.0.47 → 0.0.49

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.49](https://github.com/theserverkid/reactapistack/compare/v0.0.48...v0.0.49) (2026-07-14)
+
+### [0.0.48](https://github.com/theserverkid/reactapistack/compare/v0.0.47...v0.0.48) (2026-07-13)
+
 ### [0.0.47](https://github.com/theserverkid/reactapistack/compare/v0.0.46...v0.0.47) (2026-07-13)
 
 ### [0.0.46](https://github.com/theserverkid/reactapistack/compare/v0.0.45...v0.0.46) (2026-07-13)

package/dist/compile/entities.d.ts

@@ -1,54 +1,5 @@
 import * as ts from "typescript";
 import { ResourceModel } from "./model";
-/**
- * Interface-driven resource inference — "the entities in the app are a list of
- * interfaces".
- *
- * Instead of (or alongside) the `resource()` DSL, an app can describe its data
- * as plain TypeScript interfaces and consume them through typed hooks. The
- * analyser works the resource graph out from the *usage*:
- *
- * 1. **Roots come from the hooks.** Every hook call that carries a type
- *    argument — `useEntityList<Airport>(…)`, `useQuery<Terminal>(…)` — marks
- *    the interface behind that type argument as an entity. An interface can
- *    also opt in explicitly with a `@rastackResource` JSDoc tag.
- * 2. **Datatypes come from the interfaces.** Each property's TypeScript type
- *    maps to a manifest scalar (`string` → string, `number` → float,
- *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
- *    type system with `DbConfig` brands from `rastack/types` —
- *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
- *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
- *    Optional / `| null` properties become nullable fields.
- * 3. **Foreign keys come from the type system.** A property whose type is
- *    another entity interface is a foreign key, and the referenced interface
- *    is pulled into the resource graph transitively — the closure of the
- *    hook-rooted interfaces is the app's resource set.
- * 4. **Circular dependencies are detected.** The FK graph is walked for
- *    cycles; a cycle is an *error* when every edge in it is required (no row
- *    could ever be inserted) and a *warning* when it is breakable through a
- *    nullable field (e.g. an optional self-referencing `manager`).
- *
- * ```ts
- * // entities/airports.ts
- * export interface Airport {
- *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
- *   name: string;
- * }
- * export interface Terminal {
- *   airport: Airport;   // FK — inferred from the property type
- *   label: string;
- * }
- *
- * // app/screen.tsx — the hook call is what roots the graph
- * const terminals = useEntityList<Terminal>("terminals");
- * // → resources: airports.terminal (root) + airports.airport (transitive)
- * ```
- *
- * Naming: `model` is the lower-camel interface name (a leading `I` prefix as
- * in generated `IFlight` interfaces is stripped, so hook usage of generated
- * types round-trips onto the same resource); `app` defaults to the defining
- * file's basename. Both are overridable with `@rastackApp` / `@rastackModel` tags.
- */
 export interface EntityDiagnostic {
     severity: "error" | "warning";
     message: string;

package/dist/compile/entities.js

@@ -43,17 +43,20 @@ function analyzeEntities(program, fileNames) {
     const diagnostics = [];
     const sourceFiles = (0, program_1.resourceSourceFiles)(program, fileNames);
     const scanned = new Set(sourceFiles.map((sf) => path.resolve(sf.fileName)));
-    // Every interface declared in the scanned files is a *candidate* entity.
+    // Every class/interface declared in the scanned files is a *candidate* entity.
     const candidates = new Set();
     for (const sf of sourceFiles) {
         ts.forEachChild(sf, function walk(node) {
             if (ts.isInterfaceDeclaration(node))
                 candidates.add(node);
+            if (ts.isClassDeclaration(node) && node.name)
+                candidates.add(node);
             ts.forEachChild(node, walk);
         });
     }
-    // 1. Roots: interfaces used as type arguments of hook calls, plus explicit
-    //    `@rastackResource` opt-ins.
+    // 1. Roots: declarations used as type arguments of hook calls, explicit
+    //    `@rastackResource` opt-ins, and plain data classes (declaring one *is*
+    //    the opt-in).
     const roots = [];
     const rooted = new Set();
     const addRoot = (decl) => {
@@ -66,7 +69,7 @@ function analyzeEntities(program, fileNames) {
         ts.forEachChild(sf, function walk(node) {
             if (ts.isCallExpression(node) && isHookCall(node)) {
                 for (const typeArg of node.typeArguments ?? []) {
-                    const decl = interfaceBehindTypeNode(typeArg, checker, scanned);
+                    const decl = entityBehindTypeNode(typeArg, checker, scanned);
                     if (decl && candidates.has(decl))
                         addRoot(decl);
                 }
@@ -77,9 +80,11 @@ function analyzeEntities(program, fileNames) {
     for (const decl of candidates) {
         if (jsdocTags(decl).has("rastackresource"))
             addRoot(decl);
+        else if (ts.isClassDeclaration(decl) && isDataClass(decl))
+            addRoot(decl);
     }
-    // 2. Transitive closure over FK references: an entity's interface-typed
-    //    property pulls the referenced interface in as an entity too.
+    // 2. Transitive closure over FK references: an entity's entity-typed
+    //    property pulls the referenced declaration in as an entity too.
     const propsByDecl = new Map();
     const analyzed = (decl) => {
         let props = propsByDecl.get(decl);
@@ -166,36 +171,93 @@ function isHookCall(call) {
             : undefined;
     return !!name && /^use[A-Z0-9_]/.test(name);
 }
-/** Resolve a type node to an interface declared in one of the scanned files. */
-function interfaceBehindTypeNode(node, checker, scanned) {
-    return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+/** Resolve a type node to a class/interface declared in a scanned file. */
+function entityBehindTypeNode(node, checker, scanned) {
+    return entityBehindType(checker.getTypeFromTypeNode(node), scanned);
 }
-function interfaceBehindType(type, scanned) {
+function entityBehindType(type, scanned) {
     const symbol = type.aliasSymbol ?? type.getSymbol();
     for (const decl of symbol?.declarations ?? []) {
-        if (ts.isInterfaceDeclaration(decl) &&
+        if ((ts.isInterfaceDeclaration(decl) ||
+            (ts.isClassDeclaration(decl) && decl.name)) &&
             scanned.has(path.resolve(decl.getSourceFile().fileName))) {
             return decl;
         }
     }
     return undefined;
 }
+/**
+ * A *plain data class* — the class-authored equivalent of a `resource()` call,
+ * so it roots itself. It must carry no heritage clause (a subclass of
+ * `React.Component` or a service base is app code, not a table), not be
+ * abstract, contain nothing but property declarations, and have at least one
+ * instance property. Anything richer can still opt in via a hook or the
+ * `@rastackResource` tag.
+ */
+function isDataClass(decl) {
+    if (decl.heritageClauses?.length)
+        return false;
+    if (ts.getCombinedModifierFlags(decl) &
+        (ts.ModifierFlags.Abstract | ts.ModifierFlags.Ambient)) {
+        return false;
+    }
+    let properties = 0;
+    for (const member of decl.members) {
+        if (!ts.isPropertyDeclaration(member))
+            return false; // method/ctor/accessor
+        if (ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static)
+            continue;
+        properties += 1;
+    }
+    return properties > 0;
+}
 function analyzeProperties(decl, checker, scanned) {
     const props = [];
     for (const member of decl.members) {
-        if (!ts.isPropertySignature(member) || !member.type)
+        let prop;
+        if (ts.isPropertySignature(member) && member.type) {
+            prop = member;
+        }
+        else if (ts.isPropertyDeclaration(member) &&
+            (member.type || member.initializer) &&
+            !ts.isPrivateIdentifier(member.name) &&
+            !(ts.getCombinedModifierFlags(member) &
+                (ts.ModifierFlags.Static |
+                    ts.ModifierFlags.Private |
+                    ts.ModifierFlags.Protected))) {
+            prop = member;
+        }
+        if (!prop)
             continue;
-        const name = ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)
-            ? member.name.text
+        const name = ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)
+            ? prop.name.text
             : undefined;
         if (!name)
             continue;
-        props.push(analyzeProperty(name, member, checker, scanned));
+        props.push(analyzeProperty(name, prop, checker, scanned));
     }
     return props;
 }
 function analyzeProperty(name, member, checker, scanned) {
     let nullable = !!member.questionToken;
+    // A class field with no annotation infers its (widened) type from the
+    // initializer — `region = "EU"` is a string column defaulting to "EU".
+    if (!member.type) {
+        const type = checker.getTypeAtLocation(member);
+        const base = classifyType(type, scanned);
+        if (base === undefined) {
+            return { name, nullable, skip: "unsupported type — skipped" };
+        }
+        if (typeof base !== "string")
+            return { name, nullable, target: base };
+        const config = configFromTags(jsdocTags(member));
+        if (config.default === undefined) {
+            const dflt = initializerDefault(member);
+            if (dflt !== undefined)
+                config.default = dflt;
+        }
+        return scalarProp(name, base, config, nullable);
+    }
     // Unwrap parens and unions: strip null/undefined (→ nullable), and require a
     // single remaining arm (unions of string literals collapse to `string`).
     let typeNode = unwrapParens(member.type);
@@ -219,7 +281,7 @@ function analyzeProperty(name, member, checker, scanned) {
     // but is intentionally not an error. Arrays of scalars have no manifest shape.
     const element = arrayElement(typeNode);
     if (element) {
-        if (interfaceBehindTypeNode(element, checker, scanned)) {
+        if (entityBehindTypeNode(element, checker, scanned)) {
             return { name, nullable, inverse: true };
         }
         return { name, nullable, skip: "array fields are not supported — skipped" };
@@ -230,19 +292,44 @@ function analyzeProperty(name, member, checker, scanned) {
         return { name, nullable, skip: "unsupported type — skipped" };
     }
     if (typeof base !== "string") {
-        return { name, nullable, target: base }; // entity interface → FK
+        return { name, nullable, target: base }; // entity class/interface → FK
     }
     const config = {
         ...configFromTags(jsdocTags(member)),
         ...configFromType(type, checker, member),
     };
+    if (config.default === undefined) {
+        const dflt = initializerDefault(member);
+        if (dflt !== undefined)
+            config.default = dflt;
+    }
     return scalarProp(name, base, config, nullable);
 }
+/** The literal value of a class field's initializer, used as the default. */
+function initializerDefault(member) {
+    if (!ts.isPropertyDeclaration(member) || !member.initializer)
+        return undefined;
+    const init = member.initializer;
+    if (ts.isStringLiteralLike(init))
+        return init.text;
+    if (ts.isNumericLiteral(init))
+        return Number(init.text);
+    if (ts.isPrefixUnaryExpression(init) &&
+        init.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(init.operand)) {
+        return -Number(init.operand.text);
+    }
+    if (init.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (init.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
 /**
- * What a property type *is*: a manifest scalar, an entity interface (→ FK), or
- * unsupported. Intersections classify by their first classifiable constituent,
- * which is what lets `DbConfig` brands ride along — `string & Unique` is a
- * string; the brand carries configuration, not a datatype.
+ * What a property type *is*: a manifest scalar, an entity class/interface
+ * (→ FK), or unsupported. Intersections classify by their first classifiable
+ * constituent, which is what lets `DbConfig` brands ride along — `string &
+ * Unique` is a string; the brand carries configuration, not a datatype.
  */
 function classifyType(type, scanned) {
     if (type.flags & ts.TypeFlags.StringLike)
@@ -261,7 +348,7 @@ function classifyType(type, scanned) {
     }
     if (type.getProperty("__rastackDb"))
         return undefined; // a bare config brand
-    const decl = interfaceBehindType(type, scanned);
+    const decl = entityBehindType(type, scanned);
     if (decl)
         return decl;
     if (type.getSymbol()?.getName() === "Date")
@@ -390,6 +477,7 @@ function arrayElement(node) {
 }
 function entityNaming(decl) {
     const tags = jsdocTags(decl);
+    // Class candidates are only ever collected with a name (see analyzeEntities).
     const raw = decl.name.text;
     // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
     // so hook usage of generated types resolves to the same resource.

package/dist/compile/index.d.ts

@@ -19,7 +19,7 @@ export interface CompileResult {
  * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
  * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
  * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
- * interface-driven entity graph; co-located helpers are harmless.
+ * class/interface entity graph; co-located helpers are harmless.
  */
 export declare function resolveResourceFiles(input: string): string[];
 export interface ProjectAnalysis {

package/dist/compile/index.js

@@ -77,7 +77,7 @@ const IGNORE_DIRS = new Set([
  * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
  * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
  * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
- * interface-driven entity graph; co-located helpers are harmless.
+ * class/interface entity graph; co-located helpers are harmless.
  */
 function resolveResourceFiles(input) {
     const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;

package/dist/compile/program.js

@@ -55,7 +55,7 @@ function createProgram(fileNames) {
         esModuleInterop: true,
         noEmit: true,
         // `.tsx` app files are scanned for the typed hook calls that root the
-        // interface-driven entity graph.
+        // class/interface entity graph.
         jsx: ts.JsxEmit.ReactJSX,
         baseUrl: process.cwd(),
         paths: {

package/dist/define/db.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type-level column configuration for interface-driven entities.
+ * Type-level column configuration for class- and interface-driven entities.
  *
  * Interface entities are plain TypeScript, so their column constraints are
  * expressed *in the type system*: intersect a property type with one or more

package/dist/define/db.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Type-level column configuration for interface-driven entities.
+ * Type-level column configuration for class- and interface-driven entities.
  *
  * Interface entities are plain TypeScript, so their column constraints are
  * expressed *in the type system*: intersect a property type with one or more

package/dist/rastack-admin.d.ts

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
+ *   • the compiled `schema.rastack.json` / `openapi.json`,
+ *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 export {};

package/dist/rastack-admin.js

@@ -1,16 +1,23 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
+ *   • the compiled `schema.rastack.json` / `openapi.json`,
+ *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -48,6 +55,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
 const path = __importStar(require("path"));
 const harness_1 = require("./dev/harness");
 const HERE = __dirname; // dist/ when installed — the bundle lives beside us.
@@ -59,6 +67,42 @@ function compile(resourcesDir, outDir) {
         return false;
     return fs.existsSync(path.join(outDir, "schema.rastack.json"));
 }
+/** Locate the prebuilt wasm bundle dir shipped in the package (no cargo fallback). */
+function resolveWasmDir() {
+    for (const dir of (0, harness_1.wasmBundleCandidates)(HERE)) {
+        if (fs.existsSync(path.join(dir, harness_1.WASM_ENTRY)))
+            return dir;
+    }
+    return null;
+}
+/** Serve one file if it exists and stays within `root`; else 404/403. */
+function serveUnder(res, root, relPath) {
+    const safeRoot = path.resolve(root);
+    const rel = decodeURIComponent(relPath).replace(/^\/+/, "");
+    const target = path.resolve(safeRoot, rel);
+    // Path-traversal guard: the resolved target must stay inside the root.
+    if (target !== safeRoot && !target.startsWith(safeRoot + path.sep)) {
+        res.writeHead(403).end("Forbidden");
+        return;
+    }
+    fs.readFile(target, (err, data) => {
+        if (err) {
+            res.writeHead(404).end("Not found");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": (0, harness_1.contentType)(target) }).end(data);
+    });
+}
+/** Serve an exact file (no traversal concern — a fixed internal artifact). */
+function serveFile(res, file) {
+    fs.readFile(file, (err, data) => {
+        if (err) {
+            res.writeHead(404).end("Not found");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": (0, harness_1.contentType)(file) }).end(data);
+    });
+}
 /** Best-effort open the default browser at `url`. */
 function openBrowser(url) {
     const cmd = process.platform === "darwin"
@@ -81,47 +125,48 @@ function main(argv) {
         console.error("  ✗ compile failed — fix the resource graph and re-run.");
         process.exit(1);
     }
-    const bundle = path.join(HERE, "admin.js");
-    if (!fs.existsSync(bundle)) {
-        console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
+    const wasmDir = resolveWasmDir();
+    if (!wasmDir) {
+        console.error("\n  ✗ No prebuilt WASM engine found in this rastack install.\n" +
+            "    Update rastack to pull the prebuilt bundle:\n" +
+            "      rastack update\n");
         process.exit(1);
     }
-    const repoRoot = path.resolve(HERE, "..", "..");
-    const binary = process.env.RASTACK_SERVER_BIN ||
-        path.join(repoRoot, "rust", "target", "release", "rastack-server");
-    const manifest = path.join(args.outDir, "schema.rastack.json");
-    const serverArgs = [
-        "admin",
-        "--manifest",
-        manifest,
-        "--warehouse",
-        args.warehouseDir,
-        "--addr",
-        `127.0.0.1:${args.port}`,
-        // Local dev context: the admin runs unauthenticated, exactly like the old
-        // native admin. Production admins run the server with --jwks/--admin-group.
-        "--insecure-dev-auth",
-    ];
-    const url = `http://127.0.0.1:${args.port}/admin/`;
-    // The server serves the React bundle from here; hand the path via env so the
-    // Rust side stays free of JS-toolchain knowledge.
-    const child = (0, child_process_1.spawn)(binary, serverArgs, {
-        stdio: "inherit",
-        env: { ...process.env, RASTACK_ADMIN_ASSETS: HERE },
-    });
-    child.on("error", () => {
-        console.error(`  ✗ Could not run the Rust server (${binary}). Build it first:\n` +
-            `      cd rust && cargo build --release\n`);
+    const adminBundle = path.join(HERE, "admin.js");
+    if (!fs.existsSync(adminBundle)) {
+        console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
         process.exit(1);
+    }
+    const server = http.createServer((req, res) => {
+        const url = (req.url || "/").split("?")[0];
+        if (req.method !== "GET") {
+            res.writeHead(405).end("Method not allowed");
+            return;
+        }
+        if (url === "/" || url === "/index.html") {
+            res
+                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                .end((0, harness_1.renderShell)("React API Stack — admin"));
+            return;
+        }
+        if (url === "/dev/admin.js")
+            return serveFile(res, adminBundle);
+        if (url.startsWith("/wasm/"))
+            return serveUnder(res, wasmDir, url.slice("/wasm/".length));
+        if (url === "/schema.rastack.json" || url === "/openapi.json")
+            return serveUnder(res, args.outDir, path.basename(url));
+        if (url.startsWith("/data/warehouse/"))
+            return serveUnder(res, args.warehouseDir, url.slice("/data/warehouse/".length));
+        res.writeHead(404).end("Not found");
     });
-    child.on("exit", (code) => process.exit(code ?? 0));
-    // Give the server a moment to bind, then print + open.
-    setTimeout(() => {
+    server.listen(args.port, () => {
+        const url = `http://localhost:${args.port}`;
+        console.log(`  ✓ WASM engine: ${path.relative(process.cwd(), wasmDir)}`);
         console.log(`\n  ▸ ${url}\n`);
         console.log("  Press Ctrl+C to stop.\n");
         if (args.open)
             openBrowser(url);
-    }, 700);
+    });
 }
 if (require.main === module) {
     main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",

package/src/compile/entities.ts

@@ -4,55 +4,67 @@ import { FieldModel, RelationModel, ResourceModel, ScalarType } from "./model";
 import { resourceSourceFiles } from "./program";
 
 /**
- * Interface-driven resource inference — "the entities in the app are a list of
- * interfaces".
+ * Type-driven resource inference — "the entities in the app are a list of
+ * plain TypeScript types".
  *
  * Instead of (or alongside) the `resource()` DSL, an app can describe its data
- * as plain TypeScript interfaces and consume them through typed hooks. The
- * analyser works the resource graph out from the *usage*:
+ * as plain TypeScript **classes or interfaces** and consume them through typed
+ * hooks. The analyser works the resource graph out from the *usage*:
  *
  * 1. **Roots come from the hooks.** Every hook call that carries a type
  *    argument — `useEntityList<Airport>(…)`, `useQuery<Terminal>(…)` — marks
- *    the interface behind that type argument as an entity. An interface can
- *    also opt in explicitly with a `@rastackResource` JSDoc tag.
- * 2. **Datatypes come from the interfaces.** Each property's TypeScript type
+ *    the class/interface behind that type argument as an entity. A declaration
+ *    can also opt in explicitly with a `@rastackResource` JSDoc tag. And a
+ *    **plain data class** — no heritage clause, no methods or constructor,
+ *    only property declarations — is an entity by virtue of being declared:
+ *    writing `export class Airport { code: string }` is the whole authoring
+ *    step, no DSL and no tag required. (Interfaces are ubiquitous in app code,
+ *    so they still need a hook or a tag to root; an entity-shaped class is a
+ *    deliberate declaration.)
+ * 2. **Datatypes come from the properties.** Each property's TypeScript type
  *    maps to a manifest scalar (`string` → string, `number` → float,
  *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
  *    type system with `DbConfig` brands from `rastack/types` —
  *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
  *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
- *    Optional / `| null` properties become nullable fields.
+ *    Optional / `| null` properties become nullable fields. On a class, a
+ *    literal property initializer (`status = "scheduled"`) doubles as the
+ *    column default, and the property type may be inferred from it.
  * 3. **Foreign keys come from the type system.** A property whose type is
- *    another entity interface is a foreign key, and the referenced interface
- *    is pulled into the resource graph transitively — the closure of the
- *    hook-rooted interfaces is the app's resource set.
+ *    another entity class/interface is a foreign key, and the referenced
+ *    declaration is pulled into the resource graph transitively — the closure
+ *    of the rooted declarations is the app's resource set.
  * 4. **Circular dependencies are detected.** The FK graph is walked for
  *    cycles; a cycle is an *error* when every edge in it is required (no row
  *    could ever be inserted) and a *warning* when it is breakable through a
  *    nullable field (e.g. an optional self-referencing `manager`).
  *
  * ```ts
- * // entities/airports.ts
- * export interface Airport {
+ * // entities/airports.ts — plain data classes are entities by declaration
+ * export class Airport {
  *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
  *   name: string;
  * }
- * export interface Terminal {
+ * export class Terminal {
  *   airport: Airport;   // FK — inferred from the property type
  *   label: string;
  * }
  *
+ * // interfaces root through usage instead:
  * // app/screen.tsx — the hook call is what roots the graph
  * const terminals = useEntityList<Terminal>("terminals");
- * // → resources: airports.terminal (root) + airports.airport (transitive)
  * ```
  *
- * Naming: `model` is the lower-camel interface name (a leading `I` prefix as
- * in generated `IFlight` interfaces is stripped, so hook usage of generated
- * types round-trips onto the same resource); `app` defaults to the defining
- * file's basename. Both are overridable with `@rastackApp` / `@rastackModel` tags.
+ * Naming: `model` is the lower-camel class/interface name (a leading `I`
+ * prefix as in generated `IFlight` interfaces is stripped, so hook usage of
+ * generated types round-trips onto the same resource); `app` defaults to the
+ * defining file's basename. Both are overridable with `@rastackApp` /
+ * `@rastackModel` tags.
  */
 
+/** An entity can be declared as an interface or as a (named) class. */
+type EntityDecl = ts.InterfaceDeclaration | ts.ClassDeclaration;
+
 export interface EntityDiagnostic {
   severity: "error" | "warning";
   message: string;
@@ -72,20 +84,22 @@ export function analyzeEntities(
   const sourceFiles = resourceSourceFiles(program, fileNames);
   const scanned = new Set(sourceFiles.map((sf) => path.resolve(sf.fileName)));
 
-  // Every interface declared in the scanned files is a *candidate* entity.
-  const candidates = new Set<ts.InterfaceDeclaration>();
+  // Every class/interface declared in the scanned files is a *candidate* entity.
+  const candidates = new Set<EntityDecl>();
   for (const sf of sourceFiles) {
     ts.forEachChild(sf, function walk(node) {
       if (ts.isInterfaceDeclaration(node)) candidates.add(node);
+      if (ts.isClassDeclaration(node) && node.name) candidates.add(node);
       ts.forEachChild(node, walk);
     });
   }
 
-  // 1. Roots: interfaces used as type arguments of hook calls, plus explicit
-  //    `@rastackResource` opt-ins.
-  const roots: ts.InterfaceDeclaration[] = [];
-  const rooted = new Set<ts.InterfaceDeclaration>();
-  const addRoot = (decl: ts.InterfaceDeclaration) => {
+  // 1. Roots: declarations used as type arguments of hook calls, explicit
+  //    `@rastackResource` opt-ins, and plain data classes (declaring one *is*
+  //    the opt-in).
+  const roots: EntityDecl[] = [];
+  const rooted = new Set<EntityDecl>();
+  const addRoot = (decl: EntityDecl) => {
     if (!rooted.has(decl)) {
       rooted.add(decl);
       roots.push(decl);
@@ -95,7 +109,7 @@ export function analyzeEntities(
     ts.forEachChild(sf, function walk(node) {
       if (ts.isCallExpression(node) && isHookCall(node)) {
         for (const typeArg of node.typeArguments ?? []) {
-          const decl = interfaceBehindTypeNode(typeArg, checker, scanned);
+          const decl = entityBehindTypeNode(typeArg, checker, scanned);
           if (decl && candidates.has(decl)) addRoot(decl);
         }
       }
@@ -104,12 +118,13 @@ export function analyzeEntities(
   }
   for (const decl of candidates) {
     if (jsdocTags(decl).has("rastackresource")) addRoot(decl);
+    else if (ts.isClassDeclaration(decl) && isDataClass(decl)) addRoot(decl);
   }
 
-  // 2. Transitive closure over FK references: an entity's interface-typed
-  //    property pulls the referenced interface in as an entity too.
-  const propsByDecl = new Map<ts.InterfaceDeclaration, PropInfo[]>();
-  const analyzed = (decl: ts.InterfaceDeclaration): PropInfo[] => {
+  // 2. Transitive closure over FK references: an entity's entity-typed
+  //    property pulls the referenced declaration in as an entity too.
+  const propsByDecl = new Map<EntityDecl, PropInfo[]>();
+  const analyzed = (decl: EntityDecl): PropInfo[] => {
     let props = propsByDecl.get(decl);
     if (!props) {
       props = analyzeProperties(decl, checker, scanned);
@@ -118,8 +133,8 @@ export function analyzeEntities(
     return props;
   };
 
-  const included: ts.InterfaceDeclaration[] = [];
-  const seen = new Set<ts.InterfaceDeclaration>();
+  const included: EntityDecl[] = [];
+  const seen = new Set<EntityDecl>();
   const queue = [...roots];
   while (queue.length) {
     const decl = queue.shift()!;
@@ -200,23 +215,24 @@ function isHookCall(call: ts.CallExpression): boolean {
   return !!name && /^use[A-Z0-9_]/.test(name);
 }
 
-/** Resolve a type node to an interface declared in one of the scanned files. */
-function interfaceBehindTypeNode(
+/** Resolve a type node to a class/interface declared in a scanned file. */
+function entityBehindTypeNode(
   node: ts.TypeNode,
   checker: ts.TypeChecker,
   scanned: Set<string>,
-): ts.InterfaceDeclaration | undefined {
-  return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+): EntityDecl | undefined {
+  return entityBehindType(checker.getTypeFromTypeNode(node), scanned);
 }
 
-function interfaceBehindType(
+function entityBehindType(
   type: ts.Type,
   scanned: Set<string>,
-): ts.InterfaceDeclaration | undefined {
+): EntityDecl | undefined {
   const symbol = type.aliasSymbol ?? type.getSymbol();
   for (const decl of symbol?.declarations ?? []) {
     if (
-      ts.isInterfaceDeclaration(decl) &&
+      (ts.isInterfaceDeclaration(decl) ||
+        (ts.isClassDeclaration(decl) && decl.name)) &&
       scanned.has(path.resolve(decl.getSourceFile().fileName))
     ) {
       return decl;
@@ -225,6 +241,31 @@ function interfaceBehindType(
   return undefined;
 }
 
+/**
+ * A *plain data class* — the class-authored equivalent of a `resource()` call,
+ * so it roots itself. It must carry no heritage clause (a subclass of
+ * `React.Component` or a service base is app code, not a table), not be
+ * abstract, contain nothing but property declarations, and have at least one
+ * instance property. Anything richer can still opt in via a hook or the
+ * `@rastackResource` tag.
+ */
+function isDataClass(decl: ts.ClassDeclaration): boolean {
+  if (decl.heritageClauses?.length) return false;
+  if (
+    ts.getCombinedModifierFlags(decl) &
+    (ts.ModifierFlags.Abstract | ts.ModifierFlags.Ambient)
+  ) {
+    return false;
+  }
+  let properties = 0;
+  for (const member of decl.members) {
+    if (!ts.isPropertyDeclaration(member)) return false; // method/ctor/accessor
+    if (ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static) continue;
+    properties += 1;
+  }
+  return properties > 0;
+}
+
 // -- property analysis --------------------------------------------------------
 
 interface PropInfo {
@@ -232,43 +273,79 @@ interface PropInfo {
   nullable: boolean;
   /** Scalar field (mutually exclusive with `target`). */
   field?: FieldModel;
-  /** FK target interface (relation resolved after naming). */
-  target?: ts.InterfaceDeclaration;
+  /** FK target declaration (relation resolved after naming). */
+  target?: EntityDecl;
   /** `Entity[]` — the reverse side of a FK; contributes no column. */
   inverse?: boolean;
   /** Unsupported type — reported as a warning and skipped. */
   skip?: string;
 }
 
+/** A column-shaped member: an interface property or a class instance field. */
+type EntityProp = ts.PropertySignature | ts.PropertyDeclaration;
+
 function analyzeProperties(
-  decl: ts.InterfaceDeclaration,
+  decl: EntityDecl,
   checker: ts.TypeChecker,
   scanned: Set<string>,
 ): PropInfo[] {
   const props: PropInfo[] = [];
   for (const member of decl.members) {
-    if (!ts.isPropertySignature(member) || !member.type) continue;
+    let prop: EntityProp | undefined;
+    if (ts.isPropertySignature(member) && member.type) {
+      prop = member;
+    } else if (
+      ts.isPropertyDeclaration(member) &&
+      (member.type || member.initializer) &&
+      !ts.isPrivateIdentifier(member.name) &&
+      !(
+        ts.getCombinedModifierFlags(member) &
+        (ts.ModifierFlags.Static |
+          ts.ModifierFlags.Private |
+          ts.ModifierFlags.Protected)
+      )
+    ) {
+      prop = member;
+    }
+    if (!prop) continue;
     const name =
-      ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)
-        ? member.name.text
+      ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)
+        ? prop.name.text
         : undefined;
     if (!name) continue;
-    props.push(analyzeProperty(name, member, checker, scanned));
+    props.push(analyzeProperty(name, prop, checker, scanned));
   }
   return props;
 }
 
 function analyzeProperty(
   name: string,
-  member: ts.PropertySignature,
+  member: EntityProp,
   checker: ts.TypeChecker,
   scanned: Set<string>,
 ): PropInfo {
   let nullable = !!member.questionToken;
 
+  // A class field with no annotation infers its (widened) type from the
+  // initializer — `region = "EU"` is a string column defaulting to "EU".
+  if (!member.type) {
+    const type = checker.getTypeAtLocation(member);
+    const base = classifyType(type, scanned);
+    if (base === undefined) {
+      return { name, nullable, skip: "unsupported type — skipped" };
+    }
+    if (typeof base !== "string") return { name, nullable, target: base };
+    const config = configFromTags(jsdocTags(member));
+    if (config.default === undefined) {
+      const dflt = initializerDefault(member);
+      if (dflt !== undefined) config.default = dflt;
+    }
+    return scalarProp(name, base, config, nullable);
+  }
+
   // Unwrap parens and unions: strip null/undefined (→ nullable), and require a
   // single remaining arm (unions of string literals collapse to `string`).
-  let typeNode = unwrapParens(member.type!);
+  let typeNode = unwrapParens(member.type);
   if (ts.isUnionTypeNode(typeNode)) {
     const arms = typeNode.types.filter((t) => {
       const isNullish =
@@ -290,7 +367,7 @@ function analyzeProperty(
   // but is intentionally not an error. Arrays of scalars have no manifest shape.
   const element = arrayElement(typeNode);
   if (element) {
-    if (interfaceBehindTypeNode(element, checker, scanned)) {
+    if (entityBehindTypeNode(element, checker, scanned)) {
       return { name, nullable, inverse: true };
     }
     return { name, nullable, skip: "array fields are not supported — skipped" };
@@ -302,26 +379,50 @@ function analyzeProperty(
     return { name, nullable, skip: "unsupported type — skipped" };
   }
   if (typeof base !== "string") {
-    return { name, nullable, target: base }; // entity interface → FK
+    return { name, nullable, target: base }; // entity class/interface → FK
   }
 
   const config = {
     ...configFromTags(jsdocTags(member)),
     ...configFromType(type, checker, member),
   };
+  if (config.default === undefined) {
+    const dflt = initializerDefault(member);
+    if (dflt !== undefined) config.default = dflt;
+  }
   return scalarProp(name, base, config, nullable);
 }
 
+/** The literal value of a class field's initializer, used as the default. */
+function initializerDefault(
+  member: EntityProp,
+): string | number | boolean | undefined {
+  if (!ts.isPropertyDeclaration(member) || !member.initializer) return undefined;
+  const init = member.initializer;
+  if (ts.isStringLiteralLike(init)) return init.text;
+  if (ts.isNumericLiteral(init)) return Number(init.text);
+  if (
+    ts.isPrefixUnaryExpression(init) &&
+    init.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(init.operand)
+  ) {
+    return -Number(init.operand.text);
+  }
+  if (init.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (init.kind === ts.SyntaxKind.FalseKeyword) return false;
+  return undefined;
+}
+
 /**
- * What a property type *is*: a manifest scalar, an entity interface (→ FK), or
- * unsupported. Intersections classify by their first classifiable constituent,
- * which is what lets `DbConfig` brands ride along — `string & Unique` is a
- * string; the brand carries configuration, not a datatype.
+ * What a property type *is*: a manifest scalar, an entity class/interface
+ * (→ FK), or unsupported. Intersections classify by their first classifiable
+ * constituent, which is what lets `DbConfig` brands ride along — `string &
+ * Unique` is a string; the brand carries configuration, not a datatype.
  */
 function classifyType(
   type: ts.Type,
   scanned: Set<string>,
-): ScalarType | ts.InterfaceDeclaration | undefined {
+): ScalarType | EntityDecl | undefined {
   if (type.flags & ts.TypeFlags.StringLike) return "string";
   if (type.flags & ts.TypeFlags.NumberLike) return "float";
   if (type.flags & ts.TypeFlags.BooleanLike) return "bool";
@@ -333,7 +434,7 @@ function classifyType(
     return undefined;
   }
   if (type.getProperty("__rastackDb")) return undefined; // a bare config brand
-  const decl = interfaceBehindType(type, scanned);
+  const decl = entityBehindType(type, scanned);
   if (decl) return decl;
   if (type.getSymbol()?.getName() === "Date") return "datetime";
   return undefined;
@@ -476,9 +577,10 @@ interface EntityNaming {
   permission?: ResourceModel["permission"];
 }
 
-function entityNaming(decl: ts.InterfaceDeclaration): EntityNaming {
+function entityNaming(decl: EntityDecl): EntityNaming {
   const tags = jsdocTags(decl);
-  const raw = decl.name.text;
+  // Class candidates are only ever collected with a name (see analyzeEntities).
+  const raw = decl.name!.text;
   // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
   // so hook usage of generated types resolves to the same resource.
   const stripped = /^I[A-Z]/.test(raw) ? raw.slice(1) : raw;

package/src/compile/index.ts

@@ -39,7 +39,7 @@ const IGNORE_DIRS = new Set([
  * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
  * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
  * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
- * interface-driven entity graph; co-located helpers are harmless.
+ * class/interface entity graph; co-located helpers are harmless.
  */
 export function resolveResourceFiles(input: string): string[] {
   const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;

package/src/compile/program.ts

@@ -20,7 +20,7 @@ export function createProgram(fileNames: string[]): ts.Program {
     esModuleInterop: true,
     noEmit: true,
     // `.tsx` app files are scanned for the typed hook calls that root the
-    // interface-driven entity graph.
+    // class/interface entity graph.
     jsx: ts.JsxEmit.ReactJSX,
     baseUrl: process.cwd(),
     paths: {

package/src/define/db.ts

@@ -1,5 +1,5 @@
 /**
- * Type-level column configuration for interface-driven entities.
+ * Type-level column configuration for class- and interface-driven entities.
  *
  * Interface entities are plain TypeScript, so their column constraints are
  * expressed *in the type system*: intersect a property type with one or more

package/src/rastack-admin.ts

@@ -1,22 +1,36 @@
 #!/usr/bin/env node
 
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
+ *   • the compiled `schema.rastack.json` / `openapi.json`,
+ *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 
-import { execFileSync, spawn, spawnSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import * as fs from "fs";
+import * as http from "http";
 import * as path from "path";
-import { parseAdminArgs } from "./dev/harness";
+import {
+  WASM_ENTRY,
+  contentType,
+  parseAdminArgs,
+  renderShell,
+  wasmBundleCandidates,
+} from "./dev/harness";
 
 const HERE = __dirname; // dist/ when installed — the bundle lives beside us.
 
@@ -32,6 +46,48 @@ function compile(resourcesDir: string, outDir: string): boolean {
   return fs.existsSync(path.join(outDir, "schema.rastack.json"));
 }
 
+/** Locate the prebuilt wasm bundle dir shipped in the package (no cargo fallback). */
+function resolveWasmDir(): string | null {
+  for (const dir of wasmBundleCandidates(HERE)) {
+    if (fs.existsSync(path.join(dir, WASM_ENTRY))) return dir;
+  }
+  return null;
+}
+
+/** Serve one file if it exists and stays within `root`; else 404/403. */
+function serveUnder(
+  res: http.ServerResponse,
+  root: string,
+  relPath: string,
+): void {
+  const safeRoot = path.resolve(root);
+  const rel = decodeURIComponent(relPath).replace(/^\/+/, "");
+  const target = path.resolve(safeRoot, rel);
+  // Path-traversal guard: the resolved target must stay inside the root.
+  if (target !== safeRoot && !target.startsWith(safeRoot + path.sep)) {
+    res.writeHead(403).end("Forbidden");
+    return;
+  }
+  fs.readFile(target, (err, data) => {
+    if (err) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": contentType(target) }).end(data);
+  });
+}
+
+/** Serve an exact file (no traversal concern — a fixed internal artifact). */
+function serveFile(res: http.ServerResponse, file: string): void {
+  fs.readFile(file, (err, data) => {
+    if (err) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": contentType(file) }).end(data);
+  });
+}
+
 /** Best-effort open the default browser at `url`. */
 function openBrowser(url: string): void {
   const cmd =
@@ -57,54 +113,57 @@ function main(argv: string[]): void {
     process.exit(1);
   }
 
-  const bundle = path.join(HERE, "admin.js");
-  if (!fs.existsSync(bundle)) {
-    console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
+  const wasmDir = resolveWasmDir();
+  if (!wasmDir) {
+    console.error(
+      "\n  ✗ No prebuilt WASM engine found in this rastack install.\n" +
+        "    Update rastack to pull the prebuilt bundle:\n" +
+        "      rastack update\n",
+    );
     process.exit(1);
   }
 
-  const repoRoot = path.resolve(HERE, "..", "..");
-  const binary =
-    process.env.RASTACK_SERVER_BIN ||
-    path.join(repoRoot, "rust", "target", "release", "rastack-server");
-
-  const manifest = path.join(args.outDir, "schema.rastack.json");
-  const serverArgs = [
-    "admin",
-    "--manifest",
-    manifest,
-    "--warehouse",
-    args.warehouseDir,
-    "--addr",
-    `127.0.0.1:${args.port}`,
-    // Local dev context: the admin runs unauthenticated, exactly like the old
-    // native admin. Production admins run the server with --jwks/--admin-group.
-    "--insecure-dev-auth",
-  ];
-
-  const url = `http://127.0.0.1:${args.port}/admin/`;
-  // The server serves the React bundle from here; hand the path via env so the
-  // Rust side stays free of JS-toolchain knowledge.
-  const child = spawn(binary, serverArgs, {
-    stdio: "inherit",
-    env: { ...process.env, RASTACK_ADMIN_ASSETS: HERE },
-  });
-
-  child.on("error", () => {
+  const adminBundle = path.join(HERE, "admin.js");
+  if (!fs.existsSync(adminBundle)) {
     console.error(
-      `  ✗ Could not run the Rust server (${binary}). Build it first:\n` +
-        `      cd rust && cargo build --release\n`,
+      "  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.",
     );
     process.exit(1);
+  }
+
+  const server = http.createServer((req, res) => {
+    const url = (req.url || "/").split("?")[0];
+    if (req.method !== "GET") {
+      res.writeHead(405).end("Method not allowed");
+      return;
+    }
+    if (url === "/" || url === "/index.html") {
+      res
+        .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+        .end(renderShell("React API Stack — admin"));
+      return;
+    }
+    if (url === "/dev/admin.js") return serveFile(res, adminBundle);
+    if (url.startsWith("/wasm/"))
+      return serveUnder(res, wasmDir, url.slice("/wasm/".length));
+    if (url === "/schema.rastack.json" || url === "/openapi.json")
+      return serveUnder(res, args.outDir, path.basename(url));
+    if (url.startsWith("/data/warehouse/"))
+      return serveUnder(
+        res,
+        args.warehouseDir,
+        url.slice("/data/warehouse/".length),
+      );
+    res.writeHead(404).end("Not found");
   });
-  child.on("exit", (code) => process.exit(code ?? 0));
 
-  // Give the server a moment to bind, then print + open.
-  setTimeout(() => {
+  server.listen(args.port, () => {
+    const url = `http://localhost:${args.port}`;
+    console.log(`  ✓ WASM engine: ${path.relative(process.cwd(), wasmDir)}`);
     console.log(`\n  ▸ ${url}\n`);
     console.log("  Press Ctrl+C to stop.\n");
     if (args.open) openBrowser(url);
-  }, 700);
+  });
 }
 
 if (require.main === module) {

package/test/entities.spec.ts

@@ -16,6 +16,7 @@ import {
  */
 const workRoot = join(__dirname, "entities-fixtures");
 const appDir = join(workRoot, "app");
+const classesDir = join(workRoot, "classes");
 const cycleDir = join(workRoot, "cycles");
 const hardCycleDir = join(workRoot, "hard-cycles");
 const mixedDir = join(workRoot, "mixed");
@@ -150,6 +151,39 @@ declare function useEntity<T>(name: string): T;
 export const a = useEntity<Airport>("airport");
 `;
 
+const CLASSES_TS = `
+import { MaxLength, Unique } from "rastack/types";
+
+/** @rastackSearch code,name */
+export class Airport {
+  code!: string & Unique & MaxLength<3>;
+  /** @maxLength 120 */
+  name!: string;
+  region = "EU";        // initializer → type inferred, value is the default
+  active = true;
+  /** @int */
+  gates = 0;
+}
+
+export class Terminal {
+  airport!: Airport;    // FK — inferred from the property type
+  /** @maxLength 20 */
+  label!: string;
+  opened?: Date;
+  static kind = "terminal";        // not a column
+  private secret!: string;         // not a column
+}
+
+/** Not a plain data class — a method means it must opt in explicitly. */
+export class BoardingService {
+  queue: string[] = [];
+  board(): void {}
+}
+
+/** Heritage means app code, not a table. */
+export class SplashScreen extends BoardingService {}
+`;
+
 function findResource(
   resources: ResourceModel[],
   app: string,
@@ -166,6 +200,8 @@ beforeAll(() => {
   writeFileSync(join(appDir, "flights.ts"), FLIGHTS_TS);
   writeFileSync(join(appDir, "passengers.ts"), PASSENGERS_TS);
   writeFileSync(join(appDir, "screens.tsx"), SCREENS_TSX);
+  mkdirSync(classesDir, { recursive: true });
+  writeFileSync(join(classesDir, "airports.ts"), CLASSES_TS);
   mkdirSync(cycleDir, { recursive: true });
   writeFileSync(join(cycleDir, "org.ts"), SOFT_CYCLE_TS);
   mkdirSync(hardCycleDir, { recursive: true });
@@ -307,6 +343,69 @@ describe("interface entities — FK inference", () => {
   });
 });
 
+describe("class entities — plain data classes", () => {
+  it("roots a plain data class by declaration — no hook, tag, or DSL needed", () => {
+    const { resources } = analyzeProject(classesDir);
+    const keys = resources.map((r) => `${r.app}.${r.model}`);
+    expect(keys).toContain("airports.airport");
+    expect(keys).toContain("airports.terminal");
+  });
+
+  it("does not root classes with methods or heritage clauses", () => {
+    const { resources } = analyzeProject(classesDir);
+    const keys = resources.map((r) => `${r.app}.${r.model}`);
+    expect(keys).not.toContain("airports.boardingService");
+    expect(keys).not.toContain("airports.splashScreen");
+  });
+
+  it("reads DbConfig brands and JSDoc tags off class fields", () => {
+    const { resources } = analyzeProject(classesDir);
+    const airport = findResource(resources, "airports", "airport");
+    expect(airport.search).toEqual(["code", "name"]);
+    expect(airport.fields.find((f) => f.name === "code")).toMatchObject({
+      type: "string",
+      maxLength: 3,
+      unique: true,
+    });
+    expect(airport.fields.find((f) => f.name === "name")).toMatchObject({
+      type: "string",
+      maxLength: 120,
+    });
+  });
+
+  it("infers types and defaults from field initializers", () => {
+    const { resources } = analyzeProject(classesDir);
+    const airport = findResource(resources, "airports", "airport");
+    const field = (name: string) => airport.fields.find((f) => f.name === name);
+    expect(field("region")).toMatchObject({ type: "string", default: "EU" });
+    expect(field("active")).toMatchObject({ type: "bool", default: true });
+    expect(field("gates")).toMatchObject({ type: "int", default: 0 });
+  });
+
+  it("treats a class-typed field as a foreign key", () => {
+    const { resources } = analyzeProject(classesDir);
+    const terminal = findResource(resources, "airports", "terminal");
+    expect(terminal.fields.find((f) => f.name === "airport")).toMatchObject({
+      type: "fk",
+      relation: { app: "airports", model: "airport" },
+    });
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+    expect(terminal.fields.find((f) => f.name === "opened")).toMatchObject({
+      type: "datetime",
+      null: true,
+    });
+  });
+
+  it("ignores static and private class members", () => {
+    const { resources } = analyzeProject(classesDir);
+    const terminal = findResource(resources, "airports", "terminal");
+    expect(terminal.fields.find((f) => f.name === "kind")).toBeUndefined();
+    expect(terminal.fields.find((f) => f.name === "secret")).toBeUndefined();
+  });
+});
+
 describe("interface entities — circular dependencies", () => {
   it("reports a breakable cycle (optional self-FK) as a warning", () => {
     const { diagnostics } = analyzeProject(cycleDir);