castle-web-cli 0.4.197 → 0.4.199

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 (62) hide show
  1. package/dist/agent-prompts.d.ts +1 -0
  2. package/dist/agent-prompts.js +9 -3
  3. package/dist/agent.js +25 -1
  4. package/dist/api.d.ts +1 -1
  5. package/dist/api.js +14 -3
  6. package/dist/byo-auth.js +4 -5
  7. package/dist/castle-host/host.js +215 -0
  8. package/dist/devSessionServer.js +40 -3
  9. package/dist/devSessionStorage.js +155 -0
  10. package/dist/filesChanged.d.ts +23 -0
  11. package/dist/filesChanged.js +15 -9
  12. package/dist/ide.d.ts +3 -0
  13. package/dist/ide.js +37 -25
  14. package/dist/init.js +1 -1
  15. package/dist/paramsFile.d.ts +80 -0
  16. package/dist/paramsFile.js +516 -0
  17. package/dist/paramsRegisterPlugin.d.ts +3 -0
  18. package/dist/paramsRegisterPlugin.js +81 -0
  19. package/dist/paramsTunes.d.ts +44 -0
  20. package/dist/paramsTunes.js +200 -0
  21. package/dist/paramsWrites.d.ts +30 -0
  22. package/dist/paramsWrites.js +138 -0
  23. package/dist/platformDoc.d.ts +1 -1
  24. package/dist/platformDoc.js +6 -20
  25. package/dist/save-deck.js +9 -1
  26. package/dist/serve.js +23 -15
  27. package/dist/shell/assets/index-DJSLmPmw.js +449 -0
  28. package/dist/shell/assets/index-uXcYGwQC.css +1 -0
  29. package/dist/shell/index.html +2 -2
  30. package/dist/textHash.d.ts +2 -0
  31. package/dist/textHash.js +28 -0
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/package-lock.json +1 -1
  34. package/kits/base/sdk/README.md +4 -0
  35. package/kits/base/sdk/castle.d.ts +4 -0
  36. package/kits/base/sdk/castle.js +2 -0
  37. package/kits/base/sdk/characters.d.ts +26 -0
  38. package/kits/base/sdk/characters.js +108 -0
  39. package/kits/base/sdk/commands.d.ts +70 -0
  40. package/kits/base/sdk/multiplayer.js +68 -0
  41. package/kits/base/sdk/paramsRegistry.d.ts +32 -0
  42. package/kits/base/sdk/paramsRegistry.js +100 -0
  43. package/kits/base/sdk/runtime.d.ts +7 -0
  44. package/kits/base/sdk/runtime.js +34 -0
  45. package/kits/base/sdk/server/storage.d.ts +77 -0
  46. package/kits/base/sdk/server/storage.js +272 -18
  47. package/kits/base/sdk/server/wrapper.d.ts +1 -1
  48. package/kits/physics-2d/behaviors/Collider.jsx +3 -3
  49. package/kits/physics-2d/behaviors/Joints.jsx +2 -2
  50. package/kits/physics-2d/castle.json +2 -2
  51. package/kits/physics-2d/editors/SceneEditor.jsx +5 -5
  52. package/kits/physics-2d/editors/pxArtTimeline.jsx +1 -1
  53. package/kits/physics-2d/editors/pxArtTimeline.module.css +73 -73
  54. package/kits/physics-2d/editors/themeEditor.module.css +17 -17
  55. package/kits/physics-2d/engine/castle-tokens.css +64 -0
  56. package/kits/physics-2d/engine/fields/fields.module.css +43 -37
  57. package/kits/physics-2d/engine/ui.jsx +1 -0
  58. package/kits/physics-2d/engine/ui.module.css +262 -288
  59. package/kits/physics-2d/package-lock.json +6 -1
  60. package/package.json +1 -1
  61. package/dist/shell/assets/index-MSHtKPXt.css +0 -1
  62. package/dist/shell/assets/index-yHGXRGlX.js +0 -449
