castle-web-sdk 0.4.53 → 0.4.54

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.md CHANGED
@@ -38,6 +38,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
38
38
  - [Agent](#agent)
39
39
  - [Lifecycle](#lifecycle)
40
40
  - [Display](#display)
41
+ - [DebugConsole](#debugconsole)
41
42
  - [Multiplayer](#multiplayer)
42
43
  - [Setup](#setup)
43
44
  - [Saving files](#writefilepath-contents-promisevoid)
@@ -1975,6 +1976,44 @@ deck's preferred display orientation: `landscape`, `portrait`, or `any`.
1975
1976
  Missing or unrecognized preferences mean `any`; read the value as
1976
1977
  `display.orientation ?? "any"`.
1977
1978
 
1979
+ ## DebugConsole
1980
+
1981
+ A published deck's `console` output never reaches devtools: on
1982
+ castle.xyz the deck runs in a sandboxed frame of its own, and in the
1983
+ app it runs in a WebView. `DebugConsole` draws the deck's console as a
1984
+ panel along the bottom of the deck itself, so it can be read on the
1985
+ device the deck is running on.
1986
+
1987
+ - **`DebugConsole.show()`** — opens the panel. It holds the last 300
1988
+ lines of `console.log`, `console.warn` and `console.error`, plus
1989
+ uncaught errors and unhandled promise rejections. After
1990
+ [`setup()`](#setup) that includes everything since the deck started;
1991
+ in a deck that never calls `setup()`, only what comes after the first
1992
+ `show()`. The panel has **Clear** and **Hide** buttons.
1993
+ - **`DebugConsole.hide()`** — closes the panel. Lines keep being
1994
+ recorded.
1995
+ - **`DebugConsole.lines(): DebugConsoleLine[]`** — the recorded lines,
1996
+ oldest first, each `{ level: "log" | "warn" | "error", text, time }`
1997
+ with `time` from `Date.now()`, for a deck that draws its own.
1998
+
1999
+ The panel covers the bottom of the deck and takes touches there, so
2000
+ open it from a gesture or a debug option the deck controls, and remove
2001
+ that before the deck is for players:
2002
+
2003
+ ```js
2004
+ import { DebugConsole } from "castle-web-sdk";
2005
+
2006
+ // Three fingers on the card toggles the console.
2007
+ let open = false;
2008
+ window.addEventListener("touchstart", (event) => {
2009
+ if (event.touches.length === 3) {
2010
+ open = !open;
2011
+ if (open) DebugConsole.show();
2012
+ else DebugConsole.hide();
2013
+ }
2014
+ });
2015
+ ```
2016
+
1978
2017
  ## Setup
1979
2018
 
1980
2019
  Startup, editor-mode check, and a file-write call for editor UI.
@@ -1990,6 +2029,17 @@ While running locally with `castle-web serve`, it also forwards
1990
2029
  `console` output to the CLI and reloads the page when `castle-web
1991
2030
  restart` runs.
1992
2031
 
2032
+ `setup()` also keeps `history.pushState` and `history.replaceState`
2033
+ from throwing in a deck published on castle.xyz. There the deck's frame
2034
+ has no origin of its own, and a call that passes a URL throws a
2035
+ `SecurityError`; after
2036
+ `setup()` the call adds or replaces the history entry with its state
2037
+ but leaves the address as it was. A router that keeps its route in the
2038
+ address won't see it change; keep the route in the state or in the
2039
+ deck's own variables. `localStorage` throws there too; use
2040
+ [`LocalCache`](#localcache) for things the deck can rebuild and
2041
+ [`Store`](#store) for everything else.
2042
+
1993
2043
  ```js
1994
2044
  import { setup } from "castle-web-sdk";
1995
2045
 
package/dist/castle.d.ts CHANGED
@@ -46,6 +46,8 @@ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
46
46
  export type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
47
47
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
48
48
  export type { SaveState } from "./saveQueue";
49
+ export { DebugConsole } from "./debugConsole";
50
+ export type { DebugConsoleApi, DebugConsoleLevel, DebugConsoleLine } from "./debugConsole";
49
51
  export { LocalCache } from "./localCache";
50
52
  export type { LocalCacheApi } from "./localCache";
51
53
  export { SharedStorage, Storage } from "./storage";
package/dist/castle.js CHANGED
@@ -24,6 +24,7 @@ export { Portal } from "./portal";
24
24
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
25
25
  export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
26
26
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
27
+ export { DebugConsole } from "./debugConsole";
27
28
  export { LocalCache } from "./localCache";
28
29
  export { SharedStorage, Storage } from "./storage";
29
30
  export { Store } from "./store";
@@ -0,0 +1,17 @@
1
+ export type DebugConsoleLevel = "log" | "warn" | "error";
2
+ export interface DebugConsoleLine {
3
+ level: DebugConsoleLevel;
4
+ text: string;
5
+ /** `Date.now()` when the line was written. */
6
+ time: number;
7
+ }
8
+ export interface DebugConsoleApi {
9
+ show(): void;
10
+ hide(): void;
11
+ lines(): DebugConsoleLine[];
12
+ }
13
+ export declare function formatConsoleArgs(args: unknown[]): string;
14
+ export declare function recordConsoleLine(level: DebugConsoleLevel, text: string): void;
15
+ export declare function noteConsoleHooked(): void;
16
+ export declare function captureErrors(): void;
17
+ export declare const DebugConsole: DebugConsoleApi;
@@ -0,0 +1,154 @@
1
+ // A console drawn inside the deck's own frame, for debugging on a phone. A
2
+ // published deck runs in an opaque-origin frame (and in the app, a WebView), so
3
+ // the host page's devtools never see its console; this puts the lines where the
4
+ // person holding the device can read them. Off until the deck asks for it.
5
+ //
6
+ // `setup()` records every console line and uncaught error from the start, so
7
+ // `show()` reveals what happened before it was called. A deck that never calls
8
+ // `setup()` gets recording from its first `show()` on.
9
+ const MAX_LINES = 300;
10
+ const MAX_LINE_CHARS = 2000;
11
+ const COLORS = {
12
+ log: "#e8e8e8",
13
+ warn: "#ffd66b",
14
+ error: "#ff8a80",
15
+ };
16
+ const recorded = [];
17
+ let consoleHooked = false;
18
+ let errorsHooked = false;
19
+ let panel = null;
20
+ let list = null;
21
+ export function formatConsoleArgs(args) {
22
+ return args
23
+ .map((arg) => {
24
+ if (typeof arg === "string")
25
+ return arg;
26
+ if (arg instanceof Error)
27
+ return arg.stack || arg.message;
28
+ try {
29
+ const json = JSON.stringify(arg);
30
+ return json ?? String(arg);
31
+ }
32
+ catch {
33
+ return String(arg);
34
+ }
35
+ })
36
+ .join(" ");
37
+ }
38
+ // runtime.ts's own console hook calls this, so the line is formatted once for
39
+ // both the dev serve and this buffer.
40
+ export function recordConsoleLine(level, text) {
41
+ const line = {
42
+ level,
43
+ text: text.length > MAX_LINE_CHARS ? `${text.slice(0, MAX_LINE_CHARS)}…` : text,
44
+ time: Date.now(),
45
+ };
46
+ recorded.push(line);
47
+ if (recorded.length > MAX_LINES) {
48
+ recorded.splice(0, recorded.length - MAX_LINES);
49
+ }
50
+ if (list) {
51
+ appendRow(line);
52
+ }
53
+ }
54
+ export function noteConsoleHooked() {
55
+ consoleHooked = true;
56
+ }
57
+ // Uncaught errors and rejections never pass through console.error, and they
58
+ // are what a deck that "just shows a black card" on a phone is hiding.
59
+ export function captureErrors() {
60
+ if (errorsHooked || typeof window === "undefined")
61
+ return;
62
+ errorsHooked = true;
63
+ window.addEventListener("error", (event) => {
64
+ const error = event.error;
65
+ const text = error instanceof Error ? error.stack || error.message : event.message;
66
+ recordConsoleLine("error", `Uncaught ${text || "error"}`);
67
+ });
68
+ window.addEventListener("unhandledrejection", (event) => {
69
+ recordConsoleLine("error", `Unhandled rejection ${formatConsoleArgs([event.reason])}`);
70
+ });
71
+ }
72
+ function hookConsole() {
73
+ if (consoleHooked)
74
+ return;
75
+ consoleHooked = true;
76
+ for (const level of ["log", "warn", "error"]) {
77
+ const original = console[level];
78
+ console[level] = (...args) => {
79
+ original(...args);
80
+ recordConsoleLine(level, formatConsoleArgs(args));
81
+ };
82
+ }
83
+ }
84
+ function button(label, onClick) {
85
+ const el = document.createElement("button");
86
+ el.type = "button";
87
+ el.textContent = label;
88
+ el.style.cssText =
89
+ "font: inherit; color: #fff; background: #333; border: 1px solid #555; border-radius: 4px; padding: 2px 8px; margin-left: 6px;";
90
+ el.addEventListener("click", onClick);
91
+ return el;
92
+ }
93
+ // Text only, never markup: a line is whatever the deck logged.
94
+ function appendRow(line) {
95
+ if (!list)
96
+ return;
97
+ const row = document.createElement("div");
98
+ row.textContent = line.text;
99
+ row.style.cssText = `color: ${COLORS[line.level]}; white-space: pre-wrap; word-break: break-word; border-bottom: 1px solid #222; padding: 1px 0;`;
100
+ const atBottom = list.scrollHeight - list.scrollTop - list.clientHeight < 8;
101
+ list.appendChild(row);
102
+ while (list.childElementCount > MAX_LINES) {
103
+ list.firstElementChild?.remove();
104
+ }
105
+ if (atBottom) {
106
+ list.scrollTop = list.scrollHeight;
107
+ }
108
+ }
109
+ function buildPanel() {
110
+ const root = document.createElement("div");
111
+ root.setAttribute("data-castle-debug-console", "");
112
+ root.style.cssText =
113
+ "position: fixed; left: 0; right: 0; bottom: 0; max-height: 40%; z-index: 2147483647; display: flex; flex-direction: column; background: rgba(0, 0, 0, 0.85); color: #e8e8e8; font: 11px/1.35 ui-monospace, Menlo, Consolas, monospace; pointer-events: auto; touch-action: pan-y;";
114
+ const header = document.createElement("div");
115
+ header.style.cssText =
116
+ "display: flex; align-items: center; padding: 4px 8px; border-bottom: 1px solid #444; flex: none;";
117
+ const title = document.createElement("span");
118
+ title.textContent = "Console";
119
+ title.style.cssText = "flex: 1; font-weight: bold;";
120
+ header.append(title, button("Clear", () => {
121
+ recorded.length = 0;
122
+ list?.replaceChildren();
123
+ }), button("Hide", hide));
124
+ list = document.createElement("div");
125
+ list.style.cssText = "overflow-y: auto; padding: 4px 8px; flex: 1; min-height: 0;";
126
+ root.append(header, list);
127
+ return root;
128
+ }
129
+ function show() {
130
+ if (typeof document === "undefined")
131
+ return;
132
+ hookConsole();
133
+ captureErrors();
134
+ if (panel)
135
+ return;
136
+ panel = buildPanel();
137
+ (document.body ?? document.documentElement).appendChild(panel);
138
+ for (const line of recorded) {
139
+ appendRow(line);
140
+ }
141
+ if (list) {
142
+ list.scrollTop = list.scrollHeight;
143
+ }
144
+ }
145
+ function hide() {
146
+ panel?.remove();
147
+ panel = null;
148
+ list = null;
149
+ }
150
+ export const DebugConsole = {
151
+ show,
152
+ hide,
153
+ lines: () => recorded.slice(),
154
+ };
package/dist/runtime.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { CASTLE_SDK_PROTOCOL, } from "./commands";
2
2
  import { getCastleEmbed, isEdit } from "./context";
3
+ import { captureErrors, formatConsoleArgs, noteConsoleHooked, recordConsoleLine } from "./debugConsole";
3
4
  import { cardUnit, fitStage, getDisplay } from "./display";
4
5
  import { appliedNotice, applyTunedParams, } from "./paramsRegistry";
5
6
  export const CARD_RATIO = 5 / 7;
@@ -27,6 +28,8 @@ const origError = console.error;
27
28
  const dynamicImport = new Function("u", "return import(u)");
28
29
  export function setup() {
29
30
  interceptConsole();
31
+ captureErrors();
32
+ initHistoryShim();
30
33
  connectLocal();
31
34
  initLocalWake();
32
35
  initHostCapture();
@@ -429,35 +432,49 @@ function resolveLocalRequest(msg) {
429
432
  return true;
430
433
  }
431
434
  function interceptConsole() {
435
+ noteConsoleHooked();
432
436
  console.log = (...args) => {
433
437
  origLog(...args);
434
- sendMsg({ type: "log", level: "log", msg: formatConsoleArgs(args) });
438
+ forwardConsoleLine("log", args);
435
439
  };
436
440
  console.warn = (...args) => {
437
441
  origWarn(...args);
438
- sendMsg({ type: "log", level: "warn", msg: formatConsoleArgs(args) });
442
+ forwardConsoleLine("warn", args);
439
443
  };
440
444
  console.error = (...args) => {
441
445
  origError(...args);
442
- sendMsg({ type: "log", level: "error", msg: formatConsoleArgs(args) });
446
+ forwardConsoleLine("error", args);
443
447
  };
444
448
  }
445
- function formatConsoleArgs(args) {
446
- return args
447
- .map((arg) => {
448
- if (typeof arg === "string")
449
- return arg;
450
- if (arg instanceof Error)
451
- return arg.stack || arg.message;
452
- try {
453
- const json = JSON.stringify(arg);
454
- return json ?? String(arg);
455
- }
456
- catch {
457
- return String(arg);
458
- }
459
- })
460
- .join(" ");
449
+ function forwardConsoleLine(level, args) {
450
+ const msg = formatConsoleArgs(args);
451
+ recordConsoleLine(level, msg);
452
+ sendMsg({ type: "log", level, msg });
453
+ }
454
+ // A published deck's frame has an opaque origin (about:srcdoc on the web), so
455
+ // pushState/replaceState throw a SecurityError the moment they are given a URL.
456
+ // Keep the state and drop the URL: the history entry still lands, and routers
457
+ // that read state rather than the address keep working. Calls without a URL
458
+ // never threw and pass straight through. Only an opaque origin gets this: with
459
+ // an origin of its own a URL that throws is a real error (a cross-origin URL a
460
+ // router may catch to navigate instead), and is left to throw.
461
+ function initHistoryShim() {
462
+ if (typeof history === "undefined" || location.origin !== "null")
463
+ return;
464
+ for (const name of ["pushState", "replaceState"]) {
465
+ const original = history[name];
466
+ history[name] = function (data, unused, url) {
467
+ try {
468
+ original.call(this, data, unused, url);
469
+ }
470
+ catch (error) {
471
+ const security = error instanceof DOMException && error.name === "SecurityError";
472
+ if (!security || url === undefined || url === null)
473
+ throw error;
474
+ original.call(this, data, unused);
475
+ }
476
+ };
477
+ }
461
478
  }
462
479
  // Compositing a card needs html2canvas, and where it comes from decides whether
463
480
  // a capture can fail for reasons that have nothing to do with the deck.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-sdk",
3
- "version": "0.4.53",
3
+ "version": "0.4.54",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"