@kubohiroya/turbowarp-plus-editor-project-folder 0.5.0 → 0.6.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/source.d.ts CHANGED
@@ -12,6 +12,7 @@ type Target = JsonObject & {
12
12
  name: string;
13
13
  };
14
14
  export declare const projectFile = "project.source.json";
15
+ export declare const manifestFile = "sb3-source.json";
15
16
  export declare class FolderError extends Error {
16
17
  code: 'conflict' | 'unsupported';
17
18
  constructor(code: FolderError['code'], detail?: string);
@@ -49,6 +50,8 @@ export type FolderSource = FolderFiles & {
49
50
  projectText: string;
50
51
  storageAssets: Map<string, Asset>;
51
52
  };
53
+ export declare const fileVersion: (file: File) => string;
54
+ export declare const assetTypeFor: (storage: Storage, kind: "costumes" | "sounds", format: string) => AssetType;
52
55
  export declare const assetKey: (type: AssetType, id: string, format: string) => string;
53
56
  export declare function readFolder(directory: FileSystemDirectoryHandle, storage: Storage): Promise<FolderSource>;
54
57
  export type FolderUpdate = {
@@ -60,10 +63,18 @@ export type DiskChange = FolderUpdate | 'structure' | 'waiting' | null;
60
63
  export declare function readFolderUpdate(source: FolderSource, previous: FolderUpdate | null): Promise<DiskChange>;
61
64
  export declare function assertFolderUnchanged(source: FolderSource): Promise<void>;
62
65
  export declare const equal: (left: Json | undefined, right: Json | undefined) => boolean;
66
+ /** The asset files a project refers to, by file name, with the kind of list that refers to each. */
67
+ export declare const projectAssets: (project: Project) => Map<string, "costumes" | "sounds">;
68
+ /** Runtime ids of the targets, in the order of the project's `targets`, so a renamed sprite stays the same sprite. */
69
+ export type TargetIdentity = {
70
+ before: readonly string[];
71
+ after: readonly string[];
72
+ };
63
73
  /**
64
74
  * 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.
75
+ * fields and order the VM does not know. Sprites are matched by `identity` (by name without it): a sprite with the
76
+ * same id keeps its folder entry under a new name, and added or removed sprites are added or removed. The asset files
77
+ * the result needs are the caller's to write. Returns `null` without edits.
67
78
  */
68
- export declare function projectChanges(source: Project, before: Project, after: Project): Project | null;
79
+ export declare function projectChanges(source: Project, before: Project, after: Project, identity?: TargetIdentity): Project | null;
69
80
  export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-plus-editor-project-folder",
3
- "version": "0.5.0",
3
+ "version": "0.6.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",
@@ -30,10 +30,13 @@
30
30
  },
31
31
  "scripts": {
32
32
  "build": "vite build && tsc -p tsconfig.json",
33
- "test": "npm run build && node --test",
34
- "prepack": "npm run build"
33
+ "test": "npm run build && node --test test/*.test.js",
34
+ "prepack": "npm run build",
35
+ "test:browser": "npm run build && node --test test/*.browser.js"
35
36
  },
36
37
  "devDependencies": {
38
+ "@kubohiroya/turbowarp-plus-editor-test-runtime": "0.1.0",
39
+ "@playwright/test": "1.64.1",
37
40
  "typescript": "6.0.3",
38
41
  "vite": "8.3.5"
39
42
  }
package/src/session.ts CHANGED
@@ -1,5 +1,6 @@
1
- import {assetKey, assertFolderUnchanged, FolderError, parseProject, projectChanges, projectFile, readFolder, readFolderUpdate} from './source.js';
2
- import type {Asset, FolderSource, FolderUpdate, Project, Storage} from './source.js';
1
+ import {assetKey, assetTypeFor, assertFolderUnchanged, fileVersion, FolderError, manifestFile, parseProject, projectAssets, projectChanges,
2
+ projectFile, readFolder, readFolderUpdate, unsupported} from './source.js';
3
+ import type {Asset, FolderSource, FolderUpdate, JsonObject, Project, Storage} from './source.js';
3
4
  import {applyBlockReload, planBlockReload} from './block-reload.js';
4
5
  import type {ReloadTarget} from './block-reload.js';
5
6
  import {applyScriptReload, planScriptReload} from './script-reload.js';
@@ -73,7 +74,7 @@ type Edits = {kind: 'values'; changes: ReturnType<typeof planBlockReload>} |
73
74
  {kind: 'scripts'; changes: ReturnType<typeof planScriptReload>};
74
75
  type PendingUpdate = {update: FolderUpdate; edits: Edits | null; stable: boolean};
75
76
  type Pending = PendingUpdate | 'structure' | 'waiting';
76
- type Session = {source: FolderSource; baseline: Project; stage: object; pending: Pending | null};
77
+ type Session = {source: FolderSource; baseline: Project; ids: string[] | undefined; stage: object; pending: Pending | null};
77
78
  /**
78
79
  * `ready`: the change can be applied in place: values and positions, or with `deserializeBlocks`, whole scripts. `full`: the change needs the whole project reloaded.
79
80
  * `waiting`: an external write looks incomplete and is checked again. `dirty`, `running` and `busy` hold the change.
@@ -84,6 +85,8 @@ export type ReloadKind = 'partial' | 'full' | null;
84
85
  export type OpenResult = 'opened' | 'cancelled';
85
86
  export type SaveResult = 'saved' | 'unchanged';
86
87
 
88
+ type VMAsset = {assetId: string; dataFormat: string; data?: Uint8Array};
89
+
87
90
  export function createFolderSession(vm: FolderVM, host: FolderHost) {
88
91
  let current: Session | null = null;
89
92
  let busy = false;
@@ -91,6 +94,53 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
91
94
  let revision = 0;
92
95
  let scanning: Promise<void> | null = null;
93
96
  const snapshot = () => parseProject(vm.toJSON(undefined, {allowOptimization: false}));
97
+ type RuntimeTarget = {id?: string; isStage: boolean; isOriginal: boolean; getName(): string; sprite?: {
98
+ costumes?: readonly {asset?: VMAsset}[]; sounds?: readonly {asset?: VMAsset}[];
99
+ }};
100
+ const runtimeTargets = () => (vm.runtime.targets ?? []) as readonly RuntimeTarget[];
101
+ // Runtime ids in the order of the project's targets, so a renamed sprite is still the same sprite.
102
+ const identify = (project: Project): string[] | undefined => {
103
+ const ids = new Map<string, string>();
104
+ for (const target of runtimeTargets()) {
105
+ if (target.isOriginal && target.id) ids.set(target.isStage ? 'stage' : `sprite:${target.getName()}`, target.id);
106
+ }
107
+ const result = project.targets.map(target => ids.get(target.isStage ? 'stage' : `sprite:${target.name}`));
108
+ return result.every((id): id is string => id !== undefined) ? result : undefined;
109
+ };
110
+ const identity = (session: Session, edited: Project) => {
111
+ const after = identify(edited);
112
+ return session.ids && after ? {before: session.ids, after} : undefined;
113
+ };
114
+ // Writes a whole file and, for a file the folder already had, checks the folder before the write takes effect.
115
+ // A new asset file is empty until then, so it is checked by the writes that follow it instead.
116
+ const writeChecked = async (session: Session, handle: FileSystemFileHandle, data: Uint8Array, existing: boolean) => {
117
+ const options = (existing ? {mode: 'exclusive'} : {}) as FileSystemCreateWritableOptions;
118
+ const writable = await handle.createWritable(options);
119
+ try {
120
+ await writable.write(data as Uint8Array<ArrayBuffer>);
121
+ if (existing) await assertFolderUnchanged(session.source);
122
+ active(session);
123
+ await writable.close();
124
+ } catch (error) {
125
+ await writable.abort().catch(() => {});
126
+ throw error;
127
+ }
128
+ };
129
+ const rewrite = async (directory: FileSystemDirectoryHandle, name: string, data: Uint8Array) => {
130
+ const writable = await (await directory.getFileHandle(name)).createWritable();
131
+ await writable.write(data as Uint8Array<ArrayBuffer>);
132
+ await writable.close();
133
+ };
134
+ // The bytes of an asset the Editor holds, such as a costume added since the folder was opened.
135
+ const assetData = (name: string) => {
136
+ for (const target of runtimeTargets()) {
137
+ for (const entry of [...target.sprite?.costumes ?? [], ...target.sprite?.sounds ?? []]) {
138
+ const asset = entry.asset;
139
+ if (asset && `${asset.assetId}.${asset.dataFormat}` === name && asset.data) return asset.data;
140
+ }
141
+ }
142
+ return null;
143
+ };
94
144
  const changed = () => {revision++;};
95
145
  const loaded = () => {current = null;};
96
146
  vm.runtime.on('PROJECT_LOADED', loaded);
@@ -135,7 +185,8 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
135
185
  }
136
186
  if (disposed || !stage || vm.runtime.getTargetForStage() !== stage) return 'cancelled';
137
187
  host.onOpened(directory.name);
138
- current = {source, stage, baseline: snapshot(), pending: null};
188
+ const baseline = snapshot();
189
+ current = {source, stage, baseline, ids: identify(baseline), pending: null};
139
190
  vm.renderer?.draw();
140
191
  return 'opened';
141
192
  } finally {
@@ -212,7 +263,8 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
212
263
  const base = decoder.decode(session.source.files.get(projectFile));
213
264
  let editor: string | null;
214
265
  try {
215
- const result = projectChanges(session.source.project, session.baseline, snapshot());
266
+ const edited = snapshot();
267
+ const result = projectChanges(session.source.project, session.baseline, edited, identity(session, edited));
216
268
  editor = result ? `${JSON.stringify(result, null, 2)}\n` : base;
217
269
  } catch (error) {
218
270
  if (!(error instanceof FolderError)) throw error;
@@ -262,6 +314,7 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
262
314
  throw error;
263
315
  }
264
316
  session.baseline = snapshot();
317
+ session.ids = identify(session.baseline);
265
318
  session.source.project = pending.update.project;
266
319
  session.source.files.set(projectFile, pending.update.bytes);
267
320
  session.source.versions.set(projectFile, pending.update.version);
@@ -304,30 +357,86 @@ export function createFolderSession(vm: FolderVM, host: FolderHost) {
304
357
  try {
305
358
  const saveRevision = revision;
306
359
  const edited = snapshot();
307
- const result = projectChanges(session.source.project, session.baseline, edited);
360
+ const ids = identify(edited);
361
+ const result = projectChanges(session.source.project, session.baseline, edited, identity(session, edited));
308
362
  await assertFolderUnchanged(session.source);
309
363
  active(session);
310
364
  if (!result) {
311
365
  if (revision === saveRevision) host.onSaved();
312
366
  return 'unchanged';
313
367
  }
368
+ const {source} = session;
369
+ // New asset files first, then the manifest and the project file, then the files nothing refers to.
370
+ // A failure part way leaves every file the manifest and the project file refer to in the folder.
371
+ const needed = projectAssets(result);
372
+ const added = new Map<string, Uint8Array>();
373
+ for (const [name, kind] of needed) {
374
+ if (source.bytes.has(name)) continue;
375
+ const data = assetData(name);
376
+ if (!data) return unsupported(`The data of ${name} is not in the Editor`);
377
+ const [id, format] = name.split('.');
378
+ const asset = vm.runtime.storage.createAsset(assetTypeFor(vm.runtime.storage, kind, format), format, data.slice(), null, true);
379
+ if (asset.assetId !== id) return unsupported(`Asset hash mismatch: ${name}`);
380
+ added.set(name, data);
381
+ }
382
+ const removed = [...source.bytes.keys()].filter(name => !needed.has(name));
383
+ const encoder = new TextEncoder();
384
+ let manifest: Uint8Array | null = null;
385
+ if (added.size || removed.length) {
386
+ const value = JSON.parse(new TextDecoder().decode(source.files.get(manifestFile))) as JsonObject;
387
+ const entries = (value.archiveEntries as string[]).filter(name => !removed.includes(name));
388
+ value.archiveEntries = [...entries, ...added.keys()];
389
+ manifest = encoder.encode(`${JSON.stringify(value, null, 2)}\n`);
390
+ }
391
+ const assets = await source.directory.getDirectoryHandle('assets');
392
+ const written: string[] = [];
393
+ const previousManifest = source.files.get(manifestFile)!;
394
+ let manifestWritten = false;
314
395
  const text = `${JSON.stringify(result, null, 2)}\n`;
315
- const file = await session.source.directory.getFileHandle(projectFile);
316
- const options = {mode: 'exclusive'} as FileSystemCreateWritableOptions;
317
- const writable = await file.createWritable(options);
318
396
  try {
319
- await writable.write(text);
320
- await assertFolderUnchanged(session.source);
321
- active(session);
322
- await writable.close();
397
+ for (const [name, data] of added) {
398
+ const handle = await assets.getFileHandle(name, {create: true});
399
+ written.push(name);
400
+ await writeChecked(session, handle, data, false);
401
+ source.bytes.set(name, data);
402
+ source.versions.set(`assets/${name}`, fileVersion(await handle.getFile()));
403
+ }
404
+ if (manifest) {
405
+ const handle = await source.directory.getFileHandle(manifestFile);
406
+ await writeChecked(session, handle, manifest, true);
407
+ manifestWritten = true;
408
+ source.files.set(manifestFile, manifest);
409
+ source.versions.set(manifestFile, fileVersion(await handle.getFile()));
410
+ }
411
+ await writeChecked(session, await source.directory.getFileHandle(projectFile), encoder.encode(text), true);
323
412
  } catch (error) {
324
- await writable.abort().catch(() => {});
413
+ // Put the folder back as it was, as far as it can be. The checks above keep other tools' files.
414
+ if (manifestWritten) {
415
+ await rewrite(source.directory, manifestFile, previousManifest).catch(() => {});
416
+ source.files.set(manifestFile, previousManifest);
417
+ source.versions.delete(manifestFile);
418
+ }
419
+ for (const name of written) {
420
+ await assets.removeEntry(name).catch(() => {});
421
+ source.bytes.delete(name);
422
+ source.versions.delete(`assets/${name}`);
423
+ }
325
424
  throw error;
326
425
  }
327
- session.source.project = result;
328
- session.source.files.set(projectFile, new TextEncoder().encode(text));
329
- session.source.versions.delete(projectFile);
426
+ source.project = result;
427
+ source.files.set(projectFile, encoder.encode(text));
428
+ source.versions.delete(projectFile);
429
+ for (const name of removed) {
430
+ try {
431
+ await assets.removeEntry(name);
432
+ source.bytes.delete(name);
433
+ source.versions.delete(`assets/${name}`);
434
+ } catch {
435
+ // The file stays; nothing refers to it, and the next save tries again.
436
+ }
437
+ }
330
438
  session.baseline = edited;
439
+ session.ids = ids;
331
440
  session.pending = null;
332
441
  if (current === session && revision === saveRevision) host.onSaved();
333
442
  return 'saved';
package/src/source.ts CHANGED
@@ -4,7 +4,7 @@ export type Project = JsonObject & {targets: Target[]};
4
4
  type Target = JsonObject & {isStage: boolean; name: string};
5
5
 
6
6
  export const projectFile = 'project.source.json';
7
- const manifestFile = 'sb3-source.json';
7
+ export const manifestFile = 'sb3-source.json';
8
8
  const extensionsFile = 'embedded-extensions.json';
9
9
 
10
10
  export class FolderError extends Error {
@@ -61,7 +61,7 @@ type FolderFiles = {
61
61
  export type FolderSource = FolderFiles & {project: Project; projectText: string; storageAssets: Map<string, Asset>};
62
62
 
63
63
  const getFile = async (dir: FileSystemDirectoryHandle, name: string) => (await dir.getFileHandle(name)).getFile();
64
- const fileVersion = (file: File) => `${file.size}:${file.lastModified}`;
64
+ export const fileVersion = (file: File) => `${file.size}:${file.lastModified}`;
65
65
  const fileBytes = async (file: File) => new Uint8Array(await file.arrayBuffer());
66
66
  const readBytes = async (dir: FileSystemDirectoryHandle, name: string) => fileBytes(await getFile(dir, name));
67
67
  const readNames = async (dir: FileSystemDirectoryHandle) => {
@@ -78,6 +78,8 @@ const sameNames = (actual: Set<string>, expected: Iterable<string>) => {
78
78
  return actual.size === expectedNames.size && [...actual].every(name => expectedNames.has(name));
79
79
  };
80
80
 
81
+ export const assetTypeFor = (storage: Storage, kind: 'costumes' | 'sounds', format: string) => kind === 'sounds' ?
82
+ storage.AssetType.Sound : format === 'svg' ? storage.AssetType.ImageVector : storage.AssetType.ImageBitmap;
81
83
  export const assetKey = (type: AssetType, id: string, format: string) => `${type.name}/${id}.${format}`;
82
84
 
83
85
  export async function readFolder(directory: FileSystemDirectoryHandle, storage: Storage): Promise<FolderSource> {
@@ -235,13 +237,23 @@ const applyChanges = (source: Json | undefined, before: Json, after: Json): Json
235
237
  return result;
236
238
  };
237
239
 
238
- const assetNames = (project: Project) => {
239
- const names = new Set<string>();
240
+ /** The asset files a project refers to, by file name, with the kind of list that refers to each. */
241
+ export const projectAssets = (project: Project) => {
242
+ const names = new Map<string, 'costumes' | 'sounds'>();
240
243
  for (const target of project.targets) {
241
244
  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
+ const entries = target[kind] ?? [];
246
+ if (!Array.isArray(entries)) return unsupported('Invalid asset list');
247
+ for (const entry of entries) {
248
+ if (!isObject(entry) || typeof entry.assetId !== 'string' || !/^[a-f0-9]{32}$/u.test(entry.assetId) ||
249
+ typeof entry.dataFormat !== 'string' || entry.md5ext !== `${entry.assetId}.${entry.dataFormat}`) {
250
+ return unsupported('Invalid asset reference');
251
+ }
252
+ const supported = kind === 'sounds' ? /^(wav|mp3)$/u.test(entry.dataFormat) :
253
+ /^(svg|png|bmp|jpg|jpeg|gif)$/u.test(entry.dataFormat);
254
+ if (!supported) return unsupported(`Unsupported asset reference: ${entry.md5ext}`);
255
+ names.set(entry.md5ext, kind);
256
+ }
245
257
  }
246
258
  }
247
259
  return names;
@@ -249,42 +261,48 @@ const assetNames = (project: Project) => {
249
261
  const customContent = (project: Project) => project.turboWarpPlus !== undefined || project.customFonts !== undefined ||
250
262
  (project.extensionURLs !== undefined && (!isObject(project.extensionURLs) || Object.keys(project.extensionURLs).length > 0));
251
263
 
264
+ /** Runtime ids of the targets, in the order of the project's `targets`, so a renamed sprite stays the same sprite. */
265
+ export type TargetIdentity = {before: readonly string[]; after: readonly string[]};
266
+
252
267
  /**
253
268
  * 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.
269
+ * fields and order the VM does not know. Sprites are matched by `identity` (by name without it): a sprite with the
270
+ * same id keeps its folder entry under a new name, and added or removed sprites are added or removed. The asset files
271
+ * the result needs are the caller's to write. Returns `null` without edits.
256
272
  */
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');
273
+ export function projectChanges(source: Project, before: Project, after: Project, identity?: TargetIdentity): Project | null {
274
+ const beforeIds = identity?.before ?? before.targets.map(targetKey);
275
+ const afterIds = identity?.after ?? after.targets.map(targetKey);
276
+ if (beforeIds.length !== before.targets.length || afterIds.length !== after.targets.length) {
277
+ return unsupported('The targets could not be identified');
266
278
  }
279
+ projectAssets(after);
267
280
  if (customContent(after)) return unsupported('Custom extensions and fonts are not saved to a project folder');
268
- if (equal(before, after)) return null;
281
+ if (equal(before, after) && equal([...beforeIds], [...afterIds])) return null;
269
282
  const {targets: sourceTargets, ...sourceOther} = source;
270
283
  const {targets: beforeTargets, ...beforeOther} = before;
271
284
  const {targets: afterTargets, ...afterOther} = after;
272
285
  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 => {
275
- const key = targetKey(target);
276
- const original = originals.get(key);
286
+ const previous = new Map(beforeTargets.map((target, index) => [beforeIds[index], target]));
287
+ const targets = afterTargets.map((target, index) => {
288
+ const prior = previous.get(afterIds[index]);
289
+ if (!prior) return target;
290
+ const original = originals.get(targetKey(prior));
277
291
  if (!original) return unsupported('The original target could not be identified');
278
- return applyChanges(original, previous.get(key)!, target) as Target;
292
+ return applyChanges(original, prior, target) as Target;
279
293
  });
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]));
294
+ // The folder keeps its own target order unless the Editor added, removed or reordered sprites.
295
+ let ordered = targets;
296
+ if (equal([...beforeIds], [...afterIds])) {
297
+ const position = new Map(sourceTargets.map((target, index) => [targetKey(target), index]));
298
+ const place = (index: number) => position.get(targetKey(beforeTargets[index])) ?? index;
299
+ ordered = targets.map((target, index) => ({target, at: place(index)})).sort((a, b) => a.at - b.at).map(entry => entry.target);
300
+ }
283
301
  const other = applyChanges(sourceOther, beforeOther, afterOther) as JsonObject;
284
302
  // Keep the folder's key order, with the targets where they were.
285
303
  const result: JsonObject = {};
286
304
  for (const key of Object.keys(source)) {
287
- if (key === 'targets') result.targets = order.map(key => byKey.get(key)!);
305
+ if (key === 'targets') result.targets = ordered;
288
306
  else if (Object.hasOwn(other, key)) result[key] = other[key];
289
307
  }
290
308
  for (const key of Object.keys(other)) if (!Object.hasOwn(result, key)) result[key] = other[key];