Ephemeral Sheets

An ephemeral sheet is a render-only sheet built from a URL or catalog template — no server-side persistence. Used for shareable demos, the home dashboard, and the docs CLI.

Catalog templates

import { BUILTIN_SHEET_CATALOG, ephemeralFromCatalog } from "@tento-lona/sheets";

const sheet = await ephemeralFromCatalog(":home", { /* options */ });

Built-in catalog entries:

The accessor consults the catalog when the server returns null for a sheet key — i.e. the URL /sheet/:home opens the ephemeral home sheet client-side instead of a 404.

URL serialization

import { EphemeralSheetSerde } from "@tento-lona/sheets";

// Parse a URL into an ephemeral spec:
const parsed = EphemeralSheetSerde.parse(new URL("https://lona.so/sheet?title=Sprint&r0.type=task&r0.label=Frontend"));

// Build a sheet from the parsed spec:
const sheet = await Sheet.from(parsed.toRawSheet(), { backend });

// Round-trip back to URL:
const url = EphemeralSheetSerde.serialize(parsed);

Two URL formats:

• Flat-indexed — ?title=...&timeScale=...&d=YYYY-MM-DD&rN.type=...&rN.label=...&rN.ts=...&rN.key=... Ergonomic for hand-constructed URLs (3-4 row sheets).
• JSON — ?e=<encodeURIComponent(JSON)>. Used for complex rows with nested attributes or shape-tagged cells.

See /docs/lona-js/ephemeral-urls for the complete grammar.

Use in tests

The CLI's snapshot harness uses ephemeral catalog templates as ready-made fixtures:

import { Sheet, ephemeralFromCatalog } from "@tento-lona/sheets";

const sheet = await ephemeralFromCatalog(":home");
const tree = buildHydratedTree(sheet);
assertSnapshot(serializeTree(tree), "home-fixture.snap");

Every commit re-runs these snapshots; drift means a builtin template changed semantically.

Why no backend writes?

Ephemeral sheets aren't stored — they exist only in the client. setCell / addRow mutations are visible in the running session but discarded on reload. App code that wants persistence opens a real sheet via LonaSdk.Client.open(sheetId).

See also

• Sheet & SheetRow — Sheet.from(raw, ...) is the same entry point for ephemeral + persisted sheets
• /docs/lona-js/ephemeral-urls — the URL grammar
• __user_tests/row-type-migration/ — fixture catalog used by the CLI snapshot tests