diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 566dccc5..8abba4fe 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -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=` 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.