@kubohiroya/turbowarp-plus-editor-git 0.0.0-stage → 0.8.0

package/src/mutation-fs.ts

@@ -0,0 +1,204 @@
+import {createReadOnlyFs, errorCode, fileError, fileStat, GitPanelError, pathParts, sameBytes} from './filesystem.js';
+
+type Entry = {kind: 'directory'} | {kind: 'file'; bytes: Uint8Array<ArrayBuffer>; time: number} | null;
+type Change = {path: string; before: Entry; after: Entry};
+const missing = (error: unknown) => ['ENOENT', 'ENOTDIR'].includes(errorCode(error) ?? '');
+
+// Stage Git's writes before touching the granted directory. Pack data precedes refs.
+export function createMutationFs(root: FileSystemDirectoryHandle, worktree: boolean) {
+    const base = createReadOnlyFs(root);
+    const changes = new Map<string, Change>();
+    const normalize = (path: string) => '/' + pathParts(path).join('/');
+    const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/';
+    const name = (path: string) => path.slice(path.lastIndexOf('/') + 1);
+    const fail = (code: string, path: string): never => {throw fileError(code, path);};
+    function allow(path: string, directory = false) {
+        const parts = pathParts(path);
+        const [first, second, ...rest] = parts;
+        if (!first || parts.slice(1).some(part => part.toLowerCase() === '.git'))
+            return fail('EACCES', path);
+        if (first === '.git') {
+            const writableFolder = second === 'refs' || second === 'logs' ||
+                (second === 'objects' && rest[0]?.toLowerCase() !== 'info');
+            const writableFile = !directory && !rest.length &&
+                ['HEAD', 'ORIG_HEAD', 'FETCH_HEAD', 'index', 'packed-refs', 'shallow'].includes(second);
+            if (writableFolder || writableFile) return;
+        } else if (first.toLowerCase() !== '.git' && worktree) {
+            return;
+        }
+        fail('EACCES', path);
+    }
+
+    async function readEntry(fs: typeof base.promises, path: string): Promise<Entry> {
+        try {
+            const stat = await fs.stat(path);
+            if (stat.isDirectory()) return {kind: 'directory'};
+            const bytes = await fs.readFile(path);
+            if (!(bytes instanceof Uint8Array)) throw new GitPanelError('unsupported');
+            return {kind: 'file', bytes: Uint8Array.from(bytes), time: stat.mtimeMs};
+        } catch (error) {
+            if (missing(error)) return null;
+            throw error;
+        }
+    }
+
+    async function kind(path: string) {
+        const change = changes.get(path);
+        if (change) return change.after?.kind;
+        try {return (await base.promises.stat(path)).isDirectory() ? 'directory' : 'file';}
+        catch (error) {if (!missing(error)) throw error;}
+    }
+
+    async function stage(path: string, after: Entry) {
+        const previous = changes.get(path);
+        const before = previous ? previous.before : await readEntry(base.promises, path);
+        if (before && after && before.kind !== after.kind) throw new GitPanelError('unsupported');
+        changes.set(path, {path, before, after});
+    }
+
+    async function readdir(raw: string) {
+        const path = normalize(raw);
+        const current = await kind(path);
+        if (current !== 'directory') return fail(current ? 'ENOTDIR' : 'ENOENT', path);
+        const names = new Set<string>();
+        try {for (const entry of await base.promises.readdir(path)) names.add(entry);}
+        catch (error) {if (!missing(error)) throw error;}
+        for (const change of changes.values()) {
+            if (parent(change.path) !== path) continue;
+            if (change.after) names.add(name(change.path));
+            else names.delete(name(change.path));
+        }
+        return [...names];
+    }
+
+    async function remove(raw: string, directory: boolean) {
+        const path = normalize(raw);
+        allow(path, directory);
+        const current = await kind(path);
+        if (!current) return fail('ENOENT', path);
+        if (directory !== (current === 'directory')) return fail(directory ? 'ENOTDIR' : 'EISDIR', path);
+        if (directory && (await readdir(path)).length) return fail('ENOTEMPTY', path);
+        await stage(path, null);
+    }
+
+    async function stat(raw: string) {
+        const path = normalize(raw);
+        const change = changes.get(path);
+        if (!change) return base.promises.stat(path);
+        if (!change.after) return fail('ENOENT', path);
+        return fileStat(change.after.kind === 'directory' ? null :
+            {size: change.after.bytes.length, lastModified: change.after.time});
+    }
+
+    const fs = {promises: {
+        async readFile(raw: string, options?: string | {encoding?: string}) {
+            const path = normalize(raw);
+            const change = changes.get(path);
+            if (!change) return base.promises.readFile(path, options);
+            if (!change.after) return fail('ENOENT', path);
+            if (change.after.kind === 'directory') return fail('EISDIR', path);
+            const encoding = typeof options === 'string' ? options : options?.encoding;
+            return encoding ? new TextDecoder(encoding).decode(change.after.bytes) : change.after.bytes.slice();
+        },
+        async writeFile(raw: string, bytes: string | Uint8Array, options?: {mode?: number}) {
+            const path = normalize(raw);
+            allow(path);
+            if (!path.startsWith('/.git/') && options?.mode && (options.mode & 0o111))
+                throw new GitPanelError('unsupported');
+            if (await kind(parent(path)) !== 'directory') return fail('ENOENT', path);
+            if (await kind(path) === 'directory') return fail('EISDIR', path);
+            await stage(path, {kind: 'file', bytes: typeof bytes === 'string' ?
+                new TextEncoder().encode(bytes) : Uint8Array.from(bytes), time: Date.now()});
+        },
+        async mkdir(raw: string) {
+            const path = normalize(raw);
+            if (await kind(path)) return fail('EEXIST', path);
+            allow(path, true);
+            if (await kind(parent(path)) !== 'directory') return fail('ENOENT', path);
+            await stage(path, {kind: 'directory'});
+        },
+        unlink: (path: string) => remove(path, false),
+        rmdir: (path: string) => remove(path, true),
+        readdir, stat, lstat: stat,
+        readlink: base.promises.readlink,
+        symlink: base.promises.symlink,
+        chmod: base.promises.chmod
+    }};
+
+    function equal(a: Entry, b: Entry) {
+        return a?.kind === b?.kind && (a?.kind !== 'file' || (b?.kind === 'file' && sameBytes(a.bytes, b.bytes)));
+    }
+
+    async function apply(path: string, from: Entry, to: Entry) {
+        const current = createReadOnlyFs(root).promises;
+        if (path.startsWith('/.git/') && (await readEntry(current, path + '.lock') ||
+            await readEntry(current, '/.git/index.lock') || await readEntry(current, '/.git/packed-refs.lock')))
+            throw new GitPanelError('changed');
+        if (!equal(await readEntry(current, path), from))
+            throw new GitPanelError('changed');
+        let directory = root;
+        for (const part of pathParts(parent(path))) directory = await directory.getDirectoryHandle(part);
+        const filename = name(path);
+        if (!to) await directory.removeEntry(filename);
+        else if (to.kind === 'directory') await directory.getDirectoryHandle(filename, {create: true});
+        else {
+            const handle = await directory.getFileHandle(filename, {create: !from});
+            let stream: FileSystemWritableFileStream | undefined;
+            try {
+                stream = await handle.createWritable();
+                await stream.write(to.bytes);
+                await stream.close();
+            } catch (error) {
+                await stream?.abort().catch(() => {});
+                if (!from) {
+                    const current = await handle.getFile();
+                    if (current.size === 0) await directory.removeEntry(filename);
+                }
+                throw error;
+            }
+        }
+    }
+
+    function order(change: Change) {
+        const {path, before, after} = change;
+        const depth = pathParts(path).length;
+        if (!after) return before?.kind === 'directory' ? 1000 - depth : 0;
+        if (after.kind === 'directory') return 1000 + depth;
+        if (path.startsWith('/.git/objects/')) return 2000;
+        if (!path.startsWith('/.git/')) return 3000;
+        return path.startsWith('/.git/refs/heads/') || path === '/.git/HEAD' ? 5000 : 4000;
+    }
+
+    return {fs, async commit(guard: () => void) {
+        const pending = [...changes.values()].filter(change => !equal(change.before, change.after))
+            .sort((left, right) => order(left) - order(right));
+        await base.checkReads();
+        for (const change of pending) {
+            if (!equal(await readEntry(createReadOnlyFs(root).promises, change.path), change.before))
+                throw new GitPanelError('changed');
+        }
+        const applied: Change[] = [];
+        try {
+            for (const change of pending) {
+                guard();
+                try {
+                    await apply(change.path, change.before, change.after);
+                    applied.push(change);
+                } catch (error) {
+                    const current = await readEntry(createReadOnlyFs(root).promises, change.path);
+                    if (equal(current, change.after) && !(error instanceof GitPanelError)) applied.push(change);
+                    throw error;
+                }
+            }
+            guard();
+        } catch (error) {
+            let rollbackFailed = false;
+            for (const change of applied.reverse()) {
+                try {await apply(change.path, change.after, change.before);}
+                catch {rollbackFailed = true;}
+            }
+            if (rollbackFailed) throw new GitPanelError('rollbackFailed');
+            throw error;
+        }
+    }};
+}

