eraspace 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # eraspace
 
-Build and deploy realtime apps written in TypeScript. The server runs on the BEAM with Postgres storage, live queries
+Build and deploy realtime apps written in TypeScript. The server runs in V8 with Postgres storage, live queries
 and WebSockets; the client is Preact. Apps need no `package.json`, `tsconfig.json` or `node_modules`: the CLI bundles
 the SDK, Preact and TypeScript.
 
@@ -23,16 +23,34 @@ sign in and claim it (`eraspace auth login`, then `eraspace claim`).
 | --- | --- |
 | `new <name>` / `init` | Create an app in a new directory or the current one |
 | `typecheck` | Typecheck `server/`, `client/` and `shared/` |
-| `deploy` | Build the client, compile the server and deploy |
-| `dev` | Deploy, then redeploy on every save |
-| `call <fn> '<json>'...` | Call a query, mutation or action |
-| `logs` | Read handler logs (`--follow` to stream) |
+| `deploy` | Build the client, compile the server and deploy (`--delete-table <table>=<rows>` confirms deleting a removed table) |
+| `dev` | Deploy, then redeploy whenever `server/`, `client/`, `shared/` or `.env.eraspace.server` change |
+| `call <fn> '<json>'...` | Call a query, mutation or action, each argument a JSON value |
+| `logs [app]` | Read handler logs (`--follow` to stream) |
 | `inspect` | Show the schema, functions and deploys |
-| `auth login` / `claim` | Sign in, and take ownership of an unclaimed app |
+| `auth login` / `logout` / `whoami` | Sign in with your browser, sign out, or show who you are |
+| `claim` | Take ownership of this checkout's unclaimed app |
+| `apps` | List your apps |
+| `names` / `names add` / `names rm` | List, add or remove the app's names |
+| `inspection public\|private [app]` | Open or close inspection and logs to everyone |
+| `archive` / `restore [app]` | Stop serving an app and keep its data, or serve it again |
+| `terminate [app] --yes` | Stop an app permanently: its data is kept but it accepts no more deploys |
+| `token create` / `list` / `revoke` | Manage API tokens for one app, or for all your apps with `--personal` |
 
-`eraspace --help` and `eraspace <command> --help` list every flag.
+Commands act on the app bound to the current checkout. Pass `--app <name or id>` or set `ERASPACE_APP` to choose
+another. `eraspace --help` and `eraspace <command> --help` list every flag.
+
+## CI
+
+Create a token with `eraspace token create` (add `--read` for inspection and logs only), then set `ERASPACE_TOKEN` and
+`ERASPACE_TOKEN_API=<platform origin>` in CI. The CLI never sends the token to any other origin.
 
 ## Platform
 
 The CLI deploys to the hosted eraspace platform by default. Set `ERASPACE_URL` or pass `--url` to use another one, such
 as a local platform at `http://localhost:4000`.
+
+## Upgrading from 0.1
+
+0.2 targets the V8 platform and its JSON socket protocol. Apps deployed with 0.1 are not carried over: deploy them
+afresh with 0.2, which also rebuilds their browser bundles against the new SDK.

package/bin.js

