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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-plus-editor-git",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Read-only local Git panel for TurboWarp Plus Editor",
   "type": "module",
   "license": "MPL-2.0",
@@ -36,6 +36,7 @@
     "tsconfig.json",
     "README.ja.md",
     "THIRD_PARTY_NOTICES.md",
+    "test/smart-http-fixture.js",
     "README.md",
     "LICENSE"
   ],

package/src/index.tsx

@@ -93,6 +93,9 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
     const alive = useRef(true);
     const opening = useRef(false);
     const dialog = useRef<HTMLDivElement>(null);
+    // A closed panel reads nothing; a refresh asked while it is closed waits until it opens again.
+    const shownRef = useRef(false);
+    const deferred = useRef(false);
     const reviewing = useRef(review);
     reviewing.current = review;
     // The last fingerprint acted on, so a failing read or an open diff is not retried on every check.
@@ -115,10 +118,20 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
         } catch (error) {
             if (epoch.current !== ticket) return;
             const code = error instanceof GitPanelError ? error.code : 'failed';
+            // A background read that met another tool still writing tries again on the next check, without an alert.
+            if (automatic && code === 'changed') {
+                handled.current = null;
+                setState(previous => ({...previous, busy: false}));
+                return;
+            }
             const message = labels[code as keyof typeof labels] || labels.failed;
             setState(previous => ({...previous, error: automatic && previous.error ? previous.error : message, busy: false, diff: null}));
         } finally {
             running.current = false;
+            // A result dropped by a newer load still ends the busy state, unless a refresh follows at once.
+            if (epoch.current !== ticket && !refreshPending.current && alive.current) {
+                setState(previous => ({...previous, busy: false}));
+            }
             if (automatic) {background.current = null; settle();}
             if (refreshPending.current) {
                 refreshPending.current = false;
@@ -143,14 +156,26 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
     };
     controller.refresh = async (automatic = false) => {
         if (!alive.current || !current.current.repository) return;
+        if (!shownRef.current) {
+            deferred.current = true;
+            return;
+        }
         if (running.current) {
             if (!automatic) refreshPending.current = true;
             return;
         }
         await run(async () => {
             const {repository, project} = current.current;
-            const snapshot = await repository!.read(project ?? '');
-            return {snapshot, changes: snapshot.changes, selected: null, diff: null, commit: null};
+            // A save or a Git command may still be finishing its writes; read again briefly before reporting a change.
+            for (let attempt = 1; ; attempt++) {
+                try {
+                    const snapshot = await repository!.read(project ?? '');
+                    return {snapshot, changes: snapshot.changes, selected: null, diff: null, commit: null};
+                } catch (error) {
+                    if (!(error instanceof GitPanelError && error.code === 'changed') || attempt >= 5) throw error;
+                    await new Promise(resolve => setTimeout(resolve, 200 * attempt));
+                }
+            }
         }, automatic);
     };
     useEffect(() => {
@@ -159,13 +184,21 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
             setDirty(host.isProjectDirty());
             if (event === 'loaded' && !opening.current) {
                 epoch.current++;
+                // An operation still running stays busy; its end, or the refresh queued after it, clears the flag.
                 setState(previous => ({...previous, project: null, snapshot: null, changes: [],
-                    selected: null, diff: null, commit: null, busy: false}));
+                    selected: null, diff: null, commit: null, busy: running.current}));
                 queueMicrotask(() => void controller.refresh());
             }
         });
         return () => {alive.current = false; epoch.current++; remoteRequest.current?.abort(); unsubscribe?.();};
     }, [host]);
