The README keeps the pitch, quick start, and constraints; everything the docs site now covers moves one step away behind absolute lofi.host links so it stays accurate on JSR. .env.example gains the documented LOFI_BASE_PATH name and the environment contract test expects all five.
- commit
- 0185b2eabfafdda117fb7f1eee981ec6e5c3169b
- parent
- fa6930656f8cab8250a20ec86e658814707fb5c0
- author
- Dami <dami.etoile@gmail.com>
| M | .env.example | 4 | + |
| M | README.md | 182 | +++++------------------------- |
| M | tools/ | 2 | +- |
@@ -1,3 +1,7 @@
1+# Public deployment base. Blank defaults to an origin-root deployment (/); use2+# /my-app/ when the static host mounts the build below the origin root.3+LOFI_BASE_PATH=4+15 # lofi's client-visible Jazz configuration. The runtime maps this complete pair26 # to framework-prefixed vendor names internally; product UI never reads it.37 JAZZ_APP_ID=@@ -10,8 +10,8 @@ durable local data. Users start with a private, on-device account—no sign-in o
1010 can add [Jazz](https://jazz.tools)-powered sync and recovery later without replacing that identity1111 or rewriting product code.1212 13-[Documentation](docs/README.md) · [JSR package](https://jsr.io/@nzip/lofi) ·14-[GitHub](https://github.com/FelineStateMachine/lofi) · [MIT License](LICENSE)13+[Documentation](https://lofi.host/docs) · [API reference](https://lofi.host/api) ·14+[JSR package](https://jsr.io/@nzip/lofi) · [MIT License](LICENSE)1515 1616 ## Quick start1717 @@ -28,175 +28,49 @@ reload the page to see that it remains in durable local storage. Once the page i
2828 the network and you can keep reading and writing data locally.2929 3030 The generated app starts in local-only mode. You do not need an account, a backend, or an `.env`31-file to begin building.31+file to begin building. To provision managed Jazz sync, scaffold with `--sync` or run32+`deno task jazz:provision` later; either way users keep the account they already have.3233 33-Continue with the [generated-app guide](docs/getting-started.md) when you are ready to replace the34-task example with your own schema, permissions, hook, and UI.34+Continue with [Getting started](https://lofi.host/docs/getting-started) when you are ready to35+replace the task example with your own schema, permissions, hook, and UI.3536 3637 ## What you get3738 38-- **Local-first data.** The UI reads from durable local storage instead of waiting on the network.39- Storage failures are surfaced rather than silently falling back to memory.40-- **Identity from the first launch.** Each user begins with a private on-device account, even when41- the app has no sync service configured.42-- **Optional sync and recovery.** Users can make that same account portable when you connect the app43- to managed Jazz sync, using a recoverable passkey when available and a recovery phrase as the44- portable fallback.45-- **Narrow collaboration templates.** Private resources, direct sharing, and fixed-role groups sit46- behind a small `@nzip/lofi/access` API while raw Jazz permissions remain available as an escape47- hatch.48-- **A narrow authoring surface.** Product code owns the schema, permissions, configuration, Preact49- islands, styles, and tests. lofi owns storage, identity, sync, lifecycle, and PWA plumbing.50-- **Local-first test helpers.** Playwright-backed fixtures cover offline writes, multiple clients,51- convergence, and readiness without hand-timed sleeps.52-- **Explicit mobile support.** Unsupported browsers receive a clear explanation instead of a53- partially working app that risks data loss.54-55-## Add sync and account recovery56-57-To provision sync while scaffolding:58-59-```sh60-deno run -A jsr:@nzip/lofi/create --sync my-app61-```62-63-For an existing generated project:64-65-```sh66-deno task jazz:provision67-```68-69-Provisioning creates a managed Jazz app and writes the public `JAZZ_APP_ID` and `JAZZ_SERVER_URL`70-configuration to the project's `.env`. Server-only credentials remain outside client output.71-72-Once sync is configured, a user can choose to back up and sync their existing account, then recover73-it with a recoverable passkey or a 24-word recovery phrase. Passkey portability depends on the74-browser, provider, and configured RP-ID; the phrase remains the provider-independent fallback.75-Enabling sync preserves data created while the app was local-only because the account identity does76-not change.39+- **Local-first data** read from durable local storage; failures are surfaced, never silently40+ swapped for memory.41+- **Identity from the first launch**, with optional sync and account recovery via passkey or a42+ 24-word phrase.43+- **Narrow collaboration templates** — private, direct-share, and fixed-role group access behind a44+ small [`@nzip/lofi/access`](https://lofi.host/api/access) API.45+- **Local-first test helpers** — Playwright-backed two-client fixtures for offline writes and46+ convergence.47+- **An explicit authoring boundary**: product code owns schema, permissions, config, islands,48+ styles, and tests; lofi owns storage, identity, sync, lifecycle, and PWA plumbing.49+50+The [documentation](https://lofi.host/docs) covers all of this in depth: guides,51+[commands](https://lofi.host/docs/reference/commands),52+[project layout](https://lofi.host/docs/reference/project-layout),53+[installed-app recipes](https://lofi.host/docs/recipes),54+[examples](https://lofi.host/docs/examples/shared), and the55+[identity and recovery model](https://lofi.host/docs/auth-identity).7756 7857 ## Where lofi fits7958 8059 lofi is designed for mobile web apps where offline operation is a requirement, not a best-effort81-enhancement. It is a good fit when you want Deno tooling, an Astro shell, Preact islands, and an82-opinionated boundary between product code and local-first infrastructure.83-84-Keep these current constraints in mind:60+enhancement. Keep these current constraints in mind:8561 8662 - lofi is an early, pre-1.0 release.87-- The data layer is Jazz 2 alpha and deliberately pinned to a reviewed version.63+- The data layer is Jazz 2 alpha and deliberately pinned to a reviewed version64+ ([stack and version policy](https://lofi.host/#stack)).8865 - The supported browser floors are Android Chrome 148+ and iOS Safari 16.4+.8966 - Recovery is user-controlled: lofi does not retain recoverable account material on the server, so9067 the recovery phrase must be kept safe.9168 92-## Project anatomy93-94-A generated project keeps application source separate from the versioned framework package:95-96-```text97-my-app/98-├── deno.json # tasks and one pinned @nzip/lofi version99-├── public/ # manifest and replaceable product icons100-├── src/101-│ ├── app.ts # app, storage, sync, and passkey configuration102-│ ├── schema.ts # persisted data model103-│ ├── permissions.ts # private, shared, or group access policy104-│ ├── islands/ # interactive Preact product UI105-│ ├── layouts/ # document shell106-│ ├── pages/ # Astro routes107-│ └── styles/ # product styling108-├── tests/ # app tests and local-first browser journeys109-├── .lofi/ # generated package tooling (ignored)110-└── dist/ # generated production PWA (ignored)111-112-@nzip/lofi # versioned storage, identity, sync, PWA, and tooling113-```114-115-Product work stays in `schema.ts`, `permissions.ts`, `app.ts`, `pages/`, `layouts/`, `islands/`, and116-`styles/`. Framework behavior is imported from `@nzip/lofi`; upgrading the package updates runtime117-code without copying it into your source tree.118-119-See the [exact generated-project map](docs/reference/project-layout.md) for every source-controlled120-path, its ownership category, and the separately regenerated `.lofi/` and `dist/` trees.121-122-## Sharing and groups123-124-`@nzip/lofi/access` provides schema helpers, policy templates, app-scoped sharing identities, and125-operations for direct shares and fixed-role groups. Collaboration requires configured sync; the126-helpers fail explicitly in local-only mode rather than implying that another device can see local127-data.128-129-Start with the [account and access API](docs/reference/access.md), then copy the130-[direct-share](docs/examples/shared.md) or [group](docs/examples/group.md) example. The templates131-compile ordinary Jazz policies, so unusual authorization models can still use raw Jazz schema and132-permission APIs.133-134-## Optional installed-app recipes135-136-OS-facing capabilities stay out of the starter until the product opts in. The137-[installed-app recipe catalog](docs/recipes/README.md) contains tested, isolated entrypoints for Web138-Share, launch handling, file-import previews, custom-protocol links, presentation-only companion139-discovery, reciprocal cross-origin app-window scope, and desktop titlebar geometry. Each keeps140-manifest changes opt-in and documents validation, behavior, and fallbacks.141-142-## Testing local-first behavior143-144-`@nzip/lofi/testing` provides Playwright-backed helpers for behavior that is difficult to test with145-ordinary unit tests: two-client fixtures, concurrent offline writes, convergence, readiness waits,146-and secret-free failure artifacts.147-148-Every generated project includes a worked example at `tests/convergence_e2e_test.ts`.149-150-## Commands151-152-Every generated project exposes these tasks as `deno task <name>`.153-154-### Everyday development155-156-| Command | What it does |157-| --------- | ----------------------------------------------------------------- |158-| `dev` | Runs the Astro development server and prints runtime state. |159-| `doctor` | Checks readiness without printing configuration or secret values. |160-| `test` | Runs the deterministic local-first test suite. |161-| `build` | Creates a static production build in `dist/`. |162-| `preview` | Serves the production build locally. |163-164-### Sync, schema, and deployment165-166-| Command | What it does |167-| --------------------------------------- | ------------------------------------------------- |168-| `jazz:provision` | Creates a managed Jazz app and configures `.env`. |169-| `schema:validate` / `schema:deploy` | Validates and publishes the Jazz schema. |170-| `migrations:create` / `migrations:push` | Authors and pushes schema migrations. |171-| `deploy` / `deploy:create` | Hosts the static build on Deno Deploy. |172-173-## Stack and version policy174-175-| Layer | Choice | Pinned at |176-| ---------- | ------------------------------------------ | ------------------- |177-| Data/sync | Jazz 2, CRDTs, OPFS | `2.0.0-alpha.53` |178-| UI runtime | Preact islands with a thin adapter | Preact 10 / Astro 7 |179-| Shell | Fully prerendered Astro, statically hosted | Astro 7 |180-| Toolchain | Deno tasks and npm compatibility | Deno 2.9 |181-182-Version pins are deliberate. Because the data layer is an alpha, every upgrade is reviewed and183-validated before it becomes part of the generated project.184-185-## Identity and recovery model186-187-A new app opens immediately on a private, on-device account. When managed sync is configured, the188-user can back up and sync that same account and recover it with a recoverable passkey or the189-recovery phrase. The phrase remains the portable bearer-secret fallback; keeping it safe is the190-user's responsibility.191-192-See [Sync and recovery](docs/sync-and-recovery.md) for setup and shipping guidance, and193-[Local-first accounts: open now, back up later](docs/auth-identity.md) for the detailed account194-states, recovery guarantees, custody model, and optional passkey-based protection at rest.195-19669 ## Developing lofi itself19770 19871 This repository is the framework's development monorepo. `package/` contains the `@nzip/lofi`199-source, while `apps/reference/` is the reference app against which the generator is validated.72+source, `apps/reference/` is the reference app against which the generator is validated, and73+`website/` builds the [lofi.host](https://lofi.host) documentation site.20074 20175 See [CONTRIBUTING.md](https://github.com/FelineStateMachine/lofi/blob/main/CONTRIBUTING.md) for the20276 repository workflow and the@@ -24,6 +24,6 @@ Deno.test("real environment files are ignored and untracked", async () => {
2424 Deno.test("environment example contains names but no values", async () => {2525 const example = await Deno.readTextFile(".env.example");2626 const assignments = example.split("\n").filter((line) => /^[A-Z][A-Z0-9_]*=/.test(line));27- assert(assignments.length === 4, "expected four documented environment variables");27+ assert(assignments.length === 5, "expected five documented environment variables");2828 assert(assignments.every((line) => line.endsWith("=")), ".env.example must not contain values");2929 });