xbintsc 0.5.51 → 0.5.52

package/doc/gui/animation.md

@@ -30,21 +30,27 @@ running transition is recorded and re-applied every frame until it finishes;
 the engine advances the clock with real frame deltas (`XtDocument::advance`),
 and `win.advance(ms)` lets tests step it deterministically.
 
-- Supported properties: `background-color`, `color`, `border-color`,
-  `border-radius` and `transform`; `transition: all` covers them. A
-  layout-affecting property (width, position, …) is still not animated — that
-  would reflow every frame — but `transform` is paint-time, so animating it costs
-  one matrix per animated box per frame ([Layout](./layout.md#transforms-m15)).
+- Supported properties: `background-color`, `color`, `border-color`, `opacity`,
+  `border-radius`, `transform`, `text-shadow`, `box-shadow`, every box offset
+  and size length (`width`/`height`/`top`/`left`/`margin-*`/`padding-*`/…), the
+  gap/flex-basis lengths and `filter` (matching filter lists interpolate their
+  blur lengths, amounts and drop-shadow colours). `transition: all` covers the
+  whole list. Lengths
+  interpolate when their units line up (a mixed-unit change is CSS's discrete
+  fallback); `opacity`, colours and `transform` interpolate normally.
 - Both the `transition` shorthand and the `transition-property` / `-duration` /
   `-delay` / `-timing-function` longhands are parsed; time values accept `s` and
-  `ms`; timing functions are `linear`, `ease`, `ease-in`, `ease-out` and
-  `ease-in-out` (`ease` is a smoothstep approximation).
+  `ms`; `calc()` is accepted inside the shorthand and longhands.
+- Timing functions are `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
+  `cubic-bezier(x1, y1, x2, y2)`, `steps(n, start|end)` and their `jump-*`
+  spellings. The engine solves the cubic Bézier numerically; keyword curves use
+  the CSS control points.
 - Retargeting mid-flight starts a new transition from the current interpolated
   value, so reversing a hover animates smoothly from wherever it was.
 - `computedStyle()` reports the displayed (interpolated) value, so transitions
   are directly observable in tests.
 
-`transform` lists interpolate **element-wise** (`document.cpp`,
+`transform` lists interpolate **element-wise** (`animation_values.cpp`,
 `xt_transform_interpolate`), which is what makes the common pair
 `translateY(-4px) rotate(-0.35deg)` <-> `none` glide instead of jumping: the
 missing side is filled with identity ops of the same kind. Two lists whose shapes
@@ -52,6 +58,29 @@ or units do not line up (`rotate(10deg)` vs `rotate(10rad)`, or a different numb
 of functions) are not interpolated at all — the transition snaps to the target,
 which is CSS's discrete fallback rather than a wrong-looking sweep.
 
+## CSS animations (`@keyframes`)
+
+`@keyframes` rules are parsed into `StyleSheet::keyframes` (offsets from
+`from`/`to`/percent selectors, sorted). `animation` and every `animation-*`
+longhand are supported: name, duration, delay, timing function, iteration count
+(including `infinite`), direction (`normal`/`reverse`/`alternate`/
+`alternate-reverse`), fill mode (`none`/`forwards`/`backwards`/`both`) and
+`paused`/`running`.
+
+`XtDocument` starts one active animation per element/name when the computed
+style first declares it, restarts it when the shorthand changes, and leaves it
+alone across unrelated restyles. Each frame it resolves the local time to an
+iteration progress, applies the timing function **per keyframe interval**, and
+interpolates every animatable property. A property that a middle keyframe does
+not mention keeps interpolating between the nearest keyframes that do declare
+it (so a transform declared at 0% and 100% runs straight through a 50% step that
+only changes `opacity`). Missing 0%/100% steps use the element's underlying
+style. `forwards`/`backwards` hold the edge value outside the active time, and
+`computedStyle()` reports the animated value.
+
+Animations and transitions share `animation_values.cpp`, so both understand the
+same property set, shadow lists and `transform` identity filling.
+
 ## CSS transforms (M15)
 
 `transform` and `transform-origin` are supported as *paint-time* effects
@@ -93,5 +122,6 @@ Both are exercised by `examples/gui/pelican-svg` (per-frame sway plus a
 hover transition on the caption) and pinned by
 `tests/e2e/gui-transform.test.ts`.
 
-Still to do for animation: `@keyframes` animations and `cubic-bezier(...)`.
+`calc()` can be used in any animated length (for example
+`transition: width 300ms ease-out; width: calc(100% - 20px)`).
 

package/doc/gui/build.md

@@ -131,7 +131,7 @@ features** selected per program:
 | `media` | `media_bridge.c` + `media.a` (FFmpeg) | an HTML `<video>`/`<audio>` tag, `createElement("video"/"audio")`, `new Audio()`, `decodeAudioData`, or runtime-built markup |
 | `gpu` | `gpu_bridge.c` (the implementation is already in `gui.a`) | a `getContext("webgl"/"webgl2"/"experimental-webgl")` (or a kind decided at run time), any `webgl` string, `mix-blend-mode`/`mixBlendMode`, or runtime-built markup |
 | `images` | `image_bridge.c` (the implementation is already in `gui.a`) | `<img>`, inline `<svg>`, `background-image`/`url(...)`, a `.svg` path, `drawImage`/`createImageBitmap`/`Image`, or runtime-built markup |
-| `shaping` | `text_bridge.c` (the implementation is already in `gui.a`) | non-ASCII text (CJK/Cyrillic/Greek/…), an escaped/entity codepoint, or runtime-built markup |
+| `shaping` | `text_bridge.c` (the implementation is already in `gui.a`) | non-ASCII text (CJK/Cyrillic/Greek/…), an escaped/entity codepoint, an author `@font-face` rule (custom fonts may be CFF/OTF), or runtime-built markup |
 | `webgl` | `webgl_bridge.c` (the implementation is already in `gui.a`; requires `gpu`) | a WebGL `getContext(...)`, a `webgl` string, or runtime-built markup |
 
 The driver scans the bundled AST (`src/driver/usage.ts`): every string literal
@@ -206,10 +206,11 @@ TrueType outlines and a per-codepoint mapping plus the font's `kern` table, so
 CFF/OTF and variable fonts, OpenType ligatures and complex-script shaping
 (Arabic/Indic/Thai) are not available. The fallback chain still selects another
 face for codepoints the primary lacks. Selecting the optional **`shaping`**
-feature (automatically for non-ASCII text, or with `--feature shaping`) links
-HarfBuzz + FreeType back in (~1.2 MiB) and restores full OpenType shaping and
-CFF/OTF/variable-font support. A Latin-only DOM page therefore stays near
-3.1 MiB; a Chinese/complex-script page is closer to 4.3 MiB.
+feature (automatically for non-ASCII text or an author `@font-face` rule, or
+with `--feature shaping`) links HarfBuzz + FreeType back in (~1.2 MiB) and
+restores full OpenType shaping and CFF/OTF/variable-font support. A Latin-only
+DOM page therefore stays near 3.1 MiB; a Chinese/complex-script page is closer
+to 4.3 MiB.
 
 ## Running the example
 

package/doc/gui/dom.md

@@ -21,11 +21,26 @@ commas, brackets or parentheses without splitting the list. Selectors: type,
 `.class`, `#id`, attribute (`=`, `~=`, `|=`, `^=`, `$=`, `*=`), the four
 combinators (descendant, child, adjacent and general sibling), the pseudo-classes
 `:first-child`, `:last-child`, `:only-child`, `:empty`, `:root`, `:not(...)`,
-`:nth-child(an+b)`, `:disabled`, `:checked`, plus the stateful `:hover` and
-`:focus` (see [Input](./input.md)), and the pseudo-elements `::before`/`::after`
+`:nth-child(an+b)`, `:disabled`, `:checked`, plus the stateful `:hover`,
+`:focus`, `:focus-visible` (currently an alias of `:focus`) and `:active` (see
+[Input](./input.md)), and the pseudo-elements `::before`/`::after`
 (legacy `:before`/`:after` too). Values: lengths (`px`, `%`, `em`, `rem`, `vw`,
 `vh`, `pt`, `pc`, `in`, `cm`, `mm`, `q`), colors (hex, `rgb()`/`rgba()`, a named
-subset), numbers, keywords and shorthands (`margin`/`padding`/`border`/`flex`).
+subset), numbers, keywords and shorthands (`margin`/`padding`/`border`/`flex`/
+`font`/`outline`). `display: inline-flex`/`inline-grid` make a flex/grid
+container inline-level; `grid-area`, `aspect-ratio`, `letter-spacing`,
+`text-transform`, `writing-mode` (`vertical-rl`/`vertical-lr` text),
+`vertical-align` (length form), percentage `border-radius`, `background-size`
+(size + default repeat for `url()` layers) and `currentColor` are parsed too.
+`font-variant-numeric`, `text-wrap`, `text-rendering`, `touch-action`,
+`user-select`, `overscroll-behavior`, `scroll-behavior`, `isolation` and
+`vector-effect` are accepted but have no engine behaviour (the text stack exposes no OpenType features and the engine
+has no touch/selection/smooth-scroll subsystem); `cursor` maps to the SDL system
+cursor. A document rule may style SVG children with the presentation properties
+`fill`, `fill-opacity`, `fill-rule`, `stroke`, `stroke-opacity`, `stroke-width`,
+`stroke-dasharray`, `stroke-dashoffset`, `stroke-linecap` and `stroke-linejoin`;
+the serializer writes them into the inline `<svg>` markup as NanoSVG-readable
+inline styles. `skewX()`/`skewY()`/`skew()` transform functions are supported.
 `transform` (`translate`/`translate3d`/`translateX`/`translateY`, `scale`/
 `scale3d`/`scaleX`/`scaleY`, `rotate`/`rotateZ`, `matrix`; the `3d` spellings'
 `z` argument is dropped) and `transform-origin` are parsed into the computed
@@ -33,7 +48,8 @@ style as a list of operations plus two (unresolved) origin lengths; an
 unsupported function invalidates the whole declaration
 ([Layout](./layout.md#transforms-m15)). M19 adds `background-image` layer lists
 (linear/radial), `clip-path` (`inset`/`circle`/`ellipse`/`polygon`), the
-`filter`/`backdrop-filter` function lists, `text-shadow` and `content`.
+`filter`/`backdrop-filter` function lists, `text-shadow`, `box-shadow` and
+`content`.
 
 **Cascade & computed style** (`runtime/ext_gui/style.{h,cpp}`): a small built-in
 UA stylesheet, author rules sorted by `(!important, specificity, source order)`,

package/doc/gui/known-issues.md

@@ -64,29 +64,37 @@
   *class change* on a flex container has also been observed to crash the same
   way; `examples/gui/pelican-bike` reveals its game-over overlay with `opacity`
   instead.
-- **CSS coverage is a deliberate subset.** Grid, `clamp()`/`min()`/`max()`/`env()`,
-  `var()` custom properties, the `inset` shorthand, `box-sizing`, `visibility` and
-  `pointer-events`, `@media` queries, generated content (`::before`/`::after`),
-  multi-layer linear/radial backgrounds, `text-shadow`, `clip-path`
-  (`inset`/`circle`/`ellipse`/`polygon`) and `filter` colour functions are
-  implemented. Known limits: `background-clip`,
-  `background-position`/`size`/`repeat` and `backdrop-filter` compositing are not
-  implemented (`backdrop-filter` parses and cascades, but sampling the backdrop
-  needs an offscreen layer, so it paints nothing); `mix-blend-mode` and repeating
-  gradients are implemented (see [Rendering](./rendering.md)), but group
-  `opacity` is a per-shape alpha rather than a true group composite, and the
-  blend compositor is unavailable on the D3D12/DXIL backend, where groups fall
-  back to normal source-over painting;
-  `filter: blur()` is a nine-tap per-shape spread rather than a true group blur,
-  so overlapping descendants can darken; `drop-shadow` is approximated from box
-  silhouettes; at most two nested `clip-path` shapes are intersected (deeper
-  nesting keeps the outer two); and images/canvases are not colour-filtered
-  except for the brightness/opacity tint the image shader can carry. Canvas
-  textures are sampled nearest-neighbour. A background linear gradient remains
-  solid bands (18 strips, 64 while repeating), so a large soft ramp may show
-  slight banding; a radial gradient is rasterised per pixel into a texture
-  (capped at 1024 px per edge, then stretched, so a hard stop in a very large
-  box comes out slightly soft).
+- **CSS coverage is a deliberate subset.** Grid, `calc()` (including
+  nested arithmetic and `calc()` inside `min()`/`max()`/`clamp()`),
+  `clamp()`/`min()`/`max()`/`env()`, `var()` custom properties, the `inset`
+  shorthand, `box-sizing`, `visibility` and `pointer-events`, `@media` queries,
+  generated content (`::before`/`::after`), multi-layer linear/radial
+  backgrounds, `text-shadow` (true Gaussian), `box-shadow` (outer/inset, spread,
+  multiple layers), `clip-path` (`inset`/`circle`/`ellipse`/`polygon`),
+  `filter` colour functions, `@keyframes` animations, the full `transition`
+  timing-function set, `letter-spacing`, `text-transform`, inline-level
+  `flex`/`grid`, `grid-area`, `aspect-ratio`, auto margins, percentage
+  `border-radius`, `outline`, `background-size` tiling for `url()` layers and
+  document CSS on SVG children (`fill`/`stroke`/…) are implemented. Known
+  limits: `background-clip`, `background-position` and `background-repeat`
+  remain unimplemented (`background-size` covers the tiled default);
+  `font-variant-numeric`, `text-wrap`, `text-rendering`, `touch-action`,
+  `user-select`, `overscroll-behavior`, `scroll-behavior`, `isolation` and
+  `vector-effect` are parsed but inert; vertical writing mode is text-only (nested/mixed content falls back to
+  horizontal); group `opacity` is
+  a per-shape alpha rather than a true group composite; the blend and
+  `backdrop-filter` compositors are unavailable on the D3D12/DXIL backend, where
+  groups fall back to normal source-over painting and the backdrop filter is
+  skipped. `filter: blur()` is still a nine-tap per-shape spread rather than a
+  true group blur, so overlapping descendants can darken; `drop-shadow` is
+  approximated from box silhouettes; at most two nested `clip-path` shapes are
+  intersected (deeper nesting keeps the outer two); and images/canvases are not
+  colour-filtered except for the brightness/opacity tint the image shader can
+  carry. Canvas textures are sampled nearest-neighbour. Background gradients
+  (linear and radial) are rasterised per pixel into a texture and then stretched
+  when the box is larger than the texture (1024 px per edge for a radial ramp,
+  4096 px along the line for a linear one, which is only one texel thick across
+  it), so a hard stop in a very large box can come out slightly soft.
 - **SVG is NanoSVG's subset.** SVG *files* (`<img src="logo.svg">`) and inline
   `<svg>` trees share the vendored NanoSVG parser/rasteriser
   (`runtime/ext_gui/svg.cpp`, `inline_svg.cpp`), which renders

package/doc/gui/layout.md

@@ -25,7 +25,10 @@ with absolute (viewport-relative) geometry:
   measured with the stb_truetype stack (see [Text stack](./rendering.md#text-stack-m4b)).
 - **Flexbox** — `row`/`column` (and the `-reverse` variants) with `gap`,
   `flex-basis`/`flex-grow`/`flex-shrink`, `justify-content` and `align-items`
-  (including `stretch` when the cross size is definite). `flex-wrap: wrap`
+  (including `stretch` when the cross size is definite). On both axes the main
+  size comes from `flex-basis` (or the measured size when it is `auto`), positive
+  free space is split by `flex-grow` and a deficit by `flex-shrink`, and an
+  item's `align-self` overrides the container's `align-items`. `flex-wrap: wrap`
   breaks items into several lines, `align-content`
   (`stretch`/`flex-start`/`flex-end`/`center`/`space-between`/`space-around`)
   distributes the lines on the cross axis and `wrap-reverse` flips that axis.
@@ -37,14 +40,34 @@ with absolute (viewport-relative) geometry:
   `row-gap` / `column-gap`, row-major auto-placement, simple `grid-column` /
   `grid-row` line placement, and `align/justify-items` plus
   `align/justify-self` (including `place-items` / `place-self`). Implicit rows
-  and columns grow from the items; a single-cell grid with `place-items: center` centres a card in the whole overlay. Item measurement is a two-pass
+  and columns grow from the items; a definite grid height is shared across `fr`
+  rows after the fixed and auto rows are sized, so `aspect-ratio` can drive a
+  `repeat(n, 1fr)` grid. A single-cell grid with `place-items: center` centres a
+  card in the whole overlay. Item measurement is a two-pass
   layout (intrinsic size, then final placement), so text fragments are cleared
   between passes.
-- **CSS value functions and custom properties** — `clamp(min, value, max)`,
-  `min(...)` and `max(...)` keep their arguments unresolved in the computed style
-  and are evaluated at layout time against the element's font size and the
-  viewport (`vw`/`vh`); `env(safe-area-inset-*)` resolves to zero in a desktop
-  window. `var(--name[, fallback])` is substituted from inherited custom
+- **Inline-level containers, auto margins and aspect ratio** — `display:
+  inline-flex`/`inline-grid` lay their children out with the flex/grid algorithm
+  but participate in the parent line as one atomic inline box (`vertical-align`
+  shifts it by its length value). A block-level box with `margin-left: auto` /
+  `margin-right: auto` absorbs the leftover inline space (both auto → centred);
+  a flex item's auto main-axis margins absorb the line's free space before
+  `justify-content`, which is what pushes a footer or button hint to the end.
+  `aspect-ratio` derives a `height: auto` box from its used width (the
+  width-from-height direction is not implemented). `border-radius` accepts a
+  percentage and resolves against the smaller border-box side.
+- **Vertical writing mode** — `writing-mode: vertical-rl|vertical-lr` lays text
+  out one character per column step: CJK/kana/Hangul glyphs stay upright and
+  other scripts are rotated 90° at paint time. A definite height starts a new
+  column; a flex container's row/column axes swap with the writing mode. This is
+  a text-focused implementation: nested blocks and mixed horizontal content in a
+  vertical container still fall back to horizontal layout.
+- **CSS value functions and custom properties** — `calc()` arithmetic (including
+  nested `calc()` and `calc()` inside the other functions), `clamp(min, value,
+  max)`, `min(...)` and `max(...)` keep their expression unresolved in the
+  computed style and are evaluated at layout time against the element's font
+  size and the viewport (`vw`/`vh`); `env(safe-area-inset-*)` resolves to zero in
+  a desktop window. `var(--name[, fallback])` is substituted from inherited custom
   properties during the cascade. `inset` is the four-value
   `top/right/bottom/left` shorthand, `box-sizing: border-box` subtracts padding
   and borders from an explicit width/height, `visibility: hidden` skips painting

package/doc/gui/rendering.md

@@ -76,17 +76,27 @@ divided back into logical units, exactly the way HiDPI scaling already worked.
 
 The window background (`setBackground`) is the render-pass clear colour.
 
+`background-size` on a `url()` layer emits one image quad per tile (default
+`repeat`, 4096-tile cap) instead of stretching the picture to the box;
+percentage sizes resolve against the box, `auto` keeps the box dimension.
+`outline` paints four edge rectangles outside the border box (offset included)
+after the border and before the content. A vertical-writing-mode text run is
+painted by rotating its glyph quads 90° (CJK glyphs stay upright and are centred
+in their column).
+
 ### Backgrounds, generated content and effects (M19)
 
 `background-color` and every `background-image` layer are painted. A
 comma-separated layer list is painted bottom-up (the first declaration layer is
 topmost), and both gradient kinds are supported:
 
-- a **linear** gradient is sampled at 18 points (64 when repeating) and emitted
-  as solid rectangles; `to <side>`, `deg`/`grad`/`rad`/`turn`, percentage or
-  length (`px`/`em`/…) offsets, the `color <start> <end>` shorthand and
-  multi-stop colours work (the band walk is axis-aligned, so an oblique angle
-  uses the nearest axis);
+- a **linear** gradient follows the CSS gradient line (through the box centre,
+  at the declared angle, with the box extent projected onto it as its length, so
+  `%` and `%`-inside-`calc()` offsets resolve against that length) and is
+  resolved per pixel like a radial one. The ramp only varies along the line, so
+  the texture is one row (or one column) of device pixels. `to <side>`,
+  `deg`/`grad`/`rad`/`turn`, percentage or length (`px`/`em`/…) offsets, the
+  `color <start> <end>` shorthand and multi-stop colours work;
 - a **radial** gradient is resolved per pixel in `renderer_gradient.cpp` into one
   RGBA texture that is drawn as a single image quad (`PaintGradient`). Nesting the
   bands instead would composite their alpha once per band — since every band
@@ -98,6 +108,14 @@ topmost), and both gradient kinds are supported:
   the side or corner, as CSS does. Stops interpolate in premultiplied alpha, and
   the last stop extends past the ending shape over the rest of the box.
 
+Both kinds share that per-pixel path: a walk of solid rectangles composites a
+translucent stop once per band and cannot place a stop narrower than a band, so a
+`transparent … calc(100% - 1px), rgba(…) calc(100% - 1px)` divider line either
+fell between two samples (and vanished) or widened into a full band. A stop
+position given as `calc()` keeps its percentage relative to the gradient line,
+and a stop whose resolved offset is negative stays where the declaration put it
+instead of being treated as "no offset declared".
+
 `repeating-linear-gradient()` and `repeating-radial-gradient()` tile the stop
 pattern from 0 to the last stop's offset across the whole box; the stop list is
 not forced to end at 100%, so `red 0%, blue 10%` repeats every 10%. A normal
@@ -105,18 +123,34 @@ gradient whose last stop is below 100% holds that colour for the rest of the box
 as in CSS.
 
 The background colour sits under every layer. Gradients are partially
-transparent if their stops are; a radial gradient is exact per pixel, while a
-linear one still samples 18 bands and can show banding on a large soft ramp.
+transparent if their stops are; both kinds are exact per pixel, so hard stops and
+1px details stay hard instead of banding.
 
 **Generated content** needs no new display-list kind: `::before`/`::after` are
 ordinary layout boxes owned by the per-restyle arena in `style.cpp`, so their
 background, border, text and transforms flow through the same paint walk.
 `content` is resolved from strings, `attr()` and open/close quotes.
 
-**`text-shadow`** is emitted as shadow `PaintText` runs *before* the real run, so
-the text pipeline draws them without a new shader. A blurred shadow is nine
-translucent copies spread around the offset (the same approximation `filter:
-blur()` uses).
+**`text-shadow`** with no blur is emitted as shadow `PaintText` runs *before* the
+real run, so the text pipeline draws it crisply. A blurred shadow is a real
+Gaussian: `paint_shadow.cpp` rasterises the glyph coverage, convolves it with a
+separable kernel (`sigma = blur / 2`, cropped at ±3σ), and emits one tinted image
+quad. The mask is cached by text/font/blur, so an animated colour only changes
+the quad's tint.
+
+**`box-shadow`** uses the same Gaussian mask: the rounded-rectangle silhouette is
+rasterised (spread expands or shrinks it), convolved, and composited behind the
+background; `inset` shadows invert the mask, crop it to the padding box and paint
+above the background. A zero-blur outer shadow stays an exact rounded rect. The
+declaration list is painted last-layer-first, matching CSS.
+
+**`backdrop-filter`** is composited by the same offscreen machinery as
+`mix-blend-mode`: when the painter reaches the box, the renderer copies the
+scene painted so far into a scratch texture, applies the Gaussian and one
+combined colour matrix (brightness/contrast/grayscale/sepia/invert/saturate/
+hue-rotate/opacity multiplied together) in a full-screen shader, and composites
+the result back through the box's rounded border-box mask. A `backdrop-filter`
+therefore shows as a `backdrop …` op in `paintList()`.
 
 **`clip-path`** is resolved in `paint_clip.cpp` to a device-space polygon (the
 box transform is applied to every point), triangulated with ear clipping, and
@@ -133,8 +167,8 @@ colour, so a box and its descendants see the filter. `blur()` and
 `drop-shadow()` are approximations at the display-list level: blur spreads nine
 translucent copies per shape, drop-shadow is a box/text silhouette. This keeps
 the ordinary painter single-pass at the cost of group semantics: overlapping
-descendants of a blurred/filtered group can darken, and `backdrop-filter` cannot
-sample what is behind the element, so it parses and cascades but paints nothing.
+descendants of a blurred/filtered group can darken. `backdrop-filter` is the
+exception — it has its own offscreen snapshot/filter pass (see above).
 
 **`mix-blend-mode`** is the exception that does need an offscreen layer. A box
 with a non-`normal` mode is wrapped in `LayerBegin`/`LayerEnd` markers (visible
@@ -149,7 +183,8 @@ SPIRV-Cross (Metal); the two scene textures per nesting level are reused across
 frames and ping-pong so the backdrop stays sampleable while it is written.
 Backends that consume neither format — the D3D12/DXIL path, which has no shader
 compiler here — keep painting the group with ordinary source-over blending.
-`backdrop-filter` still paints nothing.
+`backdrop-filter` uses the same runtime-compiled path; when the shader backend is
+unavailable it is skipped while the rest of the page still paints.
 
 ## Text stack (M4b)
 
@@ -157,22 +192,43 @@ compiler here — keep painting the group with ordinary source-over blending.
 backend table. The default backend is the bundled **stb_truetype**
 (`text_stb.cpp`, `runtime/ext_gui/stb_truetype.h`). The optional **`shaping`**
 link feature installs `text_hb.cpp`, a HarfBuzz + FreeType backend, and is
-selected automatically for non-ASCII text.
+selected automatically for non-ASCII text or an author `@font-face` rule. Both
+backends share the font database in `text_font_db.cpp` (discovery and indexing)
+and the CSS matcher in `text_fonts.cpp`, plus the sfnt metadata reader in
+`text_font_sfnt.cpp`, so a CSS style resolves to the same real face whichever
+shaper is linked.
 
-- Fonts are resolved from well-known system paths (Helvetica/Arial on macOS,
-  DejaVu/Liberation on Linux, Segoe UI/Arial on Windows), overridable with
-  `XT_GUI_FONT` (and `XT_GUI_FONT_MONO`), and cached per `(family class, size)`.
-  Only regular upright faces are used for now; weight/italic selection is a
-  later refinement.
+- Fonts are resolved from the installed system faces. The `font-family` list is
+  matched case-insensitively; `sans-serif`, `serif`, `monospace` (and the
+  `system-ui`/`ui-*` aliases) map to platform defaults, while any other family
+  name discovers the platform font directories once. `font-weight` (1–1000) and
+  `font-style: italic` select that family's real bold/italic face using the CSS
+  Fonts weight-matching order; a missing weight picks the nearest face and a
+  family without an italic face uses its upright face — there is no synthetic
+  bold or oblique. Faces are cached per `(file, collection index, size)`.
+  `XT_GUI_FONT` / `XT_GUI_FONT_MONO` still override the generic defaults.
+- Author **`@font-face`** rules load local sfnt faces (`.ttf`, `.ttc`, `.otf`,
+  `.otc`). The `src` list is tried from left to right; `local(...)`, remote and
+  `data:` entries are skipped. A relative URL is a local `file:` path resolved
+  against the process working directory — the same policy as image sources — and
+  `file://` URLs (including percent-encoded paths) are accepted. The
+  `font-weight`/`font-style` descriptors select the face; a weight range
+  (`font-weight: 100 900`) is honoured, and later rules with the same family and
+  descriptors replace earlier ones. CSS matches the declared family name even
+  when it differs from the font file's internal name. When no source is
+  readable the family simply falls through to the next family in the CSS list.
 - The default candidates prefer a **CJK-capable TrueType/TTC** face (Microsoft
   YaHei on Windows, PingFang/STHeiti on macOS, Noto Sans CJK/WenQuanYi on Linux)
-  before the Latin-only ones. A candidate that stb_truetype cannot parse (for
-  example a CFF/OTF collection) is skipped in favour of the next one.
+  before the Latin-only ones. A family's weight/style variants are resolved
+  across its files, and a candidate stb_truetype cannot parse (for example a
+  CFF/OTF collection) is skipped in favour of the next one; the `shaping`
+  backend loads it instead.
 - **Codepoints the primary face lacks fall back to another face.** The engine
   keeps a small fallback chain — the platform's symbol face (Segoe UI Symbol,
-  Apple Symbols, Noto Sans Symbols, DejaVu Sans) first, then the other family
-  class — and resolves each codepoint to the first face in it that has the
-  glyph. The run is shaped in segments, one per face, so a mixed run (Latin
+  Apple Symbols, Noto Sans Symbols, DejaVu Sans) first, then the default sans,
+  serif and monospace faces — and resolves each codepoint to the first face in
+  it that has the glyph. The run is shaped in segments, one per face, so a mixed
+  run (Latin
   plus an arrow, box-drawing or geometric shape, or Latin inside CJK) draws
   every glyph instead of dropping the missing ones as `.notdef`. Each shaped
   glyph carries its face (`ShapedGlyph::font`) so the renderer rasterises it
@@ -219,7 +275,9 @@ is what `tests/e2e/gui-perf.test.ts` asserts on.
   glyphs / 8,192 entries; when a generation is full the *spare* one is dropped
   and becomes current, so the hot path has no LRU bookkeeping. A word is shaped
   once and reused by every later layout pass and repaint that draws it. Primary
-  face lookups are cached by (family class, size) as well.
+  face lookups are cached by (family, weight, style, size) as well; the font
+  database itself scans the platform directories only once, on the first
+  non-generic family request.
 - **No-op writes.** `textContent` and `style.<property>` do nothing when the
   node already shows that value: the document is not dirtied, so no restyle,
   relayout, repaint or upload follows. A HUD that assigns the same clock string,

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M20** — features (M1–M15) are complete: HTML parsing, CSS selector
+Status: **M22** — features (M1–M15) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
@@ -44,13 +44,17 @@ them) can be translated, scaled and rotated without reflowing anything — and
 **M19** fills in the decorative CSS layer: `@media` queries, generated content
 (`::before`/`::after`), multi-layer linear/radial/repeating backgrounds,
 `text-shadow`, `clip-path`, `mix-blend-mode` (through an offscreen compositor)
-and the `filter` colour/shadow effects. `backdrop-filter` still needs a backdrop
-snapshot, and true group blur remains an approximation — see
+and the `filter` colour effects. See
 [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 **M20** makes large documents interactive: `@media` is evaluated once per rule,
 layout and paint share a bounded shaping cache, and a frame only does (and
 presents) the work a change requires — see
 [Performance](./gui/rendering.md#performance-m20).
+**M21** completes the value/animation gaps: `calc()` arithmetic everywhere a
+length is accepted, true Gaussian `text-shadow`/`box-shadow`, backdrop
+compositing, `@keyframes` and the full transition timing-function set. See
+[Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19)
+and [Animation](./gui/animation.md#css-animations-keyframes).
 This overview records the locked decisions, the architecture, the milestone plan
 and the current progress; the engine itself is documented by function in the
 pages above.
@@ -179,8 +183,10 @@ engine were Rust.
      rounded-rect SDL_GPU pipeline (`paint.*`, `renderer.*`).
    - **M4b-1 — text stack + metrics** ✅ the text module (`text.*`) with font
      resolution/caching and shaping-based metrics used by layout
-     (`measureText`/`fontMetrics`); originally HarfBuzz + FreeType, now the
-     bundled stb_truetype.
+     (`measureText`/`fontMetrics`); the CSS family list, weight and italic style
+     select real installed faces, and author `@font-face` rules load local font
+     files (relative URLs resolve as `file:` paths against the process working
+     directory). Originally HarfBuzz + FreeType, now the bundled stb_truetype.
    - **M4b-2 — glyph rendering** ✅ stb_truetype rasterisation, a shared shelf-packed
      glyph atlas, textured text quads in the display list and HiDPI-aware raster
      scaling. Gradients remain.
@@ -195,8 +201,8 @@ engine were Rust.
      per-file GPU textures and textured quads (`image.*`, `svg.*`, `paint.*`,
      `renderer.*`).
    - **M6b — transitions/animations** ✅ `transition` shorthand + longhands,
-     animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
-     and `win.advance(ms)`. `@keyframes` remain.
+     retargeting, `cubic-bezier()`/`steps()`, `win.advance(ms)` and (M21)
+     `@keyframes` with every animation longhand.
 7. **M7 — CI & releases** ✅ (Linux/macOS/Windows x64 build) / 🚧 (run + Windows arm64)
    - `compile-examples` builds `gui.a` and `media.a` on Linux and macOS
      (required), then runs the examples and `tests/e2e/gui-*.test.ts` under
@@ -348,16 +354,18 @@ engine were Rust.
     - Generated content: `::before`/`::after` selectors, inherited pseudo styles,
       `content` strings/escapes/`attr()`, and synthetic layout boxes that never
       leak into DOM traversal.
-    - Multi-layer `background-image` with linear gradients painted bottom-up as
-      solid bands (18 strips) and radial gradients rasterised per pixel into one
-      image texture (`renderer_gradient.cpp`).
-    - `text-shadow` as shadow text runs, including a nine-tap blur approximate.
+    - Multi-layer `background-image` with linear and radial gradients rasterised
+      per pixel into one image texture (`renderer_gradient.cpp`), so hard stops
+      and sub-pixel details (a 1px divider) are exact.
+    - `text-shadow` and `box-shadow` (outer/inset, spread, multiple layers),
+      blurred with a true separable Gaussian over the shape mask (M21).
     - `clip-path` polygons (`inset`/`circle`/`ellipse`/`polygon`) resolved to
       device space, ear-clipped and intersected with shape geometry in
       `renderer_clip.cpp` — no stencil/shader change.
     - `filter` colour functions, nine-tap `blur()` and silhouette
-      `drop-shadow()`; `backdrop-filter` parses and cascades but needs an
-      offscreen backdrop pass (see [Known issues](./gui/known-issues.md)).
+      `drop-shadow()`; `backdrop-filter` snapshots the scene, applies a Gaussian
+      and one combined colour matrix, and composites through the border-box mask
+      (M21).
     - E2E coverage in `tests/e2e/gui-effects.test.ts`; see
       [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
 20. **M20 — rendering performance** ✅
@@ -372,6 +380,28 @@ engine were Rust.
       dirty frame, and redundant render-state binds removed.
     - `win.stats()`/`XT_GUI_PERF` counters and `tests/e2e/gui-perf.test.ts`; see
       [Performance](./gui/rendering.md#performance-m20).
+21. **M21 — CSS value/animation completeness** ✅
+    - `calc()` is parsed as an unresolved expression tree and resolved by both
+      layout (`toPx`) and paint; nested arithmetic, `calc()` inside
+      `min`/`max`/`clamp`, and calc in shadows/transforms/filters are covered.
+    - `box-shadow` (outer/inset, spread, multiple layers) and blurred
+      `text-shadow` are rasterised into a Gaussian mask, cached and composited
+      as one tinted image quad.
+    - `backdrop-filter` snapshots the painted scene and composites a Gaussian +
+      colour matrix through the border-box mask in a runtime-compiled shader.
+    - `@keyframes` plus every `animation-*` longhand (delay, iterations,
+      direction, fill mode, paused/running) share the property interpolator with
+      transitions; transitions now cover opacity, layout lengths, box shadows
+      and `cubic-bezier()`/`steps()`/`step-start`/`step-end`.
+    - E2E: `tests/e2e/gui-css-features.test.ts`.
+22. **M22 — CSS coverage for the boxing UI** ✅
+    - `letter-spacing`, `text-transform`, the `font` shorthand, length-form
+      `vertical-align`, `writing-mode` (text-only vertical layout), percentage
+      `border-radius`, `inline-flex`/`inline-grid`, `grid-area`, `aspect-ratio`,
+      auto margins, `outline` + `:focus-visible`/`:active`, `currentColor`,
+      `skewX()`/`skewY()`, `background-size` tiling for `url()` layers and
+      document CSS on SVG children (`fill`/`stroke`/…) are now honoured.
+    - E2E: `tests/e2e/gui-css-coverage.test.ts`.
 
 ## Progress log
 
@@ -522,9 +552,27 @@ engine were Rust.
   `paint_background.cpp` resolves and paints it (radial layers become one
   `PaintGradient`, which `renderer_gradient.cpp` rasterises into a texture),
   `paint_effects.cpp` applies filter colour functions plus nine-tap
-  blur/drop-shadow and emits `text-shadow` runs, and
+  blur/drop-shadow, `paint_shadow.cpp` rasterises Gaussian text/box shadows,
+  `paint_backdrop.cpp` + `renderer_layer.cpp` composite `backdrop-filter`, and
   `paint_clip.cpp`/`renderer_clip.cpp` clip geometry against triangulated
   `clip-path` polygons. E2E: `tests/e2e/gui-effects.test.ts`.
+- **M22** ✅ CSS coverage for the boxing UI. The cascade/declaration parser
+  gained `letter-spacing`, `text-transform`, the `font` shorthand,
+  `vertical-align`, `writing-mode`, percentage `border-radius`, `outline`,
+  `background-size`, `currentColor` and the SVG presentation properties;
+  layout gained inline-level flex/grid, `grid-area`, `aspect-ratio`, auto
+  margins and text-only vertical writing mode; paint gained outline edges,
+  sized/tiled image backgrounds and rotated vertical text; `:focus-visible` is
+  an alias of `:focus` and `:active` is tracked from pointer down/up. E2E:
+  `tests/e2e/gui-css-coverage.test.ts`.
+- **M21** ✅ CSS value/animation completeness. `calc()` is parsed as an
+  unresolved expression tree and resolved by layout/paint; `box-shadow` and
+  blurred `text-shadow` use a separable Gaussian mask cached as a texture;
+  `backdrop-filter` gets an offscreen snapshot pass; `@keyframes` (plus every
+  `animation-*` longhand, delay, iteration, direction and fill mode) shares the
+  property interpolator with transitions, which now also cover opacity, layout
+  lengths, box shadows and `cubic-bezier()`/`steps()`. E2E:
+  `tests/e2e/gui-css-features.test.ts`.
 - **M20** ✅ rendering performance. `@media` is evaluated once per rule per
   restyle, generated content is skipped for sheets without `::before`/`::after`,
   and `:hover`/`:focus` only restyle when the sheet tracks them