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

package/src/project-assets.ts

@@ -0,0 +1,78 @@
+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;
+}
+
+/** The image type of an asset file name, or `undefined` for sounds and anything that is not an image. */
+export function assetImageType(md5ext: string): string | undefined {
+    const match = /^[0-9A-Za-z_-]{1,128}\.([0-9A-Za-z]{1,8})$/.exec(md5ext);
+    return match ? imageTypes[match[1].toLowerCase()] : undefined;
+}
+
+/** Loads one image asset of one version as an object URL, or `null` while it is unavailable or not an image. */
+export function useAssetImage(md5ext: string | undefined, version: ProjectVersion, loadAsset?: ProjectAssetLoader): string | null {
+    const type = md5ext ? assetImageType(md5ext) : undefined;
+    const key = md5ext && type && loadAsset ? version + ':' + md5ext : '';
+    const [image, setImage] = useState<{key: string; url: string}>();
+    useEffect(() => {
+        if (!key || !loadAsset) return;
+        let active = true;
+        let url: string | undefined;
+        void readAsset(loadAsset, version, md5ext!).then(blob => {
+            if (!blob || !active) return;
+            url = URL.createObjectURL(new Blob([blob], {type}));
+            setImage({key, url});
+        });
+        return () => {
+            active = false;
+            if (url) URL.revokeObjectURL(url);
+        };
+    }, [key, loadAsset]);
+    return image?.key === key ? image.url : null;
+}
+
+/** 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;
+    return useAssetImage(costume?.md5ext, version, loadAsset);
+}

package/src/project-change-list.tsx

@@ -0,0 +1,210 @@
+import React, {useEffect, useState} from 'react';
+import {organizeProjectChanges, projectPropertyLabel} from './project-change-model.js';
+import type {ChangedFile, ProjectChangeList, ProjectElementChange, ProjectTargetChanges} from './project-change-model.js';
+import {parseProjectSource} from './project-source-patch.js';
+import {useAssetImage, useCostumeImage} from './project-assets.js';
+import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
+import {ProjectSourceComparison} from './project-source-review.js';
+import type {ChangeGroup, FileChange, Repository, Snapshot} from './repository.js';
+import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+
+const en = {
+    title: 'Changes by project element', stage: 'Stage', code: (count: number) => `Code · ${count} ${count === 1 ? 'change' : 'changes'}`,
+    costumes: 'Costume', backdrops: 'Backdrop', sounds: 'Sound', data: 'Variables and messages', settings: 'Other settings',
+    project: 'Whole project', other: 'Files outside the project', added: 'Added', removed: 'Removed', updated: 'Changed',
+    files: 'Files and Git groups', before: 'Before', after: 'After', absent: 'Not in this version',
+    loading: 'Reading the project changes…', unreadable: 'The project data could not be read, so the changes are listed by file.',
+    fileList: 'List by file', property: 'Item', format: 'Format', rate: 'Sample rate', samples: 'Samples', file: 'File name',
+    noImage: 'No image', groups: {staged: 'Staged', unstaged: 'Unstaged', untracked: 'Untracked', commit: 'Commit'} as Record<ChangeGroup, string>
+};
+const ja: typeof en = {
+    title: '作品の要素ごとの変更', stage: 'ステージ', code: count => `コード · ${count} か所`,
+    costumes: 'コスチューム', backdrops: '背景', sounds: '音', data: '変数・リスト・メッセージ', settings: 'そのほかの設定',
+    project: '作品全体', other: '作品に属さないファイル', added: '追加', removed: '削除', updated: '変更',
+    files: 'ファイルと Git の区分', before: '変更前', after: '変更後', absent: 'この版にはありません',
+    loading: '作品の変更を読み込み中…', unreadable: '作品データを読み込めないため、ファイル単位で一覧にします。',
+    fileList: 'ファイル単位の一覧', property: '項目', format: '形式', rate: 'サンプリング周波数', samples: 'サンプル数', file: 'ファイル名',
+    noImage: '画像なし', groups: {staged: 'ステージ済み', unstaged: '未ステージ', untracked: '未追跡', commit: 'コミット'}
+};
+type Labels = typeof en;
+export const projectChangeLabels = (locale: string): Labels => locale.startsWith('ja') ? ja : en;
+
+export interface ProjectChanges {
+    list: ProjectChangeList;
+    sources: {before: string | null; after: string | null};
+    loadAsset: ProjectAssetLoader;
+}
+
+/**
+ * Reads the selected project folder in the last commit and the working tree (or a commit and its parent) and arranges
+ * the changed files by stage, sprite and element. `undefined` while there is no project; `'loading'` and `'unreadable'`
+ * tell the panel to keep the list by file.
+ */
+export function useProjectChanges(repository: Repository | null, snapshot: Snapshot | null, project: string | null,
+    commit: string | null, changes: readonly FileChange[]): ProjectChanges | 'loading' | 'unreadable' | undefined {
+    const [result, setResult] = useState<{changes: readonly FileChange[]; value: ProjectChanges | 'unreadable'}>();
+    const active = !!repository && !!snapshot && project !== null && changes.length > 0;
+    useEffect(() => {
+        if (!repository || !snapshot || project === null || !changes.length) return;
+        let current = true;
+        const comparison = commit ? {kind: 'commit' as const, commit} : {kind: 'worktree' as const};
+        void repository.readProject(snapshot, project, comparison).then(read => {
+            if (!current) return;
+            let list: ProjectChangeList;
+            try {
+                list = organizeProjectChanges({folder: project,
+                    before: read.before === null ? null : parseProjectSource(read.before),
+                    after: read.after === null ? null : parseProjectSource(read.after),
+                    assetsDirectory: read.assetsDirectory, files: changes.map(({path, group}) => ({path, group}))});
+            } catch {
+                setResult({changes, value: 'unreadable'});
+                return;
+            }
+            setResult({changes, value: {list, sources: {before: read.before, after: read.after},
+                loadAsset: repository.projectAssetLoader(snapshot, project, comparison)}});
+        }, () => {if (current) setResult({changes, value: 'unreadable'});});
+        return () => {current = false;};
+    }, [repository, snapshot, project, commit, changes]);
+    if (!active) return undefined;
+    // Keep the last list while a refresh reads again, so the panel does not fall back to files and back.
+    if (result?.changes === changes || (result && typeof result.value === 'object')) return result!.value;
+    return 'loading';
+}
+
+function TargetHeading({target, labels, loadAsset}: {target: ProjectTargetChanges; labels: Labels; loadAsset: ProjectAssetLoader}) {
+    const version: ProjectVersion = target.after ? 'after' : 'before';
+    const image = useCostumeImage(target[version], version, loadAsset);
+    return <h4 className="twgit-element-target">
+        {image ? <img src={image} alt=""/> : <span className="twgit-element-thumbnail"/>}
+        <span>{target.isStage ? labels.stage : target.name}</span>
+        {target.status !== 'updated' && <small className="twgit-review-status">{labels[target.status]}</small>}
+    </h4>;
+}
+
+function elementTitle(element: ProjectElementChange, target: ProjectTargetChanges | null, labels: Labels, locale: string) {
+    switch (element.kind) {
+    case 'code': return labels.code(element.scripts ?? 0);
+    case 'costumes': return `${target?.isStage ? labels.backdrops : labels.costumes} · ${element.name ?? ''}`;
+    case 'sounds': return `${labels.sounds} · ${element.name ?? ''}`;
+    default: {
+        const names = (element.properties ?? []).map(key => projectPropertyLabel(key, locale)).join('・');
+        return target ? `${element.kind === 'data' ? labels.data : labels.settings} · ${names}` : names;
+    }
+    }
+}
+
+function ElementRow({element, target, labels, locale, loadAsset, selected, busy, onSelect}: {
+    element: ProjectElementChange; target: ProjectTargetChanges | null; labels: Labels; locale: string;
+    loadAsset: ProjectAssetLoader; selected: boolean; busy: boolean; onSelect(): void;
+}) {
+    const version: ProjectVersion = element.md5ext?.after ? 'after' : 'before';
+    const image = useAssetImage(element.kind === 'costumes' ? element.md5ext?.[version] : undefined, version, loadAsset);
+    return <li><button className="twgit-file twgit-element" data-git-element={element.kind} disabled={busy} aria-pressed={selected}
+        onClick={onSelect}>
+        {element.kind === 'costumes' && (image ? <img src={image} alt=""/> : <span className="twgit-element-thumbnail"/>)}
+        <span className="twgit-element-name">{elementTitle(element, target, labels, locale)}</span>
+        {element.status !== 'updated' && <small className="twgit-review-status">{labels[element.status]}</small>}
+    </button></li>;
+}
+
+/** The change list arranged by the project's stage, sprites and elements, with files outside the project after them. */
+export function ProjectChangeListView({changes, selected, locale, busy, onSelect, onSelectFile, fileList, fileListOpen, setFileListOpen}: {
+    changes: ProjectChanges; selected: string | null; locale: string; busy: boolean;
+    onSelect(key: string): void; onSelectFile(file: ChangedFile): void; fileList: React.ReactNode;
+    fileListOpen: boolean; setFileListOpen(open: boolean): void;
+}) {
+    const labels = projectChangeLabels(locale);
+    const {list, loadAsset} = changes;
+    return <section className="twgit-element-list" aria-label={labels.title}>
+        {list.targets.map(target => <section key={target.key}>
+            <TargetHeading target={target} labels={labels} loadAsset={loadAsset}/>
+            <ul>{target.elements.map(element => <ElementRow key={element.key} element={element} target={target} labels={labels}
+                locale={locale} loadAsset={loadAsset} selected={selected === element.key} busy={busy} onSelect={() => onSelect(element.key)}/>)}</ul>
+        </section>)}
+        {list.project.length > 0 && <section>
+            <h4 className="twgit-element-target"><span>{labels.project}</span></h4>
+            <ul>{list.project.map(element => <ElementRow key={element.key} element={element} target={null} labels={labels}
+                locale={locale} loadAsset={loadAsset} selected={selected === element.key} busy={busy} onSelect={() => onSelect(element.key)}/>)}</ul>
+        </section>}
+        {list.other.length > 0 && <section>
+            <h4 className="twgit-element-target"><span>{labels.other}</span></h4>
+            <ul>{list.other.map(file => <li key={file.group + ':' + file.path}><button className="twgit-file" data-git-other={file.group}
+                disabled={busy} onClick={() => onSelectFile(file)}>{file.path} <small>{labels.groups[file.group]}</small></button></li>)}</ul>
+        </section>}
+        <details className="twgit-file-list" open={fileListOpen}
+            onToggle={event => setFileListOpen((event.currentTarget as HTMLDetailsElement).open)}>
+            <summary>{labels.fileList}</summary>{fileList}</details>
+    </section>;
+}
+
+export function findElement(list: ProjectChangeList, key: string | null) {
+    if (key === null) return null;
+    for (const target of list.targets) {
+        const element = target.elements.find(item => item.key === key);
+        if (element) return {element, target};
+    }
+    const element = list.project.find(item => item.key === key);
+    return element ? {element, target: null} : null;
+}
+
+function Picture({md5ext, version, loadAsset, labels, title}: {
+    md5ext?: string; version: ProjectVersion; loadAsset: ProjectAssetLoader; labels: Labels; title: string;
+}) {
+    const image = useAssetImage(md5ext, version, loadAsset);
+    return <figure className="twgit-element-picture">
+        <figcaption>{title}</figcaption>
+        {!md5ext ? <p>{labels.absent}</p> : image ? <img src={image} alt={title}/> : <p>{labels.noImage}</p>}
+    </figure>;
+}
+
+const show = (value: unknown) => {
+    if (value === undefined) return '—';
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    return text.length > 400 ? text.slice(0, 400) + '…' : text;
+};
+
+/** The details of one selected row: its code, pictures or values in both versions, and the files behind it. */
+export function ProjectElementView({changes, selection, locale, renderBlock, onSelectFile}: {
+    changes: ProjectChanges; selection: {element: ProjectElementChange; target: ProjectTargetChanges | null}; locale: string;
+    renderBlock?: ProjectBlockRenderer; onSelectFile(file: ChangedFile): void;
+}) {
+    const labels = projectChangeLabels(locale);
+    const {element, target} = selection;
+    const record = (version: ProjectVersion): Record<string, unknown> | undefined => {
+        if (element.kind === 'costumes' || element.kind === 'sounds') return element[version];
+        if (!target) {
+            const source = changes.sources[version];
+            try {
+                return source === null ? undefined : parseProjectSource(source) as Record<string, unknown>;
+            } catch {
+                return undefined;
+            }
+        }
+        return target[version] as Record<string, unknown> | undefined;
+    };
+    const rows = element.kind === 'sounds' ? [['name', 'name'], ['dataFormat', labels.format], ['rate', labels.rate],
+        ['sampleCount', labels.samples], ['md5ext', labels.file]] as const :
+        (element.properties ?? []).map(key => [key, projectPropertyLabel(key, locale)] as const);
+    return <section className="twgit-element-view" aria-label={elementTitle(element, target, labels, locale)}>
+        <h3>{target && <span>{target.isStage ? labels.stage : target.name} · </span>}{elementTitle(element, target, labels, locale)}</h3>
+        {element.kind === 'code' && target && renderBlock && <ProjectSourceComparison before={changes.sources.before}
+            after={changes.sources.after} renderBlock={renderBlock} locale={locale} loadAsset={changes.loadAsset}
+            target={{isStage: target.isStage, name: target.name}}/>}
+        {element.kind === 'costumes' && <div className="twgit-element-pictures">
+            {(['before', 'after'] as const).map(version => <Picture key={version} md5ext={element.md5ext?.[version]} version={version}
+                loadAsset={changes.loadAsset} labels={labels} title={element[version]?.name === undefined ? labels[version] : `${labels[version]} · ${String(element[version]!.name)}`}/>)}
+        </div>}
+        {element.kind !== 'code' && element.kind !== 'costumes' && <table className="twgit-element-values">
+            <thead><tr><th>{labels.property}</th><th>{labels.before}</th><th>{labels.after}</th></tr></thead>
+            <tbody>{rows.map(([key, name]) => <tr key={key}>
+                <th scope="row">{name}</th>
+                <td>{record('before') ? show(record('before')![key]) : labels.absent}</td>
+                <td>{record('after') ? show(record('after')![key]) : labels.absent}</td>
+            </tr>)}</tbody>
+        </table>}
+        <details className="twgit-element-files"><summary>{labels.files}</summary>
+            <ul>{element.files.map(file => <li key={file.group + ':' + file.path}><button className="twgit-file" type="button"
+                onClick={() => onSelectFile(file)}>{file.path} <small>{labels.groups[file.group]}</small></button></li>)}</ul>
+        </details>
+    </section>;
+}

