@hypen-space/web 0.4.947 → 0.4.949

package/src/canvas/PARITY.md

@@ -1,254 +0,0 @@
-# Canvas Renderer — DOM Parity Gaps
-
-Tracked list of gaps between `CanvasRenderer` and `DOMRenderer` when driven by
-the real WASM engine (the social example is the reference workload).
-
-The renderer currently handles the basic cases its unit tests cover (simple
-column/row flex, flat prop names), but has not been exercised end-to-end
-against engine output. Recent fixes landed the obvious bridging layer —
-applicator-namespaced props, rem/em length parsing, `scrollable`↔`overflow`,
-`aspectRatio` — and an additional batch (Stack overlay, image intrinsic
-aspect, per-axis scroll, hit-test scroll offset, intrinsic-size flex-shrink)
-landed alongside the `tests/canvas-parity.test.ts` fixture suite. The
-remaining items below still block full parity.
-
-## Known gaps
-
-### Text
-
-- **Line wrapping inside flex rows.** Text that wraps across lines in the
-  DOM currently either overflows horizontally or reports the wrong measured
-  height back to Taffy. Columns below it then collapse because subsequent
-  children layout against stale content height.
-- **Measurement before first layout pass.** Text nodes report width based on
-  `ctx.measureText` at the moment the Taffy tree is built; when the Taffy
-  WASM layer initialises async, early frames get the JS-flexbox fallback and
-  measurements can disagree between the two paths.
-
-### Layout
-
-- **`Stack` absolute positioning.** Fixed — Stack now uses Taffy Grid with a
-  single 1×1 cell and every child placed at `gridColumn: 1 / 2; gridRow: 1
-  / 2`, mirroring the DOM `grid-template-areas: "stack"` strategy.
-  `horizontalAlignment` / `verticalAlignment` map to `justifyItems` /
-  `alignItems` so the badge can pin to any corner.
-- **`Image` natural-size fallback.** Fixed — when an Image declares only one
-  of `width`/`height` and its intrinsic size is known (loaded image, or
-  seeded via `setImageNaturalSize` for tests), the other dimension is
-  derived from `naturalWidth / naturalHeight` and pinned explicitly so the
-  flex parent's default `align-items: stretch` can't override it.
-- **Per-axis scroll.** Fixed — `getScrollAxes(node)` returns `{ x, y }` and
-  the wheel/drag/clamp paths in `ScrollManager` honour each axis
-  independently. A horizontal strip with `scrollable: "horizontal"` no
-  longer accumulates Y scroll range from tall children, and the layout
-  builder additionally drops `flex-shrink` to 0 on direct children of a
-  main-axis-scrollable parent so items overflow instead of collapsing.
-- **Scrolled hit-testing / event routing.** Fixed — `getScrollAwareBounds`
-  no longer double-walks the parent chain to add `contentX/Y` (the layout
-  pass already writes absolute coordinates), and only subtracts each
-  scrollable ancestor's scroll offset. `getAbsoluteBounds` simplified to
-  match.
-
-### Painters
-
-- **Button transparent background.** Fixed — explicit backgrounds now win
-  over the default-blue hover swap. Mentioned here as the canary for
-  per-component painters that still assume flat-prop defaults; audit the
-  rest of `paint.ts` against engine output.
-- **Icon sizing inside buttons.** Fixed — intrinsic-sized components (icon,
-  avatar, badge, switch, checkbox, radio, spinner) now default to
-  `flex-shrink: 0`. They keep their default size in tight cross-axis
-  containers instead of collapsing to 0×0.
-- **Border-radius clamping.** Fixed — Tailwind's `rounded-full` lands as
-  `border-radius: 9999px`. Without clamping, `drawRoundedRect`'s arcs
-  wrapped outside the box and a 20×20 blue badge painted as a 470×250
-  rectangle, swamping the Stories row. `drawRoundedRect` and
-  `isPointInRoundedRect` now clamp `radius` to `min(width, height) / 2`.
-
-### Hosting
-
-- **Taffy WASM 404 in the social example.** Fixed in
-  `examples/social/typescript/web_canvas/serve.ts` — the bundled canvas
-  references `taffy_wasm_bg.wasm` at the page origin, so the dev server
-  needs to serve it. Without this route the renderer silently falls back
-  to the JS flexbox path, which drops most of the parity work above.
-
-### Engine prop shape
-
-- **Element type case sensitivity.** Fixed — engine emits types
-  capitalised (`"Text"`, `"Button"`, `"Input"`, …). The Taffy `buildTree`
-  text-leaf check used `node.type === "text"` and missed; every Text
-  became an empty container with size 0×0 and downstream siblings landed
-  on top of each other (the visible symptom: "1,431 likes" overlapped the
-  caption row). The renderer's `clickable`/`focusable` flags had the same
-  bug — Buttons weren't flagged clickable, so cursor barely fired.
-  All per-type checks now lowercase the type before comparing.
-
-### Painters
-
-- **Image circular clipping.** Fixed — `paintImage` clips to the rounded
-  box before drawing, so `rounded-full` avatars actually paint as circles
-  (story rings + post-header avatars). Also added `objectFit: cover`
-  semantics — the source is centered and cropped instead of stretched.
-
-### Scrolling
-
-- **Root inflated by overflowing children.** Fixed — when the root has no
-  explicit width/height, `computeLayoutTaffy` now pins it to the canvas
-  dimensions. Previously a horizontally-scrollable Stories row with 5+
-  w-24 items inflated the entire feed to 607px on a 470px canvas and
-  pushed the BottomNav off-screen.
-- **Scroll containers contribute their min-content to parent layout.**
-  Fixed — scrollable nodes set `style.overflow = Scroll` on the relevant
-  axis. Children still flow at intrinsic positions (so
-  `ScrollManager.updateScrollBounds` sees the correct scrollHeight) but
-  the container itself stops bubbling its min-content sideways.
-
-### Events
-
-- **Cursor flash on hover over Buttons.** Fixed — the hit test returns
-  the deepest visible node, which for a Button-with-Icon is the Icon
-  (not clickable). `events.ts` now lifts the hit to the nearest
-  clickable ancestor for hover/cursor and click/mousedown/mouseup
-  dispatch, so the cursor stays a pointer over the whole Button surface.
-- **Clicks silently dropped after `mouseup`.** Fixed — `onMouseUp`
-  cleared `mouseDownNode = null`, but the browser fires `click` AFTER
-  `mouseup`, and `onClick`'s press+release sameness check then always
-  failed (`null !== <Button>`). The clear is now done in `onClick`.
-
-### Text rendering
-
-- **`View all X comments` wraps to 2 lines.** Fixed — pretext returns a
-  fractional pixel width (e.g. `141.71875` for "View all 87 comments"),
-  Taffy gives the Button exactly that, but at paint time `renderText`
-  re-measures with a maxWidth of the integer-rounded box width and
-  pretext wraps because `141.71 > 141`. The Taffy measure callback now
-  returns `Math.ceil(metrics.width)` so the box reserves the next whole
-  pixel up.
-
-### Components
-
-- **`List` rendered as a row.** Fixed — `List` is the DSL's vertical-
-  iteration container (DOM uses `flex-direction: column`). The canvas
-  buildTaffyStyle now treats `type === "list"` as Column unless the
-  `direction` prop says `"horizontal"`. Notifications stack vertically
-  again.
-- **`Grid(...).gridColumns(N)` rendered as 1 column.** Fixed — the
-  canvas was reading `gridTemplateColumns`/`columns` only, but the
-  engine emits the applicator name (`gridColumns`) on props. Also,
-  `parseGridTemplate(N)` now expands a bare number to N equal `1fr`
-  tracks (matching `dom/applicators/advanced-layout.ts`).
-- **Grid items with `width: "100%"` collapsed track sizing.** Fixed —
-  on a Grid child, `width: "100%"` creates a circular dependency with
-  `1fr` track sizing (the cell wants to be `1fr` of the grid; the item
-  wants to be `100%` of the cell). Children of a Grid container now
-  ignore `width: "100%"` / `height: "100%"` (use `auto`) so Taffy's
-  default grid stretch fills the cell.
-- **Grid items with `aspect-ratio: 1` swallowed siblings.** Fixed —
-  default `min-width: auto` (= min-content) on grid items collapsed
-  tracks. Grid children now default to `min-width: 0; min-height: 0`,
-  the standard CSS workaround.
-
-### Flex defaults
-
-- **`flex: 1` shorthand left basis at `auto`.** Fixed — `flex: 1` in
-  CSS expands to `flex: 1 1 0%`, but the canvas was only reading the
-  grow value. Without the `0%` basis, an overflowing flex item started
-  at its intrinsic content size and Taffy redistributed from there,
-  squeezing the BottomNav off-screen on long routes (the home feed
-  with N posts; the search grid with 100s of items).
-
-### Z-order
-
-- **Absolute-positioned overlays painted under in-flow siblings.**
-  Fixed — Story declares its close-button header BEFORE the full-screen
-  Image; CSS `z-index` puts the header on top, but Canvas paints in
-  tree order, so the Image covered the header (and the Hover/click
-  for the close button hit the Image instead). `paintNode` now paints
-  flow children first, then absolute children on top; `events.ts`
-  hit-tests absolutes first (front-to-back). Story's ✕ navigates
-  back to `/` again.
-
-### Form controls
-
-- **Input / Textarea collapse to padding-only height.** Fixed —
-  `Input`, `Textarea`, and `Select` paint via the `InputOverlay` HTML
-  element, so the canvas layout doesn't see their text content as
-  children. The default fall-through gave them `size.auto`, and Taffy
-  (border-box by default) collapsed the box to padding only — the
-  social Search bar rendered as a 4-tall pill instead of the ~36 the
-  DOM produces, with the `Search` placeholder peeking out of a sliver
-  that looked nothing like the iOS / Android equivalent. Each control
-  now sets `size.height = lineHeight × rows + padding + border` so the
-  outer box matches the DOM, with Textarea defaulting to `rows: 3`.
-
-### Grid auto rows
-
-- **Aspect-ratio image grid collapses to gap-tall rows.** Fixed —
-  Taffy's grid auto-row sizing queries each leaf's max-content height
-  before column widths are resolved. For an Image leaf with no fixed
-  height, max-content = 0, so a `Grid.gridColumns(3)` of `aspect-square`
-  images sized the implicit rows to gap-only and items overlapped by
-  ~150px each (the Search route's explore grid was a single squashed
-  band of every image). `computeLayout` now runs a second Taffy pass
-  when `annotateCollapsedAspectGrids` finds a Grid where the next-row
-  child sits closer than `firstChild.width / aspectRatio` — the second
-  pass reads a private `__autoRowsPx` hint set on the grid (column
-  width / aspectRatio) and pins implicit rows to that height. Two-pass
-  cost is bounded: only fires when an aspect-ratio overflow is observed,
-  not on every layout.
-
-### HiDPI
-
-- **Hit tests offset by `dpr` on Mac retina screens.** Fixed —
-  `events.ts` `getCanvasCoordinates` (and the same helpers in `scroll.ts`
-  / `selection.ts` / `input.ts`) used to multiply client coords by
-  `canvas.width / rect.width`, which equals `devicePixelRatio` because
-  the renderer scales the ctx by dpr at setup. Layout (and therefore
-  the hit-test bounds) live in CSS pixels — multiplying again landed
-  every click at 2× the bounds. Visible symptoms on a Mac (dpr=2):
-  the cursor turned to a pointer ABOVE the actual story avatar instead
-  of on it, and bottom-nav clicks/hovers fell off the bottom of the
-  canvas entirely (y=850 logical → y=1700 canvas-pixel, past the 900
-  canvas height). Drag-scroll deltas and Input/Textarea overlay
-  positioning had the same family of bug. All four now use logical
-  CSS pixels directly.
-
-### Action wire format
-
-- **`@router.push` dispatched verbatim.** Fixed — DOM strips the `@`
-  prefix and the `actions.` namespace before sending to the engine,
-  but the canvas was sending `@router.push` literal. The engine
-  silently dropped it, so every nav click was a no-op. `props.ts`
-  `resolveEventAction` now mirrors `dom/applicators/events.ts`
-  `extractActionDetails`.
-
-### Engine prop shape (continued)
-
-- **Click was always `null !== <Button>`.** Fixed — `onMouseUp`
-  cleared `this.mouseDownNode = null`, but the browser fires `click`
-  AFTER `mouseup`. The `node === mouseDownNode` press+release check
-  in `onClick` always saw `null`. The clear is now done at the end
-  of `onClick` instead.
-
-## Not yet assessed
-
-- Input / Textarea focus + caret positioning against the InputOverlay DOM
-  inputs.
-- Select / Switch / Slider under engine-driven props.
-- Router attach/detach patches (subtree caching) — the canvas renderer
-  implements `detach` / `attach` but hasn't been tested against the
-  ManagedRouter persist-cache path.
-
-## How to make progress
-
-The shape of each of these is the same: write a small fixture in
-`tests/canvas-*.test.ts` that reproduces the engine-output shape (use the
-patches captured in `ws://localhost:3000` as the input), assert the expected
-layout / paint output, then fix the canvas code until the test passes. The
-screenshot-driven loop we've been in is too expensive; the real investment
-is in fixture tests that pin behaviour.
-
-The social example under `examples/social/typescript/web_canvas/` is the
-end-to-end integration check, not a regression target — carry a visible
-"partial" banner until parity is reached.