rastack 0.0.57 → 0.0.59

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.59](https://github.com/theserverkid/reactapistack/compare/v0.0.58...v0.0.59) (2026-07-18)
+
+
+### Bug Fixes
+
+* **ci:** valid pnpm-workspace.yaml (pnpm 11 moved overrides/onlyBuiltDependencies out of package.json); fixes ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION ([b739531](https://github.com/theserverkid/reactapistack/commit/b739531a34d323afd2a0df3394d95563cfa175a0))
+* **hooks:** type the query compat layer against @tanstack/react-query v5, drop the dead react-query v3 dependency ([6642bc6](https://github.com/theserverkid/reactapistack/commit/6642bc68c917465bd763deaf4a5696983e1dde45))
+* **pkg:** add files allowlist so npm publishes only the framework surface (root-package layout no longer leaks engine/web/docs) ([a6bc9ee](https://github.com/theserverkid/reactapistack/commit/a6bc9ee93d794628be42bac14eef12575a5cdfba))
+
+### [0.0.58](https://github.com/theserverkid/reactapistack/compare/v0.0.57...v0.0.58) (2026-07-18)
+
 ### [0.0.57](https://github.com/theserverkid/reactapistack/compare/v0.0.56...v0.0.57) (2026-07-18)
 
 ### [0.0.56](https://github.com/theserverkid/reactapistack/compare/v0.0.55...v0.0.56) (2026-07-18)

package/README.md

@@ -0,0 +1,190 @@
+# React API Stack
+
+**A full-stack framework on top of object storage. Scale to millions.**
+
+React API Stack is not a UI library and not "just" an API package — it is the
+**whole vertical**: the API exposure surface, the database storage layer, and the
+devops that ships them. You author **one TypeScript resource** and the framework
+derives everything from the React data hooks at the top to the Parquet files on
+S3 at the bottom, with a stateless Rust API in between.
+
+```
+            ┌─────────────────────────────────────────────┐
+            │                React / Expo                  │   API EXPOSURE
+            │   useData(Airport) / useForm(Flight)         │   SURFACE
+            └───────────────────────▲─────────────────────┘
+                                    │  your types, resolved via the manifest
+            ┌───────────────────────┴─────────────────────┐
+            │   TypeScript resources → `rastack compile`       │   API EXPOSURE
+            │   FK inferred from types → manifest+OpenAPI  │   SURFACE
+            └───────────────────────▲─────────────────────┘
+                                    │  schema.rastack.json (manifest)
+            ┌───────────────────────┴─────────────────────┐
+            │        Rust API (rastack-server, axum)           │   API + ADMIN
+            │  manifest-driven CRUD · FK validation ·      │
+            │  Django-admin-style /admin DB browser        │
+            └───────────────────────▲─────────────────────┘
+                                    │  object_store
+            ┌───────────────────────┴─────────────────────┐
+            │     Apache Iceberg tables on S3 (Parquet)    │   DATABASE
+            │   snapshots · ACID on object storage         │   STORAGE
+            └───────────────────────▲─────────────────────┘
+                                    │
+            ┌───────────────────────┴─────────────────────┐
+            │     AWS Lambda (stateless) + S3 (state)      │   DEVOPS
+            │   compute/storage separation, IaC, scale-to- │
+            │   zero — modelled on SurrealDB's Gen-3        │
+            └─────────────────────────────────────────────┘
+```
+
+## The three surfaces, one framework
+
+| Surface | What it is | Package(s) |
+| --- | --- | --- |
+| **API exposure** | TypeScript resources → `rastack compile` (FK inferred from types) → manifest + OpenAPI → pass your type to `useData` / `useForm` (typed TanStack Query hooks, no codegen) | the repo root, published as `rastack` (npm) — `components/`, `hooks/`, `theme/`, … |
+| **Database storage** | A stateless Rust API that stores every model as an Apache Iceberg table on object storage — snapshots, ACID on S3, columnar Parquet | `engine/` (`serve/rastack-server`) |
+| **DevOps** | Serverless Rust on AWS Lambda + S3: stateless compute, state in object storage, infrastructure-as-code, scale-to-zero — driven by `rastack init` / `deploy` / `ci` | `deploy/cloudformation/`, `examples/serverless/` |
+
+## Install the CLI
+
+One command, no clone — installs the `rastack` CLI into a per-user dir
+(`~/.rastack`, no sudo), the way you'd install Poetry or rustup. Node.js is the
+only prerequisite.
+
+```bash
+# macOS / Linux
+curl -fsSL https://reactapistack.com/setup.sh | sh
+
+# Windows (PowerShell) — from cmd, prefix with: powershell -c "…"
+irm https://reactapistack.com/setup.ps1 | iex
+```
+
+Prefer a package manager, or adding it to a single project? `npm install -g rastack`
+(global CLI) or `npm install -D rastack` (project dependency) work too. Pin a
+version with `RASTACK_VERSION=x.y.z` before the installer.
+
+## Author once, compile the rest
+
+```ts
+// resources/airports.ts
+import { resource, s } from "rastack/define";
+
+export const Airport = resource("airports", "airport", {
+  code: s.string({ maxLength: 3, unique: true }),
+  name: s.string({ maxLength: 120 }),
+});
+
+export const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),   // ← foreign key, detected from the type
+  label: s.string({ maxLength: 20 }),
+});
+```
+
+```bash
+rastack compile resources .rastack # TS → schema.rastack.json + openapi.json (FK detected)
+rastack dev                        # the app + admin, in-browser over the WASM engine
+rastack admin                      # Django-admin-style DB browser
+```
+
+```tsx
+// Then just pass your type to the hooks — nothing is generated into your repo.
+const airports = useData(Airport);
+<DataTable query={airports} />
+
+const form = useForm(Flight, { id });
+form.transition("board");          // a typed, state-machine-safe save
+```
+
+The compile step runs a real TypeScript type checker and infers relationships
+straight from the field types — see
+[docs/compile-and-relations.md](docs/compile-and-relations.md); the hooks
+resolve your types against the compiled manifest at runtime — see
+[docs/typed-hooks.md](docs/typed-hooks.md). Resources can declare **state
+transitions** (`scheduled → boarding → departed`), compiled into the manifest
+and enforced on every write surface — an illegal jump is a 400 from the form,
+the importer, the server, and the in-browser WASM engine alike.
+
+## Ship it — one command per stage
+
+The DevOps surface is a CLI too. A new repo is scaffolded, configured, and
+deployed with three commands, and GitHub Actions stays a one-liner because the
+pipeline lives in the CLI, not the YAML:
+
+```bash
+rastack init                       # template .github/workflows + .rastack/deploy.json
+rastack deploy                     # configure the deployment; print the stack launch command
+rastack ci deploy                  # what CI runs: build the arm64 Lambda, bake the JWKS, ship the code
+```
+
+`init` scaffolds the base GitHub Actions and a deploy config (defaulting the
+GitHub coordinates from your `origin` remote); `deploy` fills that config in and
+prints the one-time `aws cloudformation deploy` plus the repo Variables to wire;
+`ci` runs the build/deploy pipeline so a workflow is just
+`run: rastack ci deploy` (`rastack ci --plan deploy` prints every step). Full
+guide: **[docs/serverless-deploy.md](docs/serverless-deploy.md)**.
+
+## Run the whole API in the browser
+
+The Rust API is stateless compute over object storage, so it also compiles to
+**WebAssembly and runs entirely in the browser** — no server, no network. One
+setting on the React provider picks where the API runs; the hooks never
+change:
+
+```tsx
+// Local-first dev: the entire API in the browser, over the data/ Iceberg files.
+<RAStackProvider mode="local" manifest={schema} warehouseBaseUrl="/data/warehouse/">
+  <App />
+</RAStackProvider>
+
+// Production: the same code on AWS Lambda + S3.
+<RAStackProvider mode="remote" baseURL="https://api.example.com">…</RAStackProvider>
+
+// Client-only, reading and writing S3 directly.
+<RAStackProvider mode="s3" manifest={schema} warehouseBaseUrl="https://bucket.s3.amazonaws.com/warehouse/">…</RAStackProvider>
+```
+
+`local` and `s3` run the same `rastack-api-core` request logic (CRUD, foreign-key
+validation, DRF-shaped lists) that Lambda runs — and, because Arrow/Parquet
+compile to WebAssembly, the browser reads and writes the **same Parquet Iceberg
+files** the server does. The local database is just a committed directory of
+those files under `data/`. Full guide:
+**[docs/local-wasm-dev.md](docs/local-wasm-dev.md)**.
+
+## Why "on top of object storage"?
+
+Traditional stacks pin you to a server-bound RDBMS. React API Stack instead puts
+**S3 at the bottom of the stack as the system of record** and runs the API as
+**stateless, elastic compute** on top — the same compute/storage-separation
+principle behind [SurrealDB's Gen-3 architecture](https://surrealdb.com/platform/surrealds).
+That gives you:
+
+- **Scale to millions** — compute scales horizontally and independently of data;
+  storage is S3's 11-nines durability and effectively unbounded capacity.
+- **Scale to zero** — when no requests are in flight, no compute runs and you pay
+  only for object storage.
+- **No vendor lock-in** — data lives in open Apache Iceberg / Parquet, readable by
+  Spark, DuckDB, Trino, and Polars.
+
+## Start here
+
+- **[docs/compile-and-relations.md](docs/compile-and-relations.md)** — the
+  TypeScript-first compile step and foreign-key inference.
+- **[docs/typed-hooks.md](docs/typed-hooks.md)** — pass your type to
+  `useData` / `useForm`, and state transitions as typesafe backend functions.
+- **[docs/architecture.md](docs/architecture.md)** — the full serverless,
+  object-storage architecture and how the three surfaces compose.
+- **[docs/local-wasm-dev.md](docs/local-wasm-dev.md)** — running the whole API in
+  the browser via WebAssembly, and the `RAStackProvider` mode switch.
+- **[engine/](engine/)** — the Rust engine: `core/` (manifest, Iceberg storage, request brain) and `serve/` (axum API, server binary, wasm).
+- **[examples/serverless/](examples/serverless/)** — Lambda + S3 + IaC.
+- **[CLAUDE.md](CLAUDE.md)** — codebase guide for contributors.
+- **Building with an LLM?** The documentation site is mirrored as plain Markdown
+  for agents — [reactapistack.com/llms.txt](https://reactapistack.com/llms.txt)
+  (curated index), [llms-full.txt](https://reactapistack.com/llms-full.txt)
+  (every page in one file), or any page at `/docs/<slug>.md`.
+
+> **Performance note.** Apache Iceberg over S3 is currently the portable,
+> correct-by-default storage path, not the fastest one. S3 first-byte latency
+> dominates small OLTP reads. The roadmap closes this with a custom S3 backend
+> fronted by a DynamoDB metadata/cache layer (and optionally EFS for hot IO) —
+> see [docs/architecture.md](docs/architecture.md#performance-roadmap).

package/admin/index.tsx

@@ -17,12 +17,12 @@ import React, { useEffect, useMemo, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { RAStackProvider, useRastackClient } from "../provider";
 import type { RastackWasmModule } from "../provider/types";
-import { Spinner } from "../components";
 import { ThemeProvider } from "../theme";
 import { defineTheme } from "../tokens";
 import { AdminApp } from "./AdminApp";
 import { parseManifest, type AdminResource } from "./adapters";
 import { createHttpEngine } from "./httpEngine";
+import { BootScreen } from "./ui/BootScreen";
 
 interface AdminConfig {
   mode: "local" | "remote";
@@ -55,22 +55,19 @@ const loadEngine = async (): Promise<RastackWasmModule> => {
   return mod;
 };
 
-function Loading({ label }: { label: string }): React.JSX.Element {
-  return (
-    <div className="ras-boot">
-      <Spinner /> {label}
-    </div>
-  );
-}
-
 /** Local (WASM) admin: wait for the provider's engine, then render. */
 function LocalAdmin({ resources }: { resources: AdminResource[] }): React.JSX.Element {
   const client = useRastackClient();
   if (client.status === "error")
-    return <Loading label="The WASM engine failed to start — check the console." />;
+    return (
+      <BootScreen
+        error
+        label="The WASM engine failed to start — check the console."
+      />
+    );
   if (!client.engine || client.status !== "ready")
     return (
-      <Loading
+      <BootScreen
         label={
           client.status === "seeding"
             ? "Seeding the local warehouse…"
@@ -108,8 +105,17 @@ function Boot(): React.JSX.Element {
   }, []);
 
   if (error)
-    return <div className="ras-boot">Failed to load the schema: {error}</div>;
-  if (!resources || !manifest) return <Loading label="Loading the schema…" />;
+    return (
+      <ThemeProvider tokens={theme}>
+        <BootScreen error label={`Failed to load the schema: ${error}`} />
+      </ThemeProvider>
+    );
+  if (!resources || !manifest)
+    return (
+      <ThemeProvider tokens={theme}>
+        <BootScreen label="Loading the schema…" />
+      </ThemeProvider>
+    );
 
   if (cfg.mode === "remote") {
     return (

package/admin/ui/BootScreen.tsx

@@ -0,0 +1,201 @@
+/**
+ * The admin's boot / loading screen — what you see while the schema loads and
+ * the WASM engine spins up. It is deliberately **self-contained**: the main
+ * `AdminStyles` sheet is only injected once `<AdminApp>` mounts, so this screen
+ * ships its own scoped `<style>` (guarded against double-injection) and leans on
+ * the design-token CSS variables with graceful fallbacks, so it looks right in
+ * every phase — before the `<ThemeProvider>` is even in the tree, and in both
+ * light and dark. It reuses the product `<BrandMark>` and honours
+ * `prefers-reduced-motion`.
+ */
+import React from "react";
+import { BrandMark } from "./icons";
+
+const STYLE_ID = "ras-boot-style";
+
+const BOOT_CSS = String.raw`
+.ras-loader {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background:
+    radial-gradient(120% 90% at 50% -10%,
+      color-mix(in srgb, var(--color-accent, #4F6BFF) 12%, transparent) 0%,
+      transparent 60%),
+    var(--color-bg, transparent);
+}
+.ras-loader-inner {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 22px;
+  animation: ras-boot-in 0.5s cubic-bezier(0.22, 0.7, 0.24, 1) both;
+}
+.ras-loader-mark {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 76px;
+  height: 76px;
+}
+/* Soft pulsing halo behind the logo. */
+.ras-loader-mark::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: 22px;
+  background: color-mix(in srgb, var(--color-accent, #4F6BFF) 45%, transparent);
+  filter: blur(16px);
+  animation: ras-boot-glow 1.8s var(--ras-ease, cubic-bezier(0.22, 0.7, 0.24, 1)) infinite;
+}
+/* Rotating conic ring that frames the mark. */
+.ras-loader-mark::after {
+  content: "";
+  position: absolute;
+  inset: -7px;
+  border-radius: 26px;
+  padding: 2px;
+  background: conic-gradient(from 0deg,
+    transparent 0deg,
+    var(--color-accent, #4F6BFF) 90deg,
+    transparent 200deg);
+  -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+  -webkit-mask-composite: xor;
+          mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+          mask-composite: exclude;
+  animation: ras-boot-spin 1.4s linear infinite;
+}
+.ras-loader-logo {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 62px;
+  height: 62px;
+  border-radius: 18px;
+  background: var(--color-surface, var(--color-bg, #fff));
+  box-shadow:
+    0 8px 24px color-mix(in srgb, var(--color-accent, #4F6BFF) 22%, transparent),
+    0 1px 0 color-mix(in srgb, var(--color-text, #0B1020) 6%, transparent) inset;
+  animation: ras-boot-bob 3s ease-in-out infinite;
+}
+.ras-loader-title {
+  font-size: 17px;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+  color: var(--color-text, #0B1020);
+  font-family: var(--font-family-sans, "Inter", system-ui, sans-serif);
+}
+.ras-loader-title .ras-loader-admin {
+  color: var(--color-accent, #4F6BFF);
+  font-weight: 600;
+}
+/* Indeterminate track. */
+.ras-loader-track {
+  position: relative;
+  width: 172px;
+  height: 4px;
+  border-radius: 999px;
+  overflow: hidden;
+  background: color-mix(in srgb, var(--color-text, #0B1020) 10%, transparent);
+}
+.ras-loader-track::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  width: 40%;
+  border-radius: inherit;
+  background: linear-gradient(90deg,
+    transparent,
+    var(--color-accent, #4F6BFF),
+    color-mix(in srgb, var(--color-accent, #4F6BFF) 40%, transparent));
+  animation: ras-boot-slide 1.25s cubic-bezier(0.5, 0.1, 0.3, 1) infinite;
+}
+.ras-loader-label {
+  margin: -6px 0 0;
+  font-size: 13.5px;
+  color: var(--color-text-muted, #6b7590);
+  font-family: var(--font-family-sans, "Inter", system-ui, sans-serif);
+  text-align: center;
+  max-width: 320px;
+}
+.ras-loader.is-error .ras-loader-mark::before,
+.ras-loader.is-error .ras-loader-mark::after { animation-play-state: paused; opacity: 0.35; }
+.ras-loader.is-error .ras-loader-label { color: var(--color-danger, #d64550); }
+
+@keyframes ras-boot-in {
+  from { opacity: 0; transform: translateY(8px) scale(0.985); }
+  to   { opacity: 1; transform: none; }
+}
+@keyframes ras-boot-spin { to { transform: rotate(360deg); } }
+@keyframes ras-boot-glow {
+  0%, 100% { opacity: 0.45; transform: scale(0.9); }
+  50%      { opacity: 0.85; transform: scale(1.08); }
+}
+@keyframes ras-boot-bob {
+  0%, 100% { transform: translateY(0); }
+  50%      { transform: translateY(-3px); }
+}
+@keyframes ras-boot-slide {
+  0%   { left: -42%; }
+  100% { left: 100%; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ras-loader-inner,
+  .ras-loader-mark::before,
+  .ras-loader-mark::after,
+  .ras-loader-logo,
+  .ras-loader-track::after { animation: none; }
+  .ras-loader-track::after { left: 0; width: 100%; opacity: 0.7; }
+}
+`;
+
+/** Inject the scoped stylesheet exactly once. */
+function useBootStyles(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = STYLE_ID;
+  el.textContent = BOOT_CSS;
+  document.head.appendChild(el);
+}
+
+export interface BootScreenProps {
+  /** The status line shown beneath the mark. */
+  label: string;
+  /** Render in the error palette (paused halo, danger-coloured label). */
+  error?: boolean;
+}
+
+/**
+ * A branded, animated boot screen — the product logo in a floating tile with a
+ * pulsing halo and a rotating ring, the wordmark, an indeterminate progress
+ * track, and the current status. Matches the polish of the rest of the admin.
+ */
+export function BootScreen({ label, error }: BootScreenProps): React.JSX.Element {
+  useBootStyles();
+  return (
+    <div
+      className={`ras-loader${error ? " is-error" : ""}`}
+      role="status"
+      aria-live="polite"
+      aria-busy={!error}
+    >
+      <div className="ras-loader-inner">
+        <div className="ras-loader-mark">
+          <div className="ras-loader-logo">
+            <BrandMark size={34} />
+          </div>
+        </div>
+        <div className="ras-loader-title">
+          React API Stack <span className="ras-loader-admin">Admin</span>
+        </div>
+        {!error ? <div className="ras-loader-track" aria-hidden="true" /> : null}
+        <p className="ras-loader-label">{label}</p>
+      </div>
+    </div>
+  );
+}