How .pop files work

A .pop is one SQLite file that holds the app needed to open it and, once created as a writable document, everything that document saved. Send it by Mail or AirDrop, and it arrives whole.

Source is not the runtime file

pop.ts declares identity, window, theme and optional artwork. schema.ts owns the document shape and initial values. The CLI discovers App.svelte, required Preview.svelte and Icon.svelte, optional Export.svelte, Widget.svelte and agent-only commands.ts by these exact names. Components import styles and media through Vite. Before mounting, the host applies theme defaults and document overrides as --pop-* CSS variables.

pop build compiles the app, evaluates the declaration, and packs the result into a template file.

A template holds:

• the app: its identity, descriptor, theme and commands, and the format and runtime it needs;
• its assets: the compiled interface, styles and media;
• its artwork: the preview and, when declared, the icon;
• the initial values for a new document.

The authored bundle does not contain its own document engine. The installed app supplies the page shell, boot sequence, the native document engine and lifecycle. It calls the compiled app’s mount(ctx, target) with document, binding, attachment, speech, and window services. The page shell is served to the WebView; it is never copied into the file.

A document adds its saved state

Creating a document copies a template into a new file. As it is edited, the same file gains the document’s identity, its saved data and theme overrides, and any imported files. A document shared through live sharing also remembers its link.

The Rust owner, shared by the app and CLI, owns the live document and its saved history; the page renders snapshots of it. Initial values are read only when a document is created, and the stored schema is a descriptor rather than JSON Schema. There is no editable document JSON file.

One writer at a time owns a document. The CLI hands a command to the app when it has the document open, and otherwise edits the file directly without starting a window.

Theme overrides are saved with the document, outside the authored data. They merge per color and share the document’s undo and saving. The page receives the effective palette through its initial state and ordered publications. Replacing document data with JSON preserves the theme. See theme files and commands. Duplicate and Share a Copy preserve the saved content, attachments and overrides in a new file.

Templates and copies

Registered templates and built-in starters remain immutable. Create makes a writable copy. Rebuilding or updating a template does not replace the app or schema in existing documents. An app update supplies a newer page shell and engine to those documents. Captures render saved state independently. For an open document, pop first saves and copies it; no second writer renders the original file. See capture views and widget refresh.

Close before moving or renaming a document. Keep active standalone documents on a local filesystem outside iCloud and other synced folders. The Synced Library manages sync between your Mac and iPhone separately. The Mac app checks for iCloud-synced Desktop and Documents folders and uses ~/pop as its initial save location when Desktop is synced. It remembers your last usable local save folder.

Opening a document stored in iCloud offers Move to ~/pop and Open. pop saves and verifies a local copy before moving the original to Trash. If the original cannot be removed, both files are kept and the app explains where the local document was saved. Templates stay unchanged and create editable copies.

Every file is checked when it opens: a damaged or oversized one is refused, never repaired. Migrations, schema evolution, and multiple writers on one document are not supported.