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

package/src/file-diff-view.tsx

@@ -5,6 +5,7 @@ import type {FileChange, FileDiff} from './repository.js';
 import type {labelsFor} from './messages.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
 import type {ProjectAssetLoader} from './project-assets.js';
+import type {ProjectBlockLocator} from './block-diff-location.js';
 
 const en = {view: 'Show changes as', blocks: 'Blocks', text: 'Text'};
 const ja: typeof en = {view: '変更の表示', blocks: 'ブロック', text: 'テキスト'};
@@ -15,16 +16,18 @@ export const isProjectSource = (path: string) => path.split('/').pop() === 'proj
 /**
  * Shows one changed file. Project sources are compared as blocks by default, with their text diff one switch away.
  */
-export function FileDiffView({change, diff, labels, locale, renderBlock, loadAsset}: {
+export function FileDiffView({change, diff, labels, locale, renderBlock, loadAsset, locateBlock}: {
     change: FileChange; diff: FileDiff | null; labels: ReturnType<typeof labelsFor>; locale: string;
-    renderBlock?: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
+    renderBlock?: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader; locateBlock?: ProjectBlockLocator;
 }) {
     const [view, setView] = useState<'blocks' | 'text'>('blocks');
     const names = locale.startsWith('ja') ? ja : en;
     const parsed = diff?.patch ? parseDiff(diff.patch)[0] : null;
     const text = <>
-        <p>{labels.mode} · {change.oldMode?.toString(8) || '—'} → {change.newMode?.toString(8) || '—'}</p>
-        {diff && <p>{diff.beforeSize} → {diff.afterSize} {labels.bytes}</p>}
+        <details className="twgit-file-details"><summary>{labels.details}</summary>
+            <p>{labels.mode} · {change.oldMode?.toString(8) || '—'} → {change.newMode?.toString(8) || '—'}</p>
+            {diff && <p>{diff.beforeSize} → {diff.afterSize} {labels.bytes}</p>}
+        </details>
         {diff?.binary && <p>{labels.binary}</p>}
         {diff?.tooLarge && <p>{labels.large}</p>}
         {parsed && <Diff viewType="unified" diffType={parsed.type} hunks={parsed.hunks}>
@@ -38,7 +41,7 @@ export function FileDiffView({change, diff, labels, locale, renderBlock, loadAss
             {(['blocks', 'text'] as const).map(mode => <button key={mode} type="button" aria-pressed={view === mode}
                 data-git-view={mode} onClick={() => setView(mode)}>{names[mode]}</button>)}
         </div>}
-        {sources && view === 'blocks' ? <ProjectSourceComparison renderBlock={renderBlock!} locale={locale} fallback={text} loadAsset={loadAsset}
+        {sources && view === 'blocks' ? <ProjectSourceComparison renderBlock={renderBlock!} locale={locale} fallback={text} loadAsset={loadAsset} locateBlock={locateBlock}
             before={change.before === null ? null : sources.before} after={change.after === null ? null : sources.after}/> : text}
     </>;
 }

package/src/index.tsx

@@ -1,5 +1,5 @@
 import React, {useEffect, useMemo, useRef, useState} from 'react';
-import {render, unmountComponentAtNode} from 'react-dom';
+import {createPortal, render, unmountComponentAtNode} from 'react-dom';
 import {FileDiffView} from './file-diff-view.js';
 import {findElement, ProjectChangeListView, ProjectElementView, projectChangeLabels, useProjectChanges} from './project-change-list.js';
 import type {ChangedFile} from './project-change-model.js';
@@ -12,6 +12,11 @@ import type {GitConnectionSettings} from './connection-settings.js';
 import type {RemoteOperation} from './remote-operations.js';
 import {PullRequestReviewPanel} from './pull-request-panel.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+import type {ScratchBlockLocationWorkspace} from './block-diff-location.js';
+export {createScratchBlocksDiffLocator} from './block-diff-location.js';
+export {createEditorBlockLocator} from './editor-block-locator.js';
+import {createEditorBlockLocator} from './editor-block-locator.js';
+import type {LocatorVM} from './editor-block-locator.js';
 
 export {createScratchBlocksDiffRenderer} from './scratch-block-diff-renderer.js';
 export type {ScratchBlockDiffRendererOptions, ScratchBlocksPort} from './scratch-block-diff-renderer.js';
@@ -26,6 +31,22 @@ export interface GitHost {
     isProjectDirty(): boolean;
     isProjectRunning?(): boolean;
     subscribe?(listener: (event: 'loaded' | 'changed') => void): () => void;
+    /**
+     * Opens the panel as a tab of the host's layout, with the same shape as the layout package's DocumentPanelRequest.
+     * Returning `false` keeps the modal dialog.
+     */
+    openPanel?(request: GitPanelRequest): boolean;
+    /** Opens the code of one stage or sprite, so a diff can point at its block. Without it, no block is located. */
+    openTargetCode?(targetId: string): void | Promise<void>;
+    /** The Editor's code workspace as it is now. */
+    getWorkspace?(): ScratchBlockLocationWorkspace | null | Promise<ScratchBlockLocationWorkspace | null>;
+}
+export interface GitPanelRequest {
+    reference: {providerId: string; documentId: string};
+    filename: string;
+    title?: string;
+    transient?: boolean;
+    mount(element: HTMLElement, close: () => void): {requestClose(): void; dispose(): void};
 }
 interface Controller {open(locale: string): void; refresh(automatic?: boolean): Promise<void>}
 interface State {
@@ -51,8 +72,14 @@ type ObserverWindow = Window & {FileSystemObserver?: new (callback: () => void)
 }};
 const watchInterval = 2000;
 
-function GitPanel({document, host, controller}: {document: Document; host: GitHost; controller: Controller}) {
+function GitPanel({vm, document, host, controller}: {vm: object; document: Document; host: GitHost; controller: Controller}) {
     const [visible, setVisible] = useState(false);
+    // A layout tab that holds the panel. The panel component stays mounted, so the repository survives closing the tab.
+    const [slot, setSlot] = useState<{element: HTMLElement; close(): void} | null>(null);
+    const shown = visible || slot !== null;
+    // Only a tab leaves the Editor visible, so only a tab offers to point at blocks in it.
+    const locator = useMemo(() => slot && host.openTargetCode && host.getWorkspace ? createEditorBlockLocator({
+        vm: vm as LocatorVM, openTargetCode: host.openTargetCode, getWorkspace: host.getWorkspace}) : undefined, [slot !== null, host, vm]);
     const [review, setReview] = useState(false);
     const [locale, setLocale] = useState(document.documentElement.lang || 'en');
     const [dirty, setDirty] = useState(host.isProjectDirty());
@@ -99,7 +126,21 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
             }
         }
     };
-    controller.open = language => {setLocale(language); setVisible(true);};
+    controller.open = language => {
+        setLocale(language);
+        const opened = host.openPanel?.({reference: {providerId: 'turbowarp-plus-git', documentId: 'local-git'},
+            filename: 'Git', title: labelsFor(language).title, transient: true,
+            mount(element, close) {
+                setVisible(false);
+                setSlot({element, close});
+                return {requestClose: close, dispose() {setSlot(previous => previous?.element === element ? null : previous);}};
+            }});
+        if (!opened) setVisible(true);
+    };
+    const closePanel = () => {
+        if (slot) slot.close();
+        else setVisible(false);
+    };
     controller.refresh = async (automatic = false) => {
         if (!alive.current || !current.current.repository) return;
         if (running.current) {
@@ -128,7 +169,7 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
     // While the panel is open, notice Git commands, agents and editors that change the repository outside the Editor.
     useEffect(() => {
         const repository = state.repository;
-        if (!visible || !repository) return;
+        if (!shown || !repository) return;
         const view = document.defaultView as ObserverWindow;
         let stopped = false;
         let checking = false;
@@ -177,13 +218,13 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
             document.removeEventListener('visibilitychange', onFocus);
             observer?.disconnect();
         };
-    }, [visible, state.repository, locale]);
+    }, [shown, state.repository, locale]);
     useEffect(() => {
-        if (!visible) return;
+        if (!visible || slot) return;
         const previous = document.activeElement as HTMLElement | null;
         dialog.current?.focus();
         return () => {if (previous?.isConnected) previous.focus();};
-    }, [visible]);
+    }, [visible, slot]);
     const chooseRoot = async () => {
         const view = document.defaultView as PickerWindow;
         await run(async () => {
@@ -208,6 +249,8 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
             const result = await host.openProject(directory, () => document.defaultView!.confirm(labels.replace));
             if (result === 'cancelled') return {};
         } finally {opening.current = false;}
+        // Loading the project brings its code to the front; keep the panel the person is working in in front of it.
+        if (slot) controller.open(locale);
         if (!alive.current) return {};
         setDirty(host.isProjectDirty());
         setState(previous => ({...previous, project: path, snapshot: null, changes: [], selected: null, diff: null, commit: null}));
@@ -256,7 +299,7 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
         });
     };
     const focusTrap = (event: React.KeyboardEvent<HTMLDivElement>) => {
-        if (event.key === 'Escape') {event.stopPropagation(); setVisible(false); return;}
+        if (event.key === 'Escape') {event.stopPropagation(); closePanel(); return;}
         if (event.key !== 'Tab') return;
         const items = [...event.currentTarget.querySelectorAll<HTMLElement>('button:not(:disabled), input:not(:disabled), select:not(:disabled), a[href], summary, [tabindex="0"]')]
             .filter(item => item.getClientRects().length > 0);
@@ -268,13 +311,19 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
     // One loader per selected change, so thumbnails read each asset once.
     const loadAsset = useMemo(() => state.repository && state.snapshot && state.selected ?
         state.repository.assetLoader(state.snapshot, state.selected) : undefined, [state.repository, state.snapshot, state.selected]);
-    if (!visible) return null;
+    if (!shown) return null;
     const groups: ChangeGroup[] = state.commit ? ['commit'] : ['staged', 'unstaged', 'untracked'];
     const projectList = typeof projectChanges === 'object' ? projectChanges : null;
+    // The open project matches the working tree, so only the working-tree side of its project file can be located.
+    const projectFile = state.project === null ? null : [state.project, 'project.source.json'].filter(Boolean).join('/');
+    const fileLocator = (change: FileChange) => locator && change.path === projectFile &&
+        (change.group === 'unstaged' || change.group === 'untracked' ||
+            (change.group === 'staged' && !state.changes.some(item => item.path === change.path && item.group === 'unstaged'))) ?
+        locator : undefined;
+    const reviewLocator = (path: string, headSha: string) => locator && path === projectFile && state.snapshot?.head === headSha &&
+        !state.changes.length ? locator : undefined;
     const selection = projectList && !state.selected ? findElement(projectList.list, element) : null;
-    return <div className="twgit-backdrop">
-        <div className="twgit-panel" ref={dialog} tabIndex={-1} role="dialog" aria-modal="true" aria-label={labels.title}
-            onKeyDown={focusTrap}>
+    const content = <>
             <header>
                 <h2>{labels.title}</h2>
                 <button onClick={chooseRoot} disabled={state.busy}>{labels.choose}</button>
@@ -282,28 +331,38 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
                 {!review && state.project !== null && <button disabled={state.busy} onClick={() => void openProject(state.project!)}>{labels.reload}</button>}
                 {state.repository && host.renderReviewBlock && <button type="button" disabled={state.busy}
                     onClick={() => setReview(!review)}>{review ? labels.localChanges : labels.pullRequests}</button>}
-                <button onClick={() => setVisible(false)}>{labels.close}</button>
+                <button onClick={closePanel}>{labels.close}</button>
             </header>
             <div className="twgit-context">
                 <span>{labels.repository} · {state.repository?.root.name || '—'}</span>
                 <span>{labels.project} · {state.project === null ? labels.none : state.project || labels.root}</span>
-                <strong>{state.snapshot?.branch || (state.snapshot?.head ? labels.detached : labels.unborn)}</strong>
-                <code>{state.snapshot?.head?.slice(0, 12)}</code>
                 <span data-git-dirty="">{dirty ? labels.dirty : labels.saved}</span>
+                {state.snapshot && <span data-git-upstream={state.snapshot.upstream.state} title={labels.checkedAt}>{upstreamText(state.snapshot, labels)}</span>}
+                {!review && host.connectionSettings && <ConnectionSettings settings={host.connectionSettings} locale={locale}
+                    runOperation={host.connectionSettings.getSession ? remoteOperation : undefined}
+                    readOrigin={state.repository && !state.busy ? async () => {
+                        const ticket = epoch.current;
+                        const remote = await state.repository!.readOrigin();
+                        return epoch.current === ticket ? remote : undefined;
+                    } : undefined}/>}
+                {state.snapshot && <details className="twgit-git-details">
+                    <summary>{labels.details}</summary>
+                    <div className="twgit-connection-body">
+                        <p>{labels.branch} · <strong>{state.snapshot.branch || (state.snapshot.head ? labels.detached : labels.unborn)}</strong></p>
+                        <p>{labels.head} · <code>{state.snapshot.head?.slice(0, 12) ?? '—'}</code></p>
+                        <p>{labels.branches} · {state.snapshot.branches.join(', ') || '—'}</p>
+                        <p>{labels.groups} · {labels.gitStaged} = {labels.staged} / {labels.gitUnstaged} = {labels.unstaged} / {labels.gitUntracked} = {labels.untracked}</p>
+                        <p>{labels.permissions}</p>
+                    </div>
+                </details>}
             </div>
-            {!review && host.connectionSettings && <ConnectionSettings settings={host.connectionSettings} locale={locale}
-                runOperation={host.connectionSettings.getSession ? remoteOperation : undefined}
-                readOrigin={state.repository && !state.busy ? async () => {
-                    const ticket = epoch.current;
-                    const remote = await state.repository!.readOrigin();
-                    return epoch.current === ticket ? remote : undefined;
-                } : undefined}/>}
             {state.error && <p className="twgit-error" role="alert">{state.error}</p>}
             {state.notice && <p className="twgit-context" role="status">{state.notice}</p>}
             {state.busy && <p role="status">{labels.loading}</p>}
             {!state.repository && <p>{labels.empty}</p>}
             {review && state.repository && host.renderReviewBlock &&
-                <PullRequestReviewPanel repository={state.repository} locale={locale} renderBlock={host.renderReviewBlock}/>}
+                <PullRequestReviewPanel repository={state.repository} locale={locale} renderBlock={host.renderReviewBlock}
+                    locateFor={reviewLocator}/>}
             {!review && state.repository && <div className="twgit-content">
                 <aside>
                     {state.browser && <details>
@@ -323,7 +382,7 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
                             <ul>{state.changes.filter(change => change.group === group).map(change => <li key={change.path}>
                                 <button className="twgit-file" data-git-group={group} disabled={state.busy}
                                     aria-pressed={state.selected === change} onClick={() => openFile(change)}>
-                                    <span>{!change.after ? 'D' : !change.before ? 'A' : 'M'}</span> {change.path}
+                                    <small className="twgit-change-kind">{!change.after ? labels.deleted : !change.before ? labels.added : labels.modified}</small> {change.path}
                                 </button>
                             </li>)}</ul>
                         </section>);
@@ -332,33 +391,50 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
                             fileListOpen={fileListOpen} setFileListOpen={setFileListOpen}/> : fileList;
                     })()}
                     {!state.changes.length && <p>{labels.clean}</p>}
