@kubohiroya/turbowarp-extension-loader 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## Unreleased
+## 0.8.0
+
+Released on 2026-11-03. Two additions a host needs to give a project an address at save time and to keep one cache across
+projects. Both are additive: the string form of `appURI`, every existing method and every default
+behave as before.
+
+- `createIndexedDBContentCache({appURI})` also accepts `() => string | undefined`, read at each
+  write like `sharedDigests`, so a host that keeps one cache while projects are reopened files each
+  write under the project open at that moment. `undefined` files the write as shared, as a missing
+  `appURI` always has. An `appURI` that is neither a string nor a function is now refused with
+  `Invalid IndexedDB cache options` instead of being used as a bucket name.
+- `ProjectIO.assignProjectURI(context, uri, {replace})` in `./project-codec` returns a new context
+  whose Manifest carries `uri`, so a project whose Manifest has no address can be given one at its
+  first save and keep it on later saves. The address is checked like the `uri` option of `prepare*`
+  (`INVALID_PROJECT_URI`). An existing different address is refused with the new code
+  `PROJECT_URI_CONFLICT` unless `replace: true`; the same address returns the context unchanged.
 
 ## 0.7.0
 

package/README.ja.md

@@ -151,6 +151,17 @@ await cache.deleteBucket(manifest.uri);    // 手放す。他が参照してい
 ごとに読むので、カタログの読み込みに合わせて埋めていけます。どの作品を開いているか言えないホスト
 は、すべてを shared に入れます。名前を推測するのは、無いと認めるより悪いからです。
 
+作品を開き直しても1つのキャッシュを使い続けるホスト（たとえば VM ごとに1つ）は、`appURI` に
+関数を渡します。`sharedDigests` と同じく書き込みごと（`put` を呼んだとき）に読むので、各書き込みは
+その時点で開いている作品の下に入り、関数が `undefined` を返した書き込みは shared に入ります。
+文字列を渡せば、これまでどおりキャッシュの寿命の間ずっと1つの作品を指します。
+
+```js
+let openProject;                           // いま開いている作品の URI。無ければ undefined
+const cache = createIndexedDBContentCache({appURI: () => openProject, sharedDigests: catalogDigests});
+// 読み込むたびに: openProject = prepared.manifest?.uri;
+```
+
 バケットを手放すと claim が落ち、**他が参照していない**バイト列だけが回収されます。2回参照されて
 いる1つの実体は残ります。もう一方の作品は失うことを求めていません。容量超過で追い出すときは
 claim も一緒に落ちるので、バケットが「もう無いもの」を並べることはありません。
@@ -228,18 +239,20 @@ Manifest は `uri` を持てます。その作品をダウンロードできる
 `prepareCatalogExtensionChanges` と `prepareExtensionAddition` は `uri` を受け取ります。作品が
 最初の住所を得るのも、作者が選んだ住所へ移るのも、この経路です。何も言わなければ作品が持って
 いる住所がそのまま残り、`readProjectAuthoringState` がその住所を報告するので、ホストは初回保存
-かどうかを決める前に見分けられます。割り当てるかどうかはホストの判断です。作者が住所を選んだ
+かどうかを決める前に見分けられます。`./project-codec` で開いた作品の Manifest に住所が
+無ければ、保存のときに `assignProjectURI` で与えます（「SB3 codec」を参照）。割り当てるかどうかはホストの判断です。作者が住所を選んだ
 のか、既定が必要な初回保存なのかを知っているのはホストだけだからです。
 
 `./project-authoring` の `createProjectUUID` と `defaultProjectURI` が、作者が住所を選んで
 いないときに与える住所を組みます。
 
 ```js
-const uri = defaultProjectURI(location.origin + location.pathname, createProjectUUID());
+const uri = defaultProjectURI(location.origin, createProjectUUID());
 ```
 
