Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
88a4c50
Flows and forces: wave along a tube, flow in beats, pump, particles t…
ProjectIdris Nov 8, 2026
0336bf9
The camera fits the stage to everything a running machine does, not o…
ProjectIdris Nov 8, 2026
c5b14f7
A pendulum hung from a part its weight is attached to swings about th…
ProjectIdris Nov 8, 2026
7a67f8e
The swept part may fit to the screen's edge, not only the stage's, an…
ProjectIdris Nov 8, 2026
e46cd8f
Guide: say add with shape force, field and particles (a model wrote o…
ProjectIdris Nov 8, 2026
1d301ba
Merge arm-fit (camera fits a model's whole swing)
ProjectIdris Nov 8, 2026
13e43b0
The stage grows taller to about 62 percent of the screen where the pa…
ProjectIdris Nov 8, 2026
ff7d3e2
Guide pass: a smaller guide with the gaps the judge sets found closed
ProjectIdris Nov 8, 2026
fb46d38
Guide: a heart is drawn with all its chambers, and the pump goes to t…
ProjectIdris Nov 8, 2026
aeea585
Guide: the muscle line keeps its 0.1 to 0.25 for a limb; shapeAsOp sa…
ProjectIdris Nov 8, 2026
a85fa4e
The grown stage stops short of taking the last quiet place a note-siz…
ProjectIdris Nov 8, 2026
6d4e669
A pin written at a point inside a solid made of overlapping pieces is…
ProjectIdris Nov 8, 2026
e7644f6
Merge commit 'aeea585' into batch-2
ProjectIdris Nov 8, 2026
d506996
Merge commit 'a85fa4e' into batch-2
ProjectIdris Nov 8, 2026
605269a
Merge commit '6d4e669' into batch-2
ProjectIdris Nov 8, 2026
3ccf69a
Version 0.6.0
ProjectIdris Nov 8, 2026
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
6 changes: 3 additions & 3 deletions docs/overlay.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,11 @@ The camera's near and far clipping planes follow the current visible pieces, inc

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.
A stage a clear is taking away (`panel.leaving`) holds no space against what arrives either (`stageKeepOut`), and does not push the surfaces that arrive where it stood, so a chart that replaces the model is not hidden and the cue not raised while the model fades. 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.
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. Stage growth goes through the placer (`taller`), so cards relocate before admission is needed; a normal answer omits nothing while the stage appears.

### Where tags go

Expand Down Expand Up @@ -100,7 +100,7 @@ Frame grabs can show these states without a pointer: `--steps step:t:az:el:zoom:

## Where things go

A model writes coordinates without seeing the page, so the overlay moves what it would cover (`src/overlay/placement.ts`). From a small gray picture of the screenshot it finds where there is something on the page (an edge, or a tone that is not the page's own background) and, for the 3D stage (a tag beside a small stage is drawn up to 30 per cent smaller so it does not outweigh the model) and for each note card or crop, picks the nearest free rectangle. Explanation first (Alex, 5 November): a stage, card or diagram takes the size and shape it was asked for before it shrinks or narrows to keep off page text, and may sit over text where that reads best; the cost of covering text still picks the quietest place of that size, and it leaves where the model put it only when the move is clearly worth it (`MOVE_WORTH`). Only what the answer points at (boxes, circles, underlines, arrow ends, labels, crop regions) is kept clear: touching it, even by a corner, costs a good deal, and only when no place of its size is clear of it, of the stage or of the cards does a stage go smaller (down to about half) or a diagram smaller and narrower. A card or diagram keeps well off the stage (it counts eight times over), since the model in it is what is being explained. A stage the model asked for small is made larger, up to a width and height of about a third of the screen (`STAGE_BIGGEST`), into blank page first and, when that gives it less than most of what it could have, onto page text too, never over what is pointed at or the cards (`enlarge`). What is covered is weighed by kind (`bodyTextOf`, `FIXTURE_COST`): each cell of ink is body text to some degree from 0 to 1, and covering the rest counts six times as much. A stack of at least four lines that start together, repeat at a steady pitch and mostly run nearly as long as the longest is a column of text however narrow it is (a split pane, a chat, an ultrawide screen); any other ink is weighed by the width of its line, a fixture under 15% of the page, prose from 30%, and a ramp between so a figure does not flip at a cliff, and a run wider than 85% is a bar (a toolbar) and a fixture again. A sidebar or panel of labels of all lengths, an infobox and its picture, and a toolbar are fixtures, so a place of the asked size that avoids a page's controls or figures is preferred to one that covers them, and body text is covered first. A place that is already free stays where the model put it, a move has to be clearly worth it, and a page with nowhere free is left as written. A card's place is free again when it is cleared. The scene's messages wait, up to a second and a half, for the screenshot to be decoded so the first stage is placed on the real page; without a picture of the page nothing moves. The optional `frame` behind the stage is light over a light page and dark over a dark one.
A model writes coordinates without seeing the page, so the overlay moves what it would cover (`src/overlay/placement.ts`). From a small gray picture of the screenshot it finds where there is something on the page (an edge, or a tone that is not the page's own background) and, for the 3D stage (a tag beside a small stage is drawn up to 30 per cent smaller so it does not outweigh the model) and for each note card or crop, picks the nearest free rectangle. Explanation first (Alex, 5 November): a stage, card or diagram takes the size and shape it was asked for before it shrinks or narrows to keep off page text, and may sit over text where that reads best; the cost of covering text still picks the quietest place of that size, and it leaves where the model put it only when the move is clearly worth it (`MOVE_WORTH`). Only what the answer points at (boxes, circles, underlines, arrow ends, labels, crop regions) is kept clear: touching it, even by a corner, costs a good deal, and only when no place of its size is clear of it, of the stage or of the cards does a stage go smaller (down to about half) or a diagram smaller and narrower. A card or diagram keeps well off the stage (it counts eight times over), since the model in it is what is being explained. A stage the model asked for small is made larger, up to a width and height of about a third of the screen (`STAGE_BIGGEST`), into blank page first and, when that gives it less than most of what it could have, onto page text too, never over what is pointed at or the cards (`enlarge`). A stage shorter than a fair share of the screen's height (620 units, about 62 per cent) is then made taller, keeping its width and everything it covered (`taller`): the screen is wider than tall, so a stage as wide as it is tall is a wide slab and a tall or compact model is limited by its height. The added height must lie on page with little on it (at most 15% of its cells inked, at most 10% controls or figures), so a page of text keeps the stage as asked; cards and the page's controls are hard keep-outs, and what the answer points at is a preference (a place that would cover another pointed-at spot is passed over; a spot the stage already covers is left out of the reckoning). It stops short of taking the last quiet place a note-sized card could have (a card about 380 by 150 units must find a place as quiet as it had before, clear of the grown stage, the strip of its buttons below it, the controls and the cards already placed), so on a page with one blank column the stage grows less rather than push the next note onto the page's content. It is done in the placement, so cards written after it keep off the taller stage, and the rectangle the page eases to always holds the one it eased from, so admission does not flip while it eases. What is covered is weighed by kind (`bodyTextOf`, `FIXTURE_COST`): each cell of ink is body text to some degree from 0 to 1, and covering the rest counts six times as much. A stack of at least four lines that start together, repeat at a steady pitch and mostly run nearly as long as the longest is a column of text however narrow it is (a split pane, a chat, an ultrawide screen); any other ink is weighed by the width of its line, a fixture under 15% of the page, prose from 30%, and a ramp between so a figure does not flip at a cliff, and a run wider than 85% is a bar (a toolbar) and a fixture again. A sidebar or panel of labels of all lengths, an infobox and its picture, and a toolbar are fixtures, so a place of the asked size that avoids a page's controls or figures is preferred to one that covers them, and body text is covered first. A place that is already free stays where the model put it, a move has to be clearly worth it, and a page with nowhere free is left as written. A card's place is free again when it is cleared. The scene's messages wait, up to a second and a half, for the screenshot to be decoded so the first stage is placed on the real page; without a picture of the page nothing moves. The optional `frame` behind the stage is light over a light page and dark over a dark one.

A model also points at things inside a picture from a downsized view, so a mark can be a few pixels off what it means (an arrow stopping short of its curve, a ring beside the crossing, a box with an edge through a line of text). `src/overlay/snap.ts` looks at the page's own pixels, at about a thousand cells across: the long edges (lines and curves, found by thinning the edges and keeping those that run a few percent of the screen; letters are shorter), the corners and crossings (where the gradient changes two ways, then placed exactly where the two lines through them meet) and the ink (anything that is not the page's own background). Then an arrow's tip goes to the nearest line, a point goes to the nearest crossing or line, a small ring is centred on the crossing next to it, a polygon's corners go to the page's corners, a trace is laid on the curve it follows, a box takes in an edge that cuts through a line of text or a figure and takes in a loose empty margin (keeping a little air), and an underline drops to just under its line of letters. It never moves a mark far (seven percent of the shorter side at most, and less for most) and it leaves a mark alone wherever it cannot tell what was meant: nothing long enough to land on near it, two lines about equally near, a mark over blank page, a box on a border, a tilted box, a large ring round a figure. It runs before the placement above, once for each action, and says each move in the app log (`talkthrough: snapped arrow demandarrow by 14 units`). What it works out from a page (the busy map, the placement grid, the snapper) is kept for that capture only and dropped when the next screenshot arrives, since one image element holds every capture; it is built as soon as the screenshot has decoded, not at the first mark.

Expand Down
Loading
Loading