package/src/project-asset-paths.ts

@@ -0,0 +1,33 @@
+// Shared by the local and GitHub asset loaders. Kept free of React so the repository entry stays UI-free.
+
+/** The largest asset a thumbnail reads. */
+export const assetLimit = 10 * 1024 * 1024;
+/** The largest sb3-source.json read to find the assets directory. */
+export const folderSettingsLimit = 1024 * 1024;
+
+/** Asset names are plain `<md5>.<ext>` file names; anything else could address a path outside the assets directory. */
+export const isAssetName = (name: unknown): name is string =>
+    typeof name === 'string' && /^[0-9A-Za-z_-]{1,128}\.[0-9A-Za-z]{1,8}$/.test(name);
+
+/**
+ * The assets directory named by one version of a project folder's `sb3-source.json`, as path segments relative to the
+ * folder. `assets` when that file or its `assetsDirectory` field is missing or unreadable. `null` when the field names
+ * anything other than a plain relative path inside the folder.
+ */
+export function assetsDirectoryParts(settings: string | null): string[] | null {
+    let value: unknown = 'assets';
+    if (settings !== null) {
+        try {
+            const parsed: unknown = JSON.parse(settings);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) && 'assetsDirectory' in parsed) {
+                value = (parsed as {assetsDirectory: unknown}).assetsDirectory;
+            }
+        } catch {
+            // An unreadable file names no directory, as a missing one does.
+        }
+    }
+    if (typeof value !== 'string' || value.length > 1024) return null;
+    const parts = value.split('/');
+    return parts.every(part => part && part !== '.' && part !== '..' && part.toLowerCase() !== '.git' &&
+        !/[\\\0-\x1f\x7f]/.test(part)) ? parts : null;
+}