-オリジンはエディター自身のもので、配信していない host を名乗ることはありません。この住所は作品
-を人に渡すとき SB3 の中に入って一緒に移動するからです。識別子は UUID version 7 なので、初回保存
+オリジンはエディターをブラウザーで起動したドメインのもので、パスは付けません（`editor.html` の
+パスを付けると、住所がその下にできてしまいます）。配信していない host を名乗ることはありません。
+この住所は作品を人に渡すとき SB3 の中に入って一緒に移動するからです。識別子は UUID version 7 なので、初回保存
 の時刻順に並びます。2段のディレクトリは UUID の**末尾**から取ります。version 7 の先頭はミリ秒
 時計の上位で、ほとんど動かないので、先頭でシャーディングすると**作られた全作品が1つの
 ディレクトリに入ります**。
@@ -280,6 +293,22 @@ npm run check
 
 `prepare` は JSON object / string / UTF-8 bytes / ArrayBuffer / Blob と SB3 ZIP を受け取り、`{manifest, input, context}` を返します。Manifest があれば core で検証し、legacy input の Plus ID に対する `extensionURLs` を除去して自動 URL 実行を防ぎます。ID 自体は GUI の登録 hook 用に残します。保存時は Manifest・元の Plus URL metadata・embedded bytes・未知の ZIP entry・未知の top-level metadata を復元します。`restoreArchive` は GUI の `toJSON` hook が `project.json` を復元済みであることを前提とします。
 
+`assignProjectURI(context, uri, {replace})` は、Manifest が `uri` を持つ新しい context を返し、
+以後の restore に使います。Manifest に住所の無い作品は、これで最初の保存のときに住所を得ます。
+ホストが返された context を保てば、その後の保存でも同じ住所が入ります。住所は `prepare*` の
+`uri` と同じ規則で検証し（HTTPS で、資格情報もフラグメントも無いこと。違えば
+`INVALID_PROJECT_URI`）、正規化した形で記録します。**作品が既に持っている住所は、
+`replace: true` と言わない限り置き換えません**。違う住所は `PROJECT_URI_CONFLICT` で拒否し、
+同じ住所なら context をそのまま返します。渡した context は変わらず有効で、`null` の context
+（Manifest が無い）は住所を載せる先が無いので拒否します。
+
+```js
+let saved = prepared.context;
+// 保存のとき、prepared.manifest が uri を持たない場合だけ:
+if (saved && !prepared.manifest.uri) saved = io.assignProjectURI(saved, defaultProjectURI(location.origin, createProjectUUID()));
+io.restoreJSON(json, saved);
+```
+
 未対応形式は ZIP64、multidisk、暗号化、STORE/DEFLATE 以外、UTF-8 以外の非 ASCII entry 名、Unicode path extra field です。既定上限は archive と全展開量64 MiB、1 entry16 MiB、project.json 32 MiB、4096 entry、圧縮比1000です。上限はホスト起動設定で変更できます。Manifest のない ZIP もこの安全検査を受け、通過後は元 input をそのまま返します。このため、従来 VM が許していた未対応 ZIP もフラグ有効時には拒否されます。フラグ OFF では codec 自体を呼びません。
 
 ## 追加のホスト向けAPI

package/README.md

@@ -152,6 +152,17 @@ is read at each write, so a host may keep filling it as its catalog loads. A hos
 which project it is opening files everything as shared, because guessing a name is worse than
 admitting there is none.
 
+A host that keeps one cache while projects are opened and closed — one per VM, say — passes
+`appURI` as a function instead. Like `sharedDigests`, it is read at each write (when `put` is
+called), so each write is filed under the project open at that moment, and a function that returns
+`undefined` files that write as shared. A string still names one project for the cache's lifetime.
+
+```js
+let openProject;                           // the URI of the project open now, or undefined
+const cache = createIndexedDBContentCache({appURI: () => openProject, sharedDigests: catalogDigests});
+// on each load: openProject = prepared.manifest?.uri;
+```
+
 Releasing a bucket drops its claims and reclaims only the bytes **nothing else refers to**. One
 copy referred to twice stays: the other project did not ask to lose it. An eviction takes the
 claims on it as well, so a bucket never lists bytes that are gone.
