eraspace 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "eraspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "eraspace: build, deploy and manage eraspace capsules",
+  "type": "module",
+  "keywords": [
+    "eraspace",
+    "cli",
+    "realtime",
+    "preact",
+    "beam"
+  ],
+  "license": "MIT",
+  "bin": {
+    "eraspace": "bin.js"
+  },
+  "eraspace": {
+    "command": "npx eraspace"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@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",
+    "typescript": "7.0.2"
+  }
+}

package/sdk/src/client/client.ts

@@ -0,0 +1,156 @@
+import { computed, type ReadonlySignal } from "@preact/signals";
+import { useEffect, useMemo, useRef } from "preact/hooks";
+import { createStorageClient } from "./storage.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 { ClientImpl } from "./connection.ts";
+import { Pager } from "./pagination.ts";
+
+export { readConfig, type EraspaceConfig, type ClientOptions } from "./config.ts";
+export { subKey } from "./sub-key.ts";
+export type { EraspaceClient, Room, PresenceEntry, MutationOptions, OptimisticStore, PaginatedQueryName, PaginatedQueryResult } from "./types.ts";
+
+type Fn = (...args: any[]) => any;
+
+/**
+ * Create the typed client. Import the server definition with `import type app from "../server/index"`, then
+ * `const client = createClient<typeof app>()`. Options default to `window.__ERASPACE__`.
+ */
+export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C> {
+  let impl: ClientImpl | undefined;
+  // Lazy so a module-level createClient() costs nothing until first use.
+  const get = () => (impl ??= new ClientImpl(options));
+
+  function useSubscription(name: string, args: unknown[]): Subscription {
+    const c = get();
+    const sub = c.acquire(name, args);
+    useEffect(() => {
+      c.retain(sub);
+      return () => c.release(sub);
+    }, [sub]);
+    return sub;
+  }
+
+  function useQuerySignal(name: string, ...args: unknown[]): ReadonlySignal<unknown> {
+    const sub = useSubscription(name, args);
+    return useMemo(() => computed(() => {
+      const err = sub.error.value;
+      const value: unknown = sub.value.value;
+      if (err && value === undefined) throw err;
+      return value;
+    }), [sub]);
+  }
+
+  function useQuerySelector(name: string, args: unknown[], select: (value: unknown) => unknown): unknown {
+    const result = useQuerySignal(name, ...args);
+    const selected = useMemo(() => computed(() => select(result.value)), [result, select]);
+    return selected.value;
+  }
+
+  function useQuery(name: string, ...args: unknown[]): unknown {
+    return useQuerySignal(name, ...args).value;
+  }
+
+  function useMutation(name: string, opts?: { optimistic?: Fn }) {
+    const ref = useRef(opts);
+    ref.current = opts;
+    return useMemo(() => (...args: unknown[]) => get().mutate(name, args, ref.current?.optimistic), [name]);
+  }
+
+  function useAction(name: string) {
+    return useMemo(() => (...args: unknown[]) => get().call(name, args), [name]);
+  }
+
+  function usePaginatedQuery(name: string, args: unknown[], opts?: { initialNumItems?: number }) {
+    const c = get();
+    const n = opts?.initialNumItems ?? 20;
+    const key = subKey(name, args) + ":" + n;
+    const pager = useMemo(() => new Pager(c, name, args, n), [key]);
+    useEffect(() => {
+      pager.start();
+      return () => pager.stop();
+    }, [pager]);
+    const { results, status } = pager.result.value;
+    return {
+      results,
+      status,
+      isLoading: status === "LoadingFirstPage" || status === "LoadingMore",
+      loadMore: (k?: number) => pager.loadMore(k),
+      reset: () => pager.reset(),
+    };
+  }
+
+  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 metaKey = meta === undefined ? undefined : stableStringify(meta);
+    useEffect(() => {
+      if (meta !== undefined) r.setMeta(meta);
+    }, [r, metaKey]);
+    return r;
+  }
+
+  function usePresence(room: string, meta?: Record<string, unknown>) {
+    return useRoomConn(room, meta).members.value;
+  }
+
+  function useRoom(room: string, meta?: Record<string, unknown>): Room<any, any> {
+    const r = useRoomConn(room, meta);
+    return {
+      presence: r.members.value,
+      self: r.self.value,
+      state: r.state.value,
+      broadcast: (event: string, payload?: unknown) => {
+        r.channel.push("broadcast", { event, payload: payload ?? null });
+      },
+      on: (event: string, cb: (payload: any, from: string | undefined) => void) => {
+        let set = r.listeners.get(event);
+        if (!set) r.listeners.set(event, (set = new Set()));
+        set.add(cb);
+        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 });
+      },
+    };
+  }
+
+  const client = {
+    storage: createStorageClient(() => get().base),
+    useQuery,
+    useQuerySignal,
+    useQuerySelector,
+    useMutation,
+    useAction,
+    usePaginatedQuery,
+    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),
+    subscribe: (name: string, args: unknown[], onValue: Fn, onError?: Fn) => get().subscribe(name, args, onValue, onError),
+    get app() {
+      return get().app;
+    },
+    get base() {
+      return get().base;
+    },
+    get guestId() {
+      return get().self.value;
+    },
+    get status() {
+      return get().status;
+    },
+    get version() {
+      return get().version;
+    },
+    onDeployed: (cb: (v: number) => void) => get().onDeployedCb(cb),
+    close: () => impl?.close(),
+  };
+  return client as unknown as EraspaceClient<C>;
+}