@@ -0,0 +1,516 @@
1
+ // Reading and rewriting a deck file's `export const PARAMS = { ... }`.
2
+ //
3
+ // The whole point of the params view is that tweaking a constant should not
4
+ // mean putting a cursor in a text area, so everything here is in service of one
5
+ // rule: an edit is a SPLICE over the value's source range, never a reprint of
6
+ // the object. `text.slice(0, from) + next + text.slice(to)` leaves the comments,
7
+ // the formatting, the trailing commas and the several hundred lines that are
8
+ // not params byte-identical -- which is what keeps a tune from showing up as a
9
+ // diff someone has to review, in a file an agent is probably also editing.
10
+ //
11
+ // The parser is CodeMirror's own (`tsxLanguage`, the same one editorLanguage.ts
12
+ // hands the code editor for every JS dialect), so the params view can never
13
+ // disagree with the code view about what the file is, and no new dependency
14
+ // arrives to do it.
15
+ //
16
+ // Only literals are editable, plus the arithmetic that is a literal written the
17
+ // long way: `1 / 3`, `60 * 1000` and `Math.PI / 2` fold to the number they mean,
18
+ // because nothing in them can ever mean anything else. A value that NAMES
19
+ // something -- `speed: BASE * 2` -- is kept as a `readonly` slot showing its
20
+ // source, NOT dropped: a pane that silently omits half the object is worse than
21
+ // no pane, because you tune three of five constants and conclude the other two
22
+ // do not exist.
23
+ //
24
+ // An optional `PARAMS_META` sibling says how to render a value: a range, a step,
25
+ // a unit, a set of options, a file kind, a hint. It is READ and never written,
26
+ // so it has no offsets to maintain across a splice. It is parsed rather than
27
+ // evaluated, like everything else here, so every value in it must be a literal.
28
+ import { tsxLanguage } from '@codemirror/lang-javascript';
29
+ /** The name a file declares its tunable values under. */
30
+ export const PARAMS_NAME = 'PARAMS';
31
+ /** The optional sibling object that says how to RENDER them, keyed the same. */
32
+ export const PARAMS_META_NAME = 'PARAMS_META';
33
+ // The source extensions a `PARAMS` object can be read out of -- the same ones
34
+ // the shell parses as JS/TS. Not a kit's vocabulary: `export const PARAMS` is a
35
+ // JavaScript declaration, not a file type somebody declared.
36
+ export const PARAMS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx']);
37
+ // Deliberately looser than the parser below, which also accepts a `const PARAMS`
38
+ // that is never exported. A prefilter that were TIGHTER than the parser would
39
+ // drop files the panel can actually edit; every caller re-parses the candidates
40
+ // and discards the ones that only look like a match.
41
+ export const PARAMS_DECLARATION = /\bconst\s+PARAMS\b/;
42
+ export const EMPTY_PARAMS = { found: false, groups: [] };
43
+ // `deadZoneY` -> `Dead Zone Y`. Same rule as the kit's auto-inspector, so a
44
+ // param and a behavior prop with the same name read the same way.
45
+ export function humanizeKey(key) {
46
+ return key
47
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
48
+ .replace(/^./, (c) => c.toUpperCase())
49
+ .trim();
50
+ }
51
+ export function isHexColor(value) {
52
+ return (typeof value === 'string' && /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3}([0-9a-fA-F]{2})?)?$/.test(value));
53
+ }
54
+ // ── parsing ──────────────────────────────────────────────────────────────────
55
+ // The `export const <name> = {...}` object, or null. A bare `const` is accepted
56
+ // too: the convention is the exported form (and the empty state teaches that),
57
+ // but a file that declares one without exporting it plainly means the same
58
+ // thing, and refusing to show its params would just read as a bug.
59
+ function findObject(text, tree, name) {
60
+ for (let child = tree.firstChild; child; child = child.nextSibling) {
61
+ const decl = child.name === 'ExportDeclaration'
62
+ ? child.getChild('VariableDeclaration')
63
+ : child.name === 'VariableDeclaration'
64
+ ? child
65
+ : null;
66
+ const defined = decl?.getChild('VariableDefinition');
67
+ if (!defined || text.slice(defined.from, defined.to) !== name)
68
+ continue;
69
+ const object = decl?.getChild('ObjectExpression');
70
+ if (object)
71
+ return object;
72
+ }
73
+ return null;
74
+ }
75
+ // A property's key, for the forms that name one: `speed: 1` and `'speed': 1`.
76
+ // Anything else (a computed key, a spread) has no stable name to show.
77
+ function keyOf(text, node) {
78
+ const raw = text.slice(node.from, node.to);
79
+ if (node.name === 'PropertyDefinition')
80
+ return raw;
81
+ if (node.name === 'String')
82
+ return decodeString(raw)?.value ?? null;
83
+ return null;
84
+ }
85
+ // Where the value starts. A normal property has a `:` and the value follows it;
86
+ // a method (`fn() {...}`) and a shorthand (`{ speed }`) have none, and are shown
87
+ // as readonly over their whole source rather than pretended into a field.
88
+ function valueRangeOf(property) {
89
+ for (let child = property.firstChild; child; child = child.nextSibling) {
90
+ if (child.name !== ':')
91
+ continue;
92
+ const value = child.nextSibling;
93
+ return value ? { node: value, from: value.from } : null;
94
+ }
95
+ return null;
96
+ }
97
+ // Arithmetic over numbers is folded rather than left readonly, because a
98
+ // `1 / 3` or a `60 * 1000` is a value someone tunes, not a reference to
99
+ // anything: the file already says everything there is to know about it, and a
100
+ // third of the rows in a real deck were losing their field to a division.
101
+ //
102
+ // Evaluated here and never through `eval` or `new Function` -- the shell runs
103
+ // under the serve's CSP, and the narrowness is the point besides. An identifier
104
+ // has to STAY readonly: a name is the file saying the value is decided
105
+ // somewhere else, and folding it would put a number in the panel that the file
106
+ // does not contain.
107
+ const FOLD_OPS = new Map([
108
+ ['+', (a, b) => a + b],
109
+ ['-', (a, b) => a - b],
110
+ ['*', (a, b) => a * b],
111
+ ['/', (a, b) => a / b],
112
+ ['%', (a, b) => a % b],
113
+ ['**', (a, b) => a ** b],
114
+ ]);
115
+ // The two members of `Math` that are as fixed as a number is. `Math.PI / 2` is
116
+ // simply how a rotation gets written; every other member reads something.
117
+ const MATH_CONSTANTS = new Map([
118
+ ['PI', Math.PI],
119
+ ['E', Math.E],
120
+ ]);
121
+ function childrenOf(node) {
122
+ const out = [];
123
+ for (let child = node.firstChild; child; child = child.nextSibling)
124
+ out.push(child);
125
+ return out;
126
+ }
127
+ // May return a non-finite number (`1 / 0`); the caller decides what to do with
128
+ // one. Null means "not arithmetic over numbers", which is a different answer.
129
+ function foldNumber(text, node) {
130
+ if (node.name === 'Number')
131
+ return Number(text.slice(node.from, node.to));
132
+ if (node.name === 'ParenthesizedExpression') {
133
+ const inner = childrenOf(node).filter((child) => child.name !== '(' && child.name !== ')');
134
+ return inner.length === 1 ? foldNumber(text, inner[0]) : null;
135
+ }
136
+ if (node.name === 'UnaryExpression')
137
+ return foldUnary(text, node);
138
+ if (node.name === 'BinaryExpression')
139
+ return foldBinary(text, node);
140
+ if (node.name === 'MemberExpression')
141
+ return foldMathConstant(text, node);
142
+ return null;
143
+ }
144
+ function foldUnary(text, node) {
145
+ const [op, operand, ...rest] = childrenOf(node);
146
+ if (!op || !operand || rest.length > 0)
147
+ return null;
148
+ const sign = text.slice(op.from, op.to);
149
+ if (sign !== '-' && sign !== '+')
150
+ return null;
151
+ const value = foldNumber(text, operand);
152
+ if (value === null)
153
+ return null;
154
+ return sign === '-' ? -value : value;
155
+ }
156
+ function foldBinary(text, node) {
157
+ const [left, op, right, ...rest] = childrenOf(node);
158
+ if (!left || !op || !right || rest.length > 0)
159
+ return null;
160
+ const operator = text.slice(op.from, op.to);
161
+ const apply = FOLD_OPS.get(operator);
162
+ if (!apply)
163
+ return null;
164
+ // `2 ** 3 ** 2` is 512 in JS (`**` binds right) but lezer's tree nests it
165
+ // left, which would fold to 64. Left readonly rather than folded wrong.
166
+ if (operator === '**' && isPowerExpression(text, left))
167
+ return null;
168
+ const a = foldNumber(text, left);
169
+ const b = foldNumber(text, right);
170
+ return a === null || b === null ? null : apply(a, b);
171
+ }
172
+ function isPowerExpression(text, node) {
173
+ if (node.name !== 'BinaryExpression')
174
+ return false;
175
+ const op = childrenOf(node)[1];
176
+ return op !== undefined && text.slice(op.from, op.to) === '**';
177
+ }
178
+ function foldMathConstant(text, node) {
179
+ const [object, dot, name, ...rest] = childrenOf(node);
180
+ if (!object || !name || rest.length > 0 || dot?.name !== '.')
181
+ return null;
182
+ if (object.name !== 'VariableName' || text.slice(object.from, object.to) !== 'Math')
183
+ return null;
184
+ if (name.name !== 'PropertyName')
185
+ return null;
186
+ return MATH_CONSTANTS.get(text.slice(name.from, name.to)) ?? null;
187
+ }
188
+ // A number the file states outright, as opposed to one it works out. `-5` counts
189
+ // -- a negative default is simply how one is written -- so the only rows that
190
+ // carry `folded` are the ones whose field shows something their source does not.
191
+ function isWrittenOut(node) {
192
+ if (node.name === 'Number')
193
+ return true;
194
+ return node.name === 'UnaryExpression' && node.lastChild?.name === 'Number';
195
+ }
196
+ // What kind of field a value gets, from the value itself -- the same inference
197
+ // the kit's `AutoFields` does over a behavior's defaultProps.
198
+ function literalOf(text, node) {
199
+ const raw = text.slice(node.from, node.to);
200
+ if (node.name === 'BooleanLiteral')
201
+ return { kind: 'boolean', value: raw === 'true' };
202
+ if (node.name === 'String') {
203
+ const decoded = decodeString(raw);
204
+ if (!decoded)
205
+ return { kind: 'readonly' };
206
+ const kind = isHexColor(decoded.value) ? 'color' : 'string';
207
+ return { kind, value: decoded.value, quote: decoded.quote };
208
+ }
209
+ const value = foldNumber(text, node);
210
+ if (value === null || !Number.isFinite(value))
211
+ return { kind: 'readonly' };
212
+ const literal = { kind: 'number', value };
213
+ return isWrittenOut(node) ? literal : { ...literal, folded: true };
214
+ }
215
+ // Counted at parse rather than at click time: the row that links has the slot
216
+ // and nothing else, and a splice never adds a line (`encodeString` escapes every
217
+ // newline), so the number a slot is born with stays true for the file's life.
218
+ function lineOf(text, from) {
219
+ let line = 1;
220
+ for (let i = text.indexOf('\n'); i >= 0 && i < from; i = text.indexOf('\n', i + 1))
221
+ line += 1;
222
+ return line;
223
+ }
224
+ function slotFrom(text, property, key, prefix) {
225
+ const base = { id: prefix ? `${prefix}.${key}` : key, key, label: humanizeKey(key) };
226
+ const range = valueRangeOf(property);
227
+ // No `:` at all -- a method or a shorthand. Its source is the whole property.
228
+ if (!range?.node) {
229
+ return {
230
+ ...base,
231
+ kind: 'readonly',
232
+ source: text.slice(property.from, property.to),
233
+ from: property.from,
234
+ to: property.to,
235
+ line: lineOf(text, property.from),
236
+ };
237
+ }
238
+ const { node } = range;
239
+ return {
240
+ ...base,
241
+ ...literalOf(text, node),
242
+ source: text.slice(node.from, node.to),
243
+ from: node.from,
244
+ to: node.to,
245
+ line: lineOf(text, node.from),
246
+ };
247
+ }
248
+ // The properties of one object literal, in source order.
249
+ function propertiesOf(node) {
250
+ return childrenOf(node).filter((child) => child.name === 'Property');
251
+ }
252
+ // The `key: value` pairs of one object literal, skipping the properties that
253
+ // have no name or no value (a spread, a method, a shorthand).
254
+ function entriesOf(text, node) {
255
+ const out = [];
256
+ for (const property of propertiesOf(node)) {
257
+ const keyNode = property.firstChild;
258
+ const key = keyNode ? keyOf(text, keyNode) : null;
259
+ const value = valueRangeOf(property)?.node;
260
+ if (key !== null && value)
261
+ out.push({ key, value });
262
+ }
263
+ return out;
264
+ }
265
+ // Nesting stops at one level: a plain object directly under PARAMS becomes a
266
+ // titled group, and anything deeper is a readonly slot showing its source.
267
+ //
268
+ // DEFERRED, not settled. Nothing here constrains depth -- slots carry a dotted
269
+ // id and absolute offsets, and the splice is depth-agnostic, so recursing is
270
+ // about ten lines. What stops it is the renderer's flat two-column grid, whose
271
+ // label column is already only ~130px on a phone. Game constants cluster one
272
+ // level (`player`, `enemy`, `camera`) and nothing has wanted more yet.
273
+ //
274
+ // If you lift it: keep the flat list, give each group a `depth`, and indent only
275
+ // the group headers so rows stay on the one grid. Fix the ordering below in the
276
+ // same pass -- see "Deferred: nesting past one level" in 2026-aug-params.md.
277
+ export function parseParams(text) {
278
+ const top = tsxLanguage.parser.parse(text).topNode;
279
+ const object = findObject(text, top, PARAMS_NAME);
280
+ if (!object)
281
+ return EMPTY_PARAMS;
282
+ const root = [];
283
+ const groups = [];
284
+ for (const property of propertiesOf(object)) {
285
+ const keyNode = property.firstChild;
286
+ const key = keyNode ? keyOf(text, keyNode) : null;
287
+ if (key === null)
288
+ continue;
289
+ const value = valueRangeOf(property)?.node;
290
+ if (value?.name === 'ObjectExpression') {
291
+ const slots = propertiesOf(value).flatMap((inner) => {
292
+ const innerKey = inner.firstChild ? keyOf(text, inner.firstChild) : null;
293
+ return innerKey === null ? [] : [slotFrom(text, inner, innerKey, key)];
294
+ });
295
+ groups.push({ title: humanizeKey(key), slots });
296
+ continue;
297
+ }
298
+ root.push(slotFrom(text, property, key, ''));
299
+ }
300
+ // NOTE: this hoists every root-level scalar above every group, so the pane's
301
+ // order is not the file's when a group sits between two scalars. Fine while
302
+ // nesting is one level ("scalars, then sections"); revisit with depth.
303
+ const all = root.length > 0 ? [{ title: null, slots: root }, ...groups] : groups;
304
+ return withMeta(text, top, { found: true, groups: all });
305
+ }
306
+ // ── metadata ─────────────────────────────────────────────────────────────────
307
+ // One field's meta. Anything that is not a literal of the right type for its
308
+ // field is DROPPED rather than reported: `PARAMS_META` is an optional hint from
309
+ // a file the panel does not own, and a deck whose meta is half wrong should
310
+ // still get the half that reads.
311
+ function readMeta(text, object) {
312
+ const meta = {};
313
+ for (const { key, value } of entriesOf(text, object)) {
314
+ if (key === 'options') {
315
+ const options = readOptions(text, value);
316
+ if (options.length > 0)
317
+ meta.options = options;
318
+ continue;
319
+ }
320
+ const literal = literalOf(text, value).value;
321
+ if (typeof literal === 'number') {
322
+ if (key === 'min')
323
+ meta.min = literal;
324
+ else if (key === 'max')
325
+ meta.max = literal;
326
+ else if (key === 'step')
327
+ meta.step = literal;
328
+ }
329
+ else if (typeof literal === 'string') {
330
+ if (key === 'unit')
331
+ meta.unit = literal;
332
+ else if (key === 'file')
333
+ meta.file = literal;
334
+ else if (key === 'hint')
335
+ meta.hint = literal;
336
+ }
337
+ }
338
+ return meta;
339
+ }
340
+ function readOptions(text, node) {
341
+ if (node.name !== 'ArrayExpression')
342
+ return [];
343
+ const out = [];
344
+ for (let child = node.firstChild; child; child = child.nextSibling) {
345
+ const option = optionOf(text, child);
346
+ if (option)
347
+ out.push(option);
348
+ }
349
+ return out;
350
+ }
351
+ // `'easy'` and `{ value: 2, label: 'Two' }`. An entry with no usable `value` is
352
+ // dropped; a label defaults to the value, which is what a bare list means.
353
+ function optionOf(text, node) {
354
+ if (node.name === 'ObjectExpression') {
355
+ let value;
356
+ let label;
357
+ for (const entry of entriesOf(text, node)) {
358
+ const literal = literalOf(text, entry.value).value;
359
+ if (entry.key === 'value' && (typeof literal === 'string' || typeof literal === 'number')) {
360
+ value = literal;
361
+ }
362
+ else if (entry.key === 'label' && typeof literal === 'string')
363
+ label = literal;
364
+ }
365
+ return value === undefined ? null : { value, label: label ?? String(value) };
366
+ }
367
+ const literal = literalOf(text, node).value;
368
+ if (typeof literal === 'number' || typeof literal === 'string') {
369
+ return { value: literal, label: String(literal) };
370
+ }
371
+ return null;
372
+ }
373
+ // A slot's key path, minus its own key: the group it sits in, or null at the
374
+ // top level. Read off the id rather than tracked, so a key containing a dot
375
+ // still lands in the right place.
376
+ function groupKeyOf(slot) {
377
+ return slot.id === slot.key ? null : slot.id.slice(0, slot.id.length - slot.key.length - 1);
378
+ }
379
+ // Attach `PARAMS_META` entries to the slots they name. The slot decides how its
380
+ // meta object is read: under a group's key `{ speed: { max: 20 } }` is the
381
+ // group's slots' meta, and at the top level the same shape is one field's.
382
+ // Nothing here can tell those apart on its own, and it does not have to.
383
+ function withMeta(text, top, doc) {
384
+ const object = findObject(text, top, PARAMS_META_NAME);
385
+ if (!object)
386
+ return doc;
387
+ const entries = new Map(entriesOf(text, object).map((entry) => [entry.key, entry.value]));
388
+ const attach = (slot) => {
389
+ const group = groupKeyOf(slot);
390
+ const outer = entries.get(group ?? slot.key);
391
+ if (!outer || outer.name !== 'ObjectExpression')
392
+ return slot;
393
+ const node = group === null
394
+ ? outer
395
+ : entriesOf(text, outer).find((entry) => entry.key === slot.key)?.value;
396
+ if (!node || node.name !== 'ObjectExpression')
397
+ return slot;
398
+ const meta = readMeta(text, node);
399
+ return Object.keys(meta).length > 0 ? { ...slot, meta } : slot;
400
+ };
401
+ return { ...doc, groups: doc.groups.map((g) => ({ ...g, slots: g.slots.map(attach) })) };
402
+ }
403
+ // ── editing ──────────────────────────────────────────────────────────────────
404
+ function formatValue(slot, value) {
405
+ if (typeof value === 'boolean')
406
+ return value ? 'true' : 'false';
407
+ if (typeof value === 'number')
408
+ return Number.isFinite(value) ? String(value) : '0';
409
+ return encodeString(value, slot.quote ?? "'");
410
+ }
411
+ export function findSlot(doc, id) {
412
+ for (const group of doc.groups) {
413
+ for (const slot of group.slots)
414
+ if (slot.id === id)
415
+ return slot;
416
+ }
417
+ return null;
418
+ }
419
+ /**
420
+ * The same tuned slots with every `before` read off `doc` instead of off
421
+ * whatever the write was first built on.
422
+ *
423
+ * A write re-sent over somebody else's version did not move the value it set
424
+ * out to move. The marker answers "what did the person change this from", the
425
+ * router reads it, and a number the file never held is worse there than no
426
+ * entry at all -- so a slot the doc no longer has is dropped rather than
427
+ * carried forward on a guess.
428
+ */
429
+ export function rebaseTuned(tuned, doc) {
430
+ return tuned.flatMap((slot) => {
431
+ const found = findSlot(doc, slot.id);
432
+ return found?.value === undefined ? [] : [{ ...slot, before: found.value }];
433
+ });
434
+ }
435
+ // Splice one value and shift the offsets that moved, rather than re-parsing.
436
+ //
437
+ // A scrub fires a change per pointer move, so the doc has to stay exact without
438
+ // a parse each time -- and it can, because exactly one range changed: the edited
439
+ // slot takes the new text, every slot that started after it shifts by the length
440
+ // delta, and everything before is untouched.
441
+ export function editParam(text, doc, id, value) {
442
+ const slot = findSlot(doc, id);
443
+ if (!slot || slot.kind === 'readonly')
444
+ return { text, doc };
445
+ const source = formatValue(slot, value);
446
+ if (source === slot.source)
447
+ return { text, doc };
448
+ const nextText = text.slice(0, slot.from) + source + text.slice(slot.to);
449
+ const delta = source.length - (slot.to - slot.from);
450
+ const shift = (other) => {
451
+ // The splice put the tuned literal where the arithmetic was, so the row has
452
+ // no original source left to show beside its value.
453
+ if (other.id === slot.id) {
454
+ return { ...other, value, source, to: other.from + source.length, folded: undefined };
455
+ }
456
+ if (other.from < slot.from)
457
+ return other;
458
+ return { ...other, from: other.from + delta, to: other.to + delta };
459
+ };
460
+ return {
461
+ text: nextText,
462
+ doc: { found: true, groups: doc.groups.map((g) => ({ ...g, slots: g.slots.map(shift) })) },
463
+ };
464
+ }
465
+ // ── string literals ──────────────────────────────────────────────────────────
466
+ // A quoted string's value plus the quote it was written with. Returns null for
467
+ // anything that isn't a plain quoted literal (a template literal, or an escape
468
+ // sequence we would not round-trip), which makes it a readonly slot.
469
+ function decodeString(raw) {
470
+ const quote = raw[0];
471
+ if ((quote !== "'" && quote !== '"') || raw.length < 2 || raw[raw.length - 1] !== quote) {
472
+ return null;
473
+ }
474
+ const inner = raw.slice(1, -1);
475
+ if (!inner.includes('\\'))
476
+ return { value: inner, quote };
477
+ // Re-spell as JSON to decode the escapes: unescape `\'` (legal in a JS single-
478
+ // quoted string, invalid in JSON) and escape any bare `"` (the reverse).
479
+ let json = '';
480
+ for (let i = 0; i < inner.length; i += 1) {
481
+ const ch = inner[i];
482
+ if (ch === '\\') {
483
+ const next = inner[i + 1] ?? '';
484
+ json += next === "'" ? "'" : ch + next;
485
+ i += 1;
486
+ }
487
+ else if (ch === '"') {
488
+ json += '\\"';
489
+ }
490
+ else {
491
+ json += ch;
492
+ }
493
+ }
494
+ try {
495
+ return { value: JSON.parse(`"${json}"`), quote };
496
+ }
497
+ catch {
498
+ return null;
499
+ }
500
+ }
501
+ function encodeString(value, quote) {
502
+ let out = quote;
503
+ for (const ch of value) {
504
+ if (ch === '\\' || ch === quote)
505
+ out += `\\${ch}`;
506
+ else if (ch === '\n')
507
+ out += '\\n';
508
+ else if (ch === '\r')
509
+ out += '\\r';
510
+ else if (ch === '\t')
511
+ out += '\\t';
512
+ else
513
+ out += ch;
514
+ }
515
+ return out + quote;
516
+ }
@@ -0,0 +1,3 @@
1
+ import type { Plugin } from 'vite';
2
+ import type { TuneLedger } from './paramsTunes.js';
3
+ export declare function paramsRegisterPlugin(projectDir: string, ledger?: TuneLedger): Plugin;
@@ -0,0 +1,81 @@
1
+ // Dev-serve only: hands every module that declares `PARAMS` to the SDK, so a
2
+ // tuned value can reach the deck that is already running.
3
+ //
4
+ // Decks do not write this, and must not have to. The whole promise of the
5
+ // Parameters panel is that a number in a plain object is tunable with no
6
+ // ceremony around it, and a deck that had to import a registry to get live
7
+ // apply would be a deck where forgetting the import means a control that
8
+ // silently does nothing. So the serve appends the registration itself, to the
9
+ // module it already has in hand.
10
+ //
11
+ // Registered on the dev server's plugin list ONLY -- never on `bundle.ts`.
12
+ // A published deck has no serve broadcasting tunes at it, so the call would be
13
+ // dead weight in every shipped bundle, and the import would drag the SDK into
14
+ // decks that never referenced it.
15
+ import * as fs from 'fs';
16
+ import * as path from 'path';
17
+ import { FORKS_DIR, importedPathForFork } from './forks.js';
18
+ import { parseParams, PARAMS_DECLARATION, PARAMS_EXTS } from './paramsFile.js';
19
+ import { hasSdkProvider, SDK_PACKAGE } from './sdkResolve.js';
20
+ const SKIPPED_SEGMENTS = new Set(['node_modules', '.castle', '.git']);
21
+ // Namespace import and an optional call, rather than a named one: a deck still
22
+ // resolving `castle-web-sdk` to a version published before this existed would
23
+ // otherwise fail to link, and every module declaring PARAMS would 500.
24
+ function registration(rel) {
25
+ return (`\n;import * as __castleSdk from ${JSON.stringify(SDK_PACKAGE)};\n` +
26
+ `__castleSdk.registerParams?.(${JSON.stringify(rel)}, PARAMS);\n`);
27
+ }
28
+ export function paramsRegisterPlugin(projectDir, ledger) {
29
+ // Vite hands `transform` ids that have been through the real path, so a deck
30
+ // reached by a symlink -- a worktree, a macOS temp dir -- would compare every
31
+ // id against a root none of them start with and quietly register nothing.
32
+ let root = projectDir;
33
+ try {
34
+ root = fs.realpathSync(projectDir);
35
+ }
36
+ catch {
37
+ /* unreadable: the deck-relative test below refuses everything anyway */
38
+ }
39
+ // Asked per transform rather than remembered for the serve's lifetime: an
40
+ // import can arrive while the serve is up, and this only runs for a module
41
+ // that already parsed as declaring params.
42
+ const deckHasSdk = () => hasSdkProvider(root) || fs.existsSync(path.join(root, 'node_modules', SDK_PACKAGE));
43
+ return {
44
+ name: 'castle-params-register',
45
+ // Ahead of vite's own transform so the module is still the source the
46
+ // parser was written for, and so the appended import goes through normal
47
+ // resolution like any the deck wrote.
48
+ enforce: 'pre',
49
+ transform(code, id) {
50
+ const file = id.split('?')[0];
51
+ if (!PARAMS_EXTS.has(path.extname(file).toLowerCase()))
52
+ return null;
53
+ const rel = path.relative(root, file);
54
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
55
+ return null;
56
+ let posix = rel.split(path.sep).join('/');
57
+ // A fork stands in for the imported path EVERYWHERE else -- it is what the
58
+ // watcher announces and what the ledger and the panel key on -- so
59
+ // registering a forked module under `forks/...` would tie the deck's live
60
+ // object to a path no broadcast ever names.
61
+ if (posix.startsWith(`${FORKS_DIR}/`)) {
62
+ const imported = importedPathForFork(root, file);
63
+ if (!imported)
64
+ return null;
65
+ posix = path.relative(root, imported).split(path.sep).join('/');
66
+ }
67
+ if (posix.split('/').some((segment) => SKIPPED_SEGMENTS.has(segment)))
68
+ return null;
69
+ if (!PARAMS_DECLARATION.test(code))
70
+ return null;
71
+ if (!parseParams(code).found)
72
+ return null;
73
+ if (!deckHasSdk())
74
+ return null;
75
+ // The text the browser is about to be handed, which is what makes a later
76
+ // tune's chain start from something a frame is actually running.
77
+ ledger?.seed(posix, code);
78
+ return { code: code + registration(posix), map: null };
79
+ },
80
+ };
81
+ }
@@ -0,0 +1,44 @@
1
+ import type { TunedSlot } from './paramsWrites.js';
2
+ /**
3
+ * The slots that differ between two versions of a params file, or null when the
4
+ * difference is anything more than their values.
5
+ *
6
+ * The byte-identity check at the end is what makes this trustworthy: it is not
7
+ * enough that the same slots hold different numbers, because a file can gain a
8
+ * line of code in the same write. Re-applying only the differing slots to the
9
+ * disk text has to reproduce the incoming text exactly, or nothing is claimed.
10
+ */
11
+ export declare function diffTune(diskText: string, incomingText: string): TunedSlot[] | null;
12
+ export interface TuneLedger {
13
+ /** The text a frame just loaded, from the transform that handed it over. */
14
+ seed(rel: string, text: string): void;
15
+ /** Called on the way to disk; returns what this write tunes, or null. */
16
+ verify(rel: string, diskText: string, incomingText: string): TunedSlot[] | null;
17
+ /** Called once per broadcast entry; hands over the chain and clears it. */
18
+ claim(rel: string, event: 'add' | 'change' | 'delete'): TunedSlot[] | null;
19
+ }
20
+ export declare function createTuneLedger(deckDir: string): TuneLedger;
21
+ export type DeckWriteResult = {
22
+ ok: true;
23
+ path: string;
24
+ } | {
25
+ ok: false;
26
+ error: string;
27
+ conflict?: true;
28
+ };
29
+ /**
30
+ * The one place a whole-file write from an editor client lands.
31
+ *
32
+ * `ifMatch` is the fix for the clobber: the panel splices against the text it
33
+ * last read and skips external reloads while its own write is in flight, so a
34
+ * code save or an agent write landing inside a scrub window used to be
35
+ * overwritten silently. A caller that names the text it based its edit on gets
36
+ * a refusal instead, and can re-read and re-apply.
37
+ */
38
+ export declare function applyDeckWrite(opts: {
39
+ abs: string;
40
+ rel: string;
41
+ contents: string;
42
+ ifMatch?: string;
43
+ ledger?: TuneLedger;
44
+ }): DeckWriteResult;