@@ -231,7 +242,9 @@ do.
 `prepareCatalogExtensionChanges` and `prepareExtensionAddition` take a `uri` option, which is how
 a project gets its first address and how it moves to one the author chose. Saying nothing keeps
 the address the project already has, and `readProjectAuthoringState` reports that address, so a
-host can tell a first save from a later one before deciding. Whether to assign one is the host's
+host can tell a first save from a later one before deciding. A project opened through
+`./project-codec` whose Manifest has no address is given one at save time with
+`assignProjectURI` (see "SB3 codec"). Whether to assign one is the host's
 call: only the host knows whether the author chose an address or whether this is a first save
 that needs a default.
 
@@ -239,11 +252,12 @@ that needs a default.
 is given when its author has not chosen one:
 
 ```js
-const uri = defaultProjectURI(location.origin + location.pathname, createProjectUUID());
+const uri = defaultProjectURI(location.origin, createProjectUUID());
 ```
 
-The origin is the editor's own, never a host it does not serve from, because this address travels
-inside the SB3 when the work is handed on. The identifier is a UUID version 7, so it sorts by when
+The origin is that of the domain the editor was opened at, with no path (passing the path of
+`editor.html` would put the address under it). It is never a host the editor does not serve from,
+because this address travels inside the SB3 when the work is handed on. The identifier is a UUID version 7, so it sorts by when
 the project was first saved, and the two directory levels are taken from its **end** — a version 7
 UUID begins with the top of a millisecond clock, which barely moves, so sharding on its first
 characters would put every project ever created in one directory.
@@ -285,6 +299,23 @@ Wire the Loader inside a host feature flag that is fixed at startup and off by d
 
 `prepare` accepts a JSON object, a string, UTF-8 bytes, an ArrayBuffer, a Blob and an SB3 ZIP, and returns `{manifest, input, context}`. When a Manifest is present, the core validates it and strips `extensionURLs` for Plus IDs in legacy input to prevent automatic URL execution. The IDs themselves remain for the GUI's registration hook. On save it restores the Manifest, the original Plus URL metadata, embedded bytes, unknown ZIP entries and unknown top-level metadata. `restoreArchive` assumes the GUI's `toJSON` hook has already restored `project.json`.
 
+`assignProjectURI(context, uri, {replace})` returns a new context whose Manifest carries `uri`, for
+the restore calls that follow. It is how a project whose Manifest has no address gets one when it is
+first saved: the host keeps the context it returns, so every later save carries the same address.
+The address follows the same rule as the `uri` option of `prepare*` (`INVALID_PROJECT_URI` unless
+HTTPS without credentials or fragment) and is recorded normalized. **An address the project already
+has is never replaced unless `replace: true` says so**: a different one is refused with
+`PROJECT_URI_CONFLICT`, and the same one returns the context unchanged. The context passed in stays
+valid and unchanged, and a `null` context (no Manifest) is refused, since there is nothing to carry
+the address.
+
+```js
+let saved = prepared.context;
+// at save time, only when prepared.manifest has no uri:
+if (saved && !prepared.manifest.uri) saved = io.assignProjectURI(saved, defaultProjectURI(location.origin, createProjectUUID()));
+io.restoreJSON(json, saved);
+```
+
 Unsupported formats are ZIP64, multidisk, encryption, compression other than STORE/DEFLATE, non-ASCII entry names that are not UTF-8, and the Unicode path extra field. The default limits are 64 MiB for the archive and for total expansion, 16 MiB per entry, 32 MiB for `project.json`, 4096 entries, and a compression ratio of 1000. The limits are configurable through the host's startup settings. A ZIP without a Manifest goes through the same safety checks, and the original input is returned unchanged once it passes. As a result, an unsupported ZIP that the previous VM accepted is rejected while the flag is on. With the flag off, the codec is not called at all.
 
 ## Additional host-facing API

