@kubohiroya/turbowarp-plus-editor-project-folder 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/session.d.ts CHANGED
@@ -41,8 +41,36 @@ export interface FolderHost {
41
41
  * changed scripts in place; without it they need the whole project reloaded.
42
42
  */
43
43
  deserializeBlocks?: DeserializeBlocks;
44
+ /**
45
+ * Shows the comparisons in `request` and resolves with the chosen action's id, or `null` when closed.
46
+ * With it, unsaved edits are compared with the folder before the user chooses to replace them.
47
+ */
48
+ compareChanges?(request: ComparisonRequest): Promise<string | null>;
44
49
  };
45
50
  }
51
+ /** A titled comparison of two project.source.json texts; `null` stands for a version that cannot be shown. */
52
+ export type ComparisonSection = {
53
+ title: string;
54
+ before: string | null;
55
+ after: string | null;
56
+ };
57
+ export type ComparisonRequest = {
58
+ title: string;
59
+ description: string;
60
+ notes: string[];
61
+ sections: ComparisonSection[];
62
+ actions: {
63
+ id: string;
64
+ label: string;
65
+ }[];
66
+ closeLabel: string;
67
+ };
68
+ /** The last version loaded or saved, the Editor's edits as Save would write them, and the folder now. */
69
+ export type Comparison = {
70
+ base: string;
71
+ editor: string | null;
72
+ disk: string | null;
73
+ };
46
74
  /**
47
75
  * `ready`: the change can be applied in place: values and positions, or with `deserializeBlocks`, whole scripts. `full`: the change needs the whole project reloaded.
48
76
  * `waiting`: an external write looks incomplete and is checked again. `dirty`, `running` and `busy` hold the change.
@@ -65,6 +93,11 @@ export declare function createFolderSession(vm: FolderVM, host: FolderHost): {
65
93
  /** Identifies the pending project file version, so a host can attempt an automatic apply only once. */
66
94
  readonly pendingVersion: string | null;
67
95
  readonly directory: FileSystemDirectoryHandle | null;
96
+ /**
97
+ * Reads what to compare before unsaved edits are replaced. `editor` is `null` when the edits cannot be
98
+ * written to the folder, and `disk` when the folder's project file cannot be read.
99
+ */
100
+ comparison(): Promise<Comparison | null>;
68
101
  refresh(): Promise<void>;
69
102
  reload(): Promise<boolean>;
70
103
  /**
package/dist/source.d.ts CHANGED
@@ -60,5 +60,10 @@ export type DiskChange = FolderUpdate | 'structure' | 'waiting' | null;
60
60
  export declare function readFolderUpdate(source: FolderSource, previous: FolderUpdate | null): Promise<DiskChange>;
61
61
  export declare function assertFolderUnchanged(source: FolderSource): Promise<void>;
62
62
  export declare const equal: (left: Json | undefined, right: Json | undefined) => boolean;
63
+ /**
64
+ * Applies the edits between `before` and `after` (both from the VM) to the project read from the folder, keeping the
65
+ * fields and order the VM does not know. Saves change only the project file: the stage and sprites keep their names,
66
+ * and the costumes and sounds keep using the asset files already in the folder. Returns `null` without edits.
67
+ */
63
68
  export declare function projectChanges(source: Project, before: Project, after: Project): Project | null;
64
69
  export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-plus-editor-project-folder",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Read and save expanded Scratch project folders in TurboWarp Plus Editor",
5
5
  "type": "module",
6
6
  "license": "MPL-2.0",
package/src/index.ts CHANGED
@@ -2,7 +2,7 @@ import {FolderError} from './source.js';
2
2
  import {createFolderSession} from './session.js';
3
3
  import type {FolderHost, FolderVM, PickerWindow} from './session.js';
4
4
 
5
- export type {FolderHost, FolderVM, OpenResult} from './session.js';
5
+ export type {Comparison, ComparisonRequest, ComparisonSection, FolderHost, FolderVM, OpenResult} from './session.js';
6
6
  export type {ReloadTarget} from './block-reload.js';
7
7
  export type {DeserializeBlocks} from './script-reload.js';
8
8
 
