Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/overlay.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions src/overlay/annotations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down Expand Up @@ -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'];

Expand Down Expand Up @@ -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);
Expand Down
47 changes: 39 additions & 8 deletions src/overlay/diagram-draw.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand All @@ -109,6 +111,7 @@ export class DiagramPainter {
this.options = options;
}
private last: number | undefined;
private prepared: { now: number; rects: Map<number, Px>; seen: Set<string>; moving: boolean } | undefined;
moving = false;

/** Reset node easing when an edge change actually moves an existing node to a different graph slot. */
Expand Down Expand Up @@ -153,22 +156,44 @@ export class DiagramPainter {
return next;
}

/** 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 {
/** 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);
this.last = now;
const rects = new Map<number, Px>(), seen = new Set<string>();
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;
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<string>();
const seen = prepared?.seen ?? new Set<string>();
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);
this.one(ctx, d, view, alpha, dt, seen, admitSurface, prepared?.rects.get(d.key));
} finally {
ctx.restore();
}
Expand Down Expand Up @@ -218,11 +243,17 @@ export class DiagramPainter {
return regrow(d.def.id, want) ?? r0;
}

private one(ctx: Ctx, d: DiagramFrame, view: View, alpha: number, dt: number, seen: Set<string>): void {
const theme = THEME;
private surface(ctx: Ctx, d: DiagramFrame, view: View, dt: number, seen: Set<string>): 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<string>, 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);
const face = this.options.faceOf?.(`d${d.key}`, r) ?? 'dark';
const tone = FROST[face];
Expand Down
7 changes: 7 additions & 0 deletions src/overlay/diagram-plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down Expand Up @@ -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);
Expand All @@ -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,
});
Expand Down
3 changes: 3 additions & 0 deletions src/overlay/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand Down Expand Up @@ -126,6 +127,8 @@
<button id="detail" type="button" title="Ask for a much more detailed version of this model"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 4l1.8 4.6L18.5 10l-4.7 1.4L12 16l-1.8-4.6L5.5 10l4.7-1.4z"/><path d="M18 16l.8 2 2 .8-2 .8-.8 2-.8-2-2-.8 2-.8z"/></svg><span class="lbl">More detail</span></button>
<button id="undo" type="button" title="Take back the last circle"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M9 7L4 12l5 5"/><path d="M4 12h10a6 6 0 0 1 0 12"/></svg><span>Undo</span></button>
<div id="caption"></div>
<div id="panel-overflow" class="panel-overflow" role="status" aria-live="polite"></div>
<div id="panel-overflow-measure" class="panel-overflow" aria-hidden="true" style="display: block; visibility: hidden"></div>
<div id="answer"><div class="aq"><span class="dot"></span><span id="answer-q"></span></div><p id="answer-text"></p><div class="rule"></div><div class="foot"><span id="answer-spoken">Spoken as well</span><span class="sp"></span><button id="answer-copy" type="button">Copy</button><button id="answer-pin" type="button">Pin</button><button id="answer-close" type="button">Close</button></div></div>
<script src="./overlay.js"></script>
</body>
Expand Down
Loading
Loading