package/dist/indexeddb-cache.d.ts

@@ -30,8 +30,12 @@ export interface IndexedDBContentCacheOptions {
      * Without one, everything is filed as shared: a host that cannot say which project it is
      * opening cannot have per-project accounting, and guessing a name would be worse than
      * admitting there is none.
+     *
+     * A host that keeps one cache while projects are opened and closed passes a function instead:
+     * it is read at the time of each write, like `sharedDigests`, so each write is filed under the
+     * project open at that moment. A function that returns `undefined` files that write as shared.
      */
-    appURI?: string;
+    appURI?: string | (() => string | undefined);
     /**
      * Digests that belong to no one project, read at the time of each write.
      *

package/dist/indexeddb-cache.js

@@ -17,8 +17,17 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
         throw new Error('IndexedDB unavailable');
     if (typeof databaseName !== 'string' || !databaseName || !Number.isSafeInteger(maxBytes) || maxBytes < 1 ||
         !Number.isSafeInteger(maxDecompressedBytes) || maxDecompressedBytes < 1 ||
-        typeof now !== 'function')
+        typeof now !== 'function' ||
+        (appURI !== undefined && typeof appURI !== 'string' && typeof appURI !== 'function')) {
         throw new TypeError('Invalid IndexedDB cache options');
+    }
+    /** The project a write is filed under, read when it happens. */
+    function currentAppURI() {
+        const uri = typeof appURI === 'function' ? appURI() : appURI;
+        if (uri !== undefined && typeof uri !== 'string')
+            throw new TypeError('appURI must return a string or undefined');
+        return uri;
+    }
     let dbPromise;
     function open() {
         if (!dbPromise) {
@@ -192,12 +201,15 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
                 throw signal.reason;
             if (bytes.byteLength > maxDecompressedBytes)
                 throw new RangeError('Cache input exceeds decompressed size limit');
+            // Read when put() is called, not after compressing: the project open now is the one
+            // these bytes were fetched for, even if another is opened before the write lands.
+            const uri = currentAppURI();
             const originalBytes = bytes.byteLength;
             const compressed = await gzipBytes(bytes);
             if (signal?.aborted)
                 throw signal.reason;
             const db = await open();
-            const bucket = appURI === undefined || sharedDigests?.has(key) ? SHARED_BUCKET : appURI;
+            const bucket = uri === undefined || sharedDigests?.has(key) ? SHARED_BUCKET : uri;
             return transaction(db, 'readwrite', (store, _set, tx) => {
                 const usage = tx.objectStore('usage');
                 const time = now();

package/dist/project-authoring.d.ts

@@ -47,8 +47,9 @@ export declare const PROJECT_URI_PREFIX = "turbowarp-plus-projects";
  * A fresh identifier for one project: a UUID version 7.
  *
  * Version 7 and not 4 because the first 48 bits are the millisecond clock, so the identifier
- * itself sorts by when the project was first saved. That costs nothing over a random UUID and
- * leaves the ordering available to anything that wants it.
+ * itself sorts by when the project was first saved, to the millisecond. That costs nothing over a
+ * random UUID and leaves the ordering available to anything that wants it. Two identifiers made in
+ * the same millisecond are ordered by their random bits, not by which came first.
  * @returns {string} The UUID, in the canonical lowercase form.
  */
 export declare function createProjectUUID(): string;

package/dist/project-authoring.js

@@ -173,8 +173,9 @@ export const PROJECT_URI_PREFIX = 'turbowarp-plus-projects';
  * A fresh identifier for one project: a UUID version 7.
  *
  * Version 7 and not 4 because the first 48 bits are the millisecond clock, so the identifier
- * itself sorts by when the project was first saved. That costs nothing over a random UUID and
- * leaves the ordering available to anything that wants it.
+ * itself sorts by when the project was first saved, to the millisecond. That costs nothing over a
+ * random UUID and leaves the ordering available to anything that wants it. Two identifiers made in
+ * the same millisecond are ordered by their random bits, not by which came first.
  * @returns {string} The UUID, in the canonical lowercase form.
  */
 export function createProjectUUID() {

package/dist/project-codec.d.ts

@@ -53,6 +53,23 @@ export interface ProjectIO {
     restoreJSON<T extends string | Record<string, unknown>>(json: T, context: ProjectContext | null): T;
     restoreFiles(files: Record<string, Uint8Array>, context: ProjectContext | null): Record<string, Uint8Array>;
     restoreArchive<T extends ZipArchive>(archive: T, context: ProjectContext | null): T;
+    /**
+     * A context like `context` whose Manifest carries `uri`, for the restore calls that follow.
+     *
+     * This is how a project whose Manifest has no address gets one when it is first saved, and
+     * keeps it on every later save: the host holds on to the context this returns. The address
+     * follows the same rule as the `uri` option of `prepareExtensionAddition` and
+     * `prepareCatalogExtensionChanges` (`INVALID_PROJECT_URI` unless HTTPS without credentials or
+     * fragment), and comes back normalized in the Manifest.
+     *
+     * An address the project already has is never replaced unless `replace` says so: a different
+     * one is refused with `PROJECT_URI_CONFLICT`, and the same one returns `context` itself. The
+     * context passed in is left as it was. A project with no Manifest (a `null` context) has no
+     * address to carry, and is refused.
+     */
+    assignProjectURI(context: ProjectContext, uri: string, options?: {
+        replace?: boolean;
+    }): ProjectContext;
 }
 /** The one carrier spelling this family writes, and the only one a standard host is given. */
 export declare const DATA_CARRIER_PREFIX = "data:text/javascript;base64,";

package/dist/project-codec.js

@@ -1,4 +1,4 @@
-import { discoverManifest, LoaderError } from './index.js';
+import { discoverManifest, LoaderError, validateManifest } from './index.js';
 import { DEFAULT_ENTRY_BYTES, DEFAULT_PROJECT_JSON_BYTES, DEFAULT_TOTAL_BYTES } from './limits.js';
 const DEFAULTS = Object.freeze({ maxArchiveBytes: DEFAULT_TOTAL_BYTES, maxTotalBytes: DEFAULT_TOTAL_BYTES,
     maxEntryBytes: DEFAULT_ENTRY_BYTES, maxProjectBytes: DEFAULT_PROJECT_JSON_BYTES, maxEntries: 4096, maxRatio: 1000 });
@@ -342,6 +342,24 @@ export function createProjectIO({ zip: Zip, ...options } = {}) {
                 if (name !== 'project.json' && (!archive.file(name) || name.startsWith('extensions/')))
                     archive.file(name, new Uint8Array(bytes), { dir: name.endsWith('/'), createFolders: false });
             return archive;
+        },
+        assignProjectURI(context, uri, { replace = false } = {}) {
+            const state = get(context);
+            if (!state)
+                throw new TypeError('A project without a manifest has no address to assign');
+            // The one address rule, through the one place that applies it.
+            const address = validateManifest({ schemaVersion: 1, uri, extensions: [] }).uri;
+            const current = state.manifest.uri;
+            if (current === address)
+                return context;
+            // Saying nothing keeps the address a project has; replacing it has to be asked for.
+            if (current !== undefined && replace !== true) {
+                throw new LoaderError('PROJECT_URI_CONFLICT', 'This project already has a different address');
+            }
+            const manifest = Object.freeze({ schemaVersion: 1, uri: address, extensions: state.manifest.extensions });
+            const next = Object.freeze({});
+            contexts.set(next, { manifest, project: state.project, files: state.files });
+            return next;
         }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-extension-loader",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Host-independent verified TurboWarp Plus extension loading core",
   "keywords": [
     "turbowarp",