-                    <details><summary>{labels.branches}</summary><ul>{state.snapshot?.branches.map(branch => <li key={branch}>{branch}</li>)}</ul></details>
                     <h3>{labels.history}</h3>
                     <ol className="twgit-history">{state.snapshot?.commits.map(commit => <li key={commit.oid}>
                         <button disabled={state.busy} aria-pressed={state.commit === commit.oid} title={commit.oid}
                             onClick={() => void selectCommit(commit.oid)}>{commit.message.split('\n')[0]}</button>
-                        <small><code>{commit.oid.slice(0, 8)}</code> · {commit.author} · {new Date(commit.timestamp * 1000).toLocaleString(locale)}</small>
+                        <small>{commit.author} · {new Date(commit.timestamp * 1000).toLocaleString(locale)}</small>
                     </li>)}</ol>
                 </aside>
                 <main className="twgit-diff">
                     {selection && projectList ? <ProjectElementView changes={projectList} selection={selection} locale={locale}
+                        locateBlock={state.commit ? undefined : locator}
                         renderBlock={host.renderReviewBlock} onSelectFile={openFile}/> :
                         state.selected ? <FileDiffView change={state.selected} diff={state.diff} labels={labels} locale={locale}
+                            locateBlock={fileLocator(state.selected)}
                             renderBlock={host.renderReviewBlock} loadAsset={loadAsset}/> : <p>{labels.select}</p>}
                 </main>
             </div>}