@@ -12,11 +12,16 @@ const messages = {
12
12
  replace: 'Replace the open project and discard its unsaved changes?',
13
13
  opened: 'Project folder opened.', saved: 'Project folder saved.', unchanged: 'No changes to save.',
14
14
  conflict: 'The project folder changed outside the editor or is no longer open. Your edits are still in the editor.',
15
- unsupported: 'This project or edit is outside the folder prototype scope.',
15
+ unsupported: 'This project or edit cannot be saved to a project folder yet.',
16
16
  failed: 'Could not access the project folder.',
17
17
  external: 'External changes detected.', reload: 'Reload from Disk', reloaded: 'Changes loaded from disk.',
18
18
  reloadAll: 'Reload Whole Project', discard: 'Discard Edits and Reload…',
19
19
  discardConfirm: 'Discard your unsaved edits and load the project from the folder?',
20
+ compare: 'Compare and Choose…', compareTitle: 'External changes and your unsaved edits',
21
+ compareDescription: 'The project folder changed while the Editor has unsaved edits. Loading from the folder discards your edits.',
22
+ compareUnsaved: 'Some of your edits are outside what the project folder can save, so they are not shown here.',
23
+ yourEdits: 'Your unsaved edits', diskChanges: 'Changes in the folder',
24
+ keep: 'Keep My Edits', discardLoad: 'Discard Edits and Load from Folder', close: 'Close',
20
25
  dirty: 'You have unsaved edits.', running: 'Stop the project before reloading.',
21
26
  runningAuto: 'The changes load when the project stops.', busy: 'Please wait for the current operation.',
22
27
  waiting: 'Waiting for the external write to finish.',
@@ -27,11 +32,16 @@ const messages = {
27
32
  replace: '未保存の変更を破棄して、別の作品を開きますか?',
28
33
  opened: 'プロジェクトフォルダを開きました。', saved: 'プロジェクトフォルダに保存しました。', unchanged: '保存する変更はありません。',
29
34
  conflict: '外部でフォルダが変更されたか、作品が切り替わりました。編集中の変更はエディターに残っています。',
30
- unsupported: 'この作品または編集はフォルダ編集の試作対象外です。',
35
+ unsupported: 'この作品または編集は、まだプロジェクトフォルダに保存できません。',
31
36
  failed: 'プロジェクトフォルダにアクセスできませんでした。',
32
37
  external: '外部変更あり', reload: 'ディスクから再読み込み', reloaded: 'ディスクの変更を読み込みました。',
33
38
  reloadAll: '作品全体を再読み込み', discard: '編集を破棄して再読み込み…',
34
39
  discardConfirm: '未保存の編集を破棄して、フォルダの作品を読み込みますか?',
40
+ compare: '比較して選ぶ…', compareTitle: '外部の変更と未保存の編集',
41
+ compareDescription: 'Editor に未保存の編集がある間に、プロジェクトフォルダが変更されました。フォルダから読み込むと、未保存の編集は失われます。',
42
+ compareUnsaved: '未保存の編集の一部はプロジェクトフォルダに保存できない種類のため、ここには表示していません。',
43
+ yourEdits: 'あなたの未保存の編集', diskChanges: 'フォルダでの変更',
44
+ keep: '編集を残す', discardLoad: '編集を破棄してフォルダから読み込む', close: '閉じる',
35
45
  dirty: '未保存の編集があります。', running: '作品を停止してから再読み込みできます。',
36
46
  runningAuto: '作品の停止後に反映します。', busy: '処理が終わるまでお待ちください。',
37
47
  waiting: '外部の書き込みが終わるのを待っています。',
@@ -109,6 +119,31 @@ export function mountProjectFolder({vm, document, host, locale = 'en', autoReloa
109
119
  button.textContent = message.reload;
110
120
  notice.append(text, button);
111
121
  document.body.append(notice);
122
+ const compareChanges = host.blockReload.compareChanges?.bind(host.blockReload);
123
+ let comparing = false;
124
+ // Lets the user see their unsaved edits next to the folder's changes before choosing to replace them.
125
+ const compare = async (show: NonNullable<typeof compareChanges>) => {
126
+ if (comparing) return;
127
+ comparing = true;
128
+ try {
129
+ const texts = await session.comparison();
130
+ if (!texts) return;
131
+ const sections = [{title: message.diskChanges, before: texts.base, after: texts.disk}];
132
+ if (texts.editor !== null) sections.unshift({title: message.yourEdits, before: texts.base, after: texts.editor});
133
+ const choice = await show({
134
+ title: message.compareTitle, description: message.compareDescription,
135
+ notes: texts.editor === null ? [message.compareUnsaved] : [], sections,
136
+ actions: [{id: 'keep', label: message.keep}, {id: 'discard', label: message.discardLoad}],
137
+ closeLabel: message.close
138
+ });
139
+ if (choice === 'discard' && session.reloadState === 'dirty') apply(() => session.reloadAll(() => true));
140
+ } catch (error) {
141
+ fail(locale, error);
142
+ } finally {
143
+ comparing = false;
144
+ renderReload();
145
+ }
146
+ };
112
147
  let settle: number | undefined;
113
148
  let autoTried: string | null = null;
114
149
  let observed: FileSystemDirectoryHandle | null = null;
@@ -130,7 +165,8 @@ export function mountProjectFolder({vm, document, host, locale = 'en', autoReloa
130
165
  notice.hidden = !state;
131
166
  button.hidden = !kind;
132
167
  button.disabled = !['ready', 'full', 'dirty'].includes(state ?? '');
133
- const action = state === 'dirty' ? message.discard : kind === 'full' ? message.reloadAll : message.reload;
168
+ const action = state === 'dirty' ? (compareChanges ? message.compare : message.discard) :
169
+ kind === 'full' ? message.reloadAll : message.reload;
134
170
  if (button.textContent !== action) button.textContent = action;
135
171
  const detail = !state || state === 'ready' ? '' :
136
172
  state === 'running' && kind === 'partial' && autoReload ? message.runningAuto : message[state];
@@ -166,6 +202,7 @@ export function mountProjectFolder({vm, document, host, locale = 'en', autoReloa
166
202
  const state = session.reloadState;
167
203
  if (state === 'ready') apply(() => session.reload());
168
204
  else if (state === 'full') apply(() => session.reloadAll(() => true));
205
+ else if (state === 'dirty' && compareChanges) void compare(compareChanges);
169
206
  else if (state === 'dirty') apply(() => session.reloadAll(() => view.confirm(message.discardConfirm)));
170
207
  });
171
208
  const unsubscribe = host.blockReload.subscribe(renderReload);
package/src/session.ts CHANGED
@@ -51,9 +51,23 @@ export interface FolderHost {
51
51
  * changed scripts in place; without it they need the whole project reloaded.
52
52
  */
53
53
  deserializeBlocks?: DeserializeBlocks;
54
+ /**
55
+ * Shows the comparisons in `request` and resolves with the chosen action's id, or `null` when closed.
56
+ * With it, unsaved edits are compared with the folder before the user chooses to replace them.
57
+ */
58
+ compareChanges?(request: ComparisonRequest): Promise<string | null>;
54
59
  };
55
60
  }
56
61
 
62
+ /** A titled comparison of two project.source.json texts; `null` stands for a version that cannot be shown. */
63
+ export type ComparisonSection = {title: string; before: string | null; after: string | null};
64
+ export type ComparisonRequest = {
65
+ title: string; description: string; notes: string[]; sections: ComparisonSection[];
66
+ actions: {id: string; label: string}[]; closeLabel: string;
67
+ };
68
+ /** The last version loaded or saved, the Editor's edits as Save would write them, and the folder now. */
69
+ export type Comparison = {base: string; editor: string | null; disk: string | null};
70
+
57
71
  // `stable` turns true once two scans see the same file version, so consecutive writes settle before auto-apply.
58
72
  type Edits = {kind: 'values'; changes: ReturnType<typeof planBlockReload>} |
59
73
  {kind: 'scripts'; changes: ReturnType<typeof planScriptReload>};
@@ -187,6 +201,32 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
187
201
  return typeof pending === 'object' && pending !== null ? pending.update.version : null;
188
202
  },
189
203
  get directory() {return current?.source.directory ?? null;},
204
+ /**
205
+ * Reads what to compare before unsaved edits are replaced. `editor` is `null` when the edits cannot be
206
+ * written to the folder, and `disk` when the folder's project file cannot be read.
207
+ */
208
+ async comparison(): Promise<Comparison | null> {
209
+ const session = current;
210
+ if (!session) return null;
211
+ const decoder = new TextDecoder();
212
+ const base = decoder.decode(session.source.files.get(projectFile));
213
+ let editor: string | null;
214
+ try {
215
+ const result = projectChanges(session.source.project, session.baseline, snapshot());
216
+ editor = result ? `${JSON.stringify(result, null, 2)}\n` : base;
217
+ } catch (error) {
218
+ if (!(error instanceof FolderError)) throw error;
219
+ editor = null;
220
+ }
221
+ let disk: string | null;
222
+ try {
223
+ const file = await (await session.source.directory.getFileHandle(projectFile)).getFile();
224
+ disk = decoder.decode(new Uint8Array(await file.arrayBuffer()));
225
+ } catch {
226
+ disk = null;
227
+ }
228
+ return current === session ? {base, editor, disk} : null;
229
+ },
190
230
  refresh(): Promise<void> {
191
231
  if (disposed || busy || !current || !host.blockReload) return Promise.resolve();
192
232
  if (scanning) return scanning;
package/src/source.ts CHANGED
@@ -102,7 +102,7 @@ export async function readFolder(directory: FileSystemDirectoryHandle, storage:
102
102
  (embedded.extensionBundles !== undefined && (!Array.isArray(embedded.extensionBundles) || embedded.extensionBundles.length)) ||
103
103
  project.turboWarpPlus !== undefined || project.customFonts !== undefined ||
104
104
  (project.extensionURLs !== undefined && (!isObject(project.extensionURLs) || Object.keys(project.extensionURLs).length))) {
105
- return unsupported('Custom extensions and fonts are outside the prototype scope');
105
+ return unsupported('Custom extensions and fonts are not supported in project folders');
106
106
  }
107
107
  const expected = new Set(['project.json']);
108
108
  const references = new Map<string, {id: string; format: string; type: AssetType; name: string}>();
@@ -210,8 +210,17 @@ export const equal = (left: Json | undefined, right: Json | undefined): boolean
210
210
  keys.every(key => Object.hasOwn(right, key) && equal(left[key], right[key]));
211
211
  };
212
212
 
213
+ // Items that name themselves (monitors, costumes) must be the same item in the folder and in the Editor.
214
+ const sameIdentity = (left: Json, right: Json) => !isObject(left) || !isObject(right) ||
215
+ ['id', 'assetId', 'name', 'opcode'].every(key => !Object.hasOwn(left, key) || !Object.hasOwn(right, key) || equal(left[key], right[key]));
213
216
  const applyChanges = (source: Json | undefined, before: Json, after: Json): Json => {
214
217
  if (equal(before, after)) return source === undefined ? after : source;
218
+ // Lists of the same length, such as costumes or a block input, change item by item to keep unknown fields.
219
+ if (Array.isArray(before) && Array.isArray(after) && Array.isArray(source) &&
220
+ before.length === after.length && source.length === after.length &&
221
+ source.every((item, index) => sameIdentity(item, before[index]))) {
222
+ return after.map((item, index) => applyChanges(source[index], before[index], item));
223
+ }
215
224
  if (!isObject(before) || !isObject(after)) return after;
216
225
  const result: JsonObject = Object.assign(Object.create(null), isObject(source) ? source : {});
217
226
  for (const key of Object.keys(before)) {
@@ -226,31 +235,58 @@ const applyChanges = (source: Json | undefined, before: Json, after: Json): Json
226
235
  return result;
227
236
  };
228
237
 
238
+ const assetNames = (project: Project) => {
239
+ const names = new Set<string>();
240
+ for (const target of project.targets) {
241
+ for (const kind of ['costumes', 'sounds'] as const) {
242
+ const entries = target[kind];
243
+ if (!Array.isArray(entries)) continue;
244
+ for (const entry of entries) if (isObject(entry) && typeof entry.md5ext === 'string') names.add(entry.md5ext);
245
+ }
246
+ }
247
+ return names;
248
+ };
249
+ const customContent = (project: Project) => project.turboWarpPlus !== undefined || project.customFonts !== undefined ||
250
+ (project.extensionURLs !== undefined && (!isObject(project.extensionURLs) || Object.keys(project.extensionURLs).length > 0));
251
+
252
+ /**
253
+ * Applies the edits between `before` and `after` (both from the VM) to the project read from the folder, keeping the
254
+ * fields and order the VM does not know. Saves change only the project file: the stage and sprites keep their names,
255
+ * and the costumes and sounds keep using the asset files already in the folder. Returns `null` without edits.
256
+ */
229
257
  export function projectChanges(source: Project, before: Project, after: Project): Project | null {
258
+ const keys = (project: Project) => project.targets.map(targetKey);
259
+ const beforeKeys = keys(before), afterKeys = keys(after);
260
+ if (beforeKeys.length !== afterKeys.length || !afterKeys.every(key => beforeKeys.includes(key))) {
261
+ return unsupported('Adding, removing or renaming sprites is not saved to a project folder yet');
262
+ }
263
+ const used = assetNames(after), known = assetNames(before);
264
+ if (used.size !== known.size || [...used].some(name => !known.has(name))) {
265
+ return unsupported('Adding or removing costumes and sounds is not saved to a project folder yet');
266
+ }
267
+ if (customContent(after)) return unsupported('Custom extensions and fonts are not saved to a project folder');
268
+ if (equal(before, after)) return null;
269
+ const {targets: sourceTargets, ...sourceOther} = source;
230
270
  const {targets: beforeTargets, ...beforeOther} = before;
231
271
  const {targets: afterTargets, ...afterOther} = after;
232
- if (!equal(beforeOther, afterOther) || !equal(beforeTargets.map(targetKey), afterTargets.map(targetKey))) {
233
- return unsupported('This prototype saves block edits on existing targets only');
234
- }
235
- const edits = new Map<string, Partial<Pick<Target, 'blocks' | 'comments'>>>();
236
- const originalTargets = new Map(source.targets.map(target => [targetKey(target), target]));
237
- for (const [index, target] of afterTargets.entries()) {
238
- const {blocks, comments, ...rest} = target;
239
- const {blocks: priorBlocks, comments: priorComments, ...priorRest} = beforeTargets[index];
240
- if (!equal(rest, priorRest)) return unsupported('This prototype saves block edits on existing targets only');
272
+ const originals = new Map(sourceTargets.map(target => [targetKey(target), target]));
273
+ const previous = new Map(beforeTargets.map(target => [targetKey(target), target]));
274
+ const targets = afterTargets.map(target => {
241
275
  const key = targetKey(target);
242
- const original = originalTargets.get(key);
276
+ const original = originals.get(key);
243
277
  if (!original) return unsupported('The original target could not be identified');
244
- if (!equal(priorBlocks, blocks) || !equal(priorComments, comments)) {
245
- const changes: Partial<Pick<Target, 'blocks' | 'comments'>> = {};
246
- if (!equal(priorBlocks, blocks)) changes.blocks = applyChanges(original.blocks, priorBlocks, blocks);
247
- if (!equal(priorComments, comments)) changes.comments = applyChanges(original.comments, priorComments, comments);
248
- edits.set(key, changes);
249
- }
278
+ return applyChanges(original, previous.get(key)!, target) as Target;
279
+ });
280
+ // The folder keeps its own target order unless the Editor reordered the sprites.
281
+ const order = equal(beforeKeys, afterKeys) ? sourceTargets.map(targetKey) : afterKeys;
282
+ const byKey = new Map(targets.map(target => [targetKey(target), target]));
283
+ const other = applyChanges(sourceOther, beforeOther, afterOther) as JsonObject;
284
+ // Keep the folder's key order, with the targets where they were.
285
+ const result: JsonObject = {};
286
+ for (const key of Object.keys(source)) {
287
+ if (key === 'targets') result.targets = order.map(key => byKey.get(key)!);
288
+ else if (Object.hasOwn(other, key)) result[key] = other[key];
250
289
  }
251
- if (!edits.size) return null;
252
- return {...source, targets: source.targets.map(target => {
253
- const edit = edits.get(targetKey(target));
254
- return edit ? {...target, ...edit} : target;
255
- })};
290
+ for (const key of Object.keys(other)) if (!Object.hasOwn(result, key)) result[key] = other[key];
291
+ return result as Project;
256
292
  }