@kubohiroya/turbowarp-plus-editor-project-folder 0.16.0 → 0.18.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,10 +8,10 @@ TurboWarp Plus Editor で sb3-toolchain の作品フォルダ(展開ソース
8
8
 
9
9
  - `mountProjectFolder({vm, document, host})` でワークスペースに接続します。ワークスペースの切り替え時には `dispose()` を呼びます。
10
10
  - `renderProjectFolderMenu(createElement, props)` は既存の開く・保存コマンドをホストのファイルメニューに渡します。
11
- - 選んだフォルダの直下に作品がなく、その中の `project` フォルダが作品フォルダのときは、`project` を作品フォルダとして開きます(Project Starter が作るリポジトリの形)。`project` フォルダの中に `.git` があるときは開きません。どちらも作品でないときは、選んだフォルダのエラーをそのまま出します。
12
- - 接続後の `openDirectory(handle, confirmReplace, root?)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・`project` フォルダへの切り替え・未保存編集の確認を経て開き、保存先にはその作品フォルダを使います。`root` には、ホストが自分で作品の場所を見つけたときに、ユーザーが選んだフォルダを渡します。省略すると `handle` です。
11
+ - 一つのフォルダには一つの作品を、フォルダのルートに置きます。ルートに `project.source.json`・`sb3-source.json`・`embedded-extensions.json` があるフォルダがプロジェクトフォルダです。ユーザーが開こうとしたフォルダ(**フォルダを開く…**、**ブラウザーに保存したフォルダを開く…**、ホストの `openDirectory`)がプロジェクトフォルダでないときは、エラーのダイアログに「このフォルダはプロジェクトフォルダではありません。」(英語では “This folder is not a project folder.”)と、その操作の言語で出し、何も開きません。開いている作品はそのまま残り、未保存の編集の確認も出さず、`followProjectFolder` の listener も呼びません。ダイアログはモーダルの `<dialog>`(`role="alertdialog"`、`data-project-folder-error="not-project"`)で、タイトルと **OK** ボタンがあり、OK で閉じるとフォーカスを元の場所に戻します。ファイルが壊れている、または対応していない形式のプロジェクトフォルダは、これまでどおり状態表示にエラーを出します。`createFromSnapshot` で新しいプロジェクトフォルダに保存する操作は変わりません。
12
+ - 接続後の `openDirectory(handle, confirmReplace, root?, options?)` には、ホストが選択済みのディレクトリハンドルを渡せます。ファイルメニューと同じ作品検証・未保存編集の確認を経て開き、`'opened'`・`'cancelled'`・`'not-project'`(`OpenResult`)のどれかで終わります。`'not-project'` のときは何も変わっていません。エラーのダイアログを出しますが、ホストが自分の方法で知らせるときは `options.notProjectDialog` に `false` を渡すと出しません。`options.locale` はダイアログの言語で、省略すると `mountProjectFolder` の `locale` です。保存先にはその作品フォルダを使います。`root` には、ホストが作品を見つけたフォルダとして、ユーザーが選んだフォルダを渡します。省略すると `handle` です(`options` だけを渡すときは `undefined` を渡します)。ダイアログを出さなかったホスト向けに、ダイアログを出す `showNotProjectFolderDialog({document, locale})` と、その文言を返す `notProjectFolderMessage(locale)` もあります。
13
13
  - 接続後の `directory` は、読み込んだ作品のフォルダーのハンドルです。別の作品を読み込むか、フォルダーとの接続を外すと `null` になります。ホストは作品を見分けるのに使えます。
14
- - 接続後の `root` は、その作品のためにユーザーが選んだフォルダーです。`directory` そのもの、`directory` を `project` フォルダに持つリポジトリ、またはブラウザーに保存したフォルダでは保存したフォルダー全体を指します。`directory` が `null` のときは `null` です。ブラウザーではフォルダーの親を読めないので、ホストは Git のリポジトリを `root` に結び付けます。
14
+ - 接続後の `root` は、その作品のためにユーザーが選んだフォルダーです。ホストが `openDirectory` に別のフォルダを渡したとき以外は `directory` そのものです。`directory` が `null` のときは `null` です。ブラウザーではフォルダーの親を読めないので、ホストは Git のリポジトリを `root` に結び付けます。
15
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` のほかのファイルは残します。
16
16
 
17
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)
@@ -26,13 +26,26 @@ Safari と Firefox にはフォルダ選択(`showDirectoryPicker`)があり
26
26
  - `fallback`(既定):フォルダ選択がないブラウザー(Safari、Firefox)でだけ使います。ファイルメニューでは **フォルダを開く…** を、このブラウザーでは端末のフォルダを開けない旨を添えて無効にし、ブラウザー内の作品フォルダの一覧を開く **ブラウザーに保存したフォルダを開く…** を出します。`projectFolderActions(vm)` は `deviceFolders: false` を返すので、ホストのメニューでも同じように無効にできます。ホストが `open` を呼んだときは、これまでどおりブラウザー内のフォルダを開きます。`createFromSnapshot` は新しい作品フォルダの名前を尋ねます(`title` で名前の初期値を渡せます)。