+    useEffect(() => {
+        shownRef.current = shown;
+        if (shown && deferred.current) {
+            deferred.current = false;
+            void controller.refresh();
+        }
+    }, [shown]);
     // While the panel is open, notice Git commands, agents and editors that change the repository outside the Editor.
     useEffect(() => {
         const repository = state.repository;
@@ -175,7 +208,9 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
         let checking = false;
         const check = async () => {
             const {snapshot} = current.current;
-            if (stopped || checking || running.current || document.visibilityState === 'hidden' ||
+            // A tab behind another one has no boxes; it reads again when it is shown.
+            const hidden = !dialog.current || !dialog.current.getClientRects().length;
+            if (stopped || checking || running.current || document.visibilityState === 'hidden' || hidden ||
                 !snapshot || current.current.repository !== repository) return;
             checking = true;
             try {
@@ -409,7 +444,7 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
             </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>,
+    if (slot) return createPortal(<div className="twgit-panel twgit-panel-tab" ref={dialog} 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}

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')};

package/src/project-source-review.tsx

@@ -7,7 +7,9 @@ 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 {currentCostume, useAssetImage, useCostumeImage} from './project-assets.js';
+import {assetFileName, projectPropertyLabel} from './project-change-model.js';
+import {hatName, legend, summaryPhrase} from './review-words.js';
 import type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
 
 type Comparison = ReturnType<typeof compareProjectForReview>;
@@ -35,7 +37,11 @@ const ja = {
     review: '変更レビュー', fullDescription: 'PR 本文を表示', checks: '確認してほしいこと', files: '変更ファイル', targets: '影響するステージ・スプライト',
     scripts: 'コードの変更', scriptCount: (count: number) => `コードの変更 · ${count} か所`,
     reviewed: '確認済み', before: '変更前', after: '変更後',
-    updated: '変更', added: '追加', removed: '削除', reorganized: '再編',
+    updated: '変更', added: '追加', removed: '削除', reorganized: '再編', moved: '位置だけ', reordered: '並べ替え',
+    stage: 'ステージ', otherSettings: 'そのほかの設定', legend: '色の見方',
+    targetAdded: (name: string, stage: boolean) => stage ? 'ステージを追加' : `スプライト『${name}』を追加`,
+    targetRemoved: (name: string, stage: boolean) => stage ? 'ステージを削除' : `スプライト『${name}』を削除`,
+    assetOwner: (owner: string, kind: 'costume' | 'backdrop' | 'sound', name: string) => `${owner} の${kind === 'sound' ? '音' : kind === 'backdrop' ? '背景' : 'コスチューム'}『${name}』`,
     absent: 'この版にはこのコードがありません', loading: 'コードを描画中…',
     unavailable: 'このコードを描画できません。',
     related: '関連ファイル', properties: 'コード以外の変更', invalid: 'この作品の差分を読み込めません。',
@@ -49,7 +55,11 @@ const en: typeof ja = {
     review: 'Change review', fullDescription: 'Show full PR description', checks: 'Review checklist', files: 'Changed files', targets: 'Affected stages and sprites',
     scripts: 'Code changes', scriptCount: count => `Code changes · ${count}`,
     reviewed: 'Reviewed', before: 'Before', after: 'After',
-    updated: 'Changed', added: 'Added', removed: 'Removed', reorganized: 'Reorganized',
+    updated: 'Changed', added: 'Added', removed: 'Removed', reorganized: 'Reorganized', moved: 'Moved only', reordered: 'Reconnected',
+    stage: 'Stage', otherSettings: 'Other settings', legend: 'Colours',
+    targetAdded: (name, stage) => stage ? 'Added the stage' : `Added the sprite “${name}”`,
+    targetRemoved: (name, stage) => stage ? 'Removed the stage' : `Removed the sprite “${name}”`,
+    assetOwner: (owner, kind, name) => `${kind === 'sound' ? 'Sound' : kind === 'backdrop' ? 'Backdrop' : 'Costume'} “${name}” of ${owner}`,
     absent: 'No code in this version', loading: 'Rendering code…',
     unavailable: 'This code could not be rendered.',
     related: 'Related file', properties: 'Changes outside the code', invalid: 'This project diff could not be read.',
@@ -71,15 +81,12 @@ const properties = new Map<string, readonly [string, string]>([
 function scriptTitle(side: BlockSide, labels: typeof ja) {
     const block = side.target.blocks[side.id];
     if (!isRecord(block)) return labels.script;
-    if (block.opcode === 'event_whenflagclicked') return labels.flag;
-    if (block.opcode === 'event_whenthisspriteclicked') return labels.click;
-    if (block.opcode === 'event_whenkeypressed') return labels.key;
     if (block.opcode === 'event_whenbroadcastreceived') {
         const field = isRecord(block.fields) ? block.fields.BROADCAST_OPTION : undefined;
         const message = Array.isArray(field) && typeof field[0] === 'string' ? field[0] : '';
         if (message) return labels === ja ? `「${message}」${labels.broadcast}` : `“${message}” ${labels.broadcast}`;
     }
-    return typeof block.opcode === 'string' ? block.opcode : labels.script;
+    return typeof block.opcode === 'string' && hatName(block.opcode, labels === ja ? 'ja' : 'en') || labels.script;
 }
 
 type BlockLocation = {locate?(side: BlockSide): void; status(side: BlockSide): LocationStatus | undefined};
@@ -118,8 +125,9 @@ function ScriptComparison({script, labels, reviewed = false, setReviewed, render
 }) {
     const [open, setOpen] = useState(false);
     const {sync, toggle} = usePreviewSync(labels === ja ? 'ja' : 'en');
-    const status = !script.before.length ? 'added' : !script.after.length ? 'removed' :
-        script.before.length !== 1 || script.after.length !== 1 ? 'reorganized' : 'updated';
+    const status = script.kind;
+    const locale = labels === ja ? 'ja' : 'en';
+    const summary = script.summary.map(item => summaryPhrase(item, locale)).join(labels === ja ? '、' : ', ');
     const beforeTitle = script.before[0] && scriptTitle(script.before[0], labels);
     const afterTitle = script.after[0] && scriptTitle(script.after[0], labels);
     const title = beforeTitle && afterTitle && beforeTitle !== afterTitle ? beforeTitle + ' → ' + afterTitle : afterTitle ?? beforeTitle;
@@ -128,6 +136,7 @@ function ScriptComparison({script, labels, reviewed = false, setReviewed, render
             <span className="twgit-review-status">{labels[status]}</span>
             <strong>{title}</strong>
             {status === 'reorganized' && <small>{script.before.length} → {script.after.length}</small>}
+            {summary && <small className="twgit-review-summary">{summary}</small>}
             {reviewed && <small>{labels.reviewed}</small>}
         </summary>
         {open && <>
@@ -149,8 +158,16 @@ function ScriptComparison({script, labels, reviewed = false, setReviewed, render
     </details>;
 }
 
+// Keys without a name people know are grouped as other settings; the keys stay in the title for those who look.
 function propertyNames(keys: readonly string[], labels: typeof ja) {
-    return keys.map(key => properties.get(key)?.[labels === ja ? 0 : 1] ?? key).join(' · ');
+    const locale = labels === ja ? 'ja' : 'en';
+    const named = new Set<string>(), other: string[] = [];
+    for (const key of keys) {
+        const label = properties.get(key)?.[labels === ja ? 0 : 1] ?? projectPropertyLabel(key, locale);
+        if (label === key) other.push(key);
+        else named.add(label);
+    }
+    return <span title={keys.join(', ')}>{[...named, ...(other.length ? [labels.otherSettings] : [])].join(' · ')}</span>;
 }
 
 /**
@@ -186,8 +203,10 @@ function ComparisonTargets({comparison, labels, renderBlock, loadAsset, locateBl
         {!comparison.targets.length && !comparison.properties.length && <p>{labels.noChanges}</p>}
         {comparison.targets.map(target => <section className="twgit-review-target" key={JSON.stringify([target.isStage, target.name])}>
             <h5><TargetThumbnails target={target} labels={labels} loadAsset={loadAsset}/>
-                {target.name}{target.scripts.length > 0 && <small>{labels.scriptCount(target.scripts.length)}</small>}</h5>
-            {target.properties.length > 0 && <p>{labels.properties} · {propertyNames(target.properties, labels)}</p>}
+                {target.isStage ? labels.stage : target.name}{target.scripts.length > 0 && <small>{labels.scriptCount(target.scripts.length)}</small>}</h5>
+            {target.status !== 'updated' && <p className="twgit-review-target-status">
+                {(target.status === 'added' ? labels.targetAdded : labels.targetRemoved)(target.name, target.isStage)}</p>}
+            {target.status === 'updated' && target.properties.length > 0 && <p>{labels.properties} · {propertyNames(target.properties, labels)}</p>}
             {target.scripts.map(script => {
                 const key = JSON.stringify([review?.file, target.isStage, target.name, script.id]);
                 return <ScriptComparison key={key} script={script} labels={labels} renderBlock={renderBlock} loadAsset={loadAsset}
@@ -197,6 +216,51 @@ function ComparisonTargets({comparison, labels, renderBlock, loadAsset, locateBl
     </>;
 }
 
+function Legend({labels}: {labels: typeof ja}) {
+    return <p className="twgit-review-legend" aria-label={labels.legend}>
+        {legend(labels === ja ? 'ja' : 'en').map(([kind, text]) => <span key={kind} data-legend={kind}>{text}</span>)}
+    </p>;
+}
+
+type RelatedEntry = {file: ProjectSourceReviewFile; comparison?: Comparison};
+
+/** Finds who uses an asset file of the review: the costume or sound whose file name it is, in the project beside it. */
+function assetOwner(path: string, status: 'added' | 'removed' | 'updated', entries: readonly RelatedEntry[]) {
+    const parts = path.split('/');
+    const name = parts.pop()!;
+    const folder = parts.slice(0, -1).join('/');
+    const version: ProjectVersion = status === 'removed' ? 'before' : 'after';
+    for (const {file, comparison} of entries) {
+        if (!comparison || !('patch' in file) || file.path.split('/').slice(0, -1).join('/') !== folder) continue;
+        for (const target of comparison.targets) {
+            const owner = target[version];
+            if (!owner) continue;
+            for (const kind of ['costumes', 'sounds'] as const) {
+                const list = (owner as unknown as Record<string, unknown>)[kind];
+                if (!Array.isArray(list)) continue;
+                const entry = list.find(item => isRecord(item) && assetFileName(item) === name);
+                if (isRecord(entry)) return {target, version, md5ext: name, loadAsset: file.loadAsset,
+                    kind: kind === 'sounds' ? 'sound' as const : target.isStage ? 'backdrop' as const : 'costume' as const,
+                    name: typeof entry.name === 'string' ? entry.name : name};
+            }
+        }
+    }
+    return null;
+}
+
+function RelatedFile({file, entries, labels}: {
+    file: ProjectSourceReviewFile & {status: 'added' | 'removed' | 'updated'}; entries: readonly RelatedEntry[]; labels: typeof ja;
+}) {
+    const owner = assetOwner(file.path, file.status, entries);
+    const image = useAssetImage(owner && owner.kind !== 'sound' ? owner.md5ext : undefined, owner?.version ?? 'after', owner?.loadAsset);
+    if (!owner) return <p>{labels.related} · {labels[file.status]}</p>;
+    const ownerName = owner.target.isStage ? labels.stage : owner.target.name;
+    return <p className="twgit-review-asset">
+        {image && <img src={image} alt=""/>}
+        <span>{labels.assetOwner(ownerName, owner.kind, owner.name)} · {labels[file.status]}</span>
+    </p>;
+}
+
 const countScripts = (comparison: Comparison) => comparison.targets.reduce((count, target) => count + target.scripts.length, 0);
 
 export interface ProjectSourceComparisonProps {
@@ -234,6 +298,7 @@ export function ProjectSourceComparison({before, after, renderBlock, locale = 'e
     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}>
+        {!only && <Legend labels={labels}/>}
         {!only && <header className="twgit-review-overview">
             <dl>
                 <div><dt>{labels.targets}</dt><dd>{comparison.targets.length}</dd></div>
@@ -289,10 +354,11 @@ export function ProjectSourceReview({title, description, verification, files, re
                 <ul>{verification.map((item, index) => <li key={index}>{item}</li>)}</ul>
             </div>}
         </header>
+        <Legend labels={labels}/>
         <h3 className="twgit-review-files-title">{labels.files}</h3>
         {entries.map(({file, comparison, invalid}) => <section key={file.path} className="twgit-review-file">
             <header><h4>{file.previousPath ? file.previousPath + ' → ' + file.path : file.path}</h4>{file.summary && <p>{file.summary}</p>}</header>
-            {'status' in file && <p>{labels.related} · {labels[file.status]}</p>}
+            {'status' in file && <RelatedFile file={file} entries={entries} labels={labels}/>}
             {(invalid || file.unavailable) && <p role="alert">{labels.invalid}</p>}
             {comparison && <ComparisonTargets comparison={comparison} labels={labels} renderBlock={renderBlock}
                 loadAsset={'loadAsset' in file ? file.loadAsset : undefined}

package/src/review-words.ts

@@ -0,0 +1,66 @@
+import type {ScriptSummaryItem} from './project-source-review-model.js';
+
+type Pair = readonly [string, string];
+const pick = ([ja, en]: Pair, locale: string) => locale.startsWith('ja') ? ja : en;
+
+// Hat blocks name a script, as people read it in the Editor.
+const hats = new Map<string, Pair>([
+    ['event_whenflagclicked', ['緑の旗が押されたとき', 'When green flag clicked']],
+    ['event_whenthisspriteclicked', ['このスプライトが押されたとき', 'When this sprite clicked']],
+    ['event_whenstageclicked', ['ステージが押されたとき', 'When stage clicked']],
+    ['event_whenkeypressed', ['キーが押されたとき', 'When key pressed']],
+    ['event_whenbackdropswitchesto', ['背景が切り替わったとき', 'When backdrop switches']],
+    ['event_whengreaterthan', ['値が超えたとき', 'When value exceeds']],
+    ['event_whenbroadcastreceived', ['メッセージを受け取ったとき', 'When message received']],
+    ['control_start_as_clone', ['クローンされたとき', 'When I start as a clone']],
+    ['procedures_definition', ['定義', 'Define']]
+]);
+
+// Only blocks that summaries name; anything else is called a block.
+const blocks = new Map<string, Pair>([
+    ['control_repeat', ['〜回繰り返す', 'repeat'], ], ['control_forever', ['ずっと', 'forever']],
+    ['control_repeat_until', ['〜まで繰り返す', 'repeat until']], ['control_while', ['〜の間繰り返す', 'while']],
+    ['control_if', ['もし〜なら', 'if']], ['control_if_else', ['もし〜なら、でなければ', 'if else']],
+    ['control_wait', ['〜秒待つ', 'wait']], ['motion_movesteps', ['〜歩動かす', 'move steps']],
+    ['motion_turnright', ['〜度回す', 'turn']], ['motion_turnleft', ['〜度回す', 'turn']], ['motion_gotoxy', ['x座標を〜、y座標を〜にする', 'go to x y']],
+    ['motion_changeyby', ['y座標を〜ずつ変える', 'change y by']], ['motion_changexby', ['x座標を〜ずつ変える', 'change x by']],
+    ['motion_glidesecstoxy', ['〜秒でx座標を〜に、y座標を〜に変える', 'glide']],
+    ['looks_sayforsecs', ['〜と〜秒言う', 'say for secs']], ['looks_say', ['〜と言う', 'say']],
+    ['looks_switchcostumeto', ['コスチュームを〜にする', 'switch costume']], ['looks_nextcostume', ['次のコスチュームにする', 'next costume']],
+    ['data_setvariableto', ['〜を〜にする', 'set variable']], ['data_changevariableby', ['〜を〜ずつ変える', 'change variable']],
+    ['event_broadcast', ['〜を送る', 'broadcast']], ['sound_play', ['〜の音を鳴らす', 'play sound']]
+]);
+
+export function hatName(opcode: string, locale: string): string | undefined {
+    const pair = hats.get(opcode);
+    return pair && pick(pair, locale);
+}
+
+const blockName = (opcode: string, locale: string) => {
+    const pair = blocks.get(opcode) ?? hats.get(opcode);
+    return pair ? pick(pair, locale) : locale.startsWith('ja') ? 'ブロック' : 'a block';
+};
+
+/** One phrase per summary item, in the reader's language. */
+export function summaryPhrase(item: ScriptSummaryItem, locale: string): string {
+    const ja = locale.startsWith('ja');
+    switch (item.kind) {
+    case 'hatReplaced': return ja ? `「${blockName(item.before, locale)}」を「${blockName(item.after, locale)}」に替えた` :
+        `replaced “${blockName(item.before, locale)}” with “${blockName(item.after, locale)}”`;
+    case 'wrapped': return ja ? `「${blockName(item.opcode, locale)}」で包んだ` : `wrapped in “${blockName(item.opcode, locale)}”`;
+    case 'branchAdded': return ja ? `分岐「${blockName(item.opcode, locale)}」を追加` : `added “${blockName(item.opcode, locale)}”`;
+    case 'valueChanged': return ja ? `「${blockName(item.opcode, locale)}」の ${item.name} を変更` :
+        `changed ${item.name} of “${blockName(item.opcode, locale)}”`;
+    case 'blocksAdded': return ja ? `ブロックを ${item.count} 個追加` : `added ${item.count} ${item.count === 1 ? 'block' : 'blocks'}`;
+    case 'blocksRemoved': return ja ? `ブロックを ${item.count} 個削除` : `removed ${item.count} ${item.count === 1 ? 'block' : 'blocks'}`;
+    case 'reordered': return ja ? 'つなぎ方だけを変更' : 'only reconnected';
+    case 'moved': return ja ? '位置だけを変更' : 'only moved';
+    }
+}
+
+/** The colours of the previews, said once at the top of a review. */
+export const legend = (locale: string) => locale.startsWith('ja') ?
+    [['added', '緑の縁: 追加したブロック'], ['removed', '赤の縁: 削除したブロック'], ['updated', '紫の縁: 中身を変えたブロック'],
+        ['part', 'オレンジの枠: 値を変えた欄']] as const :
+    [['added', 'Green outline: added block'], ['removed', 'Red outline: removed block'], ['updated', 'Purple outline: block with changed contents'],
+        ['part', 'Orange frame: changed value']] as const;