castle-web-sdk 0.4.10 → 0.4.12

package/README.md

@@ -412,6 +412,23 @@ await writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));
 Only works while editing locally with `castle-web serve`. Calls from a
 published deck fail.
 
+### `fileUrl(path): string`
+
+A URL that serves a deck file as raw bytes. Point an `<img>`, `<audio>`,
+or `<video>` at it when editor UI has to show a file the browser renders
+natively — `writeFile`'s counterpart reads text, which is nothing an
+image or a sound can be read as.
+
+```js
+import { fileUrl } from "castle-web-sdk";
+
+<img src={fileUrl("assets/logo.png")} alt="" />;
+```
+
+Like `writeFile`, this only means anything while editing locally with
+`castle-web serve` — a published deck has no serve to ask, and should
+load its assets through the bundler instead.
+
 ## CastleError
 
 Every error the SDK throws is a `CastleError`. Check `code` to tell

package/dist/castle.d.ts

@@ -1,5 +1,6 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
 export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
 export { Leaderboard } from "./leaderboard";
@@ -10,7 +11,7 @@ export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
-export { CARD_RATIO, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";

package/dist/castle.js

@@ -1,12 +1,13 @@
 // Castle Web SDK
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
 export { Portal } from "./portal";
-export { CARD_RATIO, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/files.d.ts

@@ -0,0 +1,15 @@
+export declare const IMPORTS_PREFIX = "@imports/";
+export declare const IMPORTS_DIR = "imports";
+export declare function deckPrefixOf(filePath: string): string;
+/**
+ * Resolve a reference to the key it names in the deck's file map.
+ *
+ * @param ref  the reference as written -- `drawings/rock.pxart` or
+ *             `@imports/someone.pack/drawings/rock.pxart`
+ * @param from the path of the file the reference was written in; a reference in
+ *             a deck's own file resolves against the deck root, one in an
+ *             import's file against that import.
+ */
+export declare function resolveDeckFile(ref: string, from?: string): string;
+/** Whether a path names a file some import owns (rather than the deck's own). */
+export declare function isImportedFile(filePath: string): boolean;

package/dist/files.js

@@ -0,0 +1,52 @@
+// How a deck names a file -- one rule, everywhere a path appears: in JS module
+// specifiers, in a scene's `blueprint`, in a Sprite's `file`, in anything a kit
+// invents later.
+//
+//   drawings/rock.pxart          a file of the deck the REFERENCE lives in
+//   @imports/<alias>/drawings/rock.pxart   a file of that import
+//
+// The unprefixed form is deck-relative, and "the deck" means whichever deck the
+// referencing file belongs to. So a kit's blueprint saying `drawings/cauldron.pxart`
+// means the kit's own drawing whether the kit is the deck being played or an
+// import of it -- the same text keeps meaning the same file after the kit is
+// imported by somebody else. That is what makes a deck publishable as a
+// dependency without rewriting its insides.
+//
+// `@imports/` is the only way to name someone else's file, so a cross-deck
+// reference is visible as one at a glance, and it means the same thing from any
+// depth: imports are flattened into one `imports/` at the deck root, so the
+// prefix is positional in nothing.
+export const IMPORTS_PREFIX = '@imports/';
+// Where imports live on disk, relative to the deck root. `@imports/x/y` is
+// exactly `imports/x/y` -- the alias exists so the reference reads as a
+// cross-deck one and does not depend on where the referencing file sits.
+export const IMPORTS_DIR = 'imports';
+function stripDotSlash(path) {
+    return path.replace(/^\.\//, '');
+}
+// The deck a file belongs to, as a path prefix: `imports/<alias>/` for a file of
+// an import, `''` for one of the deck's own.
+export function deckPrefixOf(filePath) {
+    const match = new RegExp(`^(${IMPORTS_DIR}/[^/]+/)`).exec(filePath ?? '');
+    return match ? match[1] : '';
+}
+/**
+ * Resolve a reference to the key it names in the deck's file map.
+ *
+ * @param ref  the reference as written -- `drawings/rock.pxart` or
+ *             `@imports/someone.pack/drawings/rock.pxart`
+ * @param from the path of the file the reference was written in; a reference in
+ *             a deck's own file resolves against the deck root, one in an
+ *             import's file against that import.
+ */
+export function resolveDeckFile(ref, from = '') {
+    const path = stripDotSlash(String(ref ?? ''));
+    if (path.startsWith(IMPORTS_PREFIX)) {
+        return `${IMPORTS_DIR}/${path.slice(IMPORTS_PREFIX.length)}`;
+    }
+    return deckPrefixOf(stripDotSlash(from)) + path;
+}
+/** Whether a path names a file some import owns (rather than the deck's own). */
+export function isImportedFile(filePath) {
+    return deckPrefixOf(filePath) !== '';
+}

package/dist/runtime.d.ts

@@ -25,6 +25,7 @@ export interface FilesChangedEvent {
 }
 export declare function setup(): void;
 export declare function writeFile(path: string, contents: string): Promise<LocalResponse>;
+export declare function fileUrl(path: string): string;
 export declare function initCard(): HTMLDivElement;
 export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
 export declare function onFilesChanged(listener: (event: FilesChangedEvent) => void): () => void;

package/dist/runtime.js

@@ -30,6 +30,14 @@ export function writeFile(path, contents) {
         contents,
     });
 }
+// A same-origin URL that serves a deck file as raw bytes. Editor UI that shows
+// a file the browser renders natively -- an image in an `<img>`, a sound in an
+// `<audio>` -- points at this instead of reading the file, which only speaks
+// text. Only meaningful while editing locally with `castle-web serve`; a
+// published deck has no serve to ask.
+export function fileUrl(path) {
+    return `/__castle/files/raw?path=${encodeURIComponent(path)}`;
+}
 export function initCard() {
     const style = document.createElement("style");
     style.textContent = `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",