From 44d5810e6bc8b670c94c61ae5cc039a1032e8618 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:40:17 +0000 Subject: [PATCH 1/4] Document the commit changes view --- docs/backend/storage.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 566dccc5..3ebf9d72 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -15,6 +15,7 @@ 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 `.fractch` file, with `scripts` (each `added`, `removed` or `changed`, with its `head`, its `before` and `after` text and its canvas position), `items` (variables, lists, costumes, sounds, extensions and comments that were added, removed, renamed, changed or, for costumes and sounds whose file changed, `edited`) and `state`. `state` lists what running the project changes rather than edits: variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Moving or reordering a script, a newer Fractch spelling of the same block, 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, and `totals` counts everything; `totals.codeChanged` is false when the commit only changed state or assets. A file over 1 MiB, or past the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. `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. From f4fd76d83c923aa6fac7b41e06b79276c7be2073 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:50:46 +0000 Subject: [PATCH 2/4] Describe the changes view per sprite folder --- docs/backend/storage.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 3ebf9d72..46e59813 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -15,7 +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 `.fractch` file, with `scripts` (each `added`, `removed` or `changed`, with its `head`, its `before` and `after` text and its canvas position), `items` (variables, lists, costumes, sounds, extensions and comments that were added, removed, renamed, changed or, for costumes and sounds whose file changed, `edited`) and `state`. `state` lists what running the project changes rather than edits: variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Moving or reordering a script, a newer Fractch spelling of the same block, 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, and `totals` counts everything; `totals.codeChanged` is false when the commit only changed state or assets. A file over 1 MiB, or past the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. `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/changes` describes the same commit by what changed in each sprite instead of by file. `targets` has one entry per changed sprite folder (`path`, with 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, 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 whose files pass 1 MiB each or the 8 MiB response budget is listed with `tooLarge: true` and no breakdown. `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. From ae994069589ff4366b76fdf324472396719ec4f8 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:50:16 +0000 Subject: [PATCH 3/4] Note how the changes view limits size and shows renamed sprites --- docs/backend/storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 46e59813..41c3a82a 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -20,7 +20,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `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, 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 whose files pass 1 MiB each or the 8 MiB response budget is listed with `tooLarge: true` and no breakdown. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. + Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block, 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. From ace4b7defe60a52996999e39d87e8eb912e22344 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Fri, 20 Nov 2026 22:00:18 +0000 Subject: [PATCH 4/4] Document target names and template normalisation in the changes view --- docs/backend/storage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 41c3a82a..8abba4fe 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -15,12 +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`, with its `.fractch` region files in `files`), comparing all of the folder's region files together. Each target has: +- `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, 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`. + 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.