@kubohiroya/turbowarp-plus-editor-project-folder 0.6.0 → 0.7.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/src/source.ts CHANGED
@@ -5,7 +5,8 @@ type Target = JsonObject & {isStage: boolean; name: string};
5
5
 
6
6
  export const projectFile = 'project.source.json';
7
7
  export const manifestFile = 'sb3-source.json';
8
- const extensionsFile = 'embedded-extensions.json';
8
+ export const extensionsFile = 'embedded-extensions.json';
9
+ const embeddedReference = 'embedded-extension:';
9
10
 
10
11
  export class FolderError extends Error {
11
12
  code: 'conflict' | 'unsupported';
@@ -57,8 +58,14 @@ type FolderFiles = {
57
58
  files: Map<string, Uint8Array>;
58
59
  directory: FileSystemDirectoryHandle;
59
60
  bytes: Map<string, Uint8Array>;
61
+ extensionBytes: Map<string, Uint8Array>;
62
+ };
63
+ export type FolderSource = FolderFiles & {
64
+ project: Project;
65
+ loadText: string;
66
+ storageAssets: Map<string, Asset>;
67
+ embedded: ExtensionManifest;
60
68
  };
61
- export type FolderSource = FolderFiles & {project: Project; projectText: string; storageAssets: Map<string, Asset>};
62
69
 
63
70
  const getFile = async (dir: FileSystemDirectoryHandle, name: string) => (await dir.getFileHandle(name)).getFile();
64
71
  export const fileVersion = (file: File) => `${file.size}:${file.lastModified}`;
@@ -82,6 +89,177 @@ export const assetTypeFor = (storage: Storage, kind: 'costumes' | 'sounds', form
82
89
  storage.AssetType.Sound : format === 'svg' ? storage.AssetType.ImageVector : storage.AssetType.ImageBitmap;
83
90
  export const assetKey = (type: AssetType, id: string, format: string) => `${type.name}/${id}.${format}`;
84
91
 
92
+ type DataUrlMetadata = {mediaType: string; parameters: string[]; encoding: 'base64' | 'percent'};
93
+ type EmbeddedExtension = JsonObject & DataUrlMetadata & {id: string; path: string};
94
+ type ExtensionBundle = JsonObject & {id: string; members: string[]};
95
+ type ExtensionManifest = JsonObject & {extensions: EmbeddedExtension[]; extensionBundles?: ExtensionBundle[]};
96
+
97
+ const extensionPath = (id: string) => {
98
+ if (!/^[A-Za-z0-9._-]+$/u.test(id)) return unsupported(`Embedded extension ID cannot be used as a filename: ${id}`);
99
+ return `extensions/${id}.js`;
100
+ };
101
+ const validUrlPart = (part: Json | undefined): part is string => typeof part === 'string' && part.length > 0 && !/[;,\r\n]/u.test(part);
102
+ const extensionURLs = (project: Project) => {
103
+ const urls = project.extensionURLs === undefined ? {} : project.extensionURLs;
104
+ if (!isObject(urls) || Object.values(urls).some(url => typeof url !== 'string')) return unsupported('Invalid extensionURLs');
105
+ return urls as Record<string, string>;
106
+ };
107
+ const apiManifestName = (entry: EmbeddedExtension): string | undefined => {
108
+ if (entry.source === undefined) return;
109
+ if (!isObject(entry.source)) return unsupported(`Invalid source for embedded extension: ${entry.id}`);
110
+ const api = entry.source.apiManifest;
111
+ if (api === undefined) return;
112
+ const name = `${entry.id}.manifest.json`;
113
+ if (!isObject(api) || api.path !== `extensions/${name}`) return unsupported(`Invalid API manifest path: ${entry.id}`);
114
+ return name;
115
+ };
116
+ const extensionNames = (entries: EmbeddedExtension[]) => entries.flatMap(entry => {
117
+ const script = `${entry.id}.js`;
118
+ const api = apiManifestName(entry);
119
+ return api === undefined ? [script] : [script, api];
120
+ });
121
+
122
+ function validateExtensions(project: Project, value: JsonObject): ExtensionManifest {
123
+ if (value.formatVersion !== 1 || !Array.isArray(value.extensions)) return unsupported('Invalid embedded extension manifest');
124
+ const urls = extensionURLs(project);
125
+ const ids = new Set<string>();
126
+ for (const entry of value.extensions) {
127
+ if (!isObject(entry) || typeof entry.id !== 'string' || ids.has(entry.id) ||
128
+ entry.path !== extensionPath(entry.id) || !validUrlPart(entry.mediaType) ||
129
+ !Array.isArray(entry.parameters) || !entry.parameters.every(validUrlPart) ||
130
+ (entry.encoding !== 'base64' && entry.encoding !== 'percent') ||
131
+ !Object.hasOwn(urls, entry.id) || urls[entry.id] !== embeddedReference + entry.path) {
132
+ return unsupported('Invalid embedded extension entry or project reference');
133
+ }
134
+ ids.add(entry.id);
135
+ }
136
+ for (const [id, url] of Object.entries(urls)) {
137
+ if (url.startsWith('data:') || (url.startsWith(embeddedReference) && !ids.has(id))) {
138
+ return unsupported(`Invalid embedded extension reference: ${id}`);
139
+ }
140
+ }
141
+ if (value.extensionBundles !== undefined) {
142
+ if (!Array.isArray(value.extensionBundles)) return unsupported('Invalid extensionBundles');
143
+ const bundleIds = new Set<string>();
144
+ const members = new Set<string>();
145
+ for (const bundle of value.extensionBundles) {
146
+ if (!isObject(bundle) || typeof bundle.id !== 'string' || !/^[a-z0-9]+$/u.test(bundle.id) ||
147
+ ids.has(bundle.id) || bundleIds.has(bundle.id) || typeof bundle.name !== 'string' ||
148
+ !bundle.name.trim() || /[\r\n]/u.test(bundle.name) ||
149
+ !Array.isArray(bundle.members) || bundle.members.length < 2) {
150
+ return unsupported('Invalid extension bundle');
151
+ }
152
+ bundleIds.add(bundle.id);
153
+ for (const member of bundle.members) {
154
+ if (typeof member !== 'string' || !/^[a-z0-9]+$/u.test(member) || !ids.has(member) || members.has(member)) {
155
+ return unsupported(`Invalid member of extension bundle: ${bundle.id}`);
156
+ }
157
+ members.add(member);
158
+ }
159
+ }
160
+ }
161
+ return value as ExtensionManifest;
162
+ }
163
+
164
+ function encodeDataUrl(entry: EmbeddedExtension, bytes: Uint8Array): string {
165
+ const metadata = [entry.mediaType, ...entry.parameters].join(';');
166
+ if (entry.encoding === 'percent') {
167
+ const payload = Array.from(bytes, byte => `%${byte.toString(16).padStart(2, '0').toUpperCase()}`).join('');
168
+ return `data:${metadata},${payload}`;
169
+ }
170
+ let binary = '';
171
+ for (let offset = 0; offset < bytes.length; offset += 8192) {
172
+ binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
173
+ }
174
+ return `data:${metadata};base64,${btoa(binary)}`;
175
+ }
176
+
177
+ function decodeDataUrl(id: string, url: string): {metadata: DataUrlMetadata; bytes: Uint8Array} {
178
+ const comma = url.indexOf(',');
179
+ if (comma === -1) return unsupported(`Invalid data URL for embedded extension: ${id}`);
180
+ const [type, ...parameters] = url.slice('data:'.length, comma).split(';');
181
+ const mediaType = type || 'text/plain';
182
+ const base64 = parameters.indexOf('base64');
183
+ if (base64 !== -1) parameters.splice(base64, 1);
184
+ const encoding = base64 === -1 ? 'percent' : 'base64';
185
+ if (!validUrlPart(mediaType) || !parameters.every(validUrlPart) || parameters.includes('base64')) {
186
+ return unsupported(`Invalid data URL metadata for embedded extension: ${id}`);
187
+ }
188
+ const payload = url.slice(comma + 1);
189
+ try {
190
+ if (encoding === 'percent') {
191
+ return {metadata: {mediaType, parameters, encoding}, bytes: new TextEncoder().encode(decodeURIComponent(payload))};
192
+ }
193
+ if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(payload)) throw new Error('Invalid base64');
194
+ const binary = atob(payload.replace(/=+$/u, ''));
195
+ return {metadata: {mediaType, parameters, encoding}, bytes: Uint8Array.from(binary, char => char.charCodeAt(0))};
196
+ } catch {
197
+ return unsupported(`Invalid data URL payload for embedded extension: ${id}`);
198
+ }
199
+ }
200
+
201
+ function hasSandboxedNoticeRequirement(bundle: ExtensionBundle, entry: EmbeddedExtension, bytes: Uint8Array): boolean {
202
+ let requirement;
203
+ if (bundle.buildMode === 'module') {
204
+ const source = entry.source;
205
+ if (isObject(source) && isObject(source.module)) requirement = source.module.unsandboxed;
206
+ } else {
207
+ const script = new TextDecoder().decode(bytes);
208
+ requirement = /^\/\/ Unsandboxed: (.+)\r?$/mu.exec(script)?.[1].trim();
209
+ }
210
+ return requirement === 'required' || requirement === 'optional';
211
+ }
212
+
213
+ export function planExtensionSave(source: FolderSource, project: Project) {
214
+ const urls = {...extensionURLs(project)};
215
+ const entries = new Map(source.embedded.extensions.map(entry => [entry.id, entry]));
216
+ const writes = new Map<string, Uint8Array>();
217
+ const sourceRemoved: string[] = [];
218
+ for (const [id, entry] of entries) {
219
+ if (!Object.hasOwn(urls, id) || (!urls[id].startsWith('data:') && urls[id] !== embeddedReference + entry.path)) entries.delete(id);
220
+ }
221
+ for (const [id, url] of Object.entries(urls)) {
222
+ if (!url.startsWith('data:')) continue;
223
+ const path = extensionPath(id);
224
+ const {metadata, bytes} = decodeDataUrl(id, url);
225
+ const name = `${id}.js`;
226
+ const previous = entries.get(id);
227
+ urls[id] = embeddedReference + path;
228
+ if (!previous || !sameBytes(source.extensionBytes.get(name)!, bytes)) {
229
+ const entry: EmbeddedExtension = {...previous, id, path, ...metadata};
230
+ if (entry.source !== undefined) {
231
+ delete entry.source;
232
+ sourceRemoved.push(id);
233
+ }
234
+ entries.set(id, entry);
235
+ writes.set(name, bytes);
236
+ }
237
+ }
238
+ const embedded: ExtensionManifest = {...source.embedded, extensions: [...entries.values()]};
239
+ if (embedded.extensionBundles) {
240
+ embedded.extensionBundles = embedded.extensionBundles.flatMap(bundle => {
241
+ const members = bundle.members.filter(id => entries.has(id) &&
242
+ // Module bundles need a managed npm module for each member.
243
+ !(bundle.buildMode === 'module' && sourceRemoved.includes(id)));
244
+ if (members.length < 2) return [];
245
+ const updated: ExtensionBundle = {...bundle, members};
246
+ const changed = members.length !== bundle.members.length || members.some(id => writes.has(`${id}.js`));
247
+ if (updated.sandboxedNotice !== undefined && changed && !members.some(id => {
248
+ const name = `${id}.js`;
249
+ return hasSandboxedNoticeRequirement(updated, entries.get(id)!, writes.get(name) ?? source.extensionBytes.get(name)!);
250
+ })) {
251
+ delete updated.sandboxedNotice;
252
+ }
253
+ return [updated];
254
+ });
255
+ }
256
+ const result = project.extensionURLs === undefined ? project : {...project, extensionURLs: urls};
257
+ validateExtensions(result, embedded);
258
+ const names = new Set(extensionNames(embedded.extensions));
259
+ return {project: result, embedded, manifestChanged: !equal(embedded, source.embedded), writes, sourceRemoved,
260
+ removed: [...source.extensionBytes.keys()].filter(name => !names.has(name))};
261
+ }
262
+
85
263
  export async function readFolder(directory: FileSystemDirectoryHandle, storage: Storage): Promise<FolderSource> {
86
264
  const versions = new Map<string, string>();
87
265
  const readEntry = async (dir: FileSystemDirectoryHandle, name: string, prefix = '') => {
@@ -100,12 +278,8 @@ export async function readFolder(directory: FileSystemDirectoryHandle, storage:
100
278
  manifest.assetsDirectory !== 'assets' || !Array.isArray(manifest.archiveEntries)) {
101
279
  return unsupported('Expected an sb3-toolchain v1 folder');
102
280
  }
103
- if (embedded.formatVersion !== 1 || !Array.isArray(embedded.extensions) || embedded.extensions.length ||
104
- (embedded.extensionBundles !== undefined && (!Array.isArray(embedded.extensionBundles) || embedded.extensionBundles.length)) ||
105
- project.turboWarpPlus !== undefined || project.customFonts !== undefined ||
106
- (project.extensionURLs !== undefined && (!isObject(project.extensionURLs) || Object.keys(project.extensionURLs).length))) {
107
- return unsupported('Custom extensions and fonts are not supported in project folders');
108
- }
281
+ if (customContent(project)) return unsupported('Plus extension manifests and custom fonts are not supported in project folders');
282
+ const extensionManifest = validateExtensions(project, embedded);
109
283
  const expected = new Set(['project.json']);
110
284
  const references = new Map<string, {id: string; format: string; type: AssetType; name: string}>();
111
285
  for (const target of project.targets) {
@@ -132,20 +306,27 @@ export async function readFolder(directory: FileSystemDirectoryHandle, storage:
132
306
  }
133
307
  expected.delete('project.json');
134
308
  const [assets, extensions] = await Promise.all([directory.getDirectoryHandle('assets'), directory.getDirectoryHandle('extensions')]);
135
- if (!sameNames(await readNames(assets), expected) || (await readNames(extensions)).size) {
309
+ const scripts = extensionNames(extensionManifest.extensions);
310
+ if (!sameNames(await readNames(assets), expected) || !sameNames(await readNames(extensions), scripts)) {
136
311
  return unsupported('Unexpected or missing source files');
137
312
  }
138
313
  const bytes = new Map(await Promise.all([...expected].map(name => readEntry(assets, name, 'assets/'))));
314
+ const extensionBytes = new Map(await Promise.all(scripts.map(name => readEntry(extensions, name, 'extensions/'))));
315
+ const loadText = extensionManifest.extensions.length ? JSON.stringify({...project, extensionURLs: {
316
+ ...extensionURLs(project),
317
+ ...Object.fromEntries(extensionManifest.extensions.map(entry =>
318
+ [entry.id, encodeDataUrl(entry, extensionBytes.get(`${entry.id}.js`)!)]))
319
+ }}) : projectText;
139
320
  const storageAssets = new Map<string, Asset>();
140
321
  for (const [key, {id, format, type, name}] of references) {
141
322
  const asset = storage.createAsset(type, format, bytes.get(name)!.slice(), null, true);
142
323
  if (asset.assetId !== id) return unsupported(`Asset hash mismatch: ${name}`);
143
324
  storageAssets.set(key, asset);
144
325
  }
145
- return {versions, files, directory, bytes, project, projectText, storageAssets};
326
+ return {versions, files, directory, bytes, extensionBytes, project, loadText, storageAssets, embedded: extensionManifest};
146
327
  }
147
328
 
148
- const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((value, index) => value === b[index]);
329
+ export const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((value, index) => value === b[index]);
149
330
 
150
331
  export type FolderUpdate = {version: string; bytes: Uint8Array; project: Project};
151
332
  export type DiskChange = FolderUpdate | 'structure' | 'waiting' | null;
@@ -159,10 +340,11 @@ export async function readFolderUpdate(source: FolderSource, previous: FolderUpd
159
340
  directory.getDirectoryHandle('assets'), directory.getDirectoryHandle('extensions'), getFile(directory, projectFile)
160
341
  ]);
161
342
  const [assetNames, extensionNames] = await Promise.all([readNames(assets), readNames(extensions)]);
162
- if (!sameNames(assetNames, source.bytes.keys()) || extensionNames.size) return 'structure';
343
+ if (!sameNames(assetNames, source.bytes.keys()) || !sameNames(extensionNames, source.extensionBytes.keys())) return 'structure';
163
344
  const unchanged = await Promise.all([
164
345
  ...[manifestFile, extensionsFile].map(async name => fileVersion(await getFile(directory, name)) === versions.get(name)),
165
- ...[...assetNames].map(async name => fileVersion(await getFile(assets, name)) === versions.get(`assets/${name}`))
346
+ ...[...assetNames].map(async name => fileVersion(await getFile(assets, name)) === versions.get(`assets/${name}`)),
347
+ ...[...extensionNames].map(async name => fileVersion(await getFile(extensions, name)) === versions.get(`extensions/${name}`))
166
348
  ]);
167
349
  if (unchanged.includes(false)) return 'structure';
168
350
  const version = fileVersion(project);
@@ -174,7 +356,9 @@ export async function readFolderUpdate(source: FolderSource, previous: FolderUpd
174
356
  versions.set(projectFile, version);
175
357
  return null;
176
358
  }
177
- return {version, bytes, project: parseProject(new TextDecoder('utf-8', {fatal: true}).decode(bytes))};
359
+ const updated = parseProject(new TextDecoder('utf-8', {fatal: true}).decode(bytes));
360
+ if (!equal(source.project.extensionURLs, updated.extensionURLs)) return 'structure';
361
+ return {version, bytes, project: updated};
178
362
  } catch (error) {
179
363
  // Well-formed JSON outside the partial scope needs a whole reload. Anything else may be a write in
180
364
  // progress, such as truncated JSON or a file replaced between the probe and the read, and is retried.
@@ -186,12 +370,12 @@ export async function assertFolderUnchanged(source: FolderSource) {
186
370
  try {
187
371
  const assets = await source.directory.getDirectoryHandle('assets');
188
372
  const extensions = await source.directory.getDirectoryHandle('extensions');
189
- if (!sameNames(await readNames(assets), source.bytes.keys()) || (await readNames(extensions)).size) throw new FolderError('conflict');
190
- for (const [name, bytes] of source.files) {
191
- if (!sameBytes(await readBytes(source.directory, name), bytes)) throw new FolderError('conflict');
192
- }
193
- for (const [name, bytes] of source.bytes) {
194
- if (!sameBytes(await readBytes(assets, name), bytes)) throw new FolderError('conflict');
373
+ if (!sameNames(await readNames(assets), source.bytes.keys()) ||
374
+ !sameNames(await readNames(extensions), source.extensionBytes.keys())) throw new FolderError('conflict');
375
+ for (const [directory, files] of [[source.directory, source.files], [assets, source.bytes], [extensions, source.extensionBytes]] as const) {
376
+ for (const [name, bytes] of files) {
377
+ if (!sameBytes(await readBytes(directory, name), bytes)) throw new FolderError('conflict');
378
+ }
195
379
  }
196
380
  } catch (error) {
197
381
  if (error instanceof FolderError || (error instanceof DOMException && ['NotFoundError', 'TypeMismatchError'].includes(error.name))) {
@@ -258,8 +442,7 @@ export const projectAssets = (project: Project) => {
258
442
  }
259
443
  return names;
260
444
  };
261
- const customContent = (project: Project) => project.turboWarpPlus !== undefined || project.customFonts !== undefined ||
262
- (project.extensionURLs !== undefined && (!isObject(project.extensionURLs) || Object.keys(project.extensionURLs).length > 0));
445
+ const customContent = (project: Project) => project.turboWarpPlus !== undefined || project.customFonts !== undefined;
263
446
 
264
447
  /** Runtime ids of the targets, in the order of the project's `targets`, so a renamed sprite stays the same sprite. */
265
448
  export type TargetIdentity = {before: readonly string[]; after: readonly string[]};
@@ -277,7 +460,7 @@ export function projectChanges(source: Project, before: Project, after: Project,
277
460
  return unsupported('The targets could not be identified');
278
461
  }
279
462
  projectAssets(after);
280
- if (customContent(after)) return unsupported('Custom extensions and fonts are not saved to a project folder');
463
+ if (customContent(after)) return unsupported('Plus extension manifests and custom fonts are not saved to a project folder');
281
464
  if (equal(before, after) && equal([...beforeIds], [...afterIds])) return null;
282
465
  const {targets: sourceTargets, ...sourceOther} = source;
283
466
  const {targets: beforeTargets, ...beforeOther} = before;
@@ -299,6 +482,12 @@ export function projectChanges(source: Project, before: Project, after: Project,
299
482
  ordered = targets.map((target, index) => ({target, at: place(index)})).sort((a, b) => a.at - b.at).map(entry => entry.target);
300
483
  }
301
484
  const other = applyChanges(sourceOther, beforeOther, afterOther) as JsonObject;
485
+ if (!equal(before.extensionURLs, after.extensionURLs)) {
486
+ // The VM only serializes the URLs it knows. Apply its edits to those entries.
487
+ const urls = applyChanges(source.extensionURLs, extensionURLs(before), extensionURLs(after)) as JsonObject;
488
+ if (after.extensionURLs === undefined && !Object.keys(urls).length) delete other.extensionURLs;
489
+ else other.extensionURLs = urls;
490
+ }
302
491
  // Keep the folder's key order, with the targets where they were.
303
492
  const result: JsonObject = {};
304
493
  for (const key of Object.keys(source)) {
package/tsconfig.json CHANGED
@@ -5,6 +5,7 @@
5
5
  "module": "NodeNext",
6
6
  "moduleResolution": "NodeNext",
7
7
  "types": [],
8
+ "jsx": "react",
8
9
  "strict": true,
9
10
  "verbatimModuleSyntax": true,
10
11
  "declaration": true,
@@ -12,5 +13,5 @@
12
13
  "rootDir": "src",
13
14
  "outDir": "dist"
14
15
  },
15
- "include": ["src/**/*.ts"]
16
+ "include": ["src/**/*.ts", "src/**/*.tsx"]
16
17
  }
package/vite.config.ts CHANGED
@@ -1,10 +1,20 @@
1
- import {defineConfig} from 'vite';
1
+ import {defineConfig, esmExternalRequirePlugin} from 'vite';
2
2
 
3
3
  export default defineConfig({
4
4
  build: {
5
5
  // The pinned Scratch GUI still parses the library with Webpack 4.
6
6
  target: 'es2017',
7
7
  license: {fileName: 'THIRD_PARTY_NOTICES.md'},
8
- lib: {entry: 'src/index.ts', formats: ['es'], fileName: () => 'index.js'}
8
+ lib: {
9
+ entry: {index: 'src/index.ts', explorer: 'src/explorer.tsx'},
10
+ formats: ['es'],
11
+ fileName: (_format, name) => `${name}.js`
12
+ },
13
+ rolldownOptions: {
14
+ // The explorer renders with the host's React; Headless Tree is bundled.
15
+ plugins: [esmExternalRequirePlugin({external: ['react', 'react-dom']})],
16
+ // Code both entries use; it never imports React.
17
+ output: {chunkFileNames: 'shared-[hash].js'}
18
+ }
9
19
  }
10
20
  });