package/sdk/src/client/config.ts

@@ -0,0 +1,37 @@
+/** `window.__ERASPACE__`, injected by the platform's HTML shell (SPEC §6). */
+export interface EraspaceConfig {
+  app: string;
+  base: string;
+  version: number;
+  socket: string;
+}
+
+export interface ClientOptions {
+  app?: string;
+  /** Socket endpoint, e.g. `/socket` or `ws://localhost:4000/socket`. */
+  socket?: string;
+  base?: string;
+  version?: number;
+  /** Reload the page when the app is redeployed (after re-subscribing). Default `false`. */
+  reloadOnDeploy?: boolean;
+  /** Push timeout in ms. Default 15000. */
+  timeout?: number;
+  /** Delay before an unused subscription is dropped. Default 50 ms. */
+  unsubscribeDelayMs?: number;
+  /** 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>;
+}
+
+declare global {
+  interface Window {
+    __ERASPACE__?: EraspaceConfig;
+  }
+}
+
+export function readConfig(): Partial<EraspaceConfig> {
+  return (typeof window !== "undefined" && window.__ERASPACE__) || {};
+}

package/sdk/src/client/connection.ts

@@ -0,0 +1,322 @@
+import { Socket, type Channel } from "phoenix";
+import { signal, effect, batch, type Signal } from "@preact/signals";
+import { applyPatch } from "./result-diff.ts";
+import { EraspaceError } from "./errors.ts";
+import { readConfig, type ClientOptions } from "./config.ts";
+import { subKey } from "./sub-key.ts";
+import { Subscription, type FullResult, type DataMessage } from "./subscription.ts";
+import { RoomConn } from "./room.ts";
+import type { Status } from "./types.ts";
+
+type Fn = (...args: any[]) => any;
+
+export class ClientImpl {
+  readonly app: string;
+  readonly base: string;
+  readonly self = signal("");
+  readonly status = signal<Status>("connecting");
+  readonly version: Signal<number>;
+  private opts: ClientOptions;
+  private socketUrl: string;
+  private socket: Socket | undefined;
+  private channel: Channel | undefined;
+  private joinedOnce = false;
+  private nextSub = 1;
+  private nextMutation = 1;
+  private subs = new Map<string, Subscription>();
+  private subsById = new Map<string, Subscription>();
+  private rooms = new Map<string, RoomConn>();
+  private deployedCbs = new Set<(v: number) => void>();
+
+  constructor(opts: ClientOptions) {
+    const cfg = readConfig();
+    this.opts = opts;
+    this.app = opts.app ?? cfg.app ?? "";
+    if (!this.app) throw new Error("eraspace: createClient() needs an app (window.__ERASPACE__ is missing)");
+    this.base = opts.base ?? cfg.base ?? `/${this.app}/`;
+    this.socketUrl = opts.socket ?? cfg.socket ?? "/socket";
+    this.version = signal(opts.version ?? cfg.version ?? 0);
+  }
+
+  // -- connection -----------------------------------------------------------------------------------------------
+
+  private ensureSocket(): Socket {
+    if (this.socket) return this.socket;
+    const socketOpts: Record<string, unknown> = {
+      params: () => ({ app: this.app }),
+      timeout: this.opts.timeout ?? 15000,
+      ...this.opts.socketOptions,
+    };
+    if (this.opts.transport) socketOpts.transport = this.opts.transport;
+    const socket = new Socket(this.socketUrl, socketOpts as any);
+    socket.onOpen(() => { this.status.value = "open"; });
+    socket.onClose(() => { this.status.value = "closed"; });
+    socket.onError(() => { this.status.value = "closed"; });
+    socket.connect();
+    this.socket = socket;
+    return socket;
+  }
+
+  private ensureChannel(): Channel {
+    if (this.channel) return this.channel;
+    const socket = this.ensureSocket();
+    const channel = socket.channel(`app:${this.app}`, { patches: true, watermarks: true });
+    channel.on("data", (m: DataMessage) => this.onData(m));
+    channel.on("error", (m: { id?: string; name?: string; message?: string }) => {
+      const sub = m.id !== undefined ? this.subsById.get(String(m.id)) : undefined;
+      if (sub) sub.error.value = EraspaceError.from(m);
+    });
+    channel.on("deployed", (m: { version?: number }) => this.onDeployed(m?.version));
+    channel.join().receive("ok", (resp: { self?: string } | undefined) => {
+      if (resp && typeof resp.self === "string") this.self.value = resp.self;
+      // The channel process is new after a reconnect, so every live subscription is sent again.
+      if (this.joinedOnce) this.resubscribeAll();
+      this.joinedOnce = true;
+    });
+    this.channel = channel;
+    return channel;
+  }
+
+  private push<T>(event: string, payload: object): Promise<T> {
+    const channel = this.ensureChannel();
+    return new Promise<T>((resolve, reject) => {
+      channel
+        .push(event, payload, this.opts.timeout ?? 15000)
+        .receive("ok", (resp: T) => resolve(resp))
+        .receive("error", (resp: unknown) => reject(EraspaceError.from(resp)))
+        .receive("timeout", () => reject(new EraspaceError("TimeoutError", `${event} timed out`)));
+    });
+  }
+
+  async call(fn: string, args: unknown[]): Promise<any> {
+    const resp = await this.push<{ value?: unknown }>("call", { fn, args });
+    return resp?.value;
+  }
+
+  close(): void {
+    for (const r of this.rooms.values()) r.channel.leave();
+    this.rooms.clear();
+    this.channel?.leave();
+    this.socket?.disconnect();
+    this.channel = undefined;
+    this.socket = undefined;
+    this.subs.clear();
+    this.subsById.clear();
+    this.status.value = "closed";
+  }
+
+  // -- subscriptions --------------------------------------------------------------------------------------------
+
+  private sendSub(sub: Subscription): void {
+    const oldId = sub.id;
+    const request = ++sub.request;
+    if (request > 1) {
+      this.subsById.delete(oldId);
+      sub.id = String(this.nextSub++);
+      this.subsById.set(sub.id, sub);
+      sub.revision = undefined;
+      this.push("unsub", { id: oldId }).catch(() => {});
+    }
+    this.push<FullResult>("sub", { id: sub.id, fn: sub.fn, args: sub.args,
+      minCommitSeq: Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0)),
+    }).then(
+      (resp) => {
+        if (this.subsById.get(sub.id) !== sub || sub.request !== request) return;
+        this.setServer(sub, resp.value, resp.commitSeq, resp.revision);
+      },
+      (err: EraspaceError) => {
+        if (this.subsById.get(sub.id) === sub && sub.request === request) sub.error.value = err;
+      },
+    );
+  }
+
+  // Messages for one subscription id arrive in order, so only commit watermarks are compared. Revisions
+  // belong to a server cache entry and may restart lower when an identity-dependent query splits.
+  private setServer(sub: Subscription, value: unknown, commitSeq: number, revision: number): void {
+    if (commitSeq < sub.commitSeq) return;
+    batch(() => {
+      sub.server = value;
+      sub.hasServer = true;
+      sub.commitSeq = commitSeq;
+      sub.revision = revision;
+      sub.layers = sub.layers.filter((l) => l.commitSeq === undefined || l.commitSeq > commitSeq);
+      sub.error.value = undefined;
+      sub.recompute();
+    });
+  }
+
+  private onData(message: DataMessage): void {
+    const sub = this.subsById.get(String(message.id));
+    if (!sub || message.commitSeq < sub.commitSeq) return;
+    if ("patch" in message) {
+      if (!sub.hasServer || sub.revision !== message.base) {
+        this.sendSub(sub);
+        return;
+      }
+      try {
+        this.setServer(sub, applyPatch(sub.server, message.patch), message.commitSeq, message.revision);
+      } catch {
+        this.sendSub(sub);
+      }
+    } else {
+      this.setServer(sub, message.value, message.commitSeq, message.revision);
+    }
+  }
+
+  private resubscribeAll(): void {
+    for (const sub of this.subs.values()) this.sendSub(sub);
+  }
+
+  private onDeployed(version: number | undefined): void {
+    if (typeof version === "number") this.version.value = version;
+    this.resubscribeAll();
+    for (const cb of [...this.deployedCbs]) cb(this.version.value);
+    if (this.opts.reloadOnDeploy && typeof location !== "undefined") location.reload();
+  }
+
+  onDeployedCb(cb: (v: number) => void): () => void {
+    this.deployedCbs.add(cb);
+    return () => this.deployedCbs.delete(cb);
+  }
+
+  /** Get or create the subscription for `(fn, args)`. A new sub with no retainers is dropped after a grace period. */
+  acquire(fn: string, args: unknown[]): Subscription {
+    const key = subKey(fn, args);
+    let sub = this.subs.get(key);
+    if (!sub) {
+      sub = new Subscription(String(this.nextSub++), fn, args, key);
+      this.subs.set(key, sub);
+      this.subsById.set(sub.id, sub);
+      this.sendSub(sub);
+    }
+    if (sub.refs === 0) this.scheduleDrop(sub, 1000);
+    return sub;
+  }
+
+  retain(sub: Subscription): void {
+    if (this.subs.get(sub.key) !== sub) {
+      // Dropped in the meantime: bring it back.
+      const existing = this.subs.get(sub.key);
+      if (existing) sub = existing;
+      else {
+        this.subs.set(sub.key, sub);
+        this.subsById.set(sub.id, sub);
+        this.sendSub(sub);
+      }
+    }
+    sub.refs++;
+    if (sub.timer) clearTimeout(sub.timer);
+    sub.timer = undefined;
+  }
+
+  release(sub: Subscription): void {
+    const live = this.subs.get(sub.key);
+    if (!live) return;
+    live.refs = Math.max(0, live.refs - 1);
+    if (live.refs === 0) this.scheduleDrop(live, this.opts.unsubscribeDelayMs ?? 50);
+  }
+
+  private scheduleDrop(sub: Subscription, ms: number): void {
+    if (sub.timer) clearTimeout(sub.timer);
+    sub.timer = setTimeout(() => {
+      sub.timer = undefined;
+      if (sub.refs > 0 || this.subs.get(sub.key) !== sub) return;
+      this.subs.delete(sub.key);
+      this.subsById.delete(sub.id);
+      this.push("unsub", { id: sub.id }).catch(() => {});
+    }, ms);
+  }
+
+  subscribe(fn: string, args: unknown[], onValue: Fn, onError?: Fn): () => void {
+    const sub = this.acquire(fn, args);
+    this.retain(sub);
+    const stop = effect(() => {
+      const err = sub.error.value;
+      const v = sub.value.value;
+      if (err) onError?.(err);
+      else if (sub.hasServer) onValue(v);
+    });
+    return () => {
+      stop();
+      this.release(sub);
+    };
+  }
+
+  // -- mutations ------------------------------------------------------------------------------------------------
+
+  async mutate(fn: string, args: unknown[], optimistic?: Fn): Promise<any> {
+    if (!optimistic) return this.call(fn, args);
+    const mid = this.nextMutation++;
+    const touched = new Set<Subscription>();
+    const store = {
+      get: (name: string, qargs: unknown[]) => this.subs.get(subKey(name, qargs))?.value.peek(),
+      set: (name: string, qargs: unknown[], value: unknown) => this.addLayer(mid, name, qargs, () => value, touched),
+      update: (name: string, qargs: unknown[], updater: Fn) =>
+        this.addLayer(mid, name, qargs, (prev) => (prev === undefined ? prev : updater(prev)), touched),
+    };
+    try {
+      batch(() => optimistic(store, ...args));
+      const { value, commitSeq } = await this.push<{ value: unknown; commitSeq?: number }>("call", { fn, args });
+      const timeout = this.opts.optimisticTimeoutMs ?? 2000;
+      for (const sub of touched) {
+        // Only mutations report a commit. Without one, no watermark can cover the layer.
+        if (typeof commitSeq !== "number") {
+          setTimeout(() => this.dropLayers(sub, mid), timeout);
+          continue;
+        }
+        for (const l of sub.layers) {
+          if (l.mid !== mid) continue;
+          l.commitSeq = commitSeq;
+        }
+        if (sub.commitSeq >= commitSeq) this.dropLayers(sub, mid);
+        else setTimeout(() => {
+          if (sub.layers.some((l) => l.mid === mid) && this.subs.get(sub.key) === sub) this.sendSub(sub);
+        }, timeout);
+      }
+      return value;
+    } catch (e) {
+      for (const sub of touched) this.dropLayers(sub, mid);
+      throw e;
+    }
+  }
+
+  private addLayer(mid: number, name: string, args: unknown[], apply: Fn, touched: Set<Subscription>): void {
+    const sub = this.subs.get(subKey(name, args));
+    if (!sub) return;
+    sub.layers.push({ mid, apply });
+    touched.add(sub);
+    sub.recompute();
+  }
+
+  private dropLayers(sub: Subscription, mid: number): void {
+    const before = sub.layers.length;
+    sub.layers = sub.layers.filter((l) => l.mid !== mid);
+    if (sub.layers.length !== before) sub.recompute();
+  }
+
+  // -- rooms ----------------------------------------------------------------------------------------------------
+
+  acquireRoom(room: string): RoomConn {
+    const topic = `room:${this.app}:${room}`;
+    let r = this.rooms.get(topic);
+    if (!r) {
+      r = new RoomConn(this.ensureSocket(), topic, this.self);
+      this.rooms.set(topic, r);
+    }
+    if (r.timer) clearTimeout(r.timer);
+    r.timer = undefined;
+    r.refs++;
+    return r;
+  }
+
+  releaseRoom(r: RoomConn): void {
+    r.refs = Math.max(0, r.refs - 1);
+    if (r.refs > 0) return;
+    if (r.timer) clearTimeout(r.timer);
+    r.timer = setTimeout(() => {
+      if (r.refs > 0 || this.rooms.get(r.topic) !== r) return;
+      this.rooms.delete(r.topic);
+      r.channel.leave();
+    }, this.opts.unsubscribeDelayMs ?? 50);
+  }
+}

