@kubohiroya/turbowarp-plus-editor-git 0.7.0 → 0.8.0

package/dist/scratch-block-diff-renderer.d.ts

@@ -4,20 +4,46 @@ interface BlockWorkspace {
     dispose(): void;
     markFocused(): void;
     getBlocksBoundingBox(): {
+        x?: number;
+        y?: number;
         width: number;
         height: number;
     };
     getBlockById(id: string): DiffSvgBlock | null;
     options?: {
         pathToMedia?: string;
+        zoomOptions?: {
+            startScale?: number;
+        };
+    };
+    scale?: number;
+    scrollX?: number;
+    scrollY?: number;
+    translate?(x: number, y: number): void;
+    getMetrics?(): {
+        absoluteLeft?: number;
+        absoluteTop?: number;
+    } | null;
+    scrollbar?: {
+        resize(): void;
+    } | null;
+}
+interface InjectOptions {
+    readOnly: true;
+    sounds: false;
+    media?: string;
+    scrollbars?: boolean;
+    zoom?: {
+        controls: boolean;
+        wheel: boolean;
+        startScale: number;
+        maxScale: number;
+        minScale: number;
+        scaleSpeed: number;
     };
 }
 export interface ScratchBlocksPort {
-    inject(container: HTMLElement, options: {
-        readOnly: true;
-        sounds: false;
-        media?: string;
-    }): BlockWorkspace;
+    inject(container: HTMLElement, options: InjectOptions): BlockWorkspace;
     svgResize(workspace: BlockWorkspace): void;
     getMainWorkspace(): BlockWorkspace | null;
     mainWorkspace: BlockWorkspace | null;
@@ -47,19 +73,56 @@ export interface ScratchBlockDiffRendererOptions {
         }, deferProjectChanged: true): void;
         blockToXML(id: string): string | undefined;
     };
+    /**
+     * Adds the host's workspace navigation to each preview, as in its own code area: for example the costume
+     * thumbnail, a minimap and a row of zoom buttons in the lower right. `watermark` holds the costume thumbnail when
+     * the version has one; the host positions it. Without this option, previews keep Scratch Blocks' zoom buttons.
+     */
+    attachNavigation?(workspace: unknown, blockly: ScratchBlocksPort, watermark?: HTMLElement): {
+        dispose(): void;
+    } | null | undefined;
 }
 export interface ScriptBlockMark {
     id: string;
     kind: BlockChangeKind;
     parts: readonly BlockPart[];
 }
+/** Position and zoom of one preview, in Scratch Blocks workspace terms. */
+export interface BlockPreviewViewport {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** Lets several previews of one comparison share their zoom, scroll position and height. */
+export interface BlockPreviewView {
+    /** The zoom and frame height at which this preview shows all of its blocks. */
+    readonly fit: {
+        scale: number;
+        height: number;
+    };
+    /** Applies a zoom and frame height, scrolling to the start of the blocks. */
+    layout(fit: {
+        scale: number;
+        height: number;
+    }): void;
+    viewport(): BlockPreviewViewport;
+    setViewport(viewport: BlockPreviewViewport): void;
+    /** Calls `listener` after the user scrolls or zooms this preview. */
+    onChange(listener: () => void): () => void;
+}
+export type ProjectBlockRendering = (() => void) | {
+    dispose(): void;
+    view?: BlockPreviewView;
+} | undefined;
 export type ProjectBlockRenderer = (args: BlockSide & {
     container: HTMLElement;
     withContext: boolean;
     parts?: readonly BlockPart[];
     marks?: readonly ScriptBlockMark[];
     signal: AbortSignal;
-}) => Promise<(() => void) | undefined>;
+    /** The costume thumbnail element of this version, placed in the preview's lower right by the host navigation. */
+    watermark?: HTMLElement;
+}) => Promise<ProjectBlockRendering>;
 /** Use the host's Scratch VM serializer and Scratch Blocks definitions in an isolated workspace. */
 export declare function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendererOptions): ProjectBlockRenderer;
 export {};

package/dist/style.css

