castle-web-cli 0.4.242 → 0.4.244

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.
@@ -2261,6 +2261,7 @@ export function makeChrome({ onBack, onAvatar, onColor = () => {}, avatarCount,
2261
2261
  // A owns only this lazy, noninteractive caption. The projected surface
2262
2262
  // participates in the shared registry but is placed last, yielding to
2263
2263
  // every final control/card/label box rather than moving any of them.
2264
+ // v1.221: true only when the caption is drawn and visible this frame.
2264
2265
  setPadContext(item) {
2265
2266
  const blocked = pickerOpen || sayOpen || emotesOpen || peopleOpen || doorsOpen || talkOpen ||
2266
2267
  !!textAsk?.card || !!placeMenu?.sheet || sound?.open || actionOverflow?.isOpen?.() ||
@@ -2269,7 +2270,7 @@ export function makeChrome({ onBack, onAvatar, onColor = () => {}, avatarCount,
2269
2270
  (cabinet.style.display !== 'none' && cabinet.dataset.drawn === 'board');
2270
2271
  if (!item || blocked) {
2271
2272
  if (padContext && padContext.node.style.visibility !== 'hidden') {padContext.node.style.visibility = 'hidden';}
2272
- return;
2273
+ return false;
2273
2274
  }
2274
2275
  if (!padContext) {
2275
2276
  const node = el('div', { position: 'absolute', left: '0px', top: '0px', width: 'max-content', maxWidth: 'min(70vw, 320px)',
@@ -2318,6 +2319,7 @@ export function makeChrome({ onBack, onAvatar, onColor = () => {}, avatarCount,
2318
2319
  }
2319
2320
  const visibility = at ? '' : 'hidden';
2320
2321
  if (node.style.visibility !== visibility) {node.style.visibility = visibility;}
2322
+ return Boolean(at);
2321
2323
  },
2322
2324
  clearPadContext() {
2323
2325
  if (!padContext) {return;}
@@ -12,6 +12,7 @@ import * as AvatarCap from './avatarCap.js';
12
12
  import { mergeDictionary } from './interestCap.js';
13
13
  import * as Cabinets from './cabinets.js';
14
14
  import { firstJoinFor } from './firstJoin.js';
15
+ import { signalReplay } from './signals.js';
15
16
  import { deck, earnedNow, hub, holdShowsNow, idleNow, localArrival, mergeHidden, receiveParty, replayCleanup, rolesNow, wearingNow } from './state.js';
16
17
  import { clearShot, receiveShot } from './shot.js';
17
18
  import * as Ballot from './ballot.js';
@@ -326,6 +327,13 @@ const hooks = {
326
327
  break;
327
328
  case 'hub-arrived':
328
329
  hub.arrivedFacing = typeof msg.facing === 'number' ? msg.facing : 0;
330
+ // v1.221: an arrival the place's `signal` hook hears: its first inputs.
331
+ hub.signalArrival = Number.isSafeInteger(msg.signals) ? { n: msg.signals, at: performance.now() } : null;
332
+ break;
333
+ case 'hub-signals':
334
+ // v1.221: a retained rehello: the same arrival, what is left of its
335
+ // window and the kinds already said (never a fresh allowance).
336
+ hub.signalArrival = signalReplay(msg);
329
337
  break;
330
338
  case 'hub-hold-face':
331
339
  // v1.190: a hold with turnCamera, and its release, turn this player's
@@ -28,6 +28,8 @@ export function collectPadCues(actors, hidden) {
28
28
  cues.push({ id: actor.id, x: c.Transform.x, z: c.Transform.z, radius: spec.radius,
29
29
  y: (c.Transform.y ?? 0) + (shape?.kind === 'cylinder' ? (shape.height ?? 1) / 2 : 0) + 0.03,
30
30
  title: explicit ? spec.title : doors.get(spec.door)?.title, door: !explicit,
31
+ // v1.221: the door a door pad's caption names (first-input signals).
32
+ ...(explicit ? {} : { doorId: spec.door }),
31
33
  cabinet: !explicit && doors.get(spec.door)?.kind === 'cabinet',
32
34
  color: shape?.color ?? '#d9a441' });
33
35
  }
@@ -15,8 +15,13 @@ export function makePadReadability(engine, options) {
15
15
  rings?.frame(traveling ? null : active?.cue);
16
16
  if (engine.hubPadContext === true) {
17
17
  if (active !== previous || guest !== previousGuest) {text = padContextText(active, guest); previous = active; previousGuest = guest;}
18
- chrome.setPadContext(traveling || captionBlocked ? null : text);
18
+ // v1.221: the door whose caption chrome actually drew and shows this
19
+ // frame (not one hidden behind an open panel or left unplaced), for
20
+ // first-input signals.
21
+ const drawn = chrome.setPadContext(traveling || captionBlocked ? null : text) === true;
22
+ return drawn && typeof active?.cue.doorId === 'string' ? active.cue.doorId : null;
19
23
  }
24
+ return null;
20
25
  },
21
26
  dispose() {
22
27
  rings?.dispose();
@@ -0,0 +1,126 @@
1
+ // v1.221: first-input signals (contract §12 "First-input signals"), the
2
+ // client's half. Only an arrival whose `hub-arrived` carried an arrival number
3
+ // (`signals`, sent only where the place's module has a `signal` hook) says
4
+ // anything, and then each of its first walk, first jump and first door prompt
5
+ // at most once, within WINDOW_MS of that arrival. Once all three are said or
6
+ // the window is over, a frame costs one comparison.
7
+ //
8
+ // `{ k: 'hub-signal', kind: 'move' | 'jump', a }` and
9
+ // `{ k: 'hub-signal', kind: 'prompt', a, door }`, `a` the arrival number they
10
+ // were armed with; the server checks each. A retained rehello is told the same
11
+ // arrival again (`hub-signals`, `signalReplay`): what is left of its window
12
+ // and what was already said.
13
+
14
+ export const WINDOW_MS = 120_000;
15
+ // What walks a player (`idle.js` MOVE_KEYS without Space, which jumps).
16
+ const WALK_KEYS = ['KeyW', 'KeyA', 'KeyS', 'KeyD', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'];
17
+ // The drag stick counts once it is this far over (`idle.js` `moving`).
18
+ const STICK_MIN = 0.15;
19
+
20
+ const KINDS = ['move', 'jump', 'prompt'];
21
+
22
+ // `hub-signals` as the hub's `signalArrival`: the arrival's number, its start
23
+ // moved back by the window already spent, and the kinds already said; null
24
+ // for anything malformed.
25
+ export function signalReplay(msg, now = performance.now()) {
26
+ if (!Number.isSafeInteger(msg?.n) || !Number.isFinite(msg.left) || msg.left <= 0 || msg.left > WINDOW_MS || !Array.isArray(msg.sent)) {
27
+ return null;
28
+ }
29
+ return { n: msg.n, at: now - (WINDOW_MS - msg.left), sent: KINDS.filter((kind) => msg.sent.includes(kind)) };
30
+ }
31
+
32
+ export function walking(keys, stick) {
33
+ if (keys && WALK_KEYS.some((code) => keys.has?.(code) === true)) {
34
+ return true;
35
+ }
36
+ return Boolean(stick?.active && Math.hypot(stick.x ?? 0, stick.y ?? 0) >= STICK_MIN);
37
+ }
38
+
39
+ // The engine hears keys typed into a text field too (a chat line, a name):
40
+ // those are words, not a walk or a jump.
41
+ function typing(doc) {
42
+ const el = doc?.activeElement;
43
+ return Boolean(el && (el.isContentEditable || el.closest?.('input, textarea, select')));
44
+ }
45
+
46
+ export function makeSignals(doc = globalThis.document) {
47
+ // { arrival, move, jump, prompt, done } for the arrival being said
48
+ let record = null;
49
+ // A tap is a jump the Player behavior takes (`moveInput.consumeJump`)
50
+ // before this runs, so it is noted as it is taken. Ours stays the outermost
51
+ // wrapper: Act's own (`act.js`) adds its Jump button's press to what it
52
+ // wrapped, so one put over ours is wrapped again. Act and idle wrap a
53
+ // controls object once, so the chain does not grow.
54
+ let wrapper = null;
55
+ let tapped = false;
56
+ function watch(input) {
57
+ if (!input || typeof input.consumeJump !== 'function' || input.consumeJump === wrapper) {
58
+ return;
59
+ }
60
+ const consume = input.consumeJump;
61
+ wrapper = function consumeJump(...args) {
62
+ const had = consume.apply(this, args);
63
+ if (had) {
64
+ tapped = true;
65
+ }
66
+ return had;
67
+ };
68
+ input.consumeJump = wrapper;
69
+ }
70
+ const up = (net) => !net.closed?.() && (!net.status || net.status().state === 'connected');
71
+ return {
72
+ // Whether a door prompt shown now would still be said (so the caller
73
+ // need not collect one).
74
+ wantsPrompt: (arrival) => Boolean(arrival && record?.arrival === arrival && !record.done && !record.prompt),
75
+ // Each frame. `arrival`: the hub's `signalArrival`, or null (no hook, no
76
+ // arrival yet, a trip). `prompt`: a door id whose prompt is up, or null.
77
+ frame(net, arrival, now, { keys, stick, prompt }) {
78
+ if (!arrival) {
79
+ tapped = false;
80
+ return;
81
+ }
82
+ if (record?.arrival !== arrival) {
83
+ const said = Array.isArray(arrival.sent) ? arrival.sent : [];
84
+ record = { arrival, move: said.includes('move'), jump: said.includes('jump'), prompt: said.includes('prompt'), done: false };
85
+ record.done = record.move && record.jump && record.prompt;
86
+ tapped = false;
87
+ }
88
+ if (record.done) {
89
+ return;
90
+ }
91
+ if (now - arrival.at >= WINDOW_MS) {
92
+ record.done = true;
93
+ return;
94
+ }
95
+ if (!net) {
96
+ return;
97
+ }
98
+ if (!record.jump) {
99
+ watch(stick);
100
+ }
101
+ const tap = tapped;
102
+ tapped = false;
103
+ const typed = (!record.move || !record.jump) && keys?.size > 0 && typing(doc);
104
+ const move = !record.move && walking(typed ? null : keys, stick);
105
+ const jump = !record.jump && (tap || (!typed && keys?.has?.('Space') === true));
106
+ const door = !record.prompt && typeof prompt === 'string' && prompt ? prompt : null;
107
+ // Said only while the connection can carry it; otherwise kept for later.
108
+ if (!(move || jump || door) || !up(net)) {
109
+ return;
110
+ }
111
+ if (move) {
112
+ record.move = true;
113
+ net.send({ k: 'hub-signal', kind: 'move', a: arrival.n });
114
+ }
115
+ if (jump) {
116
+ record.jump = true;
117
+ net.send({ k: 'hub-signal', kind: 'jump', a: arrival.n });
118
+ }
119
+ if (door) {
120
+ record.prompt = true;
121
+ net.send({ k: 'hub-signal', kind: 'prompt', a: arrival.n, door });
122
+ }
123
+ record.done = record.move && record.jump && record.prompt;
124
+ },
125
+ };
126
+ }
@@ -170,6 +170,9 @@ export const hub = {
170
170
  // the facing the place gave this player on arrival, or null until it has,
171
171
  // and whether the camera has been turned to it
172
172
  arrivedFacing: null,
173
+ // v1.221: this connection's latest arrival under a place's `signal` hook,
174
+ // { n, at (performance.now()) }, or null (first-input signals)
175
+ signalArrival: null,
173
176
  // v1.165: this client's newest clamped pose row while it matters to a car
174
177
  // (`hookLayer` state, vehicle.js `placedHeading`)
175
178
  selfClamp: null,
@@ -323,6 +326,7 @@ export function clear() {
323
326
  }
324
327
  hub.cabinets = {};
325
328
  hub.arrivedFacing = null;
329
+ hub.signalArrival = null;
326
330
  hub.arrivalPlaced = false;
327
331
  hub.faced = false;
328
332
  hub.commands.length = 0;
@@ -60,6 +60,7 @@ import * as WriterLease from './writerLease.js';
60
60
  import * as ArrivalPose from './arrivalPose.js';
61
61
  import * as Observe from './observe.js';
62
62
  import * as Wallet from './wallet.js';
63
+ import * as Signals from './signals.js';
63
64
  import { makeAnonymousEntry } from './anonymousEntry.js';
64
65
  import { doorPoint } from '../client/doorFrame.js';
65
66
 
@@ -433,6 +434,11 @@ export function layer(castleJson, deckHooks, placeHooks, sceneExists, sceneGroun
433
434
  notifyVisibility(h, player.playerId);
434
435
  return;
435
436
  }
437
+ // v1.221: telemetry only, so heard during a progress read as well.
438
+ if (data?.k === 'hub-signal' && Signals.on(h)) {
439
+ Signals.message(h, player, data, () => doors(h).map((door) => door.id));
440
+ return;
441
+ }
436
442
  if (data?.k === 'hub-hello') {
437
443
  LoadAbandon.hello(h, player?.playerId);
438
444
  hello(h, player, data);
@@ -1489,6 +1495,9 @@ function hello(h, player, data, synthetic = false) {
1489
1495
  // holds none of the cabinet cards it was sent (v1.7).
1490
1496
  if (data.again !== true) {
1491
1497
  replaySent(h, player.playerId, data.resume === true);
1498
+ // v1.221: a retained rehello's page may have reloaded: the current
1499
+ // arrival's first-input allowance, never a new one.
1500
+ if (known?.arrived) {Signals.replay(h, player.playerId);}
1492
1501
  Idle.joinedAfresh(h, player.playerId, data.resume === true);
1493
1502
  if (h.manifest.act === true) {Act.replay(h, player.playerId);}
1494
1503
  h.vehicleDeparting?.delete(player.playerId);
@@ -2584,6 +2593,7 @@ function forget(h, playerId) {
2584
2593
  }
2585
2594
  Party.forget(h, playerId);
2586
2595
  Say.forget(h, playerId);
2596
+ Signals.forget(h, playerId);
2587
2597
  if (h.ballotState) {
2588
2598
  Ballot.forget(h, playerId);
2589
2599
  }
@@ -2724,7 +2734,9 @@ function finishSignUp(h, playerId, signUp, cancel = false) {
2724
2734
  h.hooks.arrive?.(h.ctx, [signUp.member]);
2725
2735
  settle(h, playerId);
2726
2736
  const body = h.sim.players.get(playerId);
2727
- if (body) {h.session?.send(playerId, { k: 'hub-arrived', facing: body.facing });}
2737
+ // v1.221: a signal hook's arrival number starts this arrival's first inputs.
2738
+ const signals = Signals.arrived(h, playerId);
2739
+ if (body) {h.session?.send(playerId, { k: 'hub-arrived', facing: body.facing, ...(signals ? { signals } : {}) });}
2728
2740
  } catch (err) {
2729
2741
  console.warn(`[hub] signup arrival failed: ${err?.message ?? err}`);
2730
2742
  } finally {
@@ -2878,7 +2890,9 @@ function arrivals(h) {
2878
2890
  if (Math.hypot(body.at.x - was.x, body.at.z - was.z) > HOLD_SLACK) {
2879
2891
  settle(h, playerId);
2880
2892
  }
2881
- h.session?.send(playerId, { k: 'hub-arrived', facing: body.facing });
2893
+ // v1.221: a signal hook's arrival number starts this arrival's first inputs.
2894
+ const signals = Signals.arrived(h, playerId);
2895
+ h.session?.send(playerId, { k: 'hub-arrived', facing: body.facing, ...(signals ? { signals } : {}) });
2882
2896
  }
2883
2897
  if (h.players.get(playerId)?.endAgain) {
2884
2898
  delete h.players.get(playerId).endAgain;
@@ -3758,6 +3772,7 @@ function doorJump(h, player, data) {
3758
3772
  placeAt(h, player.playerId, { x: at.x, y: standingY(h, { ...at, y: 1.2 }), z: at.z }, facing);
3759
3773
  settle(h, player.playerId);
3760
3774
  h.session?.send(player.playerId, { k: 'hub-jumped', facing });
3775
+ Signals.emit(h, player.playerId, { kind: 'press', door: door.id });
3761
3776
  }
3762
3777
 
3763
3778
  // Join on a friend at home in their House (§5): through that door into the
@@ -3785,6 +3800,7 @@ function houseVisit(h, player, data) {
3785
3800
  h.jumpAt.set(playerId, now);
3786
3801
  tellWent(h, [playerId], door.id);
3787
3802
  sendGo(h, playerId, { k: 'hub-go', door: door.id, key: null, place: null, scene: null, title: door.title, party: 1, owner });
3803
+ Signals.emit(h, playerId, { kind: 'press', door: door.id });
3788
3804
  }
3789
3805
 
3790
3806
  // "Stuck?" (v1.33): whether this place puts a player back at its arrival for
@@ -4487,6 +4503,7 @@ function gather(h, door, playerIds) {
4487
4503
  return;
4488
4504
  }
4489
4505
  const on = new Set(playerIds ?? []);
4506
+ if (Signals.on(h)) {Signals.pad(h, door, h.padDoors.get(door), on);}
4490
4507
  h.padDoors.set(door, on);
4491
4508
  h.padOccupancy?.reportedAt.set(door, h.sim.timeMs);
4492
4509
  for (const [playerId, entry] of h.shut) {
@@ -37,6 +37,7 @@ import { EMOTES } from './idle.js';
37
37
  import { npcDisplayText } from '../npcDisplayText.js';
38
38
  import { warnOnce } from './actors.js';
39
39
  import { readNpcTurnsAtOnce } from './manifest.js';
40
+ import * as Signals from './signals.js';
40
41
 
41
42
  // v1.47: a crowd answers a gesture without calling a mind.
42
43
  const REACT_RANGE_M = 6;
@@ -666,6 +667,9 @@ function open(h, n, playerId, npcId) {
666
667
  }
667
668
  state.talking = talking;
668
669
  h.ctx.track?.(playerId, 'npc_chat_count', { subject: 9, value: 1 });
670
+ // v1.221: a companion's id carries its owner's player id; it is named
671
+ // only as 'companion'.
672
+ Signals.emit(h, playerId, { kind: 'talk', npc: npc.owner ? 'companion' : npc.id });
669
673
  // A new conversation can ask again for what an earlier one finished.
670
674
  const participant = n.participants.get(playerId);
671
675
  if (participant) {
@@ -11,6 +11,7 @@
11
11
  // member) and by player id for a guest, who is a member only while here.
12
12
 
13
13
  // The most players one party holds.
14
+ import * as Signals from './signals.js';
14
15
  export const PARTY_MAX = 8;
15
16
  // An invitation and a proposed door wait this long for an answer.
16
17
  const INVITE_MS = 60000;
@@ -258,6 +259,8 @@ export function toPad(d, playerId, door, n) {
258
259
  const at = padPoint(h, door, n, playerId) ?? d.front(door);
259
260
  d.placeAt(h, playerId, { x: at.x, y: d.standingY(h, { ...at, y: 1.2 }), z: at.z }, facing);
260
261
  h.session?.send(playerId, { k: 'hub-jumped', facing });
262
+ // v1.221: a party Go or Go-yes is the player's press for this door.
263
+ Signals.emit(h, playerId, { kind: 'press', door: door.id });
261
264
  return true;
262
265
  }
263
266
 
@@ -0,0 +1,124 @@
1
+ // v1.221: first-input signals (contract §4 `signal`, §12 "First-input
2
+ // signals"). A place whose module defines a `signal` hook hears a fixed
3
+ // vocabulary of a player's first moments, never free text:
4
+ //
5
+ // { kind: 'move' } their first walk input } from the client,
6
+ // { kind: 'jump' } their first jump } each at most once
7
+ // { kind: 'prompt', door } the first door prompt shown } an arrival, within
8
+ // } WINDOW_MS of it
9
+ // { kind: 'talk', npc } a conversation opened (an NPC actor id, or
10
+ // 'companion' for the player's own companion)
11
+ // { kind: 'press', door } they were put at a door they asked for (a door
12
+ // jump, a party Go or Go-yes, a friend's House)
13
+ // { kind: 'pad', door } the place's `hub.pad` first counted them on a
14
+ // door's pad
15
+ //
16
+ // Without the hook nothing is kept, sent or called: an older kit, which knows
17
+ // no such hook, simply never calls it.
18
+
19
+ const CLIENT_KINDS = new Set(['move', 'jump', 'prompt']);
20
+ // The client signals belong to this long after an arrival.
21
+ export const WINDOW_MS = 120_000;
22
+ const own = (data, keys) => Object.keys(data).every((key) => keys.includes(key));
23
+
24
+ export function on(h) {
25
+ return typeof h.hooks?.signal === 'function';
26
+ }
27
+
28
+ // A hook that throws or rejects never reaches the kit; it is said once. Call
29
+ // it after the kit's own work for the event is done.
30
+ export function emit(h, playerId, signal) {
31
+ if (!on(h)) {
32
+ return;
33
+ }
34
+ const failed = () => {
35
+ if (!h.signalFailed) {
36
+ h.signalFailed = true;
37
+ console.warn('[hub] signal hook failed');
38
+ }
39
+ };
40
+ try {
41
+ const result = h.hooks.signal(h.ctx, playerId, Object.freeze({ ...signal }));
42
+ result?.catch?.(failed);
43
+ } catch {
44
+ failed();
45
+ }
46
+ }
47
+
48
+ // A genuine arrival (the place's `arrive` hook has heard it): the client
49
+ // signals start again for this player. A rehello or a retained resume is not
50
+ // one. Returns the arrival's number for `hub-arrived`, or null without a hook.
51
+ export function arrived(h, playerId) {
52
+ if (!on(h)) {
53
+ return null;
54
+ }
55
+ h.signalN = (h.signalN ?? 0) + 1;
56
+ (h.signalArrivals ??= new Map()).set(playerId, { n: h.signalN, at: Date.now(), sent: new Set() });
57
+ return h.signalN;
58
+ }
59
+
60
+ // The client's `{ k: 'hub-signal', kind, a, door? }`, from a present sender
61
+ // whose arrival is still in its window; the sender comes from the session,
62
+ // never the payload. `a` is the arrival number the client was armed with: one
63
+ // from an earlier arrival (a rejoin race) is dropped before the kind is spent.
64
+ // Once and window checks come before any door lookup.
65
+ // `doorIds()`: the ids of this place's doors.
66
+ export function message(h, player, data, doorIds) {
67
+ const playerId = player?.playerId;
68
+ const arrival = typeof playerId === 'string' ? h.signalArrivals?.get(playerId) : null;
69
+ if (!arrival || !on(h) || Date.now() - arrival.at >= WINDOW_MS) {
70
+ return;
71
+ }
72
+ try {
73
+ if (data.a !== arrival.n) {
74
+ return;
75
+ }
76
+ const kind = data.kind;
77
+ if (!CLIENT_KINDS.has(kind) || arrival.sent.has(kind)) {
78
+ return;
79
+ }
80
+ // Spent before it is checked further: a bad one costs its sender the kind.
81
+ arrival.sent.add(kind);
82
+ if (!h.players.get(playerId)?.arrived || !h.session?.players.some((p) => p.playerId === playerId) || !h.sim?.players.has(playerId)) {
83
+ return;
84
+ }
85
+ if (kind !== 'prompt') {
86
+ if (own(data, ['k', 'kind', 'a'])) {
87
+ emit(h, playerId, { kind });
88
+ }
89
+ return;
90
+ }
91
+ const door = data.door;
92
+ if (own(data, ['k', 'kind', 'a', 'door']) && typeof door === 'string' && doorIds().includes(door)) {
93
+ emit(h, playerId, { kind: 'prompt', door });
94
+ }
95
+ } catch {
96
+ // Refused wire data, including throwing accessors, is silent.
97
+ }
98
+ }
99
+
100
+ // A retained rehello or resume (a reloaded page, a rejoined socket) is not an
101
+ // arrival: it is told the current arrival's number, what of its window is
102
+ // left and the kinds already spent, so it can say what is left and nothing
103
+ // more. Neither the window nor the allowance starts again.
104
+ export function replay(h, playerId) {
105
+ const arrival = on(h) ? h.signalArrivals?.get(playerId) : null;
106
+ const left = arrival ? WINDOW_MS - (Date.now() - arrival.at) : 0;
107
+ if (left <= 0 || arrival.sent.size >= CLIENT_KINDS.size) {
108
+ return;
109
+ }
110
+ h.session?.send(playerId, { k: 'hub-signals', n: arrival.n, left, sent: [...arrival.sent] });
111
+ }
112
+
113
+ export function forget(h, playerId) {
114
+ h.signalArrivals?.delete(playerId);
115
+ }
116
+
117
+ // `hub.pad(door, playerIds)`: who is on `door`'s pad now that was not before.
118
+ export function pad(h, door, before, on) {
119
+ for (const playerId of on) {
120
+ if (typeof playerId === 'string' && h.players.get(playerId)?.arrived && !before?.has(playerId)) {
121
+ emit(h, playerId, { kind: 'pad', door });
122
+ }
123
+ }
124
+ }
@@ -5,6 +5,7 @@ import { kitBackNeeded } from '../client/backVisibility.js';
5
5
  import { cancelArrivalShot, faceArrivalCamera } from '../client/arrivalCamera.js';
6
6
  import { makeDoorErrors } from '../client/doorErrors.js';
7
7
  import { makeVisibility } from '../client/visibility.js';
8
+ import { makeSignals } from '../client/signals.js';
8
9
  import { makeInvites } from '../client/invites.js';
9
10
  import { makeHubEntry, planHubEntry } from '../client/hubEntry.js';
10
11
  import { makeHostGo } from '../client/hostGo.js';
@@ -856,6 +857,13 @@ class HubSystem {
856
857
  delete this.companionTappedUntil;
857
858
  }
858
859
  this.drawChrome(scene, local, now);
860
+ // v1.221: first-input signals, only for an arrival the place's `signal`
861
+ // hook hears (its `hub-arrived` carried a number).
862
+ if (Hub.hub.signalArrival || this.signals) {
863
+ this.signals ??= makeSignals();
864
+ this.signals.frame(mp.net ?? null, this.trip ? null : Hub.hub.signalArrival, now,
865
+ { keys: scene.keys, stick: scene.moveInput, prompt: this.signalDoor });
866
+ }
859
867
  if (Hub.hub.place?.actions === true || Hub.hub.place?.anonymousEntry === true) {
860
868
  this.actionsDrawn = true;
861
869
  const hud = Hub.hub.hudMe ?? Hub.hub.hud;
@@ -3865,6 +3873,10 @@ class HubSystem {
3865
3873
  drawChrome(scene, local, now) {
3866
3874
  const chrome = this.chrome;
3867
3875
  const place = Hub.hub.place;
3876
+ // v1.221: a door whose prompt is drawn this frame, while the arrival's
3877
+ // first prompt is still to be said (first-input signals).
3878
+ this.signalDoor = null;
3879
+ const wantsPrompt = this.signals?.wantsPrompt(Hub.hub.signalArrival) === true;
3868
3880
  const idle = !this.trip;
3869
3881
  const tickets = scene.persistent.hubTickets;
3870
3882
  const ticket = tickets[tickets.length - 1];
@@ -3895,7 +3907,11 @@ class HubSystem {
3895
3907
  const askVisible = town && !this.askInput && !this.menuInput && !this.actionInput && this.decor?.opened() !== true &&
3896
3908
  chrome.askShowable?.() !== false;
3897
3909
  const ask = askVisible ? this.ask(now) : null;
3898
- chrome.setAsk?.(askVisible ? this.askSlot.display(ask, askAt, askPads, now) : null);
3910
+ const shownAsk = askVisible ? this.askSlot.display(ask, askAt, askPads, now) : null;
3911
+ chrome.setAsk?.(shownAsk);
3912
+ if (wantsPrompt && typeof shownAsk?.door === 'string') {
3913
+ this.signalDoor = shownAsk.door;
3914
+ }
3899
3915
  this.retireExpiredAsk(ask);
3900
3916
  this.startBeside(scene, local, town, now);
3901
3917
  // A friend or party member went through a door: say so, and offer to follow.
@@ -4347,8 +4363,11 @@ class HubSystem {
4347
4363
  context: engine.hubPadContext, ring: engine.hubPadRing, spawn: engine.hubSpawnRing };
4348
4364
  }
4349
4365
  const selfId = scene.multiplayer?.net?.selfId?.();
4350
- this.padReadability.frame(scene.actors, Hub.hub.hidden, local?.components.Transform, Boolean(this.trip),
4366
+ const captioned = this.padReadability.frame(scene.actors, Hub.hub.hidden, local?.components.Transform, Boolean(this.trip),
4351
4367
  this.carded || this.decor?.opened() === true, selfId != null && Hub.hub.guests?.has?.(selfId) === true);
4368
+ if (captioned && !this.signalDoor && this.signals?.wantsPrompt(Hub.hub.signalArrival)) {
4369
+ this.signalDoor = captioned;
4370
+ }
4352
4371
  }
4353
4372
 
4354
4373
  // A town's world labels under `hub.labels: "near"` (v1.43): the plate and
@@ -228,6 +228,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
228
228
  | `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). v1.158 `idle.expression` also calls this with `seatId: null` for sit-anywhere, independently of `idle.seats`. Return `false` to refuse; a hook that throws refuses |
229
229
  | `action(hub, playerId, id)` | v1.74, a place with `actions: true`: an arrived, connected player pressed an id in their current offer, carrying a safe-integer `n` equal to that offer's current version (§9). Stale, removed, another player's, malformed or over-budget presses are silently dropped. Six presses/s with a burst of eight per player; dropped or refused presses spend tokens too. The return is ignored; throws and rejections are contained and logged once. Async hooks are neither serialised nor cancelled when the player leaves. |
230
230
  | `menu(hub, playerId, id)` | v1.79, only with `menu: true`: an arrived, connected player picked an item in their current, last-sent menu with its safe-integer `n`, or closed the sheet (`id: "close"`). Stale, unknown, malformed and over-budget picks are dropped; readOnly refuses item picks but still delivers close. Six attempts/s, burst eight per player, including dropped presses. Return ignored; throws/rejections contained and logged once. Async hooks are neither serialised nor cancelled on leave. |
231
+ | `signal(hub, playerId, signal)` | v1.221, optional; defining it is the opt-in (no manifest key): one of a fixed vocabulary of a player's first moments (§12 "First-input signals"). From the client, each at most once per arrival and only within 120 s of it: `{ kind: 'move' }` (first walk input), `{ kind: 'jump' }` (first jump), `{ kind: 'prompt', door }` (the first door prompt shown: a question card offering a door, or a door pad's `hubPadContext` caption). From the kit, every time: `{ kind: 'talk', npc }` (a conversation opened by the Talk button or Act; `npc` is the NPC's actor id, or `'companion'` for the player's own companion), `{ kind: 'press', door }` (the player was put at a door they asked for: the Doors list's or a question card's Go, a People row, a party Go or Go-yes, a friend's House) and `{ kind: 'pad', door }` (the place's `hub.pad` first names them on that door's pad). `signal` is a fresh frozen object; no field is free text. Called after the kit's own work for the event; the return value is ignored, and a hook that throws or rejects is logged once and changes nothing. A kit older than v1.221 never calls it |
231
232
  | `answer(hub, playerId, id, text)` | v1.75, only in a place with `ask: true`: that arrived, connected player answered their last-sent and still-current prompt; `text` is the exact string they typed, or `null` for Cancel (§9). The prompt is consumed and its close queued before the hook runs. Refused text on a current id/version consumes the prompt and calls the hook with null; it is never passed on. Two attempts/s, burst four per player; stale, malformed, oversized and dropped messages spend tokens too. Return ignored; throws and rejections contained and logged once without the text or error details. A place must never show what a player typed to another player. |
232
233
  | `decor(hub, playerId, op)` | v1.67, a place with `decor`: an offered button or an open catalogue's validated edit (§10 Decorating). The deck checks ownership, stock and collisions and applies the edit; the kit moves or spawns nothing |
233
234
  | `ballot(hub, playerId, { face, line, option, mode })` | v1.68, a place with `ballot`: a player tapped the choice card (§6). `face` a player id on their card or null, `line` a manifest line id or null, `option` an option id of the card or null, `mode` the card's mode then. The kit has already checked it against the card that player was last sent and limited it; the hook decides what it means (a line for the card's `feed`, a vote to count). Its return is ignored; a hook that throws is logged |
@@ -3696,6 +3697,64 @@ place never keeps a stale hidden or visible. A place may pause its own guidance
3696
3697
  visible. This does not itself reconnect, arrive, leave or change progression;
3697
3698
  the existing `resume` hook remains independent.
3698
3699
 
3700
+ ### First-input signals (v1.221, opt-in by hook)
3701
+
3702
+ A place whose module exports a `signal` hook (§4) opts in; there is no
3703
+ manifest key, and an older kit simply never calls the hook. On each genuine
3704
+ arrival there (the arrival the place's `arrive` hook hears, not a rehello or a
3705
+ retained resume) the kit numbers the arrival and adds it to that player's
3706
+ `hub-arrived` as `signals: <n>`. A place without the hook sends
3707
+ `hub-arrived` exactly as before, and its clients send nothing.
3708
+
3709
+ For such an arrival, and only within 120 s of it, the client sends each of
3710
+ these at most once:
3711
+
3712
+ - `{ k: 'hub-signal', kind: 'move', a }`: the first walk input (a walk key,
3713
+ or the drag stick past 0.15);
3714
+ - `{ k: 'hub-signal', kind: 'jump', a }`: the first jump (Space, a tap the
3715
+ Player behavior takes, or Act's Jump);
3716
+ - `{ k: 'hub-signal', kind: 'prompt', a, door }`: the first door prompt
3717
+ shown, which is a question card that offers a door (`again`, a friend's
3718
+ `play`, Your games) or a door pad's caption (`engine.hubPadContext`) once
3719
+ the chrome has actually drawn it visible (not behind an open panel, not
3720
+ left unplaced). A party's
3721
+ proposal card names no door and is not one. A Town's pad words drawn as
3722
+ world labels are not a prompt either: the kit does not watch labels. A
3723
+ Town sees a player step onto a pad as `pad` below.
3724
+
3725
+ Keys typed into a text field count as neither a walk nor a jump. A signal is
3726
+ only marked sent once it went out on a connected socket during that arrival;
3727
+ once all three are sent or the 120 s are over, the client's per-frame check is
3728
+ one comparison. `a` is the arrival number the client was armed with.
3729
+
3730
+ A retained rehello or resume (a rejoined socket, or a page reloaded onto a
3731
+ retained body) is not an arrival. While the current arrival has window and
3732
+ kinds left, the server answers it with `{ k: 'hub-signals', n, left, sent }`:
3733
+ the same arrival number, the milliseconds left of its window and the kinds
3734
+ already spent. The client arms from that and says only what is left; neither
3735
+ the window nor the allowance starts again.
3736
+
3737
+ The server takes each from a present sender whose current arrival is still in
3738
+ its 120 s, named by the session and never by the payload, at most once per kind
3739
+ per arrival. A signal whose `a` is not the current arrival's number (one sent
3740
+ from an earlier arrival's record across a rejoin) is dropped before it spends
3741
+ anything; the once check comes next, before any door lookup, so a repeat costs
3742
+ one lookup. `move` and `jump` carry no other field; `prompt` must name one of the
3743
+ place's doors. Anything else is ignored silently. It is heard during a
3744
+ progress read too, as telemetry.
3745
+
3746
+ The kit adds three of its own, on every occurrence: `talk` when a conversation
3747
+ opens (`hub-npc-open`, or Act's Talk), `press` once it has put a player at a
3748
+ door they asked for (a door jump, a party Go or Go-yes, a friend's House
3749
+ visit), and `pad` when `hub.pad` first names a player on a door's pad. The hook
3750
+ runs after the kit's own work for that event.
3751
+
3752
+ Limits. A Town's pad words drawn as world labels are not a `prompt`; party
3753
+ proposals name no door, so their card is not one either. `talk`, `press` and
3754
+ `pad` are the server's own and fire every time, with no window or once rule; a
3755
+ place that keeps a bounded trace (the Town keeps 120 s) keeps only its own
3756
+ window of them. `move`, `jump` and `prompt` are best-effort: once per arrival,
3757
+ and lost if the socket drops while one is in flight.
3699
3758
 
3700
3759
  A first home unlock (v1.70, §11) sends private `{ k: 'hub-home-unlock' }`
3701
3760
  to its player only, announcing "Sent to your house". It carries no item and
@@ -5312,6 +5371,7 @@ a deck written before them remains valid.
5312
5371
 
5313
5372
  | date | change |
5314
5373
  | --- | --- |
5374
+ | 2026-11-18 (v1.221) | §4/§12 first-input signals: a place that exports a `signal(hub, playerId, { kind, npc?, door? })` hook hears `move`, `jump` and the first door `prompt` from the client (each at most once per arrival, within 120 s of it; `hub-arrived` carries the arrival's `signals` number only where the hook exists, each `hub-signal` carries it back as `a`, and a retained rehello is answered `hub-signals` with that arrival's remaining window and spent kinds) and the kit's own `talk`, `press` (door jump, party Go/Go-yes, House visit) and `pad` (`hub.pad` step-on). A fixed vocabulary of authored ids, no free text and no manifest key. Without the hook: no wrapper, message, state, hook dispatch or wire field. |
5315
5375
  | 2026-11-18 (v1.220) | §"A place replaced under its players" copy: when the ending is seen as the player comes back from away (`multiplayer.returning()`), the line is "<this place's title> closed while you were away. Back to <the place left>…" ("This place closed while you were away…" with no title) instead of "This place was updated", which was not true for an owner's House left empty past its reconnect window. A player who was present still sees the updated line. Copy only: no key, API or wire change. |
5316
5376
  | 2026-11-18 (v1.219) | §12 page visibility after a rejoin: a client whose connection is not up forgets the state it last sent and sends its current state once it is connected again (a send into a socket that died unseen, as on an app switch, no longer leaves the server holding a stale hidden); the server takes a rejoin's first `hub-visibility` even when it repeats the kept value, then coalesces as before. An avatar-change hello is not a rejoin. No new key or wire field. |
5317
5377
  | 2026-11-17 (v1.218) | Kit-internal, server only, no deck-facing key or API and no wire change: §5 two bodies never start on one spot. A body admitted with no pose where another body takes the scene spawn or the slot its lone arrival would take starts where that arrival will put it (the arrival slot if free, else the free spot beside it; one helper decides both) before its WORLD goes out, so that WORLD is the one placement its client makes, at once; arriving alone it stays there while the spot is still free, and a group with such a member takes the row's slots in the order its members stand along it. An arrival slot (an arrival, and the arrival a fall or a Stuck? unstick puts a player at) or stored pose (cold `resumePose`, arrival pose, retained visit) that another body takes is likewise stepped off on every place, not only on authored floors (`ground.none: true`); a free slot or pose is used exactly. A body takes a spot when it is nearer than two radii and overlaps it in height (one on a floor above or below does not), and only while its player is on the roster (real-time admits a joiner before it removes the bodies of players who left that tick). A group row's later slots are held where a body would stand in them. The search uses the place's own body size and treats a spot past the ground slab's edge (`ground.half`, 100 m by default) as unsupported unless an authored solid holds it; when every candidate fails the slot is shared, as before. Ground-backed places (the Town) kept the spawn for everyone, so two lone joiners stood on exactly the same point; on each client the two capsules were coaxial, Rapier pushed the local one into the ground under the other's avatar, and it could not walk until one left (Nov 17 Market check, reproduced locally). A stepped-off cold restore still reaches its client as the restore always has. Tests: `test-placeat-server` stepoff, arrivalFree and arrivalTaken (WORLD before hello, reports and corrections on: the client moves once), restoreFree, restoreOccupied; `test-standing` slab edge, floors, a leaver on the same tick and an elevated row, `test-rehello` and `test-stuck` updated; physics-3d `test-coaxial-escape`. |
@@ -5584,7 +5644,11 @@ for a place without a result. Ghost grants it to the host only on a trusted
5584
5644
  owner-house instance. Key absent keeps existing manifest and wire bytes.
5585
5645
 
5586
5646
  Ghost stamps the grace value `reconnectWindowMs: 180000` into the owner-house
5587
- session spec. A capable host retains each disconnected participant and token
5647
+ session spec, or `300000` when the chosen host advertises
5648
+ `supportsHouseResumeWindowMs: 300000` (so an owner's three-minute app switch,
5649
+ whose socket closes a few seconds after the page hides, keeps the house); the
5650
+ base SDK passes a value up to 300000 to `session.hub.reconnectWindowMs` only on
5651
+ such an owner house, and every other place keeps the 180000 cap. A capable host retains each disconnected participant and token
5588
5652
  through that deadline and keeps an empty opted-in house alive for that window. A guest reconnect is
5589
5653
  admitted only into that same live instance while its owner has a live connection;
5590
5654
  otherwise the existing spent-handoff recovery returns through the Town ticket.