package/sdk/src/client/errors.ts

@@ -0,0 +1,28 @@
+/**
+ * An error raised by a server handler (or the transport). `name` is the server error name, for example `Error`,
+ * `TypeError`, or `TimeoutError` for a call that got no reply in time.
+ */
+export class EraspaceError extends Error {
+  readonly data?: unknown;
+  constructor(name: string, message: string, data?: unknown) {
+    super(message);
+    this.name = name;
+    if (data !== undefined) this.data = data;
+  }
+
+  static from(payload: unknown, fallback = "Request failed"): EraspaceError {
+    if (payload && typeof payload === "object") {
+      const p = payload as { name?: unknown; message?: unknown; data?: unknown };
+      return new EraspaceError(
+        typeof p.name === "string" ? p.name : "Error",
+        typeof p.message === "string" ? p.message : fallback,
+        p.data,
+      );
+    }
+    return new EraspaceError("Error", typeof payload === "string" ? payload : fallback);
+  }
+}
+
+export function isEraspaceError(e: unknown): e is EraspaceError {
+  return e instanceof EraspaceError;
+}

package/sdk/src/client/index.ts

@@ -0,0 +1,35 @@
+// eraspace/client: typed hooks over Phoenix Channels, routing, and mount().
+export {
+  createClient,
+  readConfig,
+  subKey,
+  type ClientOptions,
+  type MutationOptions,
+  type OptimisticStore,
+  type PaginatedQueryName,
+  type PaginatedQueryResult,
+  type PresenceEntry,
+  type Room,
+  type EraspaceClient,
+  type EraspaceConfig,
+} from "./client.ts";
+export { EraspaceError, isEraspaceError } from "./errors.ts";
+export type { StorageClient, UploadedObject } from "./storage.ts";
+export { mount, ErrorBoundary, type ErrorBoundaryProps, type MountOptions } from "./mount.ts";
+export {
+  LocationProvider,
+  Router,
+  Routes,
+  Route,
+  Link,
+  useLocation,
+  useNavigate,
+  useParams,
+  useRoute,
+  stripBase,
+  withBase,
+  type LocationValue,
+  type RouteProps,
+} from "./router.ts";
+export { signal, computed, effect, batch, useSignal, useComputed, useSignalEffect, type Signal, type ReadonlySignal } from "@preact/signals";
+export type { Id, Doc, PaginationOptions, PaginationResult } from "../server/index.ts";