27
27
  - `always`:フォルダ選択があるブラウザーでも使います。ファイルメニューの **フォルダを開く…** の隣に **ブラウザーに保存したフォルダを開く…** を足し、`projectFolderActions(vm).openBrowser` でも開けます。
28
28
  - `off`:使いません。
29
+ - 作品フォルダをまだ開いていないパネルには、利用できる保存方式の説明と作成ボタンを出します。`always` でフォルダ選択と OPFS の両方が使える場合は2方式、Safari・Firefox ではブラウザー内保存の説明を出します。説明には、ボタンを押した後の操作、外部アプリからの見え方、ブラウザー内の作品を残すための書き出し方法を含めます。
30
+ - `renderProjectFolderExplorer` の `createFolder(location)` には、選んだ保存先(`device` または `browser`)が渡ります。ホストはこれを `createFromSnapshot({location, ...})` に渡します。`location` を省略した場合は従来どおりフォルダ選択を優先し、利用できない保存先を明示した場合は別の保存先に切り替えずエラーにします。
29
31
  - 一覧のダイアログでは、作品フォルダを開く、ZIP で書き出す、削除することができます。保存領域の使用量と、ブラウザーが消さずに残すか(`persisted`)も表示します。閉じるボタンは X のアイコンで、名前は表示の言語に合わせます。
30
- - 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git の管理対象には入りません。`projectPath` を指定すると、リポジトリのルートの下の作品フォルダ(例:`project`)を開けます。
32
+ - 作品フォルダは `turbowarp-plus/projects/<id>/` に置き、表示名と時刻は `turbowarp-plus/project-info/<id>.json` に置きます。作品フォルダの外に置くので、Git の管理対象には入りません。フォルダを開くときは、保存したフォルダのルートの作品を読みます。`create(title, {projectPath})` と `directory(id)` は互換のために `projectPath` を受け付けて解決しますが、Editor はその下のフォルダを開きません。
31
33
  - 同じ作品フォルダへの保存は、`navigator.locks` で作品ごとに排他します。WebKit は `createWritable({mode: 'exclusive'})` を重ねても拒否しないので、タブ間の排他はロックで行います。保存すると一覧の更新時刻が変わります。
32
34
  - `openBrowserProjects(window)` は一覧・作成・削除・保存領域の状態を扱う口です。`chooseBrowserProject` は一覧のダイアログを、`exportBrowserProject` と `zipDirectory` は ZIP の書き出しを、ホストが直接使うためのものです。ZIP は圧縮せず、名前を UTF-8 で書きます。
33
35
 
34
36
  ブラウザーの中の作品フォルダは、サイトのデータを消したときや、しばらくサイトを使わなかったときに、ブラウザーが消すことがあります(Safari では 7 日間)。最初の作品フォルダを作るときに `navigator.storage.persist()` を求めますが、保証にはなりません。ZIP で書き出すか、Git で GitHub に送って残すようにダイアログで案内します。
35
37
 
38
+ 保存先選択の導入は、このパッケージを先に公開し、Editor の依存をその版へ固定してからホストの結線を反映します。切り戻すときは Editor の結線と依存の固定を一緒に戻します。OPFS に作成済みの作品は削除せず、ブラウザー内の一覧から開く・ZIP で書き出す経路を維持します。
39
+
40
+ ## 0.17.0 の後の互換性のない変更: 作品はフォルダのルートに置く
41
+
42
+ 0.16.0 では、選んだフォルダの直下に作品がないとき、その中の `project` フォルダの作品を開きました(Project Starter が作るリポジトリの形)。この切り替えはなくしました。一つの Git リポジトリには一つの作品を、そのルートに置きます。
43
+
44
+ - 作品を `project/` に置いたリポジトリは、プロジェクトフォルダではなくなります。開くとエラーのダイアログを出します。作品のファイルをリポジトリのルートに移すか、`project` フォルダそのものを開いてください。
45
+ - 古い形でブラウザーに保存したフォルダ(`projectPath: 'project'` の項目)も、ほかと同じく保存したフォルダのルートを開くので、エラーのダイアログを出します。このパッケージは移し替えをしません。ZIP で書き出して残し、その `project` フォルダを端末のフォルダとして開くか、sb3-toolchain で SB3 にしてから、ブラウザーの新しいフォルダに保存し直してください。
46
+ - `root` は、ホストが `openDirectory` に `root` を渡したとき以外は、作品フォルダそのものです。
47
+ - `OpenResult` に `'not-project'` が加わりました。結果を `'opened'` と `'cancelled'` だけで見分けていたホストは、これも扱ってください。
48
+
36
49
  ## ブロックパレットの設定
