Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/backend/storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ The editor POSTs a sparse sb3 to `POST /v1/projects/:id/upload` (multipart, fiel
The read-only commit endpoints inspect the stored `.mwp` on the server. Clients do not need to download the complete workspace to render history or browse an old revision.

- `GET /v1/projects/:id/commits/:sha` returns commit metadata, its first parent, and changed-file records. Each record has `path`, `status`, `oldOid`, `newOid`, `oldSize`, and `newSize`. With `?inline=1`, small text changes also include `oldData` and `newData`, encoded as base64 and capped at 1 MiB per file and 8 MiB per response. Root commits report every file as added. `legacy: true` means the change includes an old `project.sb3`; clients that need the expanded Fractch diff should use their legacy conversion fallback.
- `GET /v1/projects/:id/commits/:sha/changes` describes the same commit by what changed in each sprite instead of by file. `targets` has one entry per changed sprite folder (`path`, the sprite's `name` when its header can be read, and its `.fractch` region files in `files`), comparing all of the folder's region files together. Each target has:
- `scripts`: each `added`, `removed`, `changed` or `moved` (to another region file), with its `head`, `file`, `before` and `after` text and canvas positions.
- `items`: variables, lists, costumes, sounds, extensions and comments that were added, removed, renamed or changed. A costume or sound whose image or audio changed is `edited`, and a new costume or sound order is one `reordered` item.
- `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas.

Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`.
- `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`.
- `GET /v1/projects/:id/commits/:sha/file?path=<path>` returns one file record and `content`, encoded as base64 by JSON.
- `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias.
Expand Down
Loading