package/sdk/src/client/mount.ts

@@ -0,0 +1,45 @@
+import { Component, h, render, type ComponentChildren, type ComponentType } from "preact";
+import { LocationProvider } from "./router.ts";
+
+export interface ErrorBoundaryProps {
+  children?: ComponentChildren;
+  /** Render a fallback for `error`. `retry` re-renders the subtree. */
+  fallback?: (error: Error, retry: () => void) => ComponentChildren;
+}
+
+/** Catches render errors (including query errors thrown by `useQuery`) in its subtree. */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, { error: Error | null }> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: unknown) {
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+  componentDidCatch(error: unknown) {
+    console.error(error);
+  }
+  retry = () => this.setState({ error: null });
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    if (this.props.fallback) return this.props.fallback(error, this.retry);
+    return h(
+      "div",
+      { role: "alert", style: "font-family:system-ui,sans-serif;padding:1.5rem;max-width:40rem;margin:2rem auto" },
+      h("p", { style: "font-weight:600;margin:0 0 .5rem" }, "Something went wrong"),
+      h("pre", { style: "white-space:pre-wrap;color:#b91c1c;margin:0 0 1rem" }, `${error.name}: ${error.message}`),
+      h("button", { type: "button", onClick: this.retry, style: "padding:.375rem .75rem;border:1px solid #ccc;border-radius:.375rem" }, "Retry"),
+    );
+  }
+}
+
+export interface MountOptions {
+  /** Provide the app-relative location for `useLocation`, `<Link>` and `<Router>` (default true). */
+  router?: boolean;
+}
+
+/** Render `App` into `#app` (or `target`) inside a LocationProvider and an ErrorBoundary. */
+export function mount(App: ComponentType<{}>, target?: Element | null, options: MountOptions = {}): void {
+  const el = target ?? document.getElementById("app");
+  if (!el) throw new Error("eraspace: mount() could not find #app");
+  const app = h(ErrorBoundary, null, h(App, null));
+  render(options.router === false ? app : h(LocationProvider, null, app), el);
+}