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

package/dist/style.css

@@ -106,6 +106,20 @@
     border: 1px solid var(--twgit-review-line, color-mix(in srgb, CanvasText 18%, Canvas));
     border-radius: 4px;
 }
+
+/* The legend matches the outlines drawn on the previews. */
+.twgit-review-legend { display: flex; flex-wrap: wrap; gap: 4px 14px; margin: 8px 0; font-size: .9em; }
+.twgit-review-legend span::before { content: ''; display: inline-block; width: 12px; height: 10px; margin-inline-end: 5px;
+    vertical-align: -1px; border: 2.5px solid var(--twgit-change); border-radius: 3px; }
+.twgit-review-legend [data-legend="added"] { --twgit-change: #25875d; }
+.twgit-review-legend [data-legend="removed"] { --twgit-change: #c54a53; }
+.twgit-review-legend [data-legend="updated"] { --twgit-change: #635bce; }
+.twgit-review-legend [data-legend="part"] { --twgit-change: #b4510a; }
+.twgit-review-legend [data-legend="part"]::before { border-radius: 0; }
+.twgit-review-summary { color: color-mix(in srgb, CanvasText 72%, Canvas); }
+.twgit-review-target-status { font-weight: 600; }
+.twgit-review-asset { display: flex; align-items: center; gap: 8px; }
+.twgit-review-asset img { width: 32px; height: 32px; object-fit: contain; }
 :root{--diff-background-color:initial;--diff-text-color:initial;--diff-font-family:Consolas,Courier,monospace;--diff-selection-background-color:#b3d7ff;--diff-selection-text-color:var(--diff-text-color);--diff-gutter-insert-background-color:#d6fedb;--diff-gutter-insert-text-color:var(--diff-text-color);--diff-gutter-delete-background-color:#fadde0;--diff-gutter-delete-text-color:var(--diff-text-color);--diff-gutter-selected-background-color:#fffce0;--diff-gutter-selected-text-color:var(--diff-text-color);--diff-code-insert-background-color:#eaffee;--diff-code-insert-text-color:var(--diff-text-color);--diff-code-delete-background-color:#fdeff0;--diff-code-delete-text-color:var(--diff-text-color);--diff-code-insert-edit-background-color:#c0dc91;--diff-code-insert-edit-text-color:var(--diff-text-color);--diff-code-delete-edit-background-color:#f39ea2;--diff-code-delete-edit-text-color:var(--diff-text-color);--diff-code-selected-background-color:#fffce0;--diff-code-selected-text-color:var(--diff-text-color);--diff-omit-gutter-line-color:#cb2a1d;}.diff{background-color:var(--diff-background-color);border-collapse:collapse;color:var(--diff-text-color);table-layout:fixed;width:100%;}.diff::-moz-selection{background-color:#b3d7ff;background-color:var(--diff-selection-background-color);color:var(--diff-text-color);color:var(--diff-selection-text-color);}.diff::selection{background-color:#b3d7ff;background-color:var(--diff-selection-background-color);color:var(--diff-text-color);color:var(--diff-selection-text-color);}.diff td{padding-bottom:0;padding-top:0;vertical-align:top;}.diff-line{font-family:Consolas,Courier,monospace;font-family:var(--diff-font-family);line-height:1.5;}.diff-gutter>a{color:inherit;display:block;}.diff-gutter{cursor:pointer;padding:0 1ch;text-align:right;-webkit-user-select:none;-moz-user-select:none;user-select:none;}.diff-gutter-insert{background-color:#d6fedb;background-color:var(--diff-gutter-insert-background-color);color:var(--diff-text-color);color:var(--diff-gutter-insert-text-color);}.diff-gutter-delete{background-color:#fadde0;background-color:var(--diff-gutter-delete-background-color);color:var(--diff-text-color);color:var(--diff-gutter-delete-text-color);}.diff-gutter-omit{cursor:default;}.diff-gutter-selected{background-color:#fffce0;background-color:var(--diff-gutter-selected-background-color);color:var(--diff-text-color);color:var(--diff-gutter-selected-text-color);}.diff-code{word-wrap:break-word;padding:0 0 0 .5em;white-space:pre-wrap;word-break:break-all;}.diff-code-edit{color:inherit;}.diff-code-insert{background-color:#eaffee;background-color:var(--diff-code-insert-background-color);color:var(--diff-text-color);color:var(--diff-code-insert-text-color);}.diff-code-insert .diff-code-edit{background-color:#c0dc91;background-color:var(--diff-code-insert-edit-background-color);color:var(--diff-text-color);color:var(--diff-code-insert-edit-text-color);}.diff-code-delete{background-color:#fdeff0;background-color:var(--diff-code-delete-background-color);color:var(--diff-text-color);color:var(--diff-code-delete-text-color);}.diff-code-delete .diff-code-edit{background-color:#f39ea2;background-color:var(--diff-code-delete-edit-background-color);color:var(--diff-text-color);color:var(--diff-code-delete-edit-text-color);}.diff-code-selected{background-color:#fffce0;background-color:var(--diff-code-selected-background-color);color:var(--diff-text-color);color:var(--diff-code-selected-text-color);}.diff-widget-content{vertical-align:top;}.diff-gutter-col{width:7ch;}.diff-gutter-omit{height:0;}.diff-gutter-omit:before{background-color:#cb2a1d;background-color:var(--diff-omit-gutter-line-color);content:" ";display:block;height:100%;margin-left:4.6ch;overflow:hidden;white-space:pre;width:2px;}.diff-decoration{line-height:1.5;-webkit-user-select:none;-moz-user-select:none;user-select:none;}.diff-decoration-content{font-family:Consolas,Courier,monospace;font-family:var(--diff-font-family);padding:0;}.twgit-backdrop { position: fixed; inset: 0; z-index: 65000; background: #0006; display: flex; align-items: center; justify-content: center; }
 .twgit-panel { width: 94vw; height: 90vh; display: flex; flex-direction: column; background: Canvas; color: CanvasText; border: 1px solid GrayText; border-radius: 8px; box-shadow: 0 12px 48px #0005; font: 14px/1.5 system-ui, sans-serif; overflow: hidden; }
 .twgit-panel > header { display: flex; gap: 8px; align-items: center; padding: 10px 16px; border-bottom: 1px solid GrayText; }
@@ -163,4 +177,6 @@
 .twgit-element-files { margin-top: 12px; }
 .twgit-panel .twgit-element span.twgit-element-name { width: auto; font-family: inherit; }
 .twgit-git-details > .twgit-connection-body { left: auto; right: 0; }
+/* In a layout tab the panel fills the tab and leaves the Editor beside it. */
+.twgit-panel.twgit-panel-tab { width: 100%; height: 100%; border: 0; border-radius: 0; box-shadow: none; }
 /*$vite$:1*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-plus-editor-git",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Read-only local Git panel for TurboWarp Plus Editor",
   "type": "module",
   "license": "MPL-2.0",

package/src/editor-block-locator.ts

@@ -0,0 +1,55 @@
+import {createScratchBlocksDiffLocator} from './block-diff-location.js';
+import type {ProjectBlockLocator, ScratchBlockLocationWorkspace} from './block-diff-location.js';
+
+/** The parts of a Scratch VM the locator reads to find a stage or sprite. */
+export interface LocatorVM {
+    runtime: {targets: readonly {id: string; isOriginal?: boolean; isStage: boolean; getName(): string}[]};
+    editingTarget?: {id: string} | null;
+}
+
+export interface EditorBlockLocatorOptions {
+    vm: LocatorVM;
+    /** Opens the code of one stage or sprite in the Editor, as project search does. */
+    openTargetCode(targetId: string): void | Promise<void>;
+    /** The Editor's code workspace as it is now, or `null` while none is shown. */
+    getWorkspace(): ScratchBlockLocationWorkspace | null | Promise<ScratchBlockLocationWorkspace | null>;
+}
+
+/**
+ * Finds the stage or sprite of a compared version in the open project, opens its code and waits for the block,
+ * then centers and outlines it. The caller decides which version matches the open project.
+ */
+export function createEditorBlockLocator({vm, openTargetCode, getWorkspace}: EditorBlockLocatorOptions): ProjectBlockLocator {
+    return createScratchBlocksDiffLocator(async ({target, id: blockId, signal}) => {
+        const found = vm.runtime.targets.find(item => target.isStage ? item.isStage :
+            !item.isStage && item.isOriginal !== false && item.getName() === target.name);
+        if (!found || signal.aborted) return null;
+        await openTargetCode(found.id);
+        // The Editor switches targets and fills its workspace over the next frames.
+        const deadline = Date.now() + waitLimit;
+        while (!signal.aborted) {
+            if (vm.editingTarget?.id === found.id) {
+                const workspace = await getWorkspace();
+                if (signal.aborted) break;
+                if (workspace?.getBlockById(blockId)) return workspace;
+            }
+            if (Date.now() >= deadline) break;
+            await nextFrame(signal);
+        }
+        return null;
+    });
+}
+
+const waitLimit = 2000;
+
+function nextFrame(signal: AbortSignal) {
+    return new Promise<void>(resolve => {
+        const done = () => {
+            signal.removeEventListener('abort', done);
+            resolve();
+        };
+        signal.addEventListener('abort', done, {once: true});
+        if (typeof requestAnimationFrame === 'function') requestAnimationFrame(done);
+        else setTimeout(done, 16);
+    });
+}

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,9 +16,9 @@ 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;
@@ -40,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,7 +331,7 @@ 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>
@@ -312,7 +361,8 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
             {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>
@@ -350,12 +400,20 @@ function GitPanel({document, host, controller}: {document: Document; host: GitHo
                 </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>}
-        </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>;
 }
 
@@ -376,7 +434,7 @@ export function mountGitPanel({vm, document, host}: {vm: object; document: Docum
     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/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'}`,
@@ -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-diff.css

@@ -106,3 +106,17 @@
     border: 1px solid var(--twgit-review-line, color-mix(in srgb, CanvasText 18%, Canvas));
     border-radius: 4px;
 }
+
+/* The legend matches the outlines drawn on the previews. */
+.twgit-review-legend { display: flex; flex-wrap: wrap; gap: 4px 14px; margin: 8px 0; font-size: .9em; }
+.twgit-review-legend span::before { content: ''; display: inline-block; width: 12px; height: 10px; margin-inline-end: 5px;
+    vertical-align: -1px; border: 2.5px solid var(--twgit-change); border-radius: 3px; }
+.twgit-review-legend [data-legend="added"] { --twgit-change: #25875d; }
+.twgit-review-legend [data-legend="removed"] { --twgit-change: #c54a53; }
+.twgit-review-legend [data-legend="updated"] { --twgit-change: #635bce; }
+.twgit-review-legend [data-legend="part"] { --twgit-change: #b4510a; }
+.twgit-review-legend [data-legend="part"]::before { border-radius: 0; }
+.twgit-review-summary { color: color-mix(in srgb, CanvasText 72%, Canvas); }
+.twgit-review-target-status { font-weight: 600; }
+.twgit-review-asset { display: flex; align-items: center; gap: 8px; }
+.twgit-review-asset img { width: 32px; height: 32px; object-fit: contain; }

package/src/project-source-diff.tsx

@@ -15,6 +15,8 @@ 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 {compareProjectForReview} from './project-source-review-model.js';
+export type {ScriptChangeKind, ScriptReview, ScriptReviewSide, ScriptSummaryItem, TargetReview} from './project-source-review-model.js';
 export {currentCostume} from './project-assets.js';
 export {assetFileName, organizeProjectChanges, projectPropertyLabel} from './project-change-model.js';
 export type {ChangedFile, OrganizeProjectChangesInput, ProjectChangeList, ProjectChangeStatus, ProjectElementChange, ProjectElementKind,

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

@@ -3,14 +3,33 @@ import type {BlockChange, BlockSide, ProjectSource, ProjectTarget} from './proje
 import type {ScriptBlockMark} from './scratch-block-diff-renderer.js';
 
 export interface ScriptReviewSide extends BlockSide { marks: ScriptBlockMark[] }
+/**
+ * What happened to one script. `moved` means only positions changed, `reordered` only how blocks connect;
+ * neither changes what the script does.
+ */
+export type ScriptChangeKind = 'added' | 'removed' | 'updated' | 'reorganized' | 'moved' | 'reordered';
+/** One phrase of a script's summary, in the order shown. The view words it in the reader's language. */
+export type ScriptSummaryItem =
+    | {kind: 'hatReplaced'; before: string; after: string}  // hat block opcodes
+    | {kind: 'wrapped'; opcode: string}                     // a new C block now holds blocks that existed before
+    | {kind: 'branchAdded'; opcode: string}                 // control_if or control_if_else added
+    | {kind: 'valueChanged'; opcode: string; name: string}  // an input or field of an existing block, by its name
+    | {kind: 'blocksAdded'; count: number}
+    | {kind: 'blocksRemoved'; count: number}
+    | {kind: 'reordered'}
+    | {kind: 'moved'};
 export interface ScriptReview {
     id: string;
     before: ScriptReviewSide[];
     after: ScriptReviewSide[];
+    kind: ScriptChangeKind;
+    summary: ScriptSummaryItem[];
 }
 export interface TargetReview {
     name: string;
     isStage: boolean;
+    /** Added or removed as a whole, or changed. Added and removed targets list no properties. */
+    status: 'added' | 'removed' | 'updated';
     /** The stage or sprite in each version, absent where it does not exist. */
     before?: ProjectTarget;
     after?: ProjectTarget;
@@ -66,24 +85,149 @@ function groupScripts(before: ProjectTarget | undefined, after: ProjectTarget |
         for (const root of new Set(roots[version].values())) {
             const key = version + ':' + root;
             const id = groupOf(key);
-            const group = groups.get(id) ?? {id, before: [], after: []};
+            const group = groups.get(id) ?? {id, before: [], after: [], kind: 'updated' as ScriptChangeKind, summary: [] as ScriptSummaryItem[]};
             const side: ScriptReviewSide = {target, id: root, marks: []};
             group[version].push(side);
             groups.set(id, group);
             sides.set(key, side);
         }
     }
-    const affected = new Set<string>();
+    const affected = new Map<string, BlockChange[]>();
     for (const change of changes) {
         for (const version of ['before', 'after'] as const) {
             const block = change[version];
             if (!block) continue;
             const key = version + ':' + roots[version].get(block.id);
-            sides.get(key)?.marks.push({id: block.id, kind: change.kind, parts: change.parts});
-            affected.add(groupOf(key));
+            // Only content changes are marked; a block that was merely reconnected or moved looks the same.
+            if (!isLayoutOnly(change)) sides.get(key)?.marks.push({id: block.id, kind: change.kind, parts: change.parts});
+            const id = groupOf(key);
+            const list = affected.get(id) ?? [];
+            if (!list.includes(change)) list.push(change);
+            affected.set(id, list);
+        }
+    }
+    return [...affected].map(([id, list]) => {
+        const group = groups.get(id)!;
+        group.kind = scriptKind(group, list);
+        group.summary = summarize(group, list, before, after);
+        return group;
+    });
+}
+
+const connectionFields = new Set(['next', 'parent', 'topLevel']);
+const positionFields = new Set(['x', 'y']);
+// Compact top-level reporters are arrays: [type, name, id, x, y].
+const compactPositionOnly = (a: unknown, b: unknown) =>
+    Array.isArray(a) && Array.isArray(b) && equal(a.slice(0, 3), b.slice(0, 3)) && !equal(a, b);
+
+function blockOf(side: BlockSide | undefined) {
+    return side ? side.target.blocks[side.id] : undefined;
+}
+
+/** True for an updated block whose content is the same: only its connections or its position changed. */
+function isLayoutOnly(change: BlockChange) {
+    if (change.kind !== 'updated') return false;
+    if (compactPositionOnly(blockOf(change.before), blockOf(change.after))) return true;
+    return change.fields.length > 0 && change.fields.every(field => connectionFields.has(field) || positionFields.has(field));
+}
+
+function isPositionOnly(change: BlockChange) {
+    if (change.kind !== 'updated') return false;
+    if (compactPositionOnly(blockOf(change.before), blockOf(change.after))) return true;
+    return change.fields.length > 0 && change.fields.every(field => positionFields.has(field));
+}
+
+function scriptKind(group: ScriptReview, changes: readonly BlockChange[]): ScriptChangeKind {
+    if (!group.before.length) return 'added';
+    if (!group.after.length) return 'removed';
+    if (group.before.length !== 1 || group.after.length !== 1) return 'reorganized';
+    if (changes.every(isPositionOnly)) return 'moved';
+    if (changes.every(isLayoutOnly)) return 'reordered';
+    return 'updated';
+}
+
+const opcodeOf = (block: unknown) => isRecord(block) && typeof block.opcode === 'string' ? block.opcode : undefined;
+const isShadow = (block: unknown) => !isRecord(block) || block.shadow === true;
+const isHat = (opcode: string | undefined) => opcode !== undefined &&
+    (opcode === 'control_start_as_clone' || opcode === 'procedures_definition' || /^[a-z0-9]+_when/i.test(opcode));
+const substackInputs = ['SUBSTACK', 'SUBSTACK2'];
+
+function inputBlock(block: unknown, name: string) {
+    if (!isRecord(block) || !isRecord(block.inputs)) return undefined;
+    const input = block.inputs[name];
+    return Array.isArray(input) && typeof input[1] === 'string' ? input[1] : undefined;
+}
+
+function summarize(group: ScriptReview, changes: readonly BlockChange[], before?: ProjectTarget, after?: ProjectTarget) {
+    const items: ScriptSummaryItem[] = [];
+    const seen = new Set<string>();
+    const add = (item: ScriptSummaryItem) => {
+        const key = JSON.stringify(item);
+        if (seen.has(key)) return;
+        seen.add(key);
+        items.push(item);
+    };
+    if (group.kind === 'moved' || group.kind === 'reordered') {
+        add({kind: group.kind});
+        return items;
+    }
+    const explained = new Set<BlockChange>();
+    if (group.before.length === 1 && group.after.length === 1) {
+        const oldRoot = group.before[0].id, newRoot = group.after[0].id;
+        const a = opcodeOf(before?.blocks[oldRoot]), b = opcodeOf(after?.blocks[newRoot]);
+        if (a !== b && isHat(a) && isHat(b)) {
+            add({kind: 'hatReplaced', before: a!, after: b!});
+            // The new hat and the one it replaced are the replacement, not separate additions and removals.
+            for (const change of changes) {
+                if ((change.kind === 'added' && change.after?.id === newRoot) || (change.kind === 'removed' && change.before?.id === oldRoot)) {
+                    explained.add(change);
+                }
+            }
+        }
+    }
+    const branches: BlockChange[] = [];
+    for (const change of changes) {
+        if (change.kind !== 'added' || !after) continue;
+        const block = after.blocks[change.after!.id];
+        const opcode = opcodeOf(block);
+        if (!opcode) continue;
+        const wraps = substackInputs.some(name => {
+            const visited = new Set<string>();
+            for (let id = inputBlock(block, name); id !== undefined && !visited.has(id);) {
+                visited.add(id);
+                if (before && Object.hasOwn(before.blocks, id)) return true;
+                const next = after.blocks[id];
+                id = isRecord(next) && typeof next.next === 'string' ? next.next : undefined;
+            }
+            return false;
+        });
+        if (wraps) {
+            add({kind: 'wrapped', opcode});
+            explained.add(change);
+        } else if (opcode === 'control_if' || opcode === 'control_if_else') {
+            branches.push(change);
+        }
+    }
+    for (const change of branches) {
+        add({kind: 'branchAdded', opcode: opcodeOf(after!.blocks[change.after!.id])!});
+        explained.add(change);
+    }
+    for (const change of changes) {
+        if (change.kind !== 'updated') continue;
+        const opcode = opcodeOf(blockOf(change.after)) ?? opcodeOf(blockOf(change.before));
+        if (!opcode) continue;
+        for (const part of change.parts) {
+            // A C block's slot holds blocks; what changed there is reported as additions, removals or wrapping.
+            if (part.kind === 'input' && substackInputs.includes(part.name)) continue;
+            add({kind: 'valueChanged', opcode, name: part.name});
         }
     }
-    return [...affected].map(id => groups.get(id)!);
+    const count = (kind: 'added' | 'removed') => changes.filter(change => change.kind === kind && !explained.has(change) &&
+        !isShadow(blockOf(kind === 'added' ? change.after : change.before))).length;
+    const added = count('added'), removed = count('removed');
+    if (added) add({kind: 'blocksAdded', count: added});
+    if (removed) add({kind: 'blocksRemoved', count: removed});
+    return items;
 }
 
 function changedProperties(before: Record<string, unknown>, after: Record<string, unknown>, except: string) {
@@ -106,10 +250,12 @@ export function compareProjectForReview(before: ProjectSource, after: ProjectSou
         const a = oldTargets.get(key), b = newTargets.get(key);
         const edits = byTarget.get(key);
         const scripts = edits ? groupScripts(a, b, edits) : [];
-        const properties = changedProperties({...a}, {...b}, 'blocks');
-        if (scripts.length || properties.length) {
+        const status = !a ? 'added' : !b ? 'removed' : 'updated';
+        // An added or removed target is shown as a whole; listing every key it has would say nothing more.
+        const properties = status === 'updated' ? changedProperties({...a}, {...b}, 'blocks') : [];
+        if (scripts.length || properties.length || status !== 'updated') {
             const {name, isStage} = (b ?? a)!;
-            targets.push({name, isStage, scripts, properties, before: a, after: b});
+            targets.push({name, isStage, status, scripts, properties, before: a, after: b});
         }
     }
     return {targets, properties: changedProperties(before, after, 'targets')};