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.
- package/dist/agent-prompts.d.ts +1 -0
- package/dist/agent-prompts.js +9 -3
- package/dist/agent.js +25 -1
- package/dist/api.d.ts +1 -1
- package/dist/api.js +14 -3
- package/dist/byo-auth.js +4 -5
- package/dist/castle-host/host.js +215 -0
- package/dist/devSessionServer.js +40 -3
- package/dist/devSessionStorage.js +155 -0
- package/dist/filesChanged.d.ts +23 -0
- package/dist/filesChanged.js +15 -9
- package/dist/ide.d.ts +3 -0
- package/dist/ide.js +37 -25
- package/dist/init.js +1 -1
- package/dist/paramsFile.d.ts +80 -0
- package/dist/paramsFile.js +516 -0
- package/dist/paramsRegisterPlugin.d.ts +3 -0
- package/dist/paramsRegisterPlugin.js +81 -0
- package/dist/paramsTunes.d.ts +44 -0
- package/dist/paramsTunes.js +200 -0
- package/dist/paramsWrites.d.ts +30 -0
- package/dist/paramsWrites.js +138 -0
- package/dist/platformDoc.d.ts +1 -1
- package/dist/platformDoc.js +6 -20
- package/dist/save-deck.js +9 -1
- package/dist/serve.js +23 -15
- package/dist/shell/assets/index-DJSLmPmw.js +449 -0
- package/dist/shell/assets/index-uXcYGwQC.css +1 -0
- package/dist/shell/index.html +2 -2
- package/dist/textHash.d.ts +2 -0
- package/dist/textHash.js +28 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/README.md +4 -0
- package/kits/base/sdk/castle.d.ts +4 -0
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/characters.d.ts +26 -0
- package/kits/base/sdk/characters.js +108 -0
- package/kits/base/sdk/commands.d.ts +70 -0
- package/kits/base/sdk/multiplayer.js +68 -0
- package/kits/base/sdk/paramsRegistry.d.ts +32 -0
- package/kits/base/sdk/paramsRegistry.js +100 -0
- package/kits/base/sdk/runtime.d.ts +7 -0
- package/kits/base/sdk/runtime.js +34 -0
- package/kits/base/sdk/server/storage.d.ts +77 -0
- package/kits/base/sdk/server/storage.js +272 -18
- package/kits/base/sdk/server/wrapper.d.ts +1 -1
- package/kits/physics-2d/behaviors/Collider.jsx +3 -3
- package/kits/physics-2d/behaviors/Joints.jsx +2 -2
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/editors/SceneEditor.jsx +5 -5
- package/kits/physics-2d/editors/pxArtTimeline.jsx +1 -1
- package/kits/physics-2d/editors/pxArtTimeline.module.css +73 -73
- package/kits/physics-2d/editors/themeEditor.module.css +17 -17
- package/kits/physics-2d/engine/castle-tokens.css +64 -0
- package/kits/physics-2d/engine/fields/fields.module.css +43 -37
- package/kits/physics-2d/engine/ui.jsx +1 -0
- package/kits/physics-2d/engine/ui.module.css +262 -288
- package/kits/physics-2d/package-lock.json +6 -1
- package/package.json +1 -1
- package/dist/shell/assets/index-MSHtKPXt.css +0 -1
- 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,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;
|