@@ -22,8 +22,26 @@
 .twgit-block-diff-sides { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
 .twgit-block-diff-side { padding: 10px 14px; min-width: 0; }
 .twgit-block-diff-side + .twgit-block-diff-side { border-inline-start: 1px solid color-mix(in srgb, CanvasText 20%, Canvas); }
-.twgit-block-diff-preview { overflow: auto; max-height: 420px; }
-.twgit-block-diff-surface { position: relative; min-width: 100%; height: 64px; }
+/* A preview is a small workspace: it scrolls and zooms inside its frame, which people can make taller. */
+.twgit-block-diff-preview {
+    position: relative;
+    overflow: hidden;
+    resize: vertical;
+    min-height: 120px;
+    max-height: 85vh;
+    border: 1px solid color-mix(in srgb, CanvasText 18%, Canvas);
+    border-radius: 6px;
+}
+.twgit-block-diff-surface { position: absolute; inset: 0; }
+.twgit-block-diff-watermark { position: absolute; z-index: 2; top: 10px; right: 12px; pointer-events: none; }
+.twgit-block-diff-watermark[data-navigation] { top: auto; right: var(--plus-watermark-right, 12px); bottom: var(--plus-watermark-bottom, 140px); }
+.twgit-block-diff-watermark > img {
+    display: block;
+    max-width: var(--plus-watermark-size, 48px);
+    max-height: var(--plus-watermark-size, 48px);
+    opacity: .6;
+}
+.twgit-block-diff-link { display: block; padding: 6px 12px 0; }
 /* These markers also apply to the live Editor workspace returned by the host. */
 .twgit-changed-block > .blocklyPath { stroke: var(--twgit-change, #635bce); stroke-width: 2.5px; }
 .twgit-changed-block-part { outline: 2.5px solid #b4510a; outline-offset: 2px; }
@@ -77,6 +95,17 @@
 .twgit-pr-paging, .twgit-pr-revision { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
 .twgit-pr-revision code { overflow-wrap: anywhere; }
 .twgit-review .twgit-block-diff-side h4 { font-size: 1em; }
+
+/* Costume (or backdrop) thumbnails in stage and sprite headings. */
+.twgit-review-thumbnails { display: inline-flex; align-items: center; gap: 4px; margin-inline-end: 6px; vertical-align: middle; }
+.twgit-review-thumbnails img {
+    width: 30px;
+    height: 30px;
+    object-fit: contain;
+    background: Canvas;
+    border: 1px solid var(--twgit-review-line, color-mix(in srgb, CanvasText 18%, Canvas));
+    border-radius: 4px;
+}
 :root{--diff-background-color:initial;--diff-text-color:initial;--diff-font-family:Consolas,Courier,monospace;--diff-selection-background-color:#b3d7ff;--diff-selection-text-color:var(--diff-text-color);--diff-gutter-insert-background-color:#d6fedb;--diff-gutter-insert-text-color:var(--diff-text-color);--diff-gutter-delete-background-color:#fadde0;--diff-gutter-delete-text-color:var(--diff-text-color);--diff-gutter-selected-background-color:#fffce0;--diff-gutter-selected-text-color:var(--diff-text-color);--diff-code-insert-background-color:#eaffee;--diff-code-insert-text-color:var(--diff-text-color);--diff-code-delete-background-color:#fdeff0;--diff-code-delete-text-color:var(--diff-text-color);--diff-code-insert-edit-background-color:#c0dc91;--diff-code-insert-edit-text-color:var(--diff-text-color);--diff-code-delete-edit-background-color:#f39ea2;--diff-code-delete-edit-text-color:var(--diff-text-color);--diff-code-selected-background-color:#fffce0;--diff-code-selected-text-color:var(--diff-text-color);--diff-omit-gutter-line-color:#cb2a1d;}.diff{background-color:var(--diff-background-color);border-collapse:collapse;color:var(--diff-text-color);table-layout:fixed;width:100%;}.diff::-moz-selection{background-color:#b3d7ff;background-color:var(--diff-selection-background-color);color:var(--diff-text-color);color:var(--diff-selection-text-color);}.diff::selection{background-color:#b3d7ff;background-color:var(--diff-selection-background-color);color:var(--diff-text-color);color:var(--diff-selection-text-color);}.diff td{padding-bottom:0;padding-top:0;vertical-align:top;}.diff-line{font-family:Consolas,Courier,monospace;font-family:var(--diff-font-family);line-height:1.5;}.diff-gutter>a{color:inherit;display:block;}.diff-gutter{cursor:pointer;padding:0 1ch;text-align:right;-webkit-user-select:none;-moz-user-select:none;user-select:none;}.diff-gutter-insert{background-color:#d6fedb;background-color:var(--diff-gutter-insert-background-color);color:var(--diff-text-color);color:var(--diff-gutter-insert-text-color);}.diff-gutter-delete{background-color:#fadde0;background-color:var(--diff-gutter-delete-background-color);color:var(--diff-text-color);color:var(--diff-gutter-delete-text-color);}.diff-gutter-omit{cursor:default;}.diff-gutter-selected{background-color:#fffce0;background-color:var(--diff-gutter-selected-background-color);color:var(--diff-text-color);color:var(--diff-gutter-selected-text-color);}.diff-code{word-wrap:break-word;padding:0 0 0 .5em;white-space:pre-wrap;word-break:break-all;}.diff-code-edit{color:inherit;}.diff-code-insert{background-color:#eaffee;background-color:var(--diff-code-insert-background-color);color:var(--diff-text-color);color:var(--diff-code-insert-text-color);}.diff-code-insert .diff-code-edit{background-color:#c0dc91;background-color:var(--diff-code-insert-edit-background-color);color:var(--diff-text-color);color:var(--diff-code-insert-edit-text-color);}.diff-code-delete{background-color:#fdeff0;background-color:var(--diff-code-delete-background-color);color:var(--diff-text-color);color:var(--diff-code-delete-text-color);}.diff-code-delete .diff-code-edit{background-color:#f39ea2;background-color:var(--diff-code-delete-edit-background-color);color:var(--diff-text-color);color:var(--diff-code-delete-edit-text-color);}.diff-code-selected{background-color:#fffce0;background-color:var(--diff-code-selected-background-color);color:var(--diff-text-color);color:var(--diff-code-selected-text-color);}.diff-widget-content{vertical-align:top;}.diff-gutter-col{width:7ch;}.diff-gutter-omit{height:0;}.diff-gutter-omit:before{background-color:#cb2a1d;background-color:var(--diff-omit-gutter-line-color);content:" ";display:block;height:100%;margin-left:4.6ch;overflow:hidden;white-space:pre;width:2px;}.diff-decoration{line-height:1.5;-webkit-user-select:none;-moz-user-select:none;user-select:none;}.diff-decoration-content{font-family:Consolas,Courier,monospace;font-family:var(--diff-font-family);padding:0;}.twgit-backdrop { position: fixed; inset: 0; z-index: 65000; background: #0006; display: flex; align-items: center; justify-content: center; }
 .twgit-panel { width: 94vw; height: 90vh; display: flex; flex-direction: column; background: Canvas; color: CanvasText; border: 1px solid GrayText; border-radius: 8px; box-shadow: 0 12px 48px #0005; font: 14px/1.5 system-ui, sans-serif; overflow: hidden; }
 .twgit-panel > header { display: flex; gap: 8px; align-items: center; padding: 10px 16px; border-bottom: 1px solid GrayText; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-plus-editor-git",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Read-only local Git panel for TurboWarp Plus Editor",
   "type": "module",
   "license": "MPL-2.0",
@@ -35,8 +35,13 @@
     "vite.config.ts",
     "tsconfig.json",
     "README.ja.md",
-    "THIRD_PARTY_NOTICES.md"
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.js",

package/src/block-diff-preview.tsx

@@ -1,34 +1,115 @@
-import React, {useEffect, useRef, useState} from 'react';
+import React, {useEffect, useMemo, useRef, useState} from 'react';
 import type {BlockPart, BlockSide} from './project-source-patch.js';
-import type {ProjectBlockRenderer, ScriptBlockMark} from './scratch-block-diff-renderer.js';
+import type {BlockPreviewView, ProjectBlockRenderer, ProjectBlockRendering, ScriptBlockMark} from './scratch-block-diff-renderer.js';
+import {currentCostume, useCostumeImage} from './project-assets.js';
+import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
 export type LocationStatus = 'locating' | 'located' | 'missingLocation';
 type PreviewLabels = Record<'absent' | 'loading' | 'unavailable', string> & Partial<Record<LocationStatus | 'locate', string>>;
 
-export function BlockPreview({side, title, parts, marks, renderBlock, withContext, labels, onLocate, locationStatus}: {
+/** Keeps the previews of one comparison at the same zoom, height and scroll position while they are linked. */
+export interface PreviewSync {
+    add(view: BlockPreviewView): () => void;
+    setLinked(linked: boolean): void;
+}
+
+export function createPreviewSync(): PreviewSync {
+    const members = new Map<BlockPreviewView, () => void>();
+    let linked = true;
+    let moving = false;
+    // The version that needs the smaller zoom and the taller frame decides, so neither one is cut off.
+    const align = () => {
+        if (!linked || !members.size) return;
+        const views = [...members.keys()];
+        const fit = {scale: Math.min(...views.map(view => view.fit.scale)), height: Math.max(...views.map(view => view.fit.height))};
+        for (const view of views) view.layout(fit);
+    };
+    return {
+        add(view) {
+            const stop = view.onChange(() => {
+                if (!linked || moving) return;
+                moving = true;
+                try {
+                    const viewport = view.viewport();
+                    for (const other of members.keys()) if (other !== view) other.setViewport(viewport);
+                } finally {
+                    moving = false;
+                }
+            });
+            members.set(view, stop);
+            align();
+            return () => {
+                stop();
+                members.delete(view);
+            };
+        },
+        setLinked(value) {
+            if (linked === value) return;
+            linked = value;
+            align();
+        }
+    };
+}
+
+const linkLabels = {en: 'Move both versions together', ja: '変更前と変更後を連動して動かす'};
+
+/** One sync group per comparison, with the checkbox that links or unlinks its previews. */
+export function usePreviewSync(locale: string) {
+    const sync = useMemo(createPreviewSync, []);
+    const [linked, setLinked] = useState(true);
+    useEffect(() => sync.setLinked(linked), [sync, linked]);
+    const toggle = <label className="twgit-block-diff-link"><input type="checkbox" checked={linked}
+        onChange={event => setLinked(event.currentTarget.checked)}/> {locale.startsWith('ja') ? linkLabels.ja : linkLabels.en}</label>;
+    return {sync, toggle};
+}
+
+const rendering = (result: ProjectBlockRendering) =>
+    typeof result === 'function' ? {release: result} : {release: result && (() => result.dispose()), view: result?.view};
+
+export function BlockPreview({side, title, parts, marks, renderBlock, withContext, labels, onLocate, locationStatus,
+    version, loadAsset, sync}: {
     side?: BlockSide; title: string; parts?: readonly BlockPart[]; marks?: readonly ScriptBlockMark[]; renderBlock: ProjectBlockRenderer;
     withContext: boolean; labels: PreviewLabels; onLocate?: () => void; locationStatus?: LocationStatus;
+    /** Which version this preview shows, for its costume thumbnail. */
+    version?: ProjectVersion; loadAsset?: ProjectAssetLoader; sync?: PreviewSync;
 }) {
     const host = useRef<HTMLDivElement>(null);
+    const watermark = useRef<HTMLDivElement>(null);
     const [status, setStatus] = useState<'loading' | 'ready' | 'failed'>('loading');
+    const thumbnail = !!(side && version && loadAsset && currentCostume(side.target));
+    const image = useCostumeImage(thumbnail ? side!.target : undefined, version ?? 'after', loadAsset);
     useEffect(() => {
         if (!side || !host.current) return;
         const container = host.current;
         const abort = new AbortController();
         let dispose: (() => void) | undefined;
         setStatus('loading');
-        void Promise.resolve().then(() => renderBlock({...side, container, withContext, parts, marks, signal: abort.signal})).then(cleanup => {
-            if (abort.signal.aborted) cleanup?.();
-            else {dispose = cleanup; setStatus('ready');}
+        void Promise.resolve().then(() => renderBlock({...side, container, withContext, parts, marks, signal: abort.signal,
+            watermark: thumbnail ? watermark.current ?? undefined : undefined})).then(result => {
+            const {release, view} = rendering(result);
+            if (abort.signal.aborted) {
+                release?.();
+                return;
+            }
+            const leave = view && sync?.add(view);
+            dispose = () => {
+                leave?.();
+                release?.();
+            };
+            setStatus('ready');
         }, () => {if (!abort.signal.aborted) setStatus('failed');});
         return () => {abort.abort(); dispose?.();};
-    }, [side, renderBlock, withContext, parts, marks]);
+    }, [side, renderBlock, withContext, parts, marks, sync, thumbnail]);
     return <div className="twgit-block-diff-side">
         <h4>{title}</h4>
         {!side && <p>{labels.absent}</p>}
         {side && status === 'loading' && <p role="status">{labels.loading}</p>}
         {side && status === 'failed' && <p role="status">{labels.unavailable}</p>}
-        <div ref={host} className="twgit-block-diff-preview"/>
+        {side && <div ref={host} className="twgit-block-diff-preview">
+            {thumbnail && <div ref={watermark} className="twgit-block-diff-watermark" data-dockview-costume-thumbnail="">
+                {image && <img src={image} alt=""/>}
+            </div>}
+        </div>}
         {side && onLocate && <button type="button" aria-label={`${title} · ${labels.locate}`}
             onClick={onLocate}>{labels.locate}</button>}
         {locationStatus && <p role="status">{labels[locationStatus]}</p>}

package/src/file-diff-view.tsx

@@ -4,6 +4,7 @@ import {ProjectSourceComparison} from './project-source-review.js';
 import type {FileChange, FileDiff} from './repository.js';
 import type {labelsFor} from './messages.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+import type {ProjectAssetLoader} from './project-assets.js';
 
 const en = {view: 'Show changes as', blocks: 'Blocks', text: 'Text'};
 const ja: typeof en = {view: '変更の表示', blocks: 'ブロック', text: 'テキスト'};
@@ -14,9 +15,9 @@ export const isProjectSource = (path: string) => path.split('/').pop() === 'proj
 /**
  * Shows one changed file. Project sources are compared as blocks by default, with their text diff one switch away.
  */
-export function FileDiffView({change, diff, labels, locale, renderBlock}: {
+export function FileDiffView({change, diff, labels, locale, renderBlock, loadAsset}: {
     change: FileChange; diff: FileDiff | null; labels: ReturnType<typeof labelsFor>; locale: string;
-    renderBlock?: ProjectBlockRenderer;
+    renderBlock?: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
 }) {
     const [view, setView] = useState<'blocks' | 'text'>('blocks');
     const names = locale.startsWith('ja') ? ja : en;
@@ -37,7 +38,7 @@ export function FileDiffView({change, diff, labels, locale, renderBlock}: {
             {(['blocks', 'text'] as const).map(mode => <button key={mode} type="button" aria-pressed={view === mode}
                 data-git-view={mode} onClick={() => setView(mode)}>{names[mode]}</button>)}
         </div>}
-        {sources && view === 'blocks' ? <ProjectSourceComparison renderBlock={renderBlock!} locale={locale} fallback={text}
+        {sources && view === 'blocks' ? <ProjectSourceComparison renderBlock={renderBlock!} locale={locale} fallback={text} loadAsset={loadAsset}
             before={change.before === null ? null : sources.before} after={change.after === null ? null : sources.after}/> : text}
     </>;
 }

package/src/github-pull-requests.ts

@@ -1,5 +1,7 @@
 import {createProjectSourceDiff, isRecord} from './project-source-patch.js';
 import type {ProjectSourceReviewFile} from './project-source-review.js';
+import {assetLimit, assetsDirectoryParts, folderSettingsLimit, isAssetName} from './project-asset-paths.js';
+import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
 type ErrorCode = 'unavailable' | 'rateLimit' | 'failed' | 'changed' | 'tooManyFiles';
 export class PullRequestError extends Error {
@@ -24,19 +26,17 @@ const invalidResponse = () => new PullRequestError('failed');
 const emptyProject = '{"targets":[]}\n';
 const sourceLimit = 1024 * 1024;
 
-async function readText(response: Response, limit: number) {
+async function readBody(response: Response, limit: number, chunk: (value: Uint8Array) => void) {
     if (Number(response.headers.get('Content-Length')) > limit || !response.body) throw invalidResponse();
     const reader = response.body.getReader();
-    const decoder = new TextDecoder('utf-8', {fatal: true});
-    const chunks: string[] = [];
     let length = 0;
     try {
         for (;;) {
             const {done, value} = await reader.read();
-            if (done) return chunks.join('') + decoder.decode();
+            if (done) return;
             length += value.byteLength;
             if (length > limit) throw invalidResponse();
-            chunks.push(decoder.decode(value, {stream: true}));
+            chunk(value);
         }
     } catch (error) {
         void reader.cancel().catch(() => {});
@@ -44,6 +44,13 @@ async function readText(response: Response, limit: number) {
     }
 }
 
+async function readText(response: Response, limit: number) {
+    const decoder = new TextDecoder('utf-8', {fatal: true});
+    const chunks: string[] = [];
+    await readBody(response, limit, value => chunks.push(decoder.decode(value, {stream: true})));
+    return chunks.join('') + decoder.decode();
+}
+
 function readSummary(value: unknown) {
     if (!isRecord(value) || !Number.isSafeInteger(value.number) || Number(value.number) < 1 ||
         typeof value.title !== 'string') throw invalidResponse();
@@ -80,6 +87,62 @@ function contentPath(path: string) {
     return parts.map(encodeURIComponent).join('/');
 }
 
+/** One version of a project file on GitHub: the repository and commit, and the project file's path. */
+interface ProjectLocation {repository: string; sha: string; path: string}
+
+/**
+ * Reads the assets of both versions of a project file from raw.githubusercontent.com, which does not count against the
+ * API rate limit. Each version's sb3-source.json names its assets directory. Every read is capped, honors both its own
+ * signal and the pull request's, and resolves `null` on any failure.
+ */
+function rawAssetLoader(versions: Record<ProjectVersion, ProjectLocation | null>, send: typeof fetch, review: AbortSignal): ProjectAssetLoader {
+    const directories = new Map<ProjectVersion, Promise<string[] | null>>();
+    const get = (url: string, signal: AbortSignal) => send(url, {credentials: 'omit', redirect: 'error', signal});
+    const folderUrl = ({repository, sha, path}: ProjectLocation) => 'https://raw.githubusercontent.com/' +
+        repository.split('/').map(encodeURIComponent).join('/') + '/' + sha + '/' +
+        contentPath(path).split('/').slice(0, -1).map(part => part + '/').join('');
+    const readDirectory = async (folder: string, signal: AbortSignal) => {
+        let settings: string | null = null;
+        try {
+            const response = await get(folder + 'sb3-source.json', signal);
+            if (response.ok) settings = await readText(response, folderSettingsLimit);
+            else void response.body?.cancel().catch(() => {});
+        } catch (error) {
+            // A missing or unreadable file falls back to `assets`; a cancelled read is retried by the next request.
+            if (signal.aborted) throw error;
+        }
+        return assetsDirectoryParts(settings);
+    };
+    return async ({version, md5ext, signal: own}) => {
+        const location = versions[version];
+        if (!location || !isAssetName(md5ext)) return null;
+        try {
+            const signal = AbortSignal.any([own, review]);
+            if (signal.aborted) return null;
+            const folder = folderUrl(location);
+            let directory = directories.get(version);
+            if (!directory) {
+                directory = readDirectory(folder, signal);
+                directories.set(version, directory);
+                const pending = directory;
+                pending.catch(() => {if (directories.get(version) === pending) directories.delete(version);});
+            }
+            const parts = await directory;
+            if (!parts || signal.aborted) return null;
+            const response = await get(folder + parts.map(encodeURIComponent).join('/') + '/' + md5ext, signal);
+            if (!response.ok) {
+                void response.body?.cancel().catch(() => {});
+                return null;
+            }
+            const chunks: Uint8Array<ArrayBuffer>[] = [];
+            await readBody(response, assetLimit, value => chunks.push(value as Uint8Array<ArrayBuffer>));
+            return signal.aborted ? null : new Blob(chunks);
+        } catch {
+            return null;
+        }
+    };
+}
+
 export function createGitHubPullRequests(repository: string, send: typeof fetch = fetch) {
     if (!validRepository(repository)) throw invalidResponse();
     const api = 'https://api.github.com';
@@ -148,7 +211,11 @@ export function createGitHubPullRequests(repository: string, send: typeof fetch
                         status === 'added' ? emptyProject : source(repository, file.previous ?? file.path, base!, signal),
                         status === 'removed' ? emptyProject : source(pr.head.repository ?? repository, file.path, pr.head.sha, signal)
                     ]);
-                    files.push({path: file.path, previousPath: file.previous, patch: createProjectSourceDiff(before, after)});
+                    const loadAsset = rawAssetLoader({
+                        before: status === 'added' ? null : {repository, sha: base!, path: file.previous ?? file.path},
+                        after: status === 'removed' ? null : {repository: pr.head.repository ?? repository, sha: pr.head.sha, path: file.path}
+                    }, send, signal);
+                    files.push({path: file.path, previousPath: file.previous, patch: createProjectSourceDiff(before, after), loadAsset});
                 } catch (error) {
                     if (signal.aborted) throw error;
                     files.push({...related, unavailable: true});

package/src/index.tsx

@@ -1,4 +1,4 @@
-import React, {useEffect, useRef, useState} from 'react';
+import React, {useEffect, useMemo, useRef, useState} from 'react';
 import {render, unmountComponentAtNode} from 'react-dom';
 import {FileDiffView} from './file-diff-view.js';
 import {openRepository} from './repository.js';
@@ -249,6 +249,9 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
             event.preventDefault(); last?.focus();
         } else if (!event.shiftKey && document.activeElement === last) {event.preventDefault(); first?.focus();}
     };
+    // One loader per selected change, so thumbnails read each asset once.
+    const loadAsset = useMemo(() => state.repository && state.snapshot && state.selected ?
+        state.repository.assetLoader(state.snapshot, state.selected) : undefined, [state.repository, state.snapshot, state.selected]);
     if (!visible) return null;
     const groups: ChangeGroup[] = state.commit ? ['commit'] : ['staged', 'unstaged', 'untracked'];
     return <div className="twgit-backdrop">
@@ -314,7 +317,7 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
                 </aside>
                 <main className="twgit-diff">
                     {state.selected ? <FileDiffView change={state.selected} diff={state.diff} labels={labels} locale={locale}
-                        renderBlock={host.renderReviewBlock}/> : <p>{labels.select}</p>}
+                        renderBlock={host.renderReviewBlock} loadAsset={loadAsset}/> : <p>{labels.select}</p>}
                 </main>
             </div>}
             <footer>{labels.permissions}</footer>

package/src/project-asset-paths.ts

@@ -0,0 +1,33 @@
+// Shared by the local and GitHub asset loaders. Kept free of React so the repository entry stays UI-free.
+
+/** The largest asset a thumbnail reads. */
+export const assetLimit = 10 * 1024 * 1024;
+/** The largest sb3-source.json read to find the assets directory. */
+export const folderSettingsLimit = 1024 * 1024;
+
+/** Asset names are plain `<md5>.<ext>` file names; anything else could address a path outside the assets directory. */
+export const isAssetName = (name: unknown): name is string =>
+    typeof name === 'string' && /^[0-9A-Za-z_-]{1,128}\.[0-9A-Za-z]{1,8}$/.test(name);
+
+/**
+ * The assets directory named by one version of a project folder's `sb3-source.json`, as path segments relative to the
+ * folder. `assets` when that file or its `assetsDirectory` field is missing or unreadable. `null` when the field names
+ * anything other than a plain relative path inside the folder.
+ */
+export function assetsDirectoryParts(settings: string | null): string[] | null {
+    let value: unknown = 'assets';
+    if (settings !== null) {
+        try {
+            const parsed: unknown = JSON.parse(settings);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) && 'assetsDirectory' in parsed) {
+                value = (parsed as {assetsDirectory: unknown}).assetsDirectory;
+            }
+        } catch {
+            // An unreadable file names no directory, as a missing one does.
+        }
+    }
+    if (typeof value !== 'string' || value.length > 1024) return null;
+    const parts = value.split('/');
+    return parts.every(part => part && part !== '.' && part !== '..' && part.toLowerCase() !== '.git' &&
+        !/[\\\0-\x1f\x7f]/.test(part)) ? parts : null;
+}

package/src/project-assets.ts

@@ -0,0 +1,66 @@
+import {useEffect, useState} from 'react';
+import {isRecord} from './project-source-patch.js';
+import type {ProjectTarget} from './project-source-patch.js';
+
+export type ProjectVersion = 'before' | 'after';
+
+/**
+ * Reads one asset of one version of a project file by its `md5ext` name (for example `0123…cdef.svg`), from the
+ * assets directory of that project. Resolves `null` when that version has no readable file of that name.
+ */
+export type ProjectAssetLoader = (request: {version: ProjectVersion; md5ext: string; signal: AbortSignal}) => Promise<Blob | null>;
+
+const imageTypes: Record<string, string> = {
+    svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', bmp: 'image/bmp', webp: 'image/webp'
+};
+
+/** The costume a sprite shows, or the backdrop the stage shows, when the project data names an image file for it. */
+export function currentCostume(target: ProjectTarget): {name: string; md5ext: string; type: string} | null {
+    const {costumes, currentCostume: index} = target as unknown as Record<string, unknown>;
+    if (!Array.isArray(costumes)) return null;
+    const costume: unknown = costumes[typeof index === 'number' && Number.isInteger(index) && index >= 0 ? index : 0];
+    if (!isRecord(costume)) return null;
+    const md5ext = typeof costume.md5ext === 'string' ? costume.md5ext :
+        typeof costume.assetId === 'string' && typeof costume.dataFormat === 'string' ? costume.assetId + '.' + costume.dataFormat : '';
+    // Asset names are plain file names; anything else could address a path outside the assets directory.
+    const match = /^[0-9A-Za-z_-]{1,128}\.([0-9A-Za-z]{1,8})$/.exec(md5ext);
+    const type = match ? imageTypes[match[1].toLowerCase()] : undefined;
+    if (!type) return null;
+    return {name: typeof costume.name === 'string' ? costume.name : '', md5ext, type};
+}
+
+// Thumbnails of one target appear in its heading and in each of its frames, so one read serves all of them.
+const reads = new WeakMap<ProjectAssetLoader, Map<string, Promise<Blob | null>>>();
+function readAsset(loadAsset: ProjectAssetLoader, version: ProjectVersion, md5ext: string) {
+    let cache = reads.get(loadAsset);
+    if (!cache) reads.set(loadAsset, cache = new Map());
+    const key = version + ':' + md5ext;
+    let read = cache.get(key);
+    if (!read) {
+        read = loadAsset({version, md5ext, signal: new AbortController().signal}).catch(() => null);
+        cache.set(key, read);
+    }
+    return read;
+}
+
+/** Loads the current costume of one version of a target as an object URL for an image, or `null` while it is unavailable. */
+export function useCostumeImage(target: ProjectTarget | undefined, version: ProjectVersion, loadAsset?: ProjectAssetLoader): string | null {
+    const costume = target && loadAsset ? currentCostume(target) : null;
+    const key = costume ? version + ':' + costume.md5ext : '';
+    const [image, setImage] = useState<{key: string; url: string}>();
+    useEffect(() => {
+        if (!costume || !loadAsset) return;
+        let active = true;
+        let url: string | undefined;
+        void readAsset(loadAsset, version, costume.md5ext).then(blob => {
+            if (!blob || !active) return;
+            url = URL.createObjectURL(new Blob([blob], {type: costume.type}));
+            setImage({key, url});
+        });
+        return () => {
+            active = false;
+            if (url) URL.revokeObjectURL(url);
+        };
+    }, [key, loadAsset]);
+    return image?.key === key ? image.url : null;
+}

package/src/project-source-diff.css

@@ -22,8 +22,26 @@
 .twgit-block-diff-sides { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
 .twgit-block-diff-side { padding: 10px 14px; min-width: 0; }
 .twgit-block-diff-side + .twgit-block-diff-side { border-inline-start: 1px solid color-mix(in srgb, CanvasText 20%, Canvas); }
-.twgit-block-diff-preview { overflow: auto; max-height: 420px; }
-.twgit-block-diff-surface { position: relative; min-width: 100%; height: 64px; }
+/* A preview is a small workspace: it scrolls and zooms inside its frame, which people can make taller. */
+.twgit-block-diff-preview {
+    position: relative;
+    overflow: hidden;
+    resize: vertical;
+    min-height: 120px;
+    max-height: 85vh;
+    border: 1px solid color-mix(in srgb, CanvasText 18%, Canvas);
+    border-radius: 6px;
+}
+.twgit-block-diff-surface { position: absolute; inset: 0; }
+.twgit-block-diff-watermark { position: absolute; z-index: 2; top: 10px; right: 12px; pointer-events: none; }
+.twgit-block-diff-watermark[data-navigation] { top: auto; right: var(--plus-watermark-right, 12px); bottom: var(--plus-watermark-bottom, 140px); }
+.twgit-block-diff-watermark > img {
+    display: block;
+    max-width: var(--plus-watermark-size, 48px);
+    max-height: var(--plus-watermark-size, 48px);
+    opacity: .6;
+}
+.twgit-block-diff-link { display: block; padding: 6px 12px 0; }
 /* These markers also apply to the live Editor workspace returned by the host. */
 .twgit-changed-block > .blocklyPath { stroke: var(--twgit-change, #635bce); stroke-width: 2.5px; }
 .twgit-changed-block-part { outline: 2.5px solid #b4510a; outline-offset: 2px; }
@@ -77,3 +95,14 @@
 .twgit-pr-paging, .twgit-pr-revision { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
 .twgit-pr-revision code { overflow-wrap: anywhere; }
 .twgit-review .twgit-block-diff-side h4 { font-size: 1em; }
+
+/* Costume (or backdrop) thumbnails in stage and sprite headings. */
+.twgit-review-thumbnails { display: inline-flex; align-items: center; gap: 4px; margin-inline-end: 6px; vertical-align: middle; }
+.twgit-review-thumbnails img {
+    width: 30px;
+    height: 30px;
+    object-fit: contain;
+    background: Canvas;
+    border: 1px solid var(--twgit-review-line, color-mix(in srgb, CanvasText 18%, Canvas));
+    border-radius: 4px;
+}