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

package/src/project-source-review.tsx

@@ -1,10 +1,12 @@
 import React, {useMemo, useState} from 'react';
-import {BlockPreview} from './block-diff-preview.js';
+import {BlockPreview, usePreviewSync} from './block-diff-preview.js';
 import {isRecord, parseProjectSource, readProjectSourceDiff} from './project-source-patch.js';
 import type {BlockSide} from './project-source-patch.js';
 import {compareProjectForReview} from './project-source-review-model.js';
-import type {ScriptReview} from './project-source-review-model.js';
+import type {ScriptReview, TargetReview} from './project-source-review-model.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+import {currentCostume, useCostumeImage} from './project-assets.js';
+import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
 type Comparison = ReturnType<typeof compareProjectForReview>;
 
@@ -13,7 +15,7 @@ export type ProjectSourceReviewFile = {
     summary?: string;
     previousPath?: string;
     unavailable?: boolean;
-} & ({patch: string; beforeSource?: string} | {status: 'added' | 'removed' | 'updated'});
+} & ({patch: string; beforeSource?: string; loadAsset?: ProjectAssetLoader} | {status: 'added' | 'removed' | 'updated'});
 
 export interface ProjectSourceReviewProps {
     title: string;
@@ -24,26 +26,29 @@ export interface ProjectSourceReviewProps {
     locale?: string;
 }
 
+// Like the Editor's Code tab, a connected group of blocks is called code, and each item is named by its hat block.
 const ja = {
     review: '変更レビュー', fullDescription: 'PR 本文を表示', checks: '確認してほしいこと', files: '変更ファイル', targets: '影響するステージ・スプライト',
-    scripts: 'スクリプトの比較', reviewed: '確認済み', reviewedScripts: 'スクリプト確認済み', before: '変更前', after: '変更後',
+    scripts: 'コードの変更', scriptCount: (count: number) => `コードの変更 · ${count} か所`,
+    reviewed: '確認済み', before: '変更前', after: '変更後',
     updated: '変更', added: '追加', removed: '削除', reorganized: '再編',
-    absent: 'この版にはスクリプトがありません', loading: 'スクリプトを描画中…',
-    unavailable: 'このスクリプトを描画できません。',
+    absent: 'この版にはこのコードがありません', loading: 'コードを描画中…',
+    unavailable: 'このコードを描画できません。',
     related: '関連ファイル', properties: 'コード以外の変更', invalid: 'この作品の差分を読み込めません。',
     flag: '緑の旗が押されたとき', broadcast: 'を受け取ったとき', key: 'キーが押されたとき',
-    click: 'このスプライトが押されたとき', script: 'スクリプト', noChanges: '作品に内容の変更はありません。',
+    click: 'このスプライトが押されたとき', script: 'コード', noChanges: '作品に内容の変更はありません。',
     comparison: '作品の変更', unreadable: '作品データとして読み込めないため、テキストの差分を表示します。'
 };
 const en: typeof ja = {
     review: 'Change review', fullDescription: 'Show full PR description', checks: 'Review checklist', files: 'Changed files', targets: 'Affected stages and sprites',
-    scripts: 'Script comparisons', reviewed: 'Reviewed', reviewedScripts: 'Reviewed scripts', before: 'Before', after: 'After',
+    scripts: 'Code changes', scriptCount: count => `Code changes · ${count}`,
+    reviewed: 'Reviewed', before: 'Before', after: 'After',
     updated: 'Changed', added: 'Added', removed: 'Removed', reorganized: 'Reorganized',
-    absent: 'No script in this version', loading: 'Rendering script…',
-    unavailable: 'This script could not be rendered.',
+    absent: 'No code in this version', loading: 'Rendering code…',
+    unavailable: 'This code could not be rendered.',
     related: 'Related file', properties: 'Changes outside the code', invalid: 'This project diff could not be read.',
     flag: 'When green flag clicked', broadcast: 'received', key: 'When key pressed',
-    click: 'When this sprite clicked', script: 'Script', noChanges: 'No changes to the project contents.',
+    click: 'When this sprite clicked', script: 'Code', noChanges: 'No changes to the project contents.',
     comparison: 'Project changes', unreadable: 'This file could not be read as project data, so its text diff is shown.'
 };
 
@@ -69,11 +74,12 @@ function scriptTitle(side: BlockSide, labels: typeof ja) {
     return typeof block.opcode === 'string' ? block.opcode : labels.script;
 }
 
-function ScriptComparison({script, labels, reviewed = false, setReviewed, renderBlock}: {
+function ScriptComparison({script, labels, reviewed = false, setReviewed, renderBlock, loadAsset}: {
     script: ScriptReview; labels: typeof ja; reviewed?: boolean; setReviewed?(value: boolean): void;
-    renderBlock: ProjectBlockRenderer;
+    renderBlock: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
 }) {
     const [open, setOpen] = useState(false);
+    const {sync, toggle} = usePreviewSync(labels === ja ? 'ja' : 'en');
     const status = !script.before.length ? 'added' : !script.after.length ? 'removed' :
         script.before.length !== 1 || script.after.length !== 1 ? 'reorganized' : 'updated';
     const beforeTitle = script.before[0] && scriptTitle(script.before[0], labels);
@@ -91,10 +97,12 @@ function ScriptComparison({script, labels, reviewed = false, setReviewed, render
                 {(['before', 'after'] as const).map(version => <div key={version}>
                     {script[version].length ? script[version].map((side, index, sides) => <BlockPreview key={side.id} side={side}
                         title={sides.length > 1 ? `${labels[version]} ${index + 1}` : labels[version]}
-                        marks={side.marks} renderBlock={renderBlock} withContext labels={labels}/>) :
+                        marks={side.marks} renderBlock={renderBlock} withContext labels={labels}
+                        version={version} loadAsset={loadAsset} sync={sync}/>) :
                         <BlockPreview title={labels[version]} renderBlock={renderBlock} withContext labels={labels}/>}
                 </div>)}
             </div>
+            {toggle}
             {setReviewed && <label className="twgit-review-checked"><input type="checkbox" checked={reviewed}
                 onChange={event => setReviewed(event.currentTarget.checked)}/> {labels.reviewed}</label>}
         </>}
@@ -105,20 +113,42 @@ function propertyNames(keys: readonly string[], labels: typeof ja) {
     return keys.map(key => properties.get(key)?.[labels === ja ? 0 : 1] ?? key).join(' · ');
 }
 
-/** Lists the changed stages and sprites of one project file, each with its script comparisons. */
-function ComparisonTargets({comparison, labels, renderBlock, review}: {
-    comparison: Comparison; labels: typeof ja; renderBlock: ProjectBlockRenderer;
+/**
+ * The current costume (the backdrop for the stage) of each version of a target that has one. A changed costume shows
+ * before → after. Nothing is shown until an image is read, so the heading falls back to the name alone.
+ */
+function TargetThumbnails({target, labels, loadAsset}: {target: TargetReview; labels: typeof ja; loadAsset?: ProjectAssetLoader}) {
+    const images = {before: useCostumeImage(target.before, 'before', loadAsset), after: useCostumeImage(target.after, 'after', loadAsset)};
+    const costumes = {before: target.before && currentCostume(target.before), after: target.after && currentCostume(target.after)};
+    const changed = !!costumes.before && !!costumes.after && costumes.before.md5ext !== costumes.after.md5ext;
+    // An unchanged costume is the same file in both versions, so either read shows it.
+    const versions: ProjectVersion[] = changed ? ['before', 'after'] : [images.after ? 'after' : 'before'];
+    const shown = versions.filter(version => images[version]);
+    if (!shown.length) return null;
+    return <span className="twgit-review-thumbnails">
+        {shown.map((version, index) => <React.Fragment key={version}>
+            {index > 0 && <span aria-hidden="true">→</span>}
+            <img src={images[version]!} title={costumes[version]?.name || undefined}
+                alt={changed ? `${labels[version]}: ${costumes[version]?.name ?? ''}` : ''}/>
+        </React.Fragment>)}
+    </span>;
+}
+
+/** Lists the changed stages and sprites of one project file, each with its code comparisons. */
+function ComparisonTargets({comparison, labels, renderBlock, loadAsset, review}: {
+    comparison: Comparison; labels: typeof ja; renderBlock: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
     review?: {file: string; keys: ReadonlySet<string>; set(key: string, value: boolean): void};
 }) {
     return <>
         {comparison.properties.length > 0 && <p>{labels.properties} · {propertyNames(comparison.properties, labels)}</p>}
         {!comparison.targets.length && !comparison.properties.length && <p>{labels.noChanges}</p>}
         {comparison.targets.map(target => <section className="twgit-review-target" key={JSON.stringify([target.isStage, target.name])}>
-            <h5>{target.name}{target.scripts.length > 0 && <small>{labels.scripts} · {target.scripts.length}</small>}</h5>
+            <h5><TargetThumbnails target={target} labels={labels} loadAsset={loadAsset}/>
+                {target.name}{target.scripts.length > 0 && <small>{labels.scriptCount(target.scripts.length)}</small>}</h5>
             {target.properties.length > 0 && <p>{labels.properties} · {propertyNames(target.properties, labels)}</p>}
             {target.scripts.map(script => {
                 const key = JSON.stringify([review?.file, target.isStage, target.name, script.id]);
-                return <ScriptComparison key={key} script={script} labels={labels} renderBlock={renderBlock}
+                return <ScriptComparison key={key} script={script} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}
                     reviewed={review?.keys.has(key)} setReviewed={review && (value => review.set(key, value))}/>;
             })}
         </section>)}
@@ -136,28 +166,37 @@ export interface ProjectSourceComparisonProps {
     locale?: string;
     /** Shown after an explanation when either version cannot be read as a project. Without it, only an error is shown. */
     fallback?: React.ReactNode;
+    /** Reads the images of both versions for thumbnails. Without it, stages and sprites are shown by name. */
+    loadAsset?: ProjectAssetLoader;
+    /** Shows only the code of this stage or sprite, without the overview and the changes outside the code. */
+    target?: {isStage: boolean; name: string};
 }
 
-/** Compares two versions of a project.source.json by stage, sprite and script, as the pull request review does. */
-export function ProjectSourceComparison({before, after, renderBlock, locale = 'en', fallback}: ProjectSourceComparisonProps) {
+/** Compares two versions of a project.source.json by stage, sprite and code, as the pull request review does. */
+export function ProjectSourceComparison({before, after, renderBlock, locale = 'en', fallback, loadAsset, target}: ProjectSourceComparisonProps) {
     const labels = locale.startsWith('ja') ? ja : en;
+    const only = target && JSON.stringify([target.isStage, target.isStage || target.name]);
     const comparison = useMemo(() => {
+        let result;
         try {
-            return compareProjectForReview(parseProjectSource(before), parseProjectSource(after));
+            result = compareProjectForReview(parseProjectSource(before), parseProjectSource(after));
         } catch {
             return null;
         }
-    }, [before, after]);
+        if (!only) return result;
+        return {properties: [], targets: result.targets.filter(item => JSON.stringify([item.isStage, item.isStage || item.name]) === only)
+            .map(item => ({...item, properties: []}))};
+    }, [before, after, only]);
     if (!comparison) return fallback === undefined ? <p role="alert">{labels.invalid}</p> :
         <><p role="alert" className="twgit-review-unreadable">{labels.unreadable}</p>{fallback}</>;
     return <section className="twgit-block-diff twgit-review twgit-review-comparison" aria-label={labels.comparison}>
-        <header className="twgit-review-overview">
+        {!only && <header className="twgit-review-overview">
             <dl>
                 <div><dt>{labels.targets}</dt><dd>{comparison.targets.length}</dd></div>
                 <div><dt>{labels.scripts}</dt><dd>{countScripts(comparison)}</dd></div>
             </dl>
-        </header>
-        <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock}/>
+        </header>}
+        <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}/>
     </section>;
 }
 
@@ -194,7 +233,7 @@ export function ProjectSourceReview({title, description, verification, files, re
                 <div><dt>{labels.files}</dt><dd>{entries.length}</dd></div>
                 <div><dt>{labels.targets}</dt><dd>{targets}</dd></div>
                 <div><dt>{labels.scripts}</dt><dd>{scripts}</dd></div>
-                {scripts > 0 && <div><dt>{labels.reviewedScripts}</dt><dd>{reviewed.size} / {scripts}</dd></div>}
+                {scripts > 0 && <div><dt>{labels.reviewed}</dt><dd>{reviewed.size} / {scripts}</dd></div>}
             </dl>
             {longBody && <details className="twgit-review-body">
                 <summary>{labels.fullDescription}</summary>
@@ -211,6 +250,7 @@ export function ProjectSourceReview({title, description, verification, files, re
             {'status' in file && <p>{labels.related} · {labels[file.status]}</p>}
             {(invalid || file.unavailable) && <p role="alert">{labels.invalid}</p>}
             {comparison && <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock}
+                loadAsset={'loadAsset' in file ? file.loadAsset : undefined}
                 review={{file: file.path, keys: reviewed, set: setReviewed}}/>}
         </section>)}
     </section>;

package/src/repository.ts

@@ -3,6 +3,8 @@ import {createTwoFilesPatch} from 'diff';
 import {createReadOnlyFs, errorCode, GitPanelError, pathParts, readOptional, sameBytes} from './filesystem.js';
 import {runRemoteOperation} from './remote-operations.js';
 import type {GetRemoteSession, RemoteOperation} from './remote-operations.js';
+import {assetLimit, assetsDirectoryParts, folderSettingsLimit, isAssetName} from './project-asset-paths.js';
+import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
 export {createReadOnlyFs, GitPanelError} from './filesystem.js';
 export type ChangeGroup = 'staged' | 'unstaged' | 'untracked' | 'commit';
@@ -14,6 +16,8 @@ export interface FileChange {
     worktree: boolean;
     oldMode: number | null;
     newMode: number | null;
+    /** For `commit` changes, the commit compared with its first parent. */
+    commit?: string;
 }
 export interface Commit {
     oid: string;
@@ -22,6 +26,14 @@ export interface Commit {
     timestamp: number;
 }
 interface Entry {oid: string; mode: number}
+/** Where one version of a file is read from: a commit or tree, the index, or the working tree. */
+type Source = {kind: 'tree'; ref: string} | {kind: 'index'} | {kind: 'worktree'};
+/**
+ * Two versions of a project folder as a person sees them: the last commit and the working tree, so changes split
+ * across the index and the working tree read as one; or one commit and its first parent.
+ */
+export type ProjectComparison = {kind: 'worktree'} | {kind: 'commit'; commit: string};
+const projectSourceLimit = 16 * 1024 * 1024;
 type Metadata = Map<string, Uint8Array | null>;
 export interface Snapshot {
     branch: string | undefined;
@@ -211,7 +223,7 @@ export async function openRepository(root: FileSystemDirectoryHandle) {
             const a = before.get(path), b = after.get(path);
             if (a?.oid !== b?.oid || a?.mode !== b?.mode) result.push({
                 path, group: 'commit', before: a?.oid ?? null, after: b?.oid ?? null,
-                oldMode: a?.mode ?? null, newMode: b?.mode ?? null, worktree: false
+                oldMode: a?.mode ?? null, newMode: b?.mode ?? null, worktree: false, commit: oid
             });
         }
         await assertSnapshot(snapshot);
@@ -256,6 +268,79 @@ export async function openRepository(root: FileSystemDirectoryHandle) {
         return patch === undefined ? {...base, tooLarge: true, patch: '', text} :
             {...base, patch: 'diff --git a/file b/file\n' + patch.replace(/^=+\n/, ''), text};
     };
+    const sourceOf = async (snapshot: Snapshot, change: FileChange, version: ProjectVersion): Promise<Source | null> => {
+        if (change[version] === null) return null;
+        switch (change.group) {
+        case 'staged': return version === 'after' ? {kind: 'index'} : snapshot.head ? {kind: 'tree', ref: snapshot.head} : null;
+        case 'unstaged': return version === 'after' ? {kind: 'worktree'} : {kind: 'index'};
+        case 'untracked': return version === 'after' ? {kind: 'worktree'} : null;
+        case 'commit': {
+            if (!change.commit) return null;
+            if (version === 'after') return {kind: 'tree', ref: change.commit};
+            const parent = (await git.readCommit({...options, cache, oid: change.commit})).commit.parent[0];
+            return parent ? {kind: 'tree', ref: parent} : null;
+        }
+        }
+    };
+    /** Reads one regular file of one version, or `null` when it is missing or larger than the limit. */
+    const readVersion = async (source: Source, path: string, limit: number): Promise<Uint8Array | null> => {
+        if (source.kind === 'worktree') {
+            const stat = await fs.promises.stat('/' + path).catch(() => null);
+            if (!stat?.isFile() || stat.size > limit) return null;
+            const bytes = await readOptional(fs, '/' + path);
+            return bytes && bytes.byteLength <= limit ? bytes : null;
+        }
+        const entry = (await entries(source.kind === 'tree' ? source.ref : null, path)).get(path);
+        if (!entry || (entry.mode !== 0o100644 && entry.mode !== 0o100755)) return null;
+        const {blob} = await git.readBlob({...options, cache, oid: entry.oid});
+        return blob.byteLength <= limit ? blob : null;
+    };
+    const comparisonSource = async (snapshot: Snapshot, comparison: ProjectComparison, version: ProjectVersion): Promise<Source | null> => {
+        if (comparison.kind === 'worktree') return version === 'after' ? {kind: 'worktree'} : snapshot.head ? {kind: 'tree', ref: snapshot.head} : null;
+        if (version === 'after') return {kind: 'tree', ref: comparison.commit};
+        const parent = (await git.readCommit({...options, cache, oid: comparison.commit})).commit.parent[0];
+        return parent ? {kind: 'tree', ref: parent} : null;
+    };
+    const readAsset = (snapshot: Snapshot, change: FileChange, version: ProjectVersion, md5ext: string, signal: AbortSignal) =>
+        readFolderAsset(snapshot, pathParts(change.path).slice(0, -1), () => sourceOf(snapshot, change, version), md5ext, signal);
+    const readFolderAsset = async (snapshot: Snapshot, folder: string[], resolve: () => Promise<Source | null>, md5ext: string,
+        signal: AbortSignal) => {
+        if (signal.aborted) return null;
+        fs.clearReads();
+        await assertSnapshot(snapshot);
+        const source = await resolve();
+        if (!source) return null;
+        const settings = await readVersion(source, [...folder, 'sb3-source.json'].join('/'), folderSettingsLimit);
+        const directory = assetsDirectoryParts(settings && new TextDecoder().decode(settings));
+        if (!directory || signal.aborted) return null;
+        const bytes = await readVersion(source, [...folder, ...directory, md5ext].join('/'), assetLimit);
+        await fs.checkReads();
+        return bytes && !signal.aborted ? new Blob([bytes as Uint8Array<ArrayBuffer>]) : null;
+    };
+    /** Reads the project file and the assets directory of both versions of a project folder. */
+    const readProject = async (snapshot: Snapshot, folder: string, comparison: ProjectComparison) => {
+        fs.clearReads();
+        await assertSnapshot(snapshot);
+        const parts = pathParts(folder);
+        const read = async (version: ProjectVersion) => {
+            const source = await comparisonSource(snapshot, comparison, version);
+            if (!source) return {source: null, assetsDirectory: 'assets'};
+            const bytes = await readVersion(source, [...parts, 'project.source.json'].join('/'), projectSourceLimit);
+            const settings = await readVersion(source, [...parts, 'sb3-source.json'].join('/'), folderSettingsLimit);
+            const directory = assetsDirectoryParts(settings && new TextDecoder().decode(settings));
+            let text: string | null = null;
+            if (bytes) {
+                try {text = new TextDecoder('utf-8', {fatal: true}).decode(bytes);} catch {
+                    throw new GitPanelError('unsupported');
+                }
+            }
+            return {source: text, assetsDirectory: directory ? directory.join('/') : 'assets'};
+        };
+        const before = await read('before'), after = await read('after');
+        await assertSnapshot(snapshot);
+        await fs.checkReads();
+        return {before: before.source, after: after.source, assetsDirectory: {before: before.assetsDirectory, after: after.assetsDirectory}};
+    };
     const directoryAt = async (path: string) => {
         let directory = root;
         for (const part of pathParts(path)) directory = await directory.getDirectoryHandle(part);
@@ -302,7 +387,27 @@ export async function openRepository(root: FileSystemDirectoryHandle) {
             }),
         read: (scope?: string) => serial(() => read(scope)),
         readDiff: (snapshot: Snapshot, change: FileChange) => serial(() => readDiff(snapshot, change)),
-        historyChanges: (snapshot: Snapshot, oid: string) => serial(() => historyChanges(snapshot, oid))
+        historyChanges: (snapshot: Snapshot, oid: string) => serial(() => historyChanges(snapshot, oid)),
+        /**
+         * Reads the assets of both versions of a selected project file, for thumbnails. Staged changes compare HEAD with
+         * the index, unstaged ones the index with the working tree, untracked ones nothing with the working tree, and
+         * commit changes the first parent with the commit. Each version's sb3-source.json names its assets directory.
+         * Reads never write, and resolve `null` for anything missing, invalid, larger than 10 MiB or changed since the snapshot.
+         */
+        assetLoader: (snapshot: Snapshot, change: FileChange): ProjectAssetLoader => ({version, md5ext, signal}) =>
+            !isAssetName(md5ext) || signal.aborted ? Promise.resolve(null) :
+                serial(() => readAsset(snapshot, change, version, md5ext, signal)).catch(() => null),
+        /**
+         * Reads the project file of a folder in both versions of a comparison, with each version's assets directory.
+         * `null` stands for a version without the file. Throws `changed` when the repository changed since the snapshot.
+         */
+        readProject: (snapshot: Snapshot, folder: string, comparison: ProjectComparison) =>
+            serial(() => readProject(snapshot, folder, comparison)),
+        /** Reads the assets of a folder in both versions of a comparison, like `assetLoader`. */
+        projectAssetLoader: (snapshot: Snapshot, folder: string, comparison: ProjectComparison): ProjectAssetLoader =>
+            ({version, md5ext, signal}) => !isAssetName(md5ext) || signal.aborted ? Promise.resolve(null) :
+                serial(() => readFolderAsset(snapshot, pathParts(folder), () => comparisonSource(snapshot, comparison, version),
+                    md5ext, signal)).catch(() => null)
     };
 }
 export type Repository = Awaited<ReturnType<typeof openRepository>>;

package/src/scratch-block-diff-renderer.ts

@@ -6,12 +6,25 @@ import type {DiffSvgBlock} from './block-diff-location.js';
 interface BlockWorkspace {
     dispose(): void;
     markFocused(): void;
-    getBlocksBoundingBox(): {width: number; height: number};
+    getBlocksBoundingBox(): {x?: number; y?: number; width: number; height: number};
     getBlockById(id: string): DiffSvgBlock | null;
-    options?: {pathToMedia?: string};
+    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;
@@ -30,6 +43,12 @@ export interface ScratchBlockDiffRendererOptions {
         createBlock(block: {id: string}, 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;
@@ -37,9 +56,25 @@ export interface ScriptBlockMark {
     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>;
 
 function scriptRoot({target, id}: BlockSide): string {
     const visited = new Set<string>();
@@ -136,9 +171,81 @@ function placeholderDefinition(element: Element, opcode: string, type: string, b
     return definition;
 }
 
+// Scratch Blocks' scale for the code area, which keeps the blocks the size people edit them at.
+const defaultScale = 0.675;
+const padding = 16;
+const minHeight = 160;
+const maxHeight = 420;
+
+/**
+ * Sizes a preview frame to its blocks and reports scrolling and zooming, so both versions can move together.
+ * The frame keeps a gutter on the right for the zoom buttons, and for the minimap and thumbnail when present.
+ */
+function createView(workspace: BlockWorkspace, blockly: ScratchBlocksPort, surface: HTMLElement, frame: HTMLElement,
+    startScale: number, navigation: boolean) {
+    const bounds = workspace.getBlocksBoundingBox();
+    const left = bounds.x ?? 0, top = bounds.y ?? 0;
+    const gutter = navigation ? 150 : 56;
+    const width = frame.clientWidth || 400;
+    const scale = Math.max(0.25, Math.min(startScale, (width - padding - gutter) / Math.max(1, bounds.width),
+        (maxHeight - 2 * padding) / Math.max(1, bounds.height)));
+    const fit = {scale, height: Math.min(maxHeight, Math.max(minHeight, Math.ceil(bounds.height * scale + 2 * padding)))};
+    const listeners = new Set<() => void>();
+    const translate = workspace.translate?.bind(workspace);
+    let quiet = false;
+    // Scrolling, dragging and every zoom end in translate, which moves the canvas.
+    if (translate) workspace.translate = (x, y) => {
+        translate(x, y);
+        if (!quiet) for (const listener of listeners) listener();
+    };
+    const setViewport = ({scale, x, y}: BlockPreviewViewport) => {
+        if (!translate) return;
+        quiet = true;
+        try {
+            // setScale would also close menus in the Editor's own workspace.
+            workspace.scale = scale;
+            workspace.scrollX = x;
+            workspace.scrollY = y;
+            const metrics = workspace.getMetrics?.();
+            translate(x + (metrics?.absoluteLeft ?? 0), y + (metrics?.absoluteTop ?? 0));
+            workspace.scrollbar?.resize();
+        } finally {
+            quiet = false;
+        }
+    };
+    const layout = ({scale, height}: {scale: number; height: number}) => {
+        // The frame takes the height, so people can still drag its resize handle afterwards.
+        frame.style.height = height + 'px';
+        blockly.svgResize(workspace);
+        setViewport({scale, x: padding - left * scale, y: padding - top * scale});
+    };
+    layout(fit);
+    // Keep the drawing area matched to the frame when the panel or the frame is resized.
+    const resize = new (surface.ownerDocument.defaultView ?? globalThis).ResizeObserver(() => blockly.svgResize(workspace));
+    resize.observe(surface);
+    // A plain wheel scrolls the review; Ctrl and trackpad pinches still zoom the preview.
+    const wheel = (event: WheelEvent) => {if (!event.ctrlKey) event.stopPropagation();};
+    surface.addEventListener('wheel', wheel, {capture: true});
+    const api: BlockPreviewView = {
+        fit, layout, setViewport,
+        viewport: () => ({scale: workspace.scale ?? fit.scale, x: workspace.scrollX ?? 0, y: workspace.scrollY ?? 0}),
+        onChange(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        }
+    };
+    return {api, dispose() {
+        frame.style.removeProperty('height');
+        listeners.clear();
+        resize.disconnect();
+        surface.removeEventListener('wheel', wheel, {capture: true});
+        if (translate) workspace.translate = translate;
+    }};
+}
+
 /** Use the host's Scratch VM serializer and Scratch Blocks definitions in an isolated workspace. */
 export function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendererOptions): ProjectBlockRenderer {
-    return async ({container, target, id, withContext, parts = [], marks, signal}) => {
+    return async ({container, target, id, withContext, parts = [], marks, signal, watermark}) => {
         const blockly = await options.getBlockly();
         if (signal.aborted) return;
         const root = withContext ? scriptRoot({target, id}) : id;
@@ -157,11 +264,16 @@ export function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendere
         surface.className = 'twgit-block-diff-surface';
         container.append(surface);
         let workspace: BlockWorkspace | undefined;
+        let view!: ReturnType<typeof createView>;
+        let navigation: {dispose(): void} | null | undefined;
+        const cleanups: (() => void)[] = [];
         const placeholders: string[] = [];
         const dispose = () => {
             const active = blockly.getMainWorkspace();
+            for (const cleanup of cleanups.splice(0)) cleanup();
             blockly.Events.disable();
             try {
+                navigation?.dispose();
                 workspace?.dispose();
             } finally {
                 if (active === workspace) blockly.mainWorkspace = main;
@@ -183,7 +295,9 @@ export function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendere
                     options.locale ?? container.ownerDocument.documentElement.lang)]);
                 element.setAttribute('type', alias);
             }
-            workspace = blockly.inject(surface, {readOnly: true, sounds: false, media: main?.options?.pathToMedia});
+            const startScale = main?.options?.zoomOptions?.startScale ?? defaultScale;
+            workspace = blockly.inject(surface, {readOnly: true, sounds: false, media: main?.options?.pathToMedia, scrollbars: true,
+                zoom: {controls: true, wheel: true, startScale, maxScale: 4, minScale: 0.25, scaleSpeed: 1.2}});
             workspace.markFocused = () => {};
             blockly.Xml.domToWorkspace(dom, workspace);
             if (marks) {
@@ -197,10 +311,14 @@ export function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendere
                 const changed = workspace.getBlockById(id === root ? serializedRoot : id);
                 if (changed) markBlockLocation(changed, parts);
             }
-            const bounds = workspace.getBlocksBoundingBox();
-            surface.style.width = Math.max(100, Math.ceil(bounds.width) + 48) + 'px';
-            surface.style.height = Math.max(64, Math.ceil(bounds.height) + 48) + 'px';
-            blockly.svgResize(workspace);
+            view = createView(workspace, blockly, surface, container, startScale, !!options.attachNavigation);
+            cleanups.push(view.dispose);
+            navigation = options.attachNavigation?.(workspace, blockly, watermark);
+            if (navigation && watermark) {
+                // The host now positions the thumbnail beside its minimap.
+                watermark.dataset.navigation = '';
+                cleanups.push(() => delete watermark.dataset.navigation);
+            }
         } catch (error) {
             dispose();
             throw error;
@@ -208,6 +326,6 @@ export function createScratchBlocksDiffRenderer(options: ScratchBlockDiffRendere
             blockly.mainWorkspace = main;
             blockly.Events.enable();
         }
-        return dispose;
+        return {dispose, view: view.api};
     };
 }

package/src/style.css

@@ -27,3 +27,20 @@
 .twgit-view-switch { display: flex; flex-wrap: wrap; gap: 4px; margin: 0 0 10px; }
 .twgit-review-unreadable { margin: 6px 0; padding: 8px; background: color-mix(in srgb, #d9822b 16%, Canvas); }
 .twgit-review-comparison .twgit-review-overview dl { margin: 4px 0 8px; }
+.twgit-element-list > section { margin: 6px 0 10px; }
+.twgit-element-target { display: flex; align-items: center; gap: 6px; margin: 10px 0 4px; font-size: 14px; }
+.twgit-element-target img, .twgit-element img, .twgit-element-thumbnail { width: 28px; height: 28px; object-fit: contain; flex: none; }
+.twgit-element-thumbnail { display: inline-block; border-radius: 4px; background: color-mix(in srgb, CanvasText 8%, Canvas); }
+.twgit-panel .twgit-element { display: flex; align-items: center; gap: 6px; padding-inline-start: 10px; }
+.twgit-element-name { flex: 1; min-width: 0; overflow-wrap: anywhere; }
+.twgit-file-list { margin-top: 10px; }
+.twgit-element-pictures { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; }
+.twgit-element-picture { margin: 0; padding: 10px; border: 1px solid color-mix(in srgb, CanvasText 18%, Canvas); border-radius: 6px; }
+.twgit-element-picture img { display: block; max-width: 100%; max-height: 260px; margin: 8px auto 0; object-fit: contain;
+    background: repeating-conic-gradient(color-mix(in srgb, CanvasText 6%, Canvas) 0 25%, Canvas 0 50%) 0 0 / 16px 16px; }
+.twgit-element-values { border-collapse: collapse; width: 100%; font-size: 13px; }
+.twgit-element-values th, .twgit-element-values td { text-align: start; vertical-align: top; padding: 6px 8px;
+    border-bottom: 1px solid color-mix(in srgb, CanvasText 15%, Canvas); overflow-wrap: anywhere; }
+.twgit-element-values td { font-family: ui-monospace, monospace; }
+.twgit-element-files { margin-top: 12px; }
+.twgit-panel .twgit-element span.twgit-element-name { width: auto; font-family: inherit; }