castle-web-cli 0.4.163 → 0.4.165

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.
Files changed (142) hide show
  1. package/dist/agent-prompts.d.ts +3 -0
  2. package/dist/agent-prompts.js +14 -6
  3. package/dist/agent.js +14 -1
  4. package/dist/castle-host/host.js +276 -0
  5. package/dist/devSessionChild.js +66 -1
  6. package/dist/devSessionServer.js +21 -2
  7. package/dist/devSessionStorage.d.ts +9 -0
  8. package/dist/devSessionStorage.js +139 -0
  9. package/dist/forks.js +1 -1
  10. package/dist/headlessCover.js +12 -1
  11. package/dist/ide.d.ts +0 -2
  12. package/dist/ide.js +1 -7
  13. package/dist/imports.js +5 -0
  14. package/dist/init.js +1 -1
  15. package/dist/platformDoc.js +18 -3
  16. package/dist/rawData.d.ts +2 -0
  17. package/dist/rawData.js +10 -0
  18. package/dist/save-deck.d.ts +2 -0
  19. package/dist/save-deck.js +53 -20
  20. package/dist/serve.js +98 -0
  21. package/dist/shell/assets/index-CG9TrvCm.js +444 -0
  22. package/dist/shell/assets/index-CIRBt1qf.css +1 -0
  23. package/dist/shell/index.html +2 -2
  24. package/kits/base/CLAUDE.md +1 -1
  25. package/kits/base/castle.json +1 -1
  26. package/kits/base/node_modules/.package-lock.json +28 -0
  27. package/kits/base/node_modules/castle-web-fonts/README.md +114 -0
  28. package/kits/base/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  29. package/kits/base/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  30. package/kits/base/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  31. package/kits/base/node_modules/castle-web-fonts/dist/face.js +52 -0
  32. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  33. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  34. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  35. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  36. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  37. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  38. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  39. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  40. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  41. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  42. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  43. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  44. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  45. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  46. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  47. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  48. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  49. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  50. package/kits/base/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  51. package/kits/base/node_modules/castle-web-fonts/dist/index.js +15 -0
  52. package/kits/base/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  53. package/kits/base/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  54. package/kits/base/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  55. package/kits/base/node_modules/castle-web-fonts/package.json +47 -0
  56. package/kits/base/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  57. package/kits/base/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  58. package/kits/base/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  59. package/kits/base/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  60. package/kits/base/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  61. package/kits/base/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  62. package/kits/base/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  63. package/kits/base/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  64. package/kits/base/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  65. package/kits/base/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  66. package/kits/base/package-lock.json +1 -1
  67. package/kits/base/sdk/README.md +184 -38
  68. package/kits/base/sdk/castle.d.ts +2 -0
  69. package/kits/base/sdk/castle.js +1 -0
  70. package/kits/base/sdk/chunk.d.ts +1 -0
  71. package/kits/base/sdk/chunk.js +15 -0
  72. package/kits/base/sdk/commands.d.ts +86 -0
  73. package/kits/base/sdk/runtime.js +21 -12
  74. package/kits/base/sdk/server/platformHandle.d.ts +10 -0
  75. package/kits/base/sdk/server/storage.d.ts +46 -0
  76. package/kits/base/sdk/server/storage.js +218 -0
  77. package/kits/base/sdk/server/wrapper.d.ts +14 -1
  78. package/kits/base/sdk/server/wrapper.js +4 -1
  79. package/kits/base/sdk/storage.d.ts +15 -0
  80. package/kits/base/sdk/storage.js +29 -86
  81. package/kits/base/sdk/storageJson.d.ts +5 -0
  82. package/kits/base/sdk/storageJson.js +69 -0
  83. package/kits/base/sdk/store.d.ts +67 -0
  84. package/kits/base/sdk/store.js +313 -0
  85. package/kits/base/sdk/unloadFlush.d.ts +3 -0
  86. package/kits/base/sdk/unloadFlush.js +30 -0
  87. package/kits/blank/node_modules/.package-lock.json +13 -0
  88. package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
  89. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  90. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  91. package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  92. package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
  93. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  94. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  95. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  96. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  97. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  98. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  99. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  100. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  101. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  102. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  103. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  104. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  105. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  106. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  107. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  108. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  109. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  110. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  111. package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  112. package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
  113. package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  114. package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  115. package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  116. package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
  117. package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  118. package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  119. package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  120. package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  121. package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  122. package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  123. package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  124. package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  125. package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  126. package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  127. package/kits/physics-2d/castle.json +1 -1
  128. package/kits/physics-2d/editors/SceneEditor.jsx +2 -1
  129. package/kits/physics-2d/engine/blueprint.js +29 -28
  130. package/kits/physics-2d/engine/ui.jsx +24 -0
  131. package/kits/physics-2d/engine/ui.module.css +5 -0
  132. package/kits/physics-2d/package-lock.json +1 -6
  133. package/package.json +3 -2
  134. package/dist/shell/assets/index-BJO7LVCM.js +0 -422
  135. package/dist/shell/assets/index-DfZmu3XC.css +0 -1
  136. package/kits/blank/.castle/agent/children.json +0 -1
  137. package/kits/blank/.castle/agent/messages.json +0 -9
  138. package/kits/blank/.castle/agent/pending-sends.json +0 -1
  139. package/kits/blank/.castle/agent/tasks/index.md +0 -2
  140. package/kits/blank/.castle/docs/platform.md +0 -36
  141. package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
  142. package/kits/blank/node_modules/.vite/deps/package.json +0 -3
