castle-web-sdk 0.4.43 → 0.4.44

package/README.md

@@ -1008,6 +1008,55 @@ Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
 New code should let Castle hosts provide the frame and let the SDK infer
 whether it is running standalone or embedded.
 
+### Filling the screen: `<meta name="castle-display">`
+
+By default a deck is a 5:7 portrait card. A deck that can lay itself out at
+other shapes opts out of the card in its own `index.html`:
+
+```html
+<meta name="castle-display" content="layout=fill">
+<!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
+<meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+```
+
+A `fill` deck gets the host's whole frame, edge to edge with no rounded
+corners, whenever that frame's aspect is inside its range (default 9/21 to
+21/9); outside it, the deck gets the largest in-range box, centered. Castle's
+web player gives a fill deck a bigger stage and a fullscreen button. Hosts
+that don't know the tag still give it a 5:7 frame, so a fill deck should look
+right at 5:7 as well.
+
+Lay out against the stage: the element `initCard()` returns, or
+`--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
+window: the stage is smaller than the window when the host frame is outside
+the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
+display)` the box the SDK would pick.
+
+Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
+
+```css
+.score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
+```
+
+`--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
+stage. On a card, or a stage taller than a card, it is 1% of the stage width
+(the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
+size while the playfield gets the extra room. Anything sized in `vw` grows with
+the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
+number from `cardUnit(width, height)` (px). The SDK sets the exact value for
+its own stage; in edit mode, and in a kit's scene editor that draws the stage
+smaller than the window, it falls back to the window's.
+
+A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
+aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
+sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
+the card's full width.
+
+```js
+camera.fov = fovForAspect(50, width / height);
+camera.updateProjectionMatrix();
+```
+
 ### `CARD_RATIO`
 
 The card aspect ratio (`5 / 7`). Use this if you need to size something

package/dist/castle.d.ts

@@ -29,6 +29,8 @@ export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
+export type { DeckDisplay, DeckLayout } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";

package/dist/castle.js

@@ -15,6 +15,7 @@ export { Pass } from "./passes";
 export { Snapshot } from "./snapshots";
 export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";

package/dist/display.d.ts

@@ -0,0 +1,36 @@
+export type DeckLayout = "card" | "fill";
+export interface DeckDisplay {
+    layout: DeckLayout;
+    /** Narrowest width / height the deck accepts. */
+    minAspect: number;
+    /** Widest width / height the deck accepts. */
+    maxAspect: number;
+}
+export declare const CARD_ASPECT: number;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export declare const FILL_MIN_ASPECT: number;
+export declare const FILL_MAX_ASPECT: number;
+export declare const CARD_DISPLAY: DeckDisplay;
+export declare function parseDisplayContent(content: string | null | undefined): DeckDisplay;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export declare function getDisplay(): DeckDisplay;
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export declare function cardUnit(width: number, height: number): number;
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export declare function fovForAspect(fovDeg: number, aspect: number): number;
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export declare function fitStage(width: number, height: number, display: DeckDisplay): {
+    w: number;
+    h: number;
+};

package/dist/display.js

@@ -0,0 +1,96 @@
+// How much of the host's frame a deck may use.
+//
+// A deck declares it in its own index.html, the way a page declares its
+// viewport:
+//
+//   <meta name="castle-display" content="layout=fill">
+//   <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+//
+// With no tag the deck is a `card`: the classic 5:7 portrait card, exactly as
+// before. A `fill` deck takes whatever box the host gives it, as long as the
+// box's aspect (width / height) is inside [minAspect, maxAspect]; outside that
+// range it gets the largest box in range, centered. A card is just the range
+// [5/7, 5/7].
+//
+// Hosts read the same tag out of the bundle to size the frame before the deck
+// loads (castle-www common/deckDisplay.ts mirrors this parser). A host that
+// knows nothing about it still gives the deck a 5:7 frame, so a fill deck
+// should render well at 5:7 too; one whose range leaves 5/7 out (landscape
+// only) is letterboxed inside such a frame.
+export const CARD_ASPECT = 5 / 7;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export const FILL_MIN_ASPECT = 9 / 21;
+export const FILL_MAX_ASPECT = 21 / 9;
+export const CARD_DISPLAY = {
+    layout: "card",
+    minAspect: CARD_ASPECT,
+    maxAspect: CARD_ASPECT,
+};
+// "16/9", "16:9" or "1.78"; anything else (or a non-positive value) is null.
+function parseAspect(value) {
+    const ratio = value.match(/^\s*(\d+(?:\.\d+)?)\s*[/:]\s*(\d+(?:\.\d+)?)\s*$/);
+    const n = ratio ? Number(ratio[1]) / Number(ratio[2]) : Number(value);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+export function parseDisplayContent(content) {
+    if (!content)
+        return CARD_DISPLAY;
+    const fields = {};
+    for (const part of content.split(/[,;]/)) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        fields[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
+    }
+    if (fields.layout?.toLowerCase() !== "fill")
+        return CARD_DISPLAY;
+    let minAspect = parseAspect(fields["min-aspect"] ?? "") ?? FILL_MIN_ASPECT;
+    let maxAspect = parseAspect(fields["max-aspect"] ?? "") ?? FILL_MAX_ASPECT;
+    if (minAspect > maxAspect)
+        [minAspect, maxAspect] = [maxAspect, minAspect];
+    return { layout: "fill", minAspect, maxAspect };
+}
+let cached = null;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export function getDisplay() {
+    if (cached)
+        return cached;
+    if (typeof document === "undefined")
+        return CARD_DISPLAY;
+    const meta = document.querySelector('meta[name="castle-display"]');
+    cached = parseDisplayContent(meta?.content);
+    return cached;
+}
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export function cardUnit(width, height) {
+    return Math.min(Math.max(0, width), Math.max(0, height) * CARD_ASPECT) / 100;
+}
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export function fovForAspect(fovDeg, aspect) {
+    if (!(aspect > 0) || aspect >= CARD_ASPECT)
+        return fovDeg;
+    const half = Math.atan((Math.tan((fovDeg * Math.PI) / 360) * CARD_ASPECT) / aspect);
+    return Math.min(120, (half * 360) / Math.PI);
+}
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export function fitStage(width, height, display) {
+    const aw = Math.max(1, width);
+    const ah = Math.max(1, height);
+    const aspect = aw / ah;
+    if (aspect > display.maxAspect)
+        return { w: ah * display.maxAspect, h: ah };
+    if (aspect < display.minAspect)
+        return { w: aw, h: aw / display.minAspect };
+    return { w: aw, h: ah };
+}

package/dist/runtime.js

@@ -1,5 +1,6 @@
 import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
+import { cardUnit, fitStage, getDisplay } from "./display";
 import { appliedNotice, applyTunedParams, } from "./paramsRegistry";
 export const CARD_RATIO = 5 / 7;
 // Host -> deck capture request, and the deck's answer. Kept in sync with the
@@ -31,6 +32,7 @@ export function setup() {
     initHostCapture();
     initPlaySelection();
     initEditSelection();
+    initCardUnitFallback();
     initPlayCard();
     logPanelLoad();
 }
@@ -120,7 +122,7 @@ export function initCard() {
     body { display: flex; align-items: center; justify-content: center; }
     #castle-card {
       position: relative;
-      border-radius: 4% / calc(4% * (5 / 7));
+      border-radius: ${cardRadius()};
       overflow: hidden;
       background: #121213;
     }
@@ -129,10 +131,12 @@ export function initCard() {
     const card = document.createElement("div");
     card.id = "castle-card";
     document.body.appendChild(card);
+    initCardUnitFallback();
     function resize() {
         const { w, h } = computeCardSize();
         card.style.width = w + "px";
         card.style.height = h + "px";
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
@@ -231,8 +235,10 @@ function initEditSelection() {
         selection.removeAllRanges();
     });
 }
-// Constrains whatever the deck renders into #root to a 5:7 card in play mode.
-// Hosts own max size and padding; the SDK only preserves the card aspect ratio.
+// Constrains whatever the deck renders into #root to the deck's stage in play
+// mode: a 5:7 card, or for a `fill` deck (see display.ts) the host's whole frame
+// within the deck's aspect range. Hosts own max size and padding; the SDK only
+// preserves the aspect.
 function initPlayCard() {
     if (isEdit())
         return;
@@ -247,7 +253,7 @@ function initPlayCard() {
       transform: translate(-50%, -50%) !important;
       width: var(--castle-card-w, 100vw) !important;
       height: var(--castle-card-h, 100vh) !important;
-      border-radius: 4% / calc(4% * (5 / 7)) !important;
+      border-radius: ${cardRadius()} !important;
       overflow: hidden !important;
     }
   `;