package/src/project-assets.ts

@@ -0,0 +1,66 @@
+import {useEffect, useState} from 'react';
+import {isRecord} from './project-source-patch.js';
+import type {ProjectTarget} from './project-source-patch.js';
+
+export type ProjectVersion = 'before' | 'after';
+
+/**
+ * Reads one asset of one version of a project file by its `md5ext` name (for example `0123…cdef.svg`), from the
+ * assets directory of that project. Resolves `null` when that version has no readable file of that name.
+ */
+export type ProjectAssetLoader = (request: {version: ProjectVersion; md5ext: string; signal: AbortSignal}) => Promise<Blob | null>;
+
+const imageTypes: Record<string, string> = {
+    svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', bmp: 'image/bmp', webp: 'image/webp'
+};
+
+/** The costume a sprite shows, or the backdrop the stage shows, when the project data names an image file for it. */
+export function currentCostume(target: ProjectTarget): {name: string; md5ext: string; type: string} | null {
+    const {costumes, currentCostume: index} = target as unknown as Record<string, unknown>;
+    if (!Array.isArray(costumes)) return null;
+    const costume: unknown = costumes[typeof index === 'number' && Number.isInteger(index) && index >= 0 ? index : 0];
+    if (!isRecord(costume)) return null;
+    const md5ext = typeof costume.md5ext === 'string' ? costume.md5ext :
+        typeof costume.assetId === 'string' && typeof costume.dataFormat === 'string' ? costume.assetId + '.' + costume.dataFormat : '';
+    // Asset names are plain file names; anything else could address a path outside the assets directory.
+    const match = /^[0-9A-Za-z_-]{1,128}\.([0-9A-Za-z]{1,8})$/.exec(md5ext);
+    const type = match ? imageTypes[match[1].toLowerCase()] : undefined;
+    if (!type) return null;
+    return {name: typeof costume.name === 'string' ? costume.name : '', md5ext, type};
+}
+
+// Thumbnails of one target appear in its heading and in each of its frames, so one read serves all of them.
+const reads = new WeakMap<ProjectAssetLoader, Map<string, Promise<Blob | null>>>();
+function readAsset(loadAsset: ProjectAssetLoader, version: ProjectVersion, md5ext: string) {
+    let cache = reads.get(loadAsset);
+    if (!cache) reads.set(loadAsset, cache = new Map());
+    const key = version + ':' + md5ext;
+    let read = cache.get(key);
+    if (!read) {
+        read = loadAsset({version, md5ext, signal: new AbortController().signal}).catch(() => null);
+        cache.set(key, read);
+    }
+    return read;
+}
+
+/** Loads the current costume of one version of a target as an object URL for an image, or `null` while it is unavailable. */
+export function useCostumeImage(target: ProjectTarget | undefined, version: ProjectVersion, loadAsset?: ProjectAssetLoader): string | null {
+    const costume = target && loadAsset ? currentCostume(target) : null;
+    const key = costume ? version + ':' + costume.md5ext : '';
+    const [image, setImage] = useState<{key: string; url: string}>();
+    useEffect(() => {
+        if (!costume || !loadAsset) return;
+        let active = true;
+        let url: string | undefined;
+        void readAsset(loadAsset, version, costume.md5ext).then(blob => {
+            if (!blob || !active) return;
+            url = URL.createObjectURL(new Blob([blob], {type: costume.type}));
+            setImage({key, url});
+        });
+        return () => {
+            active = false;
+            if (url) URL.revokeObjectURL(url);
+        };
+    }, [key, loadAsset]);
+    return image?.key === key ? image.url : null;
+}

