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

package/src/messages.ts

@@ -7,9 +7,9 @@ export const messages = {
         open: 'Open This Project', reload: 'Reload Project', up: 'Parent folder', browse: 'Choose a project inside this repository',
         replace: 'Replace the open project and discard its unsaved changes?',
         dirty: 'The Editor has unsaved changes.', saved: 'The Editor has no unsaved changes.',
-        staged: 'Staged', unstaged: 'Unstaged', untracked: 'Untracked', commit: 'Commit changes',
-        history: 'History', worktree: 'Working tree', clean: 'No changes in the selected folder.',
-        branches: 'Local branches', unborn: 'No commits yet', detached: 'Detached HEAD', select: 'Select a file to view its diff.',
+        staged: 'Changes in the next record', unstaged: 'Saved, not yet recorded', untracked: 'New files never recorded', commit: 'Changes in this record',
+        history: 'Records (commits)', worktree: 'Saved files', clean: 'No saved changes in the selected folder.',
+        branches: 'Local branches', unborn: 'No records yet', detached: 'Detached HEAD', select: 'Select a file to view its diff.',
         binary: 'Binary asset', large: 'Text preview exceeds its display limit.', bytes: 'bytes',
         mode: 'Git file mode', permissions: 'Working-tree executable permission changes are unavailable in the browser.',
         unchanged: 'The text is unchanged.', loading: 'Reading repository…',
@@ -17,16 +17,20 @@ export const messages = {
         changed: 'Files or Git state changed while reading. Refresh to read the current state.',
         outdated: 'The repository changed outside the Editor. Refresh to read the current state.',
         unsupported: 'This repository contains an entry the browser cannot represent.',
-        pullUnsafe: 'Stop the project and clear unsaved or local Git changes before pulling.',
-        diverged: 'Pull requires a fast-forward. Your local branch and files are intact.',
+        pullUnsafe: 'Stop the project, and save or undo unsaved edits and unrecorded changes, before getting changes from GitHub (pull).',
+        diverged: 'This branch and GitHub\'s have both gained records, so they cannot be combined here (pull only fast-forwards). Your branch and files are unchanged.',
         session: 'Reconnect GitHub for this repository and requested permission.',
-        pushUnknown: 'The push result is unknown. Fetch and check the remote branch before retrying.',
-        pushRefresh: 'The push succeeded. Fetch to refresh the local tracking branch.',
-        rollbackFailed: 'Git could not restore all local changes. Check the working tree and Git status.',
-        remoteFailed: 'The Git operation failed. Check the selected connection and retry.',
-        remoteDone: 'Git operation completed.',
-        pulledProject: 'Pull completed. Use Reload Project to open the updated files.',
-        confirmPush: 'Push the current branch to its GitHub origin?',
+        pushUnknown: 'It is unknown whether GitHub received the records. Check GitHub (fetch) before sending again.',
+        pushRefresh: 'GitHub received the records. Check GitHub (fetch) to update the status.',
+        rollbackFailed: 'Some local changes could not be restored. Check the files and the Git details.',
+        remoteFailed: 'Could not complete the GitHub operation. Check the connection and try again.',
+        remoteDone: 'The GitHub operation finished.',
+        pulledProject: 'Got the changes from GitHub. Use Reload Project to open the updated files.',
+        confirmPush: 'Send the records on this branch to GitHub (push)?',
+        details: 'Git details', branch: 'Branch', head: 'HEAD', groups: 'Git groups', added: 'Added', modified: 'Changed', deleted: 'Deleted',
+        gitStaged: 'Staged', gitUnstaged: 'Unstaged', gitUntracked: 'Untracked',
+        upstreamSame: 'Same as GitHub', upstreamAhead: 'Ahead of GitHub', upstreamBehind: 'Behind GitHub', upstreamDiverged: 'Diverged from GitHub',
+        upstreamUnknown: 'Not checked with GitHub yet', records: 'records', checkedAt: 'as of the last check',
         failed: 'Could not read the repository. Check folder access and refresh.'
     },
     ja: {
@@ -35,11 +39,11 @@ export const messages = {
         empty: '既存の Git リポジトリを選び、ファイルの状態と履歴を確認できます。',
         repository: 'リポジトリ', project: '作品フォルダ', none: '作品は未選択', root: 'リポジトリルート',
         open: 'この作品を開く', reload: '作品を再読込', up: '上のフォルダ', browse: 'リポジトリ内の作品を選択',
-        replace: '未保存の変更を破棄して、別の作品を開きますか？',
-        dirty: 'Editor に未保存の変更があります。', saved: 'Editor に未保存の変更はありません。',
-        staged: 'ステージ済み', unstaged: '未ステージ', untracked: '未追跡', commit: 'コミットの変更',
-        history: '履歴', worktree: '作業ツリー', clean: '対象フォルダに変更はありません。',
-        branches: 'ローカルブランチ', unborn: 'コミットはまだありません', detached: 'ブランチ未選択の HEAD', select: 'ファイルを選ぶと差分を表示します。',
+        replace: '保存していない編集を破棄して、別の作品を開きますか？',
+        dirty: 'Editor に保存していない編集があります。', saved: 'Editor に保存していない編集はありません。',
+        staged: '次の記録に入る変更', unstaged: '保存したが、まだ記録していない変更', untracked: 'まだ記録したことのない新しいファイル', commit: 'この記録の変更',
+        history: '記録（コミット）の履歴', worktree: '保存したファイル', clean: '対象フォルダに、保存した変更はありません。',
+        branches: 'ローカルブランチ', unborn: 'まだ記録がありません', detached: 'ブランチ未選択の HEAD', select: 'ファイルを選ぶと差分を表示します。',
         binary: 'バイナリアセット', large: 'テキスト差分の表示上限を超えています。', bytes: 'バイト',
         mode: 'Git のファイルモード', permissions: '作業ツリーの実行権限の変更はブラウザーから確認できません。',
         unchanged: 'テキストに変更はありません。', loading: 'リポジトリを読込中…',
@@ -47,16 +51,20 @@ export const messages = {
         changed: '読込中にファイルまたは Git の状態が変わりました。再取得してください。',
         outdated: 'Editor の外でリポジトリが変更されました。再取得すると最新の状態を読み込みます。',
         unsupported: 'ブラウザーで扱えない種類の Git エントリーがあります。',
-        pullUnsafe: 'pull の前に実行を止め、未保存編集とローカルの Git 変更を解消してください。',
-        diverged: 'fast-forward できません。ローカルブランチとファイルは保持されています。',
+        pullUnsafe: 'GitHub から取り込む前に、実行を止め、保存していない編集とまだ記録していない変更をなくしてください。',
+        diverged: 'このブランチと GitHub の両方に新しい記録があるため、ここでは取り込めません（pull は fast-forward のみ）。ブランチとファイルはそのままです。',
         session: 'このリポジトリと操作に必要な権限で GitHub に接続してください。',
-        pushUnknown: 'push の結果が不明です。再試行する前に fetch でリモートブランチを確認してください。',
-        pushRefresh: 'push は成功しました。fetch でローカルの追跡ブランチを更新してください。',
-        rollbackFailed: 'Git がローカルの変更をすべて復元できませんでした。作業ツリーと Git の状態を確認してください。',
-        remoteFailed: 'Git 操作に失敗しました。選択中の接続を確認して再試行してください。',
-        remoteDone: 'Git 操作が完了しました。',
-        pulledProject: 'pull が完了しました。「作品を再読込」で更新済みのファイルを開けます。',
-        confirmPush: '現在のブランチを GitHub の origin に push しますか？',
+        pushUnknown: 'GitHub が記録を受け取ったか分かりません。送り直す前に「GitHub と確かめる」を使ってください。',
+        pushRefresh: 'GitHub が記録を受け取りました。「GitHub と確かめる」で状態を更新してください。',
+        rollbackFailed: '一部のローカルの変更を元に戻せませんでした。ファイルと Git の詳細を確認してください。',
+        remoteFailed: 'GitHub との操作を完了できませんでした。接続を確認して、もう一度試してください。',
+        remoteDone: 'GitHub との操作が終わりました。',
+        pulledProject: 'GitHub から取り込みました。「作品を再読込」で更新したファイルを開けます。',
+        confirmPush: 'このブランチの記録を GitHub に送りますか（push）？',
+        details: 'Git の詳細', branch: 'ブランチ', head: 'HEAD', groups: 'Git の区分', added: '追加', modified: '変更', deleted: '削除',
+        gitStaged: 'ステージ済み (staged)', gitUnstaged: '未ステージ (unstaged)', gitUntracked: '未追跡 (untracked)',
+        upstreamSame: 'GitHub と同じ', upstreamAhead: 'GitHub より進んでいる', upstreamBehind: 'GitHub より遅れている', upstreamDiverged: 'GitHub と分かれている',
+        upstreamUnknown: 'まだ GitHub と確かめていない', records: '件', checkedAt: '最後に確かめた時点',
         failed: 'リポジトリを読み込めませんでした。フォルダへのアクセスを確認し、再取得してください。'
     }
 };

package/src/project-assets.ts

@@ -43,18 +43,24 @@ function readAsset(loadAsset: ProjectAssetLoader, version: ProjectVersion, md5ex
     return read;
 }
 
-/** Loads the current costume of one version of a target as an object URL for an image, or `null` while it is unavailable. */
-export function useCostumeImage(target: ProjectTarget | undefined, version: ProjectVersion, loadAsset?: ProjectAssetLoader): string | null {
-    const costume = target && loadAsset ? currentCostume(target) : null;
-    const key = costume ? version + ':' + costume.md5ext : '';
+/** 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 (!costume || !loadAsset) return;
+        if (!key || !loadAsset) return;
         let active = true;
         let url: string | undefined;
-        void readAsset(loadAsset, version, costume.md5ext).then(blob => {
+        void readAsset(loadAsset, version, md5ext!).then(blob => {
             if (!blob || !active) return;
-            url = URL.createObjectURL(new Blob([blob], {type: costume.type}));
+            url = URL.createObjectURL(new Blob([blob], {type}));
             setImage({key, url});
         });
         return () => {
@@ -64,3 +70,9 @@ export function useCostumeImage(target: ProjectTarget | undefined, version: Proj
     }, [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: 'in the next record', unstaged: 'not yet recorded', untracked: 'new file', commit: 'in this record'} 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.tsx

@@ -16,6 +16,9 @@ export type {ProjectBlockLocation, ProjectBlockLocator, ScratchBlockLocationWork
 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 {BlockPreviewView, BlockPreviewViewport, ProjectBlockRenderer, ProjectBlockRendering, ScratchBlockDiffRendererOptions,

package/src/project-source-review.tsx

@@ -168,27 +168,34 @@ export interface ProjectSourceComparisonProps {
     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 code, as the pull request review does. */
-export function ProjectSourceComparison({before, after, renderBlock, locale = 'en', fallback, loadAsset}: ProjectSourceComparisonProps) {
+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>
+        </header>}
         <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}/>
     </section>;
 }