@@ -15424,12 +15424,12 @@ var posixImpl = /* @__PURE__ */ make21({
   resolve,
   normalize(path) {
     if (path.length === 0) return ".";
-    const isAbsolute = path.charCodeAt(0) === 47;
+    const isAbsolute2 = path.charCodeAt(0) === 47;
     const trailingSeparator = path.charCodeAt(path.length - 1) === 47;
-    path = normalizeStringPosix(path, !isAbsolute);
-    if (path.length === 0 && !isAbsolute) path = ".";
+    path = normalizeStringPosix(path, !isAbsolute2);
+    if (path.length === 0 && !isAbsolute2) path = ".";
     if (path.length > 0 && trailingSeparator) path += "/";
-    if (isAbsolute) return "/" + path;
+    if (isAbsolute2) return "/" + path;
     return path;
   },
   isAbsolute(path) {
@@ -15649,9 +15649,9 @@ var posixImpl = /* @__PURE__ */ make21({
     };
     if (path.length === 0) return ret;
     let code = path.charCodeAt(0);
-    const isAbsolute = code === 47;
+    const isAbsolute2 = code === 47;
     let start;
-    if (isAbsolute) {
+    if (isAbsolute2) {
       ret.root = "/";
       start = 1;
     } else {
@@ -15687,11 +15687,11 @@ var posixImpl = /* @__PURE__ */ make21({
     preDotState === 0 || // The (right-most) trimmed path component is exactly '..'
     preDotState === 1 && startDot === end3 - 1 && startDot === startPart + 1) {
       if (end3 !== -1) {
-        if (startPart === 0 && isAbsolute) ret.base = ret.name = path.slice(1, end3);
+        if (startPart === 0 && isAbsolute2) ret.base = ret.name = path.slice(1, end3);
         else ret.base = ret.name = path.slice(startPart, end3);
       }
     } else {
-      if (startPart === 0 && isAbsolute) {
+      if (startPart === 0 && isAbsolute2) {
         ret.name = path.slice(1, startDot);
         ret.base = path.slice(1, end3);
       } else {
@@ -15701,7 +15701,7 @@ var posixImpl = /* @__PURE__ */ make21({
       ret.ext = path.slice(startDot, end3);
     }
     if (startPart > 0) ret.dir = path.slice(0, startPart - 1);
-    else if (isAbsolute) ret.dir = "/";
+    else if (isAbsolute2) ret.dir = "/";
     return ret;
   },
   sep: "/",
@@ -38939,7 +38939,7 @@ var runWith2 = (command2, config2) => {
 // cli/package.json
 var package_default = {
   name: "eraspace-cli",
-  version: "0.1.0",
+  version: "0.2.0",
   private: true,
   license: "MIT",
   type: "module",
@@ -39468,7 +39468,7 @@ var whoami = Effect_exports.fnUntraced(function* (config2) {
 import { basename } from "node:path";
 
 // cli/src/build.ts
-import { dirname as dirname2, join as join5, relative as relative2, resolve as resolve8, sep } from "node:path";
+import { dirname as dirname2, isAbsolute, join as join5, relative as relative2, resolve as resolve8, sep } from "node:path";
 import * as esbuild from "esbuild";
 import { parseSync } from "oxc-parser";
 var toPosix = (p) => p.split(sep).join("/");
@@ -39478,14 +39478,12 @@ function scanImports(file2, source) {
   const fatal = result4.errors.find((e) => e.severity === "Error");
   if (fatal) return { imports: [], error: { message: fatal.message, at: fatal.labels[0]?.start ?? 0 } };
   const imports = [];
-  for (const imp of result4.module.staticImports) {
-    if (imp.entries.length && imp.entries.every((e) => e.isType)) continue;
-    imports.push({ spec: imp.moduleRequest.value, at: imp.moduleRequest.start, kind: "import-statement" });
-  }
-  for (const exp of result4.module.staticExports) {
-    const from = exp.entries.filter((e) => e.moduleRequest && !e.isType);
-    const first = from[0]?.moduleRequest;
-    if (first) imports.push({ spec: first.value, at: first.start, kind: "import-statement" });
+  for (const statement of result4.program.body) {
+    if (statement.type === "ImportDeclaration" && statement.importKind !== "type") {
+      imports.push({ spec: statement.source.value, at: statement.source.start, kind: "import-statement" });
+    } else if ((statement.type === "ExportNamedDeclaration" || statement.type === "ExportAllDeclaration") && statement.exportKind !== "type" && statement.source) {
+      imports.push({ spec: statement.source.value, at: statement.source.start, kind: "import-statement" });
+    }
   }
   for (const imp of result4.module.dynamicImports) {
     const literal = /^\s*(["'`])(.*)\1\s*$/s.exec(source.slice(imp.moduleRequest.start, imp.moduleRequest.end));
@@ -39493,10 +39491,19 @@ function scanImports(file2, source) {
   }
   return { imports: imports.sort((a, b) => (a.at ?? 0) - (b.at ?? 0)) };
 }
+var EXTENSIONS = [".ts", ".mts", ".js", ".mjs", ".tsx"];
+function importCandidates(base) {
+  const stem = /\.m?js$/.test(base) ? base.replace(/\.m?js$/, "") : void 0;
+  return [
+    base,
+    ...EXTENSIONS.map((ext) => base + ext),
+    ...stem === void 0 ? [] : [".ts", ".mts", ".tsx"].map((ext) => stem + ext),
+    ...EXTENSIONS.map((ext) => join5(base, "index" + ext))
+  ].filter((candidate) => EXTENSIONS.some((ext) => candidate.endsWith(ext)));
+}
 var resolveRelative = Effect_exports.fnUntraced(function* (fromFile, spec) {
   const fs = yield* FileSystem_exports.FileSystem;
-  const base = resolve8(dirname2(fromFile), spec);
-  for (const candidate of [base, base + ".ts", join5(base, "index.ts")]) {
+  for (const candidate of importCandidates(resolve8(dirname2(fromFile), spec))) {
     const info2 = yield* fs.stat(candidate).pipe(Effect_exports.option);
     if (info2._tag === "Some" && info2.value.type === "File") return candidate;
   }
@@ -39573,6 +39580,7 @@ function clientPlugin(root, sdk, rejected) {
     setup(build3) {
       build3.onResolve({ filter: /^[^./]/ }, async (args2) => {
         if (args2.pluginData === "eraspace-sdk") return void 0;
+        if (args2.kind === "entry-point" || isAbsolute(args2.path)) return void 0;
         const spec = args2.path;
         const fromCapsule = !args2.importer || inCapsule(args2.importer);
         if (fromCapsule) {
@@ -39778,6 +39786,14 @@ var requireTarget = Effect_exports.fnUntraced(function* (config2, explicit) {
     );
   return { ref, claim: claim2 };
 });
+var confirmedDeletes = Effect_exports.fnUntraced(function* (tables) {
+  const out = {};
+  for (const [table2, rows] of Object.entries(tables ?? {})) {
+    if (!/^\d+$/.test(rows)) return yield* fail12(`--delete-table ${table2}=${rows}: the row count must be a whole number, e.g. --delete-table ${table2}=12`);
+    out[table2] = Number(rows);
+  }
+  return out;
+});
 var withoutEnv = Effect_exports.fnUntraced(function* (payload) {
   if (Object.keys(payload.env).length) {
     yield* Console_exports.warn(
@@ -39792,19 +39808,10 @@ var okDeployed = ok(Deployed);
 var requestedName = (config2, opts) => opts.name !== void 0 ? { name: opts.name } : { name: config2.name ?? toAppName(basename(config2.root)), uniqueName: true };
 var createApp = Effect_exports.fnUntraced(function* (config2, payload, extra, opts, signedIn) {
   const naming = requestedName(config2, opts);
-  const create = (body) => api(config2, "POST", "/_api/apps", {
-    body: { ...payload, ...extra, ...body },
+  const response = yield* api(config2, "POST", "/_api/apps", {
+    body: { ...payload, ...extra, ...naming },
     timeout: DEPLOY_TIMEOUT
   });
-  let response = yield* create(naming);
-  if (response.status === 401 && !signedIn && naming.uniqueName) {
-    yield* Console_exports.warn(
-      c.yellow(
-        `This platform names apps only for signed-in developers, so this app gets an id. Run eraspace auth login and eraspace claim to name it ${naming.name}.`
-      )
-    );
-    response = yield* create({});
-  }
   if (response.status === 409 && !naming.uniqueName) {
     return yield* fail12(
       signedIn ? `The name ${naming.name} is taken. Pick another with --name or in eraspace.json; if it is your app, deploy to it with --app ${naming.name}.` : `The name ${naming.name} is taken. Pick another with --name.`
@@ -39827,7 +39834,11 @@ var deploy = Effect_exports.fnUntraced(function* (config2, opts = {}) {
   const build3 = yield* buildCapsule(config2.root);
   if (!build3.ok || !build3.payload)
     return yield* fail12(yield* formatErrors(build3.errors, config2.root));
-  const extra = opts.publicInspect ? { publicInspection: true } : {};
+  const deleteTables = yield* confirmedDeletes(opts.deleteTables);
+  const extra = {
+    ...opts.publicInspect ? { publicInspection: true } : {},
+    ...Object.keys(deleteTables).length ? { deleteTables } : {}
+  };
   const signedIn = (yield* bearerFor(config2.origin)) !== void 0;
   const t = yield* target(config2);
   let result4;
@@ -40134,7 +40145,7 @@ import { basename as basename2, join as join7, relative as relative3, resolve as
 var TEMPLATES = ["chat", "todo", "poll"];
 var agents = (cli) => `# eraspace capsule: agent instructions
 
-This directory is one eraspace app ("capsule"): a TypeScript server compiled to BEAM bytecode, a Preact client, a
+This directory is one eraspace app ("capsule"): a TypeScript server running in V8, a Preact client, a
 Postgres-backed database with live queries, and hosting, all through the \`eraspace\` CLI. Treat this directory as the
 whole app. Build the requested app by editing the starter files, deploy it, verify it, and report the URL.
 
@@ -40217,7 +40228,9 @@ export default capsule({
 - \`ctx.log.info(msg, data?)\` (also debug/warn/error) writes to \`eraspace logs\`.
 - Endpoints receive \`req\` with \`method, path, url, headers.get(), query.get(), json(), text()\` and return
   \`json(value)\`, \`text(string)\`, \`empty()\`, \`redirect(url)\` or a plain value (sent as JSON).
-- Removing a table that still holds rows is refused on deploy. Keep it in the schema.
+- Removing a populated table needs its row count confirmed: \`${cli} deploy --delete-table <table>=<rows>\` (the
+  refused deploy prints the exact flag). Deletion runs in background batches.
+- Changing a field's type or making it required fails the deploy while stored rows do not match; migrate them first.
 
 ## Client API (\`eraspace/client\`)
 
@@ -40251,28 +40264,55 @@ export default function App() {
 - Realtime rooms, not stored: \`const room = client.useRoom(name, meta)\` gives \`room.presence\`,
   \`room.broadcast(event, payload)\` and \`room.on(event, cb)\` (call \`on\` inside \`useEffect\` and return its
   cleanup). \`client.usePresence(name, meta)\` returns just the members.
-- Files: \`await client.storage.upload(file)\` returns \`{ key }\`; \`client.storage.url(key)\`; \`client.storage.delete(key)\`.
-  Up to 5 MiB per file.
+- Files: see "File uploads" below.
 - Pages: \`Router\`, \`Route\`, \`Link\`, \`useLocation\`, \`useNavigate\`, \`useParams\` from \`eraspace/client\`.
 - Client imports are limited to \`eraspace/client\`, \`preact\`, \`preact/hooks\`, \`@preact/signals\` and relative files.
 
-## TypeScript subset on the server
+## File uploads
 
-Server code is compiled to BEAM, not run in Node. It supports modern TypeScript (classes, closures, async/await,
-destructuring, spread, template literals, Map, Set, JSON, Math, Date, URL, RegExp, fetch) with these limits:
+Files go to the app's bucket, not the database. Save the returned \`FileRef\` in a row, then preview it.
 
-- No npm packages, Node built-ins (\`node:*\`, \`fs\`, \`process\`, \`Buffer\`) or dynamic \`import()\`. Do not install
-  app dependencies.
-- Rejected at compile time: \`eval\`, \`new Function\`, Proxy, Reflect, generators, getters/setters, private
-  \`#fields\`, decorators, enums, namespaces, BigInt, symbols, labeled statements, \`for await\`, static blocks and
-  named function expressions (\`const f = function g() {}\`; use arrow functions or function declarations).
-- Do not declare regex literals at module top level; create them inside the function that uses them.
-- Do not use constructor parameter properties (\`constructor(private x: number)\`). Declare the field and assign
-  \`this.x = x\` in the constructor.
-- Module-level variables are reset for every handler call. Persist state in the database.
-- \`await\` blocks; there is no real concurrency inside a handler. Handlers time out after about a second and have
-  a memory limit, so keep loops and reads bounded.
-- No Intl or \`toLocaleString\` formatting on the server. Format dates and numbers in the client.
+\`\`\`tsx
+// server/index.ts: declare the file in the schema and copy its fields in the mutation (extra fields are refused).
+photos: table({ caption: string(), file: object({ key: string(), name: string(), contentType: string(), size: number() }) }),
+addPhoto: mutation(async (ctx, caption: string, file: { key: string; name: string; contentType: string; size: number }) => {
+  if (!/^[0-9a-f-]{36}$/.test(String(file?.key))) throw new Error("Upload the photo first.");
+  return ctx.db.photos.insert({ caption, file: { key: file.key, name: file.name, contentType: file.contentType, size: file.size } });
+}),
+
+// client/index.tsx
+import { createClient, FileUpload, FilePreview } from "eraspace/client";
+const addPhoto = client.useMutation("addPhoto");
+<FileUpload client={client} accept="image/*" onUpload={(file) => addPhoto(caption, file)} />
+{photos?.map((p) => <FilePreview key={p.id} client={client} file={p.file} />)}
+\`\`\`
+
+- \`<FileUpload>\` is a drop zone and file picker with progress and error text. Props: \`accept\`, \`multiple\`,
+  \`maxBytes\`, \`disabled\`, \`class\` (replaces its default style; \`data-dragging\` is set during a drag) and
+  children for the label. \`onUpload(file)\` runs once per stored file; if it throws, the file is deleted again.
+- \`<FilePreview file={fileRef or key}>\` shows images, video and audio inline, plain text in a frame, and other
+  types (PDF, zip...) as a download card. \`caption={false}\` hides the name/size line; \`class\` replaces its style.
+  Pass the saved \`FileRef\`: a bare key costs a metadata request per preview.
+- Custom UI: \`const { upload, uploading, progress, error } = client.useUpload({ accept, maxBytes, onUpload })\`,
+  then \`upload(input.files)\`. Lower level: \`client.storage.upload(blob, { onProgress })\`, \`.url(key)\`,
+  \`.info(key)\` and \`.delete(key)\`.
+- \`accept\` and \`maxBytes\` are checked in the browser only; the server stores any type up to its limit.
+- Up to 5 MiB per file and 100 MiB per app. Anyone with a key can read or delete that file; never upload secrets.
+
+## Server execution
+
+Server TypeScript is transformed with oxc and runs as ES modules in V8. JavaScript language features such as
+classes, closures, async/await, generators, getters, private fields, Proxy, Reflect and BigInt use V8 semantics.
+Values crossing the database or RPC boundary must be JSON-compatible.
+
+- Imports support relative deployed files and \`eraspace/server\`. npm packages, Node built-ins and dynamic
+  \`import()\` are unavailable. Apps need no installed server dependencies.
+- The host supplies \`fetch\`, \`URL\`, \`Headers\`, \`Request\`, \`Response\`, \`crypto.randomUUID\`,
+  \`TextEncoder\`, \`TextDecoder\`, timers and \`console\`.
+- Persist state in the database. Module state is not durable and resets when an app unloads or a worker restarts.
+- Await database calls. Mutations run through one writer per app and reply after their Postgres commit.
+- Handlers have CPU, wall-clock and heap limits. Keep loops and reads bounded.
+- Outbound fetch is available to claimed apps in actions and read-only endpoints. Private addresses are blocked.
 
 ## Deploys without an account
 
@@ -40410,6 +40450,12 @@ var deployFlags = {
   publicInspect: Flag_exports.Boolean("public-inspect").pipe(Flag_exports.withDefault(false), Flag_exports.withDescription("Let anyone read this app's inspection data and logs"))
 };
 var deployOptions = (input) => ({ name: value3(input.name), publicInspect: input.publicInspect });
+var deleteTableFlag = {
+  deleteTable: Flag_exports.KeyValuePair("delete-table").pipe(
+    Flag_exports.withDescription("Delete a table removed from the schema, confirming its current row count: --delete-table <table>=<rows> (repeatable)"),
+    Flag_exports.optional
+  )
+};
 var browserFlag = {
   browser: Flag_exports.Boolean("browser").pipe(Flag_exports.withDefault(true), Flag_exports.withDescription("Open the sign-in page in a browser; --no-browser only prints the URL"))
 };
@@ -40431,8 +40477,13 @@ var initCommand = Command_exports.make("init", { template: templateFlag }, ({ te
 var typecheckCommand = Command_exports.make("typecheck", {}, () => Effect_exports.flatMap(config, (c2) => typecheck(c2.root))).pipe(
   Command_exports.withDescription("Typecheck server/, client/ and shared/ (no tsconfig.json or node_modules needed)")
 );
-var deployCommand = Command_exports.make("deploy", deployFlags, (input) => Effect_exports.flatMap(config, (c2) => deploy(c2, deployOptions(input)))).pipe(
-  Command_exports.withDescription("Build and deploy. Without a login this creates a temporary unclaimed app.")
+var deployCommand = Command_exports.make(
+  "deploy",
+  { ...deployFlags, ...deleteTableFlag },
+  (input) => Effect_exports.flatMap(config, (c2) => deploy(c2, { ...deployOptions(input), deleteTables: value3(input.deleteTable) }))
+).pipe(
+  Command_exports.withDescription("Build and deploy. Without a login this creates a temporary unclaimed app."),
+  Command_exports.withExamples([{ command: "eraspace deploy --delete-table drafts=12", description: "Deploy a schema without drafts, deleting its 12 rows" }])
 );
 var devCommand = Command_exports.make("dev", deployFlags, (input) => Effect_exports.flatMap(config, (c2) => dev(c2, deployOptions(input)))).pipe(
   Command_exports.withDescription("Deploy, then redeploy whenever server/, client/, shared/ or .env.eraspace.server change")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eraspace",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "eraspace: build, deploy and manage eraspace capsules",
   "type": "module",
   "keywords": [
@@ -8,7 +8,7 @@
     "cli",
     "realtime",
     "preact",
-    "beam"
+    "v8"
   ],
   "license": "MIT",
   "bin": {
@@ -24,10 +24,8 @@
     "@preact/signals": "2.11.3",
     "@tailwindcss/node": "4.3.3",
     "@tailwindcss/oxide": "4.3.3",
-    "@types/phoenix": "1.6.7",
     "esbuild": "0.28.2",
     "oxc-parser": "0.154.0",
-    "phoenix": "1.8.15",
     "preact": "11.0.1",
     "preact-iso": "2.12.2",
     "tailwindcss": "4.3.3",

package/sdk/src/client/client.ts

@@ -1,11 +1,13 @@
 import { computed, type ReadonlySignal } from "@preact/signals";
-import { useEffect, useMemo, useRef } from "preact/hooks";
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { createStorageClient } from "./storage.ts";
+import { useUpload, type UseUploadOptions } from "./files.ts";
 import type { ClientOptions } from "./config.ts";
 import { subKey, stableStringify } from "./sub-key.ts";
 import type { Subscription } from "./subscription.ts";
 import type { RoomConn } from "./room.ts";
 import type { EraspaceClient, Room } from "./types.ts";
+import { EraspaceError } from "./errors.ts";
 import { ClientImpl } from "./connection.ts";
 import { Pager } from "./pagination.ts";
 
@@ -39,7 +41,8 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
     return useMemo(() => computed(() => {
       const err = sub.error.value;
       const value: unknown = sub.value.value;
-      if (err && value === undefined) throw err;
+      // Retried failures keep showing the last value; a gone app cannot recover.
+      if (err && (value === undefined || err.name === "AppGone")) throw err;
       return value;
     }), [sub]);
   }
@@ -61,7 +64,7 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
   }
 
   function useAction(name: string) {
-    return useMemo(() => (...args: unknown[]) => get().call(name, args), [name]);
+    return useMemo(() => (...args: unknown[]) => get().call(name, args, "action"), [name]);
   }
 
   function usePaginatedQuery(name: string, args: unknown[], opts?: { initialNumItems?: number }) {
@@ -85,8 +88,17 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
 
   function useRoomConn(room: string, meta: Record<string, unknown> | undefined): RoomConn {
     const c = get();
-    const r = useMemo(() => c.acquireRoom(room), [room]);
-    useEffect(() => () => c.releaseRoom(r), [r]);
+    const [generation, renew] = useState(0);
+    // Acquiring during render holds nothing: only a committed effect retains the room.
+    const r = useMemo(() => c.acquireRoom(room), [room, generation]);
+    useEffect(() => {
+      if (!c.retainRoom(r)) {
+        // Dropped between render and commit.
+        renew((n) => n + 1);
+        return;
+      }
+      return () => c.releaseRoom(r);
+    }, [r]);
     const metaKey = meta === undefined ? undefined : stableStringify(meta);
     useEffect(() => {
       if (meta !== undefined) r.setMeta(meta);
@@ -104,8 +116,9 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
       presence: r.members.value,
       self: r.self.value,
       state: r.state.value,
+      error: r.error.value,
       broadcast: (event: string, payload?: unknown) => {
-        r.channel.push("broadcast", { event, payload: payload ?? null });
+        void r.channel.push("broadcast", { event, payload: payload ?? null }).catch(error => { r.error.value = EraspaceError.from(error); });
       },
       on: (event: string, cb: (payload: any, from: string | undefined) => void) => {
         let set = r.listeners.get(event);
@@ -114,14 +127,15 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
         return () => set!.delete(cb);
       },
       setState: (key: string, value: unknown) => {
-        r.state.value = { ...r.state.peek(), [key]: value };
-        r.channel.push("state:set", { key, value: value ?? null });
+        r.setState(key, value);
       },
     };
   }
 
+  const storage = createStorageClient(() => get().base);
   const client = {
-    storage: createStorageClient(() => get().base),
+    storage,
+    useUpload: (opts?: UseUploadOptions) => useUpload(storage, opts),
     useQuery,
     useQuerySignal,
     useQuerySelector,
@@ -131,8 +145,9 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
     usePresence,
     useRoom,
     query: (name: string, ...args: unknown[]) => get().call(name, args),
-    mutation: (name: string, ...args: unknown[]) => get().call(name, args),
-    action: (name: string, ...args: unknown[]) => get().call(name, args),
+    mutation: (name: string, ...args: unknown[]) => get().mutate(name, args),
+    retryMutation: (name: string, args: unknown[], requestKey: string) => get().retryMutation(name, args, requestKey),
+    action: (name: string, ...args: unknown[]) => get().call(name, args, "action"),
     subscribe: (name: string, args: unknown[], onValue: Fn, onError?: Fn) => get().subscribe(name, args, onValue, onError),
     get app() {
       return get().app;

package/sdk/src/client/config.ts

@@ -1,3 +1,5 @@
+import type { SocketOptions, WebSocketConstructor } from "./transport.ts";
+
 /** `window.__ERASPACE__`, injected by the platform's HTML shell (SPEC §6). */
 export interface EraspaceConfig {
   app: string;
@@ -12,7 +14,7 @@ export interface ClientOptions {
   socket?: string;
   base?: string;
   version?: number;
-  /** Reload the page when the app is redeployed (after re-subscribing). Default `false`. */
+  /** Reload the page when the app is redeployed. Default `false`. */
   reloadOnDeploy?: boolean;
   /** Push timeout in ms. Default 15000. */
   timeout?: number;
@@ -21,9 +23,9 @@ export interface ClientOptions {
   /** Delay before refreshing a subscription still waiting for a mutation commit. Default 2000 ms. */
   optimisticTimeoutMs?: number;
   /** WebSocket constructor (tests, non-browser runtimes). */
-  transport?: unknown;
-  /** Extra Phoenix socket options. */
-  socketOptions?: Record<string, unknown>;
+  transport?: WebSocketConstructor;
+  /** Reconnect and rejoin delay overrides. */
+  socketOptions?: Pick<SocketOptions, "reconnectAfterMs" | "rejoinAfterMs">;
 }
 
 declare global {