@kubohiroya/turbowarp-plus-editor-project-folder 0.13.0 → 0.14.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/README.ja.md CHANGED
@@ -12,10 +12,25 @@ TurboWarp Plus Editor で sb3-toolchain の作品フォルダ(展開ソース
12
12
  - 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
13
13
  - `host.screenState` を渡すと、Editor の画面状態をフォルダーに保存します。渡すものは workbench の `installProjectScreenState` が返すものです。作品フォルダーは SB3 ではないので、状態は `.tw-plus/workspace.json` に入れます。フォルダーを開くと、作品を読み込む前にこれを読み、`prepareLoad(text)` で渡します。保存時は、作品が変わっていなくても `serialize()` の結果を書きます。保存時刻だけが違うときは書きません。読み書きに失敗しても、開く操作と保存は失敗にしません。セッションは `projectFolder` スライス(ツリーで開いたフォルダーと選択中の項目)も登録します。SB3 から作品フォルダを作るとき、sb3-toolchain(0.26.0 以降)が展開したスナップショットに `.tw-plus/workspace.json` があれば、そのままフォルダーに書くので、作ったフォルダーは同じ画面で開きます。スナップショットにないときは、上書きするフォルダーの古い `workspace.json` を消します。`.tw-plus` のほかのファイルは残します。
14
14
 
15
- ホストは VM、メニューコンポーネント、作品状態を扱うコールバックを渡します。メニューからフォルダを開くには、ブラウザーが File System Access のフォルダ選択に対応している必要があります。ブロック、変数・リスト、スプライトの位置や大きさなどの項目、モニター、組み込みの拡張機能の編集を作品データ(`project.source.json`)に保存し、作品の実行で変わった状態も含みます。スプライトの追加・削除・名前の変更と、コスチューム・音の追加・削除も保存します。新しいアセットのファイルを先に書き、`sb3-source.json` と作品データを書いてから、参照されなくなったアセットのファイルを消します。 [Editor #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) · [Editor #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308)
15
+ ホストは VM、メニューコンポーネント、作品状態を扱うコールバックを渡します。メニューからフォルダを開くには、ブラウザーが File System Access のフォルダ選択に対応しているか、[ブラウザー内の作品フォルダ](#ブラウザー内の作品フォルダ)を使える必要があります。ブロック、変数・リスト、スプライトの位置や大きさなどの項目、モニター、組み込みの拡張機能の編集を作品データ(`project.source.json`)に保存し、作品の実行で変わった状態も含みます。スプライトの追加・削除・名前の変更と、コスチューム・音の追加・削除も保存します。新しいアセットのファイルを先に書き、`sb3-source.json` と作品データを書いてから、参照されなくなったアセットのファイルを消します。 [Editor #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) · [Editor #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308)
16
16
 
17
17
  システムフォントと Web フォントの参照は作品データに保持し、埋め込みフォントは `assets/` に保存します。 [Editor #495](https://github.com/kubohiroya/turbowarp-plus-editor/issues/495)
18
18
 
19
+ ## ブラウザー内の作品フォルダ
20
+
21
+ Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)がありません。これらのブラウザーでは、作品フォルダをブラウザーの中の保存領域(OPFS、Origin Private File System)に置きます。読み書きの処理はデバイス上のフォルダと同じです。 [Editor #660](https://github.com/kubohiroya/turbowarp-plus-editor/issues/660)
22
+
23
+ - `mountProjectFolder` の `browserStorage` で使い方を選びます。
24
+ - `fallback`(既定):フォルダ選択がないブラウザーでだけ使います。**プロジェクトフォルダを開く…** はブラウザー内の作品フォルダの一覧を開き、`createFromSnapshot` は新しい作品フォルダの名前を尋ねます(`title` で名前の初期値を渡せます)。
25
+ - `always`:フォルダ選択があるブラウザーでも使います。ファイルメニューに **ブラウザー内のプロジェクトフォルダを開く…** を足し、`projectFolderActions(vm).openBrowser` でも開けます。
26
+ - `off`:使いません。
27
+ - 一覧のダイアログでは、作品フォルダを開く、ZIP で書き出す、削除することができます。保存領域の使用量と、ブラウザーが消さずに残すか(`persisted`)も表示します。閉じるボタンは X のアイコンで、名前は表示の言語に合わせます。
28
+ - 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git の管理対象には入りません。`projectPath` を指定すると、リポジトリのルートの下の作品フォルダ(例:`project`)を開けます。
29
+ - 同じ作品フォルダへの保存は、`navigator.locks` で作品ごとに排他します。WebKit は `createWritable({mode: 'exclusive'})` を重ねても拒否しないので、タブ間の排他はロックで行います。保存すると一覧の更新時刻が変わります。
30
+ - `openBrowserProjects(window)` は一覧・作成・削除・保存領域の状態を扱う口です。`chooseBrowserProject` は一覧のダイアログを、`exportBrowserProject` と `zipDirectory` は ZIP の書き出しを、ホストが直接使うためのものです。ZIP は圧縮せず、名前を UTF-8 で書きます。
31
+
32
+ ブラウザーの中の作品フォルダは、サイトのデータを消したときや、しばらくサイトを使わなかったときに、ブラウザーが消すことがあります(Safari では 7 日間)。最初の作品フォルダを作るときに `navigator.storage.persist()` を求めますが、保証にはなりません。ZIP で書き出すか、Git で GitHub に送って残すようにダイアログで案内します。
33
+
19
34
  ## ブロックパレットの設定
20
35
 
21
36
  TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`.tw-plus/workspace.json`)に保存するようになりました。この節の形式 2 の読み書きは、それ以前に作られた作品フォルダのために残しています。
@@ -61,7 +76,7 @@ TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`
61
76
 
62
77
  ## 開発
63
78
 
64
- Node.js 26 で `npm ci` と `npm test` を実行します。Vite で JavaScript、TypeScript で型宣言を生成します。ホストとの接続検証には `npm pack` で作る tarball を使います。`npm run test:browser` は、最小 editor runtime(`@kubohiroya/turbowarp-plus-editor-test-runtime`)の上で、フォルダの外部変更と本物の VM・ワークスペースとの結合を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor のビルドは要りません。フォルダの一覧も、React 16.14 で実際の一時フォルダを表示して試します。`TWPF_EXPLORER_SCREENSHOT` にファイルのパスを入れると、その画面を保存します。
79
+ Node.js 26 で `npm ci` と `npm test` を実行します。Vite で JavaScript、TypeScript で型宣言を生成します。ホストとの接続検証には `npm pack` で作る tarball を使います。`npm run test:browser` は、最小 editor runtime(`@kubohiroya/turbowarp-plus-editor-test-runtime`)の上で、フォルダの外部変更と本物の VM・ワークスペースとの結合を Chromium で試します。Editor が固定する VM と Scratch Blocks を使い、Editor のビルドは要りません。フォルダの一覧も、React 16.14 で実際の一時フォルダを表示して試します。`TWPF_EXPLORER_SCREENSHOT` にファイルのパスを入れると、その画面を保存します。ブラウザー内の作品フォルダは、フォルダ選択を外した Chromium と WebKit で、作成・保存・開き直し・ZIP の書き出し・削除を試します。WebKit は `npx playwright install webkit` で入れます。ZIP の単体テストと書き出しの確認には `python3` の `zipfile` を使います。
65
80
 
66
81
  Editor のヘッドレス統合テストは実ディスク上のフォルダを使い、選択画面の操作を差し替えます。OS のフォルダ選択画面を確認するときは、使い捨ての sb3-toolchain v1 作品を **ファイル → プロジェクトフォルダを開く…** から選び、読み書きを許可します。標準ブロックを変更し、**ファイル → プロジェクトフォルダに保存** を選びます。選んだフォルダの `project.source.json` が更新されたことを確かめ、同じフォルダを開き直して編集が反映されることを確認します。
67
82
 
package/README.md CHANGED
@@ -12,12 +12,27 @@ This package opens and saves sb3-toolchain project folders (source formats 1 and
12
12
  - The mounted session's `directory` is the folder the loaded project came from. It becomes `null` once another project loads or the folder is detached, so a host can tell projects apart by it.
13
13
  - `host.screenState` keeps the Editor's screen state in the folder, as the workbench's `installProjectScreenState` provides it. A project folder is not an SB3, so the state goes into `.tw-plus/workspace.json`. Opening the folder reads it and passes it with `prepareLoad(text)` before the project loads. Saving writes `serialize()`, even when the project itself is unchanged, and skips the write when only the save time differs. A failure to read or write it never fails the open or the save. The session also registers the `projectFolder` slice: the expanded folders and the selected entry of the explorer. When a folder is created from an SB3, a `.tw-plus/workspace.json` in the snapshot sb3-toolchain (0.26.0 or later) unpacked is written into the folder as it is, so the new folder opens with the same screen. A snapshot without one removes the old `workspace.json` of the folder it overwrites, and keeps the other files in `.tw-plus`.
14
14
 
15
- The host supplies the VM, menu components, and project state callbacks. The browser must support the File System Access picker for the built-in open command. Save writes block, variable, list, sprite property, monitor and built-in extension edits to the project file, including state that changes while the project runs. Sprites can be added, removed and renamed, and costumes and sounds added or removed: new asset files are written first, then `sb3-source.json` and the project file, and asset files nothing refers to are deleted last. See [Editor issue #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) and [issue #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308).
15
+ The host supplies the VM, menu components, and project state callbacks. The built-in open command needs the File System Access folder picker or [project folders in the browser](#project-folders-in-the-browser). Save writes block, variable, list, sprite property, monitor and built-in extension edits to the project file, including state that changes while the project runs. Sprites can be added, removed and renamed, and costumes and sounds added or removed: new asset files are written first, then `sb3-source.json` and the project file, and asset files nothing refers to are deleted last. See [Editor issue #305](https://github.com/kubohiroya/turbowarp-plus-editor/issues/305) and [issue #308](https://github.com/kubohiroya/turbowarp-plus-editor/issues/308).
16
16
 
17
17
  The project file keeps system and web font references. Embedded font files are saved in `assets/`.
18
18
 
19
19
  Folders can contain embedded extension scripts and custom extension URLs. Opening a folder restores embedded scripts as data URLs and uses the Editor's extension review. Saving preserves unchanged extension files and metadata, and reports when replacing a script removes its recorded source. See [拡張機能](README.ja.md#拡張機能).
20
20
 
21
+ ## Project folders in the browser
22
+
23
+ Safari and Firefox have no folder picker (`showDirectoryPicker`). In these browsers, project folders live in the browser's own storage, the origin private file system (OPFS). They are read and saved the same way as folders on the device. See [Editor issue #660](https://github.com/kubohiroya/turbowarp-plus-editor/issues/660).
24
+
25
+ - `browserStorage` of `mountProjectFolder` chooses how they are used.
26
+ - `fallback` (default): only in browsers without the folder picker. **Open Project Folder…** lists the folders in the browser, and `createFromSnapshot` asks for the name of a new folder (`title` gives the initial name).
27
+ - `always`: also in browsers with the folder picker. The File menu gets **Open Project Folder in This Browser…**, and `projectFolderActions(vm).openBrowser` opens it too.
28
+ - `off`: never.
29
+ - The dialog opens, exports as a ZIP, and deletes the folders. It shows how much storage is used and whether the browser keeps it (`persisted`). Its close button is an X icon named in the display language.
30
+ - A folder lives at `turbowarp-plus/projects/<id>/`, and its name and times at `turbowarp-plus/project-info/<id>.json`, outside the folder, so Git never tracks them. With `projectPath`, the project folder can sit below the repository root, such as `project`.
31
+ - Saves to the same folder are serialized per folder with `navigator.locks`. WebKit does not refuse a second `createWritable({mode: 'exclusive'})`, so the lock is what keeps tabs apart. A save updates the folder's time in the list.
32
+ - `openBrowserProjects(window)` lists, creates and deletes the folders and reports the storage. `chooseBrowserProject` shows the dialog, and `exportBrowserProject` and `zipDirectory` write the ZIP, for hosts that use them directly. The ZIP is stored without compression and names entries in UTF-8.
33
+
34
+ The browser may delete these folders when site data is cleared or the site is not used for a while (seven days in Safari). Creating the first folder asks for `navigator.storage.persist()`, which is not a guarantee. The dialog tells the user to export a ZIP or push to GitHub with Git to keep a copy.
35
+
21
36
  ## Block palette settings
22
37
 
23
38
  TurboWarp Plus Editor now saves block palette settings in its screen state (`.tw-plus/workspace.json`). Reading and writing format 2, described here, stays for project folders made before that.
@@ -55,7 +70,7 @@ Script replacements are checked against the VM before any change, and every targ
55
70
 
56
71
  ## Development
57
72
 
58
- Use Node.js 26, then run `npm ci` and `npm test`. Vite builds the JavaScript library, and TypeScript emits the declarations. `npm pack` creates a tarball for host integration checks. `npm run test:browser` runs the folder's external changes against a real VM and workspace in Chromium on the minimal editor runtime (`@kubohiroya/turbowarp-plus-editor-test-runtime`), with the Editor's pinned VM and Scratch Blocks and without building the Editor. It also renders the explorer with React 16.14 over a real temporary folder; set `TWPF_EXPLORER_SCREENSHOT` to a file path to save a screenshot of it.
73
+ Use Node.js 26, then run `npm ci` and `npm test`. Vite builds the JavaScript library, and TypeScript emits the declarations. `npm pack` creates a tarball for host integration checks. `npm run test:browser` runs the folder's external changes against a real VM and workspace in Chromium on the minimal editor runtime (`@kubohiroya/turbowarp-plus-editor-test-runtime`), with the Editor's pinned VM and Scratch Blocks and without building the Editor. It also renders the explorer with React 16.14 over a real temporary folder; set `TWPF_EXPLORER_SCREENSHOT` to a file path to save a screenshot of it. Project folders in the browser are created, saved, reopened, exported as a ZIP and deleted in Chromium with the folder picker removed and in WebKit; install WebKit with `npx playwright install webkit`. The ZIP unit test and the export check read the archive with Python's `zipfile` (`python3`).
59
74
 
60
75
  The Editor's headless integration test uses an actual disk directory and substitutes the picker interaction. To verify the native picker separately, open a disposable sb3-toolchain v1 project with **File → Open Project Folder…**, accept read/write access, edit a standard block, and select **File → Save to Project Folder**. Check that `project.source.json` changed in the chosen directory and reopen the same folder to confirm the edit.
61
76
 
@@ -0,0 +1,20 @@
1
+ import type { BrowserProject, BrowserProjects } from './browser-projects.js';
2
+ /** A file name for the exported ZIP that every OS accepts. */
3
+ export declare function zipFileName(title: string): string;
4
+ /** Saves the stored folder of `project` as a ZIP through the browser's download. */
5
+ export declare function exportBrowserProject(document: Document, projects: BrowserProjects, project: BrowserProject): Promise<void>;
6
+ export type BrowserProjectChoice = {
7
+ project: BrowserProject;
8
+ directory: FileSystemDirectoryHandle;
9
+ };
10
+ /**
11
+ * Shows the project folders kept in this browser. With `purpose: 'open'` the user picks one; with `'create'` the user
12
+ * names a new empty one. Resolves with the chosen folder, or `null` when the dialog closes without one.
13
+ */
14
+ export declare function chooseBrowserProject({ document, projects, locale, purpose, title }: {
15
+ document: Document;
16
+ projects: BrowserProjects;
17
+ locale?: string;
18
+ purpose: 'open' | 'create';
19
+ title?: string;
20
+ }): Promise<BrowserProjectChoice | null>;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Project folders kept in the browser's origin private file system (OPFS). They let browsers without the folder
3
+ * picker, such as Safari and Firefox, open and save project folders. The folders live only in this browser, so the
4
+ * browser may delete them; a user keeps a copy by exporting a ZIP or pushing to GitHub.
5
+ *
6
+ * Layout under the OPFS root:
7
+ * turbowarp-plus/projects/<id>/ the folder (a project folder, or a repository with the project inside)
8
+ * turbowarp-plus/project-info/<id>.json its title and times, kept outside the folder so Git never sees them
9
+ */
10
+ export interface BrowserProject {
11
+ id: string;
12
+ title: string;
13
+ /** The project folder inside the stored folder, such as `project` in a repository, or `''` for the folder itself. */
14
+ projectPath: string;
15
+ createdAt: number;
16
+ updatedAt: number;
17
+ }
18
+ export interface BrowserStorageState {
19
+ usage?: number;
20
+ quota?: number;
21
+ persisted: boolean;
22
+ }
23
+ export interface BrowserProjects {
24
+ list(): Promise<BrowserProject[]>;
25
+ create(title: string, options?: {
26
+ projectPath?: string;
27
+ }): Promise<BrowserProject & {
28
+ root: FileSystemDirectoryHandle;
29
+ directory: FileSystemDirectoryHandle;
30
+ }>;
31
+ /** The stored folder, or `null` when it was deleted. */
32
+ root(id: string): Promise<FileSystemDirectoryHandle | null>;
33
+ /** The project folder of the entry, `projectPath` inside its stored folder. */
34
+ directory(id: string): Promise<FileSystemDirectoryHandle | null>;
35
+ /** The entry that holds `handle`, or `null` when it is not in the browser's storage. */
36
+ find(handle: FileSystemHandle): Promise<BrowserProject | null>;
37
+ touch(id: string): Promise<void>;
38
+ rename(id: string, title: string): Promise<void>;
39
+ remove(id: string): Promise<void>;
40
+ storage(): Promise<BrowserStorageState>;
41
+ /** Asks the browser to keep the storage. The browser may still say no. */
42
+ persist(): Promise<boolean>;
43
+ /** Runs `run` while no other tab of this origin works on the same entry. */
44
+ exclusive<T>(id: string, run: () => Promise<T>): Promise<T>;
45
+ }
46
+ /** The browser's project folders, or `null` when the browser has no origin private file system. */
47
+ export declare function openBrowserProjects(view: Window): BrowserProjects | null;
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { BrowserProjects } from './browser-projects.js';
1
2
  import type { FolderHost, FolderVM } from './session.js';
2
3
  export type { Comparison, ComparisonRequest, ComparisonSection, FolderHost, FolderScreenState, FolderVM, OpenResult } from './session.js';
3
4
  export type { ReloadTarget } from './block-reload.js';
@@ -5,6 +6,11 @@ export { followProjectFolder } from './folder-registry.js';
5
6
  export type { FollowedFolder } from './folder-registry.js';
6
7
  export type { DeserializeBlocks } from './script-reload.js';
7
8
  export { createProjectFolder, projectFolderOverwriteWarning } from './create-folder.js';
9
+ export { openBrowserProjects } from './browser-projects.js';
10
+ export type { BrowserProject, BrowserProjects, BrowserStorageState } from './browser-projects.js';
11
+ export { chooseBrowserProject, exportBrowserProject, zipFileName } from './browser-project-dialog.js';
12
+ export type { BrowserProjectChoice } from './browser-project-dialog.js';
13
+ export { zipDirectory } from './zip.js';
8
14
  type MenuElement = (component: any, props: any, ...children: any[]) => any;
9
15
  interface MenuProps {
10
16
  vm: FolderVM;
@@ -13,16 +19,25 @@ interface MenuProps {
13
19
  MenuSection: any;
14
20
  onRequestClose(): void;
15
21
  }
22
+ /**
23
+ * Where project folders can live, besides folders the user picks on the device.
24
+ * - `fallback` (default): in the browser's private file system when the browser cannot pick folders, as in Safari
25
+ * and Firefox. Open and Save then use those folders.
26
+ * - `always`: also offer the browser's folders where the browser can pick folders.
27
+ * - `off`: only folders on the device.
28
+ */
29
+ export type BrowserStorageMode = 'fallback' | 'always' | 'off';
16
30
  /**
17
31
  * `autoReload` (default true) applies value and position changes without a click when the Editor has no unsaved
18
32
  * edits and the project is stopped. Other changes always wait for the reload command.
19
33
  */
20
- export declare function mountProjectFolder({ vm, document, host, locale, autoReload }: {
34
+ export declare function mountProjectFolder({ vm, document, host, locale, autoReload, browserStorage }: {
21
35
  vm: FolderVM;
22
36
  document: Document;
23
37
  host: FolderHost;
24
38
  locale?: string;
25
39
  autoReload?: boolean;
40
+ browserStorage?: BrowserStorageMode;
26
41
  }): {
27
42
  openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean) => Promise<import("./session.js").OpenResult>;
28
43
  unsavedPaths: () => ReadonlySet<string> | null;
@@ -32,11 +47,18 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
32
47
  status: "saved" | "unchanged";
33
48
  sourceRemoved: string[];
34
49
  }>;
35
- createFromSnapshot({ prepareFiles, collectEdits, directory, current }: {
50
+ /** The folders kept in this browser, when they are offered, for a host that lists or exports them. */
51
+ browserProjects: BrowserProjects | null;
52
+ /**
53
+ * Creates a project folder from a snapshot. `title` names a folder made in the browser, where the user names a
54
+ * new folder instead of picking one on the device.
55
+ */
56
+ createFromSnapshot({ prepareFiles, collectEdits, directory, current, title }: {
36
57
  prepareFiles: () => Promise<ReadonlyMap<string, Uint8Array>>;
37
58
  collectEdits?: () => Promise<void>;
38
59
  directory?: FileSystemDirectoryHandle;
39
60
  current?: () => boolean;
61
+ title?: string;
40
62
  }): Promise<import("./session.js").OpenResult>;
41
63
  /**
42
64
  * The folder the loaded project came from, or `null` once another project loaded or the folder was
@@ -47,6 +69,7 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
47
69
  } | null;
48
70
  export declare function projectFolderActions(vm: FolderVM, locale?: string): {
49
71
  open: () => void;
72
+ openBrowser: (() => void) | undefined;
50
73
  save: (() => void) | undefined;
51
74
  detach: () => void;
52
75
  } | undefined;