package/src/project-source-diff.css

@@ -0,0 +1,108 @@
+.twgit-block-diff {
+    color: CanvasText;
+    background: Canvas;
+    font: 14px/1.5 system-ui, sans-serif;
+    container-type: inline-size;
+}
+.twgit-block-diff h2 { margin: 0; font-size: 1.3em; }
+.twgit-block-diff > p { margin: 4px 0 10px; }
+.twgit-block-diff-card {
+    border: 1px solid color-mix(in srgb, CanvasText 25%, Canvas);
+    border-radius: 8px;
+    margin: 12px 0;
+    overflow: hidden;
+}
+.twgit-block-diff-card > header { padding: 10px 14px; background: color-mix(in srgb, CanvasText 5%, Canvas); }
+.twgit-block-diff-card h3, .twgit-block-diff-card h4 { margin: 0; font-size: 1em; overflow-wrap: anywhere; }
+.twgit-block-diff-card h3 span { margin-inline-end: 6px; color: CanvasText; border-bottom: 3px solid var(--twgit-change); }
+.twgit-block-diff-card p { margin: 4px 0 0; }
+.twgit-block-diff-added { --twgit-change: #25875d; }
+.twgit-block-diff-removed { --twgit-change: #c54a53; }
+.twgit-block-diff-updated { --twgit-change: #635bce; }
+.twgit-block-diff-sides { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.twgit-block-diff-side { padding: 10px 14px; min-width: 0; }
+.twgit-block-diff-side + .twgit-block-diff-side { border-inline-start: 1px solid color-mix(in srgb, CanvasText 20%, Canvas); }
+/* A preview is a small workspace: it scrolls and zooms inside its frame, which people can make taller. */
+.twgit-block-diff-preview {
+    position: relative;
+    overflow: hidden;
+    resize: vertical;
+    min-height: 120px;
+    max-height: 85vh;
+    border: 1px solid color-mix(in srgb, CanvasText 18%, Canvas);
+    border-radius: 6px;
+}
+.twgit-block-diff-surface { position: absolute; inset: 0; }
+.twgit-block-diff-watermark { position: absolute; z-index: 2; top: 10px; right: 12px; pointer-events: none; }
+.twgit-block-diff-watermark[data-navigation] { top: auto; right: var(--plus-watermark-right, 12px); bottom: var(--plus-watermark-bottom, 140px); }
+.twgit-block-diff-watermark > img {
+    display: block;
+    max-width: var(--plus-watermark-size, 48px);
+    max-height: var(--plus-watermark-size, 48px);
+    opacity: .6;
+}
+.twgit-block-diff-link { display: block; padding: 6px 12px 0; }
+/* These markers also apply to the live Editor workspace returned by the host. */
+.twgit-changed-block > .blocklyPath { stroke: var(--twgit-change, #635bce); stroke-width: 2.5px; }
+.twgit-changed-block-part { outline: 2.5px solid #b4510a; outline-offset: 2px; }
+.twgit-block-diff-legend { font-size: .9em; }
+.twgit-block-diff-side > button { margin-top: 8px; }
+.twgit-block-diff-card > label { display: block; padding: 7px 14px 10px; }
+@container (max-width: 440px) {
+    .twgit-block-diff-sides { grid-template-columns: minmax(0, 1fr); }
+    .twgit-block-diff-side + .twgit-block-diff-side { border-inline-start: 0; border-block-start: 1px solid color-mix(in srgb, CanvasText 20%, Canvas); }
+}
+
+.twgit-review { --twgit-review-line: color-mix(in srgb, CanvasText 18%, Canvas); }
+.twgit-review-overview { border-bottom: 1px solid var(--twgit-review-line); padding-bottom: 14px; }
+.twgit-review-overview > p:first-child { margin: 0 0 5px; color: color-mix(in srgb, CanvasText 70%, Canvas); font-weight: 600; }
+.twgit-review-overview h2 { font-size: 1.65em; }
+.twgit-review-description { white-space: pre-wrap; overflow-wrap: anywhere; margin: 5px 0; }
+.twgit-review-body summary { cursor: pointer; text-decoration: underline; }
+.twgit-review-overview dl { display: flex; flex-wrap: wrap; gap: 8px; margin: 14px 0; }
+.twgit-review-overview dl > div { min-width: 90px; padding: 7px 12px; border: 1px solid var(--twgit-review-line); border-radius: 6px; }
+.twgit-review-overview dt { font-size: .85em; }
+.twgit-review-overview dd { margin: 0; font-size: 1.3em; font-weight: 650; }
+.twgit-review-checklist h3, .twgit-review-checklist ul { margin: 0; }
+.twgit-review-checklist ul { padding-inline-start: 22px; }
+.twgit-review-files-title { margin: 13px 0 6px; }
+.twgit-review-file { border: 1px solid var(--twgit-review-line); border-radius: 8px; overflow: hidden; margin-bottom: 10px; }
+.twgit-review-file > header { background: color-mix(in srgb, CanvasText 5%, Canvas); padding: 8px 12px; }
+.twgit-review-file > header h4, .twgit-review-file > header p { margin: 0; overflow-wrap: anywhere; }
+.twgit-review-file > p, .twgit-review-target > p { margin: 6px 12px; }
+.twgit-review-target { padding: 6px 12px 10px; }
+.twgit-review-target h5 { font-size: 1em; margin: 0 0 5px; }
+.twgit-review-target h5 small { margin-inline-start: 6px; font-weight: 400; }
+.twgit-review-script { border: 1px solid var(--twgit-review-line); border-radius: 6px; margin: 4px 0; overflow: hidden; }
+.twgit-review-script > summary { cursor: pointer; padding: 7px 10px; list-style: none; }
+.twgit-review-script > summary::-webkit-details-marker { display: none; }
+.twgit-review-script > summary::before { content: '▸'; margin-inline-end: 7px; }
+.twgit-review-script[open] > summary::before { content: '▾'; }
+.twgit-review-script > summary:focus-visible { outline: 2px solid Highlight; outline-offset: -2px; }
+.twgit-review-script > summary > * { margin-inline-end: 8px; }
+.twgit-review-script[open] > summary { border-bottom: 1px solid var(--twgit-review-line); }
+.twgit-review-script h4 { margin: 0 0 3px; }
+.twgit-review-script .twgit-block-diff-side + .twgit-block-diff-side { border-inline-start: 0; border-block-start: 1px solid var(--twgit-review-line); }
+.twgit-review-script .twgit-block-diff-sides > div + div { border-inline-start: 1px solid var(--twgit-review-line); }
+.twgit-review-status { font-size: .85em; padding: 2px 5px; border: 1px solid var(--twgit-review-line); border-radius: 4px; }
+.twgit-review-checked { display: block; padding: 6px 12px 9px; }
+@container (max-width: 440px) {
+    .twgit-review-script .twgit-block-diff-sides > div + div { border-inline-start: 0; border-block-start: 1px solid var(--twgit-review-line); }
+}
+
+.twgit-pr-number { display: flex; flex-wrap: wrap; align-items: end; gap: 6px; margin-bottom: 8px; }
+.twgit-pr-number input { display: block; width: 10em; max-width: 100%; }
+.twgit-pr-paging, .twgit-pr-revision { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+.twgit-pr-revision code { overflow-wrap: anywhere; }
+.twgit-review .twgit-block-diff-side h4 { font-size: 1em; }
+
+/* Costume (or backdrop) thumbnails in stage and sprite headings. */
+.twgit-review-thumbnails { display: inline-flex; align-items: center; gap: 4px; margin-inline-end: 6px; vertical-align: middle; }
+.twgit-review-thumbnails img {
+    width: 30px;
+    height: 30px;
+    object-fit: contain;
+    background: Canvas;
+    border: 1px solid var(--twgit-review-line, color-mix(in srgb, CanvasText 18%, Canvas));
+    border-radius: 4px;
+}

package/src/project-source-diff.tsx

@@ -0,0 +1,139 @@
+import React, {useEffect, useMemo, useRef, useState} from 'react';
+import {compareProjectBlocks, readProjectSourceDiff} from './project-source-patch.js';
+import type {BlockChange} from './project-source-patch.js';
+import type {ProjectBlockLocator} from './block-diff-location.js';
+import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+import {BlockPreview, usePreviewSync} from './block-diff-preview.js';
+import type {LocationStatus} from './block-diff-preview.js';
+import './project-source-diff.css';
+
+export {createGitHubPullRequests, gitHubRepositoryFromOrigin} from './github-pull-requests.js';
+export {ProjectSourceComparison, ProjectSourceReview} from './project-source-review.js';
+export type {ProjectSourceComparisonProps, ProjectSourceReviewFile, ProjectSourceReviewProps} from './project-source-review.js';
+
+export {createScratchBlocksDiffLocator} from './block-diff-location.js';
+export type {ProjectBlockLocation, ProjectBlockLocator, ScratchBlockLocationWorkspace} from './block-diff-location.js';
+export type {BlockPart} from './project-source-patch.js';
+export {createProjectSourceDiff} from './project-source-patch.js';
+export {currentCostume} from './project-assets.js';
+export type {ProjectAssetLoader, ProjectVersion} from './project-assets.js';
+export {createScratchBlocksDiffRenderer} from './scratch-block-diff-renderer.js';
+export type {BlockPreviewView, BlockPreviewViewport, ProjectBlockRenderer, ProjectBlockRendering, ScratchBlockDiffRendererOptions,
+    ScratchBlocksPort} from './scratch-block-diff-renderer.js';
+export {createPreviewSync} from './block-diff-preview.js';
+export type {PreviewSync} from './block-diff-preview.js';
+
+const en = {
+    title: 'Block changes', before: 'Before', after: 'After', added: 'Added', removed: 'Removed', updated: 'Changed',
+    inputs: 'Inputs', fields: 'Fields', opcode: 'Block type', mutation: 'Block shape', position: 'Position',
+    connection: 'Connections', properties: 'Other block properties',
+    absent: 'No block on this side', omitted: (count: number) => `${count} unchanged blocks omitted from the change list`,
+    context: 'Highlight in the surrounding code', more: 'Show more changes', noChanges: 'No block changes.',
+    locate: 'Highlight in Editor', locating: 'Finding the block in the Editor…', located: 'Highlighted in the Editor.',
+    missingLocation: 'This version or block is unavailable in the Editor. Open its surrounding code here.',
+    partLegend: 'Orange outlines mark changed inputs and fields.',
+    otherChanges: 'The project also has changes outside its block code.',
+    invalid: 'This diff could not be read. Use a full-context project diff, or provide the original project.',
+    loading: 'Rendering blocks…', unavailable: 'This block could not be rendered. Check the block definitions available in the host.'
+};
+const ja: typeof en = {
+    title: 'ブロックの変更', before: '変更前', after: '変更後', added: '追加', removed: '削除', updated: '変更',
+    inputs: '入力値', fields: 'フィールド', opcode: 'ブロックの種類', mutation: 'ブロックの形', position: '位置',
+    connection: 'つなぎ方', properties: 'その他のブロック属性',
+    absent: 'この側にはブロックがありません', omitted: count => `変更のないブロック ${count} 個を一覧から省略`,
+    context: '元のコード内で強調', more: '続きを表示', noChanges: 'ブロックの変更はありません。',
+    locate: '編集画面で強調', locating: '編集画面でブロックを検索中…', located: '編集画面で強調しました。',
+    missingLocation: '編集画面に該当する版またはブロックがありません。元のコードをここで展開できます。',
+    partLegend: 'オレンジの枠は、変更された入力欄やフィールドです。',
+    otherChanges: 'ブロックのコード以外にも作品の変更があります。',
+    invalid: '差分を読み込めません。全体の文脈を含む差分を使うか、変更前の作品を指定してください。',
+    loading: 'ブロックを描画中…', unavailable: 'ブロックを描画できません。ホストのブロック定義を確認してください。'
+};
+
+export interface ProjectSourceBlockDiffProps {
+    patch: string;
+    /** Supply the original JSON if the unified patch omits context. */
+    beforeSource?: string;
+    renderBlock: ProjectBlockRenderer;
+    locateBlock?: ProjectBlockLocator;
+    locale?: string;
+}
+
+type Version = 'before' | 'after';
+
+const propertyLabels = new Map<string, keyof typeof en>([
+    ['inputs', 'inputs'], ['fields', 'fields'], ['opcode', 'opcode'], ['mutation', 'mutation'],
+    ['x', 'position'], ['y', 'position'], ['next', 'connection'], ['parent', 'connection'], ['topLevel', 'connection']
+]);
+
+function ChangeCard({change, renderBlock, labels, onLocate, location}: {
+    change: BlockChange; renderBlock: ProjectBlockRenderer; labels: typeof en;
+    onLocate?: (version: Version) => void; location?: {version: Version; status: LocationStatus};
+}) {
+    const [withContext, setWithContext] = useState(false);
+    const {sync, toggle} = usePreviewSync(labels === en ? 'en' : 'ja');
+    const notes = [...new Set(change.fields.map(field => labels[propertyLabels.get(field) ?? 'properties']))];
+    const name = (change.after ?? change.before)!.target.name;
+    return <article className={`twgit-block-diff-card twgit-block-diff-${change.kind}`}>
+        <header>
+            <h3><span>{labels[change.kind]}</span> {name}</h3>
+            {!!notes.length && <p>{notes.join(' · ')}</p>}
+            {!!change.parts.length && <p className="twgit-block-diff-legend">{labels.partLegend}</p>}
+        </header>
+        <div className="twgit-block-diff-sides">
+            {(['before', 'after'] as const).map(version => <BlockPreview key={version} side={change[version]} title={labels[version]}
+                renderBlock={renderBlock} withContext={withContext} labels={labels} parts={change.parts}
+                onLocate={onLocate && (() => onLocate(version))} version={version} sync={sync}
+                locationStatus={location?.version === version ? location.status : undefined}/>)}
+        </div>
+        {toggle}
+        <label><input type="checkbox" checked={withContext} onChange={event => setWithContext(event.currentTarget.checked)}/> {labels.context}</label>
+    </article>;
+}
+
+const pageSize = 12;
+const empty = {changes: [], unchanged: 0, otherChanges: false};
+
+export function ProjectSourceBlockDiff({patch, beforeSource, renderBlock, locateBlock, locale = 'en'}: ProjectSourceBlockDiffProps) {
+    const labels = locale.startsWith('ja') ? ja : en;
+    const result = useMemo(() => {
+        try {
+            const projects = readProjectSourceDiff(patch, beforeSource);
+            return projects ? compareProjectBlocks(...projects) : empty;
+        } catch {
+            return null;
+        }
+    }, [patch, beforeSource]);
+    const [page, setPage] = useState({result, visible: pageSize});
+    const request = useRef<AbortController>();
+    const [location, setLocation] = useState<{result: typeof result; key: string; version: Version; locator: ProjectBlockLocator; status: LocationStatus}>();
+    useEffect(() => () => request.current?.abort(), [result, locateBlock]);
+    const locate = async (change: BlockChange, version: Version) => {
+        const side = change[version];
+        if (!side || !locateBlock) return;
+        request.current?.abort();
+        const controller = new AbortController();
+        request.current = controller;
+        const selected = {result, key: change.key, version, locator: locateBlock};
+        setLocation({...selected, status: 'locating'});
+        let found = false;
+        try {
+            found = await locateBlock({...side, version, parts: change.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'});
+    };
+    if (!result) return <p role="alert">{labels.invalid}</p>;
+    const visible = page.result === result ? page.visible : pageSize;
+    return <section className="twgit-block-diff" aria-label={labels.title}>
+        <h2>{labels.title} · {result.changes.length}</h2>
+        {result.unchanged > 0 && <p>{labels.omitted(result.unchanged)}</p>}
+        {result.otherChanges && <p>{labels.otherChanges}</p>}
+        {!result.changes.length && <p>{labels.noChanges}</p>}
+        {result.changes.slice(0, visible).map(change => <ChangeCard key={change.key} change={change} renderBlock={renderBlock} labels={labels}
+            onLocate={locateBlock && (version => void locate(change, version))}
+            location={location?.result === result && location.locator === locateBlock && location.key === change.key ? location : undefined}/>)}
+        {visible < result.changes.length && <button type="button" onClick={() => setPage({result, visible: visible + pageSize})}>{labels.more}</button>}
+    </section>;
+}