-            <footer>{labels.permissions}</footer>
-        </div>
+    </>;
+    // In a tab the Editor stays usable beside the panel, so there is no backdrop, focus trap or Escape to close.
+    if (slot) return createPortal(<div className="twgit-panel twgit-panel-tab" role="region" aria-label={labels.title}>{content}</div>,
+        slot.element);
+    return <div className="twgit-backdrop">
+        <div className="twgit-panel" ref={dialog} tabIndex={-1} role="dialog" aria-modal="true" aria-label={labels.title}
+            onKeyDown={focusTrap}>{content}</div>
     </div>;
 }
 
+/** The GitHub relation in plain words, with the number of records where it helps. */
+function upstreamText({upstream}: Snapshot, labels: ReturnType<typeof labelsFor>) {
+    switch (upstream.state) {
+    case 'same': return labels.upstreamSame;
+    case 'ahead': return `${labels.upstreamAhead} · ${upstream.ahead} ${labels.records}`;
+    case 'behind': return `${labels.upstreamBehind} · ${upstream.behind} ${labels.records}`;
+    case 'diverged': return `${labels.upstreamDiverged} · +${upstream.ahead} / −${upstream.behind}`;
+    default: return labels.upstreamUnknown;
+    }
+}
+
 export function mountGitPanel({vm, document, host}: {vm: object; document: Document; host: GitHost}) {
     if (!(document.defaultView as PickerWindow)?.showDirectoryPicker) return null;
     const root = document.createElement('div');
     document.body.append(root);
     const controller: Controller = {open() {}, async refresh() {}};
     controllers.set(vm, controller);
-    render(<GitPanel document={document} host={host} controller={controller}/>, root);
+    render(<GitPanel vm={vm} document={document} host={host} controller={controller}/>, root);
     return {refresh: () => controller.refresh(), dispose() {
         if (controllers.get(vm) === controller) controllers.delete(vm);
         void host.connectionSettings?.disconnect().catch(() => {});

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-change-list.tsx

@@ -7,6 +7,7 @@ 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';
+import type {ProjectBlockLocator} from './block-diff-location.js';
 
 const en = {
     title: 'Changes by project element', stage: 'Stage', code: (count: number) => `Code · ${count} ${count === 1 ? 'change' : 'changes'}`,
@@ -15,7 +16,7 @@ const en = {
     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>
+    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} か所`,
@@ -24,7 +25,7 @@ const ja: typeof en = {
     files: 'ファイルと Git の区分', before: '変更前', after: '変更後', absent: 'この版にはありません',
     loading: '作品の変更を読み込み中…', unreadable: '作品データを読み込めないため、ファイル単位で一覧にします。',
     fileList: 'ファイル単位の一覧', property: '項目', format: '形式', rate: 'サンプリング周波数', samples: 'サンプル数', file: 'ファイル名',
-    noImage: '画像なし', groups: {staged: 'ステージ済み', unstaged: '未ステージ', untracked: '未追跡', commit: 'コミット'}
+    noImage: '画像なし', groups: {staged: '次の記録に入る', unstaged: 'まだ記録していない', untracked: '新しいファイル', commit: 'この記録'}
 };
 type Labels = typeof en;
 export const projectChangeLabels = (locale: string): Labels => locale.startsWith('ja') ? ja : en;
@@ -164,9 +165,9 @@ const show = (value: unknown) => {
 };
 
 /** 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}: {
+export function ProjectElementView({changes, selection, locale, renderBlock, onSelectFile, locateBlock}: {
     changes: ProjectChanges; selection: {element: ProjectElementChange; target: ProjectTargetChanges | null}; locale: string;
-    renderBlock?: ProjectBlockRenderer; onSelectFile(file: ChangedFile): void;
+    renderBlock?: ProjectBlockRenderer; onSelectFile(file: ChangedFile): void; locateBlock?: ProjectBlockLocator;
 }) {
     const labels = projectChangeLabels(locale);
     const {element, target} = selection;
@@ -189,7 +190,7 @@ export function ProjectElementView({changes, selection, locale, renderBlock, onS
         <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}}/>}
+            target={{isStage: target.isStage, name: target.name}} locateBlock={locateBlock}/>}
         {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)}`}/>)}

package/src/project-source-review.tsx

@@ -1,10 +1,12 @@
-import React, {useMemo, useState} from 'react';
+import React, {useEffect, useMemo, useRef, useState} from 'react';
 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, TargetReview} from './project-source-review-model.js';
 import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+import type {ProjectBlockLocator} from './block-diff-location.js';
