Keep the core. Swap the shell.
Your web app becomes your mobile app’s interface. A small Flutter host ships through the stores once. Every UI release after that is signed, tried on each phone and rolled back on its own if it fails to start. Data lives in native SQLite, so the app works offline from the first launch.
npm create valence@latestA reference app running on a simulated phone. The console follows the update rules in the spec, with time sped up: release a bundle, restart the phone, ship a broken build and watch it revert.
sync.now over the bridge.
Next
A small native host. Everything users see is your web build.
The Flutter host goes through store review and rarely changes. It serves your web build from the phone itself, keeps data in SQLite, and checks for new signed bundles in the background.

| What changed | How it reaches users | Store review |
|---|---|---|
| UI, copy, styles, web logic | A signed over-the-air bundle with a staged rollout: 10%, then 50%, then 100% | Not needed |
| Data, or a fix to bundled data | Sync. The fix is a new row with a higher sequence number. | Not needed |
| A new native capability or feature area | A normal app release | Required |
Signed on your laptop, verified on every phone.
A release is a set of content-addressed files, a manifest signed with Ed25519, and a small pointer that says which manifest is live. Phones download only the files whose hash changed.

- 01
Build and sign
valence bundlehashes every file, writes the manifest with the page’s CSP, and signs it. It refuses any native code. - 02
Upload, pointer last
Files go up first, then the manifest and its
.sig, then the pointer. A phone never sees a manifest whose files are missing. - 03
Verify in a fixed order
Signature, then
appId, thenseqagainst the pointer, then the floor, thenrequires, then every path, hash and size. Any failure stops the update. - 04
Try it on the next launch
The new bundle runs as a trial. Your web app calls
ready()once it has painted — on every path, including a first-run screen — and that call commits the update. - 05
Commit, or go back
No
ready()within 15 seconds of foreground time means the phone returns to the last good version. A second failure marks the bundle bad. The bundle built into the app is the final fallback.
{
"format": 1,
"appId": "app.valence.reference",
"seq": 43,
"version": "2026.10.16+43",
"floor": 40,
"requires": { "bridge": 1, "data": { "schedule": 2 } },
"entry": "index.html",
"csp": "default-src 'self'; script-src 'self' 'sha256-…'; frame-src 'none'",
"urgent": false,
"routes": ["/", "/schedule", "/settings"],
"files": {
"index.html": { "h": "9f2c41…e41a", "n": 1834 },
"_app/immutable/entry/start.js": { "h": "03bd7e…a9c0", "n": 48210 }
},
"keyId": "k1"
}
seq only goes up. It is the bundle’s identity; version is for display.floor is the lowest seq a phone may run after this one. Raise it after a security fix.csp is computed at build time and sent as the entry page’s header.routes are compared with the last store-reviewed build to catch purpose drift.
Rolling back means rolling forward. Release the last good commit again. It gets a new, higher seq, so every phone moves forward to it. Phones still trying the bad bundle revert on their own.
Using an existing REST API? Keep selected responses offline with a store-enabled cache. Synced data and user edits retain their own histories.
The first launch works with no network at all.
The app ships with seed.db, so every screen has data before the phone has ever been online. After that, the phone asks for everything after the last row it has.
- usn 1239schedule/day-2Day 2 sessionsseed
- usn 1240schedule/day-1Day 1, offline talk in Hall Bseed
- usn 1241schedule/day-2Day 2, adds a workshop at 14:00new
- usn 1242schedule/day-1Day 1, offline talk moved to Hall C, lightning talks at 16:30fix
CREATE TABLE kv (bucket, schema, key, value, usn, deleted) -- JSON values CREATE TABLE bucket (name, schema, max_usn, synced_at) -- where each pull resumes CREATE TABLE outbox (id, bucket, key, value, deleted, created_at) CREATE TABLE prefs (key, value) PRAGMA journal_mode = WAL;
- Pull by sequence number. Rows arrive in order and each page is applied in one transaction, so a dropped connection never leaves half a page.
- Corrections are just newer rows. A wrong room in the seed is fixed by a row with a higher
usn. There is no separate patch system. - Local writes win until acknowledged.
data.putwrites the row and an outbox entry together. Push is idempotent by op id, and the server keeps the last write per key. - The UI and its data move together. Read-only data is stored per schema version, so a trial that reverts still has the data its old UI expects.
- No backend needed for public data. Publish static chunks on a CDN and phones fetch only the chunks above what they already have.
One schema, so Dart and TypeScript can’t drift apart.
You describe the bridge once in bridge.schema.json. Codegen writes the Dart handler interface for the host and the TypeScript types for your web app. CI runs codegen --check and fails when they are stale.
{
"version": 1,
"methods": {
"app.ready": { "since": 1, "params": {}, "returns": "void" },
"data.get": { "since": 1, "params": { "bucket": "string", "key": "string" }, "returns": "json?" },
"data.list": { "since": 1, "params": { "bucket": "string", "prefix": "string?", "limit": "int?" }, "returns": "Row[]" },
"data.put": { "since": 1, "params": { "bucket": "string", "key": "string", "value": "json?" }, "returns": "void" },
"sync.now": { "since": 1, "params": { "buckets": "string[]?" }, "returns": "SyncResult" }
},
"events": {
"sync.changed": { "since": 1, "payload": { "buckets": "string[]" } },
"bundle.updateReady": { "since": 1, "payload": { "seq": "int" } }
},
"types": {
"Row": { "key": "string", "value": "json", "usn": "int" },
"SyncResult": { "buckets": "string[]", "changed": "int", "offline": "bool", "reason": "string?" }
}
}
// GENERATED by valence codegen from valence/bridge.schema.json. Do not edit. const hostBridgeVersion = 1; abstract interface class BridgeHandlers { Future<void> appReady(); Future<Object?> dataGet(DataGetParams p); Future<List<Row>> dataList(DataListParams p); Future<void> dataPut(DataPutParams p); Future<SyncResult> syncNow(SyncNowParams p); } /// Decodes one message from the JS channel, checks the per-launch nonce, /// calls the handler and returns the reply JSON. Never throws. Future<String> bridgeDispatch(BridgeHandlers h, String raw, {required String nonce}) /// The built-ins, implemented by delegating to the valence package. /// Extend it and only your own methods are left to write. abstract class ValenceBuiltins { Future<Object?> dataGet(DataGetParams p) async => valence.dataGet(p.bucket, p.key); // … app.*, data.*, prefs.*, sync.*, secure.*, auth.*, open.external, bundle.* }
<script lang="ts"> import { onMount } from 'svelte'; import { on, call, ready } from '$lib/valence/bridge.g'; let day = $state<unknown>(null); const load = async () => (day = await call('data.get', { bucket: 'schedule', key: 'day-1' })); onMount(async () => { try { await load(); } finally { await ready(); } // every path that paints: this commits a trial bundle return on('sync.changed', ({ buckets }) => buckets.includes('schedule') && load()); }); // call('data.get') with no params does not compile. In a plain browser, // calls go to your web shim, so the same build is also your website. </script>
Only your own pages can call it
The app’s loopback server writes a per-launch nonce into the entry page. Messages without it are refused, so a page served by anything else gets no bridge.
Strict decoding on the host
Unknown fields, wrong types and non-JSON input are rejected before a handler runs. Replies are built with jsonEncode, never by joining strings into a script.
A locked frame
The WebView stays on 127.0.0.1, other URLs open in the browser, and there are no off-origin subframes. The page’s CSP comes from the signed manifest.
Allowed by both stores, within limits.
Downloading JavaScript into a WebView is permitted on iOS and Android if it keeps the app’s purpose. Apple also bars downloaded code that adds features (Guideline 2.5.2), so new features ship with a store build. Valence checks the parts a machine can check. App review has the final say.
“Interpreted code may be downloaded to an Application but only so long as such code: (a) does not change the primary purpose of the Application … (b) does not bypass signing, sandbox, or other security features of the OS; and (c) … does not create a store or storefront for other Applications.”
“An app distributed via Google Play may not modify, replace, or update itself using any method other than Google Play’s update mechanism. … This restriction does not apply to code that runs in a virtual machine or an interpreter where either provides indirect access to Android APIs (such as JavaScript in a webview or browser).”
Native code can never be downloaded
The bundler rejects these anywhere in a path:
.so.dex.jar.apk.aab.ipa.dylib.framework.a.o.class.exe.dllPurpose drift is flagged
Each release’s top-level routes are compared with the bundle you last submitted to the store. A new route raises a warning, because a new feature area should go out with a store update.
Real native value
To avoid the “repackaged website” rejection, the host ships at least two of: offline cold start, notifications, a home-screen widget, share and haptics, biometric lock.
First launch never waits
The built-in bundle and the seed make the app fully usable offline, so a first launch never blocks on a download.
No untrusted pages
Play flags a JavaScript interface that loads untrusted content. The bridge only answers pages from the app’s own local server.
A CDN can’t push code
Every manifest is signed and every file is checked against its hash. Someone who controls the CDN can freeze phones on their current bundle, but can’t serve new code.
Policy text retrieved 2026-10-14 and 2026-10-16. Not legal advice. The exact quotes and the rules built on them are in the store policy guide.
One command from your project root.
The wizard does everything that doesn’t need AI in a few seconds. It is safe to run again: it never overwrites your config, your schema or files you’ve edited.
$ npm create valence@latest # then, in Claude Code $ claude "/valence init" # later $ npx create-valence@latest update # CLI, skill and agents $ npx create-valence doctor --tests # mechanical checks # no Claude Code? the CLI is vendored into your repo $ node valence/valence.mjs bundle $ node valence/valence.mjs codegen --check
- 01Detects your web app (SvelteKit, Next.js static export, Astro or Vite), its package manager, an existing Flutter project and your app id.
- 02Writes
valence.config.jsonand the bridge schema, and declares@getvalence/bridgein your web app. - 03Generates your Ed25519 signing key outside the repo, and the typed bridge code.
- 04Installs the
/valenceskill and its agents into.claude/. - 05Offers to launch
/valence init, which adds thevalencepackage, writes the host setup, wires your web app, runs the tests and has a separate reviewer agent check the result.
/valence initAdd the host package, keys, bridge, offline store and tests./valence releaseBuild, sign and stage a bundle. Uploads only after you confirm./valence doctorCheck versions, store policy, signatures and tests.Before you ship it.
- How does my app ask for OS permissions?
- Schema 10 adds checks, foreground requests, app settings and resume changes for seven permission kinds. The store build compiles its allowlist and native declarations; an OTA cannot expand it. See Permissions for status handling and setup. iOS is experimental and untested.
- How do I show unsynced edits or read several records?
- Schema 3 adds
sync.statusfor the outbox count, including deletes, anddata.getManyfor up to 500 keys in one call. The status reads local observations without starting a sync. See offline tooling for older-host guards, seed schemas, channels and mechanical diagnostics. - How does my page know it was backgrounded, or that an update is waiting?
- Schema 6 adds three events and two methods.
app.lifecyclegives you four states rather than Flutter’s five —foreground,background,inactive,detached— so you can save a draft when the user swipes away, which a page could not hear about before.app.onlinereports what the OS says about network interfaces, which is not reachability: use it to decide whether to try, andSyncResult.reasonto say whether the last attempt worked.sync.donefires after every sync the host runs on its own, including the ones that moved nothing, so a “last synced” line stays true.bundle.statussays why an update declined — one of eleven named reasons, so “rolled out to 10% of installs”, “still pulling the data this release needs” and “this release is signed with the wrong key” stop being the same silence. Andbundle.updateReadypushes you theseqthe moment a bundle is ready, so “an update is waiting” appears without polling for it. Foreground connectivity reports also retry the signed update check, including Wi-Fi/cellular handovers; an offline result describes the last attempt until another check completes. Update checks after reconnect. Lifecycle, connectivity and updates. - Will Apple or Google reject an app built this way?
- Both stores allow JavaScript running in a WebView to be downloaded, as long as it doesn’t change the app’s advertised purpose, bypass OS security or create a storefront, and Apple expects new features to go through review. Valence guards against the common rejections: the host must add real native value, new top-level routes are flagged for a store release and the bridge is locked to the app’s own pages. Reviewers judge each app, so no tool can promise approval.
- What happens to users when a release is broken?
- Each phone tries a new bundle as a trial on the next launch. If the page doesn’t call
ready()within 15 seconds of foreground time, or the app dies first, the phone goes back to the last good version. After a second failure the bundle is marked bad on that phone. Start with a 10% rollout and most users never see it. - What happens if the phone runs out of memory?
- Your page runs in a separate process from the app, the way a browser gives each tab its own — and on Android, when memory runs short, the system kills that one first. No released
webview_flutter_androidlets an app say “I handled it”, so the app is closed too and the user reopens it. Valence 0.4 cannot prevent that on Android and says so plainly, including how to recognise it in a log; a fix needs native code and is planned for 0.5. Your data is safe either way, because it lives in SQLite. One thing to plan for: because no app code runs, the next launch cannot tell this apart from a crash in the release itself, so an eviction while a new release is on trial costs it one of its two strikes — start rollouts at 10%. - Can a compromised CDN push code to my users?
- No, as long as your signing key stays private. Every manifest is signed, and every file is checked against its hash and size. The pointer is unsigned so you can change the rollout without re-signing; someone who controls it can freeze phones on their current bundle or change who is in the rollout, and nothing more.
- Does my place survive Android reclaiming the app?
- Valence restores the route and a small UI draft when you return to a retained task. Explicit task closure starts fresh. State restoration explains the limits; iOS remains experimental and untested.
- Can a link open a screen in my app?
- Android App Links and custom schemes can open a local route in your signed UI. The store build fixes which origins are accepted; your web router handles the path. Set up deep links, including website association files. iOS support is experimental and untested.
- Can I use hot reload inside the app?
- Use
valence devwith a debug Flutter build. Vite HMR or Fast Refresh updates the page while the native bridge remains available. Release and profile builds exclude the dev proxy. Use test accounts and a separate development app id. Live development guide. - Can I use my existing REST API?
- Use
http.requestfor online actions: the native host calls your API without WebView CORS restrictions, attaches your user token, and enforces the API origins compiled into the app. For larger JSON responses, grant a bounded response size in a store build; the bridge reply limit still applies. A failure says which kind it was: no network, a timeout, or something it cannot tell apart. A store build can opt one origin into a host-held cookie jar for cookie-paired CSRF; bounded persistent sessions need a separate compiled grant. For selected offline responses, enable revision-18 REST caching in the store build. Server-managed datasets and queued user writes use the sync protocol. The backend guide includes a reference Node adapter. - Can my app have user accounts?
- Yes, and you keep your own login. Your web app authenticates against your API however it already does, then hands the host the token with
auth.setToken. The host keeps it in the Android Keystore — never in the database — and sendsAuthorization: Beareron every sync of the user’s own data, including the background runs your JavaScript is not awake for. The page can replace or clear the token but never read it back, and a 401 raisesauth.expiredso you can refresh or show a login screen. Valence is not an identity provider: sessions, refresh and password resets stay your API’s job. - Can my backend send push notifications?
- Opt-in Firebase messaging adds typed notification events, taps, and data-only sync hints. Android background notifications support images. This new capability still needs a maintainer Firebase project for device validation; iOS/APNs is experimental and untested. Configure remote push in a store build.
- Does it work on iOS?
- Not yet, honestly. Android is the tested platform: everything in the spec has been built and run on Android phones and emulators. The iOS paths are specified and implemented — App Groups for the widget, the backup exclusion, rebinding the loopback port on resume, background sync through
BGTaskScheduler— but nobody has run them, because there is no Apple hardware on the machines Valence is developed on. Treat iOS as experimental and untested, and expect to do the first run yourself. - Can I fix a bug in the host without touching every app?
- Yes — that is why the runtime is a package. Before 0.4 the host was generated into each app, so one bug in the rollback loop meant four hand-applied fixes in four apps. Now the OTA verification, the rollback state machine, the SQLite store and the bridge trust boundary live in
valenceand@getvalence/bridge, and a fix reaches an app withflutter pub upgradeornpm update. The rule that makes it work: never vendor or patch either package. - Which web frameworks work?
- Any SPA that builds to static files. The wizard detects SvelteKit, Next.js static export, Astro and Vite. When
window.Valenceis absent, bridge calls go to a web shim, so the same build is also your website. - Do I need Claude Code?
- No. The host runtime is the
valencepackage and the web client is@getvalence/bridge, so there is no large implementation job either way —flutter pub add valence, then about twenty lines ofmain.dart. The CLI is zero-dependency Node and the wizard vendors it into your repo, so CI needs no install. Claude Code adds the/valenceworkflows that wire it up, run the tests and review the result. - Does the interface follow phone accessibility settings?
- The host supplies safe-area CSS variables, Android system text zoom and dark-mode, high-contrast and reduced-motion signals. Your page still needs semantic HTML, readable contrast and usable touch targets. The accessibility guide explains the setup and device checks. iOS is experimental and untested.
- Can the web UI schedule local reminders?
- Yes. Schema 11 includes native reminders with honest exact/inexact timing, images, action buttons and cold-start taps, and schema 16 adds
notify.pendingIds()so a full queue can still be read back for a refill. Enable the group in a store build and install the native setup. Local reminder setup. iOS remains experimental and untested. - Can I add my own native features?
- Package them as a Valence plugin: a Dart handler, a namespaced schema fragment, matching npm types and native setup notes. Codegen merges it into your typed bridge. Native additions ship through a store release; plugins cannot be downloaded over the air.
- Can users share a chart or card?
- Use schema-14
share.imageto open the native share sheet with a PNG or JPEG and a caption. It accepts small inline bytes or an image from the active signed bundle. The result describes selection, not delivery. Image sharing and limits. iOS is experimental and untested. - Can I require users to install a newer store build?
- A supporting host can enforce a signed minimum-host policy with a native update screen while retaining saved data. Older runtimes and phones that have never received the policy cannot be forced. See Forcing an update for the release order and signed withdrawal.
- What is out of scope?
- Third-party mini-app stores (Apple guideline 4.7), CRDTs and real-time collaboration, and downloading native code.
- How mature is it?
- It is in beta: the spec and commands may still change before 1.0. The runtime is two published packages —
valenceon pub.dev for the Flutter host and@getvalence/bridgeon npm for the web client — each with its own test suite, and the host package runs the spec’s whole acceptance matrix. The CLI, the spec and codegen are tested too. What is missing is production mileage: no app is live on Valence yet. Apps with a 0.3 generated host follow one documented migration. - Can you set Valence up for us?
- Yes. If you want Valence in your app without learning it first — the Flutter host, signing, the release pipeline and your first over-the-air update — write to [email protected].
- How do pages handle different host versions?
- Typed method gates and the built-in capability revision let pages keep older-host fallbacks. Capability and status fields also retain sync outcomes and expose signed update urgency.
Your website is already your app.
npm create valence@latest