@kubohiroya/turbowarp-plus-editor-project-folder 0.15.1 → 0.17.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
@@ -8,8 +8,10 @@ TurboWarp Plus Editor で sb3-toolchain の作品フォルダ(展開ソース
8
8
 
9
9
  - `mountProjectFolder({vm, document, host})` でワークスペースに接続します。ワークスペースの切り替え時には `dispose()` を呼びます。
10
10
  - `renderProjectFolderMenu(createElement, props)` は既存の開く・保存コマンドをホストのファイルメニューに渡します。
11
- - 接続後の `openDirectory(handle, confirmReplace)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・未保存編集の確認を経て開き、保存先にはその作品フォルダを使います。
11
+ - 選んだフォルダの直下に作品がなく、その中の `project` フォルダが作品フォルダのときは、`project` を作品フォルダとして開きます(Project Starter が作るリポジトリの形)。`project` フォルダの中に `.git` があるときは開きません。どちらも作品でないときは、選んだフォルダのエラーをそのまま出します。
12
+ - 接続後の `openDirectory(handle, confirmReplace, root?)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・`project` フォルダへの切り替え・未保存編集の確認を経て開き、保存先にはその作品フォルダを使います。`root` には、ホストが自分で作品の場所を見つけたときに、ユーザーが選んだフォルダを渡します。省略すると `handle` です。
12
13
  - 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
14
+ - 接続後の `root` は、その作品のためにユーザーが選んだフォルダーです。`directory` そのもの、`directory` を `project` フォルダに持つリポジトリ、またはブラウザーに保存したフォルダでは保存したフォルダー全体を指します。`directory` が `null` のときは `null` です。ブラウザーではフォルダーの親を読めないので、ホストは Git のリポジトリを `root` に結び付けます。
13
15
  - `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
16
 
15
17
  ホストは 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)
@@ -21,9 +23,11 @@ TurboWarp Plus Editor で sb3-toolchain の作品フォルダ(展開ソース
21
23
  Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)がありません。これらのブラウザーでは、作品フォルダをブラウザーの中の保存領域(OPFS、Origin Private File System)に置きます。読み書きの処理はデバイス上のフォルダと同じです。 [Editor #660](https://github.com/kubohiroya/turbowarp-plus-editor/issues/660)
22
24
 
23
25
  - `mountProjectFolder` の `browserStorage` で使い方を選びます。
24
- - `fallback`(既定):フォルダ選択がないブラウザーでだけ使います。**プロジェクトフォルダを開く…** はブラウザー内の作品フォルダの一覧を開き、`createFromSnapshot` は新しい作品フォルダの名前を尋ねます(`title` で名前の初期値を渡せます)。
25
- - `always`:フォルダ選択があるブラウザーでも使います。ファイルメニューに **ブラウザー内のプロジェクトフォルダを開く…** を足し、`projectFolderActions(vm).openBrowser` でも開けます。
26
+ - `fallback`(既定):フォルダ選択がないブラウザー(Safari、Firefox)でだけ使います。ファイルメニューでは **フォルダを開く…** を、このブラウザーでは端末のフォルダを開けない旨を添えて無効にし、ブラウザー内の作品フォルダの一覧を開く **ブラウザーに保存したフォルダを開く…** を出します。`projectFolderActions(vm)` は `deviceFolders: false` を返すので、ホストのメニューでも同じように無効にできます。ホストが `open` を呼んだときは、これまでどおりブラウザー内のフォルダを開きます。`createFromSnapshot` は新しい作品フォルダの名前を尋ねます(`title` で名前の初期値を渡せます)。
27
+ - `always`:フォルダ選択があるブラウザーでも使います。ファイルメニューの **フォルダを開く…** の隣に **ブラウザーに保存したフォルダを開く…** を足し、`projectFolderActions(vm).openBrowser` でも開けます。
26
28
  - `off`:使いません。
29
+ - 作品フォルダをまだ開いていないパネルには、利用できる保存方式の説明と作成ボタンを出します。`always` でフォルダ選択と OPFS の両方が使える場合は2方式、Safari・Firefox ではブラウザー内保存の説明を出します。説明には、ボタンを押した後の操作、外部アプリからの見え方、ブラウザー内の作品を残すための書き出し方法を含めます。
30
+ - `renderProjectFolderExplorer` の `createFolder(location)` には、選んだ保存先(`device` または `browser`)が渡ります。ホストはこれを `createFromSnapshot({location, ...})` に渡します。`location` を省略した場合は従来どおりフォルダ選択を優先し、利用できない保存先を明示した場合は別の保存先に切り替えずエラーにします。
27
31
  - 一覧のダイアログでは、作品フォルダを開く、ZIP で書き出す、削除することができます。保存領域の使用量と、ブラウザーが消さずに残すか(`persisted`)も表示します。閉じるボタンは X のアイコンで、名前は表示の言語に合わせます。
28
32
  - 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git の管理対象には入りません。`projectPath` を指定すると、リポジトリのルートの下の作品フォルダ(例:`project`)を開けます。
29
33
  - 同じ作品フォルダへの保存は、`navigator.locks` で作品ごとに排他します。WebKit は `createWritable({mode: 'exclusive'})` を重ねても拒否しないので、タブ間の排他はロックで行います。保存すると一覧の更新時刻が変わります。
@@ -31,6 +35,8 @@ Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)があり
31
35
 
32
36
  ブラウザーの中の作品フォルダは、サイトのデータを消したときや、しばらくサイトを使わなかったときに、ブラウザーが消すことがあります(Safari では 7 日間)。最初の作品フォルダを作るときに `navigator.storage.persist()` を求めますが、保証にはなりません。ZIP で書き出すか、Git で GitHub に送って残すようにダイアログで案内します。
33
37
 
38
+ 保存先選択の導入は、このパッケージを先に公開し、Editor の依存をその版へ固定してからホストの結線を反映します。切り戻すときは Editor の結線と依存の固定を一緒に戻します。OPFS に作成済みの作品は削除せず、ブラウザー内の一覧から開く・ZIP で書き出す経路を維持します。
39
+
34
40
  ## ブロックパレットの設定
35
41
 
36
42
  TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`.tw-plus/workspace.json`)に保存するようになりました。この節の形式 2 の読み書きは、それ以前に作られた作品フォルダのために残しています。
@@ -54,7 +60,7 @@ TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`
54
60
  `./explorer`(`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`)は、エディターのサイドパネルに置くフォルダのツリーです。[Headless Tree](https://headless-tree.lukasbach.com/) を同梱しています。描画にはホストの React 16.14〜18 を使います(省略可能な peer dependency)。メインの入口は React を使いません。
55
61
 
56
62
  - `ProjectFolderExplorer` は `directory`(作品フォルダまたはリポジトリのルート)を表示します。フォルダは開いたときに読み込み、ファイルより先に並べます。`.git` と `.tw-plus` は表示しません。フォルダーごとの開いたフォルダーと選択中の項目はページの中で保持するので、横のパネルを開き直すと、前と同じツリーに戻ります。矢印キー・Home・End で移動と開閉をします。ファイルで Enter・Space を押すかクリックすると `onOpen({path, name, kind})` を呼びます。props は `directory`、`locale`(`ja…` で日本語、それ以外は英語)、`descriptions` と `marks`(Git の状態: `added`・`modified`・`deleted`・`untracked`、どちらも `directory` からの相対パスがキー)、`onOpen`、`label`(ツリーのアクセシブルな名前)です。読み込めないフォルダは、ツリーの中にメッセージを表示します。
57
- - `renderProjectFolderExplorer(createElement, {vm, locale, marks})` は、`vm` で開いているプロジェクトフォルダのツリーを Editor の横のパネル向けに描きます。説明はフォルダの `project.source.json` と `sb3-source.json` から作り、保存のたびに読み直します。`marks(directory, update)` はそのフォルダの印を追い、止める関数を返します(Git パッケージの `followChangeMarks` など)。フォルダを開いていないときは **プロジェクトフォルダを開く…** を出し、`vm` にプロジェクトフォルダを組み込んでいないときは何も描きません。`followProjectFolder(vm, listener)` は、組み込んだフォルダと開いているディレクトリの変化を知らせます。
63
+ - `renderProjectFolderExplorer(createElement, {vm, locale, marks})` は、`vm` で開いているプロジェクトフォルダのツリーを Editor の横のパネル向けに描きます。説明はフォルダの `project.source.json` と `sb3-source.json` から作り、保存のたびに読み直します。`marks(directory, update)` はそのフォルダの印を追い、止める関数を返します(Git パッケージの `followChangeMarks` など)。フォルダを開いていないときは **フォルダを開く…** を出し、`vm` にプロジェクトフォルダを組み込んでいないときは何も描きません。`followProjectFolder(vm, listener)` は、組み込んだフォルダ・開いているディレクトリ・ユーザーが選んだフォルダ(上の `root`)が変わるたびに `listener(folder, directory, root)` を呼びます。フォルダを開いていないときの `directory` と `root` は `null` です。
58
64
  - 各行には文字色で描いたアイコンが付きます。開いた・閉じたフォルダ、作品データ(`project.source.json`・`sb3-source.json`)、JSON、画像、音、コード(`.js`・`.mjs`・`.ts`)、テキスト(`.md`・`.txt`)、その他のファイルです。画像(`.svg`・`.png`・`.jpg`・`.jpeg`・`.gif`・`.bmp`・`.webp`)は、行が画面に入るとサムネイルを表示します。2 MiB を超えるファイルと読み込めない画像はアイコンのままです。サムネイルは装飾用の `<img>` で、オブジェクト URL は行がなくなると解放します。
59
65
  - `describeProjectFolder(project, locale, {manifest, folder})` は `descriptions` を作ります。`project.source.json`・`sb3-source.json`・`embedded-extensions.json`(形式 2 では `block-palette.json` も)の説明と、各アセットのファイルを使うコスチューム・背景・音を返します。`manifest` から `assetsDirectory` を読みます。`folder` はツリーのルートから見た作品フォルダのパスです。
60
66
 
@@ -92,7 +98,7 @@ TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`
92
98
 
93
99
  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` を使います。
94
100
 
95
- Editor のヘッドレス統合テストは実ディスク上のフォルダを使い、選択画面の操作を差し替えます。OS のフォルダ選択画面を確認するときは、使い捨ての sb3-toolchain v1 作品を **ファイル → プロジェクトフォルダを開く…** から選び、読み書きを許可します。標準ブロックを変更し、**ファイル → プロジェクトフォルダに保存** を選びます。選んだフォルダの `project.source.json` が更新されたことを確かめ、同じフォルダを開き直して編集が反映されることを確認します。
101
+ Editor のヘッドレス統合テストは実ディスク上のフォルダを使い、選択画面の操作を差し替えます。OS のフォルダ選択画面を確認するときは、使い捨ての sb3-toolchain v1 作品を **ファイル → フォルダを開く…** から選び、読み書きを許可します。標準ブロックを変更し、**ファイル → プロジェクトフォルダに保存** を選びます。選んだフォルダの `project.source.json` が更新されたことを確かめ、同じフォルダを開き直して編集が反映されることを確認します。
96
102
 
97
103
  初期実装は MPL-2.0 の [TurboWarp Plus Editor d14d065](https://github.com/kubohiroya/turbowarp-plus-editor/tree/d14d0659f77f37328c855ecfeeae0927d81ae81a/packages/editor-project-folder) から分離しました。
98
104
 
package/README.md CHANGED
@@ -8,8 +8,10 @@ This package opens and saves sb3-toolchain project folders (source formats 1 and
8
8
 
9
9
  - `mountProjectFolder({vm, document, host})` attaches the folder session to a workspace. Call `dispose()` when the workspace is replaced.
10
10
  - `renderProjectFolderMenu(createElement, props)` supplies the existing open and save commands to the host's file menu.
11
- - The mounted session's `openDirectory(handle, confirmReplace)` accepts a directory handle already selected by the host. It uses the same project validation and unsaved-edit confirmation as the file menu. Save still targets the opened folder.
11
+ - A chosen folder with no project of its own opens its `project` folder instead, as in a repository made by Project Starter, when that folder is a valid project folder and has no `.git` of its own. Otherwise the error for the chosen folder stays.
12
+ - The mounted session's `openDirectory(handle, confirmReplace, root?)` accepts a directory handle already selected by the host. It uses the same project validation, `project` fallback and unsaved-edit confirmation as the file menu. Save still targets the opened project folder. `root` names the folder the user chose, for a host that located the project itself; it defaults to `handle`.
12
13
  - 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.
14
+ - The mounted session's `root` is the folder the user chose for that project: `directory` itself, the repository whose `project` folder is `directory`, or, for a folder kept in the browser, its stored folder. It is `null` whenever `directory` is. The browser cannot read a folder's parent, so a host binds a Git repository to `root`.
13
15
  - `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
16
 
15
17
  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).
@@ -23,9 +25,11 @@ Folders can contain embedded extension scripts and custom extension URLs. Openin
23
25
  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
26
 
25
27
  - `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
+ - `fallback` (default): only in browsers without the folder picker (Safari, Firefox). The File menu shows **Open Folder…** as unavailable, with a note that this browser cannot open folders on the device, and offers **Open Folder Saved in This Browser…**, which lists the folders in the browser. `projectFolderActions(vm)` reports this as `deviceFolders: false`, so a host's own menu can do the same; its `open` still falls back to the browser's folders for hosts that call it. `createFromSnapshot` asks for the name of a new folder (`title` gives the initial name).
29
+ - `always`: also in browsers with the folder picker. The File menu gets **Open Folder Saved in This Browser…** next to **Open Folder…**, and `projectFolderActions(vm).openBrowser` opens it too.
28
30
  - `off`: never.
31
+ - Before a folder is open, the explorer explains each available destination and offers its creation button. With `always`, browsers supporting both the picker and OPFS show both choices; Safari and Firefox explain browser storage. The text describes the next step, access from other apps, and how to keep an exported copy.
32
+ - The explorer calls its host's `createFolder(location)` with `device` or `browser`. Forward this to `createFromSnapshot({location, ...})`. Omitting `location` preserves the existing picker-first behavior. An explicitly unavailable destination fails instead of silently switching storage.
29
33
  - 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
34
  - 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
35
  - 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.
@@ -48,7 +52,7 @@ A change to `block-palette.json` outside the Editor is a structural change that
48
52
  The `./explorer` entry (`@kubohiroya/turbowarp-plus-editor-project-folder/explorer`) is a tree of a folder for the Editor's side panel, built on [Headless Tree](https://headless-tree.lukasbach.com/), which is bundled. It renders with the host's React 16.14–18 (an optional peer dependency); the main entry does not use React.
49
53
 
50
54
  - `ProjectFolderExplorer` shows `directory` (a project folder or a repository root). Folders load when expanded and sort before files, and `.git` and `.tw-plus` are hidden. The expanded folders and the selected entry of each folder are kept for the page, so the tree comes back as it was when the side panel shows it again. Arrow keys, Home and End move and expand; Enter, Space or a click on a file calls `onOpen({path, name, kind})`. Props: `directory`, `locale` (`ja…` for Japanese, otherwise English), `descriptions` and `marks` (Git status: `added`, `modified`, `deleted` or `untracked`), both keyed by the path relative to `directory`, `onOpen` and `label` (the tree's accessible name). A folder that cannot be read shows a message in the tree.
51
- - `renderProjectFolderExplorer(createElement, {vm, locale, marks})` renders that explorer on the project folder open for `vm`, for the Editor's side panel, with descriptions from the folder's `project.source.json` and `sb3-source.json` (read again after each save). `marks(directory, update)` follows marks for the directory and returns the function that stops it, such as the Git package's `followChangeMarks`. With no folder open it offers **Open Project Folder…**; it renders nothing while no project folder is mounted for `vm`. `followProjectFolder(vm, listener)` reports the mounted folder and its open directory as they change.
55
+ - `renderProjectFolderExplorer(createElement, {vm, locale, marks})` renders that explorer on the project folder open for `vm`, for the Editor's side panel, with descriptions from the folder's `project.source.json` and `sb3-source.json` (read again after each save). `marks(directory, update)` follows marks for the directory and returns the function that stops it, such as the Git package's `followChangeMarks`. With no folder open it offers **Open Folder…**; it renders nothing while no project folder is mounted for `vm`. `followProjectFolder(vm, listener)` calls `listener(folder, directory, root)` with the mounted folder, its open directory and the folder the user chose for it (`root`, as above) as they change; `directory` and `root` are `null` while no folder is open.
52
56
  - Each row has an icon drawn in the text color: an open or closed folder, project data (`project.source.json`, `sb3-source.json`), JSON, image, sound, code (`.js`, `.mjs`, `.ts`), text (`.md`, `.txt`) or another file. Images (`.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`) show a thumbnail once their row is on screen; files over 2 MiB, and images that cannot be read, keep the icon. Thumbnails are decorative `<img>` elements from object URLs, which are revoked when the row goes away.
53
57
  - `describeProjectFolder(project, locale, {manifest, folder})` builds `descriptions`: what `project.source.json`, `sb3-source.json` and `embedded-extensions.json` (and `block-palette.json` in format 2) are, and which costumes, backdrops and sounds use each asset file. `manifest` supplies `assetsDirectory`; `folder` is the project folder's path under the tree's root.
54
58
 
@@ -72,7 +76,7 @@ Script replacements are checked against the VM before any change, and every targ
72
76
 
73
77
  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`).
74
78
 
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.
79
+ 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 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.
76
80
 
77
81
  The initial source was extracted from [TurboWarp Plus Editor at d14d065](https://github.com/kubohiroya/turbowarp-plus-editor/tree/d14d0659f77f37328c855ecfeeae0927d81ae81a/packages/editor-project-folder) under MPL-2.0.
78
82
 
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import type { ExplorerMutation } from './folder-registry.js';
2
+ import type { ExplorerMutation, ProjectFolderLocation } from './folder-registry.js';
3
3
  import type { Json, Project } from './source.js';
4
4
  import type { FilePreviewRequest, ReadFileBaseline } from './file-preview.js';
5
5
  export type ExplorerMark = 'added' | 'modified' | 'deleted' | 'untracked';
@@ -66,8 +66,8 @@ export type FollowFileStatuses = (directory: FileSystemDirectoryHandle, update:
66
66
  type FolderViewProps = {
67
67
  vm: object;
68
68
  locale?: string;
69
- /** Saves the current project to a local folder. */
70
- createFolder?(): Promise<unknown>;
69
+ /** Saves the current project to the selected storage location. */
70
+ createFolder?(location?: ProjectFolderLocation): Promise<unknown>;
71
71
  marks?: FollowMarks;
72
72
  fileStatuses?: FollowFileStatuses;
73
73
  /** Reports unsaved text edits in open file tabs for the given folder. */
package/dist/explorer.js CHANGED
@@ -1,4 +1,4 @@
1
- import { A as projectFile, C as isObject, F as _asyncIterator, L as _objectSpread2, a as projectFolderOverwriteWarning, d as subscribeExplorerState, f as writeExplorerState, l as readExplorerState, p as FolderError, s as hiddenEntry, t as followProjectFolder, w as manifestFile } from "./shared-cwwWtggC.js";
1
+ import { A as projectFile, C as isObject, F as _asyncIterator, L as _objectSpread2, a as projectFolderOverwriteWarning, d as subscribeExplorerState, f as writeExplorerState, l as readExplorerState, p as FolderError, s as hiddenEntry, t as followProjectFolder, w as manifestFile } from "./shared-h5VGx9Jp.js";
2
2
  import * as React from "react";
3
3
  import { useEffect, useState } from "react";
4
4
  import { createPortal } from "react-dom";
@@ -1463,7 +1463,7 @@ function createFilePreview(directory, documentId, { name, path }, locale, readBa
1463
1463
  status.textContent = message.large;
1464
1464
  return;
1465
1465
  }
1466
- const [bytes, { decodeText, mountTextFile }] = await Promise.all([file.arrayBuffer(), import("./shared-CUZGohh-.js")]);
1466
+ const [bytes, { decodeText, mountTextFile }] = await Promise.all([file.arrayBuffer(), import("./shared-CwQoV7xd.js")]);
1467
1467
  if (disposed) return;
1468
1468
  const content = decodeText(bytes);
1469
1469
  if (content === null) {
@@ -1524,10 +1524,19 @@ var messages = {
1524
1524
  empty: "This folder is empty.",
1525
1525
  noMatches: "No matching files.",
1526
1526
  results: "Matching files",
1527
- noFolder: "Open a project folder to show its files here.",
1528
- open: "Open Project Folder…",
1529
- create: "Create Project Folder",
1527
+ noFolder: "Open a folder to show its files here.",
1528
+ open: "Open Folder…",
1530
1529
  creating: "Creating project folder…",
1530
+ storageIntro: "Save the current project as a folder containing its project data, costumes, sounds and other files.",
1531
+ deviceTitle: "Save to a folder on this device",
1532
+ deviceDescription: "Choose a folder on your computer. You can view its files in Finder or File Explorer and work with them in VS Code or other apps.",
1533
+ deviceNext: "The button opens a folder picker. Choose an empty folder or create a new one there.",
1534
+ deviceCreate: "Choose a Folder and Save…",
1535
+ browserTitle: "Save in this browser",
1536
+ browserDescription: "Enter a name to create a project folder in this site’s storage, without choosing a folder on your computer. Its files are not directly visible in Finder, File Explorer or other apps.",
1537
+ browserRetention: "The project stays in this browser profile on this device. Clearing site data or automatic browser cleanup may delete it. Keep a copy by exporting an SB3 or ZIP, or saving it to GitHub.",
1538
+ browserReopen: "To continue later, use Open Folder Saved in This Browser… in the File menu.",
1539
+ browserCreate: "Name and Save in This Browser…",
1531
1540
  createFailed: "Could not create the project folder.",
1532
1541
  unavailable: "File tabs are unavailable in this editor layout.",
1533
1542
  failed: "This folder could not be read.",
@@ -1563,10 +1572,19 @@ var messages = {
1563
1572
  empty: "このフォルダは空です。",
1564
1573
  noMatches: "該当するファイルはありません。",
1565
1574
  results: "検索結果",
1566
- noFolder: "プロジェクトフォルダを開くと、ここにファイルを表示します。",
1567
- open: "プロジェクトフォルダを開く…",
1568
- create: "プロジェクトフォルダを作成",
1575
+ noFolder: "フォルダを開くと、ここにファイルを表示します。",
1576
+ open: "フォルダを開く…",
1569
1577
  creating: "プロジェクトフォルダを作成しています…",
1578
+ storageIntro: "編集中の作品を、作品データ・コスチューム・音などのファイルをまとめたプロジェクトフォルダとして保存します。",
1579
+ deviceTitle: "端末のフォルダに保存",
1580
+ deviceDescription: "パソコン上のフォルダを選んで保存します。Finder やエクスプローラーでファイルを確認でき、VS Code などの外部アプリでも扱えます。",
1581
+ deviceNext: "ボタンを押すとフォルダ選択画面が開きます。空のフォルダを選ぶか、その画面で新しいフォルダを作成してください。",
1582
+ deviceCreate: "フォルダを選んで保存…",
1583
+ browserTitle: "このブラウザー内に保存",
1584
+ browserDescription: "名前を入力すると、このサイト専用の保存領域にプロジェクトフォルダを作成します。パソコン上のフォルダを選ぶ必要はありません。Finder やエクスプローラー、外部アプリからファイルを直接見ることはできません。",
1585
+ browserRetention: "保存した作品は、この端末のこのブラウザーのプロファイル内に残ります。サイトデータの削除やブラウザーの自動整理で消える場合があります。SB3・ZIP の書き出しや GitHub への保存で、別の場所にも作品を残してください。",
1586
+ browserReopen: "次回は「ファイル」メニューの「ブラウザーに保存したフォルダを開く…」から開けます。",
1587
+ browserCreate: "名前を付けてブラウザー内に保存…",
1570
1588
  createFailed: "プロジェクトフォルダを作成できませんでした。",
1571
1589
  unavailable: "このエディターのレイアウトではファイルをタブで開けません。",
1572
1590
  failed: "このフォルダを読み込めません。",
@@ -1676,9 +1694,18 @@ background:repeating-conic-gradient(rgba(128,128,128,.22) 0 25%,transparent 0 50
1676
1694
  color:inherit;color:color-mix(in srgb,currentColor 78%,transparent);font-size:.75em;line-height:1.4;
1677
1695
  white-space:normal;overflow-wrap:anywhere}
1678
1696
  .${prefix}-status{opacity:.7;font-style:italic;padding-block:.15em}
1679
- .${prefix}-empty{padding:.5em}
1697
+ .${prefix}-empty{padding:.75em;line-height:1.6;overflow-wrap:anywhere}
1680
1698
  .${prefix}-empty p{margin:0 0 .6em}
1681
- .${prefix}-empty button{color:inherit;background:transparent;border:1px solid currentColor;border-radius:4px;padding:.2em .6em;font:inherit;cursor:pointer}`;
1699
+ .${prefix}-storage{padding-block:.8em;border-block-start:1px solid color-mix(in srgb,currentColor 25%,transparent)}
1700
+ .${prefix}-storage h3{margin:0 0 .5em;font-size:1em}
1701
+ .${prefix}-empty button{color:inherit;background:transparent;border:1px solid currentColor;border-radius:4px;padding:.4em .7em;font:inherit;cursor:pointer;white-space:normal;max-width:100%}
1702
+ .${prefix}-storage button{display:inline-flex;align-items:center;gap:.45em;text-align:start;
1703
+ border-radius:.65rem;padding:.55em .9em;background:var(--looks-secondary,#855cd6);
1704
+ border-color:var(--looks-secondary,#855cd6);color:#fff;font-weight:600;line-height:1.4}
1705
+ .${prefix}-storage button:hover:not(:disabled){background:color-mix(in srgb,var(--looks-secondary,#855cd6) 88%,#000)}
1706
+ .${prefix}-storage button:focus-visible{outline:2px solid var(--looks-secondary,#855cd6);outline-offset:3px}
1707
+ .${prefix}-storage button svg{flex:none}
1708
+ .${prefix}-empty button:disabled{opacity:.6;cursor:wait}`;
1682
1709
  var indent = (level) => ({ paddingInlineStart: `${.25 + level * 1.1}em` });
1683
1710
  var page = "M3.5 1.5h6l3 3v10h-9z";
1684
1711
  var corner = "M9.5 1.5v3h3";
@@ -1718,6 +1745,14 @@ var icons = {
1718
1745
  ],
1719
1746
  "file": [page, corner]
1720
1747
  };
1748
+ var storageIcons = {
1749
+ device: icons.folder,
1750
+ browser: [
1751
+ "M2.5 2.5h11a1 1 0 0 1 1 1v9a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1v-9a1 1 0 0 1 1-1z",
1752
+ "M1.5 5.5h13",
1753
+ "M3.5 4h.1M5.5 4h.1"
1754
+ ]
1755
+ };
1721
1756
  var extensionIcons = {
1722
1757
  json: "json",
1723
1758
  svg: "image",
@@ -2540,12 +2575,12 @@ function FolderView({ vm, locale = "en", marks: followMarks, fileStatuses: follo
2540
2575
  const message = messagesFor(locale);
2541
2576
  const [creating, setCreating] = React.useState(false);
2542
2577
  const [createError, setCreateError] = React.useState("");
2543
- const create = async () => {
2578
+ const create = async (location) => {
2544
2579
  if (!createFolder || creating) return;
2545
2580
  setCreating(true);
2546
2581
  setCreateError("");
2547
2582
  try {
2548
- await createFolder();
2583
+ await createFolder(location);
2549
2584
  } catch (_unused5) {
2550
2585
  setCreateError(message.createFailed);
2551
2586
  } finally {
@@ -2635,14 +2670,35 @@ function FolderView({ vm, locale = "en", marks: followMarks, fileStatuses: follo
2635
2670
  }));
2636
2671
  }, [directory, followGit]);
2637
2672
  if (!folder) return null;
2638
- if (!directory) return /* @__PURE__ */ React.createElement("div", { className: `${prefix}-empty` }, /* @__PURE__ */ React.createElement("style", null, css), createFolder ? /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, projectFolderOverwriteWarning(locale)), /* @__PURE__ */ React.createElement("button", {
2639
- type: "button",
2640
- disabled: creating,
2641
- onClick: () => void create()
2642
- }, message.create), creating && /* @__PURE__ */ React.createElement("p", { role: "status" }, message.creating), createError && /* @__PURE__ */ React.createElement("p", { role: "alert" }, createError)) : /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, message.noFolder), /* @__PURE__ */ React.createElement("button", {
2643
- type: "button",
2644
- onClick: () => folder.open(locale)
2645
- }, message.open)));
2673
+ if (!directory) {
2674
+ var _folder$locations;
2675
+ return /* @__PURE__ */ React.createElement("div", { className: `${prefix}-empty` }, /* @__PURE__ */ React.createElement("style", null, css), createFolder ? /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, message.storageIntro), ((_folder$locations = folder.locations) !== null && _folder$locations !== void 0 ? _folder$locations : ["device"]).map((location) => /* @__PURE__ */ React.createElement("section", {
2676
+ key: location,
2677
+ className: `${prefix}-storage`,
2678
+ "data-project-folder-location": location
2679
+ }, /* @__PURE__ */ React.createElement("h3", null, location === "device" ? message.deviceTitle : message.browserTitle), location === "device" ? /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, message.deviceDescription), /* @__PURE__ */ React.createElement("p", null, message.deviceNext), /* @__PURE__ */ React.createElement("p", null, projectFolderOverwriteWarning(locale))) : /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, message.browserDescription), /* @__PURE__ */ React.createElement("p", null, message.browserRetention), /* @__PURE__ */ React.createElement("p", null, message.browserReopen)), /* @__PURE__ */ React.createElement("button", {
2680
+ type: "button",
2681
+ disabled: creating,
2682
+ onClick: () => void create(location)
2683
+ }, /* @__PURE__ */ React.createElement("svg", {
2684
+ viewBox: "0 0 16 16",
2685
+ width: "16",
2686
+ height: "16",
2687
+ fill: "none",
2688
+ stroke: "currentColor",
2689
+ strokeWidth: "1.2",
2690
+ strokeLinecap: "round",
2691
+ strokeLinejoin: "round",
2692
+ "aria-hidden": "true",
2693
+ focusable: "false"
2694
+ }, storageIcons[location].map((d, index) => /* @__PURE__ */ React.createElement("path", {
2695
+ key: index,
2696
+ d
2697
+ }))), /* @__PURE__ */ React.createElement("span", null, location === "device" ? message.deviceCreate : message.browserCreate)))), creating && /* @__PURE__ */ React.createElement("p", { role: "status" }, message.creating), createError && /* @__PURE__ */ React.createElement("p", { role: "alert" }, createError)) : /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, message.noFolder), /* @__PURE__ */ React.createElement("button", {
2698
+ type: "button",
2699
+ onClick: () => folder.open(locale)
2700
+ }, message.open)));
2701
+ }
2646
2702
  const unsavedPaths = new Set((unsaved === null || unsaved === void 0 ? void 0 : unsaved.directory) === directory ? unsaved.paths : void 0);
2647
2703
  if ((fileEdits === null || fileEdits === void 0 ? void 0 : fileEdits.directory) === directory) for (const path of fileEdits.paths) unsavedPaths.add(path);
2648
2704
  return /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement(ProjectFolderExplorer, {
@@ -1,17 +1,24 @@
1
1
  /** The project folder mounted for a VM, as a view of the folder follows it. */
2
2
  export type ExplorerMutation = (guard: () => void) => Promise<void>;
3
+ export type ProjectFolderLocation = 'device' | 'browser';
3
4
  export interface FollowedFolder {
4
5
  readonly directory: FileSystemDirectoryHandle | null;
6
+ /** The folder the user chose for `directory`: itself, or the repository whose `project` folder it is. */
7
+ readonly root?: FileSystemDirectoryHandle | null;
8
+ /** Storage choices available when creating a project folder. */
9
+ readonly locations?: readonly ProjectFolderLocation[];
5
10
  subscribe(listener: () => void): () => void;
6
11
  subscribeEdits(listener: () => void): () => void;
7
12
  unsavedPaths(): ReadonlySet<string> | null;
8
- /** Asks for a folder and opens it, as the File menu's Open Project Folder… does. */
13
+ /** Asks for a folder and opens it, as the File menu's Open Folder… does. */
9
14
  open(locale: string): void;
10
15
  mutate(directory: FileSystemDirectoryHandle, operation: ExplorerMutation): Promise<void>;
11
16
  }
12
17
  export declare function registerFolder(vm: object, folder: FollowedFolder): () => void;
13
18
  /**
14
- * Calls `listener` with the project folder mounted for `vm` and the directory open in it, now and whenever a folder is
15
- * mounted, opened, closed or saved. Returns the function that stops it.
19
+ * Calls `listener` with the project folder mounted for `vm`, the directory open in it and the folder the user chose for
20
+ * it (`root`, the directory itself or the repository that holds it in `project/`), now and whenever a folder is
21
+ * mounted, opened, closed or saved. `directory` and `root` are `null` while no folder is open. Returns the function
22
+ * that stops it.
16
23
  */
17
- export declare function followProjectFolder(vm: object, listener: (folder: FollowedFolder | undefined, directory: FileSystemDirectoryHandle | null) => void): () => void;
24
+ export declare function followProjectFolder(vm: object, listener: (folder: FollowedFolder | undefined, directory: FileSystemDirectoryHandle | null, root: FileSystemDirectoryHandle | null) => void): () => void;
package/dist/index.d.ts CHANGED
@@ -1,9 +1,10 @@
1
+ import type { ProjectFolderLocation } from './folder-registry.js';
1
2
  import type { BrowserProjects } from './browser-projects.js';
2
3
  import type { FolderHost, FolderVM } from './session.js';
3
4
  export type { Comparison, ComparisonRequest, ComparisonSection, FolderHost, FolderScreenState, FolderVM, OpenResult } from './session.js';
4
5
  export type { ReloadTarget } from './block-reload.js';
5
6
  export { followProjectFolder } from './folder-registry.js';
6
- export type { FollowedFolder } from './folder-registry.js';
7
+ export type { FollowedFolder, ProjectFolderLocation } from './folder-registry.js';
7
8
  export type { DeserializeBlocks } from './script-reload.js';
8
9
  export { createProjectFolder, projectFolderOverwriteWarning } from './create-folder.js';
9
10
  export { openBrowserProjects } from './browser-projects.js';
@@ -39,7 +40,7 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
39
40
  autoReload?: boolean;
40
41
  browserStorage?: BrowserStorageMode;
41
42
  }): {
42
- openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean) => Promise<import("./session.js").OpenResult>;
43
+ openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean, root?: FileSystemDirectoryHandle | undefined) => Promise<import("./session.js").OpenResult>;
43
44
  unsavedPaths: () => ReadonlySet<string> | null;
44
45
  readUnsavedFile: (path: string) => Uint8Array<ArrayBufferLike> | null | undefined;
45
46
  subscribeEdits: (listener: () => void) => () => void;
@@ -53,23 +54,32 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
53
54
  * Creates a project folder from a snapshot. `title` names a folder made in the browser, where the user names a
54
55
  * new folder instead of picking one on the device.
55
56
  */
56
- createFromSnapshot({ prepareFiles, collectEdits, directory, current, title }: {
57
+ createFromSnapshot({ prepareFiles, collectEdits, directory, current, title, location }: {
57
58
  prepareFiles: () => Promise<ReadonlyMap<string, Uint8Array>>;
58
59
  collectEdits?: () => Promise<void>;
59
60
  directory?: FileSystemDirectoryHandle;
60
61
  current?: () => boolean;
61
62
  title?: string;
63
+ /** Explicit destination; omitted uses the device picker when available. */
64
+ location?: ProjectFolderLocation;
62
65
  }): Promise<import("./session.js").OpenResult>;
63
66
  /**
64
67
  * The folder the loaded project came from, or `null` once another project loaded or the folder was
65
68
  * detached. A host can tell projects apart by it, for example to keep the layout of each one.
66
69
  */
67
70
  readonly directory: FileSystemDirectoryHandle | null;
71
+ /**
72
+ * The folder the user chose for the loaded project, or `null` like `directory`. It is `directory` itself, or
73
+ * the repository whose `project` folder holds the project, or the stored folder of a folder kept in the browser.
74
+ */
75
+ readonly root: FileSystemDirectoryHandle | null;
68
76
  dispose(): void;
69
77
  } | null;
70
78
  export declare function projectFolderActions(vm: FolderVM, locale?: string): {
71
79
  open: () => void;
72
80
  openBrowser: (() => void) | undefined;
81
+ /** Whether Open can pick a folder on the device. Safari and Firefox cannot, so hosts show Open as unavailable. */
82
+ deviceFolders: boolean;
73
83
  save: (() => void) | undefined;
74
84
  detach: () => void;
75
85
  } | undefined;