Persistence

How webs are stored, loaded, exported, and imported.

Goals

• Portable: a web can move between machines without services.
• Simple: no special tooling required to back up.
• Extensible: versioning and migrations are possible.

Storage modes

Local-first (recommended for v1)

• Store current web in IndexedDB (or localStorage for tiny demos).
• Allow export to a “web package” zip.
• Allow import from a “web package” zip.

Server-backed (optional)

• Server stores web.json plus media.
• Client can still export/import.

Web package format

A package is a folder or zip file:

• web.json
• media/ (optional)
• meta.json (optional)

meta.json example:

{
  "packageVersion": 1,
  "createdAt": "2026-01-01T00:00:00Z",
  "createdBy": "kweb-app",
  "notes": "Optional"
}

Versioning

• web.json.version is an integer.
• When the format changes, bump version and provide a migration.

Import safety

• Treat imported JSON as untrusted input.
• Validate shape and required fields.
• Sanitize any rich text that could contain HTML.

Definition of done (persistence)

• [ ] Export and import work offline.
• [ ] Import validates and fails with a clear error message.
• [ ] Export includes enough info to fully reconstruct the web.