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

package/src/project-source-diff.tsx

@@ -3,7 +3,7 @@ import {compareProjectBlocks, readProjectSourceDiff} from './project-source-patc
 import type {BlockChange} from './project-source-patch.js';
 import type {ProjectBlockLocator} from './block-diff-location.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
-import {BlockPreview} from './block-diff-preview.js';
+import {BlockPreview, usePreviewSync} from './block-diff-preview.js';
 import type {LocationStatus} from './block-diff-preview.js';
 import './project-source-diff.css';
 
@@ -15,17 +15,22 @@ export {createScratchBlocksDiffLocator} from './block-diff-location.js';
 export type {ProjectBlockLocation, ProjectBlockLocator, ScratchBlockLocationWorkspace} from './block-diff-location.js';
 export type {BlockPart} from './project-source-patch.js';
 export {createProjectSourceDiff} from './project-source-patch.js';
+export {currentCostume} from './project-assets.js';
+export type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 export {createScratchBlocksDiffRenderer} from './scratch-block-diff-renderer.js';
-export type {ProjectBlockRenderer, ScratchBlockDiffRendererOptions, ScratchBlocksPort} from './scratch-block-diff-renderer.js';
+export type {BlockPreviewView, BlockPreviewViewport, ProjectBlockRenderer, ProjectBlockRendering, ScratchBlockDiffRendererOptions,
+    ScratchBlocksPort} from './scratch-block-diff-renderer.js';
+export {createPreviewSync} from './block-diff-preview.js';
+export type {PreviewSync} from './block-diff-preview.js';
 
 const en = {
     title: 'Block changes', before: 'Before', after: 'After', added: 'Added', removed: 'Removed', updated: 'Changed',
     inputs: 'Inputs', fields: 'Fields', opcode: 'Block type', mutation: 'Block shape', position: 'Position',
     connection: 'Connections', properties: 'Other block properties',
     absent: 'No block on this side', omitted: (count: number) => `${count} unchanged blocks omitted from the change list`,
-    context: 'Highlight in the surrounding script', more: 'Show more changes', noChanges: 'No block changes.',
+    context: 'Highlight in the surrounding code', more: 'Show more changes', noChanges: 'No block changes.',
     locate: 'Highlight in Editor', locating: 'Finding the block in the Editor…', located: 'Highlighted in the Editor.',
-    missingLocation: 'This version or block is unavailable in the Editor. Open its surrounding script here.',
+    missingLocation: 'This version or block is unavailable in the Editor. Open its surrounding code here.',
     partLegend: 'Orange outlines mark changed inputs and fields.',
     otherChanges: 'The project also has changes outside its block code.',
     invalid: 'This diff could not be read. Use a full-context project diff, or provide the original project.',
@@ -36,9 +41,9 @@ const ja: typeof en = {
     inputs: '入力値', fields: 'フィールド', opcode: 'ブロックの種類', mutation: 'ブロックの形', position: '位置',
     connection: 'つなぎ方', properties: 'その他のブロック属性',
     absent: 'この側にはブロックがありません', omitted: count => `変更のないブロック ${count} 個を一覧から省略`,
-    context: '元のスクリプト内で強調', more: '続きを表示', noChanges: 'ブロックの変更はありません。',
+    context: '元のコード内で強調', more: '続きを表示', noChanges: 'ブロックの変更はありません。',
     locate: '編集画面で強調', locating: '編集画面でブロックを検索中…', located: '編集画面で強調しました。',
-    missingLocation: '編集画面に該当する版またはブロックがありません。元のスクリプトをここで展開できます。',
+    missingLocation: '編集画面に該当する版またはブロックがありません。元のコードをここで展開できます。',
     partLegend: 'オレンジの枠は、変更された入力欄やフィールドです。',
     otherChanges: 'ブロックのコード以外にも作品の変更があります。',
     invalid: '差分を読み込めません。全体の文脈を含む差分を使うか、変更前の作品を指定してください。',
@@ -66,6 +71,7 @@ function ChangeCard({change, renderBlock, labels, onLocate, location}: {
     onLocate?: (version: Version) => void; location?: {version: Version; status: LocationStatus};
 }) {
     const [withContext, setWithContext] = useState(false);
+    const {sync, toggle} = usePreviewSync(labels === en ? 'en' : 'ja');
     const notes = [...new Set(change.fields.map(field => labels[propertyLabels.get(field) ?? 'properties']))];
     const name = (change.after ?? change.before)!.target.name;
     return <article className={`twgit-block-diff-card twgit-block-diff-${change.kind}`}>
@@ -77,9 +83,10 @@ function ChangeCard({change, renderBlock, labels, onLocate, location}: {
         <div className="twgit-block-diff-sides">
             {(['before', 'after'] as const).map(version => <BlockPreview key={version} side={change[version]} title={labels[version]}
                 renderBlock={renderBlock} withContext={withContext} labels={labels} parts={change.parts}
-                onLocate={onLocate && (() => onLocate(version))}
+                onLocate={onLocate && (() => onLocate(version))} version={version} sync={sync}
                 locationStatus={location?.version === version ? location.status : undefined}/>)}
         </div>
+        {toggle}
         <label><input type="checkbox" checked={withContext} onChange={event => setWithContext(event.currentTarget.checked)}/> {labels.context}</label>
     </article>;
 }

package/src/project-source-review-model.ts

@@ -11,6 +11,9 @@ export interface ScriptReview {
 export interface TargetReview {
     name: string;
     isStage: boolean;
+    /** The stage or sprite in each version, absent where it does not exist. */
+    before?: ProjectTarget;
+    after?: ProjectTarget;
     scripts: ScriptReview[];
     properties: string[];
 }
@@ -106,7 +109,7 @@ export function compareProjectForReview(before: ProjectSource, after: ProjectSou
         const properties = changedProperties({...a}, {...b}, 'blocks');
         if (scripts.length || properties.length) {
             const {name, isStage} = (b ?? a)!;
-            targets.push({name, isStage, scripts, properties});
+            targets.push({name, isStage, scripts, properties, before: a, after: b});
         }
     }
     return {targets, properties: changedProperties(before, after, 'targets')};

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,10 +166,12 @@ 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;
 }
 
-/** 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}: ProjectSourceComparisonProps) {
     const labels = locale.startsWith('ja') ? ja : en;
     const comparison = useMemo(() => {
         try {
@@ -157,7 +189,7 @@ export function ProjectSourceComparison({before, after, renderBlock, locale = 'e
                 <div><dt>{labels.scripts}</dt><dd>{countScripts(comparison)}</dd></div>
             </dl>
         </header>
-        <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock}/>
+        <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}/>
     </section>;
 }
 
@@ -194,7 +226,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 +243,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,8 @@ 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'};
 type Metadata = Map<string, Uint8Array | null>;
 export interface Snapshot {
     branch: string | undefined;
@@ -211,7 +217,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 +262,47 @@ 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 readAsset = async (snapshot: Snapshot, change: FileChange, version: ProjectVersion, md5ext: string, signal: AbortSignal) => {
+        if (signal.aborted) return null;
+        fs.clearReads();
+        await assertSnapshot(snapshot);
+        const source = await sourceOf(snapshot, change, version);
+        if (!source) return null;
+        const folder = pathParts(change.path).slice(0, -1);
+        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;
+    };
     const directoryAt = async (path: string) => {
         let directory = root;
         for (const part of pathParts(path)) directory = await directory.getDirectoryHandle(part);
@@ -302,7 +349,16 @@ 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)
     };
 }
 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};
     };
 }