From 23be619789a08f5f15233bdbe317991a8a862dae Mon Sep 17 00:00:00 2001 From: Alex Sharp Date: Sun, 8 Nov 2026 18:36:09 +1300 Subject: [PATCH 1/2] Keep crowded panels from obscuring readable content Admit panels using their actual painted bounds and existing paint order; omit conflicting panels with a visible count in a clear slot. Preserve Frost styling and fitting layouts. Release omitted annotations, pointer footprints and retained stage labels. Cover admission, lifecycle, exact ownership and size/count sweeps. Source tree matches local/native verified candidate 06b18fe5ffb2519830af3471a31b0e52389fb214 exactly: 3a42589632817ccd34c63d475bc3d87034894381. --- src/overlay/annotations.ts | 4 + src/overlay/diagram-draw.ts | 10 +- src/overlay/index.html | 2 + src/overlay/overlay.ts | 87 ++++++++--- src/overlay/placement.ts | 26 +++- src/overlay/surface-admission.ts | 42 ++++++ test/overlay-crowded-panels.test.ts | 211 ++++++++++++++++++++++++++ test/support/crowded-panels.json | 221 ++++++++++++++++++++++++++++ 8 files changed, 578 insertions(+), 25 deletions(-) create mode 100644 src/overlay/surface-admission.ts create mode 100644 test/overlay-crowded-panels.test.ts create mode 100644 test/support/crowded-panels.json diff --git a/src/overlay/annotations.ts b/src/overlay/annotations.ts index e134c54c..7135c48e 100644 --- a/src/overlay/annotations.ts +++ b/src/overlay/annotations.ts @@ -18,6 +18,8 @@ export type Annotator = { view: View; /** The 3D stage in pixels, when there is one: tags are drawn smaller beside a small stage so they do not outweigh the model. */ stage?: { w: number; h: number }; + /** Refuse a panel whose measured, animated bounds would cover an earlier surface. */ + admitSurface?: (id: string, bounds: { x: number; y: number; w: number; h: number }) => boolean; /** Where a point of a 3D object is in the window. */ project: (key: number, point: Vec3 | undefined, anchor?: string) => { x: number; y: number; visible: boolean } | undefined; /** The screenshot (or backdrop) image crops are taken from. */ @@ -342,6 +344,7 @@ export function drawCard(ctx: Ctx, m: MarkFrame, a: Annotator, order: number): v const H = y + pad * 0.7; const slide = (1 - p) * 10; const top = y0 + slide; + if (a.admitSurface?.(m.id, { x, y: top, w: W, h: H }) === false) { ctx.restore(); return; } // Frost: the panel wears the face of the page under it (light over a light page, dark over a dark one). const tone = FROST[a.faceOf?.(`m${m.key}`, { x, y: y0, w: W, h: H }) ?? 'dark']; @@ -421,6 +424,7 @@ export function drawImage(ctx: Ctx, m: MarkFrame, a: Annotator, order: number): ctx.restore(); const cap = caption.length ? capPx * (0.9 + caption.length) : 0; const x = snapPx((mk.dx / 1000) * view.width, view.dpr), y = snapPx((mk.dy / 1000) * view.height, view.dpr); + if (a.admitSurface?.(m.id, { x, y: y + (1 - p) * 10, w: w + pad * 2, h: h + pad * 2 + cap }) === false) return; ctx.save(); ctx.globalAlpha = alpha * Math.min(1, p * 1.5); ctx.translate(0, (1 - p) * 10); diff --git a/src/overlay/diagram-draw.ts b/src/overlay/diagram-draw.ts index 70d126e1..85e8fd7b 100644 --- a/src/overlay/diagram-draw.ts +++ b/src/overlay/diagram-draw.ts @@ -86,6 +86,8 @@ type Env = { ctx: Ctx; view: View; alpha: number; accent: Rgb; px: number; paint const panelRadius = (r: Px): number => Math.max(14, Math.min(28, Math.min(r.w, r.h) * 0.075)); export type DiagramPainterOptions = { + /** Last check using the actual animated panel bounds, before any content is painted. */ + admitSurface?: (id: string, bounds: Px) => boolean; regrow?: (id: string, want: Px) => Px | undefined; onBounds?: (id: string, bounds: Px) => void; /** The face a panel wears (light or dark), from the page under it; without it every panel is dark. `key` names the panel, so it keeps its face. */ @@ -154,7 +156,7 @@ export class DiagramPainter { } /** Draws every diagram of the frame; `now` is a clock in milliseconds. Returns true while something is still gliding into place. */ - draw(ctx: Ctx, diagrams: readonly DiagramFrame[], view: View, now: number): boolean { + draw(ctx: Ctx, diagrams: readonly DiagramFrame[], view: View, now: number, admitSurface = this.options.admitSurface): boolean { const dt = this.last === undefined ? 0 : Math.min(0.1, (now - this.last) / 1000); this.last = now; this.moving = false; @@ -168,7 +170,7 @@ export class DiagramPainter { ctx.save(); ctx.setTransform(view.dpr, 0, 0, view.dpr, 0, 0); try { - this.one(ctx, d, view, alpha, dt, seen); + this.one(ctx, d, view, alpha, dt, seen, admitSurface); } finally { ctx.restore(); } @@ -218,11 +220,13 @@ export class DiagramPainter { return regrow(d.def.id, want) ?? r0; } - private one(ctx: Ctx, d: DiagramFrame, view: View, alpha: number, dt: number, seen: Set): void { + private one(ctx: Ctx, d: DiagramFrame, view: View, alpha: number, dt: number, seen: Set, admitSurface?: (id: string, bounds: Px) => boolean): void { const theme = THEME; const asked = rectOf(d, view); // A flow does not go below a readable node size: its card grows (eased, so a late node does not make it jump) until the nodes read. const r = d.def.kind === 'flow' ? this.ease(`${d.key}:card`, this.grownFlow(ctx, d, asked, view), dt, seen) : asked; + // Admission uses the grown/eased card and its entrance slide, not the authored rectangle. + if (admitSurface?.(d.id, { ...r, y: r.y + (1 - d.appear) * 10 }) === false) return; this.options.onBounds?.(d.id, r); const face = this.options.faceOf?.(`d${d.key}`, r) ?? 'dark'; const tone = FROST[face]; diff --git a/src/overlay/index.html b/src/overlay/index.html index e8a542e3..1ef44e09 100644 --- a/src/overlay/index.html +++ b/src/overlay/index.html @@ -31,6 +31,7 @@ #dock { position: absolute; left: 0; right: 0; bottom: 28px; display: flex; flex-direction: column-reverse; align-items: center; gap: 10px; pointer-events: none; } #status, #notice { display: none; align-items: center; gap: 12px; box-sizing: border-box; max-width: min(88vw, 760px); padding: 10px 18px 10px 16px; border-radius: 999px; white-space: nowrap; background: var(--pill); color: var(--pilltext); font-size: 14px; font-weight: 620; letter-spacing: 0.005em; border: 1px solid var(--line); box-shadow: var(--shadow); } + #panel-overflow { position: absolute; display: none; box-sizing: border-box; width: min(320px, calc(100vw - 32px)); padding: 10px 14px; border-radius: 12px; background: var(--pill); color: var(--pilltext); border: 1px solid var(--line); font-size: 14px; line-height: 1.35; pointer-events: none; } #status .lbl { font-weight: 650; } #status .hint { font-weight: 500; font-size: 12.5px; color: var(--muted); } #status .bars, #status .ell, #status .hint { display: none; } @@ -126,6 +127,7 @@
+

Spoken as well
diff --git a/src/overlay/overlay.ts b/src/overlay/overlay.ts index 3c43b2a1..13b7d21c 100644 --- a/src/overlay/overlay.ts +++ b/src/overlay/overlay.ts @@ -20,8 +20,9 @@ import { LabelBoard, Occupancy, busyFromGray } from './labels.ts'; import type { Env as LabelEnv } from './labels.ts'; import { snapperFor } from './page-gray.ts'; import { PageMemory } from './page-memory.ts'; +import { SurfaceAdmission, admittedFrame, omitStageForCue, surfacesOverlap } from './surface-admission.ts'; +import { Placer, cardFootprint, displayBoxesFromPixels, followDiagram, markFootprint, ownedByDiagram, pageGrid, foreseePoints, placeAction, reserveMarks, settleMark, splitOwned } from './placement.ts'; import { FaceBook, THEME, fontAt } from './theme.ts'; -import { Placer, cardFootprint, displayBoxesFromPixels, followDiagram, markFootprint, ownedByDiagram, ownedMarkIds, pageGrid, foreseePoints, placeAction, reserveMarks, settleMark, splitOwned } from './placement.ts'; import { snapToControl } from '../shared/controls.ts'; import type { ControlBox } from '../shared/controls.ts'; import { snapActions } from './snap.ts'; @@ -67,6 +68,7 @@ const captureControlsEl = byId('capture-controls'); const sendFollowupEl = byId('send-followup'); const cancelFollowupEl = byId('cancel-followup'); const noticeEl = byId('notice'); +const overflowEl = byId('panel-overflow'); const explodeEl = byId('explode'); const detailEl = byId('detail'); const cutEl = byId('cut'); @@ -310,6 +312,7 @@ let controlRect: ScreenRect | undefined; let stageSize: { w: number; h: number } | undefined; let lastDisplayedFrame: Frame | undefined; let lastSourceFrame: Frame | undefined; +let paintedSurfaces = new Map(); function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { frame = displayedFrame(frame); @@ -417,12 +420,13 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { diagrams: frame.diagrams.map((d) => { const current = p.surface(d.id); return current ? { ...d, def: { ...d.def, x: current.x, y: current.y } } : d; }), }; } - lastDisplayedFrame = frame; board.beginFrame({ width: view.width, height: view.height, model: modelRect, dragging, now: labelClock(), ...(cardRect ? { within: cardRect } : {}) }); board.keep(new Set(frame.marks.filter((m) => m.mark.op === 'pin').map((m) => m.key))); pinGeometry = []; + let admission = new SurfaceAdmission(modelRect ? [modelRect] : []); const annotator = { view, + admitSurface: (id: string, bounds: ScreenRect) => admission.admit(id, bounds), ...(stageSize ? { stage: stageSize } : {}), faceOf: (key: string, rect: { x: number; y: number; w: number; h: number }) => faces.of(key, rect), place: (key: number, request: Parameters[1]) => board.place(key, request, labelEnvironment), @@ -434,11 +438,48 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { ...(cropSource() ? { source: cropSource()! } : {}), }; // A mark that lies on a flat diagram (a ring on a chart's crossing, an arrow at a bar) is drawn above the diagram's opaque card, or it would be hidden by it. - const { under, over } = splitOwned(frame.marks, ownedMarks); - drawMarks(marksCtx, under, view, annotator, { reduceMotion: reduceMotion.matches }); - // The flat diagrams go over the marks' canvas in free space; a piece moved by a later arrival glides, which wants frames until it is there. - diagramsMoving = frame.diagrams.length > 0 && diagramPainter.draw(marksCtx, frame.diagrams, view, labelClock()); - if (over.length > 0) drawMarks(marksCtx, over, view, annotator, { reduceMotion: reduceMotion.matches, append: true }); + const paintSurfaces = (): Frame => { + const { under } = splitOwned(frame.marks, ownedMarks); + pinGeometry = []; + drawMarks(marksCtx, under, view, annotator, { reduceMotion: reduceMotion.matches }); + // Admission happens after a flow grows/eases, immediately before its panel is painted. + diagramsMoving = diagramPainter.draw(marksCtx, frame.diagrams, view, labelClock(), (id, bounds) => admission.admit(id, bounds)); + const shown = admittedFrame(frame, admission, ownedSurfaces); + const { over } = splitOwned(shown.marks, ownedMarks); + if (over.length > 0) drawMarks(marksCtx, over, view, annotator, { reduceMotion: reduceMotion.matches, append: true }); + return shown; + }; + let shown = paintSurfaces(); + overflowEl.style.display = admission.omitted.size ? 'block' : 'none'; + if (admission.omitted.size) { + // Measure the largest possible count once. The cue keeps this width while its count changes. + overflowEl.textContent = `${frame.marks.length + frame.diagrams.length + 1} panels hidden to prevent overlap`; + const size = overflowEl.getBoundingClientRect(); + const obstacles = [...admission.shown.values(), ...(modelRect ? [modelRect] : []), ...overlayControlRects()]; + const at = followupSpot(view, { w: size.width, h: size.height }, obstacles); + const cue = { ...at, w: size.width, h: size.height }; + let hiddenStage = 0; + if (obstacles.some(r => surfacesOverlap(cue, r))) { + // No gap even for the cue: give it a dedicated slot, omitting intersecting panels too. + // The stage is normally first priority, but cannot obscure this last-resort explanation. + if (modelRect && surfacesOverlap(cue, modelRect)) { + hiddenStage = 1; + renderer?.setScissorTest(false); renderer?.clear(); + frameEl.style.display = 'none'; + modelRect = undefined; modelHitRect = undefined; cardRect = undefined; + frame = omitStageForCue(frame, board); + placeExplode(frame); + } + admission = new SurfaceAdmission([cue, ...(modelRect ? [modelRect] : [])]); + shown = paintSurfaces(); + } + const count = admission.omitted.size + hiddenStage; + overflowEl.textContent = `${count} ${count === 1 ? 'panel' : 'panels'} hidden to prevent overlap`; + overflowEl.style.left = `${at.x}px`; overflowEl.style.top = `${at.y}px`; + } + frame = shown; + paintedSurfaces = new Map(admission.shown); + lastDisplayedFrame = frame; drawPen(marksCtx, pen.view(labelClock(), { reduceMotion: reduceMotion.matches }), view); if (pointerX >= 0) hold.onHud(overHud(document.elementFromPoint(pointerX, pointerY))); // a button can fade under a resting pointer hold.model(modelHitRect); @@ -459,6 +500,7 @@ function cropSource(): { image: CanvasImageSource; width: number; height: number const board = new LabelBoard(); /** The ids of the marks that belong to a flat diagram (placement.ts): drawn over its card, where the rest stay under it. */ const ownedMarks = new Set(); +const ownedSurfaces = new Map(); /** The face (light or dark) each flat diagram and note card wears: the page under it decides, with a little hysteresis so it never flickers over a mid-tone page (theme.ts). The same signal as the light frame behind a 3D stage. */ const faces = new FaceBook((r) => placer()?.brightness({ x: (r.x / view.width) * 1000, y: (r.y / view.height) * 1000, w: (r.w / view.width) * 1000, h: (r.h / view.height) * 1000 })); const diagramPainter = new DiagramPainter({ @@ -700,7 +742,9 @@ function renderedContentRegions(frame: Frame): VisibleRegion[] { const alpha = m.opacity * m.appear * m.fade; if (alpha <= 0.02) continue; if (m.mark.op === 'card' || m.mark.op === 'image') { - for (const [i, b] of cardFootprint(m.mark, view.height, aspect, sourceAspect, placer()?.captionMeasure()).entries()) unitRect(`card:${m.key}:${i}`, 'content', b, alpha); + const painted = paintedSurfaces.get(m.id); + if (painted) addRect(`card:${m.key}:0`, 'content', painted, alpha); + else for (const [i, b] of cardFootprint(m.mark, view.height, aspect, sourceAspect, placer()?.captionMeasure()).entries()) unitRect(`card:${m.key}:${i}`, 'content', b, alpha); } else if (m.mark.op === 'label') { marksCtx.save(); const layout = labelLayout(marksCtx, m, view); @@ -708,7 +752,11 @@ function renderedContentRegions(frame: Frame): VisibleRegion[] { if (layout) addRect(`mark:${m.mark.id}`, 'content', layout.hit, alpha); } else regions.push(...regionsForMark(m.mark, view.width, view.height, alpha, m.appear, view.dpr, m.fade, reduceMotion.matches)); } - for (const d of frame.diagrams) unitRect(`diagram:${d.key}`, 'content', d.def, d.appear * d.fade); + for (const d of frame.diagrams) { + const painted = paintedSurfaces.get(d.id); + if (painted) addRect(`diagram:${d.key}`, 'content', painted, d.appear * d.fade); + else unitRect(`diagram:${d.key}`, 'content', d.def, d.appear * d.fade); + } regions.push(...pinGeometry); for (const [i, rect] of board.shownRects().entries()) addRect(`pin-label:${i}`, 'content', rect); return regions; @@ -782,7 +830,7 @@ function captionKeepOut(frame: Frame): Rect[] { for (const d of frame.diagrams) if (d.appear > 0.05 && d.fade > 0.05) out.push(px(d.def)); out.push(...board.shownRects()); if (modelRect) out.push(modelRect); - for (const el of [explodeEl, cutEl, detailEl, statusEl, offerEl, noticeEl, undoEl]) { + for (const el of [explodeEl, cutEl, detailEl, statusEl, offerEl, noticeEl, undoEl, overflowEl]) { if (el.style.display === 'none' || el.style.display === '') continue; const r = el.getBoundingClientRect(); out.push({ x: r.left, y: r.top, w: r.width, h: r.height }); @@ -929,7 +977,7 @@ function overlayUiRegions(): OverlayUiRegion[] { const capture = id === 'ask-more' || id === 'send-followup' || id === 'cancel-followup' || id === 'undo'; regions.push({ id: `button:${id}`, kind: capture ? 'capture-control' : 'pill', rect, alpha }); } - for (const [id, el] of [['status', statusEl], ['offer-pill', offerEl], ['notice-pill', noticeEl], ['answer-card', answerEl], ['caption', captionEl]] as const) { + for (const [id, el] of [['status', statusEl], ['offer-pill', offerEl], ['notice-pill', noticeEl], ['answer-card', answerEl], ['caption', captionEl], ['panel-overflow', overflowEl]] as const) { const rect = elementRect(el); const alpha = Number.parseFloat(el.style.opacity || '1'); if (!rect || alpha <= 0.02) continue; @@ -1390,12 +1438,13 @@ function placedScene(scene: Scene): Scene { p.reset(); if (!lastDisplayedFrame) p.setStage(undefined); const aspect = view.width / view.height; - if (!lastDisplayedFrame) ownedMarks.clear(); + if (!lastDisplayedFrame) { ownedMarks.clear(); ownedSurfaces.clear(); } const source = cropSource(); const sourceAspect = source ? source.width / source.height : aspect; - for (const id of ownedMarkIds(scene.steps, aspect, view.height, sourceAspect, p.captionMeasure())) ownedMarks.add(id); // A mark written after a flat diagram and inside the rectangle it was asked for belongs to it (it is not snapped to the page or kept clear of), and goes with it. - const owned = ownedByDiagram(scene.steps, aspect, view.height, sourceAspect, p.captionMeasure()); + const owned = ownedByDiagram(scene.steps, aspect, view.height, sourceAspect, p.captionMeasure(), ownedSurfaces); + ownedMarks.clear(); + for (const id of ownedSurfaces.keys()) ownedMarks.add(id); const snapped = scene.steps.map((step, i) => ({ ...step, actions: step.actions.map((a, j) => (owned[i]![j] ? a : (snappedActions([a])[0] as Action))) })); snapped.forEach((step, i) => reserveMarks(p, step.actions.filter((_, j) => !owned[i]![j]), aspect)); const placed = snapped.map((step) => ({ ...step, actions: step.actions.map((a) => !renderer && a.op === 'panel' ? a : placeAction(p, a, view.height)) })); @@ -1410,10 +1459,14 @@ function placedAction(action: Action): Action { if (!p) return action; const following = followDiagram(p, action, view.width / view.height); if (following) { - if ('id' in following && typeof following.id === 'string') ownedMarks.add(following.id); + if ('id' in following && typeof following.id === 'string') { + ownedMarks.add(following.id); + const owner = p.ownerOf(action); + if (owner) ownedSurfaces.set(following.id, owner); + } return settleMark(p, following); } - if ('id' in action && typeof action.id === 'string') ownedMarks.delete(action.id); + if ('id' in action && typeof action.id === 'string') { ownedMarks.delete(action.id); ownedSurfaces.delete(action.id); } const [snapped] = snappedActions([action]) as [Action]; reserveMarks(p, [snapped], view.width / view.height); return settleMark(p, placeAction(p, snapped, view.height)); @@ -1501,7 +1554,7 @@ function applyScene(message: SceneMessage): void { beginTurn(message.turn, message.detail === true); if (message.detail !== true) box.reset(typeof message.question === 'string' ? message.question : ''); placer()?.reset(); - if (message.turn <= 1 && message.detail !== true) ownedMarks.clear(); // a continuing turn retains the visible owners and their marks + if (message.turn <= 1 && message.detail !== true) { ownedMarks.clear(); ownedSurfaces.clear(); } // a continuing turn retains the visible owners and their marks if (message.turn <= 1 && message.detail !== true) placer()?.setStage(undefined); // a detail pass keeps the stage it grows into if (message.detail === true) detailState = 'running'; player.beginTurn(message.detail === true); diff --git a/src/overlay/placement.ts b/src/overlay/placement.ts index d88c2b18..6c1e3415 100644 --- a/src/overlay/placement.ts +++ b/src/overlay/placement.ts @@ -558,6 +558,8 @@ export class Placer { const was = this.cards.get(id) ?? this.homes.get(id)?.to ?? grown; const keepOut = [...this.reserved, ...this.controls, ...[...this.cards].filter(([k]) => k !== id).map(([, b]) => b), ...this.stageKeepOut()]; const placed = this.search(grown, [1], [...keepOut, ...this.reserved, ...this.reserved], [1], 0, true); + // A small coverage cost can still mean a whole line of another panel is hidden. + if (keepOut.some((r) => overlap(placed, r) > 0)) return undefined; if (this.coverage(placed, keepOut) > this.coverage(was, keepOut) + GROWTH_COVER_SLACK) return undefined; this.cards.set(id, placed); const home = this.homes.get(id); @@ -580,6 +582,16 @@ export class Placer { return undefined; } + /** Exact surface identity for a newly streamed mark, before placement changes its coordinates. */ + ownerOf(a: Action): string | undefined { + const c = MARK_OPS.has(a.op) ? markCentre(a as Mark, this.aspect) : undefined; + if (c) for (const [id, home] of this.homes) { + const r = home.from; + if (c.x >= r.x && c.x <= r.x + r.w && c.y >= r.y && c.y <= r.y + r.h) return id; + } + return undefined; + } + aspectOf(): number { return this.aspect; } @@ -801,18 +813,22 @@ export function ownedMarkIds(steps: readonly { actions: readonly Action[] }[], a * rectangle it was asked for. A mark written before it (a ring on the page's own graph, then a chart elsewhere) points at the page and stays * there, as it does when the answer is drawn as it arrives, where the earlier mark is already on the page when the diagram comes. */ -export function ownedByDiagram(steps: readonly { actions: readonly Action[] }[], aspect: number, screenHeight = 1000, sourceAspect = aspect, measureCaption?: (text: string) => number): boolean[][] { - const seen: Box[] = []; +export function ownedByDiagram(steps: readonly { actions: readonly Action[] }[], aspect: number, screenHeight = 1000, sourceAspect = aspect, measureCaption?: (text: string) => number, owners?: Map): boolean[][] { + const seen: Array = []; return steps.map((step) => step.actions.map((a) => { if (a.op === 'diagram') { - seen.push({ x: a.x, y: a.y, w: a.w, h: a.h }); + seen.push({ id: a.id, x: a.x, y: a.y, w: a.w, h: a.h }); return false; } if (a.op === 'image') { - seen.push({ x: a.dx, y: a.dy, w: a.dw, h: imageCardHeight(a, screenHeight, aspect, sourceAspect, measureCaption) }); + seen.push({ id: a.id, x: a.dx, y: a.dy, w: a.dw, h: imageCardHeight(a, screenHeight, aspect, sourceAspect, measureCaption) }); return false; } - return seen.length > 0 && insideAny(a, seen, aspect); + const owner = seen.find(r => insideAny(a, [r], aspect)); + if (owners && 'id' in a && typeof a.id === 'string') { + if (owner) owners.set(a.id, owner.id); else owners.delete(a.id); + } + return owner !== undefined; })); } diff --git a/src/overlay/surface-admission.ts b/src/overlay/surface-admission.ts new file mode 100644 index 00000000..729fd5e2 --- /dev/null +++ b/src/overlay/surface-admission.ts @@ -0,0 +1,42 @@ +import type { Box } from './placement.ts'; +import type { Frame } from './timeline.ts'; + +export function surfacesOverlap(a: Box, b: Box): boolean { + return Math.min(a.x + a.w, b.x + b.w) > Math.max(a.x, b.x) + 1e-6 + && Math.min(a.y + a.h, b.y + b.h) > Math.max(a.y, b.y) + 1e-6; +} + +/** Last line of defence after placement: retain readable sizes and the existing paint order. + * Rebuilt each frame so clear, replacement, resize and the end of an animation release room. + * Keep the whole panel, or omit it; never paint one panel through another's writing. + */ +export class SurfaceAdmission { + readonly shown = new Map(); + readonly omitted = new Map(); + private readonly keepOut: readonly Box[]; + constructor(keepOut: readonly Box[] = []) { this.keepOut = keepOut; } + + admit(id: string, box: Box): boolean { + if ([...this.keepOut, ...this.shown.values()].some(other => surfacesOverlap(box, other))) { + this.omitted.set(id, box); + return false; + } + this.shown.set(id, box); + return true; + } +} + +/** Omitted cards have no pointer footprint and their annotations must not float on other panels. */ +export function admittedFrame(frame: Frame, admission: SurfaceAdmission, owners: ReadonlyMap): Frame { + if (!admission.omitted.size) return frame; + return { ...frame, + diagrams: frame.diagrams.filter(d => !admission.omitted.has(d.id)), + marks: frame.marks.filter(m => !admission.omitted.has(m.id) && !admission.omitted.has(owners.get(m.id) ?? '')), + }; +} + +/** If even the cue cannot fit beside the stage, release both the stage and its retained labels. */ +export function omitStageForCue(frame: Frame, board: { keep(alive: ReadonlySet): void }): Frame { + board.keep(new Set()); + return { ...frame, panel: null, objects: [], marks: frame.marks.filter(m => m.mark.op !== 'pin') }; +} diff --git a/test/overlay-crowded-panels.test.ts b/test/overlay-crowded-panels.test.ts new file mode 100644 index 00000000..da1129c4 --- /dev/null +++ b/test/overlay-crowded-panels.test.ts @@ -0,0 +1,211 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { DiagramPainter } from '../src/overlay/diagram-draw.ts'; +import { drawMarks } from '../src/overlay/marks.ts'; +import { emptyFrame, planStep, settle } from '../src/overlay/timeline.ts'; +import { Placer, pageGrid, placeAction } from '../src/overlay/placement.ts'; +import type { Box } from '../src/overlay/placement.ts'; +import type { Action, Step } from '../src/scene/types.ts'; +import type { Annotator } from '../src/overlay/annotations.ts'; + +const overlap = (a: Box, b: Box) => Math.min(a.x + a.w, b.x + b.w) > Math.max(a.x, b.x) && Math.min(a.y + a.h, b.y + b.h) > Math.max(a.y, b.y); +function canvas() { + const texts: string[] = []; + const state: Record = { font: '12px sans-serif' }; + const ctx = new Proxy(state, { + get(t, k: string) { + if (k === 'createLinearGradient') return () => ({ addColorStop() {} }); + if (k === 'measureText') return (s: string) => ({ width: s.length * 7 }); + if (k === 'fillText') return (s: string) => texts.push(s); + return k in t ? t[k] : () => {}; + }, + set(t, k: string, v) { t[k] = v; return true; }, + }) as unknown as CanvasRenderingContext2D; + return { ctx, texts }; +} +const frame = (actions: Action[]) => settle(planStep(emptyFrame(), { say: '', actions } as Step)); + +test('crowded panel painters honour admission at the actual painted bounds', () => { + const view = { width: 1920, height: 1080, dpr: 1 }; + const boxes: Box[] = []; + const admitSurface = (_id: string, box: Box) => { + if (boxes.some(b => overlap(b, box))) return false; + boxes.push(box); return true; + }; + const f = frame([ + { op: 'card', id: 'note', x: 670, y: 520, w: 320, title: 'Read this note', rows: ['The chart must not cover this row.', 'Nor this row.', 'Keep all of this readable.'] }, + { op: 'diagram', kind: 'chart', id: 'chart', x: 590, y: 440, w: 400, h: 380, title: 'Crowded chart' }, + ]); + const { ctx, texts } = canvas(); + drawMarks(ctx, f.marks, view, { view, project: () => undefined, admitSurface } as Annotator); + new DiagramPainter({ admitSurface } as ConstructorParameters[0]).draw(ctx, f.diagrams, view, 0); + assert.ok(texts.includes('Read this note')); + assert.ok(!texts.includes('Crowded chart'), 'a chart rejected for covering the note must not be painted'); + assert.equal(boxes.length, 1, 'the note reserves its actual painted rectangle'); +}); + +test('card and image painters also refuse a surface that cannot fit', () => { + const view = { width: 800, height: 600, dpr: 1 }; + const f = frame([ + { op: 'card', id: 'note', x: 100, y: 100, title: 'Omitted note', rows: ['Not drawn'] }, + { op: 'image', id: 'crop', sx: 0, sy: 0, sw: 100, sh: 100, dx: 100, dy: 100, dw: 300, caption: 'Omitted crop' }, + ]); + const { ctx, texts } = canvas(); + const admitted: string[] = []; + drawMarks(ctx, f.marks, view, { view, project: () => undefined, source: { image: {} as CanvasImageSource, width: 800, height: 600 }, admitSurface: (id: string) => { admitted.push(id); return false; } } as Annotator); + assert.deepEqual(texts, [], 'omitted panels draw neither title nor content'); + assert.deepEqual(admitted, ['note', 'crop']); +}); + +test('a flow cannot regrow across an existing card even when the whole viewport is crowded', () => { + const p = new Placer(pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108), { aspect: 16 / 9 }); + p.diagram({ x: 12, y: 12, w: 300, h: 976 }, 'flow'); + p.card({ x: 312, y: 12, w: 676, h: 976 }, 'note'); + assert.equal(p.regrow('flow', { x: 12, y: 12, w: 302, h: 976 }), undefined, 'even a narrow overlap hides content'); +}); + +// These are renderer fixtures: the five-panel regression deliberately exceeds +// the author's current three-diagram cap. The renderer also receives retained follow-ups. +import { readFileSync } from 'node:fs'; +import { SurfaceAdmission, admittedFrame, surfacesOverlap } from '../src/overlay/surface-admission.ts'; +import { followupSpot } from '../src/overlay/followup-placement.ts'; +const sheet = JSON.parse(readFileSync(new URL('./support/crowded-panels.json', import.meta.url), 'utf8')).steps[0].actions as Action[]; + +function drawWithAdmission(actions: Action[], view: { width: number; height: number; dpr: number }, keepOut: Box[] = [], usePlacer = true) { + const p = new Placer(pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108), { aspect: view.width / view.height, height: view.height }); + const placed = usePlacer ? actions.map(a => placeAction(p, a, view.height)) : actions; + const f = frame(placed); + const admission = new SurfaceAdmission(keepOut); + const { ctx, texts } = canvas(); + const admitSurface = (id: string, b: Box) => admission.admit(id, b); + drawMarks(ctx, f.marks, view, { view, project: () => undefined, admitSurface }); + new DiagramPainter({ admitSurface }).draw(ctx, f.diagrams, view, 0); + return { admission, texts, frame: admittedFrame(f, admission, new Map()) }; +} +function assertClear(boxes: Box[]) { + for (let i = 0; i < boxes.length; i++) for (let j = i + 1; j < boxes.length; j++) + assert.ok(!surfacesOverlap(boxes[i]!, boxes[j]!), `panels ${i} and ${j} overlap: ${JSON.stringify(boxes)}`); +} + +test('the five-panel sheet preserves the note and never draws another panel over its content', () => { + const result = drawWithAdmission(sheet, { width: 1920, height: 1080, dpr: 1 }); + assertClear([...result.admission.shown.values()]); + assert.equal(result.admission.shown.size + result.admission.omitted.size, 5); + assert.ok(result.admission.shown.has('note')); + assert.ok(result.admission.omitted.size > 0, 'a crowded sheet needs the explicit fallback'); +}); + +test('viewport and panel-count sweep keeps admitted panels clear and makes room for the cue', () => { + for (const [width, height] of [[360, 640], [640, 360], [800, 600], [1280, 720], [1920, 1080], [2560, 1080]]) { + const view = { width: width!, height: height!, dpr: 1 }; + for (let count = 1; count <= 12; count++) { + const actions: Action[] = Array.from({ length: count }, (_, i) => i % 3 === 0 + ? { op: 'card', id: `p${i}`, x: 100 + i * 33, y: 90 + i * 44, w: 460, title: `Note ${i}`, rows: ['A readable line', 'Another readable line', 'One more line'] } + : { op: 'diagram', id: `p${i}`, kind: ['flow', 'timeline', 'steps', 'chart'][i % 4] as 'chart', x: 80 + i * 30, y: 100 + i * 35, w: 480, h: 420, title: `Panel ${i}` }); + let result = drawWithAdmission(actions, view); + assertClear([...result.admission.shown.values()]); + if (result.admission.omitted.size) { + const size = { w: Math.min(320, width! - 32), h: 58 }; + const at = followupSpot(view, size, [...result.admission.shown.values()]); + const cue = { ...at, ...size }; + result = drawWithAdmission(actions, view, [cue]); + assertClear([cue, ...result.admission.shown.values()]); + assert.ok(result.admission.omitted.size > 0); + assert.ok(cue.x >= 0 && cue.y >= 0 && cue.x + cue.w <= width! && cue.y + cue.h <= height!); + } + assert.equal(result.admission.shown.size + result.admission.omitted.size, count); + } + } +}); + +test('fitting panels keep their drawing and no omission survives clear or replacement', () => { + const view = { width: 1920, height: 1080, dpr: 1 }; + const a: Action = { op: 'diagram', kind: 'chart', id: 'a', title: 'First', x: 100, y: 100, w: 350, h: 350 }; + const b: Action = { ...a, id: 'b', title: 'Second', x: 600 }; + const plain = canvas(), fitting = drawWithAdmission([a, b], view, [], false); + new DiagramPainter().draw(plain.ctx, frame([a, b]).diagrams, view, 0); + assert.deepEqual(fitting.texts, plain.texts); + assert.equal(fitting.admission.omitted.size, 0); + const crowded = drawWithAdmission([a, { ...b, x: 100 }], view, [], false); + assert.equal(crowded.admission.omitted.size, 1); + for (let i = 0; i < 3; i++) assert.equal(drawWithAdmission([a, { ...b, x: 100 }], view, [], false).admission.omitted.size, 1); + assert.equal(drawWithAdmission([b], view, [], false).admission.omitted.size, 0, 'clearing releases room'); + assert.equal(drawWithAdmission([a, b], view, [], false).admission.omitted.size, 0, 'replacement releases room'); +}); + +test('entrance slides and grown flows use actual bounds on every animation frame', () => { + const view = { width: 1000, height: 800, dpr: 1 }, painter = new DiagramPainter(); + const f = frame([ + { op: 'diagram', kind: 'flow', id: 'flow', x: 300, y: 200, w: 160, h: 200, title: 'Growing flow' }, + ...Array.from({ length: 8 }, (_, i): Action => ({ op: 'node', of: 'flow', id: `n${i}`, text: `Long node ${i}` })), + { op: 'diagram', kind: 'chart', id: 'chart', x: 450, y: 200, w: 350, h: 400, title: 'Nearby chart' }, + ]); + for (let i = 1; i <= 45; i++) { + const admission = new SurfaceAdmission(); + const diagrams = f.diagrams.map(d => ({ ...d, appear: Math.min(1, i / 15) })); + painter.draw(canvas().ctx, diagrams, view, i * 1000 / 30, (id, b) => admission.admit(id, b)); + assertClear([...admission.shown.values()]); + assert.equal(admission.shown.size + admission.omitted.size, 2); + } +}); + +test('omitted diagrams and their owned marks are absent from the published frame', () => { + const view = { width: 1000, height: 1000 }; + const f = frame([ + { op: 'diagram', kind: 'chart', id: 'chart', x: 100, y: 100, w: 400, h: 400, title: 'Chart' }, + { op: 'point', id: 'dot', x: 250, y: 250, color: 'blue' }, + { op: 'label', id: 'standalone', x: 700, y: 700, text: 'Keep me', color: 'blue' }, + ]); + const admission = new SurfaceAdmission([{ x: 100, y: 100, w: 400, h: 400 }]); + admission.admit('chart', { x: 100, y: 100, w: 400, h: 400 }); + const shown = admittedFrame(f, admission, new Map([['dot', 'chart']])); + assert.equal(shown.diagrams.length, 0); + assert.deepEqual(shown.marks.map(m => m.id), ['standalone']); +}); + +test('an admitted chart keeps its own annotation where an omitted chart overlaps', () => { + const f = frame([ + { op: 'diagram', kind: 'chart', id: 'a', x: 100, y: 100, w: 400, h: 400 }, + { op: 'point', id: 'annotation-a', x: 250, y: 250, color: 'blue' }, + { op: 'diagram', kind: 'chart', id: 'b', x: 200, y: 200, w: 400, h: 400 }, + ]); + const admission = new SurfaceAdmission(); + admission.admit('a', { x: 100, y: 100, w: 400, h: 400 }); + admission.admit('b', { x: 200, y: 200, w: 400, h: 400 }); + const shown = admittedFrame(f, admission, new Map([['annotation-a', 'a']])); + assert.deepEqual(shown.marks.map(m => m.id), ['annotation-a']); +}); + +import { ownedByDiagram } from '../src/overlay/placement.ts'; +test('ownership keeps the authored surface identity through overlaps and placer renewal', () => { + const actions: Action[] = [ + { op: 'diagram', kind: 'chart', id: 'a', x: 100, y: 100, w: 400, h: 400 }, + { op: 'point', id: 'annotation-a', x: 250, y: 250, color: 'blue' }, + { op: 'diagram', kind: 'chart', id: 'b', x: 200, y: 200, w: 400, h: 400 }, + ]; + const owners = new Map(); + assert.deepEqual(ownedByDiagram([{ actions }], 1, 1000, 1, undefined, owners), [[false, true, false]]); + assert.equal(owners.get('annotation-a'), 'a'); + const grid = pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108); + const p = new Placer(grid, { aspect: 1 }); + placeAction(p, actions[0]!, 1000); + const renewed = new Placer(grid, { aspect: 1 }); renewed.restore(p.snapshot()); + assert.equal(renewed.ownerOf(actions[1]!), 'a'); + renewed.release('a'); + assert.equal(renewed.ownerOf(actions[1]!), undefined); +}); + +import { LabelBoard, Occupancy } from '../src/overlay/labels.ts'; +import * as admissionModule from '../src/overlay/surface-admission.ts'; +test('omitting the stage for the cue also releases its existing pin-label rectangles', () => { + const board = new LabelBoard(); + board.beginFrame({ width: 1000, height: 800, model: undefined, dragging: false, now: 0 }); + board.place(1, { anchor: { x: 500, y: 400 }, w: 120, h: 30 }, () => ({ occ: new Occupancy(1000, 800) })); + assert.equal(board.shownRects().length, 1, 'the first paint has a live label'); + assert.equal(typeof admissionModule.omitStageForCue, 'function', 'stage omission must clear its retained labels'); + const f = frame([{ op: 'panel', x: 0, y: 0, w: 1000, h: 1000 }, { op: 'pin', id: 'label', on: 'part', text: 'Label' }]); + const shown = admissionModule.omitStageForCue(f, board); + assert.equal(shown.panel, null); + assert.deepEqual(shown.marks, []); + assert.deepEqual(board.shownRects(), [], 'no invisible pin-label region survives the second paint'); +}); diff --git a/test/support/crowded-panels.json b/test/support/crowded-panels.json new file mode 100644 index 00000000..059ad61d --- /dev/null +++ b/test/support/crowded-panels.json @@ -0,0 +1,221 @@ +{ + "v": 1, + "steps": [ + { + "say": "", + "actions": [ + { + "op": "diagram", + "kind": "flow", + "id": "flow", + "x": 608, + "y": 12, + "w": 437, + "h": 379, + "title": "factorial(3), by recursion" + }, + { + "op": "node", + "id": "n0", + "of": "flow", + "text": "factorial(3)", + "note": "3 \u00d7 factorial(2)" + }, + { + "op": "node", + "id": "n1", + "of": "flow", + "text": "factorial(2)", + "note": "2 \u00d7 factorial(1)" + }, + { + "op": "node", + "id": "n2", + "of": "flow", + "text": "factorial(1)", + "note": "base case: 1" + }, + { + "op": "node", + "id": "n3", + "of": "flow", + "text": "Result: 6", + "note": "3 \u00d7 2 \u00d7 1" + }, + { + "op": "edge", + "id": "e0", + "from": "n0", + "to": "n1", + "text": "calls" + }, + { + "op": "edge", + "id": "e1", + "from": "n1", + "to": "n2", + "text": "calls" + }, + { + "op": "edge", + "id": "e2", + "from": "n2", + "to": "n3", + "text": "returns" + }, + { + "op": "diagram", + "kind": "timeline", + "id": "timeline", + "x": 220, + "y": 12, + "w": 437, + "h": 379, + "title": "Autumn 1066" + }, + { + "op": "node", + "id": "t0", + "of": "timeline", + "when": "20 Sep", + "text": "Fulford" + }, + { + "op": "node", + "id": "t1", + "of": "timeline", + "when": "25 Sep", + "text": "Stamford Bridge" + }, + { + "op": "node", + "id": "t2", + "of": "timeline", + "when": "28 Sep", + "text": "Normans land" + }, + { + "op": "node", + "id": "t3", + "of": "timeline", + "when": "14 Oct", + "text": "Hastings" + }, + { + "op": "diagram", + "kind": "steps", + "id": "steps", + "x": 30, + "y": 450, + "w": 379, + "h": 483, + "title": "Banana bread" + }, + { + "op": "node", + "id": "s0", + "of": "steps", + "text": "Cream butter and sugar" + }, + { + "op": "node", + "id": "s1", + "of": "steps", + "text": "Beat in eggs and mashed bananas" + }, + { + "op": "node", + "id": "s2", + "of": "steps", + "text": "Fold in flour, salt and sugar" + }, + { + "op": "node", + "id": "s3", + "of": "steps", + "text": "Bake 60 minutes at 175 C" + }, + { + "op": "card", + "id": "note", + "x": 670, + "y": 520, + "w": 368, + "title": "Read this note", + "rows": [ + "Price is the vertical axis", + "Quantity is the horizontal axis", + "Equilibrium is where the curves meet", + "A shock moves one curve, not both" + ] + }, + { + "op": "diagram", + "kind": "chart", + "id": "market", + "x": 590, + "y": 440, + "w": 460, + "h": 437, + "title": "Supply and demand", + "xlabel": "Quantity", + "ylabel": "Price", + "xrange": [ + 0, + 10 + ], + "yrange": [ + 0, + 10 + ] + }, + { + "op": "series", + "id": "supply", + "of": "market", + "color": "blue", + "pts": [ + [ + 1, + 1.6 + ], + [ + 5, + 4 + ], + [ + 9, + 8.8 + ] + ], + "label": "Supply" + }, + { + "op": "series", + "id": "demand", + "of": "market", + "color": "red", + "pts": [ + [ + 1, + 9 + ], + [ + 2, + 6 + ], + [ + 5, + 4.5 + ], + [ + 9, + 2.4 + ] + ], + "label": "Demand" + } + ] + } + ] +} From 50f9a4c559969c8ab02b993ac8dce79b8ec587b1 Mon Sep 17 00:00:00 2001 From: Alex Sharp Date: Sun, 8 Nov 2026 20:06:31 +1300 Subject: [PATCH 2/2] fix: prioritize current panels and retiring replacements --- docs/overlay.md | 10 ++ src/overlay/diagram-draw.ts | 41 ++++++-- src/overlay/diagram-plan.ts | 7 ++ src/overlay/index.html | 5 +- src/overlay/overlay.ts | 57 ++++++----- src/overlay/placement.ts | 29 +++--- src/overlay/surface-admission.ts | 74 +++++++++++++- src/overlay/timeline.ts | 6 ++ test/overlay-crowded-panels.test.ts | 146 +++++++++++++++++++++++++-- test/overlay-flow-transition.test.ts | 20 ++++ 10 files changed, 334 insertions(+), 61 deletions(-) diff --git a/docs/overlay.md b/docs/overlay.md index 34603aac..c4d480d5 100644 --- a/docs/overlay.md +++ b/docs/overlay.md @@ -34,6 +34,16 @@ The camera's near and far clipping planes follow the current visible pieces, inc `theme.ts` holds the look of what the overlay draws on the screen. The tags pinned to 3D parts and the image cards are dark glass with a coloured dot or bar and thin light lines. The flat diagrams (flow, timeline, steps, chart) and the note cards wear **Frost**: soft frosted panels with rounded, tinted items, each in its own accent in turn (blue, teal, violet, amber, rose), that follow the page: a light panel over a light page, a dark one over a dark page (`FROST`, `faceFor`). Windows' own fonts (Segoe UI Variable). The scene never chooses either look; it names colours, not faces. +### Crowded panels + +Placement first tries to keep readable surfaces apart. When no layout fits, admission uses the actual painted card bounds, including flow growth and entrance motion, and omits whole conflicting panels instead of painting text through text. The stage keeps priority, then panels added or highlighted by the current step (including their diagram items), then older retained panels. Newer panels win ties. A visible count explains omissions; omitted panels and their annotations have no pointer footprint. + +Cleared panels may finish fading only where they do not block live panels. Their departure does not count as a crowded omission, and reusing an id removes the old fading instance before measurement. An annotation belongs to the last preceding containing diagram or image and follows that exact surface through placement. + +Diagram bounds are prepared without painting, then admitted content is painted once at the same timestamp. Node easing is not reset or advanced twice. The cue measures in an aria-hidden element, caches its size by count bound and viewport width, and changes its live text only when the count changes. + +Known limits: an extreme thirteen-panel layout at 480×340 can still evict the stage to make room for the cue. Omitted panels still participate in placement, and diagram-internal clipping is separate from panel overlap. This fallback does not implement stage growth or animation hysteresis; future stage growth should relocate panels through the placer before admission becomes necessary. + ### Where tags go `labels.ts` places the tag of every `pin` by itself; the scene only says what is pinned to what. It is plain geometry (tested without a window): the page gives it the outline of every part of the model on screen, how busy the page underneath is (edges in the screenshot, so text counts), and the anchor of each pin. A tag is put where it overlaps neither the model, nor another tag, nor (as far as there is room) the page's own text; its leader never crosses another leader or tag, and runs over as little of the model as possible. Placed tags stay put while the model turns; only the leaders follow their parts. When the model moves a long way (a new stage, a big zoom) the tags are laid out again and glide to their new places; a tag whose way would take it through another (two that swap sides) fades out where it is and in at its new place instead, so tags never pass over each other. A scene's `off` is only a hint for the side. diff --git a/src/overlay/diagram-draw.ts b/src/overlay/diagram-draw.ts index 85e8fd7b..f3d47317 100644 --- a/src/overlay/diagram-draw.ts +++ b/src/overlay/diagram-draw.ts @@ -111,6 +111,7 @@ export class DiagramPainter { this.options = options; } private last: number | undefined; + private prepared: { now: number; rects: Map; seen: Set; moving: boolean } | undefined; moving = false; /** Reset node easing when an edge change actually moves an existing node to a different graph slot. */ @@ -155,22 +156,44 @@ export class DiagramPainter { return next; } + /** Collect actual surface bounds before admission, without painting or pruning content animation state. + * The matching draw consumes these card rectangles and advances node easing only once. + */ + prepare(ctx: Ctx, diagrams: readonly DiagramFrame[], view: View, now: number, onBounds: (id: string, box: Px) => void): void { + const dt = this.last === undefined ? 0 : Math.min(0.1, (now - this.last) / 1000); + const rects = new Map(), seen = new Set(); + this.moving = false; + this.grownLive.clear(); + for (const d of diagrams) { + if (d.opacity * d.fade <= 0.002 || d.appear <= 0) continue; + ctx.save(); + try { + const r = this.surface(ctx, d, view, dt, seen); + rects.set(d.key, r); + onBounds(d.id, { ...r, y: r.y + (1 - d.appear) * 10 }); + } finally { ctx.restore(); } + } + this.prepared = { now, rects, seen, moving: this.moving }; + } + /** Draws every diagram of the frame; `now` is a clock in milliseconds. Returns true while something is still gliding into place. */ draw(ctx: Ctx, diagrams: readonly DiagramFrame[], view: View, now: number, admitSurface = this.options.admitSurface): boolean { const dt = this.last === undefined ? 0 : Math.min(0.1, (now - this.last) / 1000); this.last = now; - this.moving = false; - this.grownLive.clear(); + const prepared = this.prepared?.now === now ? this.prepared : undefined; + this.prepared = undefined; + this.moving = prepared?.moving ?? false; + if (!prepared) this.grownLive.clear(); this.flowLive.clear(); this.timelineLive.clear(); - const seen = new Set(); + const seen = prepared?.seen ?? new Set(); for (const d of diagrams) { const alpha = Math.max(0, Math.min(1, d.opacity * d.fade)); if (alpha <= 0.002 || d.appear <= 0) continue; ctx.save(); ctx.setTransform(view.dpr, 0, 0, view.dpr, 0, 0); try { - this.one(ctx, d, view, alpha, dt, seen, admitSurface); + this.one(ctx, d, view, alpha, dt, seen, admitSurface, prepared?.rects.get(d.key)); } finally { ctx.restore(); } @@ -220,11 +243,15 @@ export class DiagramPainter { return regrow(d.def.id, want) ?? r0; } - private one(ctx: Ctx, d: DiagramFrame, view: View, alpha: number, dt: number, seen: Set, admitSurface?: (id: string, bounds: Px) => boolean): void { - const theme = THEME; + private surface(ctx: Ctx, d: DiagramFrame, view: View, dt: number, seen: Set): Px { const asked = rectOf(d, view); // A flow does not go below a readable node size: its card grows (eased, so a late node does not make it jump) until the nodes read. - const r = d.def.kind === 'flow' ? this.ease(`${d.key}:card`, this.grownFlow(ctx, d, asked, view), dt, seen) : asked; + return d.def.kind === 'flow' ? this.ease(`${d.key}:card`, this.grownFlow(ctx, d, asked, view), dt, seen) : asked; + } + + private one(ctx: Ctx, d: DiagramFrame, view: View, alpha: number, dt: number, seen: Set, admitSurface?: (id: string, bounds: Px) => boolean, prepared?: Px): void { + const theme = THEME; + const r = prepared ?? this.surface(ctx, d, view, dt, seen); // Admission uses the grown/eased card and its entrance slide, not the authored rectangle. if (admitSurface?.(d.id, { ...r, y: r.y + (1 - d.appear) * 10 }) === false) return; this.options.onBounds?.(d.id, r); diff --git a/src/overlay/diagram-plan.ts b/src/overlay/diagram-plan.ts index df4550af..cece619b 100644 --- a/src/overlay/diagram-plan.ts +++ b/src/overlay/diagram-plan.ts @@ -39,6 +39,9 @@ export type DiagramItemFrame = { done: number; }; export type DiagramFrame = { + /** This step added or highlighted the panel or one of its pieces. */ + currentStep?: boolean; + leaving?: boolean; key: number; id: string; def: DiagramAction; color: string | undefined; opacity: number; appear: number; fade: number; pulse: number; pulseColor: string | undefined; /** What the diagram holds, in the order it was made. */ @@ -201,9 +204,12 @@ export function evaluateDiagrams(dp: DiagramPlan, t: number): DiagramFrame[] { const dpulse = pulseAt(d, t); const dappear = ease(progress(t, d.bornAt, DIAGRAM_APPEAR_SECONDS)); const dfade = d.diedAt === undefined ? 1 : 1 - progress(t, d.diedAt, DIAGRAM_WIPE_SECONDS); + const touched = (i: Inst) => (i.bornAt >= 0 && i.bornAt <= t) || i.pulses.some(p => p.start <= t); + let currentStep = touched(d); const items: DiagramItemFrame[] = []; for (const it of dp.insts) { if (it.parentKey !== d.key || it.def.op === 'diagram' || !visibleAt(it, t)) continue; + if (touched(it)) currentStep = true; // A piece that is not born yet is kept (so the layout is steady while a diagram builds), at appear 0. const s = styleAt(it, t); const p = pulseAt(it, t); @@ -215,6 +221,7 @@ export function evaluateDiagrams(dp: DiagramPlan, t: number): DiagramFrame[] { }); } out.push({ + currentStep, leaving: d.diedAt !== undefined && d.diedAt <= t, key: d.key, id: d.id, def: d.def, color: ds.color, opacity: ds.opacity, appear: dappear, fade: clamp01(dfade), pulse: dpulse.amount, pulseColor: dpulse.color, items, }); diff --git a/src/overlay/index.html b/src/overlay/index.html index 1ef44e09..d86f6510 100644 --- a/src/overlay/index.html +++ b/src/overlay/index.html @@ -31,7 +31,7 @@ #dock { position: absolute; left: 0; right: 0; bottom: 28px; display: flex; flex-direction: column-reverse; align-items: center; gap: 10px; pointer-events: none; } #status, #notice { display: none; align-items: center; gap: 12px; box-sizing: border-box; max-width: min(88vw, 760px); padding: 10px 18px 10px 16px; border-radius: 999px; white-space: nowrap; background: var(--pill); color: var(--pilltext); font-size: 14px; font-weight: 620; letter-spacing: 0.005em; border: 1px solid var(--line); box-shadow: var(--shadow); } - #panel-overflow { position: absolute; display: none; box-sizing: border-box; width: min(320px, calc(100vw - 32px)); padding: 10px 14px; border-radius: 12px; background: var(--pill); color: var(--pilltext); border: 1px solid var(--line); font-size: 14px; line-height: 1.35; pointer-events: none; } + .panel-overflow { position: absolute; display: none; box-sizing: border-box; width: min(320px, calc(100vw - 32px)); padding: 10px 14px; border-radius: 12px; background: var(--pill); color: var(--pilltext); border: 1px solid var(--line); font-size: 14px; line-height: 1.35; pointer-events: none; } #status .lbl { font-weight: 650; } #status .hint { font-weight: 500; font-size: 12.5px; color: var(--muted); } #status .bars, #status .ell, #status .hint { display: none; } @@ -127,7 +127,8 @@
-
+
+

Spoken as well
diff --git a/src/overlay/overlay.ts b/src/overlay/overlay.ts index 13b7d21c..cbdf6fc7 100644 --- a/src/overlay/overlay.ts +++ b/src/overlay/overlay.ts @@ -20,7 +20,7 @@ import { LabelBoard, Occupancy, busyFromGray } from './labels.ts'; import type { Env as LabelEnv } from './labels.ts'; import { snapperFor } from './page-gray.ts'; import { PageMemory } from './page-memory.ts'; -import { SurfaceAdmission, admittedFrame, omitStageForCue, surfacesOverlap } from './surface-admission.ts'; +import { OmissionCue, SurfaceAdmission, admittedFrame, omitStageForCue, surfacesOverlap, withoutReplacedSurfaces } from './surface-admission.ts'; import { Placer, cardFootprint, displayBoxesFromPixels, followDiagram, markFootprint, ownedByDiagram, pageGrid, foreseePoints, placeAction, reserveMarks, settleMark, splitOwned } from './placement.ts'; import { FaceBook, THEME, fontAt } from './theme.ts'; import { snapToControl } from '../shared/controls.ts'; @@ -69,6 +69,8 @@ const sendFollowupEl = byId('send-followup'); const cancelFollowupEl = byId('cancel-followup'); const noticeEl = byId('notice'); const overflowEl = byId('panel-overflow'); +const overflowMeasureEl = byId('panel-overflow-measure'); +const omissionCue = new OmissionCue(overflowEl, overflowMeasureEl); const explodeEl = byId('explode'); const detailEl = byId('detail'); const cutEl = byId('cut'); @@ -315,7 +317,7 @@ let lastSourceFrame: Frame | undefined; let paintedSurfaces = new Map(); function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { - frame = displayedFrame(frame); + frame = withoutReplacedSurfaces(displayedFrame(frame), ownedSurfaces); renderer?.setScissorTest(false); renderer?.clear(); const rect = panelRect(frame.panel, view); @@ -414,7 +416,7 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { return { ...m, mark: mark.op === 'card' ? { ...mark, x: current.x, y: current.y } : { ...mark, dx: current.x, dy: current.y } }; } if (!ownedMarks.has(m.id)) return m; - const moved = followDiagram(p, mark, aspect, true); + const moved = followDiagram(p, mark, aspect, true, ownedSurfaces.get(m.id)); return moved ? { ...m, mark: moved as typeof m.mark } : m; }), diagrams: frame.diagrams.map((d) => { const current = p.surface(d.id); return current ? { ...d, def: { ...d.def, x: current.x, y: current.y } } : d; }), @@ -424,9 +426,11 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { board.keep(new Set(frame.marks.filter((m) => m.mark.op === 'pin').map((m) => m.key))); pinGeometry = []; let admission = new SurfaceAdmission(modelRect ? [modelRect] : []); + const paintTime = labelClock(); + const admitSurface = (id: string) => admission.shown.has(id); const annotator = { view, - admitSurface: (id: string, bounds: ScreenRect) => admission.admit(id, bounds), + admitSurface, ...(stageSize ? { stage: stageSize } : {}), faceOf: (key: string, rect: { x: number; y: number; w: number; h: number }) => faces.of(key, rect), place: (key: number, request: Parameters[1]) => board.place(key, request, labelEnvironment), @@ -437,27 +441,19 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { }, ...(cropSource() ? { source: cropSource()! } : {}), }; - // A mark that lies on a flat diagram (a ring on a chart's crossing, an arrow at a bar) is drawn above the diagram's opaque card, or it would be hidden by it. - const paintSurfaces = (): Frame => { - const { under } = splitOwned(frame.marks, ownedMarks); - pinGeometry = []; - drawMarks(marksCtx, under, view, annotator, { reduceMotion: reduceMotion.matches }); - // Admission happens after a flow grows/eases, immediately before its panel is painted. - diagramsMoving = diagramPainter.draw(marksCtx, frame.diagrams, view, labelClock(), (id, bounds) => admission.admit(id, bounds)); - const shown = admittedFrame(frame, admission, ownedSurfaces); - const { over } = splitOwned(shown.marks, ownedMarks); - if (over.length > 0) drawMarks(marksCtx, over, view, annotator, { reduceMotion: reduceMotion.matches, append: true }); - return shown; - }; - let shown = paintSurfaces(); + // Measure surfaces without painting their contents or touching pin-label state. The diagram + // painter retains these exact eased card bounds for the one final paint at the same timestamp. + drawMarks(marksCtx, frame.marks.filter(m => m.mark.op === 'card' || m.mark.op === 'image'), view, + { ...annotator, admitSurface: (id, bounds) => { admission.admit(id, bounds); return false; } }, + { reduceMotion: reduceMotion.matches }); + diagramPainter.prepare(marksCtx, frame.diagrams, view, paintTime, (id, bounds) => { admission.admit(id, bounds); }); + admission = admission.prioritize(frame); overflowEl.style.display = admission.omitted.size ? 'block' : 'none'; if (admission.omitted.size) { - // Measure the largest possible count once. The cue keeps this width while its count changes. - overflowEl.textContent = `${frame.marks.length + frame.diagrams.length + 1} panels hidden to prevent overlap`; - const size = overflowEl.getBoundingClientRect(); + const size = omissionCue.size(frame.marks.length + frame.diagrams.length + 1, view.width); const obstacles = [...admission.shown.values(), ...(modelRect ? [modelRect] : []), ...overlayControlRects()]; - const at = followupSpot(view, { w: size.width, h: size.height }, obstacles); - const cue = { ...at, w: size.width, h: size.height }; + const at = followupSpot(view, size, obstacles); + const cue = { ...at, w: size.w, h: size.h }; let hiddenStage = 0; if (obstacles.some(r => surfacesOverlap(cue, r))) { // No gap even for the cue: give it a dedicated slot, omitting intersecting panels too. @@ -470,14 +466,19 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { frame = omitStageForCue(frame, board); placeExplode(frame); } - admission = new SurfaceAdmission([cue, ...(modelRect ? [modelRect] : [])]); - shown = paintSurfaces(); + admission = admission.prioritize(frame, [cue, ...(modelRect ? [modelRect] : [])]); } const count = admission.omitted.size + hiddenStage; - overflowEl.textContent = `${count} ${count === 1 ? 'panel' : 'panels'} hidden to prevent overlap`; + omissionCue.show(count); overflowEl.style.left = `${at.x}px`; overflowEl.style.top = `${at.y}px`; } - frame = shown; + frame = admittedFrame(frame, admission, ownedSurfaces); + // Owned marks sit above their admitted panel; every other mark keeps the existing paint order. + const { under, over } = splitOwned(frame.marks, ownedMarks); + pinGeometry = []; + drawMarks(marksCtx, under, view, annotator, { reduceMotion: reduceMotion.matches }); + diagramsMoving = diagramPainter.draw(marksCtx, frame.diagrams, view, paintTime, admitSurface); + if (over.length) drawMarks(marksCtx, over, view, annotator, { reduceMotion: reduceMotion.matches, append: true }); paintedSurfaces = new Map(admission.shown); lastDisplayedFrame = frame; drawPen(marksCtx, pen.view(labelClock(), { reduceMotion: reduceMotion.matches }), view); @@ -1056,7 +1057,7 @@ function loop(): void { if (k < 1) frame = fadeFrame(frame, k); lastSourceFrame = frame; showHud(frame); - frame = displayedFrame(frame); + frame = withoutReplacedSurfaces(displayedFrame(frame), ownedSurfaces); showAnswer(); showFollowupControls(frame, k); syncUndo(); @@ -1449,7 +1450,7 @@ function placedScene(scene: Scene): Scene { snapped.forEach((step, i) => reserveMarks(p, step.actions.filter((_, j) => !owned[i]![j]), aspect)); const placed = snapped.map((step) => ({ ...step, actions: step.actions.map((a) => !renderer && a.op === 'panel' ? a : placeAction(p, a, view.height)) })); // The points of a step are known to its names before they are marked (so a name written first finds its point); the next step's are not. - return { ...scene, steps: placed.map((step, i) => { foreseePoints(p, step.actions, aspect); return { ...step, actions: step.actions.map((a, j) => settleMark(p, owned[i]![j] ? followDiagram(p, a, aspect) ?? a : a)) }; }) }; + return { ...scene, steps: placed.map((step, i) => { foreseePoints(p, step.actions, aspect, ownedSurfaces); return { ...step, actions: step.actions.map((a, j) => settleMark(p, owned[i]![j] ? followDiagram(p, a, aspect, false, 'id' in a && typeof a.id === 'string' ? ownedSurfaces.get(a.id) : undefined) ?? a : a)) }; }) }; } function placedAction(action: Action): Action { diff --git a/src/overlay/placement.ts b/src/overlay/placement.ts index 6c1e3415..8fc3c633 100644 --- a/src/overlay/placement.ts +++ b/src/overlay/placement.ts @@ -545,6 +545,7 @@ export class Placer { ? this.search(want, [1, 0.88, 0.76, 0.64], keep, [1, 0.8, 0.65, 0.55, 0.5], 150, true, minRatio, DIAGRAM_MIN_SIZE) : full; this.cards.set(id, placed); + this.homes.delete(id); this.homes.set(id, { from: asked, to: placed }); return placed; } @@ -556,10 +557,11 @@ export class Placer { */ regrow(id: string, grown: Box): Box | undefined { const was = this.cards.get(id) ?? this.homes.get(id)?.to ?? grown; - const keepOut = [...this.reserved, ...this.controls, ...[...this.cards].filter(([k]) => k !== id).map(([, b]) => b), ...this.stageKeepOut()]; + const hard = [...this.controls, ...[...this.cards].filter(([k]) => k !== id).map(([, b]) => b), ...this.stageKeepOut()]; + const keepOut = [...this.reserved, ...hard]; const placed = this.search(grown, [1], [...keepOut, ...this.reserved, ...this.reserved], [1], 0, true); // A small coverage cost can still mean a whole line of another panel is hidden. - if (keepOut.some((r) => overlap(placed, r) > 0)) return undefined; + if (hard.some((r) => overlap(placed, r) > 0)) return undefined; if (this.coverage(placed, keepOut) > this.coverage(was, keepOut) + GROWTH_COVER_SLACK) return undefined; this.cards.set(id, placed); const home = this.homes.get(id); @@ -577,15 +579,16 @@ export class Placer { } /** The flat diagram a point on the screen belongs to (it is inside the rectangle the diagram was asked for), and where it was placed. */ - homeOf(x: number, y: number): { from: Box; to: Box } | undefined { - for (const h of this.homes.values()) if (x >= h.from.x && x <= h.from.x + h.from.w && y >= h.from.y && y <= h.from.y + h.from.h) return h; + homeOf(x: number, y: number, owner?: string): { from: Box; to: Box } | undefined { + if (owner !== undefined) return this.homes.get(owner); + for (const h of [...this.homes.values()].reverse()) if (x >= h.from.x && x <= h.from.x + h.from.w && y >= h.from.y && y <= h.from.y + h.from.h) return h; return undefined; } /** Exact surface identity for a newly streamed mark, before placement changes its coordinates. */ ownerOf(a: Action): string | undefined { const c = MARK_OPS.has(a.op) ? markCentre(a as Mark, this.aspect) : undefined; - if (c) for (const [id, home] of this.homes) { + if (c) for (const [id, home] of [...this.homes].reverse()) { const r = home.from; if (c.x >= r.x && c.x <= r.x + r.w && c.y >= r.y && c.y <= r.y + r.h) return id; } @@ -603,6 +606,7 @@ export class Placer { /** A card that marks may be written on (an enlarged crop): marks written inside the rectangle it was asked for go with it to where it was placed. */ home(id: string, from: Box, to: Box): void { + this.homes.delete(id); this.homes.set(id, { from, to }); } @@ -614,8 +618,9 @@ export class Placer { } /** Mapping for marks already placed in the player, not newly streamed marks. */ - displayedHomeOf(x: number, y: number): { from: Box; to: Box } | undefined { - for (const [id] of this.homes) { + displayedHomeOf(x: number, y: number, owner?: string): { from: Box; to: Box } | undefined { + for (const [id] of [...this.homes].reverse()) { + if (owner !== undefined && id !== owner) continue; const from = this.sourceBoxes.get(id); const to = this.cards.get(id); if (from && to && x >= from.x && x <= from.x + from.w && y >= from.y && y <= from.y + from.h) @@ -824,7 +829,7 @@ export function ownedByDiagram(steps: readonly { actions: readonly Action[] }[], seen.push({ id: a.id, x: a.dx, y: a.dy, w: a.dw, h: imageCardHeight(a, screenHeight, aspect, sourceAspect, measureCaption) }); return false; } - const owner = seen.find(r => insideAny(a, [r], aspect)); + const owner = seen.findLast(r => insideAny(a, [r], aspect)); if (owners && 'id' in a && typeof a.id === 'string') { if (owner) owners.set(a.id, owner.id); else owners.delete(a.id); } @@ -839,10 +844,10 @@ const r1 = (v: number): number => Math.round(v * 10) / 10; * diagram: when the diagram was placed elsewhere or smaller, the mark goes with it, to the same place in the new rectangle. * Nothing when the mark is not inside a diagram's rectangle. */ -export function followDiagram(placer: Placer, a: Action, aspect: number, displayed = false): Action | undefined { +export function followDiagram(placer: Placer, a: Action, aspect: number, displayed = false, owner?: string): Action | undefined { if (!MARK_OPS.has(a.op)) return undefined; const c = markCentre(a as Mark, aspect); - const home = c ? (displayed ? placer.displayedHomeOf(c.x, c.y) : placer.homeOf(c.x, c.y)) : undefined; + const home = c ? (displayed ? placer.displayedHomeOf(c.x, c.y, owner) : placer.homeOf(c.x, c.y, owner)) : undefined; if (!home) return undefined; const { from, to } = home; const fx = to.w / from.w, fy = to.h / from.h; @@ -951,10 +956,10 @@ function besidePoint(placer: Placer, a: Extract): Actio } /** The points among these marks are made known ahead of their turn, so the names written before them keep off their rings (see Placer.foresee). */ -export function foreseePoints(placer: Placer, actions: readonly Action[], aspect: number): void { +export function foreseePoints(placer: Placer, actions: readonly Action[], aspect: number, owners?: ReadonlyMap): void { for (const a of actions) { if (a.op !== 'point') continue; - const at = (followDiagram(placer, a, aspect) ?? a) as { x: number; y: number }; + const at = (followDiagram(placer, a, aspect, false, owners?.get(a.id)) ?? a) as { x: number; y: number }; placer.foresee(a.id, at.x, at.y, a.color); } } diff --git a/src/overlay/surface-admission.ts b/src/overlay/surface-admission.ts index 729fd5e2..cb64b6df 100644 --- a/src/overlay/surface-admission.ts +++ b/src/overlay/surface-admission.ts @@ -6,32 +6,70 @@ export function surfacesOverlap(a: Box, b: Box): boolean { && Math.min(a.y + a.h, b.y + b.h) > Math.max(a.y, b.y) + 1e-6; } -/** Last line of defence after placement: retain readable sizes and the existing paint order. +// Timeline departure is distinct from the scene-wide idle/Escape fade. +const isLeaving = (s: { leaving?: boolean; fade: number }) => s.leaving ?? s.fade < 1; + +/** Last line of defence after placement: retain readable sizes and give the current explanation priority. * Rebuilt each frame so clear, replacement, resize and the end of an animation release room. * Keep the whole panel, or omit it; never paint one panel through another's writing. */ export class SurfaceAdmission { readonly shown = new Map(); readonly omitted = new Map(); + readonly hidden = new Set(); + private readonly candidates = new Map(); private readonly keepOut: readonly Box[]; constructor(keepOut: readonly Box[] = []) { this.keepOut = keepOut; } admit(id: string, box: Box): boolean { + this.candidates.set(id, box); if ([...this.keepOut, ...this.shown.values()].some(other => surfacesOverlap(box, other))) { this.omitted.set(id, box); + this.hidden.add(id); return false; } this.shown.set(id, box); return true; } + /** Resolve actual painted bounds independently of paint order. Stage/cue reservations stay first. + * A leaving surface may finish fading in free space, but yields to every live surface silently. + */ + prioritize(frame: Frame, keepOut: readonly Box[] = this.keepOut): SurfaceAdmission { + const surfaces = new Map([...frame.marks, ...frame.diagrams].map(s => [s.id, s])); + const rank = (id: string) => { + const s = surfaces.get(id); + return { leaving: s ? isLeaving(s) : false, current: !!s?.currentStep, key: s?.key ?? 0 }; + }; + const ordered = [...this.candidates].sort(([a], [b]) => { + const x = rank(a), y = rank(b); + return Number(x.leaving) - Number(y.leaving) || Number(y.current) - Number(x.current) || y.key - x.key; + }); + const result = new SurfaceAdmission(keepOut); + for (const [id, box] of ordered) { + if (!result.admit(id, box) && rank(id).leaving) result.omitted.delete(id); + } + return result; + } +} + +/** A clear followed by reuse of an id replaces the fading instance, even across surface kinds. */ +export function withoutReplacedSurfaces(frame: Frame, owners: ReadonlyMap = new Map()): Frame { + const surfaces = [...frame.marks.filter(m => m.mark.op === 'card' || m.mark.op === 'image'), ...frame.diagrams]; + const active = new Map(surfaces.filter(s => !isLeaving(s)).map(s => [s.id, s.key])); + const keep = (s: { id: string; key: number }) => !active.has(s.id) || active.get(s.id) === s.key; + const replaced = new Set(surfaces.filter(s => !keep(s)).map(s => s.id)); + return { ...frame, + marks: frame.marks.filter(m => keep(m) && !(isLeaving(m) && replaced.has(owners.get(m.id) ?? ''))), + diagrams: frame.diagrams.filter(keep), + }; } /** Omitted cards have no pointer footprint and their annotations must not float on other panels. */ export function admittedFrame(frame: Frame, admission: SurfaceAdmission, owners: ReadonlyMap): Frame { - if (!admission.omitted.size) return frame; + if (!admission.hidden.size) return frame; return { ...frame, - diagrams: frame.diagrams.filter(d => !admission.omitted.has(d.id)), - marks: frame.marks.filter(m => !admission.omitted.has(m.id) && !admission.omitted.has(owners.get(m.id) ?? '')), + diagrams: frame.diagrams.filter(d => !admission.hidden.has(d.id)), + marks: frame.marks.filter(m => !admission.hidden.has(m.id) && !admission.hidden.has(owners.get(m.id) ?? '')), }; } @@ -40,3 +78,31 @@ export function omitStageForCue(frame: Frame, board: { keep(alive: ReadonlySet m.mark.op !== 'pin') }; } + +const omissionText = (count: number) => `${count} ${count === 1 ? 'panel' : 'panels'} hidden to prevent overlap`; + +/** Measure outside the live region, once per count bound and viewport width. */ +export class OmissionCue { + private measured: { key: string; w: number; h: number } | undefined; + private readonly live: { textContent: string | null }; + private readonly measure: { textContent: string | null; getBoundingClientRect(): { width: number; height: number } }; + constructor( + live: { textContent: string | null }, + measure: { textContent: string | null; getBoundingClientRect(): { width: number; height: number } }, + ) { this.live = live; this.measure = measure; } + + size(maxCount: number, viewportWidth: number): { w: number; h: number } { + const key = `${maxCount}:${viewportWidth}`; + if (this.measured?.key !== key) { + this.measure.textContent = omissionText(maxCount); + const { width: w, height: h } = this.measure.getBoundingClientRect(); + this.measured = { key, w, h }; + } + return { w: this.measured.w, h: this.measured.h }; + } + + show(count: number): void { + const text = omissionText(count); + if (this.live.textContent !== text) this.live.textContent = text; + } +} diff --git a/src/overlay/timeline.ts b/src/overlay/timeline.ts index 521c6f59..519b950f 100644 --- a/src/overlay/timeline.ts +++ b/src/overlay/timeline.ts @@ -86,6 +86,10 @@ export type FocusFrame = { }; export type MarkFrame = { + /** Added or highlighted in this step; retained frames reset this when the next step starts. */ + currentStep?: boolean; + /** Clearing has begun, including its first frame before fade decreases. */ + leaving?: boolean; key: number; id: string; mark: Mark; color: Rgb; opacity: number; /** 0..1, how far the mark has drawn in. */ appear: number; @@ -1004,6 +1008,8 @@ export function evaluate(plan: StepPlan, t: number): Frame { fade = Math.min(fade, fadeOf(host, t)); } marks.push({ + currentStep: m.bornAt >= 0 || plan.pulses.some(p => p.key === m.key && p.start <= t), + leaving: m.diedAt !== undefined && m.diedAt <= t, key: m.key, id: m.id, mark: m.mark, color: asRgb(valueAt(m.color, t)), opacity: valueAt(m.opacity, t)[0] ?? 1, appear, fade, pulse: pulse.amount, pulseColor: pulse.color, tinted: m.tinted, ...(m.onKey !== undefined ? { onKey: m.onKey } : {}), }); diff --git a/test/overlay-crowded-panels.test.ts b/test/overlay-crowded-panels.test.ts index da1129c4..19d51731 100644 --- a/test/overlay-crowded-panels.test.ts +++ b/test/overlay-crowded-panels.test.ts @@ -75,23 +75,28 @@ function drawWithAdmission(actions: Action[], view: { width: number; height: num const p = new Placer(pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108), { aspect: view.width / view.height, height: view.height }); const placed = usePlacer ? actions.map(a => placeAction(p, a, view.height)) : actions; const f = frame(placed); - const admission = new SurfaceAdmission(keepOut); + let admission = new SurfaceAdmission(keepOut); const { ctx, texts } = canvas(); - const admitSurface = (id: string, b: Box) => admission.admit(id, b); - drawMarks(ctx, f.marks, view, { view, project: () => undefined, admitSurface }); - new DiagramPainter({ admitSurface }).draw(ctx, f.diagrams, view, 0); - return { admission, texts, frame: admittedFrame(f, admission, new Map()) }; + const painter = new DiagramPainter(); + drawMarks(ctx, f.marks, view, { view, project: () => undefined, admitSurface: (id, box) => { admission.admit(id, box); return false; } }); + painter.prepare(ctx, f.diagrams, view, 0, (id, box) => { admission.admit(id, box); }); + admission = admission.prioritize(f); + const shown = admittedFrame(f, admission, new Map()); + const admitSurface = (id: string) => admission.shown.has(id); + drawMarks(ctx, shown.marks, view, { view, project: () => undefined, admitSurface }); + painter.draw(ctx, shown.diagrams, view, 0, admitSurface); + return { admission, texts, frame: shown }; } function assertClear(boxes: Box[]) { for (let i = 0; i < boxes.length; i++) for (let j = i + 1; j < boxes.length; j++) assert.ok(!surfacesOverlap(boxes[i]!, boxes[j]!), `panels ${i} and ${j} overlap: ${JSON.stringify(boxes)}`); } -test('the five-panel sheet preserves the note and never draws another panel over its content', () => { +test('the five-panel sheet preserves the newest chart and never overlaps admitted content', () => { const result = drawWithAdmission(sheet, { width: 1920, height: 1080, dpr: 1 }); assertClear([...result.admission.shown.values()]); assert.equal(result.admission.shown.size + result.admission.omitted.size, 5); - assert.ok(result.admission.shown.has('note')); + assert.ok(result.admission.shown.has('market')); assert.ok(result.admission.omitted.size > 0, 'a crowded sheet needs the explicit fallback'); }); @@ -176,7 +181,7 @@ test('an admitted chart keeps its own annotation where an omitted chart overlaps assert.deepEqual(shown.marks.map(m => m.id), ['annotation-a']); }); -import { ownedByDiagram } from '../src/overlay/placement.ts'; +import { ownedByDiagram, followDiagram } from '../src/overlay/placement.ts'; test('ownership keeps the authored surface identity through overlaps and placer renewal', () => { const actions: Action[] = [ { op: 'diagram', kind: 'chart', id: 'a', x: 100, y: 100, w: 400, h: 400 }, @@ -209,3 +214,128 @@ test('omitting the stage for the cue also releases its existing pin-label rectan assert.deepEqual(shown.marks, []); assert.deepEqual(board.shownRects(), [], 'no invisible pin-label region survives the second paint'); }); + +import { evaluate } from '../src/overlay/timeline.ts'; +function resolveSurfaces(f: ReturnType) { + const a = new SurfaceAdmission(); + for (const m of f.marks) if (m.mark.op === 'card' || m.mark.op === 'image') a.admit(m.id, { x: 100, y: 100, w: 400, h: 300 }); + for (const d of f.diagrams) a.admit(d.id, { x: 100, y: 100, w: 400, h: 300 }); + return a.prioritize(f); +} +const crowdedChart = (id: string): Action => ({ op: 'diagram', kind: 'chart', id, x: 100, y: 100, w: 400, h: 300, title: id }); +test('newest current-step panel wins across cards and diagrams, regardless of paint order', () => { + const f = frame([{ op: 'card', id: 'old-note', x: 100, y: 100, w: 400, title: 'Old', rows: ['Before'] }, crowdedChart('new-chart')]); + assert.deepEqual([...resolveSurfaces(f).shown.keys()], ['new-chart']); +}); +test('a highlighted retained panel wins for the whole current step, including after its pulse ends', () => { + const base = frame([crowdedChart('earlier'), crowdedChart('later')]); + const p = planStep(base, { say: '', actions: [{ op: 'highlight', id: 'earlier', at: 1, dur: 0.2 }] }); + assert.deepEqual([...resolveSurfaces(evaluate(p, 0.5)).shown.keys()], ['later'], 'future highlight does not take priority early'); + for (const t of [1, 1.1, 2, Infinity]) assert.deepEqual([...resolveSurfaces(evaluate(p, t)).shown.keys()], ['earlier']); +}); +test('adding or highlighting a diagram item promotes its containing panel on a follow-up', () => { + const base = frame([crowdedChart('earlier'), crowdedChart('later')]); + assert.deepEqual([...resolveSurfaces(base).shown.keys()], ['later']); + const next = settle(planStep(base, { say: '', actions: [{ op: 'dot', id: 'dot', of: 'earlier', x: 1, y: 1 }] })); + assert.deepEqual([...resolveSurfaces(next).shown.keys()], ['earlier']); + const highlighted = settle(planStep(next, { say: '', actions: [{ op: 'highlight', id: 'dot' }] })); + assert.deepEqual([...resolveSurfaces(highlighted).shown.keys()], ['earlier']); +}); +test('a leaving panel yields to its arriving replacement without a crowded omission cue', () => { + for (const old of [crowdedChart('old'), { op: 'card', id: 'old', x: 100, y: 100, w: 400, title: 'Old', rows: ['Old'] } as Action]) { + const p = planStep(frame([old]), { say: '', actions: [{ op: 'clear', target: 'all', at: 0 }, crowdedChart('new')] }); + for (const t of [0.01, 0.1, 0.2, 0.3, 1]) { + const f = evaluate(p, t), a = resolveSurfaces(f); + assert.deepEqual([...a.shown.keys()], ['new'], `replacement wins at ${t}`); + assert.equal(a.omitted.size, 0, 'a departing panel is not a crowded omission'); + const shown = admittedFrame(f, a, new Map()); + assert.ok(!shown.marks.some(m => m.id === 'old') && !shown.diagrams.some(d => d.id === 'old')); + } + } +}); + +test('annotations belong to the last preceding containing diagram, in authored and streamed placement', () => { + const a = crowdedChart('a'), b = crowdedChart('b'); + const point = (id: string): Action => ({ op: 'point', id, x: 250, y: 250, color: 'blue' }); + const actions = [a, point('on-a'), b, point('on-b')]; + const owners = new Map(); + ownedByDiagram([{ actions }], 1, 1000, 1, undefined, owners); + assert.deepEqual([...owners], [['on-a', 'a'], ['on-b', 'b']]); + const p = new Placer(pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108), { aspect: 1 }); + p.home('a', { x: 100, y: 100, w: 400, h: 300 }, { x: 0, y: 0, w: 400, h: 300 }); + p.home('b', { x: 100, y: 100, w: 400, h: 300 }, { x: 500, y: 500, w: 400, h: 300 }); + assert.equal(p.ownerOf(point('streamed')), 'b'); + assert.deepEqual(followDiagram(p, point('on-a'), 1, false, owners.get('on-a')), { ...point('on-a'), x: 150, y: 150 }); + assert.deepEqual(followDiagram(p, point('on-b'), 1, false, owners.get('on-b')), { ...point('on-b'), x: 650, y: 650 }); + const admission = new SurfaceAdmission(); + admission.admit('a', { x: 100, y: 100, w: 400, h: 300 }); + admission.admit('b', { x: 100, y: 100, w: 400, h: 300 }); + assert.deepEqual(admittedFrame(frame(actions), admission, owners).marks.map(m => m.id), ['on-a']); +}); + +test('regrowth can retain a soft pointed-at overlap when no extra page coverage is needed', () => { + const p = new Placer(pageGrid(new Uint8Array(192 * 108).fill(240), 192, 108), { aspect: 1 }); + p.reserve({ x: 0, y: 0, w: 1000, h: 1000 }); + p.diagram({ x: 100, y: 100, w: 300, h: 300 }, 'flow'); + const grown = p.regrow('flow', { x: 100, y: 100, w: 450, h: 450 }); + assert.ok(grown, 'pointed-at page space is a weighted preference, not another opaque panel'); + assert.equal(grown.w, 450); +}); + +test('the omission cue measures separately and never rewrites unchanged live text', () => { + const writes: string[] = [], measureWrites: string[] = []; + let text = '', reads = 0; + const live = { get textContent() { return text; }, set textContent(value: string) { text = value; writes.push(value); } }; + const measure = { set textContent(value: string) { measureWrites.push(value); }, getBoundingClientRect() { reads++; return { width: 320, height: 60 }; } }; + assert.equal(typeof admissionModule.OmissionCue, 'function', 'the cue needs a cached, non-live measurement'); + const cue = new admissionModule.OmissionCue(live, measure); + for (let i = 0; i < 20; i++) { assert.deepEqual(cue.size(12, 800), { w: 320, h: 60 }); cue.show(1); } + assert.deepEqual(writes, ['1 panel hidden to prevent overlap']); + assert.equal(reads, 1); + assert.equal(measureWrites.length, 1); + cue.show(2); + assert.deepEqual(writes, ['1 panel hidden to prevent overlap', '2 panels hidden to prevent overlap']); + cue.size(12, 500); + assert.equal(reads, 2, 'viewport changes invalidate the cached size'); + assert.equal(writes.length, 2, 'measurement never changes the live announcement'); +}); + +test('clear and reuse of the same panel id removes the departing instance before measuring', () => { + const old = frame([crowdedChart('panel')]); + const f = evaluate(planStep(old, { say: '', actions: [ + { op: 'clear', target: 'all' }, + { op: 'card', id: 'panel', x: 600, y: 600, w: 200, title: 'Replacement', rows: [] }, + ] }), 0.1); + assert.equal(f.diagrams.length, 1, 'the cleared instance is still fading'); + const prepared = admissionModule.withoutReplacedSurfaces(f); + assert.equal(prepared.diagrams.length, 0, 'the old instance must neither paint nor overwrite replacement bounds'); + assert.equal(prepared.marks.length, 1); +}); + +import { fadeFrame } from '../src/overlay/fade.ts'; +test('global scene dimming does not turn live panels into departing surfaces', () => { + const f = fadeFrame(frame([crowdedChart('old'), crowdedChart('new')]), 0.8); + const a = resolveSurfaces(f); + assert.deepEqual([...a.shown.keys()], ['new']); + assert.equal(a.omitted.size, 1, 'a genuinely crowded panel keeps its omission cue during scene fade'); +}); +test('same-id replacement remains exclusive during an Escape fade', () => { + const f = evaluate(planStep(frame([crowdedChart('panel')]), { say: '', actions: [ + { op: 'clear', target: 'all' }, { op: 'card', id: 'panel', x: 600, y: 600, w: 200, title: 'New', rows: [] }, + ] }), 0.1); + const prepared = admissionModule.withoutReplacedSurfaces(fadeFrame(f, 0.9)); + assert.equal(prepared.diagrams.length, 0); + assert.equal(prepared.marks.length, 1); +}); + +test('reusing a panel id retires its old annotations but keeps newly written annotations', () => { + const oldPoint: Action = { op: 'point', id: 'old-point', x: 250, y: 250, color: 'blue' }; + const f = evaluate(planStep(frame([crowdedChart('panel'), oldPoint]), { say: '', actions: [ + { op: 'clear', target: 'all' }, crowdedChart('panel'), { ...oldPoint, id: 'new-point' }, + ] }), 0.1); + const owners = new Map([['old-point', 'panel'], ['new-point', 'panel']]); + const prepared = admissionModule.withoutReplacedSurfaces(f, owners); + assert.deepEqual(prepared.marks.map(m => m.id), ['new-point']); + assert.equal(prepared.diagrams.length, 1); + assert.equal(prepared.diagrams[0]!.leaving, false); +}); diff --git a/test/overlay-flow-transition.test.ts b/test/overlay-flow-transition.test.ts index 4e9a4465..d91ae0e9 100644 --- a/test/overlay-flow-transition.test.ts +++ b/test/overlay-flow-transition.test.ts @@ -155,3 +155,23 @@ test('reordered unchanged edges and a resized card retain ordinary easing', () = assert.deepEqual(after.sort(),before.sort(),'edge ordering alone does not reset node identities'); assert.equal(p.moving,true,'ordinary resize/card movement continues to ease'); }); + +test('admission measurement preserves node easing and paints the exact collected card bounds', () => { + const direct = new DiagramPainter(), admitted = new DiagramPainter(); + const plain = canvasGeometry(), measured = canvasGeometry(); + const view = { width: 1000, height: 800, dpr: 1 }; + direct.draw(plain.ctx, chain.diagrams, view, 0); + admitted.draw(measured.ctx, chain.diagrams, view, 0); + const moved = chain.diagrams.map(d => ({ ...d, def: { ...d.def, x: d.def.x + 100 } })); + for (let i = 1; i <= 10; i++) { + const now = i * 16; + plain.clear(); measured.clear(); + direct.draw(plain.ctx, moved, view, now); + const bounds = new Map(); + if (typeof admitted.prepare === 'function') admitted.prepare(measured.ctx, moved, view, now, (id, box) => { bounds.set(id, box); }); + else admitted.draw(measured.ctx, moved, view, now, (id, box) => { bounds.set(id, box); return false; }); + assert.deepEqual(measured.nodes, [], 'measurement must not paint content'); + admitted.draw(measured.ctx, moved, view, now, (id, box) => { assert.deepEqual(box, bounds.get(id), 'paint must use the admitted geometry'); return true; }); + assert.deepEqual(measured.nodes, plain.nodes, `priority collection must not reset or double-advance animation at frame ${i}`); + } +});