@artooi/ag-ui-web-component 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -7,6 +7,195 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.50.0] — 2026-11-08
+
+### Changed
+
+- **The themes demo sets `--ag-ui-header-btn-hover`.** A new control on its
+  page draws the header buttons' hover square in a colour you pick. The suite
+  now tests that square as a browser without relative colour syntax draws it,
+  mixed from the header text, which only a string check saw before. Demo and
+  tests only, nothing shipped changes. **A host has nothing to do.**
+
+### Fixed
+
+- **A corner panel that was moved goes full-bleed on a phone, and stays there.**
+  Under `collapse-to="auto"`, a panel moved by its header, its launcher or
+  `moveTo` on a wide window kept an inline `--ag-ui-inset` when the window
+  narrowed below the small-viewport breakpoint, which held it 8px off two edges
+  and past the other two. It now fills the screen, with no inline inset, while
+  its launcher stays on the screen for when it is collapsed. A header drag no
+  longer moves a panel that is the screen, as `moveTo` already refused to, and its
+  cursor stops offering one. The
+  place the user put the panel is now kept as they stated it: a window that
+  narrows, by any amount, holds the panel inside it without changing the record,
+  and widening gives that place back, as a reload already did. A gesture made in
+  the narrower window states a new one. **A host has nothing to do.**
+- **A corner panel remembers the corner a resize grip moved.** Under
+  `collapse-to="auto"`, growing a moved panel by a grip on its free edges, which
+  moves its top-left corner while the layout holds the opposite one, was lost on
+  the next reopen or reload: the panel came back at its old top-left, grown away
+  from its launcher. It now comes back as it was drawn, a host's maximum included,
+  and `resetSize()` keeps the panel where the size came off. The top-left stays as the
+  grip left it while the host's own `--ag-ui-width` or `--ag-ui-height` is in force at
+  that moment, and the stored spot stays as it was under `data-launcher-drag="false"`.
+  **A host has nothing to do.**
+- **`read_chat_surface` reports the page's setting for `draggable`, whatever the
+  placement.** A sidebar, embedded, side, page or full panel under `collapse-to="auto"`
+  reported `draggable: false` with `movable: false`, so `move_chat` answered that
+  the page had turned off moving the panel when the placement owned its position,
+  while the same placement under `collapse-to="none"` or `"bar"` reported `true`.
+  `draggable` is now `true` for every placement unless the page sets
+  `data-launcher-drag="false"`, and whether this panel moves stays in `movable`.
+  The refusal names the placement. **A host has nothing to do.**
+- **Every theme's header buttons follow `--ag-ui-header-fg`.** 0.49.0 did this
+  for Quiet alone, so the accent recipe still fell short under the others:
+  white on a `#3d5afe` header read 1.1 to 1.6:1 at rest under Soft and Ledger,
+  and 4.16:1 at rest and 3.75:1 hovered under Classic and code. Once a host sets
+  `--ag-ui-header-fg`, the buttons draw in it at full opacity under every theme
+  and scheme, and the hover square is the opposite of that text at 18%: that
+  pair now reads 5.13:1 at rest and 6.95:1 hovered under all of them. What
+  changes for a host that sets it, by theme. Soft: the glyph was the third ink,
+  the accent's ink hovered, on a square of `--ag-ui-tint-2`. Ledger: the glyph
+  was the third ink, the full ink hovered, on a square of `--ag-ui-hover`.
+  Classic and code: the glyph already was the header text, but at 0.85 opacity,
+  and the square was 18% white, so under white text it now darkens where it
+  lightened. Browsers without relative colour syntax (Firefox 120 to 127,
+  Safari 17.5 and 17.6) mix the square from the text itself, as under Quiet, at
+  3.75:1 hovered for that pair.
+  **`--ag-ui-header-btn-hover`, inert until now under Soft, Ledger, Classic and
+  code, works under them**, as it does under Quiet: drawn exactly as given,
+  whether or not the header text is set. A host that set it for Quiet and also
+  wears one of these themes will now see it. With neither token set, every
+  theme's header buttons are exactly as they were, whatever the header colour
+  or `--ag-ui-hover`. **No opt-in is needed.** A page's own
+  `::part(header-button)` rules still win: a host that wrote one to get here may
+  delete it, and should at least delete a `:hover` background of 18% of the text,
+  which keeps the glyph at 3.75:1 on a mid-tone accent. A host that sets neither
+  token, the Django admin among them, sees no change.
+- **A corner panel a host's own size makes the window stands at 0,0.** A host that
+  fills a wide window with `--ag-ui-width` and `--ag-ui-height` found a panel the
+  user had moved standing at 8,8 after a window resize, 8px past the right and
+  bottom edges. It now exactly fills the window, from the start of whatever the
+  viewport inset tokens reserve, as a
+  phone's full-bleed panel does, and comes back to where the user put it when the
+  host's size drops. A host's own `--ag-ui-inset` rule that already stands the box
+  on the screen is left alone. **A host has nothing to do.**
+- **A panel placed only by a resize grip goes full-bleed on a phone.** A grip on
+  an edge the layout holds moves an unmoved corner panel without storing a spot,
+  and that inline inset stayed on when the window narrowed, which held the panel
+  off two edges and past the other two. It now fills the screen with no inline
+  inset, and widening gives the place back. An inset the host wrote inline stays
+  where the host wrote it. An unmoved panel a host's own size makes the window
+  stands at 0,0 as well. **A host has nothing to do.**
+- **`data-launcher-drag="false"` on a moved panel hands it to the host's CSS.**
+  Turned on after the user had moved the panel, the attribute left an inline
+  inset behind for good, which put the panel off the screen on a phone. Nothing
+  moves when it goes on. The next window resize or reopen rests the panel where
+  the host's CSS puts it, as a reload under the attribute always did, and on a
+  phone that is full-bleed. The stored spot stays, and comes back at the first
+  restore after the attribute comes off. **A host has nothing to do.**
+- **Undoing a move after the surface changed leaves everything in agreement.** A
+  move undone once the panel had gone from a corner to a sidebar, a side panel, a
+  page or a dock wrote the corner's inset back onto the new surface, which pinned
+  a sidebar or a page off the screen and took a docked panel off its dock, and
+  left the stored spot on the move the reader had just undone. Going the other way
+  left a docked panel's stored spot on the move too. The undo now puts both
+  records back, in memory and in storage, and leaves the new surface standing where
+  its own layout puts it; the spot comes back with the surface it belongs to.
+  **A host has nothing to do.**
+- **A moved panel answers a host's size when the size changes.** A change to
+  `--ag-ui-width` or `--ag-ui-height` fires no event, so a panel the user had moved
+  stayed as the last restore left it until the next window resize or reopen. Reopened
+  under a host's size that then dropped, it stood short of its spot, at 716,232 for a
+  spot of 376,96, with the stored spot still right; sized up with no reopen, it could
+  grow past the top of the window. It now goes back to its spot as the size drops, and
+  under a bigger size it stands where a reopen already put it, held on the screen from
+  that spot, rather than growing away from the corner the layout held. A window-filling
+  size stands it at 0,0 at once, with no resize needed. **A host has nothing to do.**
+- **A moved panel answers a viewport inset token when the token changes.** A page
+  that publishes `--ag-ui-viewport-inset-top` from its own `ResizeObserver`, as the
+  README recommends, does so after the window's resize event, so the restore that event
+  starts read the bar at its old height. Widening a window past the width where the bar
+  shrinks left the panel 35px below its spot on the playground, top 224 for a spot of
+  189, and narrowing left it under a bar that had grown. It now settles from the token
+  as it stands, a frame later, on any of the four viewport inset tokens and however
+  late the page writes them. **A host has nothing to do.**
+- **The header's cursor no longer offers a drag that cannot happen.** A panel that
+  had become the screen on a narrow window with a mouse, or a docked panel under
+  `collapse-to="bar"` or `"none"` that a host's own size had made the window, showed
+  `cursor: move` although its header could not move it. The cursor is now `auto` there,
+  and stays `move` everywhere the drag is allowed. **A host has nothing to do.**
+
+## [0.49.0] — 2026-11-07
+
+### Added
+
+- **`--ag-ui-header-btn-hover`, the header buttons' hover square.** Drawn
+  exactly as given under Quiet and a host's own theme word, whether or not
+  `--ag-ui-header-fg` is set. Unset, the square follows the header text as
+  below, or is the panel's hover shade when that is unset too. A host that
+  prefers the lightening square of its old `::part(header-button):hover`
+  rule sets this token to that colour instead of keeping the rule.
+
+### Changed
+
+- **A docked panel moves and remembers where it was put.** Under
+  `collapse-to="bar"`, and under `collapse-to="none"` with or without an
+  `anchor`, a corner panel on a wide viewport now moves by its header and by
+  `moveTo`, like the default corner panel. Minimising and reopening, and a
+  reload, bring it back where it was dragged, and a panel never dragged still
+  opens at the dock. A dragged panel stays inside the viewport and above the
+  bar, or above the anchor's top under `none` (the anchor gap no longer
+  applies once dragged), and a stored spot is held there if the window or the
+  bar changed since. Once dragged off, every resize edge follows its grip.
+  `resetSize()` returns a dragged docked panel to the dock and forgets the
+  stored spot; under `auto` it still drops only the size. The spot is stored
+  apart from the corner panel's, so a spot dragged under `auto` never lands on
+  a docked panel. On a phone the panel stays full-bleed and does not move.
+  `describeSurface()` and `read_chat_surface` report `movable: true` and
+  `draggable: true` for it on a wide viewport, and `move_chat` no longer
+  refuses with "the panel is docked". `side` and `full` under `bar`, and
+  `sidebar` and `embedded` under `none`, still own their position; they now
+  report `draggable: true` where they reported `false`, so a refused move
+  there names the placement rather than the dock or the page. **A host has
+  nothing to do**: every host using `bar` or `none` gets the movable panel on
+  upgrade. A host that wants the 0.48.0 fixed dock sets
+  `data-launcher-drag="false"`, which turns the header drag and `moveTo` off
+  here as it does on a corner panel.
+
+### Fixed
+
+- **Quiet's header buttons follow `--ag-ui-header-fg`.** The accent recipe
+  (0.45.0) put the accent on the header, but Quiet drew the history, new-chat,
+  theme and collapse buttons in its third ink at 0.85 opacity, about 1.2:1 on
+  a `#3d5afe` header, and hovered them on the panel's near-white or near-black
+  shade. Once a host sets `--ag-ui-header-fg`, the buttons draw in it at full
+  opacity, and the hover square is the opposite of that text at 18% (darker
+  under white text, lighter under dark), so a hovered button reads at least
+  what the host's header pair reads: white on `#3d5afe` is 5.1:1 at rest and
+  about 7:1 hovered. Browsers without relative colour syntax (Firefox 120
+  to 127, Safari 17.5 and 17.6) mix the square from the text itself instead.
+  This applies under Quiet and under a host's own theme word, which starts
+  from Quiet, in every scheme; Soft, Ledger, Classic and code are unchanged.
+  Unset, nothing changes. **No opt-in is needed.** A host that
+  wrote `ag-ui-chat::part(header-button) { color: var(--ag-ui-header-fg) }`
+  and the `:hover` background beside it may delete both: kept, the colour
+  rule is harmless, but the page's 18% tint of the text still beats the new
+  square, and on a mid-tone accent it takes the hovered glyph under 4.5:1
+  (3.75:1 on `#3d5afe`). Delete the hover background at least; to keep a
+  lightening square, set `--ag-ui-header-btn-hover` to it. With the header
+  text set, the header buttons no longer read `--ag-ui-hover`; the rest of
+  the panel still does. A host that sets neither `--ag-ui-header-fg`
+  nor `--ag-ui-tool-fg`, the Django admin among them, sees no change.
+- **`--ag-ui-tool-fg` reaches the calls in a step group.** Under the grouped
+  default (0.46.0) every call in a group was drawn in the second ink whatever
+  the token said, so the recipe's tool colour reached nothing. A set
+  `--ag-ui-tool-fg` now colours grouped calls under every theme; unset, they
+  keep the second ink, Classic included. **No opt-in is needed**, but a host
+  that set the token and kept the grouped default sees its calls in that
+  colour from this release.
+
 ## [0.48.0] — 2026-11-07
 
 ### Added
