# Workflow: Where My Files Live

> Everything you author is written to a browser-local mirror of your GitHub repo, never a DiceyTable server, with a persistence request and eviction safety net.

- Source: https://diceytable.com/docs/editor/workflows/where-my-files-live
- Last verified: 2026-09-14

## The short answer

**Your files live in your browser, in a folder structure that mirrors your mod's eventual
GitHub repository exactly.** Nothing you upload, draw, or generate is ever sent to a DiceyTable
server for storage — the server only ever sees your files at the moment you explicitly
checkpoint or publish to GitHub.

## Where, specifically

Every project's working file tree is written to the **Origin Private File System (OPFS)**, under
`drafts/<projectId>/tree/…` (`draftModFsScope`, `apps/web/src/storage/draftModFs.ts`) — a
real, file-backed filesystem private to the DiceyTable origin, invisible to other sites and not
part of your regular downloads folder. The layout under `tree/` is the exact repo-relative path
your mod will have on GitHub (`assets/models/…`, `assets/textures/…`, `manifest.json`, …), so
publishing is a straight upload of what's already there rather than a repacking step.

**If your browser doesn't support OPFS**, the editor falls back to an equivalent IndexedDB-backed
store (`IdbModFs`, behind the same `LocalModFs` interface — `apps/web/src/storage/localModFs.ts`)
so authoring still works; you won't notice the difference in the editor's behavior.

A sibling, separate scope (`drafts/<projectId>/sync/`) records GitHub sync bookkeeping: `state.json`
holds which file was last synced at which blob sha, and `manifest-base.json` holds your mod details
as they last agreed with the repository, which is what lets the sync
[merge them](https://diceytable.com/docs/editor/interface/status-bar#synced-the-sync-dot-pulls-in) instead of
reporting every unpublished change as a conflict. It's deliberately **outside** the `tree/` scope
so it's never mistaken for part of your published mod.

## Persistence

The moment you open a draft, the editor asks the browser for **persistent storage**
(`navigator.storage.persist()`, called automatically via `requestPersistentStorage()`) — a
best-effort request that, when granted, tells the browser not to evict your data under ordinary
storage pressure the way it might evict a regular cache. This happens silently in the background;
there's no button to click or setting to check.

## What happens if you clear your browser data

Clearing site data, using a different browser, or the browser evicting storage under real
pressure **empties your local draft**. If your mod is **linked to a GitHub repository**, this is
recoverable: see [Opening on another device](https://diceytable.com/docs/editor/workflows/open-on-another-device) — the
editor re-downloads everything from your repo the next time you open it. If your mod has **never
been linked to a repository** ("No repo yet"), there is no copy anywhere else, and clearing your
data loses it — link a repository and checkpoint before you need this safety net, not after.

## Clearing the local copy on purpose

The same recovery works as a deliberate action. **Reset local copy from GitHub**, in the GitHub
sync dialog behind the [status bar](https://diceytable.com/docs/editor/interface/status-bar#synced-the-sync-dot-pulls-in)'s
`⇅` indicator, deletes this device's local working copy and re-downloads every file from the
repository. It is the answer to "my local files have drifted and I no longer trust them".

What survives it is the same split this page is about: your **manifest and your scene** live in
the project's draft **on the server**, not in the local file tree, so Mod Details and the
viewport come back exactly as they were. What does not survive is any local file you edited and
never published — a texture, a model, a script. The dialog asks you to type the repository name
before it will do it, for that reason.

## When the same file changed in both places

If a file changed **locally and in the repository** since the last sync, the editor does not
pick a winner. It keeps your copy, leaves the repository's alone, and reports a conflict on the
`⇅` indicator; the dialog shows both versions side by side and records whichever you choose. Three
files never take part in this: `diceytable.mod.json` and `setup.json` are written *from* the
server draft on every save, and `README.md` is regenerated from your manifest on every publish,
so there is no local edit to protect and nothing to reconcile.

## Which of these files do players download?

Not all of them. The manifest editor's
[Files tab](https://diceytable.com/docs/editor/interface/topbar#mod-details-the-files-tab) (**Mod ▸ Mod Details…** ▸ **Files**)
lists every file in this tree with what publishing does with it: **Pre-loaded** (declared in the
manifest, downloaded before the table opens), **On demand** (published, fetched when first used),
**Entry** (the manifest, scene and script) or **Editor-only** (thumbnails, originals, card source
images, photo-mode captures — pushed to your repository, never sent to players). The list maintains
itself as you add, move and delete files. The same tab deletes files, and its **Cleanup** view finds
leftovers from deleted decks and thumbnails of files that no longer exist.

Materials, prefabs and table scripts are not in that list because they are not files: they live
inside the scene, `setup.json`.

## Preview and photo-mode captures

[Preview](https://diceytable.com/docs/editor/workflows/preview-and-photo-mode) reads this same local tree, but through a
**read-only** view: it can never write, move or delete a file in your draft. A file missing
locally is fetched from your linked repository's `wip` branch instead.

Photo-mode captures taken in Preview are the one thing that comes back. The preview tab hands each
capture to the editor tab that holds the project's lease, which writes it into the tree as
`screenshots/<yyyymmdd-hhmmss>-<id>.png` (or `.webp`) with a `.json` sidecar. From then on it is an
ordinary draft file: it syncs, it publishes, and it is removed from the repository only when you
delete it. It is never a declared asset, so players never download it. See
[The Screenshots gallery](https://diceytable.com/docs/editor/interface/screenshots).

If no editor tab answers within 3 seconds, or the editor cannot save it yet (still loading, lost
the lease, or the write failed), the capture is kept in an **IndexedDB outbox** in this browser
(`diceytable-preview-captures`) and imported the next time you open the project in the editor. The
status line then reads *"N screenshots imported from Preview."* The preview also offers a
Download, because an outbox is still only this browser's storage: it keeps entries for at most
30 days and at most 50 across all projects, dropping the oldest first. A capture over 40 MB is
never queued; it is offered as a Download only.

Photo mode on a normal `/table` writes nothing here at all: a capture there is a browser download
and nothing else.

## What eviction actually touches

Under real storage-quota pressure, the browser (or the editor's own quota-error retry path) only
ever clears the **disposable pull-cache** for published mods you've merely *played*, at
`cache/<owner>/<repo>/<version>` (the commit sha, or the mod's content hash when no sha was
recorded) — content that's trivially re-downloaded from GitHub on demand. Loading a mod that has
been republished since you last played it also prunes your superseded copies of that same mod, so
the cache holds one version per mod rather than one per publish. Your
**active draft** (`drafts/…`) is never touched by this eviction path
(`OpfsModFs.clearPullCaches`, `apps/web/src/storage/OpfsModFs.ts`) — a write that hits a
quota error retries once *after* the pull-caches are cleared, specifically so an active draft
write never fails just because you'd previously played a lot of other mods.

## See also

- [Opening on another device](https://diceytable.com/docs/editor/workflows/open-on-another-device)
- [The Status Bar](https://diceytable.com/docs/editor/interface/status-bar#synced-the-sync-dot-pulls-in) — the sync indicator, the conflict resolver, and the reset
- [Connect GitHub](https://diceytable.com/docs/mods/publishing/github-setup)
- [wip and main](https://diceytable.com/docs/mods/publishing/wip-and-main)
