castle-web-sdk 0.4.6 → 0.4.7

package/README.md

@@ -19,6 +19,7 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [Time](#time)
 - [User](#user)
 - [Pass](#pass)
+- [Lifecycle](#lifecycle)
 - [Setup](#setup)
 - [CastleError](#castleerror)
 
@@ -223,6 +224,30 @@ if (status === "purchased" || status === "alreadyOwned") {
 }
 ```
 
+## Lifecycle
+
+`Lifecycle` tells the host when the deck has painted its first frame, so
+the Castle feed can reveal it right away instead of waiting out a fixed
+delay.
+
+### `Lifecycle.ready()`
+
+Signal that the deck has painted its first presentable frame. Idempotent
+— only the first call has any effect.
+
+Kits already wire this up to fire as soon as the first frame paints; if
+you change how the deck first renders, make sure it still fires there. If
+nothing calls this, the feed reveals the deck on its own after a brief
+timeout.
+
+If you call it right after kicking off your initial render, wait for the
+next paint first so the host doesn't reveal a blank frame:
+
+```js
+createRoot(root).render(<App />);
+requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
+```
+
 ## Setup
 
 Startup, editor-mode check, and a file-write call for editor UI.

package/dist/castle.d.ts

@@ -2,6 +2,8 @@ export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+export { Lifecycle } from "./lifecycle";
+export type { CastleLifecycleApi } from "./lifecycle";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";

package/dist/castle.js

@@ -2,6 +2,7 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
+export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";

package/dist/commands.d.ts

@@ -115,3 +115,8 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
+export type LifecycleEvent = "ready";
+export interface LifecycleEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    lifecycle: LifecycleEvent;
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export interface CastleLifecycleApi {
+    ready(): void;
+}
+export declare const Lifecycle: CastleLifecycleApi;

package/dist/lifecycle.js

@@ -0,0 +1,13 @@
+// Deck-side lifecycle signals. The feed reveals the deck when it reports `ready`
+// (its first presentable frame) instead of waiting out a fixed timer.
+import { hostNotify } from "./transport";
+let readySent = false;
+function ready() {
+    if (readySent)
+        return;
+    readySent = true;
+    hostNotify("ready");
+}
+export const Lifecycle = {
+    ready,
+};

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResult } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
 type PostChannel = "mobile" | "web";
 interface ReactNativeWebViewBridge {
     postMessage: (message: string) => void;
@@ -13,4 +13,5 @@ declare global {
 }
 export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
 export declare function getCommandChannel(): PostChannel | "local";
+export declare function hostNotify(event: LifecycleEvent): void;
 export {};

package/dist/transport.js

@@ -52,6 +52,20 @@ export async function hostRequest(command, params) {
 export function getCommandChannel() {
     return resolveChannel();
 }
+// Fire-and-forget counterpart to hostRequest: no reply, no timeout. The local
+// dev server has no surface to react to lifecycle events, so it's skipped.
+export function hostNotify(event) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        lifecycle: event,
+    };
+    sendEnvelope(channel, envelope);
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";

package/package.json

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