@@ -4979,7 +5168,9 @@ hosts that both arrange the page the way it expects.
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.48.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.50.0...HEAD
+[0.50.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.49.0...v0.50.0
+[0.49.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.48.0...v0.49.0
 [0.48.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.47.0...v0.48.0
 [0.47.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.46.0...v0.47.0
 [0.46.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.45.0...v0.46.0

package/README.md

@@ -208,7 +208,7 @@ another origin, add `credentials="include"` too; see
 | `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
 | `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
 | `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded`). Persisted per tab. `placement="page"` has no collapsed state and ignores it. |
-| `collapse-to` | — | What the panel collapses to: `auto` (the default; absent or any other value reads the same) leaves every placement as it is, `bar` draws a strip along the bottom edge in place of the round launcher, `none` hides the collapsed widget so the host's own control brings it back. Live. See [Collapsing to a bottom bar](#collapsing-to-a-bottom-bar). |
+| `collapse-to` | — | What the panel collapses to: `auto` (the default; absent or any other value reads the same) leaves every placement as it is, `bar` draws a strip along the bottom edge in place of the round launcher, `none` hides the collapsed widget so the host's own control brings it back. Under either, a corner panel still moves by its header and `moveTo` on a wide viewport, and remembers where it was dragged. Live. See [Collapsing to a bottom bar](#collapsing-to-a-bottom-bar). |
 | `anchor` | `anchor` | Under `collapse-to="none"`, a selector for the host's element the panel rises from, right-aligned to it. The `anchor` property takes an element instead and wins over the attribute. Live. |
 | `data-dragging` | — | **Written by the element, not by you.** Stamped on whichever handle a gesture is currently using, so the styles can react and so the element knows not to re-place the widget under a drag in progress. Cleared on `pointerup` and on `pointercancel`. |
 | `data-expand-corner` | — | **Written by the element, not by you.** It stamps the corner a dragged or agent-moved panel opens from, so the collapse animation starts where the panel actually is. Listed because the element reads its own stamp back; setting it yourself is overwritten on the next move. |
@@ -1183,10 +1183,13 @@ matching JS API:
 - `moveTo(corner)` — send the panel to `top-left` / `top-right` / `bottom-left` / `bottom-right`,
   returning whether it went. It takes the axes the same way a user drag does, so the launcher
   travels with it and switching placement hands them back. Returns `false` rather than pretending
-  when the placement owns its position or the panel fills the screen.
+  when the placement owns its position or the panel fills the screen. Under `collapse-to="bar"`
+  or `"none"` it moves the panel within the room above the bar or the anchor.
 - `resetSize()` — drop a size the user dragged, and its stored copy, so the placement's own
   size and your `--ag-ui-width` / `--ag-ui-height` apply again. For a host that enters a sized
   state of its own (an expanded mode): a user's drag outranks host tokens, so call this first.
+  Under `collapse-to="bar"` or `"none"` it also returns a panel the user dragged off its dock to
+  the dock and forgets the stored spot; a corner panel under `auto` keeps its dragged position.
 - `setCollapsed(collapsed)` / `toggleCollapsed()` — collapse or expand the widget. The state is
   reflected as the boolean `collapsed` attribute/property and persisted per-tab in
   `sessionStorage`, so it survives a reload.
@@ -1485,14 +1488,35 @@ body {
 your toolbar: its max height is the viewport less the bar's height (or, under `none`, the
 distance to the anchor's top) and one gutter, and its bottom sits on the bar or the anchor.
 
-**Docked means not moved.** A docked panel cannot be dragged by its header or launcher, and
-`moveTo` refuses, because a position the user chose would take it away from the bar or the
-anchor. Resizing still works on wide viewports: the edges standing on the bar or the anchor
-stay put and the free ones follow the grip, and `resetSize()` still drops the dragged size.
+**Docked, and still movable.** On a wide viewport a docked corner panel (the corner placements
+under `bar`, or under `none` with or without an anchor) moves by its header, and `moveTo` moves
+it, as it would the corner panel it is; `describeSurface()` reports `movable: true`. There is no
+launcher to drag: the bar and your own control stay where they are.
+
+- **Above the dock.** A dragged panel stays inside the viewport and above the bar's top edge, so it
+  never covers the bar it minimises to. Under `none` with an anchor it stays above the anchor's
+  top edge the same way, because the anchor is your own way back and has to stay in view;
+  `--ag-ui-anchor-gap` no longer applies once the panel is dragged, and the screen-edge margin
+  (8px) does. Under `none` with no anchor only the viewport holds it, as for a corner panel.
+- **Remembered like a corner panel.** Minimising and reopening brings it back where it was
+  dragged, and so does a reload. The spot is kept apart from the one a corner panel stores under
+  `auto`, so switching `collapse-to` never puts one surface's spot on the other. A spot that no
+  longer fits, because the window shrank or the bar grew, is held inside the room that is left
+  and comes back whole when there is room again.
+- **Resizing.** A panel standing on its dock keeps the edges on the bar or the anchor still and the
+  free ones follow the grip. Once dragged off, every edge follows its grip, as on a corner panel.
+- **Back to the dock.** `resetSize()` drops the dragged size and returns the panel to its dock,
+  forgetting the stored spot, so a reload opens it there too.
+- **Keeping it fixed.** `data-launcher-drag="false"` turns the header drag and `moveTo` off here as
+  everywhere else, and the panel stays on its dock.
+
+Placements that own their position (`side` and `full` under `bar`, `sidebar` and `embedded`
+under `none`) do not move, as without `collapse-to`.
 
 **Phones.** At 600px or less the open panel stays full-bleed, over the bar, and the header's
 minimise control is the way back; the bar shows only while collapsed, so no second strip sits
-at the bottom edge while the keyboard is up.
+at the bottom edge while the keyboard is up. The panel does not move there, and a spot dragged on
+a wide viewport does not apply: it comes back when the window is wide again.
 
 The bar is styled through the parts `bar` (the strip's wrapper, holding the launcher and the
 history button) and `bar-history`, and the launcher's own parts (`launcher`, `rail-label`,
@@ -3302,6 +3326,45 @@ fallback white (2.5:1), as it always was. What they miss is the correction for a
 mid-tone brand accent can fall under 4.5:1 there, under any theme. If you support those browsers
 and set a mid-tone accent, set `--ag-ui-on-accent` yourself. There is no script path.
 
+#### Keeping a brand accent on the header
+
+Quiet draws the header, the launcher and the tool names in the panel's own colours, so a host that
+sets only `--ag-ui-accent` gets a neutral header. To put the accent back without leaving Quiet, set
+the surfaces to the accent and the text on them to a colour that reads on it. The same recipe holds
+under every other theme:
+
+```css
+ag-ui-chat {
+  --ag-ui-header-bg: #3d5afe;
+  --ag-ui-header-fg: #ffffff;
+  --ag-ui-launcher-bg: #3d5afe;
+  --ag-ui-launcher-fg: #ffffff;
+  --ag-ui-tool-fg: #3d5afe;
+}
+```
+
+- **The header buttons follow `--ag-ui-header-fg`, under every theme.** Unset, each theme draws
+  them its own way at 0.85 opacity: Quiet, Soft and Ledger in their third ink, Classic and Code in
+  the header text, each on its own hover square. Once you set the header text they draw in it at
+  full opacity, and the hover square is the opposite of that text at about a fifth (a darker square
+  under white text, a lighter one under dark text), so a hovered button reads at least what your
+  header pair reads. A theme word of your own starts from Quiet, so it holds there too. No
+  `::part(header-button)` rule is needed. The opposite is computed with relative
+  colour syntax; the browsers without it (see the fallback above) mix the square from the text
+  itself, which on a mid-tone header can take the hovered glyph under your pair (white on
+  `#3d5afe`: 3.75:1).
+- **`--ag-ui-header-btn-hover` sets the hover square outright** under every theme, whether or not
+  the header text is set, and is drawn exactly as given. For a square that lightens under white
+  text instead, at the cost of contrast on a mid-tone header:
+
+  ```css
+  ag-ui-chat { --ag-ui-header-btn-hover: color-mix(in srgb, #ffffff 18%, transparent); }
+  ```
+- **`--ag-ui-tool-fg` colours every tool call**, in a step group as well as in the card displays.
+  Unset, a grouped call is drawn in the second ink (`--ag-ui-ink-2`) under every theme.
+- Pick the pair yourself: `--ag-ui-header-fg` is not derived from the header colour the way
+  `--ag-ui-on-accent` is from the accent.
+
 #### Overriding a theme, lightest layer first
 
 Four layers, each documented and each lighter than the next. Reach for the first one that does