castle-web-cli 0.4.251 → 0.4.253

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.
@@ -31,6 +31,19 @@ function anchor(value, box) {
31
31
  const x = /^translateX\(([^)]+)\)$/.exec(value ?? '');
32
32
  return [x ? pixels(x[1], box.width) : 0, 0];
33
33
  }
34
+ // The translate a node is drawn with: safe layout's (`safeStyle.js`, an
35
+ // `!important` rule over `--hub-safe-translate` while the node carries
36
+ // `data-hub-safe-translate`) outranks the inline one. Inline-only reads missed
37
+ // a safe-layout move made after the snapshot, so a moved act pill was read at
38
+ // its old place (review, Nov 19).
39
+ export function drawnTranslate(node) {
40
+ const style = node.style ?? {};
41
+ if (node.hasAttribute?.('data-hub-safe-translate') === true) {
42
+ const safe = style.getPropertyValue?.('--hub-safe-translate')?.trim();
43
+ if (safe && safe !== 'revert') {return safe;}
44
+ }
45
+ return style.translate;
46
+ }
34
47
  function shift(box, before, after, viewport) {
35
48
  const [bx, by = '0'] = (before.translate || '0 0').split(' ');
36
49
  const [ax, ay = '0'] = (after.translate || '0 0').split(' ');
@@ -190,7 +203,7 @@ export function makeLayoutCache() {
190
203
  rect: { left: box.left, right: box.right, top: box.top, bottom: box.bottom, width: box.width, height: box.height },
191
204
  size: { w: shown ? node.offsetWidth : 0, h: shown ? node.offsetHeight : 0 },
192
205
  offsets: { left: shown ? node.offsetLeft ?? 0 : 0, top: shown ? node.offsetTop ?? 0 : 0 },
193
- position: { left: style.left, top: style.top, translate: style.translate, transform: style.transform },
206
+ position: { left: style.left, top: style.top, translate: drawnTranslate(node), transform: style.transform },
194
207
  displayed: shown, frame,
195
208
  layout: !shown ? null : reuse ? previous.layout : layoutState(node),
196
209
  };
@@ -291,11 +304,15 @@ export function makeLayoutCache() {
291
304
  // These owned world layers have no transformed ancestors. Use their
292
305
  // snapshot size at the new pixel position, without another DOM read.
293
306
  if (!measured.displayed) {return measured.rect;}
294
- if (sources.get(node)?.positioned) {return shift(measured.rect, measured.position, node.style, viewport);}
307
+ const translate = drawnTranslate(node);
308
+ if (sources.get(node)?.positioned) {
309
+ const style = node.style ?? {};
310
+ return shift(measured.rect, measured.position, { left: style.left, top: style.top, transform: style.transform, translate }, viewport);
311
+ }
295
312
  // Caption and other surface translations can be restored after the
296
313
  // snapshot too; derive that move without re-reading their layout.
297
- return measured.position.translate !== node.style.translate
298
- ? shift(measured.rect, { translate: measured.position.translate }, { translate: node.style.translate }, viewport)
314
+ return measured.position.translate !== translate
315
+ ? shift(measured.rect, { translate: measured.position.translate }, { translate }, viewport)
299
316
  : measured.rect;
300
317
  },
301
318
  size: (node) => active ? read(node).size : { w: used(node).offsetWidth, h: node.offsetHeight },
@@ -61,7 +61,9 @@ export function worldPlacement(pointers, labels, controls, view, around = []) {
61
61
  const inside = (box) => box.left >= bounds.left && box.right <= bounds.right && box.top >= bounds.top && box.bottom <= bounds.bottom;
62
62
  const clear = (box, ignore) => !taken.some((other) => other !== ignore && overlaps(box, other));
63
63
  const labelBoxes = labels.map((box) => {
64
- let placed = inside(box) && clear(box, box.ignoreObstacle) ? box : null;
64
+ // An NPC's line always goes through `edgeSlot`, which owns its held far
65
+ // slot (a clear own slot is not taken back from a held far one there).
66
+ let placed = !box.edge && inside(box) && clear(box, box.ignoreObstacle) ? box : null;
65
67
  if (!placed && box.clamp) {
66
68
  const at = clampTo(box, bounds);
67
69
  const w = box.right - box.left, h = box.bottom - box.top;
@@ -73,7 +75,7 @@ export function worldPlacement(pointers, labels, controls, view, around = []) {
73
75
  placed = moves.filter((move) => inside(move) && clear(move, box.ignoreObstacle))
74
76
  .sort((a, b) => Math.hypot(a.left - box.left, a.top - box.top) - Math.hypot(b.left - box.left, b.top - box.top))[0] ?? null;
75
77
  } else if (!placed && box.edge) {
76
- placed = edgeSlot(box, bounds, taken, inside, clear);
78
+ placed = edgeSlot(box, bounds, taken, inside, clear, new Set(safeEdges));
77
79
  }
78
80
  if (placed) {taken.push(placed);}
79
81
  return placed;
@@ -83,33 +85,65 @@ export function worldPlacement(pointers, labels, controls, view, around = []) {
83
85
 
84
86
  // Where an NPC's line goes when its slid box is covered: the nearest clear
85
87
  // slot higher up (above its own Talk prompt, beside a reserved corner as
86
- // well if need be), then the nearest clear slot beside or below, then the same search
87
- // for its first line alone (`box.line` tall; the result carries `line: true`
88
- // and the chrome clips the rest). Slots stand 8 px off what they step around
89
- // and stay within a label's width, and twice its height, of where it was
90
- // slid to. Null when the anchor is off `bounds` or nothing is clear.
91
- function edgeSlot(box, bounds, taken, inside, clear) {
88
+ // well if need be), then the nearest clear slot beside or below, within a
89
+ // label's width, and twice its height, of where it was slid to. Then the
90
+ // nearest clear slot for the whole line anywhere in `bounds`: its words name
91
+ // their speaker, and a line drawn as its first line alone can be no more
92
+ // than that name (a barker's "Tally, the street barker:" on a 390 px phone,
93
+ // door-ui pass Nov 19). That far slot is chosen by distance alone, not
94
+ // above-first: above-first let a 0.2 px move of the anchor flip the line
95
+ // between a close slot below and a far one above (review, Nov 19). And it is
96
+ // held: `box.far` is the last far slot's offset from the slid box, kept while
97
+ // that place is still inside and clear, so a nearer slot opening up by a
98
+ // pixel does not move it either. The result carries `far: { dx, dy }` for
99
+ // the caller to hand back next time. Only then the near search for its first
100
+ // line alone (`box.line` tall; the result carries `line: true` and the
101
+ // chrome clips the rest). Slots stand 8 px off what they step around. Null
102
+ // when the anchor is off `bounds` or nothing is clear.
103
+ // Review round 2: a line in a held far slot stays there while that slot is
104
+ // clear, unless a near slot (its own or the near search's) is clear by
105
+ // FAR_RELEASE_PX on every side of what it would step around (the view's
106
+ // edges aside, which near slots are pinned against). So a line on the
107
+ // boundary does not flip near and far frame to frame: it goes far only when
108
+ // nothing near fits, and comes back only with room to spare.
109
+ const FAR_RELEASE_PX = 8;
110
+ function edgeSlot(box, bounds, taken, inside, clear, edges = new Set()) {
92
111
  const at = clampTo(box, bounds);
93
112
  if (!at) {return null;}
94
- if (inside(at) && clear(at, box.ignoreObstacle)) {return at;}
95
113
  const w = at.right - at.left, h = at.bottom - at.top;
96
- const reach = { left: at.left - w - 8, right: at.right + w + 8, top: at.top - 2 * h - 16, bottom: at.bottom + 2 * h + 16 };
97
- const near = taken.filter((other) => other !== box.ignoreObstacle && overlaps(other, reach));
98
- const lefts = [...new Set([at.left, bounds.left, bounds.right - w, ...near.flatMap((other) => [other.left - 8 - w, other.right + 8])])]
99
- .filter((left) => Math.abs(left - at.left) <= w + 8);
100
- const slot = (height) => {
114
+ const held = box.far && Number.isFinite(box.far.dx) && Number.isFinite(box.far.dy)
115
+ ? { left: at.left + box.far.dx, right: at.right + box.far.dx, top: at.top + box.far.dy, bottom: at.bottom + box.far.dy } : null;
116
+ const heldClear = Boolean(held && inside(held) && clear(held, box.ignoreObstacle));
117
+ const roomy = (move) => {
118
+ const m = FAR_RELEASE_PX;
119
+ const grown = { left: move.left - m, right: move.right + m, top: move.top - m, bottom: move.bottom + m };
120
+ return !taken.some((other) => other !== box.ignoreObstacle && !edges.has(other) && overlaps(grown, other));
121
+ };
122
+ const keepFar = (near) => heldClear && !(near && roomy(near));
123
+ if (inside(at) && clear(at, box.ignoreObstacle)) {
124
+ return keepFar(at) ? { ...held, far: box.far } : at;
125
+ }
126
+ const near = { left: at.left - w - 8, right: at.right + w + 8, top: at.top - 2 * h - 16, bottom: at.bottom + 2 * h + 16 };
127
+ const slot = (height, reach, byDistance = false) => {
128
+ const around = taken.filter((other) => other !== box.ignoreObstacle && overlaps(other, reach));
129
+ const lefts = [...new Set([at.left, bounds.left, bounds.right - w, ...around.flatMap((other) => [other.left - 8 - w, other.right + 8])])]
130
+ .filter((left) => left >= reach.left && left + w <= reach.right);
101
131
  const tops = [...new Set([at.top, at.bottom - height, bounds.top, bounds.bottom - height,
102
- ...near.flatMap((other) => [other.top - 8 - height, other.bottom + 8])])]
132
+ ...around.flatMap((other) => [other.top - 8 - height, other.bottom + 8])])]
103
133
  .filter((top) => top >= reach.top && top + height <= reach.bottom);
104
- const rank = (move) => [move.bottom < at.bottom - 0.5 ? 0 : 1, Math.hypot(move.left - at.left, move.bottom - at.bottom)];
134
+ const rank = (move) => [byDistance || move.bottom < at.bottom - 0.5 ? 0 : 1, Math.hypot(move.left - at.left, move.bottom - at.bottom)];
105
135
  return tops.flatMap((top) => lefts.map((left) => ({ left, right: left + w, top, bottom: top + height })))
106
136
  .filter((move) => inside(move) && clear(move, box.ignoreObstacle))
107
137
  .map((move) => ({ move, key: rank(move) }))
108
138
  .sort((a, b) => a.key[0] - b.key[0] || a.key[1] - b.key[1])[0]?.move ?? null;
109
139
  };
110
- const whole = slot(h);
111
- if (whole || !(box.line > 0 && box.line < h - 0.5)) {return whole;}
112
- const first = slot(box.line);
140
+ const nearWhole = slot(h, near);
141
+ if (keepFar(nearWhole)) {return { ...held, far: box.far };}
142
+ if (nearWhole) {return nearWhole;}
143
+ const far = slot(h, bounds, true);
144
+ if (far) {return { ...far, far: { dx: far.left - at.left, dy: far.top - at.top } };}
145
+ if (!(box.line > 0 && box.line < h - 0.5)) {return null;}
146
+ const first = slot(box.line, near);
113
147
  return first && { ...first, line: true };
114
148
  }
115
149
 
@@ -209,7 +243,8 @@ function surroundings(node, geometry) {
209
243
  }
210
244
 
211
245
  // `held(node)` is the box a control held before safe layout moved or hid it
212
- // (an act prompt): labels and pointers make way for that box, as before.
246
+ // (an act prompt): labels and pointers make way for that box, as before, and
247
+ // for the box it is drawn in now.
213
248
  export function makeWorldLayout(entries, view, obstacles = () => [], geometry = makeLayoutCache(), held = () => null) {
214
249
  const hidden = new Set();
215
250
  const shifted = new Map();
@@ -247,6 +282,8 @@ export function makeWorldLayout(entries, view, obstacles = () => [], geometry =
247
282
  };
248
283
  // NPC lines drawn as their first line alone: node -> its own clip-path.
249
284
  const clipped = new Map();
285
+ // NPC lines placed in a far slot: node -> its offset from the slid box.
286
+ const farSlots = new WeakMap();
250
287
  function unplace() {
251
288
  for (const node of hidden) {node.style.visibility = '';}
252
289
  for (const [node, value] of shifted) {node.style.translate = value;}
@@ -394,7 +431,10 @@ export function makeWorldLayout(entries, view, obstacles = () => [], geometry =
394
431
  const pointers = measured.filter((entry) => entry.kind === 'pointer' && entry.id !== 'stuck')
395
432
  .sort((a, b) => Number(b.id?.startsWith('pointer:goal:') === true) - Number(a.id?.startsWith('pointer:goal:') === true));
396
433
  const labels = measured.filter((entry) => entry.kind === 'label');
397
- const controls = measured.filter((entry) => (entry.kind !== 'pointer' || entry.id === 'stuck') && entry.kind !== 'label' && !held(entry.node)).map((entry) => entry.box)
434
+ // A moved act prompt is made way for twice: at the place it held (as
435
+ // before) and where it is drawn now, since it is painted over any label
436
+ // left under its new lane (Talk to Rowan over a barker's line).
437
+ const controls = measured.filter((entry) => (entry.kind !== 'pointer' || entry.id === 'stuck') && entry.kind !== 'label').map((entry) => entry.box)
398
438
  .concat(surfaces.map((entry) => held(entry.node)).filter(Boolean));
399
439
  const around = obstacles();
400
440
  // An NPC line's one-line form: the slot is its line box and both
@@ -411,7 +451,13 @@ export function makeWorldLayout(entries, view, obstacles = () => [], geometry =
411
451
  return top + line + (Number.parseFloat(style.paddingBottom) || 0);
412
452
  };
413
453
  const placements = worldPlacement(pointers.map((entry) => entry.box), labels.map(({ node, box, ignoreObstacle, clamp, edge }) => ignoreObstacle || clamp || edge
414
- ? { left: box.left, right: box.right, top: box.top, bottom: box.bottom, ignoreObstacle, clamp, edge, ...(edge ? { line: lineOf(node) } : {}) } : box), [...controls, ...around], view(), around);
454
+ ? { left: box.left, right: box.right, top: box.top, bottom: box.bottom, ignoreObstacle, clamp, edge,
455
+ ...(edge ? { line: lineOf(node), ...(farSlots.has(node) ? { far: farSlots.get(node) } : {}) } : {}) } : box), [...controls, ...around], view(), around);
456
+ // An NPC line's far slot is held across flushes (`edgeSlot`).
457
+ labels.forEach(({ node, edge }, index) => {
458
+ const far = edge ? placements.labels[index]?.far : null;
459
+ if (far) {farSlots.set(node, far);} else {farSlots.delete(node);}
460
+ });
415
461
  for (const [items, boxes] of [[pointers, placements.pointers], [labels, placements.labels]]) {
416
462
  items.forEach(({ node, box }, index) => {
417
463
  const placed = boxes[index];
@@ -1138,6 +1138,8 @@ function makeContext(h) {
1138
1138
  // A transport departure precedes real-time's physical removal. The
1139
1139
  // opted lifecycle must expose the same live roster as ordinary leave.
1140
1140
  if (h.arrivalPoses && !h.session?.players.some(p => p.playerId === playerId)) {continue;}
1141
+ // v1.229: a player told `away` is off the live roster until `back`.
1142
+ if (h.awayTold?.has(playerId) || h.awayGone?.has(playerId)) {continue;}
1141
1143
  out.push({
1142
1144
  playerId,
1143
1145
  username: usernameOf(h, playerId),
@@ -2060,6 +2062,9 @@ function reconcile(h) {
2060
2062
  for (const playerId of h.resumeKept?.keys() ?? []) {
2061
2063
  prepareResume(h, playerId);
2062
2064
  }
2065
+ for (const id of h.awayGone ?? []) {
2066
+ if (!h.sim.players.has(id) || h.session?.players.some((p) => p.playerId === id)) {h.awayGone.delete(id);}
2067
+ }
2063
2068
  for (const id of h.playerCells.keys()) {
2064
2069
  if (!h.sim.players.has(id)) {
2065
2070
  h.playerCells.delete(id);
@@ -2137,6 +2142,12 @@ function rememberResumePoses(h) {
2137
2142
  continue;
2138
2143
  }
2139
2144
  const previous = h.resumeKept.get(id);
2145
+ // v1.229: a player told `away` keeps their absence (and its deadline)
2146
+ // while real-time still holds the body, so a same-body return is `back`.
2147
+ if (previous?.awayAt !== undefined && h.awayTold?.has(id) &&
2148
+ !h.session?.players.some((player) => player.playerId === id)) {
2149
+ continue;
2150
+ }
2140
2151
  // v1.145: a resumePose place holds private state on this deadline too.
2141
2152
  if ((h.place.resumeVisibility === true || h.place.resumePose === true) && previous) {
2142
2153
  const rosterPresent = h.session?.players.some((player) => player.playerId === id) === true;
@@ -2158,6 +2169,9 @@ function rememberResumePoses(h) {
2158
2169
  // v1.145: a body real-time still holds after its roster row went keeps
2159
2170
  // the account it was retained for (Vis/Companion heldAway).
2160
2171
  identityUserId: h.session?.players.some((player) => player.playerId === id) ? userIdOf(h, id) : previous?.identityUserId ?? null,
2172
+ // v1.229: the roster's own id (an anonymous guest's included), so `back`
2173
+ // is told only to the same person, not merely the same transport id.
2174
+ rosterUserId: rosterUserOf(h, id) ?? previous?.rosterUserId ?? null,
2161
2175
  ...(previous?.pendingClientHello ? { pendingClientHello: previous.pendingClientHello } : {}),
2162
2176
  ...(previous?.visibilityResumePending ? { visibilityResumePending: true } : {}),
2163
2177
  });
@@ -2235,6 +2249,95 @@ function rememberAnonymousEntries(h) {
2235
2249
  }
2236
2250
  }
2237
2251
 
2252
+ // v1.229: a place's `away` hook hears once that pinned retention is holding a
2253
+ // dropped, arrived player (the first tick that keeps them past the deadline
2254
+ // check), and `back` once when the same id returns inside the window. Only a
2255
+ // pinned window (`reconnectWindowMs`) tells; the 60 s and pose-only keeps do
2256
+ // not. An expiry, Back, travel or shutdown after `away` runs `leave` as before.
2257
+ function awayHooks(h) {
2258
+ return typeof h.hooks.away === 'function' && typeof h.hooks.back === 'function';
2259
+ }
2260
+
2261
+ function tellAway(h, playerId) {
2262
+ const entry = h.players.get(playerId);
2263
+ if (!pinnedResume(h) || !entry?.arrived || entry.ended || h.awayTold?.has(playerId) || !awayHooks(h)) {
2264
+ if (!h.awayWarned && pinnedResume(h) && (typeof h.hooks.away === 'function') !== (typeof h.hooks.back === 'function')) {
2265
+ h.awayWarned = true;
2266
+ console.warn('[hub] away and back are a pair: a place that defines only one is told neither');
2267
+ }
2268
+ return;
2269
+ }
2270
+ (h.awayTold ??= new Map()).set(playerId, {
2271
+ at: Date.now(),
2272
+ userId: entry.userId ?? null,
2273
+ rosterUserId: h.resumeKept?.get(playerId)?.rosterUserId ?? null,
2274
+ });
2275
+ callAwayHook(h, 'away', playerId, { userId: entry.userId ?? null, username: entry.username ?? 'player' });
2276
+ }
2277
+
2278
+ function rosterUserOf(h, playerId) {
2279
+ const p = h.session?.players.find((q) => q.playerId === playerId);
2280
+ return p && p.userId !== undefined && p.userId !== null ? String(p.userId) : null;
2281
+ }
2282
+
2283
+ function visitOver(h, playerId, entry) {
2284
+ return h.players.get(playerId) !== entry || entry.ended === true || h.resumeDeparting?.has(playerId) === true;
2285
+ }
2286
+
2287
+ // Before anything of the held visit is put back: false when the visit told
2288
+ // `away` does not resume. Another person on its id, or a visit ended while
2289
+ // away, leaves once (its `leave` names the old account; no door end goes down
2290
+ // the id), and whoever is there now arrives fresh.
2291
+ function awayReturns(h, playerId) {
2292
+ const told = h.awayTold?.get(playerId);
2293
+ if (!told) {
2294
+ return true;
2295
+ }
2296
+ const entry = h.players.get(playerId);
2297
+ if (!entry) {
2298
+ h.awayTold.delete(playerId);
2299
+ return false;
2300
+ }
2301
+ const rosterUserId = rosterUserOf(h, playerId);
2302
+ const other = (userIdOf(h, playerId) ?? null) !== told.userId ||
2303
+ (told.rosterUserId !== null && rosterUserId !== told.rosterUserId);
2304
+ if (other || visitOver(h, playerId, entry)) {
2305
+ forget(h, playerId);
2306
+ return false;
2307
+ }
2308
+ return true;
2309
+ }
2310
+
2311
+ // After the pose is back: false when the `back` hook ended the visit.
2312
+ function tellBack(h, playerId) {
2313
+ const told = h.awayTold?.get(playerId);
2314
+ if (!told) {
2315
+ return true;
2316
+ }
2317
+ h.awayTold.delete(playerId);
2318
+ const entry = h.players.get(playerId);
2319
+ if (!entry) {
2320
+ return false;
2321
+ }
2322
+ callAwayHook(h, 'back', playerId, {
2323
+ userId: entry.userId ?? null,
2324
+ username: entry.username ?? 'player',
2325
+ awayMs: Math.max(0, Date.now() - told.at),
2326
+ });
2327
+ return !visitOver(h, playerId, entry);
2328
+ }
2329
+
2330
+ function callAwayHook(h, name, playerId, info) {
2331
+ try {
2332
+ const out = h.hooks[name](h.ctx, playerId, Object.freeze(info));
2333
+ if (out && typeof out.then === 'function') {
2334
+ out.then(undefined, () => console.warn(`[hub] ${name} hook failed`));
2335
+ }
2336
+ } catch (err) {
2337
+ console.warn(`[hub] ${name} hook failed: ${err?.message ?? err}`);
2338
+ }
2339
+ }
2340
+
2238
2341
  function prepareResume(h, playerId, greet = true) {
2239
2342
  const kept = h.resumeKept?.get(playerId);
2240
2343
  if (!kept) {
@@ -2260,9 +2363,16 @@ function prepareResume(h, playerId, greet = true) {
2260
2363
  forget(h, playerId);
2261
2364
  return;
2262
2365
  }
2366
+ if (!present) {
2367
+ tellAway(h, playerId);
2368
+ return;
2369
+ }
2263
2370
  if (!returning) {
2264
2371
  return;
2265
2372
  }
2373
+ if (!awayReturns(h, playerId)) {
2374
+ return h.players.has(playerId) ? 'handled' : 'fresh';
2375
+ }
2266
2376
  if (h.place.resumeVisibility === true) {
2267
2377
  if (typeof kept.identityUserId === 'string' && kept.identityUserId === userIdOf(h, playerId)) {
2268
2378
  kept.visibilityResumePending = true;
@@ -2300,6 +2410,10 @@ function prepareResume(h, playerId, greet = true) {
2300
2410
  settle(h, playerId);
2301
2411
  kept.body = body;
2302
2412
  delete kept.awayAt;
2413
+ // v1.229: after the pose is back, before the hello replay and `resume`.
2414
+ if (!tellBack(h, playerId)) {
2415
+ return h.players.has(playerId) ? 'handled' : 'fresh';
2416
+ }
2303
2417
  // The silent same-id case has no fresh arrive hook. Reuse the existing hello
2304
2418
  // replay to restore private channels, including a cleared channel it missed.
2305
2419
  if (greet) {
@@ -2577,6 +2691,12 @@ function forget(h, playerId) {
2577
2691
  console.warn(`[hub] leave hook failed: ${err?.message ?? err}`);
2578
2692
  }
2579
2693
  }
2694
+ // v1.229: a visit told `away` ends with `leave` alone, never a late `back`;
2695
+ // a body real-time still holds stays off the roster until it goes.
2696
+ if (h.awayTold?.delete(playerId) && h.sim?.players.has(playerId) &&
2697
+ !h.session?.players.some((p) => p.playerId === playerId)) {
2698
+ (h.awayGone ??= new Set()).add(playerId);
2699
+ }
2580
2700
  Vehicle.forget(h, playerId, (id, point, face) => placeAt(h, id, point, face));
2581
2701
  Disguise.forget(h, playerId);
2582
2702
  DoorAnalytics.finish(h, playerId, 3);
@@ -221,6 +221,8 @@ of any of these. Every hook gets `hub`, the place's context, first:
221
221
  | `fall(hub, playerId)` | v1.1: a player fell below the place's `fallY` (§5); place them somewhere, or the kit puts them back at the arrival |
222
222
  | `carry(hub, playerId, carry)` | where the host has hub ops: what an already-arrived player brings back, when ghost's read came after the arrival window (§7) |
223
223
  | `leave(hub, playerId, { userId, username })` | a player left (Back, the host's Back, a closed tab). v1.89 `{ resume: { keep: true } }` delays an unexplained absence up to 60 s (§12); a short resume runs neither leave nor arrive. Runs while the player is still known (v1.2): `hub.result` takes their result for the visit here, and `userId` names their storage (§14) |
224
+ | `away(hub, playerId, { userId, username })` | v1.229, optional; defining it together with `back` is the opt-in (a place defining only one of the pair is told neither, with one warning): pinned retention (a host-pinned `reconnectWindowMs`, the Town's or a door's `resumeWindowSec`) is holding this arrived player, who dropped without Back. Called once, on the first tick that keeps them; from then until `back` they are left out of `hub.players()` (even while the host still holds their body, and through `leave` until that body goes), and their visit, pose and result state stay held. Free what other players wait on (a shared turn, a control, a slot, co-op credit) here; it is neither `leave` nor the end of the visit. Then exactly one of: `back` on a same-id return inside the window, or `leave` (the window expired, the visit was ended or replaced, another person (account or anonymous guest) came back on the id, shutdown). A visit `hub.end`ed while away gets no `back`: on return it leaves once and whoever is there arrives fresh. The 60 s keep (`resume: { keep: true }`) and pose-only places never call it. `info` is frozen; return ignored; throws and rejections contained and logged ("Away and back") |
225
+ | `back(hub, playerId, { userId, username, awayMs })` | v1.229, optional, paired with `away`: the player told `away` is back under the same id and the same account (or the same anonymous guest) inside the window. Called once, after their pose is put back and before the hello replay and `resume`; `awayMs` is wall-clock time since `away`. Re-take what `away` freed; the player is in `hub.players()` again. Never called without an `away` first; a return past the window is a fresh `arrive` after `leave`. Return ignored; throws and rejections contained and logged |
224
226
  | `shutdown(hub)` | v1.2: the session is stopping. Anyone still here has had `leave` first; return a promise to finish writing (awaited up to 1.5 s, inside the host's own grace) |
225
227
  | `grab(hub, playerId, actorId, op)` | v1.3, a place with `grab`: a player grabbed (`op` `"grab"`) or threw (`"throw"`) a loose object (§6). Return `false` to a grab to refuse it (the player lets go at once); a throw is only told. A hook that throws refuses the grab |
226
228
  | `emote(hub, playerId, id)` | v1.6, a place with `idle.emotes`: a player asked to play emote `id` (§6). Return `false` to refuse it (nobody sees it); a hook that throws refuses it |
@@ -5476,6 +5478,7 @@ a deck written before them remains valid.
5476
5478
  | 2026-11-18 (v1.222) | Writer leases (server-only, no wire or manifest change): a fresh connection whose account has no connected visit here forgets that account's retained visits whether or not it is lost, and a visit back to a held claim (retained visits, or the 60 s end-save window) revalidates it; a claim another instance took meanwhile is replaced silently instead of losing the fresh visit. `hub.saves.deck`/`user` views are bound to the claim current when made, so a superseded visit's queued writes reject with `CAULDRON_STORAGE_WRITER_LOST`. `resumePose` takes, ends and clears its durable pose through the lease view, so a fenced instance no longer moves the pose revision. No deck opts in yet. |
5477
5479
  | 2026-11-18 (v1.223) | Writer leases (server-only, no wire or manifest change): a lone visit back that arrives while an earlier visit's revalidation is still out checks the claim again once that round settles (on whichever claim it settled), so a check from before another instance's takeover never lets the return proceed only to lose its first save. `resumePose` takes its snapshot through the lease view too, so it reads only once the claim settles and keeps a pose the previous writer saved just before; its 5 s read budget starts once the claim has settled. An older pending round that resumes on a replacement claim a newer arrival is already checking waits for that round and keeps the claim it found; it never inherits a claim that round reopens. A take holds its queue place at once, so an end asked while it waits for the claim runs after it. Without `writerLease` nothing changes. No deck opts in yet. |
5478
5480
  | 2026-11-18 (v1.224) | Writer leases (server-only): `await hub.saves.holds(view)` tells whether the claim a save view writes through is still active and has not been lost, after pending claim checks settle. Unrecognized views and lease-off stores answer true. No manifest or wire change. |
5481
+ | 2026-11-19 (v1.229) | §4 optional `away(hub, playerId, { userId, username })` and `back(hub, playerId, { userId, username, awayMs })` hooks: pinned retention tells a place once when it holds a dropped arrived player, and once on the same id's return inside the window (after the pose is restored, before the hello replay and `resume`); otherwise the visit ends with `leave` as before ("Away and back"). The 60 s keep and pose-only places never call them. Hook presence is the opt-in; server-only, no manifest or wire change. |
5479
5482
  | 2026-11-19 (v1.230) | §1 `resumeWindowSec` may stand beside `resumePose` (still refused beside `result`, `houseResume` and `resumeArrivalPose`): the pinned window holds the same visit and pose, and `resumePose`'s stored pose then places a new id for the same account up to ten minutes after departure, as the Town's places already do ("Door resume window"). Manifest validation only; no runtime or wire change. |
5480
5483
  | 2026-11-18 (v1.226) | Writer leases (server-only, no manifest or wire change): every `set`/`remove`/`increment` through a `hub.saves` view carries the platform writer check of the claim it is bound to, so a stale write is refused atomically instead of after a separate fence (the write-after-fence window is closed for ordinary writes where the platform checks). A refusal loses the claim and is never retried. Where a checked write answers `CAULDRON_STORAGE_UNAVAILABLE` (`castle-web serve`, persistent-world sessions; the details may sit under `extensions`) the session fences and writes unchecked as before; view `transaction`/`conditionalWrite` and root atomic calls keep their fence. Every lone arrival now claims anew and the place reloads (no revalidation of a held claim): queued writes of the previous visit go first for up to 5 s; claims are sent or retried only while a connected visit is here, and a resume picks a waiting claim up again. `holds(view)` also waits for the account's current claim. Without `writerLease` nothing changes. No deck opts in yet. |
5481
5484
  | 2026-11-18 (v1.228) | Writer leases (server-only, no manifest or wire change): `hub.saves.bind(store, view)` returns another store of the account (a `session.storage.playthrough` handle) bound to the claim `view` is bound to: `set`/`remove` carry that claim's writer check and run in account order, reads wait for that claim. The raw store when `view` is not a lease view or the lease is off. The Town conversation saves through it. No deck opts in yet. |
@@ -5696,6 +5699,39 @@ has passed `resumePose`'s stored pose still places a new id for the same
5696
5699
  account (up to ten minutes after departure). Absent, on an older Ghost, or on a host
5697
5700
  without grace, nothing is pinned and a drop ends the visit exactly as before.
5698
5701
 
5702
+ ### Away and back (v1.229)
5703
+
5704
+ A pinned window holds a dropped player's visit with no `leave` and no
5705
+ `arrive`, which suits a place that only needs them to stand where they were.
5706
+ A place with shared state (a turn, a relay leg, a host slot, a co-op count, a
5707
+ control one player drives) would otherwise wait on, charge or credit someone
5708
+ who is gone for up to the whole window. Such a place defines `away` and
5709
+ `back` (§4):
5710
+
5711
+ - `away(hub, playerId, { userId, username })` runs once when the kit first
5712
+ keeps the dropped player under the pinned deadline. It does not run for a
5713
+ drop the kit lets go at once (the player's own Back, kit travel, a writer
5714
+ lease replaced) -- those go straight to `leave`.
5715
+ - `back(hub, playerId, { userId, username, awayMs })` runs once on a same-id
5716
+ return inside the window, after the pose is restored and before the hello
5717
+ replay and the `resume` hook.
5718
+ - After `away`, the visit ends in exactly one of `back` or `leave`. A second
5719
+ drop after `back` tells `away` again. The pair is the opt-in: a place that
5720
+ defines only one is told neither (the kit warns once).
5721
+ - Another person (account or anonymous guest) returning on the same id is
5722
+ not `back`: before anything of the held visit is put back, the old visit
5723
+ leaves (its `leave` names the old account) and the newcomer arrives fresh.
5724
+ A visit ended (`hub.end`) while away leaves the same way on return; one
5725
+ ended by `back` ends as any present player's does.
5726
+ - From `away` until `back`, and through `leave` until real-time drops the
5727
+ body, the player is left out of `hub.players()`; the deadline counts from
5728
+ the drop even while the body lingers.
5729
+
5730
+ Only a pinned window tells (`reconnectWindowMs` on the session, the Town's 180
5731
+ s, a door's `resumeWindowSec`, an owner house's grace); the 60 s keep and
5732
+ pose-only resume do not. Absent hooks, an older kit, or no pinned window:
5733
+ unchanged behaviour. Server-only; no manifest key and no wire change.
5734
+
5699
5735
  ### v1.115: owner-house reconnect retention
5700
5736
 
5701
5737
  Optional place key `hub.houseResume: true` (also in a `hub.places` block), only