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 +50 -0
- package/dist/castle.d.ts +2 -0
- package/dist/castle.js +1 -0
- package/dist/debugConsole.d.ts +17 -0
- package/dist/debugConsole.js +154 -0
- package/dist/runtime.js +36 -19
- package/package.json +1 -1
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
|
-
|
|
438
|
+
forwardConsoleLine("log", args);
|
|
435
439
|
};
|
|
436
440
|
console.warn = (...args) => {
|
|
437
441
|
origWarn(...args);
|
|
438
|
-
|
|
442
|
+
forwardConsoleLine("warn", args);
|
|
439
443
|
};
|
|
440
444
|
console.error = (...args) => {
|
|
441
445
|
origError(...args);
|
|
442
|
-
|
|
446
|
+
forwardConsoleLine("error", args);
|
|
443
447
|
};
|
|
444
448
|
}
|
|
445
|
-
function
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
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.
|