+import type {LocationStatus} from './block-diff-preview.js';
 import {currentCostume, useCostumeImage} from './project-assets.js';
 import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
@@ -15,7 +17,9 @@ export type ProjectSourceReviewFile = {
     summary?: string;
     previousPath?: string;
     unavailable?: boolean;
-} & ({patch: string; beforeSource?: string; loadAsset?: ProjectAssetLoader} | {status: 'added' | 'removed' | 'updated'});
+} & ({patch: string; beforeSource?: string; loadAsset?: ProjectAssetLoader;
+    /** Offers "Highlight in Editor" on this file's after version, which the caller has matched with the open project. */
+    locateBlock?: ProjectBlockLocator} | {status: 'added' | 'removed' | 'updated'});
 
 export interface ProjectSourceReviewProps {
     title: string;
@@ -37,7 +41,9 @@ const ja = {
     related: '関連ファイル', properties: 'コード以外の変更', invalid: 'この作品の差分を読み込めません。',
     flag: '緑の旗が押されたとき', broadcast: 'を受け取ったとき', key: 'キーが押されたとき',
     click: 'このスプライトが押されたとき', script: 'コード', noChanges: '作品に内容の変更はありません。',
-    comparison: '作品の変更', unreadable: '作品データとして読み込めないため、テキストの差分を表示します。'
+    comparison: '作品の変更', unreadable: '作品データとして読み込めないため、テキストの差分を表示します。',
+    locate: '編集画面で強調', locating: '編集画面でブロックを検索中…', located: '編集画面で強調しました。',
+    missingLocation: '編集画面に該当する版またはブロックがありません。'
 };
 const en: typeof ja = {
     review: 'Change review', fullDescription: 'Show full PR description', checks: 'Review checklist', files: 'Changed files', targets: 'Affected stages and sprites',
@@ -49,7 +55,9 @@ const en: typeof ja = {
     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: '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.'
+    comparison: 'Project changes', unreadable: 'This file could not be read as project data, so its text diff is shown.',
+    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.'
 };
 
 const properties = new Map<string, readonly [string, string]>([
@@ -74,9 +82,39 @@ function scriptTitle(side: BlockSide, labels: typeof ja) {
     return typeof block.opcode === 'string' ? block.opcode : labels.script;
 }
 
-function ScriptComparison({script, labels, reviewed = false, setReviewed, renderBlock, loadAsset}: {
+type BlockLocation = {locate?(side: BlockSide): void; status(side: BlockSide): LocationStatus | undefined};
+const sideKey = (side: BlockSide) => JSON.stringify([side.target.isStage, side.target.name, side.id]);
+
+/** Highlights the after version of a script in the Editor, one request per comparison, and cancels it on unmount. */
+function useBlockLocation(comparison: Comparison, locateBlock?: ProjectBlockLocator): BlockLocation {
+    const request = useRef<AbortController>();
+    const [location, setLocation] = useState<{comparison: Comparison; key: string; locator: ProjectBlockLocator; status: LocationStatus}>();
+    useEffect(() => () => request.current?.abort(), [comparison, locateBlock]);
+    const locate = async (side: BlockSide) => {
+        if (!locateBlock) return;
+        request.current?.abort();
+        const controller = new AbortController();
+        request.current = controller;
+        const selected = {comparison, key: sideKey(side), locator: locateBlock};
+        setLocation({...selected, status: 'locating'});
+        let found = false;
+        try {
+            found = await locateBlock({target: side.target, id: side.id, version: 'after', parts: [], signal: controller.signal});
+        } catch {
+            // The host may replace the active project while resolving its workspace.
+        }
+        if (!controller.signal.aborted) setLocation({...selected, status: found ? 'located' : 'missingLocation'});
+    };
+    return {
+        locate: locateBlock && (side => void locate(side)),
+        status: side => location?.comparison === comparison && location.locator === locateBlock && location.key === sideKey(side) ?
+            location.status : undefined
+    };
+}
+
+function ScriptComparison({script, labels, reviewed = false, setReviewed, renderBlock, loadAsset, location}: {
     script: ScriptReview; labels: typeof ja; reviewed?: boolean; setReviewed?(value: boolean): void;
-    renderBlock: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
+    renderBlock: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader; location?: BlockLocation;
 }) {
     const [open, setOpen] = useState(false);
     const {sync, toggle} = usePreviewSync(labels === ja ? 'ja' : 'en');
@@ -98,7 +136,9 @@ function ScriptComparison({script, labels, reviewed = false, setReviewed, render
                     {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}
-                        version={version} loadAsset={loadAsset} sync={sync}/>) :
+                        version={version} loadAsset={loadAsset} sync={sync}
+                        onLocate={version === 'after' && location?.locate ? () => location.locate!(side) : undefined}
+                        locationStatus={version === 'after' ? location?.status(side) : undefined}/>) :
                         <BlockPreview title={labels[version]} renderBlock={renderBlock} withContext labels={labels}/>}
                 </div>)}
             </div>
@@ -135,10 +175,12 @@ function TargetThumbnails({target, labels, loadAsset}: {target: TargetReview; la
 }
 
 /** Lists the changed stages and sprites of one project file, each with its code comparisons. */
-function ComparisonTargets({comparison, labels, renderBlock, loadAsset, review}: {
+function ComparisonTargets({comparison, labels, renderBlock, loadAsset, locateBlock, review}: {
     comparison: Comparison; labels: typeof ja; renderBlock: ProjectBlockRenderer; loadAsset?: ProjectAssetLoader;
+    locateBlock?: ProjectBlockLocator;
     review?: {file: string; keys: ReadonlySet<string>; set(key: string, value: boolean): void};
 }) {
+    const location = useBlockLocation(comparison, locateBlock);
     return <>
         {comparison.properties.length > 0 && <p>{labels.properties} · {propertyNames(comparison.properties, labels)}</p>}
         {!comparison.targets.length && !comparison.properties.length && <p>{labels.noChanges}</p>}
@@ -149,7 +191,7 @@ function ComparisonTargets({comparison, labels, renderBlock, loadAsset, review}:
             {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} loadAsset={loadAsset}
-                    reviewed={review?.keys.has(key)} setReviewed={review && (value => review.set(key, value))}/>;
+                    location={location} reviewed={review?.keys.has(key)} setReviewed={review && (value => review.set(key, value))}/>;
             })}
         </section>)}
     </>;
@@ -168,12 +210,14 @@ 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;
+    /** Offers "Highlight in Editor" on the after version, which the caller has matched with the open project. */
+    locateBlock?: ProjectBlockLocator;
     /** 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, target}: ProjectSourceComparisonProps) {
+export function ProjectSourceComparison({before, after, renderBlock, locale = 'en', fallback, loadAsset, locateBlock, target}: ProjectSourceComparisonProps) {
     const labels = locale.startsWith('ja') ? ja : en;
     const only = target && JSON.stringify([target.isStage, target.isStage || target.name]);
     const comparison = useMemo(() => {
@@ -196,7 +240,8 @@ 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} loadAsset={loadAsset}/>
+        <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}
+            locateBlock={locateBlock}/>
     </section>;
 }
 
@@ -251,6 +296,7 @@ export function ProjectSourceReview({title, description, verification, files, re
             {(invalid || file.unavailable) && <p role="alert">{labels.invalid}</p>}
             {comparison && <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock}
                 loadAsset={'loadAsset' in file ? file.loadAsset : undefined}
+                locateBlock={'locateBlock' in file ? file.locateBlock : undefined}
                 review={{file: file.path, keys: reviewed, set: setReviewed}}/>}
         </section>)}
     </section>;