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.
@@ -53,6 +53,8 @@ function boot(keys = {}, more = {}) {
53
53
  },
54
54
  fall: more.fall,
55
55
  resume: more.resume,
56
+ away: more.away,
57
+ back: more.back,
56
58
  message: more.message,
57
59
  leave(ctx, playerId) {
58
60
  leaves.push(playerId);
@@ -1180,6 +1182,198 @@ test('pinned Town:181s expires despite the old five-minute pose marker', () => k
1180
1182
  r.drop(); r.tick(); advance(181_000); r.tick(181_000); assert.equal(r.leaves.length, 1);
1181
1183
  }));
1182
1184
 
1185
+ // v1.229: pinned retention tells a place `away` once when it holds a dropped
1186
+ // player and `back` once on the same id's return inside the window.
1187
+ function awayBoot(keys = {}, more = {}) {
1188
+ const told = [];
1189
+ const r = boot(keys, { reconnectWindowMs: 180_000,
1190
+ away(c, id, info) { told.push(['away', id, { ...info }, c.players().some(p => p.playerId === id)]); },
1191
+ back(c, id, info) { told.push(['back', id, { ...info }, { ...c.players().find(p => p.playerId === id)?.at }]); },
1192
+ resume(c, { playerId }) { told.push(['resume', playerId]); },
1193
+ leave(c, id) { told.push(['leave', id]); },
1194
+ ...more });
1195
+ return { r, told };
1196
+ }
1197
+ for (const away of [30_000, 180_000]) {
1198
+ test(`v1.229 pinned: away once, back once after the pose is put back (${away} ms)`, () => keeping((advance) => {
1199
+ const { r, told } = awayBoot();
1200
+ const at = { x: 44.2, y: 1, z: -2.4 };
1201
+ r.ctx().placeAt('p2', at, 90); r.tick();
1202
+ r.drop(); r.tick();
1203
+ assert.deepEqual(told, [['away', 'p2', { userId: '102', username: 'Bo' }, false]]);
1204
+ r.tick(); advance(away); r.tick(away);
1205
+ assert.equal(told.length, 1, 'told away once while held');
1206
+ r.back(); r.say('p2', rehello); r.tick();
1207
+ assert.deepEqual(told.slice(1).map(t => t[0]), ['back', 'resume']);
1208
+ assert.deepEqual(told[1].slice(0, 3), ['back', 'p2', { userId: '102', username: 'Bo', awayMs: away }]);
1209
+ assert.deepEqual(told[1][3], at, 'back sees the restored pose');
1210
+ assert.equal(r.arrivedTimes('p2'), 1); assert.deepEqual(r.leaves, []);
1211
+ r.tick(); r.tick(5000);
1212
+ assert.equal(told.length, 3, 'nothing more while back');
1213
+ }));
1214
+ }
1215
+ test('v1.229 pinned: a body the host still holds is off hub.players() from away until back', () => keeping((advance) => {
1216
+ const { r, told } = awayBoot();
1217
+ const kept = r.world.players.get('p2');
1218
+ r.session.players = r.session.players.filter((p) => p.playerId !== 'p2'); r.tick();
1219
+ assert.equal(told[0][0], 'away'); assert.ok(r.world.players.get('p2') === kept);
1220
+ assert.ok(!r.ctx().players().some(p => p.playerId === 'p2'));
1221
+ r.world.players.delete('p2'); r.tick(); advance(5_000); r.back(); r.say('p2', rehello); r.tick();
1222
+ assert.ok(r.ctx().players().some(p => p.playerId === 'p2'));
1223
+ assert.deepEqual(told.map(t => t[0]), ['away', 'back', 'resume']);
1224
+ }));
1225
+ test('v1.229 pinned: a same-body return (roster row back, body never gone) is back', () => keeping((advance) => {
1226
+ const { r, told } = awayBoot();
1227
+ r.session.players = r.session.players.filter((p) => p.playerId !== 'p2');
1228
+ r.tick(); r.tick(); advance(20_000); r.tick(20_000); r.tick();
1229
+ assert.deepEqual(told.map(t => t[0]), ['away']);
1230
+ r.session.players.push({ playerId: 'p2', userId: '102', username: 'Bo', isAnonymous: false });
1231
+ r.tick(); r.say('p2', rehello); r.tick();
1232
+ assert.deepEqual(told.filter(t => t[0] !== 'resume').map(t => t[0]), ['away', 'back']);
1233
+ assert.ok(r.ctx().players().some(p => p.playerId === 'p2'));
1234
+ assert.deepEqual(r.leaves, []);
1235
+ }));
1236
+ test('v1.229 pinned: the held deadline does not move while the body lingers', () => keeping((advance) => {
1237
+ const { r, told } = awayBoot();
1238
+ r.session.players = r.session.players.filter((p) => p.playerId !== 'p2');
1239
+ r.tick();
1240
+ for (let i = 0; i < 4; i += 1) { advance(50_000); r.tick(50_000); }
1241
+ assert.deepEqual(told.map(t => t.slice(0, 2)), [['away', 'p2'], ['leave', 'p2']]);
1242
+ }));
1243
+ test('v1.229 pinned: expiry with a lingering body keeps the player off hub.players() during leave and after', () => keeping((advance) => {
1244
+ const seen = [];
1245
+ const { r } = awayBoot({}, { leave(c, id) { seen.push(c.players().some(p => p.playerId === id)); } });
1246
+ r.session.players = r.session.players.filter((p) => p.playerId !== 'p2');
1247
+ r.tick(); advance(181_000); r.tick(181_000);
1248
+ assert.deepEqual(seen, [false]);
1249
+ r.tick(); assert.ok(!r.ctx().players().some(p => p.playerId === 'p2'));
1250
+ r.world.players.delete('p2'); r.tick();
1251
+ r.back(); r.say('p2', rehello); r.tick(2000); r.tick();
1252
+ assert.ok(r.ctx().players().some(p => p.playerId === 'p2'), 'a fresh arrival on the id is listed');
1253
+ }));
1254
+ test('v1.229 pinned: another account back on the id is a leave of the old visit, never back', () => keeping((advance) => {
1255
+ const { r, told } = awayBoot();
1256
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000);
1257
+ r.session.players.push({ playerId: 'p2', userId: '103', username: 'Cy', isAnonymous: false });
1258
+ r.world.players.set('p2', body());
1259
+ r.say('p2', rehello); r.tick(2000); r.tick();
1260
+ assert.ok(!told.some(t => t[0] === 'back'));
1261
+ assert.deepEqual(told.filter(t => t[0] === 'leave').map(t => t[1]), ['p2']);
1262
+ assert.ok(!r.sent.some(([id, m]) => id === 'p2' && m.k === 'hub-end'), 'no door end sent to the newcomer');
1263
+ }));
1264
+ for (const where of ['away', 'back']) {
1265
+ test(`v1.229 pinned: a visit ended in ${where} gets no back and no retained replay`, () => keeping((advance) => {
1266
+ const calls = [];
1267
+ const { r } = awayBoot({}, {
1268
+ away(c, id) { calls.push('away'); if (where === 'away') {c.end([id]);} },
1269
+ back(c, id) { calls.push('back'); if (where === 'back') {c.end([id]);} },
1270
+ resume() { calls.push('resume'); },
1271
+ });
1272
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000); r.back(); r.say('p2', rehello); r.tick();
1273
+ r.say('p2', rehello); r.tick(); r.say('p2', rehello); r.tick();
1274
+ if (where === 'away') {
1275
+ assert.deepEqual(calls, ['away'], 'no back, no retained resume on any hello');
1276
+ assert.deepEqual(r.leaves, ['p2'], 'the ended visit leaves once');
1277
+ } else {
1278
+ assert.deepEqual(calls.slice(0, 2), ['away', 'back']);
1279
+ assert.ok(!calls.slice(2).includes('back'));
1280
+ }
1281
+ }));
1282
+ }
1283
+ test('v1.229 pinned: the identity check runs before the old pose is put on the newcomer', () => keeping((advance) => {
1284
+ const { r, told } = awayBoot();
1285
+ const at = { x: 44.2, y: 1, z: -2.4 };
1286
+ r.ctx().placeAt('p2', at, 90); r.tick();
1287
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000);
1288
+ r.session.players.push({ playerId: 'p2', userId: '103', username: 'Cy', isAnonymous: false });
1289
+ const fresh = body(); r.world.players.set('p2', fresh);
1290
+ r.say('p2', rehello);
1291
+ assert.notDeepEqual(fresh.at, at, 'the newcomer is not moved to the old visit\'s pose');
1292
+ assert.ok(!told.some(t => t[0] === 'back'));
1293
+ }));
1294
+ test('v1.229 pinned: a different anonymous guest on the id is not back', () => keeping((advance) => {
1295
+ const guests = [
1296
+ { playerId: 'p1', userId: '101', username: 'Ada', isAnonymous: false },
1297
+ { playerId: 'p2', userId: '9001', username: 'guest', isAnonymous: true },
1298
+ ];
1299
+ const { r, told } = awayBoot({}, { players: guests });
1300
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000);
1301
+ r.session.players.push({ playerId: 'p2', userId: '9002', username: 'guest', isAnonymous: true });
1302
+ r.world.players.set('p2', body());
1303
+ r.say('p2', rehello); r.tick(2000); r.tick();
1304
+ assert.equal(told[0][0], 'away');
1305
+ assert.ok(!told.some(t => t[0] === 'back'));
1306
+ assert.deepEqual(told.filter(t => t[0] === 'leave').map(t => t[1]), ['p2']);
1307
+ }));
1308
+ test('v1.229 pinned: the same anonymous guest back on the id is back', () => keeping((advance) => {
1309
+ const guest = { playerId: 'p2', userId: '9001', username: 'guest', isAnonymous: true };
1310
+ const { r, told } = awayBoot({}, { players: [{ playerId: 'p1', userId: '101', username: 'Ada', isAnonymous: false }, guest] });
1311
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000);
1312
+ r.session.players.push({ ...guest }); r.world.players.set('p2', body());
1313
+ r.say('p2', rehello); r.tick();
1314
+ assert.deepEqual(told.filter(t => t[0] !== 'resume').map(t => t[0]), ['away', 'back']);
1315
+ }));
1316
+ test('v1.229 pinned: a second drop after back tells away again', () => keeping((advance) => {
1317
+ const { r, told } = awayBoot();
1318
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000); r.back(); r.say('p2', rehello); r.tick();
1319
+ r.drop(); r.tick(); advance(5_000); r.tick(5_000); r.back(); r.say('p2', rehello); r.tick();
1320
+ assert.deepEqual(told.map(t => t[0]), ['away', 'back', 'resume', 'away', 'back', 'resume']);
1321
+ assert.equal(told[4][2].awayMs, 5_000);
1322
+ }));
1323
+ test('v1.229 pinned: past the window, away is followed by leave and no back', () => keeping((advance) => {
1324
+ const { r, told } = awayBoot();
1325
+ r.drop(); r.tick(); advance(181_000); r.tick(181_000);
1326
+ assert.deepEqual(told.map(t => t.slice(0, 2)), [['away', 'p2'], ['leave', 'p2']]);
1327
+ r.back(); r.say('p2', rehello); r.tick(2000); r.tick();
1328
+ assert.ok(!told.some(t => t[0] === 'back'), 'a return past the window is not a back');
1329
+ }));
1330
+ test('v1.229 pinned: Back, then a drop, is a leave with no away', () => keeping(() => {
1331
+ const { r, told } = awayBoot();
1332
+ r.say('p2', { k: 'hub-back' }); r.tick(); r.drop(); r.tick();
1333
+ assert.deepEqual(told.map(t => t.slice(0, 2)), [['leave', 'p2']]);
1334
+ }));
1335
+ test('v1.229 pinned: shutdown drains a player told away with leave alone', async () => {
1336
+ const { r, told } = awayBoot();
1337
+ r.drop(); r.tick();
1338
+ await r.server.shutdown();
1339
+ assert.deepEqual(told.filter(t => t[1] === 'p2').map(t => t.slice(0, 2)), [['away', 'p2'], ['leave', 'p2']]);
1340
+ });
1341
+ test('v1.229 pinned: a hook that throws is contained and the hold goes on', () => keeping((advance) => {
1342
+ const calls = [];
1343
+ const { r } = awayBoot({}, { away() { calls.push('away'); throw new Error('x'); }, back() { calls.push('back'); throw new Error('y'); } });
1344
+ const warn = console.warn; console.warn = () => {};
1345
+ try {
1346
+ r.drop(); r.tick(); advance(30_000); r.tick(30_000); r.back(); r.say('p2', rehello); r.tick();
1347
+ } finally { console.warn = warn; }
1348
+ assert.deepEqual(calls, ['away', 'back']);
1349
+ assert.equal(r.arrivedTimes('p2'), 1); assert.deepEqual(r.leaves, []);
1350
+ }));
1351
+ test('v1.229 pinned: back without a hello (late greet) still tells back once', () => keeping((advance) => {
1352
+ const { r, told } = awayBoot();
1353
+ r.drop(); r.tick(); advance(20_000); r.tick(20_000); r.back(); r.tick(); r.tick(3500); r.say('p2', rehello); r.tick();
1354
+ assert.deepEqual(told.filter(t => t[0] !== 'resume').map(t => t[0]), ['away', 'back']);
1355
+ }));
1356
+ test('v1.229: no pinned window, no away or back (60 s keep and plain places)', () => keeping((advance) => {
1357
+ for (const [keys, more] of [[keepGame, {}], [{ resumePose: true }, {}], [{}, {}]]) {
1358
+ const calls = [];
1359
+ const r = boot(keys, { ...more, away() { calls.push('away'); }, back() { calls.push('back'); } });
1360
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000); r.back(); r.say('p2', rehello); r.tick();
1361
+ assert.deepEqual(calls, [], JSON.stringify(keys));
1362
+ }
1363
+ }));
1364
+ for (const only of ['away', 'back']) {
1365
+ test(`v1.229 pinned: a place with only ${only} is told neither and keeps the visit as before`, () => keeping((advance) => {
1366
+ const calls = [];
1367
+ const r = boot({}, { reconnectWindowMs: 180_000, [only]() { calls.push(only); } });
1368
+ const warn = console.warn; const warned = []; console.warn = (m) => warned.push(m);
1369
+ try {
1370
+ r.drop(); r.tick(); advance(10_000); r.tick(10_000); r.back(); r.say('p2', rehello); r.tick();
1371
+ } finally { console.warn = warn; }
1372
+ assert.deepEqual(calls, []); assert.equal(r.arrivedTimes('p2'), 1); assert.deepEqual(r.leaves, []);
1373
+ assert.equal(warned.filter(m => String(m).includes('away and back are a pair')).length, 1);
1374
+ }));
1375
+ }
1376
+
1183
1377
  // v1.98: server-only town opt-in; the visit's first door is not a new trip.