@@ -276,25 +282,37 @@ function initPlayCard() {
         const { w, h } = computeCardSize();
         document.documentElement.style.setProperty("--castle-card-w", w + "px");
         document.documentElement.style.setProperty("--castle-card-h", h + "px");
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
 }
+// `--castle-unit`: 1% of the width of the largest 5:7 card inside the stage
+// (display.ts cardUnit). A deck sizes HUD and text in it so they keep card
+// proportions on a wide fill stage. Play mode sets the exact px value on every
+// resize; the stylesheet fallback covers edit mode and the moment before the
+// first resize, and follows the window -- which is not the stage where a kit's
+// scene editor draws the deck smaller inside the editor.
+function setCardUnit(w, h) {
+    document.documentElement.style.setProperty("--castle-unit", cardUnit(w, h) + "px");
+}
+let cardUnitFallbackInstalled = false;
+function initCardUnitFallback() {
+    if (cardUnitFallbackInstalled)
+        return;
+    cardUnitFallbackInstalled = true;
+    const style = document.createElement("style");
+    style.textContent = `:root { --castle-unit: min(1vw, 1vh * 5 / 7); }`;
+    document.head.appendChild(style);
+}
 function computeCardSize() {
     const pad = shouldUseStandaloneChrome() ? 20 : 0;
-    const aw = Math.max(1, window.innerWidth - pad * 2);
-    const ah = Math.max(1, window.innerHeight - pad * 2);
-    let w;
-    let h;
-    if (aw / ah < CARD_RATIO) {
-        w = aw;
-        h = w / CARD_RATIO;
-    }
-    else {
-        h = ah;
-        w = h * CARD_RATIO;
-    }
-    return { w, h };
+    return fitStage(window.innerWidth - pad * 2, window.innerHeight - pad * 2, getDisplay());
+}
+// A card keeps its rounded corners; a fill deck runs edge to edge and the host
+// decides how its frame looks.
+function cardRadius() {
+    return getDisplay().layout === "fill" ? "0" : "4% / calc(4% * (5 / 7))";
 }
 function shouldUseStandaloneChrome() {
     if (window.parent !== window)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.43",
+  "version": "0.4.44",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"