@@ -0,0 +1,313 @@
1
+ import { chunked } from "./chunk";
2
+ import { decodeStorageValue, encodeStorageValue, storageError } from "./storageJson";
3
+ import { hostRequest } from "./transport";
4
+ import { onUnloadFlush } from "./unloadFlush";
5
+ // Per-key deck storage for Cauldron decks.
6
+ //
7
+ // The older Storage/SharedStorage keep one document per bucket and rewrite the
8
+ // whole thing on every change, which loses concurrent writes and stops at 2 MB.
9
+ // This keeps one row per key instead: two players writing different keys no
10
+ // longer overwrite each other, a counter can be incremented atomically, and a
11
+ // deck can hold far more than one document's worth and read back a slice of it.
12
+ //
13
+ // Every operation here is a bounded request. A deck never supplies a filter or
14
+ // an ordering, which is what lets the platform promise that no deck can make the
15
+ // database do expensive work.
16
+ // Writes coalesce by key for this long before being sent, so a deck that saves
17
+ // on every change costs one request per burst rather than one per change.
18
+ const FLUSH_INTERVAL_MS = 200;
19
+ // The platform takes at most this many keys per call. A buffer that coalesced
20
+ // past it goes out as several requests rather than as one the server rejects,
21
+ // so a deck that saves many small keys in a burst never has to know the limit.
22
+ const MAX_KEYS_PER_REQUEST = 32;
23
+ const buckets = new Map();
24
+ function bucketKey(scope, subject) {
25
+ return `${scope}|${subject ?? "self"}`;
26
+ }
27
+ function pendingBucket(scope, subject) {
28
+ const id = bucketKey(scope, subject);
29
+ let bucket = buckets.get(id);
30
+ if (!bucket) {
31
+ bucket = {
32
+ scope,
33
+ subject,
34
+ values: new Map(),
35
+ waiters: [],
36
+ timer: null,
37
+ inFlight: Promise.resolve(),
38
+ pending: 0,
39
+ };
40
+ buckets.set(id, bucket);
41
+ }
42
+ return bucket;
43
+ }
44
+ function queueWrite(scope, subject, values, unload = false) {
45
+ const bucket = pendingBucket(scope, subject);
46
+ for (const [key, value] of values)
47
+ bucket.values.set(key, value);
48
+ const settled = new Promise((resolve, reject) => {
49
+ bucket.waiters.push({ keys: Array.from(values.keys()), resolve, reject });
50
+ });
51
+ // A stable reference, so registering on every write leaves one handler.
52
+ onUnloadFlush(flushAllNow);
53
+ if (unload) {
54
+ void flushBucket(bucket, true);
55
+ }
56
+ else if (!bucket.timer) {
57
+ bucket.timer = setTimeout(() => {
58
+ bucket.timer = null;
59
+ void flushBucket(bucket, false);
60
+ }, FLUSH_INTERVAL_MS);
61
+ }
62
+ return settled;
63
+ }
64
+ // Never rejects: a failed request is reported to the waiters whose keys it
65
+ // carried, which is what the deck is holding. Callers can `void` it safely.
66
+ function flushBucket(bucket, unload) {
67
+ bucket.pending += 1;
68
+ // An unload flush does not wait its turn. Queueing it behind a request that
69
+ // may not come back before the frame does would lose the last save outright,
70
+ // and the host finishes an `unload` write with fetch keepalive, so what
71
+ // matters is that the message reaches it at all. The cost is that this one
72
+ // write can race the request already in flight: if they touch the same key
73
+ // and land out of order, the older value stays stored. Ordering that
74
+ // correctly needs a revision token the server checks, which does not exist
75
+ // yet -- a stale key beats a lost one until it does.
76
+ const run = unload
77
+ ? guarded(sendBucket(bucket, true))
78
+ : guarded(bucket.inFlight.then(() => sendBucket(bucket, false)));
79
+ // Later flushes queue behind this one either way, so only the unload write
80
+ // itself skips the queue. Counting it in `pending` matters as much: a bucket
81
+ // dropped while its request is still out would let the next write build a
82
+ // second bucket for the same scope, and the two would flush concurrently.
83
+ bucket.inFlight = Promise.all([bucket.inFlight, run]).then(() => {
84
+ bucket.pending -= 1;
85
+ pruneBucket(bucket);
86
+ });
87
+ return run;
88
+ }
89
+ // A rejection must never reach `inFlight`. The chain is built with `then`, so a
90
+ // rejected link makes every later flush for this bucket skip its send and
91
+ // reject in turn: the scope stops writing, permanently and silently. Failed
92
+ // requests are already reported to their waiters, so anything arriving here is
93
+ // a bug in this file rather than a write that did not land.
94
+ function guarded(run) {
95
+ return run.catch(reportWriteError);
96
+ }
97
+ function reportWriteError(error) {
98
+ console.warn("Castle store flush failed unexpectedly", error);
99
+ }
100
+ async function sendBucket(bucket, unload) {
101
+ // Take the buffer before awaiting: writes made while this request is in flight
102
+ // belong to the next one, not to this one's waiters.
103
+ const values = bucket.values;
104
+ const waiters = bucket.waiters;
105
+ bucket.values = new Map();
106
+ bucket.waiters = [];
107
+ if (bucket.timer) {
108
+ clearTimeout(bucket.timer);
109
+ bucket.timer = null;
110
+ }
111
+ if (values.size === 0 && waiters.length === 0)
112
+ return;
113
+ const entries = [];
114
+ const removals = [];
115
+ for (const [key, value] of values) {
116
+ if (value === null)
117
+ removals.push(key);
118
+ else
119
+ entries.push({ key, value });
120
+ }
121
+ // Which keys failed to store, and why. Set and delete never share a key here:
122
+ // a key written and then removed inside one window is a single null in
123
+ // `values`, so the two lists are disjoint and their outcomes independent.
124
+ const failures = new Map();
125
+ // Anything escaping the per-request catch is a bug, not a write that failed.
126
+ // It still has to reach the waiters: an unsettled one is a deck awaiting a
127
+ // promise that will never resolve.
128
+ let unexpected = null;
129
+ try {
130
+ for (const request of buildRequests(bucket, entries, removals, unload)) {
131
+ try {
132
+ await request.send();
133
+ }
134
+ catch (error) {
135
+ for (const key of request.keys)
136
+ failures.set(key, error);
137
+ }
138
+ }
139
+ }
140
+ catch (error) {
141
+ unexpected = error;
142
+ }
143
+ for (const waiter of waiters) {
144
+ if (unexpected !== null) {
145
+ waiter.reject(unexpected);
146
+ continue;
147
+ }
148
+ // `find`, not `some`: the first failing key supplies the error the deck sees.
149
+ const failed = waiter.keys.find((key) => failures.has(key));
150
+ // A caller that contributed no keys -- `set({})`, `remove([])` -- has nothing
151
+ // that can fail, and must still be settled rather than left hanging.
152
+ if (failed === undefined)
153
+ waiter.resolve();
154
+ else
155
+ waiter.reject(failures.get(failed));
156
+ }
157
+ }
158
+ function buildRequests(bucket, entries, removals, unload) {
159
+ const requests = [];
160
+ // Removals go first: within one window a key that was set and then removed
161
+ // should end up removed, and sending the set afterwards would resurrect it.
162
+ for (const keys of chunked(removals, MAX_KEYS_PER_REQUEST)) {
163
+ requests.push({
164
+ keys,
165
+ send: () => hostRequest("cauldronStorage.delete", {
166
+ scope: bucket.scope,
167
+ subject: bucket.subject,
168
+ keys,
169
+ unload,
170
+ }),
171
+ });
172
+ }
173
+ for (const chunk of chunked(entries, MAX_KEYS_PER_REQUEST)) {
174
+ requests.push({
175
+ keys: chunk.map((entry) => entry.key),
176
+ send: () => hostRequest("cauldronStorage.set", {
177
+ scope: bucket.scope,
178
+ subject: bucket.subject,
179
+ entries: chunk,
180
+ unload,
181
+ }),
182
+ });
183
+ }
184
+ return requests;
185
+ }
186
+ // A deck that reads many players' buckets would otherwise leave one empty entry
187
+ // per user id behind for the life of the page.
188
+ function pruneBucket(bucket) {
189
+ if (bucket.pending > 0 ||
190
+ bucket.values.size > 0 ||
191
+ bucket.waiters.length > 0 ||
192
+ bucket.timer) {
193
+ return;
194
+ }
195
+ const id = bucketKey(bucket.scope, bucket.subject);
196
+ if (buckets.get(id) === bucket)
197
+ buckets.delete(id);
198
+ }
199
+ function flushAllNow() {
200
+ for (const bucket of buckets.values()) {
201
+ // Nothing awaits these: the page is going away. The host is what finishes
202
+ // the request, and it outlives the deck's frame.
203
+ void flushBucket(bucket, true);
204
+ }
205
+ }
206
+ // ---------------------------------------------------------------------------
207
+ function assertKeys(keys, operation) {
208
+ if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
209
+ throw storageError("CASTLE_STORE_INVALID_KEYS", "Store keys must be an array of strings.", operation);
210
+ }
211
+ return keys;
212
+ }
213
+ function createScope(scope, subject) {
214
+ return {
215
+ async get(keys) {
216
+ const { entries } = await hostRequest("cauldronStorage.get", {
217
+ scope,
218
+ subject,
219
+ keys: assertKeys(keys, "Store.get"),
220
+ });
221
+ const result = {};
222
+ for (const entry of entries) {
223
+ // defineProperty rather than assignment: a stored key named "__proto__"
224
+ // would otherwise reach the prototype setter instead of becoming an own
225
+ // property, corrupting the object handed back to the deck.
226
+ Object.defineProperty(result, entry.key, {
227
+ value: decodeStorageValue(entry.value, "Store.get"),
228
+ writable: true,
229
+ enumerable: true,
230
+ configurable: true,
231
+ });
232
+ }
233
+ return result;
234
+ },
235
+ set(values) {
236
+ const pending = new Map();
237
+ for (const [key, value] of Object.entries(values)) {
238
+ pending.set(key, encodeStorageValue(value, "Store.set"));
239
+ }
240
+ return queueWrite(scope, subject, pending);
241
+ },
242
+ remove(keys) {
243
+ const pending = new Map();
244
+ for (const key of assertKeys(keys, "Store.remove"))
245
+ pending.set(key, null);
246
+ return queueWrite(scope, subject, pending);
247
+ },
248
+ async increment(key, delta = 1) {
249
+ // Not coalesced. Merging increments locally would mean reporting a total
250
+ // the server has not agreed to, and the point of this verb is that the
251
+ // server is the one doing the adding.
252
+ const { value } = await hostRequest("cauldronStorage.increment", {
253
+ scope,
254
+ subject,
255
+ key,
256
+ delta,
257
+ });
258
+ return Number(value);
259
+ },
260
+ async list(options = {}) {
261
+ const { entries, cursor } = await hostRequest("cauldronStorage.list", {
262
+ scope,
263
+ subject,
264
+ prefix: options.prefix ?? null,
265
+ limit: options.limit ?? null,
266
+ cursor: options.cursor ?? null,
267
+ });
268
+ return {
269
+ entries: entries.map((entry) => ({
270
+ key: entry.key,
271
+ value: decodeStorageValue(entry.value, "Store.list"),
272
+ })),
273
+ cursor,
274
+ };
275
+ },
276
+ };
277
+ }
278
+ function createBoard(name) {
279
+ return {
280
+ async submit(score) {
281
+ const { entry } = await hostRequest("cauldronStorage.boardSubmit", {
282
+ board: name,
283
+ score,
284
+ });
285
+ return entry;
286
+ },
287
+ async top(limit) {
288
+ const { entries } = await hostRequest("cauldronStorage.boardTop", {
289
+ board: name,
290
+ limit: limit ?? null,
291
+ });
292
+ return entries;
293
+ },
294
+ async get(userId) {
295
+ const { entry } = await hostRequest("cauldronStorage.boardGet", {
296
+ board: name,
297
+ subject: userId ?? null,
298
+ });
299
+ return entry;
300
+ },
301
+ };
302
+ }
303
+ export const Store = {
304
+ deck: createScope("deck", null),
305
+ me: createScope("user", null),
306
+ user(userId) {
307
+ return createScope("user", userId);
308
+ },
309
+ private: createScope("private", null),
310
+ board(name) {
311
+ return createBoard(name);
312
+ },
313
+ };
@@ -0,0 +1,3 @@
1
+ type FlushHandler = () => void;
2
+ export declare function onUnloadFlush(handler: FlushHandler): void;
3
+ export {};
@@ -0,0 +1,30 @@
1
+ // Somewhere to hang "flush before the page goes away".
2
+ //
3
+ // Writes batch on a timer, so leaving the page inside that window would lose
4
+ // them, and a deck saving progress as someone quits is exactly when it matters.
5
+ // `pagehide` is the reliable signal on iOS, where unload often never fires, and
6
+ // visibilitychange covers backgrounding without a navigation.
7
+ //
8
+ // Listeners are registered on the first write, so a deck that never stores
9
+ // anything hooks nothing.
10
+ //
11
+ // Handlers are held in a Set, so registering on every write is fine as long as
12
+ // the caller passes a STABLE function reference. A fresh closure per call would
13
+ // accumulate, and every one of them would run at unload.
14
+ const handlers = new Set();
15
+ let hooked = false;
16
+ export function onUnloadFlush(handler) {
17
+ handlers.add(handler);
18
+ if (hooked || typeof window === "undefined")
19
+ return;
20
+ hooked = true;
21
+ const flushAll = () => {
22
+ for (const flush of handlers)
23
+ flush();
24
+ };
25
+ window.addEventListener("pagehide", flushAll);
26
+ document.addEventListener("visibilitychange", () => {
27
+ if (document.visibilityState === "hidden")
28
+ flushAll();
29
+ });
30
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "blank",
3
+ "lockfileVersion": 3,
4
+ "requires": true,
5
+ "packages": {
6
+ "node_modules/castle-web-fonts": {
7
+ "version": "1.0.0",
8
+ "resolved": "https://registry.npmjs.org/castle-web-fonts/-/castle-web-fonts-1.0.0.tgz",
9
+ "integrity": "sha512-amFts4vVJjaXKNQkh2DMMmxYHafCYczAOvme70n+0WX8fsTqJACh6r6MzND94l89Q6LFoIyrCm+cLh3S1Usy0w==",
10
+ "license": "SEE LICENSE IN licenses/FONTS.md"
11
+ }
12
+ }
13
+ }
@@ -0,0 +1,114 @@
1
+ # castle-web-fonts
2
+
3
+ The nine typefaces the Castle Classic engine gives its text tool, as web fonts
4
+ a Castle deck can use. Same faces, same names: a deck asking for `Piazzolla`
5
+ here gets what a Classic card asking for `Piazzolla` gets.
6
+
7
+ ```js
8
+ import { installTektur } from 'castle-web-fonts';
9
+
10
+ installTektur(); // now: font-family: 'Tektur'
11
+ ```
12
+
13
+ Install what you name, then use the family name in CSS. Two or three faces is
14
+ normal — one for body and UI, one display face for titles.
15
+
16
+ ## The faces
17
+
18
+ | face | character | good for | woff2 |
19
+ |---|---|---|---:|
20
+ | `DMSans` | clean geometric sans, low contrast | body, UI, HUD | 27 KB |
21
+ | `Piazzolla` | sturdy text serif, readable at length | body text, narrative, prose-heavy decks | 81 KB |
22
+ | `CourierPrime` | monospace typewriter serif | code, terminals, typewriter effects | 28 KB |
23
+ | `Tektur` | condensed squarish techno | sci-fi, arcade, HUD numerals | 31 KB |
24
+ | `Bore` | very heavy wide grotesque | impact headlines, scores, big titles | 12 KB |
25
+ | `Synco` | light wide geometric, unusual joins | retro-modernist titles | 12 KB |
26
+ | `Glacier` | slanted condensed hand-cut italic | informal, energetic display | 13 KB |
27
+ | `HelicoCentrica` | blackletter-flavored roman, pointed serifs | medieval, fantasy, ornate | 78 KB |
28
+ | `YatraOne` | high-contrast brushy display (also Devanagari) | bold headlines, South Asian text | 89 KB |
29
+
30
+ Each has one weight and one style, as in Classic. Ask for bold or italic and the
31
+ browser synthesizes it.
32
+
33
+ ## `install<Face>(): Promise<string>`
34
+
35
+ Registers the face and resolves with its CSS family name. Idempotent — repeat
36
+ calls return the first call's promise, so calling it from several modules is
37
+ fine.
38
+
39
+ The bytes are a `data:` URI inside the module, so there is no network fetch: no
40
+ CORS, no round trip, nothing to go wrong offline, and the face is available on
41
+ the first frame. That matters because a published deck is a single HTML file
42
+ served from an origin that is never castle.xyz — `castle-deck://` in the iOS
43
+ app, `*.decks.castle.games` on Android.
44
+
45
+ **Awaiting it matters before drawing to a canvas.** Canvas 2D does not trigger a
46
+ font load, so `ctx.font = '20px Piazzolla'` before the face is ready silently
47
+ falls back to the default and never repaints when the font arrives:
48
+
49
+ ```js
50
+ import { installPiazzolla } from 'castle-web-fonts';
51
+
52
+ const family = await installPiazzolla();
53
+ ctx.font = `20px ${family}`;
54
+ ```
55
+
56
+ In CSS it matters less — the browser reflows when the face lands.
57
+
58
+ ## `FACES`, `FACE_NAMES`, `faceInfo(name)`
59
+
60
+ The catalog: each face's `name`, `label`, `character`, `goodFor`, `credit`,
61
+ `copyright`, `url`, and `license`. **Metadata only — no font bytes**, so a font
62
+ picker can list every face without pulling any of them into the bundle.
63
+
64
+ ## One named export per face, never a lookup
65
+
66
+ A deck pays for exactly the faces it names, because each face is a named export
67
+ backed by its own module and there is no other way to reach the bytes. Adding a
68
+ tenth face, or a fiftieth, costs every existing deck zero.
69
+
70
+ That property is fragile and worth stating plainly:
71
+
72
+ ```js
73
+ // Fine. Inlines Tektur, 41 KB.
74
+ import { installTektur } from 'castle-web-fonts';
75
+
76
+ // NOT fine. Inlines all nine, 495 KB, in every deck that does this.
77
+ const FONTS = { Tektur: installTektur, Bore: installBore, /* ... */ };
78
+ FONTS[themeName]();
79
+ ```
80
+
81
+ No bundler can prove which key a lookup reads, so it keeps every face. Declaring
82
+ `"sideEffects": false` does not rescue it. `npm run check` builds a real
83
+ single-file bundle and counts the inlined faces, so a regression fails there
84
+ rather than in someone's deck.
85
+
86
+ If a font name has to come from data — a theme file, a saved setting — resolve
87
+ that name to an `install` call at build time, not at runtime. The physics-2d kit
88
+ does this by generating a one-line module when the deck's font is picked.
89
+
90
+ ## Licensing
91
+
92
+ Eight faces are [OFL 1.1](licenses/OFL-1.1.txt), which permits woff2 conversion
93
+ and redistribution. Bore is [CC BY-ND 4.0](licenses/CC-BY-ND-4.0.txt), where
94
+ conversion is a permitted technical modification under §2(a)(4) — but
95
+ **subsetting Bore is not**, since dropping glyphs makes a derivative work. It is
96
+ 12 KB whole.
97
+
98
+ Per-face notices, verbatim from each font's own name table, are in
99
+ [licenses/FONTS.md](licenses/FONTS.md).
100
+
101
+ ## Development
102
+
103
+ `woff2/*.woff2` are converted from the TrueType files in a `ghost` checkout
104
+ (`core/assets/`), which is where the C++ engine bakes them in from — those are
105
+ the source of truth for which faces exist:
106
+
107
+ ```bash
108
+ npm run convert -- --ghost ../../ghost # ttf -> woff2/
109
+ npm run build # woff2/ -> dist/
110
+ npm run check # lint + build + bundle-size invariant
111
+ ```
112
+
113
+ `convert` is deliberately not part of the build: a ghost checkout is not
114
+ something a `castle-web-fonts` build may assume.
@@ -0,0 +1,18 @@
1
+ export interface CastleFace {
2
+ /** CSS family name, e.g. 'Piazzolla'. Also the `install<Name>` suffix and the `woff2/<Name>.woff2` stem. */
3
+ name: string;
4
+ /** Human name, e.g. 'Courier Prime'. */
5
+ label: string;
6
+ /** Source filename in a ghost checkout's core/assets/. */
7
+ ttf: string;
8
+ /** What the face looks like, in a phrase. */
9
+ character: string;
10
+ /** What it suits. */
11
+ goodFor: string;
12
+ /** Designer / foundry attribution. */
13
+ credit: string;
14
+ license: 'OFL-1.1' | 'CC-BY-ND-4.0';
15
+ }
16
+ export declare const FACES: CastleFace[];
17
+ export declare const FACE_NAMES: string[];
18
+ export declare function faceInfo(name: string): CastleFace | undefined;
@@ -0,0 +1,142 @@
1
+ // The nine faces the Castle Classic engine offers its text tool, as web fonts.
2
+ //
3
+ // This list is the package: everything else -- the per-face modules, the woff2
4
+ // conversion, the docs table -- is generated from or checked against it. The
5
+ // `name` of a face is three things at once, deliberately: its CSS family, the
6
+ // suffix of its `install<Name>` export, and the stem of its `woff2/<Name>.woff2`
7
+ // file. They match Classic's own registry names (ghost/core/src/behaviors/
8
+ // text_fonts.cpp), so a deck asking for `Piazzolla` here gets the same face a
9
+ // Classic card asking for `Piazzolla` gets.
10
+ //
11
+ // `character` and `goodFor` are what an agent picking a face reads instead of
12
+ // seeing a specimen, and what the physics-2d picker prints on its cards. Keep
13
+ // them one short phrase each.
14
+ //
15
+ // This module carries NO font bytes, so importing it costs a deck nothing --
16
+ // the picker UI and the docs generator both want the metadata alone.
17
+
18
+ /**
19
+ * @typedef {object} CastleFace
20
+ * @property {string} name CSS family name, e.g. 'Piazzolla'.
21
+ * @property {string} label Human name, e.g. 'Courier Prime'.
22
+ * @property {string} ttf Source filename in a ghost checkout's core/assets/.
23
+ * @property {string} character What the face looks like, in a phrase.
24
+ * @property {string} goodFor What it suits.
25
+ * @property {string} credit Designer / foundry attribution.
26
+ * @property {'OFL-1.1' | 'CC-BY-ND-4.0'} license
27
+ * @property {string} copyright The notice embedded in the font's own name table, verbatim.
28
+ * @property {string} url Where the face is published.
29
+ */
30
+
31
+ /** @type {CastleFace[]} */
32
+ export const FACES = [
33
+ {
34
+ name: 'DMSans',
35
+ label: 'DM Sans',
36
+ ttf: 'DMSans-Medium.ttf',
37
+ character: 'clean geometric sans, low contrast',
38
+ goodFor: 'body, UI, HUD',
39
+ credit: 'Colophon Foundry',
40
+ license: 'OFL-1.1',
41
+ copyright: "Copyright 2014-2017 Indian Type Foundry (info@indiantypefoundry.com) with Reserved Font Name 'Poppins'. Copyright 2019 Google LLC.",
42
+ url: 'https://github.com/googlefonts/dm-fonts',
43
+ },
44
+ {
45
+ name: 'Piazzolla',
46
+ label: 'Piazzolla',
47
+ ttf: 'Piazzolla.ttf',
48
+ character: 'sturdy text serif, readable at length',
49
+ goodFor: 'body text, narrative, prose-heavy decks',
50
+ credit: 'Juan Pablo del Peral for Huerta Tipográfica',
51
+ license: 'OFL-1.1',
52
+ copyright: 'Copyright 2018 The Piazzolla Project Authors (https://github.com/huertatipografica/piazzolla)',
53
+ url: 'https://github.com/huertatipografica/piazzolla',
54
+ },
55
+ {
56
+ name: 'CourierPrime',
57
+ label: 'Courier Prime',
58
+ ttf: 'CourierPrime-Regular.ttf',
59
+ character: 'monospace typewriter serif',
60
+ goodFor: 'code, terminals, typewriter effects',
61
+ credit: 'Alan Dague-Greene for John August',
62
+ license: 'OFL-1.1',
63
+ copyright: 'Copyright (c) 2013, Quote-Unquote Apps (http://quoteunquoteapps.com), with Reserved Font Name Courier Prime.',
64
+ url: 'https://quoteunquoteapps.com/courierprime/',
65
+ },
66
+ {
67
+ name: 'Tektur',
68
+ label: 'Tektur',
69
+ ttf: 'Tektur.ttf',
70
+ character: 'condensed squarish techno',
71
+ goodFor: 'sci-fi, arcade, HUD numerals',
72
+ credit: 'Adam Jagosz',
73
+ license: 'OFL-1.1',
74
+ copyright: 'Copyright 2020 The Tektur Project Authors (https://www.github.com/hyvyys/Tektur)',
75
+ url: 'https://github.com/hyvyys/Tektur',
76
+ },
77
+ {
78
+ name: 'Bore',
79
+ label: 'Bore',
80
+ ttf: 'Bore.ttf',
81
+ character: 'very heavy wide grotesque',
82
+ goodFor: 'impact headlines, scores, big titles',
83
+ credit: 'Austin Stahl',
84
+ license: 'CC-BY-ND-4.0',
85
+ copyright: 'Copyright © 2021 by Austin Stahl. All rights reserved.',
86
+ url: 'https://www.austinstahl.com/bore-download',
87
+ },
88
+ {
89
+ name: 'Synco',
90
+ label: 'Synco',
91
+ ttf: 'Synco.ttf',
92
+ character: 'light wide geometric, unusual joins',
93
+ goodFor: 'retro-modernist titles',
94
+ credit: 'Ariel Martín Pérez for Altiplano',
95
+ license: 'OFL-1.1',
96
+ copyright: 'Copyright © 2020 by Raphaël Verona | Altiplano Typefaces. All rights reserved.',
97
+ url: 'https://fontesk.com/synco-font/',
98
+ },
99
+ {
100
+ name: 'Glacier',
101
+ label: 'Glacier',
102
+ ttf: 'Glacier.ttf',
103
+ character: 'slanted condensed hand-cut italic',
104
+ goodFor: 'informal, energetic display',
105
+ credit: 'Quentin Juhel',
106
+ license: 'OFL-1.1',
107
+ copyright: 'Copyright (c) 2020, Quentin Juhel (https://juhel-quentin.fr), with Reserved Font Name Glacier.',
108
+ url: 'https://fontesk.com/glacier-typeface/',
109
+ },
110
+ {
111
+ name: 'HelicoCentrica',
112
+ label: 'Helico Centrica',
113
+ ttf: 'HelicoCentrica.ttf',
114
+ character: 'blackletter-flavored roman, pointed serifs',
115
+ goodFor: 'medieval, fantasy, ornate',
116
+ credit: 'Toby Le Rhone',
117
+ license: 'OFL-1.1',
118
+ copyright: 'Copyright (c) Toby le Rhone, 2015. No rights reserved.',
119
+ url: 'https://fontesk.com/helico-centrica-roman-font/',
120
+ },
121
+ {
122
+ name: 'YatraOne',
123
+ label: 'Yatra One',
124
+ ttf: 'YatraOne.ttf',
125
+ character: 'high-contrast brushy display (also Devanagari)',
126
+ goodFor: 'bold headlines, South Asian text',
127
+ credit: 'Catherine Leigh Schmidt',
128
+ license: 'OFL-1.1',
129
+ copyright: 'Copyright 2014 The Yatra Project Authors.',
130
+ url: 'https://github.com/cathschmidt/yatra-one',
131
+ },
132
+ ];
133
+
134
+ /** Every face's CSS family name, in catalog order. */
135
+ export const FACE_NAMES = FACES.map((face) => face.name);
136
+
137
+ /** One face's metadata by CSS family name, or undefined. Metadata only -- this
138
+ * cannot install anything, precisely because a name-keyed install would pull
139
+ * every face into the bundle (see the README). */
140
+ export function faceInfo(name) {
141
+ return FACES.find((face) => face.name === name);
142
+ }
@@ -0,0 +1 @@
1
+ export declare function installFace(family: string, source: string): Promise<string>;