37
50
 
38
51
  TurboWarp Plus Editor は、ブロックパレットの設定を画面状態(`.tw-plus/workspace.json`)に保存するようになりました。この節の形式 2 の読み書きは、それ以前に作られた作品フォルダのために残しています。
package/README.md CHANGED
@@ -8,10 +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
- - 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`.
11
+ - One folder holds one project, at its root. A folder is a project folder when its root has `project.source.json`, `sb3-source.json` and `embedded-extensions.json`. When the folder the user opens (with **Open Folder…**, **Open Folder Saved in This Browser…** or a host's `openDirectory`) is not a project folder, an error dialog says “This folder is not a project folder.” (Japanese: 「このフォルダはプロジェクトフォルダではありません。」) in the locale of the command, and nothing opens: the open project stays, unsaved edits are not asked about, and `followProjectFolder` listeners are not called. The dialog is a modal `<dialog>` (`role="alertdialog"`, `data-project-folder-error="not-project"`) with a title and an **OK** button that closes it and returns the focus. A project folder whose files are broken or of an unsupported format reports its error in the status line as before. Saving a new project folder with `createFromSnapshot` is not affected.
12
+ - The mounted session's `openDirectory(handle, confirmReplace, root?, options?)` accepts a directory handle already selected by the host. It uses the same project validation and unsaved-edit confirmation as the file menu, and resolves with `'opened'`, `'cancelled'` or `'not-project'` (`OpenResult`). With `'not-project'` nothing changed, and the error dialog is shown unless `options.notProjectDialog` is `false`, for a host that tells the user in its own way; `options.locale` sets the dialog's locale, which defaults to the `locale` of `mountProjectFolder`. Save still targets the opened project folder. `root` names the folder the user chose, for a host that located the project in it; it defaults to `handle` (pass `undefined` to give only `options`). `showNotProjectFolderDialog({document, locale})` shows the dialog, and `notProjectFolderMessage(locale)` gives its message, for hosts that opted out.
13
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`.
14
+ - The mounted session's `root` is the folder the user chose for that project: `directory` itself, unless a host gave another folder to `openDirectory`. It is `null` whenever `directory` is. The browser cannot read a folder's parent, so a host binds a Git repository to `root`.
15
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`.
16
16
 
17
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).
@@ -28,13 +28,24 @@ Safari and Firefox have no folder picker (`showDirectoryPicker`). In these brows
28
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
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.
30
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.
31
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.
32
- - 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`.
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. Opening a folder reads the project at the root of that stored folder. `create(title, {projectPath})` and `directory(id)` still accept and resolve `projectPath` for compatibility, but the Editor does not open the folder below it.
33
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.
34
36
  - `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.
35
37
 
36
38
  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.
37
39
 
40
+ ## Breaking change after 0.17.0: the project is at the folder's root
41
+
42
+ 0.16.0 opened the `project` folder of a chosen folder that had no project of its own, as in a repository made by Project Starter. That fallback is removed: one Git repository holds one project, at its root.
43
+
44
+ - A repository with its project in `project/` is not a project folder any more. Opening it shows the error dialog. Move the project files to the repository root, or open the `project` folder itself.
45
+ - A folder kept in the browser with the old layout (its entry has `projectPath: 'project'`) is opened at its stored folder like any other, so it shows the error dialog too. The package has no migration: export it as a ZIP to keep it, and open its `project` folder as a folder on the device, or build it into an SB3 with sb3-toolchain and save that as a new folder in the browser.
46
+ - `root` is the project folder itself unless a host passes `root` to `openDirectory`.
47
+ - `OpenResult` has the new value `'not-project'`. A host that compared the result with `'opened'` and `'cancelled'` only should handle it.
48
+
38
49
  ## Block palette settings
39
50
 
40
51
  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.
@@ -9,7 +9,7 @@ export type BrowserProjectChoice = {
9
9
  };
10
10
  /**
11
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.
12
+ * names a new empty one. Resolves with the chosen stored folder, or `null` when the dialog closes without one.
13
13
  */
14
14
  export declare function chooseBrowserProject({ document, projects, locale, purpose, title }: {
15
15
  document: Document;
@@ -4,13 +4,16 @@
4
4
  * browser may delete them; a user keeps a copy by exporting a ZIP or pushing to GitHub.
5
5
  *
6
6
  * Layout under the OPFS root:
7
- * turbowarp-plus/projects/<id>/ the folder (a project folder, or a repository with the project inside)
7
+ * turbowarp-plus/projects/<id>/ the folder, a project folder with the project at its root
8
8
  * turbowarp-plus/project-info/<id>.json its title and times, kept outside the folder so Git never sees them
9
9
  */
10
10
  export interface BrowserProject {
11
11
  id: string;
12
12
  title: string;
13
- /** The project folder inside the stored folder, such as `project` in a repository, or `''` for the folder itself. */
13
+ /**
14
+ * A folder inside the stored folder, `''` for the stored folder itself. Only for compatibility: the Editor opens the
15
+ * project at the root of the stored folder, so an entry with another path is not a project folder there.
16
+ */
14
17
  projectPath: string;
15
18
  createdAt: number;
16
19
  updatedAt: number;
@@ -30,7 +33,7 @@ export interface BrowserProjects {
30
33
  }>;
31
34
  /** The stored folder, or `null` when it was deleted. */
32
35
  root(id: string): Promise<FileSystemDirectoryHandle | null>;
33
- /** The project folder of the entry, `projectPath` inside its stored folder. */
36
+ /** The folder `projectPath` inside the entry's stored folder. Opening uses `root` instead. */
34
37
  directory(id: string): Promise<FileSystemDirectoryHandle | null>;
35
38
  /** The entry that holds `handle`, or `null` when it is not in the browser's storage. */
36
39
  find(handle: FileSystemHandle): Promise<BrowserProject | null>;
@@ -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-h5VGx9Jp.js";
1
+ import { C as isObject, I as _asyncIterator, R as _objectSpread2, T as manifestFile, a as projectFolderOverwriteWarning, d as subscribeExplorerState, f as writeExplorerState, j as projectFile, l as readExplorerState, p as FolderError, s as hiddenEntry, t as followProjectFolder } from "./shared-CLo1e5zK.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-CwQoV7xd.js")]);
1466
+ const [bytes, { decodeText, mountTextFile }] = await Promise.all([file.arrayBuffer(), import("./shared-DkIVN2xk.js")]);
1467
1467
  if (disposed) return;
1468
1468
  const content = decodeText(bytes);
1469
1469
  if (content === null) {
@@ -1526,8 +1526,17 @@ var messages = {
1526
1526
  results: "Matching files",
1527
1527
  noFolder: "Open a folder to show its files here.",
1528
1528
  open: "Open Folder…",
1529
- create: "Create Project 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.",
@@ -1565,8 +1574,17 @@ var messages = {
1565
1574
  results: "検索結果",
1566
1575
  noFolder: "フォルダを開くと、ここにファイルを表示します。",
1567
1576
  open: "フォルダを開く…",
1568
- create: "プロジェクトフォルダを作成",
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,9 +1,12 @@
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;
5
- /** The folder the user chose for `directory`: itself, or the repository whose `project` folder it is. */
6
+ /** The folder the user chose for `directory`: itself, unless a host gave another one to `openDirectory`. */
6
7
  readonly root?: FileSystemDirectoryHandle | null;
8
+ /** Storage choices available when creating a project folder. */
9
+ readonly locations?: readonly ProjectFolderLocation[];
7
10
  subscribe(listener: () => void): () => void;
8
11
  subscribeEdits(listener: () => void): () => void;
9
12
  unsavedPaths(): ReadonlySet<string> | null;
@@ -14,7 +17,7 @@ export interface FollowedFolder {
14
17
  export declare function registerFolder(vm: object, folder: FollowedFolder): () => void;
15
18
  /**
16
19
  * Calls `listener` with the project folder mounted for `vm`, the directory open in it and the folder the user chose for
17
- * it (`root`, the directory itself or the repository that holds it in `project/`), now and whenever a folder is
20
+ * it (`root`, the directory itself unless a host gave another one), now and whenever a folder is
18
21
  * mounted, opened, closed or saved. `directory` and `root` are `null` while no folder is open. Returns the function
19
22
  * that stops it.
20
23
  */
package/dist/index.d.ts CHANGED
@@ -1,15 +1,17 @@
1
+ import type { ProjectFolderLocation } from './folder-registry.js';
1
2
  import type { BrowserProjects } from './browser-projects.js';
2
- import type { FolderHost, FolderVM } from './session.js';
3
+ import type { FolderHost, FolderVM, OpenResult } 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';
10
11
  export type { BrowserProject, BrowserProjects, BrowserStorageState } from './browser-projects.js';
11
12
  export { chooseBrowserProject, exportBrowserProject, zipFileName } from './browser-project-dialog.js';
12
13
  export type { BrowserProjectChoice } from './browser-project-dialog.js';
14
+ export { notProjectFolderMessage, showNotProjectFolderDialog } from './not-project-dialog.js';
13
15
  export { zipDirectory } from './zip.js';
14
16
  type MenuElement = (component: any, props: any, ...children: any[]) => any;
15
17
  interface MenuProps {
@@ -27,6 +29,16 @@ interface MenuProps {
27
29
  * - `off`: only folders on the device.
28
30
  */
29
31
  export type BrowserStorageMode = 'fallback' | 'always' | 'off';
32
+ /** Options of `openDirectory`. */
33
+ export interface OpenDirectoryOptions {
34
+ /**
35
+ * Whether a folder that is not a project folder is told to the user in the error dialog (default true). A host
36
+ * that tells the user in its own way passes false and acts on the `not-project` result.
37
+ */
38
+ notProjectDialog?: boolean;
39
+ /** The locale of the dialog; defaults to the `locale` given to `mountProjectFolder`. */
40
+ locale?: string;
41
+ }
30
42
  /**
31
43
  * `autoReload` (default true) applies value and position changes without a click when the Editor has no unsaved
32
44
  * edits and the project is stopped. Other changes always wait for the reload command.
@@ -39,7 +51,13 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
39
51
  autoReload?: boolean;
40
52
  browserStorage?: BrowserStorageMode;
41
53
  }): {
42
- openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean, root?: FileSystemDirectoryHandle | undefined) => Promise<import("./session.js").OpenResult>;
54
+ /**
55
+ * Opens the project at the root of `directory`, as the user's Open would, and resolves with the result. A folder
56
+ * that is not a project folder changes nothing, shows the error dialog unless `options.notProjectDialog` is
57
+ * false, and resolves with `not-project`. `root` is the folder the user chose, for a host that located the
58
+ * project in it; it defaults to `directory`.
59
+ */
60
+ openDirectory: (directory: FileSystemDirectoryHandle, confirmReplace: () => boolean, root?: FileSystemDirectoryHandle | null, options?: OpenDirectoryOptions) => Promise<OpenResult>;
43
61
  unsavedPaths: () => ReadonlySet<string> | null;
44
62
  readUnsavedFile: (path: string) => Uint8Array<ArrayBufferLike> | null | undefined;
45
63
  subscribeEdits: (listener: () => void) => () => void;
@@ -53,21 +71,23 @@ export declare function mountProjectFolder({ vm, document, host, locale, autoRel
53
71
  * Creates a project folder from a snapshot. `title` names a folder made in the browser, where the user names a
54
72
  * new folder instead of picking one on the device.
55
73
  */
56
- createFromSnapshot({ prepareFiles, collectEdits, directory, current, title }: {
74
+ createFromSnapshot({ prepareFiles, collectEdits, directory, current, title, location }: {
57
75
  prepareFiles: () => Promise<ReadonlyMap<string, Uint8Array>>;
58
76
  collectEdits?: () => Promise<void>;
59
77
  directory?: FileSystemDirectoryHandle;
60
78
  current?: () => boolean;
61
79
  title?: string;
62
- }): Promise<import("./session.js").OpenResult>;
80
+ /** Explicit destination; omitted uses the device picker when available. */
81
+ location?: ProjectFolderLocation;
82
+ }): Promise<OpenResult>;
63
83
  /**
64
84
  * The folder the loaded project came from, or `null` once another project loaded or the folder was
65
85
  * detached. A host can tell projects apart by it, for example to keep the layout of each one.
66
86
  */
67
87
  readonly directory: FileSystemDirectoryHandle | null;
68
88
  /**
69
- * The folder the user chose for the loaded project, or `null` like `directory`. It is `directory` itself, or
70
- * the repository whose `project` folder holds the project, or the stored folder of a folder kept in the browser.
89
+ * The folder the user chose for the loaded project, or `null` like `directory`. It is `directory` itself, the
90
+ * project folder, unless the host gave another folder to `openDirectory`.
71
91
  */
72
92
  readonly root: FileSystemDirectoryHandle | null;
73
93
  dispose(): void;