castle-web-cli 0.4.252 → 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];
@@ -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;