package/src/project-change-model.ts

@@ -0,0 +1,212 @@
+import type {ChangeGroup} from './repository.js';
+import {equal, isRecord, targetKey} from './project-source-patch.js';
+import type {ProjectSource, ProjectTarget} from './project-source-patch.js';
+import {compareProjectForReview} from './project-source-review-model.js';
+
+/** One changed file of the repository, with the Git group it was listed under. A path can appear in several groups. */
+export interface ChangedFile {
+    path: string;
+    group: ChangeGroup;
+}
+
+export type ProjectElementKind = 'code' | 'costumes' | 'sounds' | 'data' | 'settings';
+export type ProjectChangeStatus = 'added' | 'removed' | 'updated';
+
+/** One row of the project-shaped change list: something a person recognizes in the Editor. */
+export interface ProjectElementChange {
+    /** Stable within one list, for React keys and selection. */
+    key: string;
+    kind: ProjectElementKind;
+    status: ProjectChangeStatus;
+    /** Costume or sound name; absent for code, data and settings rows. */
+    name?: string;
+    /** The costume or sound entry in each version, for costume and sound rows. */
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    /** Asset file names (`md5ext`) of each version, for costume and sound rows. */
+    md5ext?: {before?: string; after?: string};
+    /**
+     * Changed property keys, for data and settings rows (for example `variables`, `x`, `visible`), and for
+     * project-level rows (`monitors`, `extensions`, `meta`).
+     */
+    properties?: string[];
+    /** Number of changed code items (as counted by the review comparison), for code rows. */
+    scripts?: number;
+    /** The changed repository files behind this row, so the details view can show them with their Git groups. */
+    files: ChangedFile[];
+}
+
+export interface ProjectTargetChanges {
+    key: string;
+    name: string;
+    isStage: boolean;
+    status: ProjectChangeStatus;
+    before?: ProjectTarget;
+    after?: ProjectTarget;
+    /** In the order code, costumes, sounds, data, settings; costumes and sounds in their order in the target. */
+    elements: ProjectElementChange[];
+}
+
+export interface ProjectChangeList {
+    /** The stage first, then sprites in project order; removed targets after the existing ones. */
+    targets: ProjectTargetChanges[];
+    /** Project-level changes outside the targets (monitors, extensions, meta and other top-level keys). */
+    project: ProjectElementChange[];
+    /** Changed files that belong to no element: sb3-source.json, embedded-extensions.json, unreferenced assets and the rest. */
+    other: ChangedFile[];
+}
+
+export interface OrganizeProjectChangesInput {
+    /** The project folder relative to the repository root, `''` for the root. */
+    folder: string;
+    /** The project data of each version, `null` where the version has no project file. */
+    before: ProjectSource | null;
+    after: ProjectSource | null;
+    /** The assets directory of each version, relative to the folder (from sb3-source.json; `assets` by default). */
+    assetsDirectory: {before: string; after: string};
+    /** Every changed file in the folder, from all Git groups. */
+    files: readonly ChangedFile[];
+}
+
+const targetDataKeys = ['variables', 'lists', 'broadcasts'] as const;
+const nonSettingKeys = new Set(['blocks', 'costumes', 'sounds', ...targetDataKeys]);
+
+const propertyLabels = new Map<string, readonly [string, string]>([
+    ['variables', ['変数', 'Variables']], ['lists', ['リスト', 'Lists']], ['broadcasts', ['メッセージ', 'Broadcast messages']],
+    ['costumes', ['コスチューム・背景', 'Costumes and backdrops']], ['sounds', ['音', 'Sounds']], ['blocks', ['コード', 'Code']],
+    ['x', ['X 座標', 'X position']], ['y', ['Y 座標', 'Y position']], ['size', ['大きさ', 'Size']],
+    ['direction', ['向き', 'Direction']], ['visible', ['表示状態', 'Visibility']],
+    ['currentCostume', ['表示するコスチューム', 'Selected costume']], ['layerOrder', ['重なり順', 'Layer order']],
+    ['volume', ['音量', 'Volume']], ['comments', ['コメント', 'Comments']], ['draggable', ['ドラッグ可否', 'Draggable']],
+    ['rotationStyle', ['回転方法', 'Rotation style']], ['tempo', ['テンポ', 'Tempo']],
+    ['videoTransparency', ['ビデオの透明度', 'Video transparency']], ['videoState', ['ビデオの状態', 'Video state']],
+    ['textToSpeechLanguage', ['音声合成の言語', 'Text to speech language']], ['monitors', ['モニター', 'Monitors']],
+    ['extensions', ['拡張機能', 'Extensions']], ['meta', ['作品の情報', 'Project metadata']]
+]);
+
+/** The Japanese or English name of a project or target property key; unknown keys are returned as they are. */
+export function projectPropertyLabel(key: string, locale = 'en'): string {
+    return propertyLabels.get(key)?.[locale.startsWith('ja') ? 0 : 1] ?? key;
+}
+
+/** The asset file name of a costume or sound entry: `md5ext`, or `assetId.dataFormat`; `''` when it has neither. */
+export function assetFileName(entry: Record<string, unknown>): string {
+    if (typeof entry.md5ext === 'string') return entry.md5ext;
+    return typeof entry.assetId === 'string' && typeof entry.dataFormat === 'string' ? entry.assetId + '.' + entry.dataFormat : '';
+}
+
+function joinPath(...parts: string[]) {
+    return parts.flatMap(part => part.split('/')).filter(part => part !== '' && part !== '.').join('/');
+}
+
+function statusOf(before: unknown, after: unknown): ProjectChangeStatus {
+    return before === undefined ? 'added' : after === undefined ? 'removed' : 'updated';
+}
+
+function entriesOf(target: ProjectTarget | undefined, kind: 'costumes' | 'sounds') {
+    const list = (target as Record<string, unknown> | undefined)?.[kind];
+    return Array.isArray(list) ? list.filter(isRecord) : [];
+}
+
+function nameOf(entry: Record<string, unknown>) {
+    return typeof entry.name === 'string' ? entry.name : '';
+}
+
+/** Pairs the entries of two versions by name (repeated names pair in order): after's order first, then removed ones. */
+function pairEntries(before: Record<string, unknown>[], after: Record<string, unknown>[]) {
+    const remaining = new Map<string, Record<string, unknown>[]>();
+    for (const entry of before) {
+        const queue = remaining.get(nameOf(entry));
+        if (queue) queue.push(entry);
+        else remaining.set(nameOf(entry), [entry]);
+    }
+    const pairs: {name: string; before?: Record<string, unknown>; after?: Record<string, unknown>}[] = [];
+    for (const entry of after) pairs.push({name: nameOf(entry), before: remaining.get(nameOf(entry))?.shift(), after: entry});
+    for (const entry of before) {
+        const queue = remaining.get(nameOf(entry));
+        if (queue?.[0] === entry) pairs.push({name: nameOf(entry), before: queue.shift()});
+    }
+    return pairs;
+}
+
+function changedKeys(before: Record<string, unknown>, after: Record<string, unknown>, skip: (key: string) => boolean) {
+    return [...new Set([...Object.keys(after), ...Object.keys(before)])].filter(key => !skip(key) && !equal(before[key], after[key]));
+}
+
+/** Arranges the changed files of one project folder by stage, sprite and element. Pure; reads nothing. */
+export function organizeProjectChanges(input: OrganizeProjectChangesInput): ProjectChangeList {
+    const {folder, files, assetsDirectory} = input;
+    const normalize = (project: ProjectSource | null): ProjectSource => project === null ? {targets: []} :
+        {...project, targets: project.targets.map(target => ({...target, blocks: target.blocks ?? {}}))};
+    const before = normalize(input.before), after = normalize(input.after);
+    const projectPath = joinPath(folder, 'project.source.json');
+    const projectFiles = files.filter(file => file.path === projectPath);
+    const explained = new Set<string>();
+    let projectUsed = false;
+    const useProject = () => {
+        projectUsed = true;
+        return [...projectFiles];
+    };
+    const filesAt = (paths: (string | undefined)[]) => {
+        const wanted = new Set(paths.filter((path): path is string => path !== undefined));
+        const found = files.filter(file => wanted.has(file.path));
+        for (const file of found) explained.add(file.path);
+        return found;
+    };
+
+    const review = compareProjectForReview(before, after);
+    const scripts = new Map(review.targets.map(target => [targetKey((target.after ?? target.before)!), target.scripts.length]));
+    const oldTargets = new Map(before.targets.map(target => [targetKey(target), target]));
+    const newTargets = new Map(after.targets.map(target => [targetKey(target), target]));
+    const keys = [...new Set([...after.targets, ...before.targets].map(targetKey))];
+    keys.sort((a, b) => Number(b === 'stage') - Number(a === 'stage'));
+
+    const targets: ProjectTargetChanges[] = [];
+    for (const key of keys) {
+        const a = oldTargets.get(key), b = newTargets.get(key);
+        const status = statusOf(a, b);
+        const elements: ProjectElementChange[] = [];
+        const count = scripts.get(key) ?? 0;
+        if (count) {
+            elements.push({key: JSON.stringify([key, 'code', '']), kind: 'code', status, scripts: count, files: useProject()});
+        }
+        for (const kind of ['costumes', 'sounds'] as const) {
+            const seen = new Map<string, number>();
+            for (const pair of pairEntries(entriesOf(a, kind), entriesOf(b, kind))) {
+                const md5ext = {before: pair.before && assetFileName(pair.before) || undefined, after: pair.after && assetFileName(pair.after) || undefined};
+                const differs = !equal(pair.before, pair.after);
+                const assets = filesAt([md5ext.before && joinPath(folder, assetsDirectory.before, md5ext.before),
+                    md5ext.after && joinPath(folder, assetsDirectory.after, md5ext.after)]);
+                if (!differs && !assets.length) continue;
+                const repeat = seen.get(pair.name) ?? 0;
+                seen.set(pair.name, repeat + 1);
+                elements.push({
+                    key: JSON.stringify(repeat ? [key, kind, pair.name, repeat] : [key, kind, pair.name]), kind, status: statusOf(pair.before, pair.after),
+                    name: pair.name, before: pair.before, after: pair.after, md5ext, files: [...(differs ? useProject() : []), ...assets]
+                });
+            }
+        }
+        if (a && b) {
+            const oldFields = a as unknown as Record<string, unknown>, newFields = b as unknown as Record<string, unknown>;
+            const data = changedKeys(oldFields, newFields, property => !(targetDataKeys as readonly string[]).includes(property));
+            if (data.length) elements.push({key: JSON.stringify([key, 'data', '']), kind: 'data', status, properties: data, files: useProject()});
+            const settings = changedKeys(oldFields, newFields, property => nonSettingKeys.has(property));
+            if (settings.length) {
+                elements.push({key: JSON.stringify([key, 'settings', '']), kind: 'settings', status, properties: settings, files: useProject()});
+            }
+        } else {
+            projectUsed = true;
+        }
+        if (status !== 'updated' || elements.length) {
+            const {name, isStage} = (b ?? a)!;
+            targets.push({key, name, isStage, status, before: a, after: b, elements});
+        }
+    }
+
+    const project = changedKeys(before, after, key => key === 'targets').map((property): ProjectElementChange => ({
+        key: JSON.stringify(['project', 'settings', property]), kind: 'settings', status: statusOf(before[property], after[property]),
+        properties: [property], files: useProject()
+    }));
+    if (projectUsed) explained.add(projectPath);
+    return {targets, project, other: files.filter(file => !explained.has(file.path))};
+}

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;
+}

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,25 @@ 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 {assetFileName, organizeProjectChanges, projectPropertyLabel} from './project-change-model.js';
+export type {ChangedFile, OrganizeProjectChangesInput, ProjectChangeList, ProjectChangeStatus, ProjectElementChange, ProjectElementKind,
+    ProjectTargetChanges} from './project-change-model.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 +44,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 +74,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 +86,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')};