1184
1378
  for (const away of [30_000, 180_000, 299_999]) {
1185
1379
  test(`town resumePose: ${away} ms same-id return restores before resume hook`, () => keeping((advance) => {
@@ -206,28 +206,101 @@ const dock = { people: { x: 10, y: 118, w: 100, h: 38 }, doors: { x: 10, y: 162,
206
206
  clearOfAll(drawn, controls, 'act prompt');
207
207
  }
208
208
 
209
- // Review: projected world labels and pointers (the world layout pass) make
210
- // way for the act prompt's held place, not its new lane: a label on the new
211
- // lane is drawn exactly as when the prompt was still at its old place.
209
+ // Projected world labels and pointers (the world layout pass) make way for
210
+ // the act prompt's held place, as before, and for the lane it is drawn on
211
+ // now: the prompt is painted over anything left under it (door-ui pass,
212
+ // Nov 19: Talk to Rowan, the greeter, over Vela's line in the Town).
212
213
  {
213
214
  const rect = (left, top, w, h) => ({ left, top, right: left + w, bottom: top + h, width: w, height: h });
215
+ const hit = (a, b) => a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
214
216
  const node = (at) => ({ style: {}, getBoundingClientRect() {
215
217
  const [dx, dy] = (this.style.translate || '0 0').split(' ').map(Number.parseFloat);
216
218
  return rect(at.left + dx, at.top + dy, at.width, at.height);
217
219
  } });
218
- const run = (actAt, heldAt) => {
219
- const label = node(rect(300, 40, 80, 22)), pointer = node(rect(120, 40, 70, 22)), act = node(actAt);
220
+ const run = (actAt, heldAt, labelAt = rect(300, 40, 80, 22)) => {
221
+ const label = node(labelAt), pointer = node(rect(120, 40, 70, 22)), act = node(actAt);
220
222
  const entries = [{ kind: 'label', node: label, id: 'label:rowan' }, { kind: 'pointer', node: pointer, id: 'pointer:door' },
221
223
  { kind: 'control', node: act, id: 'act-prompt:greeter', transient: true }];
222
224
  const layout = makeWorldLayout(() => entries, () => ({ w: 562, h: 241 }), () => [], undefined, (n) => n === act ? heldAt : null);
223
225
  layout.flush();
224
- return { label: [label.style.translate, label.style.visibility], pointer: [pointer.style.translate, pointer.style.visibility] };
226
+ return { label: [label.style.translate, label.style.visibility], pointer: [pointer.style.translate, pointer.style.visibility], at: pointer.getBoundingClientRect() };
225
227
  };
226
228
  const old = rect(185, 191, 208, 44);
227
229
  const before = run(old, null);
228
- assert.deepEqual(run(rect(110, 30, 280, 44), old), before, 'labels and pointers placed as before');
229
- assert.deepEqual(before, { label: [undefined, undefined], pointer: [undefined, undefined] }, 'untouched where clear');
230
+ assert.deepEqual([before.label, before.pointer], [[undefined, undefined], [undefined, undefined]], 'untouched where clear');
231
+ // A lane clear of both: placed as before.
232
+ const aside = run(rect(400, 100, 150, 44), old);
233
+ assert.deepEqual([aside.label, aside.pointer], [before.label, before.pointer], 'a lane clear of them moves nothing');
230
234
  // A hidden act prompt (no live box) is still made way for at its old place.
231
- assert.deepEqual(run(rect(0, 0, 0, 0), old), before, 'and while it is not drawn');
235
+ assert.deepEqual([run(rect(0, 0, 0, 0), old).label, run(rect(0, 0, 0, 0), old).pointer], [before.label, before.pointer], 'and while it is not drawn');
236
+ // The new lane over the label and the pointer: neither is left under it.
237
+ const lane = rect(110, 30, 280, 44);
238
+ const over = run(lane, old);
239
+ assert.equal(over.label[1], 'hidden', 'a plain label under the new lane is not drawn under the pill');
240
+ assert(over.pointer[1] !== 'hidden' && !hit(over.at, lane), 'the pointer steps clear of it');
241
+ // An NPC's line (`edge`) under the new lane steps clear of it rather than being hidden.
242
+ const say = node(rect(140, 40, 240, 42)), act = node(lane);
243
+ const layout = makeWorldLayout(() => [{ kind: 'label', node: say, id: 'label:barker', edge: true }, { kind: 'control', node: act, id: 'act-prompt:greeter', transient: true }],
244
+ () => ({ w: 562, h: 241 }), () => [], undefined, (n) => n === act ? old : null);
245
+ layout.flush();
246
+ assert.notEqual(say.style.visibility, 'hidden', 'the line is drawn');
247
+ assert(!hit(say.getBoundingClientRect(), lane) && !hit(say.getBoundingClientRect(), old), 'clear of the pill where it is drawn and where it was');
232
248
  }
249
+ // Review round 1 (Nov 19): the same, through the real frame cache. Safe
250
+ // layout moves an act pill with `--hub-safe-translate` (an !important rule
251
+ // on `data-hub-safe-translate`), not inline `translate`; the cache sampled
252
+ // the pill at its natural place (y 191) and, reading only inline translate,
253
+ // kept serving that box after the move to y 30, so a label under the drawn
254
+ // pill stayed visible. A pill moved after the frame's snapshot is read where
255
+ // it is drawn.
256
+ {
257
+ const { makeLayoutCache } = await import('../code/client/layoutCache.js');
258
+ const { makeSafeStyle } = await import('../code/client/safeStyle.js');
259
+ const hit = (a, b) => a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
260
+ // A browser-like node: inline styles, custom properties, attributes, and a
261
+ // drawn box that honours the !important safe translate over the inline one.
262
+ const node = (left, top, width, height) => {
263
+ const props = new Map(), attrs = new Map();
264
+ const style = { left: `${left}px`, top: `${top}px`, translate: '',
265
+ setProperty: (k, v) => props.set(k, v), removeProperty: (k) => props.delete(k), getPropertyValue: (k) => props.get(k) ?? '' };
266
+ const self = { style, textContent: '', className: '', isConnected: true, children: [],
267
+ setAttribute: (k, v) => attrs.set(k, v), removeAttribute: (k) => attrs.delete(k), hasAttribute: (k) => attrs.has(k),
268
+ getAttributeNames: () => [...attrs.keys()], getAttribute: (k) => attrs.get(k),
269
+ get offsetWidth() {return width;}, get offsetHeight() {return height;},
270
+ getBoundingClientRect() {
271
+ const safe = attrs.has('data-hub-safe-translate') ? props.get('--hub-safe-translate') : null;
272
+ const [dx, dy] = ((safe && safe !== 'revert' ? safe : style.translate) || '0 0').split(' ').map((v) => Number.parseFloat(v) || 0);
273
+ const l = Number.parseFloat(style.left) + dx, t = Number.parseFloat(style.top) + dy;
274
+ return { left: l, top: t, right: l + width, bottom: t + height, width, height };
275
+ } };
276
+ return self;
277
+ };
278
+ const prevDocument = globalThis.document;
279
+ globalThis.document = { createElement: () => ({ remove() {}, textContent: '' }) };
280
+ const safe = makeSafeStyle({ appendChild() {} });
281
+ globalThis.document = prevDocument;
282
+ const act = node(185, 191, 208, 44), label = node(140, 40, 200, 22);
283
+ const geometry = makeLayoutCache();
284
+ geometry.register(act, { positioned: true });
285
+ geometry.register(label, { positioned: true });
286
+ const entries = [{ kind: 'label', node: label, id: 'label:vela' }, { kind: 'control', node: act, id: 'act-prompt:greeter', transient: true }];
287
+ const old = { left: 185, top: 191, right: 393, bottom: 235 };
288
+ const layout = makeWorldLayout(() => entries, () => ({ w: 562, h: 400 }), () => [], geometry, (n) => n === act ? old : null);
289
+ geometry.beginFrame([act, label]);
290
+ assert.equal(geometry.rect(act).top, 191, 'sampled at its natural place');
291
+ // Safe layout moves the pill onto the label's row after the sample.
292
+ safe.write(act, 'translate', '0px -161px');
293
+ assert.equal(act.getBoundingClientRect().top, 30, 'drawn at y 30');
294
+ assert.equal(geometry.rect(act).top, 30, 'the cache reads it where it is drawn');
295
+ layout.flush();
296
+ const drawn = label.getBoundingClientRect();
297
+ assert(label.style.visibility === 'hidden' || !hit(drawn, act.getBoundingClientRect()), 'the label is not left under the drawn pill');
298
+ geometry.endFrame();
299
+ // Cleared again: read back at its natural place.
300
+ geometry.beginFrame([act, label]);
301
+ safe.clearNode(act);
302
+ assert.equal(geometry.rect(act).top, 191, 'back where it was once safe layout lets go');
303
+ geometry.endFrame();
304
+ }
305
+
233
306
  console.log('safe act: the act prompt leaves the controls for the nearest clear lane, or is not drawn; everything else is placed as before');
@@ -708,12 +708,19 @@ for (const focused of [true, false]) {
708
708
  assert(below && !below.line && below.top === talk.bottom + 8, 'below the prompt when there is no room above');
709
709
  for (const other of [talk, ...corners]) {assert(!hit(below, other), 'clear of the prompt and the corners');}
710
710
  // The whole Run 3 frame (the Harbour sign, Sound, the Invite and Market
711
- // chips): its first line alone, above the prompt.
712
- const [first] = worldPlacement([], [rowan], [talk, sign, sound, chips], view).labels;
711
+ // chips): nothing whole near it, so the nearest whole slot on the screen,
712
+ // under the chips, rather than its first line alone (door-ui pass, Nov 19).
713
+ const [far] = worldPlacement([], [rowan], [talk, sign, sound, chips], view).labels;
714
+ assert(far && !far.line, 'drawn whole');
715
+ assert.deepEqual([far.left, far.top, Number((far.bottom - far.top).toFixed(3))], [6, chips.bottom + 8, Number(h.toFixed(3))], 'under the chips, at its own size');
716
+ for (const other of [talk, sign, sound, chips, ...corners]) {assert(!hit(far, other), 'whole and clear of everything');}
717
+ // With no whole slot anywhere (the rest of the view taken), its first line alone, above the prompt.
718
+ const rest = rect(0, 224, 404, 721);
719
+ const [first] = worldPlacement([], [rowan], [talk, sign, sound, chips, rest], view).labels;
713
720
  assert(first?.line, 'the one-line form');
714
721
  assert.deepEqual([first.left, first.top, first.bottom], [6, talk.top - 8 - 24.9, talk.top - 8], 'one line tall, above the prompt');
715
- for (const other of [talk, sign, sound, chips, ...corners]) {assert(!hit(first, other), 'one line clear of everything');}
716
- assert.deepEqual(worldPlacement([], [{ ...rowan, line: null }], [talk, sign, sound, chips], view).labels, [null], 'no line height, no one-line form: hidden');
722
+ for (const other of [talk, sign, sound, chips, rest, ...corners]) {assert(!hit(first, other), 'one line clear of everything');}
723
+ assert.deepEqual(worldPlacement([], [{ ...rowan, line: null }], [talk, sign, sound, chips, rest], view).labels, [null], 'no line height, no one-line form: hidden');
717
724
  assert.deepEqual(worldPlacement([], [rowan], [rect(0, 0, 404, 721)], view).labels, [null], 'nothing clear: hidden');
718
725
  // A control still hides a label without `edge`, and an anchor off the view still hides it.
719
726
  assert.deepEqual(worldPlacement([], [rect(20, 65.6, 290, 124.2)], [talk], view).labels, [null], 'a sign under a control is still dropped');
@@ -726,6 +733,101 @@ for (const focused of [true, false]) {
726
733
  assert(clearOfCorner.left >= 36, 'inside the inset');
727
734
  }
728
735
 
736
+ // A Town barker on a 390x844 phone (door-ui pass, Nov 19, Nightwatch): its
737
+ // line is "Morrow, the street barker: " and three lines of words at 62vw
738
+ // (241.8 x 58.7). Sound (338,64-378,104) and a row of action chips are over
739
+ // its slid box, the pad's plate beside it, its own held Talk prompt under it
740
+ // and a goal pointer under that, so nothing whole is near. It was drawn as
741
+ // its first line alone at 115.1 (the capture's 116), which is only the
742
+ // barker's name; now it is drawn whole in the nearest clear slot, clear of
743
+ // all of it and of the avatar.
744
+ {
745
+ const view = { w: 390, h: 844, insets: { top: 0, right: 0, bottom: 0, left: 0 } };
746
+ const rect = (left, top, right, bottom, extra = {}) => ({ left, top, right, bottom, ...extra });
747
+ const hit = (a, b) => a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
748
+ const hud = rect(65, 12, 325, 37), sound = rect(338, 64, 378, 104), chips = rect(54, 40, 330, 84), plate = rect(21, 112, 132, 146);
749
+ const held = rect(150, 148, 382, 192), pointer = rect(81, 208.7, 212, 227), avatar = rect(120, 330, 270, 590);
750
+ const morrow = rect(140.2, 82.2, 382, 140.9, { edge: true, line: 24.9 });
751
+ const taken = [hud, sound, chips, plate, held, pointer, avatar];
752
+ const [line] = worldPlacement([], [morrow], taken, view).labels;
753
+ assert(line && !line.line, 'the barker\'s line is drawn whole');
754
+ assert.deepEqual([line.right - line.left, line.bottom - line.top].map((n) => Number(n.toFixed(3))), [morrow.right - morrow.left, morrow.bottom - morrow.top].map((n) => Number(n.toFixed(3))), 'at its own size');
755
+ for (const other of [...taken, rect(0, 0, 64, 56), rect(326, 0, 390, 56)]) {assert(!hit(line, other), 'clear of the HUD, Sound, the chips, the plate, the prompt, the pointer, the avatar and the corners');}
756
+ assert.deepEqual([line.left, line.top], [140.2, pointer.bottom + 8], 'the nearest: under the pointer, at its own left');
757
+ assert(line.top >= 6 && line.bottom <= 838 && line.left >= 6 && line.right <= 384, 'inside the view');
758
+ console.log('world labels: a barker line with nothing whole near it is drawn whole farther off, never as its name alone passed');
759
+ }
760
+
761
+ // Review round 1 (Nov 19): the far slot is the nearest by distance, not
762
+ // above-first, and it is held while it stays clear. A line whose near search
763
+ // fails (a band of controls 166-440 under it) used to flip between y 448
764
+ // (148 px away, below) and y 99 (above, much farther) on a 0.2 px anchor move.
765
+ {
766
+ const view = { w: 390, h: 844, insets: { top: 0, right: 0, bottom: 0, left: 0 } };
767
+ const rect = (left, top, right, bottom, extra = {}) => ({ left, top, right, bottom, ...extra });
768
+ const hit = (a, b) => a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
769
+ const band = rect(0, 166, 390, 440);
770
+ const line = (y, far) => rect(140, y, 380, y + 59, { edge: true, line: 24.9, ...(far ? { far } : {}) });
771
+ const tops = [];
772
+ let far = null;
773
+ for (const y of [300, 300.2, 299.8, 300.4, 300]) {
774
+ const [placed] = worldPlacement([], [line(y, far)], [band], view).labels;
775
+ assert(placed && !placed.line && !hit(placed, band), `drawn whole and clear at anchor ${y}`);
776
+ tops.push(placed.top); far = placed.far;
777
+ }
778
+ // Held as an offset from the slid box, so it follows the speaker's sub-pixel moves.
779
+ assert(tops.every((top, i) => Math.abs(top - 448 - [0, 0.2, -0.2, 0.4, 0][i]) < 1e-9), `the close slot below, every time (${tops})`);
780
+ // Held: with the band reaching to 520 the nearest whole slot is above (99);
781
+ // when the band shrinks back, the slot below (448) is nearer, but the held
782
+ // one is still clear, so the line stays where it is.
783
+ const tall = rect(0, 166, 390, 520);
784
+ const [up] = worldPlacement([], [line(300)], [tall], view).labels;
785
+ assert.equal(up.top, 99, 'above when the band runs to 520');
786
+ const [kept] = worldPlacement([], [line(300, up.far)], [band], view).labels;
787
+ assert.equal(kept.top, 99, 'kept while its last place is clear');
788
+ const [fresh] = worldPlacement([], [line(300)], [band], view).labels;
789
+ assert.equal(fresh.top, 448, 'with nothing held, the nearer slot');
790
+ // Once the held place is taken, the nearest clear one.
791
+ const [moved] = worldPlacement([], [line(300, up.far)], [band, rect(0, 60, 390, 166)], view).labels;
792
+ assert.equal(moved.top, 448, 'moves once its place is taken');
793
+ console.log('world labels: a far NPC line goes to the nearest slot by distance and is held while clear passed');
794
+ }
795
+
796
+ // Review round 2 (Nov 19): no flip between a near slot and a held far one.
797
+ // The line's own slot (y 300-359) fits a 59.2 px gap between C (to 299.9)
798
+ // and D (from 359.1) only to a tenth of a pixel: at y 300.2 it touches D and
799
+ // nothing near fits, so it goes to the far slot under D. Back at y 300 its
800
+ // own slot is clear by 0.1 px, not by the 8 px margin, so it stays in the
801
+ // held far slot. Moves of +-0.2 px both ways never flip it. It returns near
802
+ // once its own slot is clear by the margin (D gone).
803
+ {
804
+ const view = { w: 390, h: 844, insets: { top: 0, right: 0, bottom: 0, left: 0 } };
805
+ const rect = (left, top, right, bottom, extra = {}) => ({ left, top, right, bottom, ...extra });
806
+ const C = rect(0, 100, 390, 299.9), D = rect(0, 359.1, 390, 440);
807
+ const line = (y, far) => rect(140, y, 380, y + 59, { edge: true, line: 24.9, ...(far ? { far } : {}) });
808
+ let far = null;
809
+ const seen = [];
810
+ for (const y of [300, 300.2, 300, 300.2, 299.8, 300, 300.2, 300]) {
811
+ const [placed] = worldPlacement([], [line(y, far)], [C, D], view).labels;
812
+ assert(placed && placed.line !== true, `drawn whole at ${y}`);
813
+ seen.push([y, placed.far ? 'far' : 'near', Number(placed.top.toFixed(3))]);
814
+ far = placed.far ?? null;
815
+ }
816
+ assert.deepEqual(seen.map(([, kind]) => kind), ['near', 'far', 'far', 'far', 'far', 'far', 'far', 'far'],
817
+ `near only until it first fails, then held far (${JSON.stringify(seen)})`);
818
+ assert(seen.slice(1).every(([y, , top]) => Math.abs(top - (y + 147.8)) < 1e-6), 'the held slot follows the speaker under D');
819
+ // Released: C pulled back to 280 and D gone, its own slot is clear by 20 px.
820
+ const [back] = worldPlacement([], [line(300, far)], [rect(0, 100, 390, 280)], view).labels;
821
+ assert(back && !back.far && back.top === 300, 'back to its own slot once clear by the margin');
822
+ // Starting near, +-0.2 px moves inside the margin keep it near.
823
+ const roomy = rect(0, 100, 390, 280);
824
+ for (const y of [300, 300.2, 299.8]) {
825
+ const [placed] = worldPlacement([], [line(y)], [roomy], view).labels;
826
+ assert(placed && !placed.far && placed.top === y, `near stays near at ${y}`);
827
+ }
828
+ console.log('world labels: no frame-to-frame flip between a near slot and a held far one passed');
829
+ }
830
+
729
831
  // The drawn width: a label's measure is its fractional box, not the
730
832
  // whole-pixel offsetWidth, so labelBox's 6 px pin is where it is drawn.
731
833
  {
@@ -89,8 +89,8 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
89
89
  - `shadows` -- sun shadows drawn near the camera instead of in a fixed box:
90
90
  docs/engine-shadows.md.
91
91
  - `camera` -- `follow: "rigid"`, the `control: "orbit"` third-person
92
- camera, and its `pitch`, `minPitch`, `distance` and `fov`; also the rule
93
- for steady forces: docs/engine-camera.md.
92
+ camera, and its `pitch`, `minPitch`, `distance`, `fov` and `portrait`
93
+ starts; also the rule for steady forces: docs/engine-camera.md.
94
94
  - `player.slideOnWalls: true` -- project the built-in grounded walk along
95
95
  nearby fixed solid walls: docs/engine-player.md.
96
96
  - `view` -- view distance and fog: docs/engine-view.md.
@@ -525,20 +525,22 @@ const finiteOr = (value, otherwise) => (Number.isFinite(value) ? value : otherwi
525
525
  // at the scene's starting pitch and distance (or the defaults), and start
526
526
  // again when those keys or camDistance/camHeight change. The latter two
527
527
  // ask for a fresh camera but do not set its orbit distance or pitch.
528
+ // While the canvas is taller than wide, `engine.camera.portrait`'s finite
529
+ // distance and pitch stand in for the starts, so turning the phone is a
530
+ // change of start like any other and restarts the camera at that
531
+ // orientation's own. Without the key nothing below reads the canvas.
528
532
  function orbitChoice(scene, props) {
529
533
  const distance = finiteOr(props.camDistance, 9);
530
534
  const height = finiteOr(props.camHeight, 7);
531
- // Only a finite number is a start; anything else is the default, so a
532
- // copy of the same scene data (a fresh {} included) never restarts it.
533
- const startDistance = finiteOr(scene.data?.engine?.camera?.distance, undefined);
534
- const startPitch = finiteOr(scene.data?.engine?.camera?.pitch, undefined);
535
+ const { startDistance, startPitch, orientation } = orbitStarts(scene);
535
536
  const minPitch = finiteOr(scene.data?.engine?.camera?.minPitch, undefined);
536
537
  const least = clamp(finiteOr(minPitch, -80) * DEG, ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST);
537
538
  const chosen = scene.cameraOrbit;
538
539
  if (chosen && chosen.distance === distance && chosen.height === height
539
540
  && Object.is(chosen.startDistance, startDistance) && Object.is(chosen.startPitch, startPitch)
540
- && Object.is(chosen.minPitch, minPitch)) return chosen;
541
+ && Object.is(chosen.minPitch, minPitch) && Object.is(chosen.orientation, orientation)) return chosen;
541
542
  scene.cameraOrbit = {
543
+ ...(orientation === undefined ? {} : { orientation }),
542
544
  distance,
543
545
  height,
544
546
  startDistance,
@@ -553,6 +555,28 @@ function orbitChoice(scene, props) {
553
555
  return scene.cameraOrbit;
554
556
  }
555
557
 
558
+ // The starting distance and pitch. Only a finite number is a start;
559
+ // anything else is the default, so a copy of the same scene data (a fresh
560
+ // {} included) never restarts the camera. With `portrait` (an object) also
561
+ // which way the canvas faces, so a turn restarts the camera even where both
562
+ // orientations' starts are the same; without it the canvas is not read.
563
+ function orbitStarts(scene) {
564
+ const camera = scene.data?.engine?.camera;
565
+ const keyed = camera?.portrait && typeof camera.portrait === 'object' ? camera.portrait : null;
566
+ const tall = keyed && tallCanvas(scene) ? keyed : null;
567
+ return {
568
+ startDistance: finiteOr(tall?.distance, finiteOr(camera?.distance, undefined)),
569
+ startPitch: finiteOr(tall?.pitch, finiteOr(camera?.pitch, undefined)),
570
+ orientation: keyed ? (tall ? 'tall' : 'wide') : undefined,
571
+ };
572
+ }
573
+
574
+ // Whether the camera is taller than wide.
575
+ function tallCanvas(scene) {
576
+ const aspect = scene.three?.camera?.aspect;
577
+ return Number.isFinite(aspect) && aspect > 0 && aspect < 1;
578
+ }
579
+
556
580
  // What the player asked of the camera this frame, onto what it is aimed for.
557
581
  function steerOrbit(per, chosen, look) {
558
582
  per.camAngle += look.yaw;
@@ -61,5 +61,5 @@
61
61
  "autoUpdateWhenImported": true,
62
62
  "deckId": "JH0SclbPVP0y",
63
63
  "cardId": "eXfAaUdbSU5A",
64
- "publishedVersion": "2026-11-19T09:37:22.766Z"
64
+ "publishedVersion": "2026-11-19T11:14:34.739Z"
65
65
  }
@@ -234,7 +234,20 @@ the `engine` object at a scene file's top level, beside `ground`.
234
234
  to -80..80. Absent, non-finite or non-number keeps the -80 degree floor
235
235
  above. A value of 0 keeps the camera at or above the point it looks at;
236
236
  a starting pitch below the floor is raised to it. Unlike `pitch`, this
237
- floor limits the player's drags throughout play. `camDistance` and
237
+ floor limits the player's drags throughout play.
238
+ `engine.camera.portrait` (`{ "distance": 6, "pitch": 25 }`, both
239
+ optional) holds the starts while the canvas is taller than wide (the
240
+ camera's aspect below 1): its finite distance and pitch stand in for
241
+ `distance` and `pitch` then, and an absent or non-finite one keeps that
242
+ key's start. The lens's vertical field of view sees far less across in
243
+ portrait, so a start that frames the player well in landscape is close
244
+ in portrait. Turning the canvas between orientations is a change of
245
+ start, so the camera starts again at the new orientation's values, both
246
+ ways; a resize that stays in one orientation keeps what the player
247
+ chose. Absent (or not an object), nothing changes: the canvas is not
248
+ read and the camera is the one before the key, frame for frame
249
+ (scripts/test-camera-orbit.mjs against Player.before-portrait.mjs).
250
+ `camDistance` and
238
251
  `camHeight` do not move the orbit camera. A change to either of them,
239
252
  either starting key or `minPitch` (a deck edit or a scene
240
253
  with different values) reapplies both starting values; unchanged values
@@ -522,21 +522,23 @@ const finiteOr = (value, otherwise) => (Number.isFinite(value) ? value : otherwi
522
522
  // at the scene's starting pitch and distance (or the defaults), and start
523
523
  // again when those keys or camDistance/camHeight change. The latter two
524
524
  // ask for a fresh camera but do not set its orbit distance or pitch.
525
+ // While the canvas is taller than wide, `engine.camera.portrait`'s finite
526
+ // distance and pitch stand in for the starts, so turning the phone is a
527
+ // change of start like any other and restarts the camera at that
528
+ // orientation's own. Without the key nothing below reads the canvas.
525
529
  function orbitChoice(scene, props) {
526
530
  const distance = finiteOr(props.camDistance, 9);
527
531
  const height = finiteOr(props.camHeight, 7);
528
- // Only a finite number is a start; anything else is the default, so a
529
- // copy of the same scene data (a fresh {} included) never restarts it.
530
- const startDistance = finiteOr(scene.data?.engine?.camera?.distance, undefined);
531
- const startPitch = finiteOr(scene.data?.engine?.camera?.pitch, undefined);
532
+ const { startDistance, startPitch, orientation } = orbitStarts(scene);
532
533
  const minPitch = finiteOr(scene.data?.engine?.camera?.minPitch, undefined);
533
534
  const least = clamp(finiteOr(minPitch, -80) * DEG, ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST);
534
535
  const chosen = scene.cameraOrbit;
535
536
  if (chosen && chosen.distance === distance && chosen.height === height
536
537
  && Object.is(chosen.startDistance, startDistance) && Object.is(chosen.startPitch, startPitch)
537
- && Object.is(chosen.minPitch, minPitch))
538
+ && Object.is(chosen.minPitch, minPitch) && Object.is(chosen.orientation, orientation))
538
539
  return chosen;
539
540
  scene.cameraOrbit = {
541
+ ...(orientation === undefined ? {} : { orientation }),
540
542
  distance,
541
543
  height,
542
544
  startDistance,
@@ -550,6 +552,26 @@ function orbitChoice(scene, props) {
550
552
  };
551
553
  return scene.cameraOrbit;
552
554
  }
555
+ // The starting distance and pitch. Only a finite number is a start;
556
+ // anything else is the default, so a copy of the same scene data (a fresh
557
+ // {} included) never restarts the camera. With `portrait` (an object) also
558
+ // which way the canvas faces, so a turn restarts the camera even where both
559
+ // orientations' starts are the same; without it the canvas is not read.
560
+ function orbitStarts(scene) {
561
+ const camera = scene.data?.engine?.camera;
562
+ const keyed = camera?.portrait && typeof camera.portrait === 'object' ? camera.portrait : null;
563
+ const tall = keyed && tallCanvas(scene) ? keyed : null;
564
+ return {
565
+ startDistance: finiteOr(tall?.distance, finiteOr(camera?.distance, undefined)),
566
+ startPitch: finiteOr(tall?.pitch, finiteOr(camera?.pitch, undefined)),
567
+ orientation: keyed ? (tall ? 'tall' : 'wide') : undefined,
568
+ };
569
+ }
570
+ // Whether the camera is taller than wide.
571
+ function tallCanvas(scene) {
572
+ const aspect = scene.three?.camera?.aspect;
573
+ return Number.isFinite(aspect) && aspect > 0 && aspect < 1;
574
+ }
553
575
  // What the player asked of the camera this frame, onto what it is aimed for.
554
576
  function steerOrbit(per, chosen, look) {
555
577
  per.camAngle += look.yaw;