xbintsc 0.5.45 → 0.5.52

package/doc/gui/layout.md

@@ -22,10 +22,13 @@ with absolute (viewport-relative) geometry:
   Each line shrinks to the band left free by any floats (`float: left|right`)
   that overlap it, so later lines wrap around them.
   Each text fragment remembers the run it covers, so paint can shape it. Text is
-  measured with the HarfBuzz/FreeType stack (see [Text stack](./rendering.md#text-stack-m4b)).
+  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/media.md

@@ -74,8 +74,9 @@ clip paths are not rendered (see [Known issues](./known-issues.md)).
 
 ## Video & audio (M13)
 
-Media playback is split across two extensions so a GUI program does not pay for
-a decoder it never uses:
+Media playback is split inside the `gui` extension so a GUI program does not pay
+for a decoder it never uses. Decoding is an optional **`media` link feature**,
+not a separate extension:
 
 - **`gui`** (`gui.a`/`gui.lib`) owns the `<video>`/`<audio>` elements, the DOM
   API, the renderer integration and the SDL audio sink, but contains **no
@@ -85,13 +86,18 @@ a decoder it never uses:
 - **`media`** (`media.a`, or `media.lib` with the MSVC ABI on Windows;
   `runtime/ext_media/`) is the optional decoder backend:
   `runtime/ext_media/media.cpp` wraps a statically vendored **FFmpeg** build,
-  and `runtime/ext_media/media_bridge.c` registers it with the engine. Enable it
-  with `--ext media` (or `--ext gui,media`). `media` requires `gui`; the
-  registry rejects the combination in the wrong order.
+  and `runtime/ext_media/media_bridge.c` registers it with the engine. The
+  compiler selects the feature when the program may use it (a `<video>`/`<audio>`
+  element in imported HTML, `createElement("video"/"audio")`, `new Audio()`,
+  `decodeAudioData`, or runtime-built markup) and only then compiles the bridge
+  and links `media.a`. `--feature media` forces it and `--no-feature media`
+  keeps it out; see [Link features](./build.md#link-features).
 
-Without the `media` extension the element still exists and its DOM API is
+Without the feature the element still exists and its DOM API is
 callable, but opening a source fails and fires `error`. The same happens on any
-host where the archive has not been built (run `npm run media`); Windows is no
+host where the archive has not been built (run `npm run media`) — an
+auto-detected feature with no archive produces a build warning and degrades this
+way, while `--feature media` fails the build. Windows is no
 longer special: `media.lib` is FFmpeg compiled with clang-cl for the MSVC ABI,
 so it links against `gui.lib` and plays normally. There is no WebView and no
 platform media framework in the path either way.

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,37 +183,59 @@ 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)
 
-`runtime/ext_gui/text.{h,cpp}` wraps **HarfBuzz** (shaping) and **FreeType**
-(metrics + eventual rasterisation). Both are built statically and linked into
-`gui.a` by `scripts/build-gui.ts`.
-
-- 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.
-- The default candidates prefer a **CJK-capable** face (Microsoft YaHei on
-  Windows, PingFang/STHeiti on macOS, Noto Sans CJK/WenQuanYi on Linux) before
-  the Latin-only ones. Setting `XT_GUI_FONT` to a Latin-only face gives its
-  Latin design instead (at the cost of CJK coverage).
+`runtime/ext_gui/text.{h,cpp}` is the front-end; it dispatches through a small
+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 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 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 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`. This is what
-  makes a character such as `▮`/`▯` (U+25AE/U+25AF, used by the pelican-bike
-  speed bar) visible even when the CJK primary has no geometric shapes. Each
-  shaped glyph carries its face (`ShapedGlyph::font`) so the renderer rasterises
-  it from the right atlas entry; `xt_text_scale` maps a face to the display's
-  scale factor.
-- `xt_text_measure_width` shapes the run with HarfBuzz (so kerning and
-  ligatures are honoured), `xt_text_metrics` returns FreeType's ascent /
+  every glyph instead of dropping the missing ones as `.notdef`. Each shaped
+  glyph carries its face (`ShapedGlyph::font`) so the renderer rasterises it
+  from the right atlas entry; `xt_text_scale` maps a face to the display's scale
+  factor.
+- `xt_text_measure_width` maps each codepoint to a glyph and adds its advance
+  plus the font's `kern` table; `xt_text_metrics` returns stb_truetype's ascent /
   descent / normal line height. When no font file can be found the module falls
   back to a deterministic per-byte approximation, so layout still works.
 - `xt_text_shape_run` returns positioned glyphs and `xt_text_rasterize` renders
@@ -189,6 +245,15 @@ compiler here — keep painting the group with ordinary source-over blending.
 - Layout uses these real metrics for text widths, line breaking and
   `line-height: normal`; `measureText`/`fontMetrics` expose them to tests.
 
+Shape trade-off: the default is a simple shaper, not a full OpenType engine. It
+handles Latin/CJK/Cyrillic/Greek, basic kerning and per-codepoint fallback, but
+it does not run ligatures or complex-script shaping (Arabic/Indic/Thai), and
+stb_truetype only accepts TrueType outlines, not CFF/OTF or variable fonts. The
+choice keeps a DOM-only binary near 3 MiB. The optional **`shaping`** link
+feature installs the HarfBuzz + FreeType backend instead (about 1.2 MiB) and
+restores full OpenType shaping and CFF/OTF/variable-font support; it is selected
+automatically for non-ASCII text and can be forced with `--feature shaping`.
+
 ## Performance (M20)
 
 The engine is a retained-mode pipeline: a DOM mutation restyles the document,
@@ -210,7 +275,17 @@ 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,
+  the same bar width or the same transform every frame therefore costs nothing —
+  before this each assignment rebuilt a text node (an allocation, and one the
+  collector then had to sweep) or re-serialized the inline style, and dirtied
+  the document for a full restyle. `classList` and `removeAttribute` already
+  behaved this way; `setAttribute` still dirties unconditionally.
 - **Frame loop.** The media/canvas tables are reconciled with the DOM only when
   the document changed (or on the first frame) instead of walking the tree every
   frame. A frame presents only when something happened — a mutation, a scroll,

package/doc/gui/runtime.md

@@ -55,6 +55,11 @@ that case with a single 16 ms `xt_set_timeout` tick:
   queued animation-frame callbacks before layout, so a page can stop itself),
 - it re-arms **only while callbacks remain**, so an idle page lets the event
   loop drain and the process exit — the browser-tab lifecycle;
+- it schedules the next tick for *frame start + 16 ms*, not 16 ms after the
+  frame finished: the frame's own duration is not added to the interval, so a
+  10 ms frame runs at a 16 ms period instead of 26 ms, and a page slower than
+  16 ms runs as fast as it can instead of falling a frame's worth of time
+  further behind on every frame;
 - it stands aside while `xt_gui_run_active()` is set (the program called
   `run()`), so the same window is not rendered twice per tick;
 - `XT_GUI_AUTOCLOSE_MS=n` makes the pump quit after `n` milliseconds, which is

package/doc/gui/webgl.md

@@ -48,8 +48,19 @@ reports the type as well.
   `readPixels` flips rows back, and the compositor sees an upright texture.
 - A fixed-function state change (`blendFunc`, `depthFunc`, `cullFace`,
   `colorMask`, …) changes which `SDL_GPUGraphicsPipeline` is needed, so
-  pipelines are created lazily per (program, vertex layout, state) and cached on
-  the program.
+  pipelines are created lazily and cached on the program. The key is the
+  *content* of the draw: the program, the primitive mode, a hash of the vertex
+  layout (attribute locations, formats, offsets, buffer pitches and input rates),
+  the reflected fixed-function state and the attachment formats. It deliberately
+  excludes the context's monotonic version counters (`attribs_version_`,
+  `framebuffer_version_`) and the GPU buffer handles: those advance on every VAO
+  bind, framebuffer switch or buffer re-creation without changing the pipeline,
+  and keying on them re-created every pipeline once per frame in a scene that
+  binds several layouts per frame — three.js does, and measured 248
+  `SDL_CreateGPUGraphicsPipeline` calls per frame while the per-program cache
+  grew without bound. `tests/e2e/gui-webgl-pipeline-cache.test.ts` pins the
+  steady state: two draws with the same layout and different buffers create no
+  pipeline after the first frame.
 
 ## Shaders: GLSL ES to SPIR-V (and on to MSL)
 
@@ -283,9 +294,15 @@ format — Direct3D 12, which would need DXIL — `getContext("webgl")` and
 `getContext("webgl2")` both answer `null`; the 2D canvas and the rest of the page
 still work.
 
-glslang and SPIRV-Cross are fetched and built by `npm run gui` and merged into
-`gui.a` / `gui.lib` (see [Packaging and build](./build.md)); a program that only
-uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
+glslang is fetched and built by `npm run gui` and merged into `gui.a` /
+`gui.lib`; SPIRV-Cross is merged **on macOS only**, because no other SDL_GPU
+backend consumes MSL (see [Packaging and build](./build.md)). Both are reached
+through the optional **`gpu` link feature**: the compiler selects it when the
+program may call `getContext("webgl…")` or use `mix-blend-mode`, and only then
+does the feature bridge pull the translator members out of `gui.a`. The WebGL
+context and DOM bindings are the separate **`webgl` feature**, which requires
+`gpu`; a program that only uses the 2D canvas or the DOM links neither glslang,
+SPIRV-Cross, nor any `webgl_*` member (see [Link features](./build.md#link-features)).
 
 ## Testing
 
@@ -339,6 +356,7 @@ Canvas2D fallback is bundled any more**. Verified with three.js r160 through SDL
 Features outside this engine's subset still cannot be emulated: transform
 feedback and MSAA. Depth textures, float render targets and compressed textures
 are available, and comparative `sampler2DShadow` sampling is translated, so
-three.js shadow maps can use the hardware depth compare on both backends. A
+three.js shadow maps can use the hardware depth compare on both backends (see
+[known issues](./known-issues.md) for an Intel-Mac driver caveat). A
 scene that needs transform feedback or MSAA will not render correctly;
 everything the previous Canvas2D fallback could show now goes through the GPU.